pi-agent-browser-native 0.2.76 → 0.2.77

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.77 - 2026-08-04
+
+### Fixed
+
+- Successful `connect`, `--cdp`, and `--auto-connect` sessions, including environment-configured and wrapper-launched Electron attachments, now keep their attached browser across native-tool follow-ups and cleanup instead of resending local-launch defaults that made upstream replace the connection and prompt again. Content-bearing first use is blocked until the attachment URL is verified, established attachments live-check `get url` before later page reads or interactions so external tab drift cannot expose a local target, and every child clears the file-access environment override even when attached reuse omits the canonical launch flags.
+
 ## 0.2.76 - 2026-08-04
 
 ### Fixed

package/README.md

@@ -510,8 +510,8 @@ Use these rules:
 - Do not assume `--profile Default` is correct. Ask the agent to run `profiles` to list Chrome profile directory names, then `doctor` if profile/user-data-dir resolution still fails.
 - For non-Chrome Chromium browsers such as Brave, Edge, Arc, or Vivaldi, use `--executable-path <path>` when upstream can launch that executable. If you need that browser's existing login state, use the browser's real profile/user-data directory path when upstream accepts it, or attach with `--auto-connect` / `connect` to a debug-enabled running browser when appropriate.
 - Use `sessionMode: "fresh"` when switching from public browsing to `--allowed-domains`, `--profile`, `--executable-path`, `--webgpu`, `--restore`, `--restore-save`, restore check flags, `--namespace`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, `--enable`, `-p` / `--provider`, or iOS `--device`.
-- Use `--session` when you want to manage a live upstream session name yourself.
-- Do not treat an arbitrary `--session` name alone as persisted auth after `close`, `quit`, or `exit`. Wrapper-owned managed sessions automatically set a Git-checkout-generation-stable `AGENT_BROWSER_RESTORE` key so cookies/localStorage/sessionStorage survive browser relaunches across Pi chats in the same checkout; the key follows a renamed checkout but changes when that path is replaced or copied, and automatic restore fails closed outside a Git checkout. The wrapper combines the checkout-root and Git-admin filesystem identities with a generation UUID in the Git admin directory and never adopts older cwd-only keys; a bare caller `--session` name does not get that injection, and the wrapper reserves `piab-*` names case-insensitively so another Pi process cannot attach to a managed authenticated browser through a case alias. Disable with `PI_AGENT_BROWSER_MANAGED_SESSION_RESTORE=0`. For explicit non-managed sessions use `--session <id> --restore`, `--profile`, or `--state`. SSO/2FA such as Okta Touch ID may still need one human approval (often `--headed` the first time); after that, managed restore should keep the session without a manual `state save` dance. Any upstream `agent-browser.json` / `AGENT_BROWSER_CONFIG` / `--config` discovered while planning blocks browser-backed native calls without reading it, while accepted browser-backed spawns pin a process-private empty config to close config-creation races. This is separate from this package's trusted Pi-scoped config; sessionless local/setup commands retain upstream config behavior. Raw batch argv, batch stdin containing nested `connect`/`batch`, browser mutation flag, or matching launch-mutation env disables automatic managed restore rather than risking restored auth in a caller-customized or attached browser. Every accepted browser-backed subprocess, including wrapper-owned close, pins `AGENT_BROWSER_CONFIG` to that process-private empty config (`0400` on POSIX) in the marked secure-temp lifecycle so a project or user config created between planning and spawn cannot change the browser. A user-private immutable ticket-claim lock serializes each same-identity daemon inspection through the receiving spawn and bridges the pre-update v2 lock path; every lock winner re-inspects the live daemon, and abandoned v2 locks fail closed rather than being reclaimed unsafely. POSIX process identity probes use absolute `/bin/ps` then `/usr/bin/ps` paths. Before an incompatible call, the wrapper inspects the actual same-identity daemon and blocks when it retains any restore key, cannot be inspected, or reports restore-disabled policy without current-process provenance, including daemons missing from transcript state and sessions launched with explicit restore keys. Same-process `session_tree` transitions retain recorded provenance; extension reload, restart, and `/resume` deliberately do not trust transcript-only provenance for a still-live restore-disabled daemon, so close it first, omit the explicit session and use `sessionMode: "fresh"`, or choose a distinct explicit session. If inspection instead proves the old daemon inactive, the next owned no-restore spawn records that null policy so subsequent follow-ups remain usable. Wrapper-owned subprocesses pin the canonical namespace, including an explicit empty default, so a parent `AGENT_BROWSER_NAMESPACE` cannot redirect close or helper calls; Electron status target reads and current-managed probes also acquire the same daemon-policy lock, verify the live URL before title/content reads, and apply the same restore decision to every underlying read. A probe whose reads all fail is an `upstream-error`, not a successful empty partial result. Current-managed probe results persist their namespace and ref state for Pi reload/branch replay. Upstream restore files live under `~/.agent-browser/` and are plaintext unless you set `AGENT_BROWSER_ENCRYPTION_KEY`; on POSIX the wrapper canonicalizes and pins `HOME` after caller env merging, requires owner-trusted non-writable ancestry, requires stable device/inode/birth-time metadata for both checkout and Git-admin directories, enforces mode `0700` without silently tightening unsafe existing directories, and rejects symlinks/non-directories along the exact restore `sessions` path and its `.tmp` write area before automatic managed restore. Windows automatic managed restore requires an absolute `USERPROFILE` and the documented 64-character hex `AGENT_BROWSER_ENCRYPTION_KEY` because POSIX mode checks cannot verify profile ACLs. Wrapper-owned close commands discard caller config/restore globals, preserve the live daemon's existing restore key instead of injecting one derived from a possibly replaced checkout, and record a returned old-generation snapshot against that observed wrapper key. If a fresh command starts agent-browser but then fails, the wrapper probes that exact identity and retains a live or uninspectable daemon for shutdown cleanup instead of abandoning it. After a wrapper-owned managed session closes successfully, the wrapper persists the returned state path as an atomic record in a lockless convergent per-key ownership directory (`0700`, with `0600` records, on POSIX), keeps the two newest proven snapshots for its exact restore key across Pi restarts, self-heals malformed regular records, removes additional proven snapshots older than 30 days, expires ownership-proven snapshots and empty manifests from older restore-key generations only when a private lineage record proves the same canonical checkout path, after 30 days, and caps young close churn at 256 records per restore key; unrecorded matching files and the current checkout key remain untouched. Managed restore keys and key-bearing paths are redacted from tool output and transcripts. `session list` and `state list` hide wrapper-managed rows; cross-checkout managed `--restore` / `--state` / state-file access, broad `state clear`, `state clean`, and managed save/rename targets are rejected before spawn. Browser access to `.agent-browser` storage is blocked through command-specific file operands (including dash-prefixed values), every path-bearing upstream environment mirror (including state/profile/config, executable/extension/init-script, action-policy, artifact, skills, and socket paths), encoded, nested-file-scheme, Windows-aliased, or symlinked targets (including not-yet-created descendants of symlinked directories), content-returning local-URL commands, protected artifact destinations and top-level `outputPath`, local-page follow-ups, and persisted unverified top-level or batch tab/attachment/script/state-load transitions. Raw batch command strings are split on literal ASCII spaces exactly like upstream and inspected recursively just like batch stdin arrays; Electron launch handoffs, probes, and later capture share the same boundary: snapshot/tabs handoff and probes verify the live URL before tab/title/content helpers, and cancellation during handoff closes the managed session plus process/profile. The wrapper rejects enabled `--allow-file-access` argv/env plus file-access-enabling or protected-path `--args` / `AGENT_BROWSER_ARGS` values, removes caller file-access occurrences, clears raw-args env, and adds canonical `--args "" --allow-file-access false` defaults so project/user config cannot silently preserve local-page filesystem access; an explicit safe CLI `--args` value may still override the empty default. Post-transition summaries, including after arbitrary `eval`, verify the live URL before title and fail implicit transitions to local file pages; failed navigation attempts remain unverified, and stale concurrent completions cannot overwrite newer unknown page state. `get url`, `tab list`, non-content `tab <id>` selection, explicit safe navigation away, and session/tab close remain available for recovery; tab selection stays unverified until `get url` succeeds. The wrapper repeats checkout, storage, environment, managed-session ownership, and managed-state access validation after async config/socket setup immediately before spawn. On POSIX the selected daemon socket directory must be absolute, current-user-owned, mode `0700`, under trusted ancestry, and free of symlink, foreign-owner, or special planted entries. Pre-existing unsafe modes are rejected rather than repaired, and the check is repeated immediately before spawn. On native Windows, command-first launcher reordering moves only syntactically valid leading globals, rewrites a valued `--restore <name>` as `--restore=<name>` to preserve upstream optional-value semantics, and leaves invalid or command-scoped leading tokens untouched. Upstream periodically saves restore-enabled cookies/localStorage while the browser is open; `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` defaults to `30000`, `0` disables periodic saves but keeps save-on-close, and the `never` value for `--restore-save` disables automatic saves for that restore session.
+- Use `--session` when you want to manage a live upstream session name yourself. For CDP, connect once, verify with `get url`, keep using that session without repeating `--cdp`, and close it explicitly when done. The wrapper preserves the established attachment across follow-ups instead of resending local-launch defaults, and live-checks the URL before later page reads or interactions because an attached browser can change tabs outside Pi.
+- Do not treat an arbitrary `--session` name alone as persisted auth after `close`, `quit`, or `exit`. Wrapper-owned managed sessions automatically set a Git-checkout-generation-stable `AGENT_BROWSER_RESTORE` key so cookies/localStorage/sessionStorage survive browser relaunches across Pi chats in the same checkout; the key follows a renamed checkout but changes when that path is replaced or copied, and automatic restore fails closed outside a Git checkout. The wrapper combines the checkout-root and Git-admin filesystem identities with a generation UUID in the Git admin directory and never adopts older cwd-only keys; a bare caller `--session` name does not get that injection, and the wrapper reserves `piab-*` names case-insensitively so another Pi process cannot attach to a managed authenticated browser through a case alias. Disable with `PI_AGENT_BROWSER_MANAGED_SESSION_RESTORE=0`. For explicit non-managed sessions use `--session <id> --restore`, `--profile`, or `--state`. SSO/2FA such as Okta Touch ID may still need one human approval (often `--headed` the first time); after that, managed restore should keep the session without a manual `state save` dance. Any upstream `agent-browser.json` / `AGENT_BROWSER_CONFIG` / `--config` discovered while planning blocks browser-backed native calls without reading it, while accepted browser-backed spawns pin a process-private empty config to close config-creation races. This is separate from this package's trusted Pi-scoped config; sessionless local/setup commands retain upstream config behavior. Raw batch argv, batch stdin containing nested `connect`/`batch`, browser mutation flag, or matching launch-mutation env disables automatic managed restore rather than risking restored auth in a caller-customized or attached browser. Every accepted browser-backed subprocess, including wrapper-owned close, pins `AGENT_BROWSER_CONFIG` to that process-private empty config (`0400` on POSIX) in the marked secure-temp lifecycle so a project or user config created between planning and spawn cannot change the browser. A user-private immutable ticket-claim lock serializes each same-identity daemon inspection through the receiving spawn and bridges the pre-update v2 lock path; every lock winner re-inspects the live daemon, and abandoned v2 locks fail closed rather than being reclaimed unsafely. POSIX process identity probes use absolute `/bin/ps` then `/usr/bin/ps` paths. Before an incompatible call, the wrapper inspects the actual same-identity daemon and blocks when it retains any restore key, cannot be inspected, or reports restore-disabled policy without current-process provenance, including daemons missing from transcript state and sessions launched with explicit restore keys. Same-process `session_tree` transitions retain recorded provenance; extension reload, restart, and `/resume` deliberately do not trust transcript-only provenance for a still-live restore-disabled daemon, so close it first, omit the explicit session and use `sessionMode: "fresh"`, or choose a distinct explicit session. If inspection instead proves the old daemon inactive, the next owned no-restore spawn records that null policy so subsequent follow-ups remain usable. Wrapper-owned subprocesses pin the canonical namespace, including an explicit empty default, so a parent `AGENT_BROWSER_NAMESPACE` cannot redirect close or helper calls; Electron status target reads and current-managed probes also acquire the same daemon-policy lock, verify the live URL before title/content reads, and apply the same restore decision to every underlying read. A probe whose reads all fail is an `upstream-error`, not a successful empty partial result. Current-managed probe results persist their namespace and ref state for Pi reload/branch replay. Upstream restore files live under `~/.agent-browser/` and are plaintext unless you set `AGENT_BROWSER_ENCRYPTION_KEY`; on POSIX the wrapper canonicalizes and pins `HOME` after caller env merging, requires owner-trusted non-writable ancestry, requires stable device/inode/birth-time metadata for both checkout and Git-admin directories, enforces mode `0700` without silently tightening unsafe existing directories, and rejects symlinks/non-directories along the exact restore `sessions` path and its `.tmp` write area before automatic managed restore. Windows automatic managed restore requires an absolute `USERPROFILE` and the documented 64-character hex `AGENT_BROWSER_ENCRYPTION_KEY` because POSIX mode checks cannot verify profile ACLs. Wrapper-owned close commands discard caller config/restore globals, preserve the live daemon's existing restore key instead of injecting one derived from a possibly replaced checkout, and record a returned old-generation snapshot against that observed wrapper key. If a fresh command starts agent-browser but then fails, the wrapper probes that exact identity and retains a live or uninspectable daemon for shutdown cleanup instead of abandoning it. After a wrapper-owned managed session closes successfully, the wrapper persists the returned state path as an atomic record in a lockless convergent per-key ownership directory (`0700`, with `0600` records, on POSIX), keeps the two newest proven snapshots for its exact restore key across Pi restarts, self-heals malformed regular records, removes additional proven snapshots older than 30 days, expires ownership-proven snapshots and empty manifests from older restore-key generations only when a private lineage record proves the same canonical checkout path, after 30 days, and caps young close churn at 256 records per restore key; unrecorded matching files and the current checkout key remain untouched. Managed restore keys and key-bearing paths are redacted from tool output and transcripts. `session list` and `state list` hide wrapper-managed rows; cross-checkout managed `--restore` / `--state` / state-file access, broad `state clear`, `state clean`, and managed save/rename targets are rejected before spawn. Browser access to `.agent-browser` storage is blocked through command-specific file operands (including dash-prefixed values), every path-bearing upstream environment mirror (including state/profile/config, executable/extension/init-script, action-policy, artifact, skills, and socket paths), encoded, nested-file-scheme, Windows-aliased, or symlinked targets (including not-yet-created descendants of symlinked directories), content-returning local-URL commands, protected artifact destinations and top-level `outputPath`, local-page follow-ups, and persisted unverified top-level or batch tab/attachment/script/state-load transitions. Raw batch command strings are split on literal ASCII spaces exactly like upstream and inspected recursively just like batch stdin arrays; Electron launch handoffs, probes, and later capture share the same boundary: snapshot/tabs handoff and probes verify the live URL before tab/title/content helpers, and cancellation during handoff closes the managed session plus process/profile. The wrapper rejects enabled `--allow-file-access` argv/env plus file-access-enabling or protected-path `--args` / `AGENT_BROWSER_ARGS` values, removes caller file-access occurrences, clears raw-args env, and adds canonical `--args "" --allow-file-access false` defaults on local-browser spawns so project/user config cannot silently preserve local-page filesystem access; attached-session follow-ups omit those launch-only flags; an explicit safe CLI `--args` value may still override the empty default. Post-transition summaries, including after arbitrary `eval`, verify the live URL before title and fail implicit transitions to local file pages; failed navigation attempts remain unverified, and stale concurrent completions cannot overwrite newer unknown page state. `get url`, `tab list`, non-content `tab <id>` selection, explicit safe navigation away, and session/tab close remain available for recovery; tab selection stays unverified until `get url` succeeds. The wrapper repeats checkout, storage, environment, managed-session ownership, and managed-state access validation after async config/socket setup immediately before spawn. On POSIX the selected daemon socket directory must be absolute, current-user-owned, mode `0700`, under trusted ancestry, and free of symlink, foreign-owner, or special planted entries. Pre-existing unsafe modes are rejected rather than repaired, and the check is repeated immediately before spawn. On native Windows, command-first launcher reordering moves only syntactically valid leading globals, rewrites a valued `--restore <name>` as `--restore=<name>` to preserve upstream optional-value semantics, and leaves invalid or command-scoped leading tokens untouched. Upstream periodically saves restore-enabled cookies/localStorage while the browser is open; `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` defaults to `30000`, `0` disables periodic saves but keeps save-on-close, and the `never` value for `--restore-save` disables automatic saves for that restore session.
 - Caller-owned explicit sessions are live-checked with `get url` before content-bearing reads or interactions. Missing or stale transcript page state is not treated as proof of a safe target; if the live URL cannot be verified, the requested content command does not run. Calls to the same effective canonical namespace/session are serialized inside one extension instance; explicit namespace argv overrides `AGENT_BROWSER_NAMESPACE`, including an explicit empty default from that probe through any semantic-action snapshot and the requested command, while different caller-owned sessions remain independent. Raw non-bail batches are rejected when a failed navigation could expose prior local or unverified page content; use exact `batch --bail` or split navigation from content. Protected Windows paths include drive-relative forms such as `C:.agent-browser\\state\\...`. Nested `batch` steps are rejected, and raw batch command strings mirror upstream's ASCII-space tokenizer, including its single/double-quote and backslash handling, without splitting on other Unicode whitespace.
 - Prefer page actions and storage checks over cookie dumps. `cookies get` can expose real profile cookies.
 - Prefer `auth save --password-stdin` over putting passwords in `args`; the wrapper only accepts caller `stdin` for `batch`, `eval --stdin`, and `auth save --password-stdin` (top-level `job` and `qa` compile to `batch` and supply their own stdin).

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

@@ -17,6 +17,7 @@ import { cleanupManagedSessionRestoreConfig, ManagedSessionRestoreState } from "
 import { isRecord } from "./lib/parsing.js";
 import { buildPromptPolicy, getLatestUserPrompt, shouldAppendBrowserSystemPrompt } from "./lib/prompt-policy.js";
 import { isCloseCommand } from "./lib/command-taxonomy.js";
+import { hasLaunchScopedFlagToken } from "./lib/launch-scoped-flags.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
 import { AGENT_BROWSER_PARAMS, } from "./lib/input-modes.js";
 import { parseAllowedDomainsPolicyFromArgs } from "./lib/navigation-policy.js";
@@ -118,6 +119,42 @@ function getToolResultArgs(details) {
         return details.effectiveArgs;
     return [];
 }
+function isAttachedBrowserInvocation(args, env = process.env) {
+    const autoConnectEnv = env.AGENT_BROWSER_AUTO_CONNECT;
+    return extractCommandTokens(args)[0] === "connect"
+        || hasLaunchScopedFlagToken(args, "--cdp")
+        || hasLaunchScopedFlagToken(args, "--auto-connect")
+        || env.AGENT_BROWSER_CDP !== undefined
+        || (autoConnectEnv !== undefined && !["", "0", "false", "no"].includes(autoConnectEnv.toLowerCase()));
+}
+function restoreAttachedSessionKeysFromBranch(branch) {
+    const attachedSessionKeys = new Set();
+    for (const entry of branch) {
+        if (!isRecord(entry) || entry.type !== "message")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        if (!message || message.toolName !== "agent_browser")
+            continue;
+        const details = isRecord(message.details) ? message.details : undefined;
+        if (!details)
+            continue;
+        const managedSessionOutcome = isRecord(details.managedSessionOutcome) ? details.managedSessionOutcome : undefined;
+        const retainedFailedAttachment = details.attachedBrowserSession === true && managedSessionOutcome?.activeAfter === true;
+        if (!getSuccessfulToolResult(details, message) && !retainedFailedAttachment)
+            continue;
+        const args = getToolResultArgs(details);
+        const sessionName = typeof details.sessionName === "string" ? details.sessionName : extractExplicitSessionName(args);
+        if (!sessionName)
+            continue;
+        const namespace = typeof details.namespace === "string" ? details.namespace : extractExplicitNamespace(args);
+        const sessionKey = getSessionContextKey(sessionName, namespace) ?? sessionName;
+        if (isCloseCommand(extractCommandTokens(args)[0]))
+            attachedSessionKeys.delete(sessionKey);
+        else if (details.attachedBrowserSession === true || isAttachedBrowserInvocation(args, {}))
+            attachedSessionKeys.add(sessionKey);
+    }
+    return attachedSessionKeys;
+}
 function restoreAllowedDomainsBySessionFromBranch(branch) {
     const restoredPolicies = new Map();
     for (const entry of branch) {
@@ -433,18 +470,18 @@ function syncElectronCleanupManagedSessions(sessions, cleanupResults) {
         untrackOwnedManagedSession(sessions, sessionName);
     }
 }
-async function closeOwnedManagedSessionsExcept(sessions, restoreState, keepSessionName, timeoutMs, keepNamespace) {
+async function closeOwnedManagedSessionsExcept(sessions, restoreState, keepSessionName, timeoutMs, attachedSessionKeys, keepNamespace) {
     const keepKey = getSessionContextKey(keepSessionName, keepNamespace);
     for (const [key, owner] of [...sessions]) {
         if (key === keepKey)
             continue;
-        const error = await closeManagedSession({ cwd: owner.cwd, namespace: owner.namespace, restoreState, sessionName: owner.sessionName, timeoutMs });
+        const error = await closeManagedSession({ cwd: owner.cwd, namespace: owner.namespace, preserveAttachedBrowserSession: attachedSessionKeys.has(key), restoreState, sessionName: owner.sessionName, timeoutMs });
         if (!error)
             sessions.delete(key);
     }
 }
-async function closeOwnedManagedSessions(sessions, restoreState, timeoutMs) {
-    await closeOwnedManagedSessionsExcept(sessions, restoreState, undefined, timeoutMs);
+async function closeOwnedManagedSessions(sessions, restoreState, timeoutMs, attachedSessionKeys) {
+    await closeOwnedManagedSessionsExcept(sessions, restoreState, undefined, timeoutMs, attachedSessionKeys);
 }
 function getOffBranchOwnedElectronLaunchRecords(ownedRecords, branchRecords) {
     const activeBranchLaunchIds = new Set(getActiveElectronRecords(branchRecords).map((record) => record.launchId));
@@ -585,6 +622,7 @@ export default function agentBrowserExtension(pi) {
     let traceOwners = new Map();
     let artifactManifest;
     let allowedDomainsBySession = new Map();
+    let attachedSessionKeys = new Set();
     let networkRoutesBySession = new Map();
     let electronLaunchRecords = new Map();
     let ownedElectronLaunchRecords = new Map();
@@ -600,6 +638,7 @@ export default function agentBrowserExtension(pi) {
         const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
         allowedDomainsBySession = new Map(allowedDomainsBySession);
         allowedDomainsBySession.delete(key);
+        attachedSessionKeys.delete(key);
         networkRoutesBySession = new Map(networkRoutesBySession);
         networkRoutesBySession.delete(key);
         sessionPageState.clearSession(key);
@@ -610,6 +649,7 @@ export default function agentBrowserExtension(pi) {
         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();
         const branchResourceEvents = collectBranchManagedResourceEvents(branch);
@@ -646,8 +686,13 @@ export default function agentBrowserExtension(pi) {
         traceOwners = new Map();
         artifactManifest = restoreArtifactManifestFromBranch(branch);
         allowedDomainsBySession = restoreAllowedDomainsBySessionFromBranch(branch);
+        attachedSessionKeys = restoreAttachedSessionKeysFromBranch(branch);
         networkRoutesBySession = new Map();
         electronLaunchRecords = restoreElectronLaunchRecordsFromBranch(branch);
+        for (const record of getActiveElectronRecords(electronLaunchRecords)) {
+            if (record.sessionName)
+                attachedSessionKeys.add(getSessionContextKey(record.sessionName) ?? record.sessionName);
+        }
         if (options.resetRuntimeOwnership) {
             ownedManagedSessions.clear();
             ownedElectronLaunchRecords = new Map();
@@ -666,6 +711,17 @@ export default function agentBrowserExtension(pi) {
             branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
             markBranchOwned: true,
         });
+        if (!options.resetRuntimeOwnership) {
+            for (const sessionKey of previousAttachedSessionKeys) {
+                if (ownedManagedSessions.has(sessionKey))
+                    attachedSessionKeys.add(sessionKey);
+            }
+            for (const record of ownedElectronLaunchRecords.values()) {
+                const sessionKey = getSessionContextKey(record.sessionName);
+                if (sessionKey && previousAttachedSessionKeys.has(sessionKey))
+                    attachedSessionKeys.add(sessionKey);
+            }
+        }
     };
     const registerWebSearchToolIfAvailable = (configState) => {
         if (webSearchToolRegistered || !canRegisterWebSearchTool(configState))
@@ -707,6 +763,7 @@ export default function agentBrowserExtension(pi) {
                 ? ownedElectronLaunchRecords
                 : getOffBranchOwnedElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords);
             const electronCleanupResults = await cleanupActiveElectronHostLaunches({
+                attachedSessionKeys,
                 cwd: shutdownCwd,
                 electronChildProcesses,
                 electronLaunchRecords: electronRecordsToCleanup,
@@ -719,10 +776,10 @@ export default function agentBrowserExtension(pi) {
                 ])];
             syncElectronCleanupManagedSessions(ownedManagedSessions, electronCleanupResults);
             if (quitting) {
-                await closeOwnedManagedSessions(ownedManagedSessions, managedSessionRestoreState, implicitSessionCloseTimeoutMs);
+                await closeOwnedManagedSessions(ownedManagedSessions, managedSessionRestoreState, implicitSessionCloseTimeoutMs, attachedSessionKeys);
             }
             else {
-                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, managedSessionActive ? managedSessionNamespace : undefined);
+                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, managedSessionActive ? managedSessionNamespace : undefined);
             }
         });
         managedSessionActive = false;
@@ -732,6 +789,7 @@ export default function agentBrowserExtension(pi) {
         traceOwners = new Map();
         artifactManifest = undefined;
         allowedDomainsBySession = new Map();
+        attachedSessionKeys = new Set();
         networkRoutesBySession = new Map();
         electronLaunchRecords = new Map();
         ownedElectronLaunchRecords = new Map();
@@ -822,6 +880,7 @@ export default function agentBrowserExtension(pi) {
                     ownedRecords: ownedElectronLaunchRecords,
                 });
                 const electronHostResult = await handleElectronHostInput({
+                    attachedSessionKeys,
                     compiledElectron,
                     cwd: ctx.cwd,
                     electronChildProcesses,
@@ -891,6 +950,7 @@ export default function agentBrowserExtension(pi) {
                 const browserRunState = {
                     allowedDomainsBySession,
                     artifactManifest,
+                    attachedSessionKeys,
                     closedManagedSessionNames: new Set(),
                     electronChildProcesses,
                     electronLaunchRecords,
@@ -911,6 +971,14 @@ export default function agentBrowserExtension(pi) {
                 const initialAllowedDomainsBySession = browserRunState.allowedDomainsBySession;
                 const initialArtifactManifest = browserRunState.artifactManifest;
                 const initialNetworkRoutesBySession = browserRunState.networkRoutesBySession;
+                const attachedSessionRequested = isAttachedBrowserInvocation(toolArgs)
+                    || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch");
+                const allocatesFreshManagedSession = explicitSessionName === undefined
+                    && (params.sessionMode === "fresh" || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch"));
+                const reusableSessionKey = allocatesFreshManagedSession
+                    ? undefined
+                    : callerOwnedSessionQueueKey ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
+                const attachedSessionKnown = reusableSessionKey !== undefined && attachedSessionKeys.has(reusableSessionKey);
                 let result = await runAgentBrowserTool({
                     ctx,
                     cwd: ctx.cwd,
@@ -921,12 +989,34 @@ export default function agentBrowserExtension(pi) {
                     input: resolvedInput,
                     onUpdate,
                     params,
+                    establishAttachedBrowserSession: attachedSessionRequested && !attachedSessionKnown,
+                    preserveAttachedBrowserSession: attachedSessionRequested || attachedSessionKnown,
                     promptPolicy,
                     sessionPageStateUpdate,
                     signal,
                     state: browserRunState,
                 });
                 const branchRestoreStillCurrent = branchRestoreGenerationAtStart === branchRestoreGeneration;
+                if (branchRestoreStillCurrent) {
+                    const resultDetails = isRecord(result.details) ? result.details : undefined;
+                    const resultSessionName = typeof resultDetails?.sessionName === "string"
+                        ? resultDetails.sessionName
+                        : extractExplicitSessionName(toolArgs);
+                    const resultNamespace = typeof resultDetails?.namespace === "string"
+                        ? resultDetails.namespace
+                        : resolveAgentBrowserNamespace(toolArgs, process.env.AGENT_BROWSER_NAMESPACE);
+                    const resultSessionKey = getSessionContextKey(resultSessionName, resultNamespace) ?? resultSessionName;
+                    const managedSessionOutcome = isRecord(resultDetails?.managedSessionOutcome) ? resultDetails.managedSessionOutcome : undefined;
+                    const attachedSessionRemainsActive = result.isError !== true
+                        || (attachedSessionRequested && managedSessionOutcome?.activeAfter === true);
+                    const closesAttachedSession = result.isError !== true && isCloseCommand(extractCommandTokens(toolArgs)[0]);
+                    if (resultSessionKey && closesAttachedSession)
+                        attachedSessionKeys.delete(resultSessionKey);
+                    else if (resultSessionKey && attachedSessionRemainsActive && (attachedSessionRequested || attachedSessionKnown)) {
+                        attachedSessionKeys.add(resultSessionKey);
+                        result = { ...result, details: { ...(resultDetails ?? {}), attachedBrowserSession: true } };
+                    }
+                }
                 if (branchRestoreStillCurrent) {
                     allowedDomainsBySession = mergeBrowserRunMap(allowedDomainsBySession, initialAllowedDomainsBySession, browserRunState.allowedDomainsBySession);
                     networkRoutesBySession = mergeBrowserRunMap(networkRoutesBySession, initialNetworkRoutesBySession, browserRunState.networkRoutesBySession);

package/dist/extensions/agent-browser/lib/orchestration/browser-run/index.js

@@ -1,4 +1,4 @@
-import { runAgentBrowserProcess } from "../../process.js";
+import { runAgentBrowserProcess, withAttachedBrowserSessionContext } from "../../process.js";
 import { withOwnedManagedSessionContext } from "../../managed-session-restore.js";
 import { cleanupClickDispatchProbe } from "./click-dispatch.js";
 import { applyBrowserRunStatePatch } from "./session-state.js";
@@ -8,6 +8,9 @@ import { processBrowserOutput } from "./process-output.js";
 export { closeManagedSession } from "./managed-session-daemon-policy.js";
 export { getSessionContextKey } from "./session-state.js";
 export async function runAgentBrowserTool(options) {
+    return await withAttachedBrowserSessionContext(options.preserveAttachedBrowserSession === true, () => runAgentBrowserToolInContext(options));
+}
+async function runAgentBrowserToolInContext(options) {
     const preparedResult = await prepareBrowserRun(options);
     applyBrowserRunStatePatch(options.state, preparedResult.kind === "ready" ? preparedResult.prepared.statePatch : preparedResult.statePatch);
     if (preparedResult.kind === "early-result") {

package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-daemon-policy.js

@@ -19,6 +19,7 @@ export async function inspectManagedSessionDaemon(options) {
         allowManagedSessionTarget: options.allowManagedSessionTarget,
         args: ["--json", "--namespace", options.namespace ?? "", "--session", options.sessionName, "session", "info"],
         cwd: options.cwd,
+        preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
         signal: options.signal,
         timeoutMs: options.timeoutMs ?? MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS,
     });
@@ -128,6 +129,7 @@ export async function closeManagedSession(options) {
             allowManagedSessionTarget: true,
             cwd: options.cwd,
             namespace: options.namespace,
+            preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
             sessionName: options.sessionName,
             signal: controller.signal,
             timeoutMs: Math.min(options.timeoutMs, 2_000),
@@ -143,6 +145,7 @@ export async function closeManagedSession(options) {
             env: { AGENT_BROWSER_JSON: "1" },
             managedSessionRestoreState: options.restoreState,
             ownedManagedSession: true,
+            preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
             signal: controller.signal,
         });
         stdoutSpillPath = processResult.stdoutSpillPath;

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare.js

@@ -451,13 +451,18 @@ export async function prepareBrowserRun(options) {
             const priorRefSnapshotState = priorSessionPageState.refSnapshot;
             const priorRefSnapshotInvalidation = priorSessionPageState.refSnapshotInvalidation;
             let semanticActionVisibleRefResolution;
-            let callerOwnedLivePageVerified = false;
+            let livePageVerified = false;
             const isCallerOwnedExplicitSession = () => executionPlan.sessionName !== undefined
                 && executionPlan.usedImplicitSession === false
                 && ownedManagedSession === undefined;
-            const verifyCallerOwnedLivePage = async (options) => {
-                if (!options.requirement || !executionPlan.sessionName)
+            const requiresLivePageVerification = () => isCallerOwnedExplicitSession() || options.preserveAttachedBrowserSession === true;
+            const verifyLivePage = async (request) => {
+                if (!request.requirement || !executionPlan.sessionName)
                     return;
+                if (options.establishAttachedBrowserSession) {
+                    executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: request.requirement };
+                    return;
+                }
                 let liveUrl;
                 try {
                     const liveUrlData = await runSessionCommandData({
@@ -475,27 +480,27 @@ export async function prepareBrowserRun(options) {
                         throw signal.reason ?? error;
                 }
                 if (liveUrl === undefined) {
-                    executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: options.requirement };
+                    executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: request.requirement };
                     return;
                 }
                 const livePageValidationError = getManagedSessionStateAccessValidationError({
-                    args: options.args,
+                    args: request.args,
                     currentPageUrl: liveUrl,
                     cwd,
                     pageUrlUnknown: false,
-                    stdin: options.stdin,
+                    stdin: request.stdin,
                 });
                 if (livePageValidationError) {
                     executionPlan = { ...executionPlan, recoveryHint: undefined, validationError: livePageValidationError };
                     return;
                 }
-                callerOwnedLivePageVerified = true;
+                livePageVerified = true;
                 priorSessionTabTarget ??= { url: liveUrl };
                 priorSessionTabTargetUnknown = undefined;
             };
             const mayResolveSemanticVisibleRef = executionPlan.managedSessionName !== freshSessionName && canResolveSemanticVisibleRef(compiledSemanticAction);
-            if (!executionPlan.validationError && mayResolveSemanticVisibleRef && isCallerOwnedExplicitSession()) {
-                await verifyCallerOwnedLivePage({
+            if (!executionPlan.validationError && mayResolveSemanticVisibleRef && requiresLivePageVerification()) {
+                await verifyLivePage({
                     args: ["snapshot", "-i"],
                     requirement: getCallerOwnedSessionLivePageVerificationRequirement({ args: ["snapshot", "-i"], cwd }),
                 });
@@ -530,21 +535,21 @@ export async function prepareBrowserRun(options) {
                 refSnapshotInvalidation: resolvedSemanticActionRefSnapshot ? undefined : priorRefSnapshotInvalidation,
                 stdin: runtimeToolStdin,
             });
-            const callerOwnedPageAccessEligible = !executionPlan.validationError
+            const livePageAccessEligible = !executionPlan.validationError
                 && preLiveStaleRefPreflight === undefined
                 && validateStdinCommandContract({ command: executionPlan.commandInfo.command, commandTokens, stdin: runtimeToolStdin }) === undefined
-                && isCallerOwnedExplicitSession();
-            const callerOwnedLivePageRequirement = callerOwnedPageAccessEligible
-                && !callerOwnedLivePageVerified
+                && requiresLivePageVerification();
+            const livePageRequirement = livePageAccessEligible
+                && !livePageVerified
                 ? getCallerOwnedSessionLivePageVerificationRequirement({
                     args: executionPlan.effectiveArgs,
                     cwd,
                     stdin: runtimeToolStdin,
                 })
                 : undefined;
-            await verifyCallerOwnedLivePage({
+            await verifyLivePage({
                 args: executionPlan.effectiveArgs,
-                requirement: callerOwnedLivePageRequirement,
+                requirement: livePageRequirement,
                 stdin: runtimeToolStdin,
             });
             const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);

package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output.js

@@ -405,9 +405,12 @@ export async function processBrowserOutput(input) {
             networkRoutesBySession = new Map(networkRoutesBySession);
             networkRoutesBySession.delete(replacedSessionStateKey ?? replacedManagedSessionName);
             sessionPageState.clearSession(replacedSessionStateKey ?? replacedManagedSessionName);
-            const replacedCloseError = await closeManagedSession({ cwd: priorManagedSessionCwd, namespace: priorManagedSessionNamespace, restoreState: state.managedSessionRestoreState, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
-            if (!replacedCloseError)
-                state.closedManagedSessionNames.add(replacedSessionStateKey ?? replacedManagedSessionName);
+            const replacedSessionKey = replacedSessionStateKey ?? replacedManagedSessionName;
+            const replacedCloseError = await closeManagedSession({ cwd: priorManagedSessionCwd, namespace: priorManagedSessionNamespace, preserveAttachedBrowserSession: state.attachedSessionKeys.has(replacedSessionKey), restoreState: state.managedSessionRestoreState, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+            if (!replacedCloseError) {
+                state.attachedSessionKeys.delete(replacedSessionKey);
+                state.closedManagedSessionNames.add(replacedSessionKey);
+            }
         }
         let electronLaunchRecord;
         let electronFailedConnectCleanup = prepared.electronFailedConnectCleanup;
@@ -431,7 +434,7 @@ export async function processBrowserOutput(input) {
                 if (electronHandoff.error) {
                     succeeded = false;
                     presentationEnvelope = { error: electronHandoff.error, success: false };
-                    const closeError = await closeManagedSession({ cwd, namespace: prepared.executionPlan.namespace, policyLock: prepared.managedSessionPolicyLock, restoreState: state.managedSessionRestoreState, sessionName: electronSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+                    const closeError = await closeManagedSession({ cwd, namespace: prepared.executionPlan.namespace, policyLock: prepared.managedSessionPolicyLock, preserveAttachedBrowserSession: input.preserveAttachedBrowserSession, restoreState: state.managedSessionRestoreState, sessionName: electronSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
                     electronFailedConnectCleanup = await cleanupElectronLaunchResources({ child: prepared.electronLaunch.child, record: electronLaunchRecord, timeoutMs: implicitSessionCloseTimeoutMs });
                     electronLaunchRecord = electronFailedConnectCleanup.record;
                     if (electronFailedConnectCleanup.partial) {

package/dist/extensions/agent-browser/lib/orchestration/electron-host/index.js

@@ -9,6 +9,7 @@ import { boundElectronProbeString } from "../../electron/text.js";
 import { buildOwnedManagedSessionRestoreContext, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { getManagedSessionStateAccessValidationError } from "../../managed-session-state-policy.js";
 import { isRecord } from "../../parsing.js";
+import { withAttachedBrowserSessionContext } from "../../process.js";
 import { buildAgentBrowserNextActions, buildAgentBrowserResultCategoryDetails } from "../../results.js";
 import { appendUniqueAgentBrowserNextActions } from "../../results/next-actions.js";
 import { extractRefSnapshotFromData, getSessionPageStateKey, isAboutBlankUrl, normalizeSessionTabTarget } from "../../session-page-state.js";
@@ -597,7 +598,7 @@ export async function cleanupTrackedElectronHostLaunches(options) {
     const results = [];
     for (const record of options.records) {
         const managedSessionCloseError = record.sessionName
-            ? await closeManagedSession({ cwd: options.cwd, restoreState: options.managedSessionRestoreState, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
+            ? await closeManagedSession({ cwd: options.cwd, preserveAttachedBrowserSession: options.attachedSessionKeys.has(getSessionPageStateKey(record.sessionName) ?? record.sessionName), restoreState: options.managedSessionRestoreState, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
             : undefined;
         const managedSessionStep = record.sessionName
             ? managedSessionCloseError
@@ -640,7 +641,13 @@ export async function cleanupActiveElectronHostLaunches(options) {
         : [];
 }
 export async function handleElectronHostInput(options) {
-    const { compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, managedSessionNamespace, managedSessionRestoreState, redactedCompiledElectron, sessionPageState, signal, } = options;
+    const currentSessionKey = getSessionPageStateKey(options.managedSessionName, options.managedSessionNamespace) ?? options.managedSessionName;
+    const preserveAttachedBrowserSession = options.attachedSessionKeys.has(currentSessionKey)
+        || [...options.electronLaunchRecords.values()].some((record) => record.sessionName !== undefined && options.attachedSessionKeys.has(getSessionPageStateKey(record.sessionName) ?? record.sessionName));
+    return await withAttachedBrowserSessionContext(preserveAttachedBrowserSession, () => handleElectronHostInputInContext(options));
+}
+async function handleElectronHostInputInContext(options) {
+    const { attachedSessionKeys, compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, managedSessionNamespace, managedSessionRestoreState, redactedCompiledElectron, sessionPageState, signal, } = options;
     if (compiledElectron?.action === "list") {
         try {
             const discovery = await discoverElectronApps({ maxResults: compiledElectron.maxResults, query: compiledElectron.query });
@@ -794,7 +801,7 @@ export async function handleElectronHostInput(options) {
         const selection = selectElectronRecords(compiledElectron, electronLaunchRecords);
         if (selection.error)
             return buildElectronHostFailureResult({ compiledElectron: redactedCompiledElectron ?? compiledElectron, errorText: selection.error, failureCategory: "validation-error" });
-        const cleanupResults = await cleanupTrackedElectronHostLaunches({ cwd, electronChildProcesses, electronLaunchRecords, managedSessionRestoreState, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
+        const cleanupResults = await cleanupTrackedElectronHostLaunches({ attachedSessionKeys, cwd, electronChildProcesses, electronLaunchRecords, managedSessionRestoreState, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
         return buildElectronCleanupResult(redactedCompiledElectron ?? compiledElectron, cleanupResults);
     }
     return undefined;

package/dist/extensions/agent-browser/lib/playbook.js

@@ -37,6 +37,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.",
     `When using launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}), put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.`,
     "Caller-owned explicit sessions are serialized per effective canonical namespace/session inside this extension while live URL checks, semantic-action snapshots, and the requested command run. For raw batches whose later content step depends on navigation, use exact batch --bail or split the calls; unsafe continue-after-navigation-failure shapes are rejected before the batch runs.",
+    "After a successful `connect`, `--cdp`, or enabled `--auto-connect` call, verify with get url and keep using the resulting session without repeating the attach flag. The wrapper remembers that attachment across active-branch reload/resume, omits local-launch-only `--args` / `--allow-file-access` defaults from follow-up and cleanup subprocesses so upstream keeps the existing CDP connection, and live-checks the URL before later page reads/interactions because an attached browser can drift externally; a successful close clears the marker. First-use attach plus content calls are blocked until the URL is verified.",
     `If you already used the implicit session and now need launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}), retry with top-level sessionMode set to fresh or pass an explicit --session for the new launch; never pass --session-mode inside args. After a successful unnamed fresh launch, later auto calls follow that new session.`,
     "For WebGPU pages, use args [\"--webgpu\", \"open\", \"<url>\"] on a fresh local browser launch; use doctor --webgpu (or --headed on Linux/Windows capture paths) to prove rendering before trusting a non-black screenshot. WebGPU cannot be combined with --cdp, --auto-connect, or provider launches unless --webgpu false overrides an enabled config/environment default.",
     "For --allowed-domains, use a fresh local Chrome context. Upstream rejects CDP/auto-connect, profiles, restore/state replay, direct-page providers, iOS/Safari, and startup/profile Chrome args because they cannot guarantee containment; Chromium also disables RTCPeerConnection while the allowlist is active.",

package/dist/extensions/agent-browser/lib/process.js

@@ -5,6 +5,7 @@
  * Usage: Called by the extension tool after argument validation and session planning are complete.
  * Invariants/Assumptions: The binary name is always `agent-browser`; Windows routes through PowerShell to invoke npm launchers with escaped argv; callers handle semantic success/error interpretation.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn } from "node:child_process";
 import { lstat, mkdir, readdir } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
@@ -32,6 +33,10 @@ const DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS = 35_000;
 /** Grace period after `exit` before resolving when `close` is delayed by inherited stdio handles. */
 const EXIT_STDIO_GRACE_MS = 100;
 const WINDOWS_AGENT_BROWSER_MISSING_MARKER = "PI_AGENT_BROWSER_COMMAND_NOT_FOUND:agent-browser.cmd";
+const attachedBrowserSessionContext = new AsyncLocalStorage();
+export function withAttachedBrowserSessionContext(preserve, run) {
+    return attachedBrowserSessionContext.run(preserve || attachedBrowserSessionContext.getStore() === true, run);
+}
 function appendTail(text, addition, maxChars) {
     const combined = text + addition;
     return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
@@ -87,7 +92,7 @@ export function reorderWindowsLeadingGlobalArgs(args) {
     }
     return args;
 }
-export function pinAgentBrowserFileAccessDisabled(args, wrapperCompatibilityUserAgent) {
+export function pinAgentBrowserFileAccessDisabled(args, wrapperCompatibilityUserAgent, preserveAttachedBrowserSession = false) {
     const filtered = [];
     for (let index = 0; index < args.length; index += 1) {
         const token = args[index];
@@ -100,6 +105,9 @@ export function pinAgentBrowserFileAccessDisabled(args, wrapperCompatibilityUser
         }
         filtered.push(token);
     }
+    // These are launch-only controls. Sending them on an attached-session follow-up makes upstream replace the CDP connection with a local browser.
+    if (preserveAttachedBrowserSession)
+        return filtered;
     // Upstream's flag overrides only the active CDP target; the Chrome arg covers new tabs. Its --args parser splits commas/newlines.
     const browserArgs = wrapperCompatibilityUserAgent
         ? `--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}`
@@ -333,6 +341,7 @@ function getManagedPreSpawnPolicyError(options, effectiveEnv, allowManagedSessio
 }
 export async function runAgentBrowserProcess(options) {
     const { allowManagedSessionTarget, cwd, env, managedSessionRestoreState, managedStateCurrentPageUrl, managedStatePageUrlUnknown, signal, stdin, trustedFirstBatchTabSelection } = options;
+    const preserveAttachedBrowserSession = options.preserveAttachedBrowserSession === true || attachedBrowserSessionContext.getStore() === true;
     const ownedManagedSession = options.ownedManagedSession === true || isOwnedManagedSessionTarget(options.args);
     const args = canonicalizeOwnedManagedSessionCloseArgs({
         args: options.args,
@@ -390,6 +399,7 @@ export async function runAgentBrowserProcess(options) {
         ...getManagedSessionRestoreProtectedEnv(managedSessionRestoreOptions, managedSessionRestoreEnv),
         ...getOwnedManagedSessionNamespaceEnv(managedSessionRestoreOptions),
         ...ownedManagedSessionCompatibilityEnv,
+        AGENT_BROWSER_ALLOW_FILE_ACCESS: undefined,
         [AGENT_BROWSER_ARGS_ENV]: undefined,
     };
     const explicitSocketDir = processOverrides[AGENT_BROWSER_SOCKET_DIR_ENV];
@@ -524,7 +534,7 @@ export async function runAgentBrowserProcess(options) {
             resolve({ aborted: false, agentBrowserStarted: false, exitCode: 1, spawnError: new Error(spawnPolicyError), stderr: "", stdout: "", timedOut: false });
             return;
         }
-        const spawnCommand = buildAgentBrowserSpawnCommand(pinAgentBrowserFileAccessDisabled(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT));
+        const spawnCommand = buildAgentBrowserSpawnCommand(pinAgentBrowserFileAccessDisabled(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession));
         const child = spawn(spawnCommand.command, spawnCommand.args, {
             cwd,
             env: childEnv,

package/docs/ARCHITECTURE.md

@@ -145,6 +145,7 @@ Practical policy:
 - keep explicit screenshots, downloads, PDFs, traces, HAR captures, and recordings written to caller-chosen paths on disk after a successful upstream close command (`close`, `quit`, or `exit`); before artifact-producing commands run, create missing parent directories for requested host paths, and for simple loopback HTML anchor downloads with resolvable HTTP(S) hrefs the wrapper may save directly to the requested path before upstream fallback. When the bounded `details.artifactManifest` has entries, successful close commands also surface `details.artifactCleanup` and a compact `Artifact lifecycle` note pointing to structured explicit paths so operators remove files with normal host tools—the native tool does not delete arbitrary user paths (`extensions/agent-browser/lib/orchestration/browser-run/diagnostics.ts`, `getArtifactCleanupGuidance`); contract in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), checklist `RQ-0079` in [`SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md)
 - reconstruct the current branch-visible extension-managed session, page-scoped refs, newest-revision aggregate artifact manifest, and Electron launch records from the active transcript branch on `session_start` and `session_tree` so later default calls keep following the active managed browser after resume/reload or branch switching; restore also honors successful explicit `--session <wrapper-owned> close` rows and `electron.cleanup` managed-session steps so closed wrapper-owned sessions are not resurrected
 - keep process-owned cleanup registries for extension-managed sessions and wrapper-launched Electron records separate from the current branch-visible view; `session_tree` restore and wrapper-owned browser commands are serialized with managed-session work, while caller-owned explicit-session commands are serialized by process-local queues keyed to effective canonical namespace/session across prepare helpers (explicit namespace argv overrides inherited `AGENT_BROWSER_NAMESPACE`, including an explicit empty default) and main execution. macOS and Windows additionally normalize and case-fold namespace and session components to match case-insensitive daemon identity. Different caller-owned identities remain concurrent, nested helpers never re-enter the outer queue, policy/route/artifact deltas merge across unrelated managed-state commits, and a separate branch-restore generation guard prevents stale completions from overwriting newer branch-visible state; aggregate artifact results use monotonic revisions so transcript replay cannot lose a concurrently completed entry. Branch switches still must not drop resources the current Pi process owns and must keep fresh-session allocation monotonic
+- record successful `connect`, `--cdp`, enabled `--auto-connect`, environment-configured CDP/auto-connect, and wrapper Electron attachment identities in branch-visible state, then run their main commands, helper probes, and cleanup inside an attached-browser process context that omits wrapper launch-only `--args` / `--allow-file-access` defaults. Re-sending those flags makes upstream choose local launch instead of its existing CDP connection and can trigger remote-debugging permission on every call. Block first-use attachment/content combinations until URL verification, and apply the existing live `get url` gate before every later content-bearing read or interaction because attached targets can drift outside Pi. Every child clears `AGENT_BROWSER_ALLOW_FILE_ACCESS`, including attached calls that omit the canonical launch flags. Successful close removes the marker; existing config, environment, URL, and protected-path checks still apply
 - when a successful close targets the current extension-managed session, including an explicit `--session <current> close` or an `electron.cleanup` managed-session step, clear page/ref state, mark that session inactive, untrack cleanup ownership, and rotate the next default auto call to a fresh wrapper-generated session name rather than reusing the closed name
 - on non-quit shutdown such as `/reload`, close off-branch owned managed sessions and off-branch owned Electron launches before clearing process-local ownership, but preserve the current branch-visible active managed session and Electron launch plus that launch's isolated `userDataDir` so reload continuity still works from the active transcript branch
 - expose still-owned off-branch Electron launch records to `electron.status { launchId }`, `electron.status { all: true }`, `electron.probe { launchId }`, and `electron.cleanup`, while leaving default `electron.probe` scoped to the current managed session

package/docs/COMMAND_REFERENCE.md

@@ -903,11 +903,11 @@ Browser default config is conservative: it adds agent guidance for signed-in/acc
 - `--proxy <server>`: proxy server URL. Environments: `AGENT_BROWSER_PROXY`, `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`.
 - `--proxy-bypass <hosts>`: proxy bypass hosts. Environments: `AGENT_BROWSER_PROXY_BYPASS`, `NO_PROXY`.
 - `--ignore-https-errors`: ignore HTTPS certificate errors. Environment: `AGENT_BROWSER_IGNORE_HTTPS_ERRORS`.
-- `--allow-file-access`: upstream capability, but enabled argv/`AGENT_BROWSER_ALLOW_FILE_ACCESS` forms and file-access-enabling `--args` / `AGENT_BROWSER_ARGS` Chrome switches are rejected by this native wrapper. Every spawn adds canonical `--args "" --allow-file-access false` defaults so project/user config cannot re-enable file access; an explicit validated safe CLI `--args` value remains usable. Every spawn removes all caller occurrences before adding one canonical separated `--allow-file-access false`, so unsupported equals forms cannot preserve an earlier enabled flag and config cannot re-enable local filesystem access. Unknown top-level or batch tab/attachment/script/state-load transitions remain blocked for page inspection until `get url` or explicit safe navigation establishes the target. `tab list` and non-content `tab <id>` selection remain available while unknown, but selection stays unverified until `get url`; post-transition summaries (including after arbitrary `eval`) read the live URL before title and stop if the target is a local file page.
+- `--allow-file-access`: upstream capability, but enabled argv/`AGENT_BROWSER_ALLOW_FILE_ACCESS` forms and file-access-enabling `--args` / `AGENT_BROWSER_ARGS` Chrome switches are rejected by this native wrapper. Local-browser spawns add canonical `--args "" --allow-file-access false` defaults so project/user config cannot re-enable file access; an explicit validated safe CLI `--args` value remains usable. Attached-session follow-ups omit those launch-only defaults. Every spawn removes all caller occurrences before any canonical separated `--allow-file-access false` is added, so unsupported equals forms cannot preserve an earlier enabled flag and config cannot re-enable local filesystem access. Unknown top-level or batch tab/attachment/script/state-load transitions remain blocked for page inspection until `get url` or explicit safe navigation establishes the target. `tab list` and non-content `tab <id>` selection remain available while unknown, but selection stays unverified until `get url`; post-transition summaries (including after arbitrary `eval`) read the live URL before title and stop if the target is a local file page.
 - `--hide-scrollbars <bool>`: explicitly show or hide native scrollbars in headless Chromium screenshots.
 - `--headed`: ask upstream to show the browser window. Environment: `AGENT_BROWSER_HEADED`. Use it on the first launch, normally with `sessionMode: "fresh"` when changing an existing managed session; verify visibility with screenshot/tab evidence because the wrapper cannot yet prove the OS window is visible to the user.
 - `--webgpu`: enable upstream's platform-specific WebGPU launch preset. Environment: `AGENT_BROWSER_WEBGPU`; config: `"webgpu": true`. Use it on a fresh local launch. It is incompatible while enabled with `--cdp`, `--auto-connect`, and provider launches. `AGENT_BROWSER_NO_XVFB=1` disables upstream's automatic Xvfb for displayless headed Linux sessions.
-- `--cdp <port>`: connect through Chrome DevTools Protocol.
+- `--cdp <port>`: connect through Chrome DevTools Protocol. Use it, `--auto-connect`, or `connect <port|url>` once on a named/fresh session, verify with `get url`, then reuse that session without repeating the attach flag. After a successful attachment the wrapper omits local-launch-only `--args` / `--allow-file-access` defaults on follow-ups and cleanup so upstream keeps one CDP connection instead of requesting Chrome permission again. Content-bearing first use is blocked until URL verification; later page reads/interactions live-check the URL because the attached browser can drift externally. `close` clears attachment state.
 - `--color-scheme <scheme>`: `dark`, `light`, or `no-preference`. Environment: `AGENT_BROWSER_COLOR_SCHEME`.
 - `--download-path <path>`: default browser download directory. Environment: `AGENT_BROWSER_DOWNLOAD_PATH`.
 - `--engine <name>`: browser engine, `chrome` by default or `lightpanda`. Environment: `AGENT_BROWSER_ENGINE`.

package/docs/SUPPORT_MATRIX.md

@@ -55,6 +55,7 @@ Current summary:
 | RQ-0137 | Upstream `agent-browser 0.32.4` rebaseline adds HAR `--content` body modes, the `derive-client` skill, and fixed `find role` implicit-ARIA/name matching with locator-detail misses; wrapper classifier/argv/docs cover those surfaces. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0330-rebaseline) |
 | RQ-0138 | Upstream `agent-browser 0.33.0` rebaseline adds `a11y` axe-core audits and discarded-tab revival on tab switch; wrapper documents/presents `a11y` and samples the new help surface. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0330-rebaseline) |
 | RQ-0139 | Upstream `agent-browser 0.33.2` rebaseline documents daemon idle timeout, stream quality/size envs, and tab-recovery fields; wrapper enables Git-checkout-generation-stable managed-session restore for SSO stickiness with canonical namespace identity, replayable pinned managed/Electron probes, nested attachment isolation, check-to-spawn config pinning with native POSIX/Windows stale-root identity, fail-closed restore storage, JSON close-state capture, and lockless convergent ownership-proven snapshot retention plus immutable ticket-claim cross-process daemon-policy locking with mandatory per-winner daemon inspection, a pre-update v2 bridge, absolute POSIX process probes, PID/start-identity dead-claim/artifact recovery, final post-setup spawn revalidation, managed restore-capability redaction/access guards, same-process restore-disabled daemon provenance plus inactive-daemon null-policy restart, owned-policy Electron probes, abort-safe Electron launch, independent daemon-inspection timeout, case-insensitive reserved managed live-session names, all-failed Electron probe classification, fail-closed POSIX socket ancestry/entry validation, pinned-disabled file access (including raw Chrome args/config) plus protected local CLI/environment input/output paths, authoritative persisted unverified/failed page transitions and URL-first Electron handoff cleanup, and local state-file navigation, same-checkout-lineage generation expiry, malformed-output discard, a per-key 256-record churn bound, caller-owned explicit-session live URL gating before content access, process-local canonical per-session serialization through semantic snapshots and main execution, non-bail batch failure-path analysis that prevents prior-page content exposure, semantic live gating before snapshot resolution, Windows drive-relative protected-path detection, nested batch rejection, and upstream ASCII-space batch-tokenizer parity. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0332-rebaseline), [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) |
+| RQ-0140 | Successful CDP/auto-connect and Electron sessions preserve one attached browser across native-tool follow-ups and cleanup by omitting wrapper local-launch defaults, with environment support, branch replay, first-use content blocking, live URL gates against external drift, and close cleanup. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.extension-passthrough-validation.test.ts` |
 
 ## Verification evidence
 

package/docs/TOOL_CONTRACT.md

@@ -152,6 +152,7 @@ The extension always plans normal browser commands with `--json` prepended in `e
 - Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.
 - When using launch-scoped flags (--auto-connect, --allowed-domains, --namespace, --cdp, --enable, --executable-path, --webgpu, --init-script, --idle-timeout, --device, --profile, --provider, -p, --session-name, --restore, --restore-save, --restore-check-url, --restore-check-text, --restore-check-fn, --state), put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.
 - Caller-owned explicit sessions are serialized per effective canonical namespace/session inside this extension while live URL checks, semantic-action snapshots, and the requested command run. For raw batches whose later content step depends on navigation, use exact batch --bail or split the calls; unsafe continue-after-navigation-failure shapes are rejected before the batch runs.
+- After a successful `connect`, `--cdp`, or enabled `--auto-connect` call, verify with get url and keep using the resulting session without repeating the attach flag. The wrapper remembers that attachment across active-branch reload/resume, omits local-launch-only `--args` / `--allow-file-access` defaults from follow-up and cleanup subprocesses so upstream keeps the existing CDP connection, and live-checks the URL before later page reads/interactions because an attached browser can drift externally; a successful close clears the marker. First-use attach plus content calls are blocked until the URL is verified.
 - If you already used the implicit session and now need launch-scoped flags (--auto-connect, --allowed-domains, --namespace, --cdp, --enable, --executable-path, --webgpu, --init-script, --idle-timeout, --device, --profile, --provider, -p, --session-name, --restore, --restore-save, --restore-check-url, --restore-check-text, --restore-check-fn, --state), retry with top-level sessionMode set to fresh or pass an explicit --session for the new launch; never pass --session-mode inside args. After a successful unnamed fresh launch, later auto calls follow that new session.
 - For WebGPU pages, use args ["--webgpu", "open", "<url>"] on a fresh local browser launch; use doctor --webgpu (or --headed on Linux/Windows capture paths) to prove rendering before trusting a non-black screenshot. WebGPU cannot be combined with --cdp, --auto-connect, or provider launches unless --webgpu false overrides an enabled config/environment default.
 - For --allowed-domains, use a fresh local Chrome context. Upstream rejects CDP/auto-connect, profiles, restore/state replay, direct-page providers, iOS/Safari, and startup/profile Chrome args because they cannot guarantee containment; Chromium also disables RTCPeerConnection while the allowlist is active.
@@ -785,6 +786,7 @@ Implementation and precedence:
 - The main tool implementation merges these fields into Pi-facing `details` from `extensions/agent-browser/index.ts` and from `extensions/agent-browser/lib/results/presentation.ts` for presentation-time failures.
 
 Additional structured fields can appear when relevant:
+- `attachedBrowserSession: true` on successful calls that establish or reuse a wrapper-tracked CDP/auto-connect/Electron attachment, and on a failed fresh attachment only when `managedSessionOutcome.activeAfter` proves its daemon remained active for cleanup. The marker restores attachment continuity from the active transcript branch, including that active-after-failure case; successful close/cleanup removes it. It does not relax config, environment, protected-path, or live-URL validation.
 - `sessionTabTargetUnknown: true` after a spawned `connect`, `state load`, history navigation, or tab-selection/close call changes the active page without a trustworthy observed target. The marker is persisted and restored across branch/reload replay, clears stale refs and tab pinning, and blocks page inspection until `get url` or an explicit safe navigation observes a target; `tab list` and close remain available.
 - `compiledSemanticAction` when the call used `semanticAction` and the result includes the unified `details` merge: `{ action, locator, args }` for `find` actions or `{ action: "select", selector, values, args }` for `select`, with the same redaction rules as `args` / `effectiveArgs`; omitted for plain `args`/`job` calls and omitted on some early error returns that omit this field (see the `semanticAction` section above)
 - `compiledJob` when the call used `job` or the job-backed `qa` preset: by default `{ args: ["batch", "--bail"], failFast: true, stdin, steps: [{ action, args }] }`; with `failFast: false`, `{ args: ["batch"], failFast: false, stdin, steps: [{ action, args }] }`. Step args are redacted the same way as other invocation details. Semantic `job` click/fill steps appear here as their compiled upstream `find … click|fill …` argv, not as the input object.
@@ -879,12 +881,12 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - reconstruct the current branch-visible extension-managed session, latest page-scoped refs, newest-revision aggregate `artifactManifest`, and wrapper-tracked Electron launch records from the active transcript branch on `session_start` and Pi `session_tree` so later default calls keep following the active managed browser and can continue reporting artifact retention state; successful explicit wrapper-owned close rows and `electron.cleanup` managed-session steps are restore-visible close events
 - keep runtime cleanup ownership separate from branch-visible state: `session_tree` restore and wrapper-owned browser commands are serialized with managed-session work; caller-owned explicit-session commands use separate process-local queues keyed by effective canonical namespace/session (explicit namespace argv wins over inherited `AGENT_BROWSER_NAMESPACE`, including an explicit empty default), so the live URL probe, preparation helpers, semantic snapshot, main command, and state commit for one identity cannot interleave while different identities remain concurrent. Namespace and session identity components are additionally Unicode-normalized and case-folded on macOS and Windows to match their case-insensitive daemon paths. Only the outer tool execution acquires that key; nested helpers run under it without re-entry. Policy, route, and artifact deltas survive unrelated managed-state commits, while a separate branch-restore generation guard prevents stale completions from overwriting a newer branch. Concurrent artifact-producing results carry a monotonic aggregate manifest revision so transcript replay selects the complete bounded manifest rather than whichever call happened to occupy the last row. Extension-managed sessions and wrapper-launched Electron records owned by the current process remain eligible for quit/cleanup, and fresh-session allocation stays monotonic across branch restores, including auto rows and close rows that reference wrapper-generated fresh names
 - when a close command or `electron.cleanup` successfully closes the current wrapper-managed session, clear live page/ref state, reserve the next generated fresh-session ordinal, and rotate the next default auto call to a fresh wrapper-generated session name rather than reusing the closed name
-- when `/reload` shuts down an extension instance, close off-branch owned managed sessions and off-branch owned Electron launches before clearing process-local ownership; preserve only the current branch-visible active managed session and active Electron launch plus its isolated `userDataDir` for reload continuity, and also persistently protect `userDataDir` paths when partial cleanup intentionally skips or fails profile removal so later temp cleanup, process exit, and stale temp-root pruning after restart do not violate Electron cleanup's safety decision; rebuild active branch state from the active branch on the next `session_start`
+- when `/reload` shuts down an extension instance, close off-branch owned managed sessions and off-branch owned Electron launches before clearing process-local ownership; retain attached-browser context for those still-owned off-branch resources so cleanup cannot resend local-launch defaults. Preserve only the current branch-visible active managed session and active Electron launch plus its isolated `userDataDir` for reload continuity, and also persistently protect `userDataDir` paths when partial cleanup intentionally skips or fails profile removal so later temp cleanup, process exit, and stale temp-root pruning after restart do not violate Electron cleanup's safety decision; rebuild active branch state from the active branch on the next `session_start`
 - when an unnamed `sessionMode: "fresh"` launch succeeds, make it the new extension-managed session so later default calls keep using it
 - when an unnamed `sessionMode: "fresh"` launch fails or times out, preserve the previous managed session when one was active or report the attempted fresh session as abandoned when no managed session was active (`details.managedSessionOutcome`; visible `Managed session outcome: …` only when the final tool call used `sessionMode: "fresh"` and failed—see `#details`)
 - if that unnamed fresh launch replaced an already-active managed session, best-effort close the old managed session after the switch succeeds
-- treat explicit caller-provided non-managed `--session` choices outside the reserved `piab-*` prefix as user-managed; those names alone isolate a live browser session but are not a persisted tab/auth restore mechanism after a close command (`close`, `quit`, or `exit`), so use `--session <id> --restore`, `--profile`, or `--state` when persisted auth/tab state is required. Wrapper-owned managed sessions (the current/generated identity or an exact namespace/session in this extension instance's ownership records; foreign `piab-*` targets are rejected) set a Git-checkout-generation-stable `AGENT_BROWSER_RESTORE` env key automatically (disable with `PI_AGENT_BROWSER_MANAGED_SESSION_RESTORE=0`) so SSO cookies/localStorage/sessionStorage can survive idle shutdown and later chats in the same checkout generation without a manual `state save` flow. Any project/user/explicit upstream config discovered while planning blocks browser-backed native calls without parsing caller-selected content; accepted browser-backed subprocesses, including wrapper-owned closes, pin a process-private empty config (`0400` on POSIX) in the marked secure-temp lifecycle so later config creation cannot change the receiving browser. Sessionless local/setup commands retain upstream config behavior, and this restriction is separate from the package's Pi-scoped config. Raw batch argv, batch stdin containing nested `connect`/`batch`, and browser mutation flags/env such as extensions, init scripts, raw launch args, custom user agents/executables, proxies, plugins, WebGPU, profiles, parent env namespaces, CDP, providers, state, and containment also disable automatic managed restore. Wrapper-owned close canonicalizes upstream argv to the known namespace/session, discards caller config/restore globals, and preserves the live daemon's existing restore key rather than injecting one derived from a replacement checkout. A failed fresh call probes its exact daemon identity and remains owned when that daemon is live or uninspectable, so shutdown still closes it. After a wrapper-owned close succeeds, the wrapper persists the returned state path as an atomic record in a lockless convergent per-key ownership directory (`0700`, with `0600` records, on POSIX), retains the two newest proven snapshots for its exact restore key across Pi restarts, self-heals malformed regular records, removes additional proven snapshots older than 30 days, expires stale ownership-proven snapshots and empty manifests from other restore-key generations after 30 days only when a private lineage record proves the same canonical checkout path, and caps young close churn at 256 records per restore key without running namespace-wide `state clean`; unrecorded matching files and the current checkout key are untouched. Automatic restore requires a durable Git checkout generation and an absolute home root. The generation UUID lives in the checkout's Git admin directory and is combined with checkout-root plus Git-admin filesystem identity, so it follows a rename, changes on checkout replacement/copy, and is not migrated from cwd-only keys. On POSIX the wrapper canonicalizes and pins `HOME`, requires trusted non-writable owner ancestry plus stable device/inode/birth-time metadata for checkout and Git-admin directories, enforces owner-only mode `0700` without silently repairing insecure existing directories, and rejects symlinks/non-directories along `~/.agent-browser[/namespaces/<canonical>/state]/sessions` and its `.tmp` write area; Windows requires a valid 64-character hex `AGENT_BROWSER_ENCRYPTION_KEY`. Namespace identity uses upstream's lowercase sanitized form, and wrapper-owned subprocesses pin it (including an explicit empty default) so parent environment cannot redirect helpers or close. `electron.status` target reads and `electron.probe` hold the managed daemon-policy lock and apply the owned restore context to each underlying title/URL/focus/tab/snapshot read. When a managed session was launched with restore suppressed by an incompatible path or the explicit opt-out, `details.managedSessionRestoreDisabled: true` means later bare follow-ups do not inject wrapper restore. Same-process `session_tree` transitions retain the process-owned daemon-policy proof; reload, restart, and `/resume` restore the sticky flag but not that proof, so a still-live restore-disabled daemon fails closed until it is closed or a fresh identity is used. If inspection proves the prior daemon inactive, the next owned no-restore spawn records a null daemon policy so later follow-ups can reuse the replacement. A user-private immutable ticket-claim lock serializes policy inspection through the receiving same-identity spawn and bridges the pre-update v2 lock path; every lock winner re-inspects the live daemon with a fixed bounded timeout independent of shorter caller watchdog overrides, and abandoned v2 locks fail closed for manual repair. Before incompatible reuse, the wrapper inspects the actual same-identity daemon and fails closed when it retains any restore key, cannot be inspected, or reports restore-disabled policy without current-process provenance, including live daemons absent from transcript state and explicit restore-key sessions; close it first, retry without an explicit session using `sessionMode: "fresh"`, or use a distinct explicit session. Managed restore keys and key-bearing paths are redacted from visible text, structured details, JSON-mode output, and persisted tool rows. Browser access to `.agent-browser` local storage is rejected before spawn through command-specific input/output operands (including dash-prefixed values), every path-bearing upstream environment mirror (state/profile/config, executable/extension/init-script, action-policy, artifact, skills, and socket paths), encoded, nested-file-scheme, Windows-aliased, or symlinked paths (including nonexistent descendants of symlinked directories), protected top-level `outputPath`, content-returning local-URL calls, all follow-ups on local file pages, and persisted unverified top-level or batch tab/attachment/script/state-load transitions, plus raw batch command strings recursively tokenized on literal ASCII spaces exactly like upstream. Electron probes and later capture from a wrapper-tracked protected target use the same guard. Raw artifact destinations use the same command parser as preparation and are checked before it creates parent directories. Enabled `--allow-file-access` argv/env and file-access-enabling or protected-path raw Chrome values are rejected. Every subprocess clears `AGENT_BROWSER_ARGS`, removes caller file-access occurrences, and adds canonical `--args "" --allow-file-access false` defaults so unsupported equals forms and project/user config cannot re-enable it; an explicit validated safe CLI `--args` value may follow and override the empty raw-args default. Post-transition summaries, including forced live probes after arbitrary `eval`, verify URL before title and fail implicit transitions to local file pages. Failed or unexecuted navigation attempts remain unverified, and stale concurrent completions serialize only the authoritative page state; transcript replay gives `sessionTabTargetUnknown` precedence over any inconsistent stale target/ref fields. `get url`, `tab list`, non-content `tab <id>` selection, safe explicit navigation away, and session/tab close remain available; tab selection stays unverified until `get url` succeeds. `session list` and `state list` omit wrapper-managed rows; the `piab-*` live-session reservation is case-insensitive, and foreign managed live-session and restore/state references, broad state clearing/cleaning, and managed save/rename targets fail before spawn. Malformed oversized upstream output is discarded rather than persisted as a parse-failure spill. Checkout, storage, environment, managed-session ownership, and state-access policy is checked again after async config/socket setup immediately before spawn. POSIX socket storage is accepted only when the target is current-user-owned mode `0700`, its ancestry is trusted, and existing entries are current-user-owned regular files, sockets, or directories without symlinks; pre-existing unsafe modes are rejected rather than repaired. Identity and config globals use upstream's separated forms (`--session <name>`, `--namespace <name>`, `--config <path>`); the wrapper rejects leading identity equals forms that upstream 0.33.2 does not recognize, while equals-shaped tokens in command payload positions remain ordinary payload rather than silently selecting wrapper ownership or config. Native Windows command-first adaptation relocates only syntactically valid leading globals, rewrites valued `--restore <name>` as `--restore=<name>`, and leaves command-scoped or invalid leading input untouched. Optional global booleans also follow upstream's separated, last-occurrence-wins form: only exact lowercase `false` after the flag disables it, and an unsupported token such as `--auto-connect=false` does not override an earlier bare flag
-- before a content-bearing read or interaction against a caller-owned explicit session, run a session-scoped `get url` probe and apply the local-state boundary to that live target. Missing or stale transcript page state is not accepted as proof; a failed or non-URL probe blocks the requested content command. The process-local effective-namespace/session queue keeps that probe atomic with semantic snapshot resolution and the main command inside one extension instance; direct CLI calls and other Pi processes remain outside this guarantee. Non-bail batch validation retains every possible pre-transition page state up to a fixed bound, so later content is rejected when any failed transition could expose local or unverified content and branching beyond that bound fails closed with exact `batch --bail` guidance; exact `batch --bail` or split calls remove that continuation path. Protected Windows paths include drive-relative forms such as `C:.agent-browser\\state\\...`. Nested `batch` steps are rejected, while raw batch command strings mirror upstream's ASCII-space tokenizer, including its single/double-quote and backslash handling, without splitting on other Unicode whitespace.
+- treat explicit caller-provided non-managed `--session` choices outside the reserved `piab-*` prefix as user-managed; those names alone isolate a live browser session but are not a persisted tab/auth restore mechanism after a close command (`close`, `quit`, or `exit`), so use `--session <id> --restore`, `--profile`, or `--state` when persisted auth/tab state is required. Wrapper-owned managed sessions (the current/generated identity or an exact namespace/session in this extension instance's ownership records; foreign `piab-*` targets are rejected) set a Git-checkout-generation-stable `AGENT_BROWSER_RESTORE` env key automatically (disable with `PI_AGENT_BROWSER_MANAGED_SESSION_RESTORE=0`) so SSO cookies/localStorage/sessionStorage can survive idle shutdown and later chats in the same checkout generation without a manual `state save` flow. Any project/user/explicit upstream config discovered while planning blocks browser-backed native calls without parsing caller-selected content; accepted browser-backed subprocesses, including wrapper-owned closes, pin a process-private empty config (`0400` on POSIX) in the marked secure-temp lifecycle so later config creation cannot change the receiving browser. Sessionless local/setup commands retain upstream config behavior, and this restriction is separate from the package's Pi-scoped config. Raw batch argv, batch stdin containing nested `connect`/`batch`, and browser mutation flags/env such as extensions, init scripts, raw launch args, custom user agents/executables, proxies, plugins, WebGPU, profiles, parent env namespaces, CDP, providers, state, and containment also disable automatic managed restore. Wrapper-owned close canonicalizes upstream argv to the known namespace/session, discards caller config/restore globals, and preserves the live daemon's existing restore key rather than injecting one derived from a replacement checkout. A failed fresh call probes its exact daemon identity and remains owned when that daemon is live or uninspectable, so shutdown still closes it. After a wrapper-owned close succeeds, the wrapper persists the returned state path as an atomic record in a lockless convergent per-key ownership directory (`0700`, with `0600` records, on POSIX), retains the two newest proven snapshots for its exact restore key across Pi restarts, self-heals malformed regular records, removes additional proven snapshots older than 30 days, expires stale ownership-proven snapshots and empty manifests from other restore-key generations after 30 days only when a private lineage record proves the same canonical checkout path, and caps young close churn at 256 records per restore key without running namespace-wide `state clean`; unrecorded matching files and the current checkout key are untouched. Automatic restore requires a durable Git checkout generation and an absolute home root. The generation UUID lives in the checkout's Git admin directory and is combined with checkout-root plus Git-admin filesystem identity, so it follows a rename, changes on checkout replacement/copy, and is not migrated from cwd-only keys. On POSIX the wrapper canonicalizes and pins `HOME`, requires trusted non-writable owner ancestry plus stable device/inode/birth-time metadata for checkout and Git-admin directories, enforces owner-only mode `0700` without silently repairing insecure existing directories, and rejects symlinks/non-directories along `~/.agent-browser[/namespaces/<canonical>/state]/sessions` and its `.tmp` write area; Windows requires a valid 64-character hex `AGENT_BROWSER_ENCRYPTION_KEY`. Namespace identity uses upstream's lowercase sanitized form, and wrapper-owned subprocesses pin it (including an explicit empty default) so parent environment cannot redirect helpers or close. `electron.status` target reads and `electron.probe` hold the managed daemon-policy lock and apply the owned restore context to each underlying title/URL/focus/tab/snapshot read. When a managed session was launched with restore suppressed by an incompatible path or the explicit opt-out, `details.managedSessionRestoreDisabled: true` means later bare follow-ups do not inject wrapper restore. Same-process `session_tree` transitions retain the process-owned daemon-policy proof; reload, restart, and `/resume` restore the sticky flag but not that proof, so a still-live restore-disabled daemon fails closed until it is closed or a fresh identity is used. If inspection proves the prior daemon inactive, the next owned no-restore spawn records a null daemon policy so later follow-ups can reuse the replacement. A user-private immutable ticket-claim lock serializes policy inspection through the receiving same-identity spawn and bridges the pre-update v2 lock path; every lock winner re-inspects the live daemon with a fixed bounded timeout independent of shorter caller watchdog overrides, and abandoned v2 locks fail closed for manual repair. Before incompatible reuse, the wrapper inspects the actual same-identity daemon and fails closed when it retains any restore key, cannot be inspected, or reports restore-disabled policy without current-process provenance, including live daemons absent from transcript state and explicit restore-key sessions; close it first, retry without an explicit session using `sessionMode: "fresh"`, or use a distinct explicit session. Managed restore keys and key-bearing paths are redacted from visible text, structured details, JSON-mode output, and persisted tool rows. Browser access to `.agent-browser` local storage is rejected before spawn through command-specific input/output operands (including dash-prefixed values), every path-bearing upstream environment mirror (state/profile/config, executable/extension/init-script, action-policy, artifact, skills, and socket paths), encoded, nested-file-scheme, Windows-aliased, or symlinked paths (including nonexistent descendants of symlinked directories), protected top-level `outputPath`, content-returning local-URL calls, all follow-ups on local file pages, and persisted unverified top-level or batch tab/attachment/script/state-load transitions, plus raw batch command strings recursively tokenized on literal ASCII spaces exactly like upstream. Electron probes and later capture from a wrapper-tracked protected target use the same guard. Raw artifact destinations use the same command parser as preparation and are checked before it creates parent directories. Enabled `--allow-file-access` argv/env and file-access-enabling or protected-path raw Chrome values are rejected. Every subprocess clears `AGENT_BROWSER_ARGS` and removes caller file-access occurrences. Local-browser spawns add canonical `--args "" --allow-file-access false` defaults so unsupported equals forms and project/user config cannot re-enable it, while attached-session follow-ups omit those launch-only defaults; an explicit validated safe CLI `--args` value may follow and override the empty raw-args default. Post-transition summaries, including forced live probes after arbitrary `eval`, verify URL before title and fail implicit transitions to local file pages. Failed or unexecuted navigation attempts remain unverified, and stale concurrent completions serialize only the authoritative page state; transcript replay gives `sessionTabTargetUnknown` precedence over any inconsistent stale target/ref fields. `get url`, `tab list`, non-content `tab <id>` selection, safe explicit navigation away, and session/tab close remain available; tab selection stays unverified until `get url` succeeds. `session list` and `state list` omit wrapper-managed rows; the `piab-*` live-session reservation is case-insensitive, and foreign managed live-session and restore/state references, broad state clearing/cleaning, and managed save/rename targets fail before spawn. Malformed oversized upstream output is discarded rather than persisted as a parse-failure spill. Checkout, storage, environment, managed-session ownership, and state-access policy is checked again after async config/socket setup immediately before spawn. POSIX socket storage is accepted only when the target is current-user-owned mode `0700`, its ancestry is trusted, and existing entries are current-user-owned regular files, sockets, or directories without symlinks; pre-existing unsafe modes are rejected rather than repaired. Identity and config globals use upstream's separated forms (`--session <name>`, `--namespace <name>`, `--config <path>`); the wrapper rejects leading identity equals forms that upstream 0.33.2 does not recognize, while equals-shaped tokens in command payload positions remain ordinary payload rather than silently selecting wrapper ownership or config. Native Windows command-first adaptation relocates only syntactically valid leading globals, rewrites valued `--restore <name>` as `--restore=<name>`, and leaves command-scoped or invalid leading input untouched. Optional global booleans also follow upstream's separated, last-occurrence-wins form: only exact lowercase `false` after the flag disables it, and an unsupported token such as `--auto-connect=false` does not override an earlier bare flag
+- before a content-bearing read or interaction against a caller-owned explicit session or any established attached browser, run a session-scoped `get url` probe and apply the local-state boundary to that live target. A first-use attach/content combination is blocked until the caller establishes the attachment with `connect`, `get url`, `tab list`, or safe navigation. Missing or stale transcript page state is not accepted as proof; a failed or non-URL probe blocks the requested content command. The process-local effective-namespace/session queue keeps that probe atomic with semantic snapshot resolution and the main command inside one extension instance; external attached-browser activity, direct CLI calls, and other Pi processes remain outside this guarantee. Non-bail batch validation retains every possible pre-transition page state up to a fixed bound, so later content is rejected when any failed transition could expose local or unverified content and branching beyond that bound fails closed with exact `batch --bail` guidance; exact `batch --bail` or split calls remove that continuation path. Protected Windows paths include drive-relative forms such as `C:.agent-browser\\state\\...`. Nested `batch` steps are rejected, while raw batch command strings mirror upstream's ASCII-space tokenizer, including its single/double-quote and backslash handling, without splitting on other Unicode whitespace.
 - pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.76",
+  "version": "0.2.77",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",