pi-agent-browser-native 0.8.2 → 0.9.0

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

@@ -1,27 +1,29 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 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 { PROJECT_RULE_PROMPT, ADVANCED_TOOL_PROMPT_GUIDELINES, QUICK_START_GUIDELINES, SHARED_BROWSER_PLAYBOOK_GUIDELINES, WEB_SEARCH_TOOL_PROMPT_GUIDELINES, WRAPPER_TAB_RECOVERY_BEHAVIOR, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
 import { SessionPageState } from "./lib/session-page-state.js";
-import { appendBrowserTransition, getBrowserResultMessage } from "./lib/browser-transcript.js";
+import { appendBrowserTransition, applyArtifactChanges, artifactChanges, browserStateEffects, getBrowserRecord, getBrowserResultMessage, pageChange, snapshotDefinition } from "./lib/browser-transcript.js";
+import { appendBrowserRecord, captureBrowserBranch, hasPublishedBrowserJournal, readBrowserEntries, requirePublishedBrowserJournal } from "./lib/browser-journal.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 { ManagedSessionRestoreState } from "./lib/managed-session-restore.js";
 import { isRecord } from "./lib/parsing.js";
-import { getAgentBrowserProcessTimeoutMs, runAgentBrowserProcess } from "./lib/process.js";
+import { getAgentBrowserProcessTimeoutMs, resolveAgentBrowserSocketDir, 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 { getBrowserCwdError, resolveExecutionCwd } 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 { buildPromptPolicy, getLatestUserMessage, getMessageText } 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";
@@ -34,7 +36,7 @@ import { buildValidationFailureResult, resolveAgentBrowserInput } from "./lib/or
 import { applyAgentBrowserOutputPath, canWriteAgentBrowserOutput, normalizeRequestedOutputPath } from "./lib/orchestration/output-file.js";
 import { appendScriptSessionLease, createBrowserCodeOutput, getScriptSessionLeasesFromBranch } from "./lib/orchestration/script-mode.js";
 import { resolveBrowserExecutionIdentity, withBrowserExecutionLock, withBrowserExecutionLocks } from "./lib/managed-session-policy-lock.js";
-import { AGENT_BROWSER_DISCOVERY_GROUP, registerAgentBrowserToolSurface } from "./lib/tool-surface.js";
+import { AGENT_BROWSER_INSTRUCTION_GROUP, AGENT_BROWSER_TOOL_INVENTORY, 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";
@@ -42,7 +44,7 @@ import { appendRecordingReservationTransition, applyRecordingArtifactsToReservat
 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";
+import { AgentBrowserResultComponent, formatAgentBrowserRenderCall, } 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));
@@ -174,103 +176,60 @@ function getResultFileArtifacts(result) {
     const details = isRecord(result.details) ? result.details : undefined;
     return Array.isArray(details?.artifacts) ? details.artifacts.filter(isResultFileArtifact) : [];
 }
-function restoreArtifactManifestFromBranch(branch) {
-    let restoredManifest;
-    for (const entry of branch) {
-        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)) {
-            restoredManifest = details.artifactManifest;
+function invocationArtifactManifest(current, previous, details, retainedReceipts) {
+    if (!current)
+        return undefined;
+    const paths = new Set();
+    for (const row of [details, ...(Array.isArray(details.batchSteps) ? details.batchSteps.filter(isRecord) : [])]) {
+        if (typeof row.fullOutputPath === "string")
+            paths.add(row.fullOutputPath);
+        for (const path of Array.isArray(row.fullOutputPaths) ? row.fullOutputPaths : [])
+            if (typeof path === "string")
+                paths.add(path);
+        for (const artifact of Array.isArray(row.artifacts) ? row.artifacts.filter(isRecord) : []) {
+            if (typeof artifact.absolutePath === "string")
+                paths.add(artifact.absolutePath);
+            if (typeof artifact.path === "string")
+                paths.add(artifact.path);
         }
     }
+    const changed = new Set((artifactChanges(previous, current)?.upserts ?? []).map(getSessionArtifactManifestEntryKey));
+    for (const row of retainedReceipts?.entries ?? [])
+        changed.add(getSessionArtifactManifestEntryKey(row));
+    const entries = current.entries.filter(row => changed.has(getSessionArtifactManifestEntryKey(row)) || paths.has(row.path) || (row.absolutePath !== undefined && paths.has(row.absolutePath)));
+    return entries.length ? redactSensitiveValue({
+        ...current, entries, liveCount: entries.filter(row => row.retentionState === "live").length,
+        evictedCount: entries.filter(row => row.retentionState === "evicted").length,
+    }) : undefined;
+}
+function restoreArtifactManifestFromBranch(branch) {
+    let restoredManifest;
+    for (const entry of branch)
+        restoredManifest = applyArtifactChanges(restoredManifest, getBrowserRecord(entry)?.event.artifacts);
     return restoredManifest;
 }
+function browserPageChanges(working, prior, touched) {
+    const pages = working.views();
+    const keys = new Set(touched);
+    for (const [key, page] of pages) {
+        const before = prior.get(key);
+        if (JSON.stringify(pageChange(key, page, before?.refSnapshot?.snapshotId)) !== JSON.stringify(pageChange(key, before ?? {}, before?.refSnapshot?.snapshotId)))
+            keys.add(key);
+    }
+    for (const key of prior.keys())
+        if (!pages.has(key))
+            keys.add(key);
+    const changes = [...keys].map(key => pages.has(key) ? pageChange(key, pages.get(key), prior.get(key)?.refSnapshot?.snapshotId) : { key, refs: { kind: "invalidate" }, clear: true });
+    const capture = changes.find(page => page.refs.kind === "replace");
+    const snapshot = capture ? pages.get(capture.key)?.refSnapshot : undefined;
+    return { pages: changes, ...(snapshot ? { snapshot: snapshotDefinition(snapshot) } : {}) };
+}
 function getRecognizedCompatibilityWorkaround(value) {
     const workaround = isRecord(value) ? value : undefined;
     return (workaround?.id === "chatgpt-headless-user-agent" || workaround?.id === "cloudflare-headless-user-agent") && typeof workaround.reason === "string"
         ? { id: workaround.id, reason: workaround.reason }
         : undefined;
 }
-function restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, sessionName, namespace) {
-    let restored;
-    const targetKey = getSessionContextKey(sessionName, namespace);
-    for (const entry of branch) {
-        const message = getBrowserResultMessage(entry);
-        if (!message)
-            continue;
-        const details = isRecord(message.details) ? message.details : undefined;
-        if (!details)
-            continue;
-        if (getSessionContextKey(typeof details.sessionName === "string" ? details.sessionName : undefined, typeof details.namespace === "string" ? details.namespace : undefined) !== targetKey)
-            continue;
-        const recognizedWorkaround = getRecognizedCompatibilityWorkaround(details.compatibilityWorkaround);
-        const succeeded = getSuccessfulToolResult(details, message);
-        const outcome = getManagedSessionOutcome(details);
-        const activeAfterFailure = recognizedWorkaround
-            && outcome?.activeAfter === true
-            && typeof outcome.currentSessionName === "string"
-            && getSessionContextKey(outcome.currentSessionName, typeof outcome.currentSessionNamespace === "string" ? outcome.currentSessionNamespace : undefined) === targetKey
-            && (outcome.status === "created" || outcome.status === "replaced" || outcome.status === "unchanged");
-        if (!succeeded && !activeAfterFailure)
-            continue;
-        if (recognizedWorkaround) {
-            restored = recognizedWorkaround;
-        }
-        else if (!canUseHeadlessCompatibilityUserAgent(getToolResultArgs(details))) {
-            restored = undefined;
-        }
-    }
-    return restored;
-}
-function restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, sessionName, namespace) {
-    let restored = false;
-    const targetKey = getSessionContextKey(sessionName, namespace);
-    for (const entry of branch) {
-        const message = getBrowserResultMessage(entry);
-        if (!message)
-            continue;
-        const details = isRecord(message.details) ? message.details : undefined;
-        if (!details)
-            continue;
-        if (getSessionContextKey(typeof details.sessionName === "string" ? details.sessionName : undefined, typeof details.namespace === "string" ? details.namespace : undefined) !== targetKey)
-            continue;
-        const outcome = getManagedSessionOutcome(details);
-        const activeAfterFailure = outcome?.activeAfter === true
-            && typeof outcome.currentSessionName === "string"
-            && getSessionContextKey(outcome.currentSessionName, typeof outcome.currentSessionNamespace === "string" ? outcome.currentSessionNamespace : undefined) === targetKey;
-        if ((getSuccessfulToolResult(details, message) || activeAfterFailure) && typeof details.managedSessionHeadedAutosaveDisabled === "boolean") {
-            restored = details.managedSessionHeadedAutosaveDisabled;
-        }
-    }
-    return restored;
-}
-function restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, sessionName, namespace) {
-    let restored;
-    const targetKey = getSessionContextKey(sessionName, namespace);
-    for (const entry of branch) {
-        const message = getBrowserResultMessage(entry);
-        if (!message)
-            continue;
-        const details = isRecord(message.details) ? message.details : undefined;
-        if (!details)
-            continue;
-        if (getSessionContextKey(typeof details.sessionName === "string" ? details.sessionName : undefined, typeof details.namespace === "string" ? details.namespace : undefined) !== targetKey)
-            continue;
-        const outcome = getManagedSessionOutcome(details);
-        const activeAfterFailure = outcome?.activeAfter === true
-            && typeof outcome.currentSessionName === "string"
-            && getSessionContextKey(outcome.currentSessionName, typeof outcome.currentSessionNamespace === "string" ? outcome.currentSessionNamespace : undefined) === targetKey;
-        if (!getSuccessfulToolResult(details, message) && !activeAfterFailure)
-            continue;
-        if (typeof details.managedSessionHeadedAutosaveInterval === "string")
-            restored = details.managedSessionHeadedAutosaveInterval;
-        else if (details.managedSessionHeadedAutosaveDisabled === true)
-            restored = "0";
-    }
-    return restored;
-}
 function getToolResultArgs(details) {
     if (Array.isArray(details.args) && details.args.every((arg) => typeof arg === "string"))
         return details.args;
@@ -346,7 +305,7 @@ function trackOwnedManagedSession(sessions, sessionName, cwd, options = {}) {
         : existing?.compatibilityWorkaround;
     const headedManagedAutosaveDisabled = options.headedManagedAutosaveDisabled ?? existing?.headedManagedAutosaveDisabled;
     const headedManagedAutosaveInterval = options.headedManagedAutosaveInterval ?? existing?.headedManagedAutosaveInterval;
-    sessions.set(key, { branchOwned, compatibilityWorkaround, cwd, headedManagedAutosaveDisabled, headedManagedAutosaveInterval, namespace: options.namespace, sessionName });
+    sessions.set(key, { branchOwned, compatibilityWorkaround, cwd, headedManagedAutosaveDisabled, headedManagedAutosaveInterval, namespace: options.namespace, sessionName, socketDir: options.socketDir ?? existing?.socketDir });
 }
 function untrackOwnedManagedSession(sessions, sessionName, namespace) {
     if (!sessionName)
@@ -382,6 +341,7 @@ function syncOwnedManagedSessionsFromResult(sessions, result, cwd) {
             headedManagedAutosaveDisabled: details?.managedSessionHeadedAutosaveDisabled === true,
             headedManagedAutosaveInterval: typeof details?.managedSessionHeadedAutosaveInterval === "string" ? details.managedSessionHeadedAutosaveInterval : undefined,
             namespace,
+            socketDir: typeof details?.managedSessionSocketDir === "string" ? details.managedSessionSocketDir : undefined,
         });
     }
     if (succeeded && status === "closed") {
@@ -394,6 +354,8 @@ function getTouchedElectronLaunchIds(sessionName, records, namespace) {
 }
 function mergeActiveElectronLaunchRecords(target, source, options = {}) {
     for (const record of getActiveElectronRecords(source)) {
+        if (options.ownerSessionId !== undefined && record.ownerSessionId !== options.ownerSessionId)
+            continue;
         const alreadyRuntimeOwned = target.has(record.launchId) && options.branchOwnedLaunchIds?.has(record.launchId) === false;
         target.set(record.launchId, record);
         if (options.branchOwnedLaunchIds) {
@@ -450,8 +412,10 @@ function shouldSerializeElectronHostInput(compiledElectron) {
     return compiledElectron?.action === "status" || compiledElectron?.action === "probe" || compiledElectron?.action === "cleanup";
 }
 function getElectronHostLaunchRecordsForInput(options) {
+    if (options.compiledElectron?.action === "cleanup") {
+        return new Map([...mergeElectronLaunchRecordMaps(options.branchRecords, options.ownedRecords)].filter(([, record]) => record.ownerSessionId === options.ownerSessionId));
+    }
     if (options.compiledElectron?.action === "status" ||
-        options.compiledElectron?.action === "cleanup" ||
         (options.compiledElectron?.action === "probe" && options.compiledElectron.launchId)) {
         return mergeElectronLaunchRecordMaps(options.branchRecords, options.ownedRecords);
     }
@@ -536,6 +500,7 @@ function collectBranchManagedResourceEvents(branch) {
         managedSessionActiveIdentities: new Map(),
         managedSessionActiveRanks: new Map(),
         managedSessionCloseRanks: new Map(),
+        managedSessionLaunchState: new Map(),
     };
     let eventRank = 0;
     for (const entry of branch) {
@@ -557,6 +522,32 @@ function collectBranchManagedResourceEvents(branch) {
         const batchCloseLifecycle = getSuccessfulBatchCloseLifecycle(details.batchSteps);
         const closeAllApplied = detailsReportCloseAllApplied(details, succeeded);
         const outcome = getManagedSessionOutcome(details);
+        if (sessionName) {
+            const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
+            const launch = events.managedSessionLaunchState.get(key) ?? { compatibilityWorkaround: undefined, headedManagedAutosaveDisabled: false };
+            if (typeof details.managedSessionCwd === "string" && isAbsolute(details.managedSessionCwd))
+                launch.cwd = details.managedSessionCwd;
+            if (typeof details.managedSessionSocketDir === "string")
+                launch.socketDir = details.managedSessionSocketDir;
+            const retainedAfterFailure = outcome?.activeAfter === true && typeof outcome.currentSessionName === "string"
+                && getSessionContextKey(outcome.currentSessionName, typeof outcome.currentSessionNamespace === "string" ? outcome.currentSessionNamespace : undefined) === key;
+            const workaround = getRecognizedCompatibilityWorkaround(details.compatibilityWorkaround);
+            if (succeeded || workaround && retainedAfterFailure && ["created", "replaced", "unchanged"].includes(String(outcome?.status))) {
+                if (workaround)
+                    launch.compatibilityWorkaround = workaround;
+                else if (!canUseHeadlessCompatibilityUserAgent(getToolResultArgs(details)))
+                    launch.compatibilityWorkaround = undefined;
+            }
+            if (succeeded || retainedAfterFailure) {
+                if (typeof details.managedSessionHeadedAutosaveDisabled === "boolean")
+                    launch.headedManagedAutosaveDisabled = details.managedSessionHeadedAutosaveDisabled;
+                if (typeof details.managedSessionHeadedAutosaveInterval === "string")
+                    launch.headedManagedAutosaveInterval = details.managedSessionHeadedAutosaveInterval;
+                else if (details.managedSessionHeadedAutosaveDisabled === true)
+                    launch.headedManagedAutosaveInterval = "0";
+            }
+            events.managedSessionLaunchState.set(key, launch);
+        }
         const outcomeSucceeded = outcome?.succeeded === true;
         const outcomeStatus = typeof outcome?.status === "string" ? outcome.status : undefined;
         const outcomeCurrentSessionName = typeof outcome?.currentSessionName === "string" ? outcome.currentSessionName : undefined;
@@ -631,7 +622,7 @@ async function closeOwnedManagedSessionsExcept(sessions, restoreState, keepSessi
     for (const [key, owner] of [...sessions]) {
         if (key === keepKey)
             continue;
-        const error = await closeManagedSession({ cwd: owner.cwd, headedManagedAutosaveInterval: owner.headedManagedAutosaveInterval, namespace: owner.namespace, preserveAttachedBrowserSession: attachedSessionKeys.has(key), restoreState, sessionName: owner.sessionName, timeoutMs });
+        const error = await closeManagedSession({ cwd: owner.cwd, headedManagedAutosaveInterval: owner.headedManagedAutosaveInterval, namespace: owner.namespace, preserveAttachedBrowserSession: attachedSessionKeys.has(key), restoreState, sessionName: owner.sessionName, socketDir: owner.socketDir, timeoutMs });
         if (!error) {
             sessions.delete(key);
             onClosed?.(owner);
@@ -804,7 +795,7 @@ function hasArgvFlag(argv, longFlag, shortFlag) {
 function shouldIncludeProjectConfig(ctx, argv = process.argv) {
     if (hasArgvFlag(argv, "--no-approve", "-na"))
         return false;
-    return ctx?.isProjectTrusted?.() ?? true;
+    return ctx.isProjectTrusted();
 }
 export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
     const ephemeralSessionSeed = createEphemeralSessionSeed();
@@ -812,15 +803,23 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         cwd: process.cwd(),
         includeProjectConfig: false,
     });
-    const webSearchToolAvailable = canRegisterWebSearchTool(agentBrowserConfig);
-    const toolPromptGuidelines = buildToolPromptGuidelines({
-        browserDefaultProfile: agentBrowserConfig.trustedBrowserDefaultProfile,
-        browserExecutablePath: agentBrowserConfig.trustedBrowserExecutablePath,
-        includeWebSearch: webSearchToolAvailable,
-        docs: getInstalledDocsPaths(),
-    });
     const implicitSessionIdleTimeoutMs = String(getImplicitSessionIdleTimeoutMs());
     const implicitSessionCloseTimeoutMs = getImplicitSessionCloseTimeoutMs();
+    let promptState;
+    const restorePromptState = (ctx) => {
+        return promptState = { sessionId: ctx.sessionManager.getSessionId(), message: getLatestUserMessage(ctx.sessionManager) };
+    };
+    const getPromptPolicy = (ctx) => {
+        const state = promptState?.sessionId === ctx.sessionManager.getSessionId() ? promptState : restorePromptState(ctx);
+        // Native message_end precedes later transforms/persistence; retain the message
+        // reference so replacement user text cannot leave policy on the earlier text.
+        const text = getMessageText(state.message?.content);
+        if (!state.policy || state.text !== text) {
+            state.text = text;
+            state.policy = buildPromptPolicy(text);
+        }
+        return state.policy;
+    };
     let webSearchToolRegistered = false;
     let managedSessionActive = false;
     let managedSessionBaseName = createImplicitSessionName(undefined, process.cwd(), ephemeralSessionSeed);
@@ -832,6 +831,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
     let managedSessionNamespace;
     let freshSessionOrdinal = 0;
     let sessionPageState = new SessionPageState();
+    let browserReplayError;
     let traceOwners = new Map();
     let artifactManifest;
     let activeRecordingReservations = new Map();
@@ -841,6 +841,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
     let networkRoutesBySession = new Map();
     let electronLaunchRecords = new Map();
     let ownedElectronLaunchRecords = new Map();
+    let browserOwnerSessionId = "";
     let branchOwnedElectronLaunchIds = new Set();
     let electronChildProcesses = new Map();
     const managedSessionRestoreState = new ManagedSessionRestoreState();
@@ -1054,13 +1055,13 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         }));
         if (closeError) {
             try {
-                appendScriptSessionLease(pi, sessionName, "failed");
+                appendScriptSessionLease(pi, sessionName, "failed", browserOwnerSessionId);
             }
             catch { }
             return redactSensitiveText(closeError);
         }
         try {
-            appendScriptSessionLease(pi, sessionName, "closed");
+            appendScriptSessionLease(pi, sessionName, "closed", browserOwnerSessionId);
         }
         catch {
             managedSessionRestoreState.disable(sessionName);
@@ -1072,11 +1073,11 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         clearSessionScopedBrowserState(sessionName, AGENT_BROWSER_SCRIPT_NAMESPACE);
         return undefined;
     };
-    const recoverScriptSessionLeasesWithinQueue = async (ctx) => {
+    const recoverScriptSessionLeasesWithinQueue = async (ctx, branch) => {
         const pendingSessionNames = new Set([...ownedManagedSessions.values()]
             .map((session) => session.sessionName)
             .filter(isAgentBrowserScriptSessionName));
-        for (const lease of getScriptSessionLeasesFromBranch(ctx.sessionManager.getBranch()).values()) {
+        for (const lease of getScriptSessionLeasesFromBranch(branch, ctx.sessionManager.getSessionId()).values()) {
             if (lease.cleanup !== "closed")
                 pendingSessionNames.add(lease.sessionName);
         }
@@ -1086,15 +1087,26 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             await closeScriptSessionLeaseWithinQueue(sessionName, ctx.cwd);
         }
     };
-    const restoreBranchBackedState = (ctx, options) => {
+    const restoreBranchBackedState = async (ctx, options) => {
         branchRestoreGeneration += 1;
         branchStateGeneration += 1;
+        restorePromptState(ctx);
         const previousManagedSessionActive = managedSessionActive;
         const previousManagedSessionName = managedSessionName;
         const previousFreshSessionOrdinal = freshSessionOrdinal;
         const previousAttachedSessionKeys = attachedSessionKeys;
         managedSessionBaseName = createImplicitSessionName(ctx.sessionManager.getSessionId(), ctx.cwd, ephemeralSessionSeed);
-        const branch = ctx.sessionManager.getBranch();
+        browserOwnerSessionId = ctx.sessionManager.getSessionId();
+        let branch;
+        try {
+            branch = await readBrowserEntries(ctx.sessionManager);
+            browserReplayError = undefined;
+        }
+        catch (error) {
+            browserReplayError = error instanceof Error ? error.message : String(error);
+            sessionPageState.reset();
+            throw error;
+        }
         const branchResourceEvents = collectBranchManagedResourceEvents(branch);
         const restoredState = restoreManagedSessionStateFromBranch(branch, managedSessionBaseName);
         managedSessionRestoreState.replace(restoredState.managedSessionRestoreDisabledIdentities, {
@@ -1120,15 +1132,11 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                 : createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, nextFreshSessionOrdinal)
             : restoredState.sessionName;
         managedSessionNamespace = shouldReservePostCloseSession ? undefined : restoredState.namespace;
-        managedSessionCompatibilityWorkaround = managedSessionActive
-            ? restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, managedSessionName, managedSessionNamespace)
-            : undefined;
-        managedSessionHeadedAutosaveDisabled = managedSessionActive
-            && restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, managedSessionName, managedSessionNamespace);
-        managedSessionHeadedAutosaveInterval = managedSessionActive
-            ? restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, managedSessionName, managedSessionNamespace)
-            : undefined;
-        managedSessionCwd = restoreManagedSessionCwd(branch, managedSessionName, managedSessionNamespace, ctx.cwd);
+        const currentLaunch = branchResourceEvents.managedSessionLaunchState.get(getSessionContextKey(managedSessionName, managedSessionNamespace) ?? managedSessionName);
+        managedSessionCompatibilityWorkaround = managedSessionActive ? currentLaunch?.compatibilityWorkaround : undefined;
+        managedSessionHeadedAutosaveDisabled = managedSessionActive && currentLaunch?.headedManagedAutosaveDisabled === true;
+        managedSessionHeadedAutosaveInterval = managedSessionActive ? currentLaunch?.headedManagedAutosaveInterval : undefined;
+        managedSessionCwd = currentLaunch?.cwd ?? ctx.cwd;
         freshSessionOrdinal = nextFreshSessionOrdinal;
         sessionPageState = SessionPageState.fromBranch(branch);
         traceOwners = new Map();
@@ -1179,12 +1187,14 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                 continue;
             if (!isRestorableManagedSessionName(identity.sessionName, managedSessionBaseName))
                 continue;
-            trackOwnedManagedSession(ownedManagedSessions, identity.sessionName, restoreManagedSessionCwd(branch, identity.sessionName, identity.namespace, ctx.cwd), {
+            const launch = branchResourceEvents.managedSessionLaunchState.get(sessionKey);
+            trackOwnedManagedSession(ownedManagedSessions, identity.sessionName, launch?.cwd ?? ctx.cwd, {
                 branchOwned: true,
-                compatibilityWorkaround: restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, identity.sessionName, identity.namespace),
-                headedManagedAutosaveDisabled: restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, identity.sessionName, identity.namespace),
-                headedManagedAutosaveInterval: restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, identity.sessionName, identity.namespace),
+                compatibilityWorkaround: launch?.compatibilityWorkaround,
+                headedManagedAutosaveDisabled: launch?.headedManagedAutosaveDisabled ?? false,
+                headedManagedAutosaveInterval: launch?.headedManagedAutosaveInterval,
                 namespace: identity.namespace,
+                socketDir: launch?.socketDir,
             });
         }
         if (restoredState.active) {
@@ -1194,6 +1204,32 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                 headedManagedAutosaveDisabled: managedSessionHeadedAutosaveDisabled,
                 headedManagedAutosaveInterval: managedSessionHeadedAutosaveInterval,
                 namespace: restoredState.namespace,
+                socketDir: currentLaunch?.socketDir,
+            });
+        }
+        const pendingOwnedBegins = new Map();
+        for (const entry of branch) {
+            const event = getBrowserRecord(entry)?.event;
+            if (!event)
+                continue;
+            if (event.phase === "begin" && event.state.ownerSessionId === browserOwnerSessionId && event.state.wrapperManaged === true)
+                pendingOwnedBegins.set(event.operationId, event);
+            else if (event.phase === "finish")
+                pendingOwnedBegins.delete(event.operationId);
+            for (const page of event.pages ?? [])
+                if (page.clear) {
+                    for (const [id, begin] of pendingOwnedBegins)
+                        if (begin.pages?.some(candidate => candidate.key === page.key))
+                            pendingOwnedBegins.delete(id);
+                }
+        }
+        for (const begin of pendingOwnedBegins.values()) {
+            if (typeof begin.state.sessionName !== "string")
+                continue;
+            // The persisted wrapper-selected intent proves cleanup scope, not launch success.
+            trackOwnedManagedSession(ownedManagedSessions, begin.state.sessionName, typeof begin.state.managedSessionCwd === "string" ? begin.state.managedSessionCwd : ctx.cwd, {
+                branchOwned: true, namespace: typeof begin.state.namespace === "string" ? begin.state.namespace : undefined,
+                socketDir: typeof begin.state.managedSessionSocketDir === "string" ? begin.state.managedSessionSocketDir : undefined,
             });
         }
         for (const record of getActiveElectronRecords(electronLaunchRecords)) {
@@ -1204,16 +1240,29 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             const closeRank = branchResourceEvents.managedSessionCloseRanks.get(sessionKey);
             if (activeRank === undefined || (closeRank !== undefined && closeRank >= activeRank))
                 continue;
-            trackOwnedManagedSession(ownedManagedSessions, record.sessionName, restoreManagedSessionCwd(branch, record.sessionName, undefined, ctx.cwd), {
+            const launch = branchResourceEvents.managedSessionLaunchState.get(sessionKey);
+            trackOwnedManagedSession(ownedManagedSessions, record.sessionName, launch?.cwd ?? ctx.cwd, {
                 branchOwned: true,
-                headedManagedAutosaveDisabled: restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, record.sessionName),
-                headedManagedAutosaveInterval: restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, record.sessionName),
+                headedManagedAutosaveDisabled: launch?.headedManagedAutosaveDisabled ?? false,
+                headedManagedAutosaveInterval: launch?.headedManagedAutosaveInterval,
+                socketDir: launch?.socketDir,
             });
         }
-        mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
+        mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, new Map([...electronLaunchRecords].filter(([, record]) => record.ownerSessionId === browserOwnerSessionId)), {
             branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
             markBranchOwned: true,
         });
+        for (const entry of branch) {
+            const event = getBrowserRecord(entry)?.event;
+            const state = event?.state;
+            if (event?.phase === "begin" || state?.ownerSessionId !== browserOwnerSessionId || typeof state.sessionName !== "string")
+                continue;
+            const namespace = typeof state.namespace === "string" ? state.namespace : undefined;
+            const key = getAgentBrowserSessionIdentityKey(state.sessionName, namespace);
+            if (ownedManagedSessions.has(key) && !managedSessionRestoreState.hasDaemonRestoreKey(state.sessionName, namespace)) {
+                managedSessionRestoreState.restoreDaemonReceipt(state.sessionName, namespace, state.managedSessionDaemon);
+            }
+        }
         if (!options.resetRuntimeOwnership) {
             for (const sessionKey of previousAttachedSessionKeys) {
                 if (ownedManagedSessions.has(sessionKey))
@@ -1225,12 +1274,12 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                     attachedSessionKeys.add(sessionKey);
             }
         }
+        return branch;
     };
     const registerWebSearchToolIfAvailable = (configState) => {
         if (webSearchToolRegistered || !canRegisterWebSearchTool(configState))
             return;
         pi.registerTool({
-            ...{ discovery: { group: AGENT_BROWSER_DISCOVERY_GROUP, role: "entry" } },
             ...createAgentBrowserWebSearchTool(configState, {
                 loadConfigState(ctx) {
                     return loadAgentBrowserConfigSync({
@@ -1242,15 +1291,19 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         });
         webSearchToolRegistered = true;
     };
+    pi.on("message_end", (event, ctx) => {
+        if (event.message.role === "user")
+            promptState = { sessionId: ctx.sessionManager.getSessionId(), message: event.message };
+    });
     pi.on("session_start", async (_event, ctx) => {
-        restoreBranchBackedState(ctx, { resetRuntimeOwnership: true });
-        electronChildProcesses = new Map();
-        registerWebSearchToolIfAvailable(loadAgentBrowserConfigSync({
-            cwd: ctx.cwd,
-            includeProjectConfig: shouldIncludeProjectConfig(ctx),
-        }));
         await managedSessionExecutionQueue.run(() => artifactExecutionQueue.run(async () => {
-            await recoverScriptSessionLeasesWithinQueue(ctx);
+            const branch = await restoreBranchBackedState(ctx, { resetRuntimeOwnership: true });
+            electronChildProcesses = new Map();
+            registerWebSearchToolIfAvailable(loadAgentBrowserConfigSync({
+                cwd: ctx.cwd,
+                includeProjectConfig: shouldIncludeProjectConfig(ctx),
+            }));
+            await recoverScriptSessionLeasesWithinQueue(ctx, branch);
             flushRecordingReservations();
             notifyRecordingPersistence(ctx);
         }));
@@ -1261,85 +1314,12 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             controller.abort();
         await Promise.allSettled([...activeScriptExecutions]);
         await managedSessionExecutionQueue.run(() => artifactExecutionQueue.run(async () => {
-            restoreBranchBackedState(ctx, { resetRuntimeOwnership: false });
-            await recoverScriptSessionLeasesWithinQueue(ctx);
+            const branch = await restoreBranchBackedState(ctx, { resetRuntimeOwnership: false });
+            await recoverScriptSessionLeasesWithinQueue(ctx, branch);
             flushRecordingReservations();
             notifyRecordingPersistence(ctx);
         }));
     });
-    // 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 code execution is pending");
-        flushRecordingReservations();
-        if (recordingReservationsDirty)
-            return blocked("Browser recording journal persistence is dirty");
-        if (activeRecordingReservations.size)
-            return blocked("Browser recording is pending; finish it explicitly before sleep");
-        const entries = ctx.sessionManager.getEntries();
-        if ([...getScriptSessionLeasesFromBranch(entries).values()].some(lease => lease.cleanup !== "closed")
-            || [...ownedManagedSessions.values()].some(owner => isAgentBrowserScriptSessionName(owner.sessionName))) {
-            return blocked("Browser script cleanup lease is unresolved");
-        }
-        if (getActiveElectronRecords(ownedElectronLaunchRecords).length || getActiveElectronRecords(electronLaunchRecords).length
-            || [...electronChildProcesses.values()].some(child => child.exitCode === null && child.signalCode === null)) {
-            return blocked("Electron launch is still active");
-        }
-        if (attachedSessionKeys.size || restoreAttachedSessionKeysFromBranch(entries).size)
-            return blocked("Attached browser state is caller-owned and not checkpointed");
-        if (traceOwners.size || [...networkRoutesBySession.values()].some(routes => routes.length))
-            return blocked("Browser trace or network routes are still active");
-        // Include off-branch and caller-owned/root identities, without acquiring
-        // cleanup ownership. Transcript page/ref details do not serialize a browser.
-        const historicalResources = collectBranchManagedResourceEvents(entries);
-        const sessions = new Map(ownedManagedSessions);
-        if (managedSessionActive)
-            trackOwnedManagedSession(sessions, managedSessionName, managedSessionCwd, { namespace: managedSessionNamespace });
-        for (const entry of entries) {
-            const message = getBrowserResultMessage(entry);
-            if (!message)
-                continue;
-            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
-                : details?.agentBrowserStarted === true ? "default" : undefined;
-            if (!sessionName)
-                continue;
-            const namespace = typeof details?.namespace === "string" ? details.namespace : undefined;
-            const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
-            if (!sessions.has(key))
-                trackOwnedManagedSession(sessions, sessionName, ctx.cwd, { namespace });
-        }
-        for (const [key, owner] of sessions) {
-            event.signal.throwIfAborted();
-            // An abnormal restart can leave a wrapper-created browser only off-branch.
-            // Reuse native ownership events for inspection, never cleanup ownership.
-            // A later close can refer to the same identity in a different socket root.
-            const historicalIdentity = historicalResources.managedSessionActiveIdentities.get(key);
-            const historicallyOwned = historicalIdentity && isRestorableManagedSessionName(historicalIdentity.sessionName, managedSessionBaseName);
-            const context = resolveOwnedManagedSessionContext({
-                ...owner,
-                currentManagedSessionName: managedSessionActive ? managedSessionName : undefined,
-                currentManagedSessionNamespace: managedSessionNamespace,
-                recordedOwnedSession: ownedManagedSessions.get(key) ?? (historicallyOwned ? { ...historicalIdentity, cwd: ctx.cwd } : undefined),
-                restoreState: managedSessionRestoreState,
-            });
-            // Owned routing must not mask an explicit caller's same-name ambient daemon.
-            for (const inspectionContext of context ? [{ ...context, reuseOnly: true }, undefined] : [undefined]) {
-                const daemon = await withOwnedManagedSessionContext(inspectionContext, () => inspectManagedSessionDaemon({ ...owner, signal: event.signal, timeoutMs: 2_000 }));
-                if (daemon.status !== "inactive")
-                    return blocked("Browser daemon is live or unverified; finish browser work explicitly before sleep");
-            }
-        }
-        // No detached writer remains to pause/resume. Native ingress stays held;
-        // checkpoint never closes a browser or changes ordinary shutdown ownership.
-        return { sleepReady: true };
-    });
     pi.on("session_shutdown", async (event, ctx) => {
         for (const controller of activeScriptControllers)
             controller.abort();
@@ -1351,7 +1331,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             const shutdownCwd = ctx?.cwd ?? managedSessionCwd;
             const quitting = event?.reason === "quit";
             preservedElectronProfileDirs = quitting
-                ? []
+                ? getActiveElectronRecords(electronLaunchRecords).filter(record => !ownedElectronLaunchRecords.has(record.launchId)).map(record => record.userDataDir)
                 : getActiveElectronRecords(electronLaunchRecords).map((record) => record.userDataDir);
             const electronRecordsToCleanup = quitting
                 ? ownedElectronLaunchRecords
@@ -1402,11 +1382,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         ownedManagedSessions.clear();
         await cleanupSecureTempArtifacts({ preservePaths: preservedElectronProfileDirs });
     });
-    pi.on("before_agent_start", async (event, ctx) => {
-        const sectionTools = event.systemPromptOptions?.sectionTools;
-        if (!Object.hasOwn(sectionTools ?? {}, "agent_browser") && !shouldAppendBrowserSystemPrompt(event.prompt)) {
-            return undefined;
-        }
+    const fullInstructions = (ctx) => {
         const runtimeConfig = loadAgentBrowserConfigSync({
             cwd: ctx.cwd,
             includeProjectConfig: shouldIncludeProjectConfig(ctx),
@@ -1422,14 +1398,42 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         const runtimeConfigPrompt = browserGuidance.length > 0
             ? `\n\nProject agent_browser config guidance:\n${browserGuidance.map((line) => `- ${line}`).join("\n")}`
             : "";
-        event.systemPromptOptions.sections.agent_browser = `${PROJECT_RULE_PROMPT}${runtimeConfigPrompt}`;
+        const guidelines = [
+            ...buildToolPromptGuidelines({
+                browserDefaultProfile: runtimeConfig.trustedBrowserDefaultProfile,
+                browserExecutablePath: runtimeConfig.trustedBrowserExecutablePath,
+                includeWebSearch: webSearchToolRegistered,
+                docs: getInstalledDocsPaths(),
+            }),
+            ...QUICK_START_GUIDELINES,
+            ...SHARED_BROWSER_PLAYBOOK_GUIDELINES,
+            ...WRAPPER_TAB_RECOVERY_BEHAVIOR,
+            ...Object.values(ADVANCED_TOOL_PROMPT_GUIDELINES).flat(),
+            ...(webSearchToolRegistered ? WEB_SEARCH_TOOL_PROMPT_GUIDELINES : []),
+        ];
+        return `${PROJECT_RULE_PROMPT}\n\n${[...new Set(guidelines)].map(line => `- ${line}`).join("\n")}${runtimeConfigPrompt}`;
+    };
+    let isInstructionsManaged = () => false;
+    pi.events.on("pi:instruction-groups", (data) => {
+        const collector = data;
+        collector.register({
+            ...AGENT_BROWSER_INSTRUCTION_GROUP,
+            tools: ["agent_browser", "agent_browser_code", "agent_browser_tools", "agent_browser_web_search",
+                ...Object.values(AGENT_BROWSER_TOOL_INVENTORY).map(({ name }) => name)],
+            instructions: fullInstructions,
+        });
+        isInstructionsManaged = collector.isManaged;
+    });
+    pi.on("before_agent_start", async (event, ctx) => {
+        if (!isInstructionsManaged())
+            event.systemPromptOptions.sections.agent_browser = fullInstructions(ctx);
     });
     pi.on("tool_call", async (event, ctx) => {
-        const promptPolicy = buildPromptPolicy(getLatestUserPrompt(ctx.sessionManager.getBranch()));
-        if (isBashToolCallEvent(event) &&
-            !promptPolicy.allowLegacyAgentBrowserBash &&
-            looksLikeDirectAgentBrowserBash(event.input.command) &&
-            !isHarmlessAgentBrowserInspectionCommand(event.input.command) &&
+        if (!isBashToolCallEvent(event) || !looksLikeDirectAgentBrowserBash(event.input.command)
+            || isHarmlessAgentBrowserInspectionCommand(event.input.command))
+            return;
+        const promptPolicy = getPromptPolicy(ctx);
+        if (!promptPolicy.allowLegacyAgentBrowserBash &&
             !(await isDirectAgentBrowserBashAllowed(ctx.cwd))) {
             return {
                 block: true,
@@ -1437,7 +1441,18 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             };
         }
     });
-    pi.on("tool_result", async (event) => buildAgentBrowserToolResultPatch(event));
+    let emptyBrowserBranch;
+    const captureCurrentBrowserBranch = (ctx) => {
+        const generation = branchRestoreGeneration;
+        const empty = ctx.sessionManager.getLeafId() === null;
+        // Concurrent empty-root callers share only their own first synchronous append.
+        if (empty && emptyBrowserBranch?.anchorId === null
+            && emptyBrowserBranch.sessionId === ctx.sessionManager.getSessionId() && emptyBrowserBranch.isCurrent())
+            return emptyBrowserBranch;
+        const branch = captureBrowserBranch(ctx.sessionManager, () => generation === branchRestoreGeneration);
+        emptyBrowserBranch = empty ? branch : undefined;
+        return branch;
+    };
     const agentBrowserTool = {
         renderCall(args, theme, context) {
             const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -1448,10 +1463,11 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             const component = context.lastComponent instanceof AgentBrowserResultComponent
                 ? context.lastComponent
                 : new AgentBrowserResultComponent();
-            component.setState(formatAgentBrowserRenderResult(result, options, theme, context.isError), options.expanded, theme);
+            component.setResult(result, options, theme, context.isError);
             return component;
         },
-        async execute(toolCallId, params, signal, onUpdate, ctx, nativeToolCallId = toolCallId, capturedCwd, modelVisible = true) {
+        async execute(toolCallId, params, signal, onUpdate, ctx, nativeToolCallId = toolCallId, capturedCwd, modelVisible = true, commandIndex, selectedBranch) {
+            const branch = selectedBranch ?? captureCurrentBrowserBranch(ctx);
             let operationCwd;
             try {
                 operationCwd = capturedCwd ?? resolveExecutionCwd(pi, ctx);
@@ -1459,7 +1475,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             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 promptPolicy = getPromptPolicy(ctx);
             const outputPath = isRecord(params) && typeof params.outputPath === "string" ? params.outputPath : undefined;
             const admittedInput = resolveAgentBrowserInput({
                 getBatchPreflightValidationError: (args, stdin) => getArtifactPreflightValidationError({ args, cwd: operationCwd, outputPath, stdin }),
@@ -1468,6 +1484,8 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             if (admittedInput.status === "invalid") {
                 return buildValidationFailureResult(admittedInput);
             }
+            if (browserReplayError && !isPlainTextInspectionArgs(admittedInput.toolArgs))
+                return browserExecutionFailure(new Error(browserReplayError), signal, "validation-error");
             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"
@@ -1533,7 +1551,31 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             branchRecords: electronLaunchRecords,
                             compiledElectron,
                             ownedRecords: ownedElectronLaunchRecords,
+                            ownerSessionId: ctx.sessionManager.getSessionId(),
                         });
+                        const hostAffecting = compiledElectron && ["cleanup", "probe"].includes(compiledElectron.action);
+                        const workingPageState = sessionPageState.fork();
+                        const priorPages = workingPageState.views();
+                        const priorManifest = artifactManifest;
+                        const operationId = randomUUID();
+                        const launchId = compiledElectron && "launchId" in compiledElectron ? compiledElectron.launchId : undefined;
+                        const selected = launchId ? [electronHostLaunchRecords.get(launchId)].filter((record) => record !== undefined) : getActiveElectronRecords(electronHostLaunchRecords);
+                        const keys = new Set(selected.flatMap(record => record.sessionName ? [getAgentBrowserSessionIdentityKey(record.sessionName, record.namespace)] : []));
+                        if (compiledElectron?.action === "probe" && !launchId && managedSessionActive)
+                            keys.add(getAgentBrowserSessionIdentityKey(managedSessionName, managedSessionNamespace));
+                        const begin = { event: { version: 1, phase: "begin", operationId, toolCallId, commandIndex: commandIndex ?? 0, isError: true,
+                                state: {}, pages: [...keys].map(key => ({ key, refs: { kind: "unknown" }, unknown: true })) } };
+                        if (hostAffecting) {
+                            try {
+                                if (!await appendBrowserRecord(ctx.sessionManager, () => appendBrowserTransition(pi, begin), begin, branch)
+                                    || !branch.isCurrent())
+                                    throw new Error("The selected Pi branch changed before host-operation admission.");
+                            }
+                            catch (error) {
+                                return browserExecutionFailure(new Error("Could not persist Electron/browser-state begin; the host operation was not run.", { cause: error }), executionSignal);
+                            }
+                            sessionPageState.applyBrowserRecord(begin);
+                        }
                         let electronHostResult = await handleElectronHostInput({
                             attachedSessionKeys,
                             compiledElectron,
@@ -1547,7 +1589,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             managedSessionRestoreState,
                             ownedManagedSessions,
                             redactedCompiledElectron,
-                            sessionPageState,
+                            sessionPageState: workingPageState,
                             signal: executionSignal,
                         });
                         if (electronHostResult && compiledElectron?.action === "cleanup") {
@@ -1575,6 +1617,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                                 retireRecordingSession(identity.sessionName, identity.namespace);
                                 const closedSessionKey = getSessionContextKey(identity.sessionName, identity.namespace) ?? identity.sessionName;
                                 clearSessionScopedBrowserState(closedSessionKey);
+                                workingPageState.clearSession(closedSessionKey);
                                 if (closedSessionKey === (getSessionContextKey(managedSessionName, managedSessionNamespace) ?? managedSessionName)) {
                                     managedSessionActive = false;
                                     managedSessionCompatibilityWorkaround = undefined;
@@ -1585,15 +1628,37 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                                     managedSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal);
                                 }
                             }
-                            if (artifactManifest) {
-                                electronHostResult = {
-                                    ...electronHostResult,
-                                    details: {
-                                        ...(isRecord(electronHostResult.details) ? electronHostResult.details : {}),
-                                        artifactManifest: redactSensitiveValue(artifactManifest),
-                                        artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
-                                    },
-                                };
+                            if (artifactManifest && isRecord(electronHostResult.details))
+                                electronHostResult.details.artifactRetentionSummary = formatSessionArtifactRetentionSummary(artifactManifest);
+                        }
+                        if (electronHostResult && hostAffecting && branch.isCurrent()) {
+                            for (const key of keys)
+                                if (workingPageState.get(key).refSnapshot && workingPageState.get(key).refSnapshot?.snapshotId !== priorPages.get(key)?.refSnapshot?.snapshotId) {
+                                    const record = selected.find(record => record.sessionName && getAgentBrowserSessionIdentityKey(record.sessionName, record.namespace) === key);
+                                    const owner = ownedManagedSessions.get(key);
+                                    const daemon = await inspectManagedSessionDaemon({ cwd: ctx.cwd, sessionName: record?.sessionName ?? managedSessionName, namespace: record?.namespace ?? managedSessionNamespace, signal: executionSignal, includeGeneration: true, headedManagedAutosaveInterval: owner?.headedManagedAutosaveInterval ?? (owner?.headedManagedAutosaveDisabled ? "0" : undefined) });
+                                    workingPageState.bindSnapshotGeneration(key, daemon.status === "active" ? daemon.generation : undefined);
+                                }
+                            const changes = browserPageChanges(workingPageState, priorPages, keys);
+                            const finish = { event: { version: 1, phase: hostAffecting ? "finish" : "state", operationId, toolCallId, commandIndex: commandIndex ?? 0, isError: electronHostResult.isError === true,
+                                    state: browserStateEffects(isRecord(electronHostResult.details) ? electronHostResult.details : {}), pages: changes.pages, artifacts: artifactChanges(priorManifest, artifactManifest) },
+                                ...(changes.snapshot ? { snapshot: changes.snapshot } : {}) };
+                            try {
+                                if (!await appendBrowserRecord(ctx.sessionManager, () => appendBrowserTransition(pi, finish), finish, branch)
+                                    || !branch.isCurrent())
+                                    throw new Error("The selected Pi branch changed before host-state confirmation.");
+                            }
+                            catch (error) {
+                                if (branch.isCurrent())
+                                    sessionPageState.applyBrowserRecord(begin);
+                                return { ...browserExecutionFailure(new Error("The host operation finished, but its state could not be persisted. Inspect before retrying; changes may already have happened.", { cause: error }), executionSignal),
+                                    details: { ...(isRecord(electronHostResult.details) ? electronHostResult.details : {}), browserStatePersistence: "finish-unconfirmed", resultCategory: "failure", failureCategory: "upstream-error", nextActions: undefined } };
+                            }
+                            sessionPageState.applyBrowserRecord(finish);
+                            artifactManifest = applyArtifactChanges(artifactManifest, finish.event.artifacts);
+                            if (isRecord(electronHostResult.details)) {
+                                electronHostResult.details.browserEventVersion = 1;
+                                electronHostResult.details.artifactManifest = invocationArtifactManifest(artifactManifest, priorManifest, electronHostResult.details);
                             }
                         }
                         if (electronHostResult && executionSignal?.aborted) {
@@ -1614,7 +1679,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             }) : runElectronHostInput(executionSignal);
                         if (!shouldSerializeElectronHostInput(compiledElectron))
                             return execute();
-                        const records = getElectronHostLaunchRecordsForInput({ branchRecords: electronLaunchRecords, compiledElectron, ownedRecords: ownedElectronLaunchRecords });
+                        const records = getElectronHostLaunchRecordsForInput({ branchRecords: electronLaunchRecords, compiledElectron, ownedRecords: ownedElectronLaunchRecords, ownerSessionId: ctx.sessionManager.getSessionId() });
                         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 }] : []);
@@ -1655,9 +1720,10 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                         // 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 workingPageState = sessionPageState.fork();
+                        const priorPages = workingPageState.views();
+                        const sessionPageStateUpdate = workingPageState.beginUpdate();
                         const browserRunState = {
                             activeRecordingReservations,
                             artifactManifest,
@@ -1678,7 +1744,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             managedSessionRestoreState,
                             networkRoutesBySession,
                             ownedManagedSessions,
-                            sessionPageState,
+                            sessionPageState: workingPageState,
                             traceOwners,
                         };
                         const selectedPlan = buildExecutionPlan(toolArgs, {
@@ -1691,6 +1757,30 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             stdin: resolvedInput.toolStdin,
                             browserIndependentReadConfirmation: readConfirmation?.capabilities?.readRequiresConfirmation === true,
                         });
+                        const browserAffecting = !selectedPlan.plainTextInspection && !(selectedPlan.commandInfo.command === "session" && selectedPlan.commandInfo.subcommand === "info")
+                            && (needsManagedSession(parseArgvDescriptor(toolArgs), resolvedInput.toolStdin) || (selectedPlan.startupScopedFlags?.length ?? 0) > 0);
+                        const operationId = randomUUID();
+                        const selectedKey = getAgentBrowserSessionIdentityKey(selectedPlan.sessionName ?? "default", selectedPlan.namespace);
+                        const begin = { event: {
+                                version: 1, phase: "begin", operationId, toolCallId, commandIndex: commandIndex ?? 0, isError: true,
+                                state: { args: redactInvocationArgs(toolArgs), sessionName: selectedPlan.sessionName, namespace: selectedPlan.namespace,
+                                    ownerSessionId: ctx.sessionManager.getSessionId(), usedImplicitSession: selectedPlan.usedImplicitSession,
+                                    wrapperManaged: selectedPlan.managedSessionName !== undefined || ownedManagedSessions.has(selectedKey), managedSessionCwd: browserCwd,
+                                    managedSessionSocketDir: resolveAgentBrowserSocketDir({ ownedManagedSession: selectedPlan.managedSessionName !== undefined || ownedManagedSessions.has(selectedKey) }) },
+                                pages: [{ key: selectedKey, refs: { kind: "unknown" }, unknown: true }],
+                            } };
+                        if (browserAffecting) {
+                            try {
+                                if (!await appendBrowserRecord(ctx.sessionManager, () => appendBrowserTransition(pi, begin), begin, branch)
+                                    || !branch.isCurrent())
+                                    throw new Error("The selected Pi branch changed before browser-command admission.");
+                            }
+                            catch (error) {
+                                const failure = browserExecutionFailure(new Error("Could not persist browser-state begin; the browser command was not run.", { cause: error }), executionSignal);
+                                return { ...failure, details: { ...(isRecord(failure.details) ? failure.details : {}), browserStatePersistence: "begin-unconfirmed" } };
+                            }
+                            sessionPageState.applyBrowserRecord(begin);
+                        }
                         const initialArtifactManifest = browserRunState.artifactManifest;
                         const initialNetworkRoutesBySession = browserRunState.networkRoutesBySession;
                         const attachedSessionRequested = isAttachedBrowserInvocation(toolArgs)
@@ -1702,28 +1792,37 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             : 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;
+                        let result;
+                        try {
+                            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,
+                            });
+                        }
+                        catch (error) {
+                            const failure = browserExecutionFailure(error, executionSignal);
+                            result = { ...failure, details: { ...browserRunState.observedBrowserEffects, ...(isRecord(failure.details) ? failure.details : {}) } };
+                        }
+                        const branchRestoreStillCurrent = branch.isCurrent();
                         const resultDetails = isRecord(result.details) ? result.details : undefined;
+                        if (resultDetails && begin.event.state.wrapperManaged === true)
+                            resultDetails.managedSessionSocketDir = begin.event.state.managedSessionSocketDir;
                         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;
@@ -1780,18 +1879,10 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                                 if (reservation)
                                     result = appendActiveRecordingCleanupAction(result, reservation);
                             }
-                            if (artifactManifest) {
-                                result = {
-                                    ...result,
-                                    details: {
-                                        ...(isRecord(result.details) ? result.details : {}),
-                                        artifactManifest: redactSensitiveValue(artifactManifest),
-                                        artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest),
-                                    },
-                                };
-                            }
+                            if (artifactManifest && isRecord(result.details))
+                                result.details.artifactRetentionSummary = formatSessionArtifactRetentionSummary(artifactManifest);
                         }
-                        const branchStateStillCurrent = generationAtStart === branchStateGeneration;
+                        const branchStateStillCurrent = generationAtStart === branchStateGeneration && branch.isCurrent();
                         if (serializeBrowserCommand || branchStateStillCurrent) {
                             freshSessionOrdinal = Math.max(freshSessionOrdinal, browserRunState.freshSessionOrdinal);
                             managedSessionActive = browserRunState.managedSessionActive;
@@ -1806,6 +1897,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             }
                             syncOwnedManagedSessionsFromResult(ownedManagedSessions, result, browserRunState.managedSessionCwd);
                             mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
+                                ownerSessionId: ctx.sessionManager.getSessionId(),
                                 branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
                                 touchedLaunchIds: !result.isError
                                     ? getTouchedElectronLaunchIds(explicitSessionName ?? browserRunState.managedSessionName, electronLaunchRecords, resultNamespace)
@@ -1814,6 +1906,39 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             if (serializeBrowserCommand)
                                 branchStateGeneration += 1;
                         }
+                        if (!selectedPlan.plainTextInspection && branchRestoreStillCurrent) {
+                            const changes = browserPageChanges(workingPageState, priorPages, [...browserRunState.closedManagedSessionNames, ...(browserAffecting ? [selectedKey] : [])]);
+                            const artifacts = artifactChanges(initialArtifactManifest, artifactManifest);
+                            if (browserAffecting || changes.pages.length > 0 || artifacts && hasPublishedBrowserJournal(ctx.sessionManager) || resultDetails?.readConfirmation !== undefined || browserRunState.observedBrowserEffects?.readConfirmation !== undefined) {
+                                const finish = { event: {
+                                        version: 1, phase: browserAffecting ? "finish" : "state", operationId, toolCallId, commandIndex: commandIndex ?? 0, isError: result.isError === true,
+                                        state: { ...browserStateEffects(isRecord(result.details) ? result.details : {}), ...browserRunState.observedBrowserEffects,
+                                            ownerSessionId: ctx.sessionManager.getSessionId(),
+                                            ...(begin.event.state.wrapperManaged === true ? { managedSessionDaemon: managedSessionRestoreState.getDaemonReceipt(resultSessionName, resultNamespace) } : {}) }, pages: changes.pages,
+                                        artifacts,
+                                    }, ...(changes.snapshot ? { snapshot: changes.snapshot } : {}) };
+                                try {
+                                    if (!await appendBrowserRecord(ctx.sessionManager, () => appendBrowserTransition(pi, finish), finish, branch)
+                                        || !branch.isCurrent())
+                                        throw new Error("The selected Pi branch changed before browser-state confirmation.");
+                                }
+                                catch (error) {
+                                    return { ...result, ...browserExecutionFailure(new Error("The browser command finished, but its state could not be persisted. Changes may already have happened; inspect the current page before retrying.", { cause: error }), executionSignal), details: { ...(isRecord(result.details) ? result.details : {}), resultCategory: "failure", failureCategory: "upstream-error", browserStatePersistence: "finish-unconfirmed", nextActions: [{
+                                                    id: "inspect-after-browser-state-persistence-failure", tool: "agent_browser", params: { args: ["--session", selectedPlan.sessionName ?? "default", "--namespace", selectedPlan.namespace ?? "", "batch", "--bail"], stdin: JSON.stringify([["get", "url"], ["snapshot", "-i"]]) },
+                                                    reason: "The effect may already have happened. Verify the current URL and inspect before deciding whether to retry.", safety: "Read-only inspection; no mutation is replayed.",
+                                                }] } };
+                                }
+                                sessionPageState.applyBrowserRecord(finish);
+                                artifactManifest = applyArtifactChanges(artifactManifest, finish.event.artifacts);
+                            }
+                        }
+                        if (isRecord(result.details)) {
+                            result.details.browserEventVersion = 1;
+                            if (!(compiledElectron?.action === "launch" && compiledElectron.handoff === "snapshot")
+                                && !getArtifactCommandSteps(toolArgs, resolvedInput.toolStdin).steps.some(step => step[0] === "snapshot"))
+                                delete result.details.refSnapshot;
+                            result.details.artifactManifest = invocationArtifactManifest(branch.isCurrent() ? artifactManifest : browserRunState.artifactManifest, initialArtifactManifest, result.details);
+                        }
                         return applyAgentBrowserOutputPath({ cwd: operationCwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result: warnRecordingPersistence(result) });
                     };
                     const closesAllSessions = commandClosesAllSessions(toolArgs, resolvedInput.toolStdin);
@@ -1825,35 +1950,39 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             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)
+                        const owner = ownedManagedSessions.get(getAgentBrowserSessionIdentityKey(plan.sessionName ?? "default", plan.namespace));
+                        return withAgentBrowserProcessEnvironment(owner?.socketDir ? { PI_AGENT_BROWSER_SOCKET_DIR: owner.socketDir } : {}, async () => {
+                            const run = (executionSignal = signal) => {
+                                const execute = () => withLaunchDefaults
+                                    ? withLaunchDefaults(inactive => runBrowserCommand(inactive, executionSignal), executionSignal)
+                                    : runBrowserCommand(undefined, executionSignal);
+                                if (!commandTouchesArtifactLifecycle(toolArgs, resolvedInput.toolStdin, outputPath))
                                     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 }));
+                                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) {
+                                    const previousOwner = ownedManagedSessions.get(getAgentBrowserSessionIdentityKey(managedSessionName, managedSessionNamespace));
+                                    identities.push(await resolveBrowserExecutionIdentity({ namespace: managedSessionNamespace, ownedManagedSession: true, sessionName: managedSessionName, env: previousOwner?.socketDir ? { AGENT_BROWSER_SOCKET_DIR: previousOwner.socketDir } : undefined }));
+                                }
+                                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 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);
-                        }
-                        catch (error) {
-                            return browserExecutionFailure(error, signal);
-                        }
+                            catch (error) {
+                                return browserExecutionFailure(error, signal);
+                            }
+                        });
                     };
                     const runWithinSessionQueue = () => {
                         if (closesAllSessions)
@@ -1887,9 +2016,15 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             return managedSessionExecutionQueue.run(executeAdmitted, signal);
         },
     };
-    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");
+    const executeCode = async (toolCallId, params, signal, _onUpdate, ctx, branch) => {
+        if (browserReplayError)
+            return browserExecutionFailure(new Error(browserReplayError), signal, "validation-error");
+        try {
+            requirePublishedBrowserJournal(ctx.sessionManager);
+        }
+        catch (error) {
+            return browserExecutionFailure(error, signal, "validation-error");
+        }
         let operationCwd;
         try {
             operationCwd = resolveExecutionCwd(pi, ctx);
@@ -1903,12 +2038,8 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         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 {
@@ -1937,9 +2068,10 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                     const namespace = plan.namespace || undefined;
                     const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
                     const owned = plan.managedSessionName !== undefined || ownedManagedSessions.has(key);
-                    const run = async () => {
+                    const run = async () => withAgentBrowserProcessEnvironment(ownedManagedSessions.get(key)?.socketDir ? { PI_AGENT_BROWSER_SOCKET_DIR: ownedManagedSessions.get(key).socketDir } : {}, async () => {
                         const identity = await resolveBrowserExecutionIdentity({ sessionName, namespace, ownedManagedSession: owned });
                         return withBrowserExecutionLock({ identity, deadline, signal: controller.signal }, async (executionSignal) => {
+                            let commandIndex = 0;
                             let journalFailed = false;
                             const run = await runAgentBrowserScript({
                                 code: params.code, signal: executionSignal, timeoutMs: Math.max(1, deadline - Date.now()),
@@ -1950,33 +2082,24 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                                     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 {
+                                    // The ordinary executor journals direct, code and hidden-helper effects alike.
+                                    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, commandIndex++, branch));
+                                    if (isRecord(result.details) && result.details.browserStatePersistence !== undefined) {
                                         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.");
-                                        }
+                                        throw new Error("The browser effect may already have happened and its finish could not be persisted. Inspect before continuing; dependent commands were stopped.");
                                     }
                                     return output.observe(result);
                                 },
                             });
                             const result = await output.finish(run, sessionName, namespace);
-                            if (artifactManifest && isRecord(result.details))
-                                result.details.artifactManifest = redactSensitiveValue(artifactManifest);
+                            if (journalFailed && isRecord(result.details)) {
+                                result.isError = true;
+                                result.details.resultCategory = "failure";
+                                result.details.failureCategory = "upstream-error";
+                                result.details.error = "Browser-state persistence failed. Dependent calls were stopped; inspect before continuing because already-dispatched effects may have happened.";
+                            }
+                            if (isRecord(result.details))
+                                result.details.browserEventVersion = 1;
                             if (!params.outputPath)
                                 return result;
                             return artifactExecutionQueue.run(async () => {
@@ -1988,7 +2111,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                                 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);
@@ -2004,11 +2127,9 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             clearTimeout(deadlineTimer);
             activeScriptControllers.delete(controller);
             signal?.removeEventListener("abort", abort);
-            activeScriptExecutions.delete(execution);
-            finish();
         }
     };
-    const finalizeObservation = async (result, params, ctx) => {
+    const finalizeObservation = async (result, params, ctx, branch) => {
         if ("args" in params && params.args && isPlainTextInspectionArgs(params.args))
             return result;
         const { renderAgentBrowserObservation } = await import("./lib/results/presentation/large-output.js");
@@ -2016,27 +2137,59 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         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) } : {}) } };
+        const renderOptions = { content: result.content, details, json: "code" in params || params.args?.includes("--json") === true, succeeded: result.isError !== true,
+            persistentArtifactStore: branch.isCurrent() ? getPersistentSessionArtifactStore(ctx) : undefined,
+            withArtifactWrite: (write) => artifactExecutionQueue.run(() => {
+                if (!branch.isCurrent())
+                    renderOptions.persistentArtifactStore = undefined;
+                return write();
+            }) };
+        const rendered = await renderAgentBrowserObservation(renderOptions);
+        if (!priorManifest && !rendered.artifactManifest)
+            return { ...result, content: rendered.content, structuredContent: rendered.structuredContent, details: { ...details, browserEventVersion: 1 } };
+        return artifactExecutionQueue.run(async () => {
+            if (!branch.isCurrent())
+                return { ...result, content: rendered.content, structuredContent: rendered.structuredContent, details: { ...details, browserEventVersion: 1, artifactManifest: rendered.artifactManifest } };
+            const before = artifactManifest;
+            const merged = mergeBrowserRunArtifactManifest(artifactManifest, priorManifest, rendered.artifactManifest);
+            const changes = artifactChanges(before, merged);
+            if (changes && hasPublishedBrowserJournal(ctx.sessionManager)) {
+                const record = { event: { version: 1, phase: "state", operationId: randomUUID(), toolCallId: "observation", commandIndex: 0, isError: result.isError === true, state: {}, artifacts: changes } };
+                if (!await appendBrowserRecord(ctx.sessionManager, () => appendBrowserTransition(pi, record), record, branch)
+                    || !branch.isCurrent())
+                    return { ...result, content: rendered.content, structuredContent: rendered.structuredContent, details: { ...details, browserEventVersion: 1, artifactManifest: rendered.artifactManifest } };
+            }
+            artifactManifest = mergeBrowserRunArtifactManifest(artifactManifest, priorManifest, rendered.artifactManifest);
+            return { ...result, content: rendered.content, structuredContent: rendered.structuredContent, details: { ...details, browserEventVersion: 1, artifactManifest: invocationArtifactManifest(artifactManifest, before, details, priorManifest) } };
+        });
     };
     registerAgentBrowserToolSurface(pi, {
         async execute(id, params, signal, onUpdate, ctx) {
+            const branch = captureCurrentBrowserBranch(ctx);
             let result;
             try {
-                result = await agentBrowserTool.execute(id, params, signal, onUpdate, ctx);
+                result = await agentBrowserTool.execute(id, params, signal, onUpdate, ctx, id, undefined, true, undefined, branch);
             }
             catch (error) {
                 result = browserExecutionFailure(error, signal);
             }
-            return finalizeObservation(result, params, ctx);
+            return finalizeObservation(result, params, ctx, branch);
         },
         async executeCode(id, params, signal, onUpdate, ctx) {
-            const result = await executeCode(id, params, signal, onUpdate, ctx);
-            return finalizeObservation(result, params, ctx);
+            const branch = captureCurrentBrowserBranch(ctx);
+            let finish;
+            const execution = new Promise(resolve => { finish = resolve; });
+            activeScriptExecutions.add(execution);
+            try {
+                const result = await executeCode(id, params, signal, onUpdate, ctx, branch);
+                return await finalizeObservation(result, params, ctx, branch);
+            }
+            finally {
+                activeScriptExecutions.delete(execution);
+                finish();
+            }
         },
         executionMode: beforeExecute ? "sequential" : undefined,
-        promptGuidelines: toolPromptGuidelines,
         renderCall: agentBrowserTool.renderCall, renderResult: agentBrowserTool.renderResult,
     });
     registerWebSearchToolIfAvailable(agentBrowserConfig);