pi-agent-browser-native 0.6.12 → 0.6.13

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## Unreleased
+## 0.6.13 - 2026-09-14
+
+### Fixed
+
+- Suppress Chrome's extra startup window using stock `--no-startup-window`, preserving headless defaults and composing caller launch arguments. URL-less `open` now uses native lazy URL reads so active pages keep their browser, profile, and URL across direct, batch, and script calls. External engines and attachments remain unchanged.
+
+### Changed
+
+- Give ordinary browser calls a native session and restore key per root Pi session. Parent/descendant groups share one browser without a global queue or child-exit teardown. Scope named Chrome profile bootstrap to automatic roots; preserve explicit browsers, script, and Electron isolation.
+
+### Validation
+
+- Start managed-lifecycle release checks explicitly in fresh mode; retain root-session ownership without leaving test browsers open.
 
 ## 0.6.12 - 2026-09-13
 

package/README.md

@@ -317,6 +317,10 @@ Open a page and inspect it (first-call recipe: open → snapshot -i → interact
 
 Chromium launch switches belong in the value of `--args`, for example `{ "args": ["--args", "--no-sandbox", "open", "https://example.com"], "sessionMode": "fresh" }` when that switch is needed. A bare `--no-sandbox` in the command slot is an unknown command; in an `open` / `goto` / `navigate` option position, upstream ignores it. The wrapper diagnoses those forms without rejecting literal text, select values or paths in other commands. For batches, put `--args` in top-level `args` before `batch`, not inside a row.
 
+Local Chrome startup uses the stock binary's `--args --no-startup-window` capability to suppress Chrome's extra startup window. Headless remains the default. Caller launch arguments keep native CLI → environment → config precedence and follow this default; browsers started before this change with custom arguments may restart once when their native launch configuration changes. Ordinary follow-ups do not resend bootstrap settings. CDP, providers, Electron, and Lightpanda remain native-owned; no tabs are deleted or profiles edited by this behavior.
+
+`open` without a URL uses native `get url`: it launches when needed and otherwise preserves the current page. This also applies to effective batch rows and script calls. `details.args` preserves the request, while `effectiveArgs`, command, URL data, and lifecycle describe the actual native operation. Use `open about:blank` only when you intend to navigate there. Help/version requests remain unchanged.
+
 Watch a browser window during a demo, QA run, or user-completed login by adding upstream's global `--headed` flag on the first launch. Use `sessionMode: "fresh"` if a managed session may already exist, because headed/headless state is launch-scoped. A successful first/fresh local wrapper-managed headed launch, including a launch inside `batch`, returns `details.browserWindow = { mode: "headed", ownership: "wrapper-managed", sessionName, visibility: "unverified" }` and one visible handoff sentence; CDP, auto-connect, provider, and Electron attachments do not. This proves that the wrapper requested and upstream launched headed mode, not that the OS window is visible on the user's display; remote, container, or virtual-display setups can still hide it. After the user finishes in the window, continue with `sessionMode: "auto"`.
 
 ```json
@@ -608,33 +612,31 @@ After a successful unnamed fresh launch, later default `sessionMode: "auto"` cal
 
 ### Shared browser defaults
 
-To reuse one signed-in browser across Pi sessions, configure native `agent-browser` defaults in `~/.agent-browser/config.json`:
+Ordinary browser calls use one native named browser per **root Pi session**. A parent and its subagents share that browser; unrelated roots get different names and can browse concurrently. `pi-subagents` supplies `PI_SUBAGENT_ROOT_SESSION_ID` through its existing launch records, including detached runs, delegated forks, grandchildren, and revived children. Ordinary Pi new/fork/clone sessions get their own root identity; resuming the same root or changing its cwd keeps its browser name.
+
+Coordinate multi-call navigation within the group using existing subagent/intercom tools. Native commands are serialized by each browser daemon; wrapper helper queues are process-local. There is no global focus queue. Parent or child exit does not close the group browser. Native idle policy applies; explicitly close only your group's browser when the group is finished.
+
+To bootstrap new root browsers from an authenticated normal Chrome profile, set the existing **Pi package** config in `~/.pi/config/pi-agent-browser-native/config.json`:
 
 ```json
 {
-  "session": "shared-work",
-  "namespace": "",
-  "profile": "/absolute/path/to/persistent-browser-profile",
-  "headed": true
+  "browser": {
+    "defaultProfile": { "name": "Default", "policy": "always" },
+    "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+  }
 }
 ```
 
-Use a dedicated full profile directory path, not a copied Chrome profile name. Add native `executablePath` if needed. Ordinary `args`, `semanticAction`, `job`, `qa`, and lookup calls then select that same caller-owned browser without repeating flags. This is separate from the advisory Pi package `browser.defaultProfile` setting. Existing native project config, environment and per-call flags keep their precedence; `--config` or `AGENT_BROWSER_CONFIG` replaces user/project config discovery.
-
-Pi quit does not close a caller-owned shared browser or impose its implicit 15-minute idle timeout. Native idle policy applies, including its default headed-browser exemption; explicit `--idle-timeout` applies to every helper in that call too. Keep native idle settings consistent between calls because changing them can restart the daemon. `AGENT_BROWSER_SOCKET_DIR` is honored for caller-owned sessions; the wrapper-specific socket override still takes priority.
+For inactive automatic roots, global/override `always` profile **names** and the configured executable bootstrap native launch through a scoped subprocess environment shared with helpers. Active roots retain native launch settings instead of resending defaults that could replace an explicitly profiled browser; their existing restore key is preserved, including follow-ups naming the same root browser. Native Chrome profile names use independent temporary copies, not the source profile's lock. Profile paths and other profile policies remain advisory; project guidance does not change a root's launch settings when a child changes cwd. Explicit unrelated sessions, native launch/config/environment choices, isolated `script`, and Electron launches do not receive the root bootstrap defaults. Do not set a global native profile merely to enable this feature: it can change the launch configuration of existing unrelated browsers.
 
-A configured native session, like explicit `--session`, takes precedence over `sessionMode: "fresh"`. To select a different browser, override the native session **and** profile/config as appropriate; changing only the name can contend for the same profile. Without a configured session, implicit ownership and fresh rotation are unchanged. `script` remains disposable: its helpers and cleanup use an empty temporary native config, never your user/project profile defaults. Electron launch retains its own isolated app lifecycle and generated session, even with a native session environment default. With a shared native default configured, target Electron's returned `sessionName` explicitly for browser follow-ups.
+Each automatic root has its own stable native restore key. Native save/restore preserves cookies, localStorage, and sessionStorage across normal close/restart; it does not merge auth between roots or save new IndexedDB-only credentials, service workers, or page-memory grants. Named profile copies can bootstrap existing IndexedDB, but are discarded on close and never write back to the communal profile. Verify the actual application after restart, not just a successful restore receipt. If an application needs unsupported state, use a supported persistent **per-root** profile and collect required sign-ins together; never point concurrent roots at one writable profile directory. Sites can expire sessions or require a fresh human challenge.
 
-Use `{ "args": ["session", "info"] }` for one read-only preflight of the selected native session (or add `--namespace` / `--session` explicitly). It separates daemon activity/PID from verified browser liveness, Chrome PID, exact profile, tabs and native launched/attached ownership. Pi cleanup ownership is separate: a caller-owned shared browser is not closed by Pi, while an explicit name can still identify a wrapper-owned browser. Missing native fields remain unknown, never inferred from config or a live daemon.
+Explicit native `session` defaults (config or `AGENT_BROWSER_SESSION`) still override automatic root selection, including `sessionMode: "fresh"`. They intentionally share whichever browser the caller selected. Per-call session/namespace flags retain precedence. Ordinary launch options such as `--profile` or `--executable-path` still use the root-group name. Repeat explicit options when deliberately relaunching a persistent per-root profile after close. Explicit `fresh` and attachment choices retain their existing managed-session lifecycle; later auto calls follow that selected managed session. Use `session info` with the reported `sessionName` for read-only native daemon/browser evidence. Unknown native fields remain unknown.
 
 Policy-required URL reads keep the two-call read → confirm/deny flow. Returned actions name the actual native namespace/session, including `default`; routing survives transcript resume and branch changes. Only explicit-read provenance plus native `capabilities.readRequiresConfirmation: true` permits matching confirm/deny without page helpers. This capability includes native confirmation-ID checking. Legacy prompts retain correct routing but normal page checks; DOM or content-shaped prompts never receive the exemption.
 
 Full live identity, browser-independent native reads/confirmations and detailed recording receipts require the companion upstream fixes; the current recommended release does not yet supply all of them. Older supported versions remain accepted with unavailable evidence marked unknown. The extension does not upgrade or restart your installed browser to obtain these fields.
 
-Coordinate tabs/navigation between agents sharing a browser; the wrapper's per-session queue is local to one Pi process. Persistent profile storage preserves browser data, not a promise of permanent website login: sites can expire or revoke sessions and require a new human challenge. Standing permission avoids repeated permission requests, but cannot change those site policies.
-
-Before enabling global native profile defaults, update and fully restart every participating Pi runtime. Older loaded wrappers can still let disposable `script` launches read HOME config; editing this source or running `/reload` does not replace their cached code. Coordinate the browser cutover too: moving an existing daemon from the old wrapper's explicit 15-minute idle timeout to native idle policy changes its launch fingerprint and can restart it. Do not change that policy while another agent is using the browser.
-
 ### Profile selection
 
 The wrapper does not clone profiles or hide what upstream Chrome/Chromium profile or executable you chose. Passing `--profile` or `--executable-path` is an explicit upstream `agent-browser` choice. Visible page content from real profiles is model-visible and may persist in transcripts or saved artifacts; redaction protects credential-like cookie/storage/auth values, not ordinary page text you asked the browser to read. Redactions use `[REDACTED]` (URL-encoded in parsed URLs); ordinary technical phrases such as `bearer token` stay intact. URL redaction includes `code`, `authorization_session_id`, and auth-context `state` / `nonce` across visible text, details, spills, and `outputPath` exports. URLs needing no redaction keep their original spelling.

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

@@ -1370,7 +1370,12 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             }
             if (resolvedInput.kind !== "script")
                 await beforeExecute?.(nativeToolCallId, { ...ctx, signal });
-            return withNativeSessionDefaults(resolvedInput, ctx.cwd, signal, async (resolvedInput) => {
+            const runtimeBrowserConfig = loadAgentBrowserConfigSync({ cwd: ctx.cwd, includeProjectConfig: shouldIncludeProjectConfig(ctx) });
+            const rootProfile = runtimeBrowserConfig.trustedBrowserDefaultProfile;
+            const pendingReadConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE));
+            const rootSessionId = process.env.PI_SUBAGENT_CHILD === "1" && process.env.PI_SUBAGENT_ROOT_SESSION_ID
+                ? process.env.PI_SUBAGENT_ROOT_SESSION_ID : ctx.sessionManager.getSessionId();
+            return withNativeSessionDefaults(resolvedInput, ctx.cwd, signal, async (resolvedInput, withLaunchDefaults) => {
                 const readConfirmation = sessionPageState.findReadConfirmation(resolvedInput.toolArgs, resolveAgentBrowserNamespace(resolvedInput.toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE));
                 if (readConfirmation)
                     resolvedInput = { ...resolvedInput, toolArgs: scopeReadConfirmationArgs(resolvedInput.toolArgs, readConfirmation) };
@@ -1614,7 +1619,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                 const callerOwnedSessionQueueKey = !serializeBrowserCommand && explicitSessionName
                     ? getSessionContextKey(explicitSessionName, callerOwnedSessionNamespace) ?? explicitSessionName
                     : undefined;
-                const runBrowserCommand = async () => {
+                const runBrowserCommand = async (daemonInactive) => {
                     flushRecordingReservations();
                     const branchRestoreGenerationAtStart = branchRestoreGeneration;
                     const generationAtStart = branchStateGeneration;
@@ -1664,6 +1669,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                             ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
                     const attachedSessionKnown = reusableSessionKey !== undefined && attachedSessionKeys.has(reusableSessionKey);
                     let result = await runAgentBrowserTool({
+                        daemonInactive,
                         ctx,
                         cwd: ctx.cwd,
                         electronPostCommandStatusSettleMs: ELECTRON_POST_COMMAND_STATUS_SETTLE_MS,
@@ -1771,6 +1777,7 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                     return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result: warnRecordingPersistence(result) });
                 };
                 const closesAllSessions = commandClosesAllSessions(toolArgs, resolvedInput.toolStdin);
+                const runWithLaunchDefaults = () => withLaunchDefaults ? withLaunchDefaults(runBrowserCommand) : runBrowserCommand();
                 const runWithinSessionQueue = () => {
                     if (closesAllSessions)
                         return managedSessionExecutionQueue.run(() => {
@@ -1783,13 +1790,13 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                                 sessionMode: params.sessionMode ?? "auto",
                                 stdin: resolvedInput.toolStdin,
                             });
-                            return callerOwnedSessionExecutionQueues.runExclusive(plan.namespace, runBrowserCommand);
+                            return callerOwnedSessionExecutionQueues.runExclusive(plan.namespace, runWithLaunchDefaults);
                         });
                     if (serializeBrowserCommand)
-                        return managedSessionExecutionQueue.run(runBrowserCommand);
+                        return managedSessionExecutionQueue.run(runWithLaunchDefaults);
                     return callerOwnedSessionQueueKey
-                        ? callerOwnedSessionExecutionQueues.run(callerOwnedSessionQueueKey, callerOwnedSessionNamespace, runBrowserCommand)
-                        : runBrowserCommand();
+                        ? callerOwnedSessionExecutionQueues.run(callerOwnedSessionQueueKey, callerOwnedSessionNamespace, runWithLaunchDefaults)
+                        : runWithLaunchDefaults();
                 };
                 if (!commandTouchesArtifactLifecycle(toolArgs, resolvedInput.toolStdin, outputPath))
                     return runWithinSessionQueue();
@@ -1814,6 +1821,10 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                         validationError: artifactValidationError,
                     }));
                 });
+            }, managedSessionActive || freshSessionOrdinal > 0 || params.sessionMode === "fresh" || pendingReadConfirmation ? undefined : {
+                id: rootSessionId,
+                profile: rootProfile?.policy === "always" && !/[\\/~]/.test(rootProfile.name) ? rootProfile.name : undefined,
+                executablePath: runtimeBrowserConfig.trustedBrowserExecutablePath,
             });
         },
     };

package/dist/extensions/agent-browser/lib/orchestration/batch-stdin.js

@@ -1,3 +1,35 @@
+import { projectUpstreamGlobalFlags } from "../argv-grammar.js";
+/** Bare open's native launch action drops prior launch options. URL reads lazily launch without navigating. */
+export function normalizeUrlLessOpen(args, stdin, batchStep = false) {
+    const { tokens, indices } = batchStep ? { tokens: args, indices: args.map((_, index) => index) } : projectUpstreamGlobalFlags(args);
+    if (tokens[0] === "open" && !tokens.slice(1).some(token => !token.startsWith("--"))) {
+        const index = indices[0];
+        return { args: [...args.slice(0, index), "get", "url", ...args.slice(index + 1)], stdin };
+    }
+    if (tokens[0] !== "batch")
+        return { args, stdin };
+    const rawSteps = tokens.slice(1).flatMap((token, offset) => {
+        const step = token === "--bail" ? undefined : parseBatchCommandArgument(token).step;
+        return step ? [{ index: indices[offset + 1], step }] : [];
+    });
+    if (tokens.slice(1).some(token => token !== "--bail")) {
+        let normalized = args;
+        for (const { index, step } of rawSteps) {
+            const row = normalizeUrlLessOpen(step, undefined, true).args;
+            if (row === step)
+                continue;
+            if (normalized === args)
+                normalized = [...args];
+            normalized[index] = row.map(token => `'${token.replaceAll("'", "'\\''")}'`).join(" ");
+        }
+        return { args: normalized, stdin };
+    }
+    const steps = parseUserBatchStdin(stdin).steps;
+    if (!steps?.length)
+        return { args, stdin };
+    const normalized = steps.map(step => normalizeUrlLessOpen(step, undefined, true).args);
+    return { args, stdin: normalized.some((step, index) => step !== steps[index]) ? JSON.stringify(normalized) : stdin };
+}
 const BATCH_STDIN_EXAMPLE = ' Example: { "args": ["batch"], "stdin": "[[\\"get\\",\\"title\\"],[\\"get\\",\\"url\\"]]" }';
 // Mirror upstream commands::shell_words_split so policy inspection sees the same argv.
 export function parseBatchCommandArgument(command) {

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

@@ -1,4 +1,4 @@
-import { runAgentBrowserProcess, withAttachedBrowserSessionContext } from "../../process.js";
+import { runAgentBrowserProcess, withAttachedBrowserSessionContext, withChromeStartupArgs } from "../../process.js";
 import { isRecord } from "../../parsing.js";
 import { withOwnedManagedSessionContext } from "../../managed-session-restore.js";
 import { cleanupClickDispatchProbe } from "./click-dispatch.js";
@@ -9,7 +9,7 @@ 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) {
-    const result = await withAttachedBrowserSessionContext(options.preserveAttachedBrowserSession === true, () => runAgentBrowserToolInContext(options));
+    const result = await withChromeStartupArgs(options.input.persistentChromeArgs, () => withAttachedBrowserSessionContext(options.preserveAttachedBrowserSession === true, () => runAgentBrowserToolInContext(options)));
     const details = isRecord(result.details) ? result.details : undefined;
     const sessionKey = getSessionContextKey(typeof details?.sessionName === "string" ? details.sessionName : undefined, typeof details?.namespace === "string" ? details.namespace : undefined);
     const page = options.state.sessionPageState.get(sessionKey);
@@ -29,7 +29,7 @@ async function runAgentBrowserToolInContext(options) {
     return await withOwnedManagedSessionContext(ownedManagedSession, async () => {
         try {
             const artifactRunStartedAtMs = Date.now();
-            const processResult = await runAgentBrowserProcess({
+            const processResult = await withChromeStartupArgs(prepared.chromeStartupArgs, () => runAgentBrowserProcess({
                 args: prepared.processArgs,
                 browserIndependentReadConfirmation: prepared.readConfirmation !== undefined,
                 cwd: options.cwd,
@@ -43,7 +43,7 @@ async function runAgentBrowserToolInContext(options) {
                 signal: options.signal,
                 stdin: prepared.processStdin,
                 timeoutMs: prepared.processTimeoutMs,
-            });
+            }));
             const missingBinaryResult = await buildMissingBinaryFailureResult({
                 compatibilityWorkaround: prepared.compatibilityWorkaround,
                 electronLaunch: prepared.electronLaunch,

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

@@ -2,7 +2,9 @@ import { copyFile, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { extractExplicitSessionName, getBooleanFlagValue, isUpstreamEnvFlagEnabled, projectUpstreamGlobalFlags, resolveAgentBrowserNamespace } from "../../argv-grammar.js";
 import { isCloseCommand } from "../../command-taxonomy.js";
-import { isBrowserIndependentRead } from "../../command-policy.js";
+import { isBrowserIndependentRead, needsManagedSession } from "../../command-policy.js";
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { prepareAgentBrowserSpawnArgs, withChromeStartupArgs } from "../../process.js";
 import { cleanupElectronLaunchResources } from "../../electron/cleanup.js";
 import { launchElectronApp } from "../../electron/launch.js";
 import { pathExists } from "../../fs-utils.js";
@@ -22,7 +24,7 @@ import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, createFreshSe
 import { buildOwnedManagedSessionRestoreContext, resolveExplicitAutosaveInterval, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
 import { getExplicitSessionPageVerificationRequirement, getPageTargetValidationError, } from "../../page-target-validation.js";
-import { acquireOwnedManagedSessionDaemonPolicy, getRunningHeadedAutosavePolicyChangeError } from "./managed-session-daemon-policy.js";
+import { acquireOwnedManagedSessionDaemonPolicy, getRunningHeadedAutosavePolicyChangeError, inspectManagedSessionDaemon } from "./managed-session-daemon-policy.js";
 import { buildManagedSessionOutcome, buildSessionDetailFields, buildStaleRefPreflight, getSessionContextKey, findElectronLaunchRecordForSession, extractStringResultField, ensureSessionTabTarget, getGuardedRefUsage, getTraceOwnerGuardMessage, runSessionCommandData, shouldPinSessionTabForCommand, } from "./session-state.js";
 import { getUpstreamEffectiveBatchSteps, parseBatchStdinJsonArray } from "../batch-stdin.js";
 import { buildElectronHostFailureResult, formatAgentBrowserNextActionsText, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
@@ -551,7 +553,16 @@ export async function prepareBrowserRun(options) {
                 };
             }
         }
-        return await withOwnedManagedSessionContext(ownedManagedSession, async () => {
+        let chromeStartupArgs;
+        if (options.input.chromeStartupArgs !== undefined && !options.preserveAttachedBrowserSession && !browserIndependent
+            && !executionPlan.validationError && !isCloseCommand(executionPlan.commandInfo.command)
+            && needsManagedSession(parseArgvDescriptor(preparedArgs.args), runtimeToolStdin)) {
+            const inactive = ownedManagedSession ? managedSessionDaemonInactive : options.daemonInactive
+                ?? (executionPlan.sessionName !== undefined && (await inspectManagedSessionDaemon({ cwd, signal, sessionName: executionPlan.sessionName, namespace: executionPlan.namespace })).status === "inactive");
+            if (inactive || options.input.configuredChromeLaunch)
+                chromeStartupArgs = options.input.chromeStartupArgs;
+        }
+        return await withChromeStartupArgs(chromeStartupArgs, () => withOwnedManagedSessionContext(ownedManagedSession, async () => {
             const managedSessionRestoreDisabled = () => state.managedSessionRestoreState.isDisabled(executionPlan.sessionName, executionPlan.namespace);
             const sessionStateKey = getSessionContextKey(executionPlan.sessionName, executionPlan.namespace);
             const priorSessionPageState = sessionPageState.get(sessionStateKey);
@@ -737,7 +748,7 @@ export async function prepareBrowserRun(options) {
                 requirement: livePageRequirement,
                 stdin: runtimeToolStdin,
             });
-            const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);
+            const redactedEffectiveArgs = redactInvocationArgs(prepareAgentBrowserSpawnArgs(executionPlan.effectiveArgs, undefined, options.preserveAttachedBrowserSession, chromeStartupArgs));
             const redactedRecoveryHint = redactRecoveryHint(executionPlan.recoveryHint);
             const compatibilityWorkaround = executionPlan.compatibilityWorkaround;
             const statePatch = executionPlan.managedSessionName === freshSessionName
@@ -1022,7 +1033,7 @@ export async function prepareBrowserRun(options) {
                 catch { }
             }
             const processTimeoutMs = options.params.timeoutMs ?? getDialogAwareProcessTimeoutMs(commandTokens, promptRefSnapshot, processStdin) ?? getCommandAwareProcessTimeoutMs(commandTokens, processStdin, readTimeoutPageUrl);
-            const redactedProcessArgs = redactInvocationArgs(processArgs);
+            const redactedProcessArgs = redactInvocationArgs(prepareAgentBrowserSpawnArgs(processArgs, ownedManagedSession?.compatibilityUserAgent, options.preserveAttachedBrowserSession, chromeStartupArgs));
             const scrollAmount = Number(commandTokens.find((token) => /^\d+(?:\.\d+)?$/.test(token)));
             const shouldProbeScrollNoop = executionPlan.commandInfo.command === "scroll" && executionPlan.startupScopedFlags.length === 0 && (state.managedSessionActive || sessionMode === "fresh") && (!Number.isFinite(scrollAmount) || scrollAmount >= 500);
             const scrollPositionBefore = shouldProbeScrollNoop
@@ -1043,6 +1054,7 @@ export async function prepareBrowserRun(options) {
             return {
                 kind: "ready",
                 prepared: {
+                    chromeStartupArgs,
                     commandTokens,
                     headedLaunch,
                     providerLaunch,
@@ -1091,7 +1103,7 @@ export async function prepareBrowserRun(options) {
                     userRequestedJson,
                 },
             };
-        });
+        }));
     }
     finally {
         if (!managedSessionPolicyLockTransferred)

package/dist/extensions/agent-browser/lib/orchestration/input-plan.js

@@ -1,5 +1,6 @@
 import { parseArgvDescriptor } from "../argv-descriptor.js";
-import { validateToolArgs, redactInvocationArgs, redactSensitiveText } from "../runtime.js";
+import { normalizeUrlLessOpen } from "./batch-stdin.js";
+import { isPlainTextInspectionArgs, validateToolArgs, redactInvocationArgs, redactSensitiveText } from "../runtime.js";
 import { buildAgentBrowserResultCategoryDetails } from "../results/categories.js";
 import { compileAgentBrowserElectron } from "../input-modes/electron.js";
 import { compileAgentBrowserJob, compileAgentBrowserQaPreset } from "../input-modes/job.js";
@@ -167,7 +168,8 @@ export function resolveAgentBrowserInput(options) {
     const redactedCompiledNetworkSourceLookup = redactCompiledNetworkSourceLookup(compiledNetworkSourceLookup);
     const redactedCompiledQaPreset = compiledQaPreset && redactedCompiledJob ? { ...redactedCompiledJob, checks: compiledQaPreset.checks } : undefined;
     const redactedCompiledSourceLookup = redactCompiledSourceLookup(compiledSourceLookup);
-    const resolvedBase = { redactedArgs, toolArgs, toolStdin };
+    const normalized = validationError || isPlainTextInspectionArgs(toolArgs) ? { args: toolArgs, stdin: toolStdin } : normalizeUrlLessOpen(toolArgs, toolStdin);
+    const resolvedBase = { redactedArgs, toolArgs: normalized.args, toolStdin: normalized.stdin };
     if (validationError) {
         return {
             ...resolvedBase,

package/dist/extensions/agent-browser/lib/orchestration/native-session-defaults.js

@@ -1,15 +1,42 @@
+import { createHash } from "node:crypto";
 import { readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { extractExplicitSessionName, scanUpstreamGlobalFlagOccurrences } from "../argv-grammar.js";
+import { extractExplicitSessionName, getBooleanFlagValue, isUpstreamEnvFlagEnabled, scanUpstreamGlobalFlagOccurrences } from "../argv-grammar.js";
 import { isRecord } from "../parsing.js";
+import { parseArgvDescriptor } from "../argv-descriptor.js";
+import { needsManagedSession } from "../command-policy.js";
+import { getUpstreamEffectiveBatchSteps } from "./batch-stdin.js";
+import { hasLaunchScopedFlagToken } from "../launch-scoped-flags.js";
 import { getAgentBrowserProcessEnvironment, withAgentBrowserProcessEnvironment } from "../process-environment.js";
-import { runAgentBrowserProcess } from "../process.js";
+import { runAgentBrowserProcess, withChromeStartupArgs } from "../process.js";
 import { parseAgentBrowserEnvelope } from "../results/envelope.js";
 import { isPlainTextInspectionArgs } from "../runtime.js";
+import { buildValidationFailureResult } from "./input-plan.js";
+import { inspectManagedSessionDaemon } from "./browser-run/managed-session-daemon-policy.js";
+import { buildMissingBinaryMessage } from "./browser-run/final-result.js";
+// These native defaults already send a local launch command on every call; keep its args stable too.
+const LOCAL_VALUE_DEFAULTS = ["executablePath", "profile", "state", "proxy", "args", "userAgent", "caCert", "colorScheme", "downloadPath", "engine", "allowedDomains"];
+const LOCAL_BOOLEAN_DEFAULTS = ["headed", "allowFileAccess", "webgpu", "noWebmcp"];
+const LOCAL_ARRAY_DEFAULTS = ["extensions", "initScripts", "enable"];
+const nativeEnvName = (key) => `AGENT_BROWSER_${key.replace(/[A-Z]/g, letter => `_${letter}`).toUpperCase()}`;
+function hasLocalLaunchDefaults(config, env) {
+    return LOCAL_VALUE_DEFAULTS.some(key => env[nativeEnvName(key)] !== undefined || config[key] !== undefined)
+        || LOCAL_BOOLEAN_DEFAULTS.some(key => isUpstreamEnvFlagEnabled(env[nativeEnvName(key)]) || config[key] === true)
+        || LOCAL_ARRAY_DEFAULTS.some(key => (env[nativeEnvName(key)]?.length ?? 0) > 0 || Array.isArray(config[key]) && config[key].length > 0)
+        || (env.AGENT_BROWSER_CLEAR_CA_CERT !== undefined ? isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_CLEAR_CA_CERT) : config.clearCaCert === true)
+        || (env.AGENT_BROWSER_HIDE_SCROLLBARS !== undefined ? !isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_HIDE_SCROLLBARS) : config.hideScrollbars === false)
+        || ["HTTP_PROXY", "http_proxy", "HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy"].some(key => env[key] !== undefined);
+}
+function requestsConnection(tokens, stdin) {
+    return tokens[0] === "connect" || getUpstreamEffectiveBatchSteps(tokens, stdin).some(step => requestsConnection(step));
+}
+function rootBrowserSessionName(rootSessionId) {
+    return `pi-root-${createHash("sha256").update(rootSessionId).digest("hex").slice(0, 24)}`;
+}
 // Native `session` reports the resolved name, but not whether it was configured.
-// Read only identity presence/namespace; native validates the rest of its schema.
-async function readNativeIdentity(path, cwd, signal) {
+// Native validates its schema; retain configured launch defaults so root fallbacks never replace them.
+async function readNativeIdentity(path, cwd, signal, rootFallback, browserCommand) {
     let config;
     try {
         config = JSON.parse(await readFile(path, "utf8"));
@@ -17,7 +44,11 @@ async function readNativeIdentity(path, cwd, signal) {
     catch {
         return {};
     }
-    if (!isRecord(config) || (typeof config.session !== "string" && typeof config.namespace !== "string"))
+    if (!isRecord(config))
+        return {};
+    const rootLaunchConfig = browserCommand && (hasLocalLaunchDefaults(config, {}) || ["cdp", "autoConnect", "provider"].some((key) => config[key] !== undefined))
+        || rootFallback && ["restore", "sessionName", "state", "allowedDomains", "profile", "executablePath"].some((key) => config[key] !== undefined);
+    if (!rootLaunchConfig && typeof config.session !== "string" && typeof config.namespace !== "string")
         return {};
     const result = await runAgentBrowserProcess({ args: ["--config", path, "--json", "session"], cwd, signal, timeoutMs: 5_000 });
     try {
@@ -29,7 +60,9 @@ async function readNativeIdentity(path, cwd, signal) {
         const data = parsed.envelope?.data;
         if (!isRecord(data) || typeof data.session !== "string")
             throw new Error("Native agent-browser session inspection returned no session name; the browser command was not run.");
+        const { session: _session, namespace: _namespace, ...defaults } = config;
         return {
+            ...defaults,
             ...(typeof config.session === "string" ? { session: data.session } : {}),
             ...(typeof config.namespace === "string" ? { namespace: config.namespace } : {}),
         };
@@ -39,7 +72,7 @@ async function readNativeIdentity(path, cwd, signal) {
             await rm(result.stdoutSpillPath, { force: true });
     }
 }
-export async function withNativeSessionDefaults(input, cwd, signal, run) {
+export async function withNativeSessionDefaults(input, cwd, signal, run, root) {
     if (input.kind === "electron" && input.compiledElectron.action === "launch")
         return withAgentBrowserProcessEnvironment({ AGENT_BROWSER_SESSION: undefined }, () => run(input));
     if (input.kind === "script" || input.kind === "electron" || isPlainTextInspectionArgs(input.toolArgs))
@@ -50,10 +83,40 @@ export async function withNativeSessionDefaults(input, cwd, signal, run) {
     const paths = configPath !== undefined
         ? [resolve(cwd, configPath)]
         : [join(homedir(), ".agent-browser", "config.json"), join(cwd, "agent-browser.json")];
+    const rootName = root && rootBrowserSessionName(root.id);
+    const explicitSession = extractExplicitSessionName(input.toolArgs);
+    const rootFallback = root !== undefined && env.AGENT_BROWSER_SESSION === undefined && (explicitSession === undefined || explicitSession === rootName)
+        && needsManagedSession(parseArgvDescriptor(input.toolArgs), input.toolStdin);
     let identity = {};
+    const browserCommand = needsManagedSession(parseArgvDescriptor(input.toolArgs), input.toolStdin);
     for (const path of paths)
-        identity = { ...identity, ...await readNativeIdentity(path, cwd, signal) };
-    const session = env.AGENT_BROWSER_SESSION ?? identity.session;
+        identity = { ...identity, ...await readNativeIdentity(path, cwd, signal, rootFallback, browserCommand) };
+    // Native ORs environment/config booleans; only CLI false overrides configured auto-connect.
+    const autoConnect = getBooleanFlagValue(input.toolArgs, "--auto-connect")
+        ?? (isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_AUTO_CONNECT) || identity.autoConnect === true);
+    const attachment = hasLaunchScopedFlagToken(input.toolArgs, "--cdp")
+        || env.AGENT_BROWSER_CDP !== undefined || identity.cdp !== undefined || autoConnect
+        || parseArgvDescriptor(input.toolArgs).upstreamCommandTokens[0] === "connect";
+    const configuredSession = env.AGENT_BROWSER_SESSION ?? identity.session;
+    const launchArgs = scanUpstreamGlobalFlagOccurrences(input.toolArgs, "--args").at(-1)?.value ?? env.AGENT_BROWSER_ARGS ?? identity.args;
+    const engine = scanUpstreamGlobalFlagOccurrences(input.toolArgs, "--engine").at(-1)?.value ?? env.AGENT_BROWSER_ENGINE ?? identity.engine;
+    const provider = scanUpstreamGlobalFlagOccurrences(input.toolArgs, "--provider").at(-1)?.value ?? scanUpstreamGlobalFlagOccurrences(input.toolArgs, "-p").at(-1)?.value ?? env.AGENT_BROWSER_PROVIDER ?? identity.provider;
+    const tokens = parseArgvDescriptor(input.toolArgs).upstreamCommandTokens;
+    const batchAttaches = requestsConnection(tokens, input.toolStdin);
+    const localChrome = browserCommand && !attachment && !batchAttaches && provider === undefined
+        && (engine === undefined || engine === "chrome");
+    const chromeStartupArgs = localChrome ? ["--no-startup-window", ...(typeof launchArgs === "string" ? [launchArgs] : [])].join(",") : undefined;
+    const persistentChromeArgs = hasLocalLaunchDefaults(identity, env) ? chromeStartupArgs : undefined;
+    const configuredChromeLaunch = persistentChromeArgs !== undefined || [...LOCAL_VALUE_DEFAULTS, ...LOCAL_BOOLEAN_DEFAULTS, ...LOCAL_ARRAY_DEFAULTS, "hideScrollbars", "clearCaCert"].some(key => {
+        const flag = { extensions: "--extension", initScripts: "--init-script", clearCaCert: "--no-ca-cert" }[key] ?? `--${key.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`)}`;
+        return scanUpstreamGlobalFlagOccurrences(input.toolArgs, flag).length > 0;
+    });
+    const rootDefault = rootName && configuredSession === undefined && rootFallback && !attachment
+        ? rootName : undefined;
+    const session = configuredSession ?? rootDefault;
+    const restoreEligible = !["--restore", "--session-name", "--state", "--allowed-domains", "--provider", "-p", "--device"].some((flag) => hasLaunchScopedFlagToken(input.toolArgs, flag))
+        && !["restore", "sessionName", "state", "allowedDomains", "provider"].some((key) => identity[key] !== undefined)
+        && !["AGENT_BROWSER_RESTORE", "AGENT_BROWSER_SESSION_NAME", "AGENT_BROWSER_STATE", "AGENT_BROWSER_ALLOWED_DOMAINS", "AGENT_BROWSER_PROVIDER"].some((key) => env[key] !== undefined);
     const namespace = env.AGENT_BROWSER_NAMESPACE ?? identity.namespace;
     let args = input.toolArgs;
     if (session !== undefined && extractExplicitSessionName(args) === undefined)
@@ -64,5 +127,33 @@ export async function withNativeSessionDefaults(input, cwd, signal, run) {
         ...(configPath !== undefined ? { AGENT_BROWSER_CONFIG: resolve(cwd, configPath) } : {}),
         ...(session !== undefined ? { AGENT_BROWSER_SESSION: session } : {}),
         ...(namespace !== undefined ? { AGENT_BROWSER_NAMESPACE: namespace } : {}),
-    }, () => run({ ...input, toolArgs: args }));
+    }, () => run({ ...input, toolArgs: args, chromeStartupArgs, persistentChromeArgs, configuredChromeLaunch }, !rootDefault ? undefined : async (browserRun) => {
+        const daemon = await inspectManagedSessionDaemon({ cwd, signal, sessionName: rootDefault,
+            namespace: scanUpstreamGlobalFlagOccurrences(args, "--namespace").at(-1)?.value ?? namespace, timeoutMs: 5_000 });
+        if (daemon.status === "missing-binary")
+            return {
+                content: [{ type: "text", text: buildMissingBinaryMessage() }],
+                details: { agentBrowserStarted: false, args: input.redactedArgs, sessionName: rootDefault, resultCategory: "failure", failureCategory: "missing-binary" },
+                isError: true,
+            };
+        if (input.kind === "qa" && input.compiledQaPreset.checks.attached && daemon.status !== "active") {
+            return buildValidationFailureResult({ ...input, attemptedKind: "qa", kind: "invalid", status: "invalid", validationError: "qa.attached requires an active attached session. Open the root browser first, or select an existing native session." });
+        }
+        // An active daemon already owns its launch settings. Re-sending defaults can replace an explicitly profiled browser.
+        const bootstrap = daemon.status === "inactive";
+        let restore;
+        if (restoreEligible && daemon.status === "active")
+            restore = daemon.restoreKey ?? undefined;
+        if (restoreEligible && bootstrap)
+            restore = rootDefault;
+        const profile = scanUpstreamGlobalFlagOccurrences(args, "--profile").at(-1)?.value
+            ?? (bootstrap && restoreEligible && identity.profile === undefined && env.AGENT_BROWSER_PROFILE === undefined ? root?.profile : undefined);
+        const executablePath = scanUpstreamGlobalFlagOccurrences(args, "--executable-path").at(-1)?.value
+            ?? (bootstrap && identity.executablePath === undefined && env.AGENT_BROWSER_EXECUTABLE_PATH === undefined ? root?.executablePath : undefined);
+        return withAgentBrowserProcessEnvironment({
+            ...(restore !== undefined ? { AGENT_BROWSER_RESTORE: restore } : {}),
+            ...(profile !== undefined ? { AGENT_BROWSER_PROFILE: profile } : {}),
+            ...(executablePath !== undefined ? { AGENT_BROWSER_EXECUTABLE_PATH: executablePath } : {}),
+        }, () => withChromeStartupArgs(bootstrap || configuredChromeLaunch ? chromeStartupArgs : undefined, () => browserRun(bootstrap)));
+    }));
 }

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

@@ -30,7 +30,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "For desktop or host-controlled rich inputs, if semanticAction fill misses, refresh refs and prefer a current editable @ref from details.richInputRecovery or the latest snapshot; focus or click that ref, then use keyboard type for framework-controlled editors that require real key events. keyboard inserttext is paste-like and can change a DOM value without updating application state, so use it only when later application-state evidence proves the edit was accepted. Do not auto-submit with Enter or a submit button unless the user flow explicitly calls for it.",
     "Do not assume Playwright selector dialects such as text=Close or button:has-text('Close') are supported wrapper syntax unless current upstream agent-browser behavior has been verified.",
     "For authenticated or user-specific content explicitly requested by the user, such as feeds, inboxes, account pages, or private dashboards, use a real profile only when the user/config asks for it or profiles have been inspected; do not assume --profile Default exists on every machine. Do not use a real profile for public pages just because they are dashboards. Treat visible page content from real profiles as model-visible transcript data. On macOS, copied Chrome profiles may omit encrypted cookies, so profile selection alone is not proof of authentication; verify the target page and use a user-approved headed login once when needed. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser. If profile/user-data-dir resolution fails, stop retrying opens, run profiles and/or doctor through agent_browser, then report what the user needs to configure.",
-    "Use bare calls for a configured native shared session; the wrapper honors its session/namespace across Pi agents without owning quit cleanup or idle policy. Otherwise use the implicit session for routine work. Coordinate shared tabs and do not close another agent's browser.",
+    "Ordinary bare calls share one native browser within your root Pi parent/subagent group; unrelated roots browse independently. Coordinate multi-call navigation inside your group with existing subagent/intercom tools. Explicit native session defaults still win. Pi quit does not close group browsers; never close an unrelated browser.",
     `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 and live-checks the URL before later page reads/interactions because an attached browser can drift externally; caller config, file access, launch arguments, and environment pass through unchanged. A successful close clears the marker. When several named sessions share one Chrome, pass --pin-tab once (AGENT_BROWSER_PIN_TAB) so a closed bound tab fails as tab_gone instead of acting on a neighbor; recover with tab new or tab list. --no-pin-tab turns the sticky pin off. tab list includes each tab's CDP targetId, accepted as a tab ref.",
@@ -80,7 +80,7 @@ export const WRAPPER_TAB_RECOVERY_BEHAVIOR = [
 export const RUNTIME_PROMPT_GUIDELINES = [
     "Use agent_browser with one input mode: script, args, semanticAction, job, qa, sourceLookup/networkSourceLookup, or electron. stdin: batch/eval/auth/wrapper batch only; electron rejects it; never pass --json.",
     "For agent_browser, use open → snapshot -i → @refs; re-snapshot after changes. In authenticated unattended/auto-approved employee flows, ordinary requested non-destructive submissions may proceed. Honor explicit stops; require explicit authorization for purchases, production-control, destructive/irreversible, or account/security/privacy changes.",
-    "agent_browser honors native shared-session defaults on bare calls; do not relaunch/close a shared browser. Without a selected native session, use sessionMode=fresh for launch flags. Use requested/configured profiles only; verify auth. Profile content is model-visible; script is always disposable.",
+    "agent_browser bare calls share a root Pi browser with descendants, not unrelated roots; coordinate within the group. Native explicit sessions win. Use sessionMode=fresh for an intentional separate launch. Use requested/configured profiles only; verify auth after restart. Script is disposable.",
     "agent_browser: exact user paths; verify artifactVerification/artifacts before success claims. Save promptGuard-required files before close; ffmpeg before recording; close keeps files; waited:timeout proves nothing.",
     "When agent_browser details.nextActions exists, use them. Check Omitted high-value controls in dense snapshots. Dashboards: verify scroll via screenshot/snapshot.",
     "agent_browser: read <url> for docs/text or active DOM; get title/url; get text/html/value/count <selector>; get attr <selector> <name>. Batch 3+ getters; heed visibility warnings.",
@@ -88,13 +88,13 @@ export const RUNTIME_PROMPT_GUIDELINES = [
 export function buildBrowserExecutablePathGuideline(executablePath) {
     if (!executablePath)
         return undefined;
-    return `agent_browser config sets browser.executablePath to ${JSON.stringify(executablePath)}; reuse a configured native shared session with bare calls; otherwise for fresh browser launches that should use that Chromium-compatible executable, add --executable-path ${JSON.stringify(executablePath)} with sessionMode:fresh. The upstream profiles command still lists Chrome profiles only; for non-Chrome Chromium login state, ask the user for an explicit profile/user-data directory path or inspect local setup with profiles/doctor before recommending a profile value.`;
+    return `agent_browser config sets browser.executablePath to ${JSON.stringify(executablePath)}. Global/override values bootstrap inactive automatic root browsers; bare calls preserve active native launch settings. Project-only values remain guidance for explicit --executable-path launches. Use sessionMode:fresh only for an intentionally separate managed browser, not routine root-group browsing. Upstream profiles lists Chrome profiles only; use a supported explicit profile path for other Chromium browsers.`;
 }
 export function buildBrowserDefaultProfileGuideline(profile) {
     if (!profile || profile.policy === "explicit-only")
         return undefined;
     if (profile.policy === "always") {
-        return `agent_browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)} with policy always; reuse a configured native shared session with bare calls, otherwise use --profile ${JSON.stringify(profile.name)} with sessionMode:fresh when a fresh browser launch should use the configured profile, and treat profile content as model-visible user data.`;
+        return `agent_browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)} with policy always. Global/override Chrome profile names bootstrap automatic root browsers through independent native copies with per-root restore; bare calls and helpers preserve the active native launch settings without resending bootstrap options. Paths and project-only settings stay advisory. Explicit unrelated sessions are unchanged. Verify actual app auth after restart: native JSON restore omits new IndexedDB and memory-only credentials; use a supported per-root persistent profile if needed. Profile content is model-visible user data.`;
     }
     return `agent_browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)}; for signed-in/account-specific browser tasks, reuse a configured native shared session with bare calls, otherwise start with --profile ${JSON.stringify(profile.name)} plus sessionMode:fresh unless the user asks for a different profile.`;
 }

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

@@ -5,7 +5,7 @@ import { dirname, isAbsolute, join } from "node:path";
 import { env as processEnv, platform as processPlatform } from "node:process";
 import { spawn as crossSpawn } from "cross-spawn";
 import { parseArgvDescriptor } from "./argv-descriptor.js";
-import { extractExplicitSessionName, resolveAgentBrowserNamespace } from "./argv-grammar.js";
+import { extractExplicitSessionName, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences } from "./argv-grammar.js";
 import { commitManagedSessionRestoreSuppression, getManagedSessionRestoreEnv, getManagedSessionRestoreProtectedEnv, getOwnedManagedSessionCompatibilityEnv, getOwnedManagedSessionNamespaceEnv, isOwnedManagedSessionTarget, validateManagedSessionRestoreContextForSpawn, } from "./managed-session-restore.js";
 import { getPageTargetValidationError, } from "./page-target-validation.js";
 import { getImplicitSessionIdleTimeoutMs } from "./runtime.js";
@@ -27,6 +27,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 attachedBrowserSessionContext = new AsyncLocalStorage();
+const chromeStartupArgsContext = new AsyncLocalStorage();
+export function withChromeStartupArgs(args, run) {
+    return chromeStartupArgsContext.run(args ?? chromeStartupArgsContext.getStore(), run);
+}
 export function withAttachedBrowserSessionContext(preserve, run) {
     return attachedBrowserSessionContext.run(preserve || attachedBrowserSessionContext.getStore() === true, run);
 }
@@ -34,10 +38,19 @@ function appendTail(text, addition, maxChars) {
     const combined = text + addition;
     return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
 }
-export function prepareAgentBrowserSpawnArgs(args, wrapperCompatibilityUserAgent, preserveAttachedBrowserSession = false) {
-    if (preserveAttachedBrowserSession || !wrapperCompatibilityUserAgent)
+export function prepareAgentBrowserSpawnArgs(args, wrapperCompatibilityUserAgent, preserveAttachedBrowserSession = false, startupArgs) {
+    if (preserveAttachedBrowserSession)
+        return args;
+    const occurrence = scanUpstreamGlobalFlagOccurrences(args, "--args").at(-1);
+    const customArgs = wrapperCompatibilityUserAgent && !occurrence
+        ? `${startupArgs ?? "--no-startup-window"},--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}` : startupArgs;
+    if (customArgs === undefined)
         return args;
-    return ["--args", `--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}`, ...args];
+    if (!occurrence)
+        return ["--args", customArgs, ...args];
+    const normalized = [...args];
+    normalized[occurrence.index + 1] = customArgs;
+    return normalized;
 }
 function terminateSpawnedChild(child, signal) {
     if (processPlatform === "win32" && child.pid) {
@@ -472,7 +485,7 @@ export async function runAgentBrowserProcess(options) {
             return;
         }
         const spawnBrowser = processPlatform === "win32" ? crossSpawn : spawn;
-        const child = spawnBrowser("agent-browser", prepareAgentBrowserSpawnArgs(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession), {
+        const child = spawnBrowser("agent-browser", prepareAgentBrowserSpawnArgs(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession, chromeStartupArgsContext.getStore()), {
             cwd,
             env: childEnv,
             stdio: ["pipe", "pipe", "pipe"],

package/docs/ARCHITECTURE.md

@@ -141,9 +141,9 @@ The default extension factory optionally accepts `{ beforeExecute }`. `index.ts`
 
 ### Default
 
-An explicit native `session` default (user/project JSON or `AGENT_BROWSER_SESSION`) selects a caller-owned browser across Pi sessions. Per-call session/namespace flags win. `lib/orchestration/native-session-defaults.ts` reads only session/namespace presence from native config paths and uses sessionless native `--config <path> --json session` to validate each contributing file and resolve its session. Native config continues to own launch/profile/storage settings; the adapter does not duplicate its schema. Explicit config and per-call idle settings are scoped to helpers through `lib/process-environment.ts`. No startup probe, persistent config cache, or new lifecycle service is added.
+An explicit native `session` default (user/project JSON or `AGENT_BROWSER_SESSION`) selects a caller-owned browser across Pi sessions. Per-call session/namespace flags win. `lib/orchestration/native-session-defaults.ts` reads session/namespace and contributing launch defaults from native config paths and uses sessionless native `--config <path> --json session` to validate each contributing file and resolve its session. Native config continues to own launch/profile/storage settings; the adapter does not duplicate its schema. Explicit config and per-call idle settings are scoped to helpers through `lib/process-environment.ts`. No startup probe, persistent config cache, or new lifecycle service is added.
 
-When no native session is configured or passed, `sessionMode: "auto"` uses the existing implicit name derived from the current `pi` session id plus a hash of the absolute cwd. A configured session has the same precedence over `fresh` as a literal `--session`; script and Electron launch keep their separate wrapper-owned lifecycles. Electron launch suppresses the native session environment default only while allocating its generated session; ordinary browser follow-ups still honor the configured native default, so use the returned Electron session explicitly.
+When no native session, attachment, or explicit fresh launch is selected, `sessionMode: "auto"` uses `pi-root-<sha256(root Pi ID)[0:24]>` through the existing caller-owned named-session path. Descendants receive `PI_SUBAGENT_ROOT_SESSION_ID` from pi-subagents; root processes use `ctx.sessionManager.getSessionId()`. No cwd, human fork ancestry, run registry, or process-global assignment participates. The same name is the default native restore key. Existing native daemon inspection runs inside the existing identity queue: inactive roots receive bootstrap defaults, while active roots retain native launch settings and their current restore key. Scoped subprocess environment keeps helper settings consistent; no launch-settings journal is added. Root-name explicit follow-ups retain those defaults; unrelated explicit names do not. Global/override package `browser.defaultProfile` with `policy: "always"` supplies native Chrome profile names only, plus the configured executable. Paths and project-only profile settings stay advisory. Native config/environment and explicit launch settings win. The communal source is copied by native Chrome launch, never by the wrapper, and each root's restore writes remain separate. Native JSON restore omits IndexedDB, service workers, and page-memory credentials; application-level restart verification is required. Parent and child quit leave the root browser alive; existing per-session queues remain process-local, with no global broker. An active older/fresh managed session keeps its existing lifecycle. A configured session has the same precedence over `fresh` as a literal `--session`; script and Electron launch keep their separate wrapper-owned lifecycles. Electron launch suppresses the native session environment default only while allocating its generated session; ordinary browser follow-ups still honor the configured native default, so use the returned Electron session explicitly.
 
 Why:
 - works out of the box
@@ -166,8 +166,9 @@ The tool should also expose a first-class `sessionMode: "fresh"` escape hatch so
 
 ### Ownership
 
-V1 ownership rule:
-- implicit auto-generated sessions are extension-managed convenience sessions
+Ownership rule:
+- automatic root sessions use native caller-owned lifecycle; group members coordinate and close them explicitly
+- older implicit auto-generated sessions are extension-managed convenience sessions
 - unnamed `sessionMode: "fresh"` launches rotate that extension-managed session to a new upstream browser
 - explicit/user-managed sessions are not auto-managed by default
 - extension-managed sessions should be reusable during an active `pi` session and across `/reload`, exact-session relaunch, `/resume`, and Pi branch-tree transitions, while still being cleaned up predictably
@@ -208,6 +209,10 @@ This is primarily about ownership clarity and avoiding surprise, not adding a he
 
 ### Launch flags
 
+`native-session-defaults.ts` reads launch-argument/engine fields through its existing native-validated config discovery. Local Chrome composes `--no-startup-window` with the highest-priority caller arguments. Root bootstrap retains its existing helper scope; owned/fresh preparation reuses daemon-policy inspection, while explicit local callers use the same session-info probe. `process.ts` applies the scoped arguments after managed restore-policy checks, composing the existing compatibility user agent without overriding caller Chrome arguments. Configured environment/file arguments remain consistent across helpers; ordinary active calls do not receive a new launch configuration. This adds no browser launcher, profile mutation, tab cleanup, binary distribution, or persistent launch-settings state. Older custom-argument browsers can undergo native's normal hash-change restart on first use of the new default.
+
+Input resolution replaces URL-less `open` with native `get url` before planning, retaining requested argv separately. Effective raw/stdin batch rows use the existing native argument parser and raw-over-stdin precedence; only changed rows are rewritten. Native URL reads provide lazy launch and real lifecycle/URL output without navigating an existing page. Explicit navigation and help/version input are unchanged.
+
 `agent-browser` startup flags are sticky once a session is already running.
 The extension should surface that clearly and avoid hidden restart behavior in v1.
 

package/docs/COMMAND_REFERENCE.md

@@ -218,6 +218,7 @@ Tool parameters (use exactly one of `script`, `args`, `semanticAction`, `job`, `
 - `outputPath`: optional wrapper-owned local file sink for successful results and recording receipts, including failed, pending, timed-out or recovered stops. Recording exports preserve an envelope with original attempt status and native receipt/verification (`details.outputFile.source: "recording-receipt"`); unrelated failed extractions remain unwritten. Use it for durable `eval`, `get`, `snapshot`, or diagnostic outputs, not as the destination for screenshots, downloads, recordings, or other browser artifacts; if the paths resolve to the same file, the browser artifact is preserved and the result-data write fails validation. If presentation compacted a large direct result, a result row, or the whole `batch`, the writer copies each full command-redacted pre-compaction value only from its matching live wrapper-manifest spill; if any required spill is unavailable or untrusted, it fails without writing compact metadata. `details.outputFile` reports the saved path and byte count. If caller argv includes upstream `--json`, the visible JSON content stays parseable and the save notice is only in `details.outputFile`.
 - `timeoutMs`: optional per-call wrapper subprocess watchdog override in milliseconds for the requested browser CLI process. Managed-session policy inspection can independently consume up to 35 seconds before that process; this preflight is intentionally not shortened by `timeoutMs` because a busy but valid daemon must remain distinguishable from an unverifiable one.
 - `sessionMode`:
+  - Unconfigured ordinary calls select a root-Pi named browser with native restore; descendants share it, unrelated roots do not wait on each other, and Pi quit leaves it running. Existing managed sessions and explicit fresh launches retain their lifecycle.
   - Native configured `session` / `AGENT_BROWSER_SESSION` defaults select a caller-owned shared browser for ordinary calls, just like explicit `--session`, without requiring repeated flags. Such a selection wins over both modes and is not closed on Pi quit. See [shared browser defaults](../README.md#shared-browser-defaults).
   - `"auto"` reuses the extension-managed session when no native session is selected.
   - `"fresh"` rotates that managed session to a fresh upstream launch so launch-scoped flags (`--allowed-domains`, `--auto-connect`, `--args`, `--ca-cert`, `--no-ca-cert`, `--cdp`, `--enable`, `--executable-path`, `--webgpu`, `--init-script`, `--idle-timeout`, `--user-agent`, `--headed`, `--device`, `--namespace`, `--profile`, `--provider`, `-p`, `--restore`, `--restore-save`, `--restore-check-url`, `--restore-check-text`, `--restore-check-fn`, `--session-name`, `--state`) apply.
@@ -1015,7 +1016,7 @@ Example config:
 }
 ```
 
-Browser default config is conservative: it adds agent guidance for signed-in/account-specific tasks and alternate Chromium-compatible executables; current releases do not auto-inject `--profile` or `--executable-path` for every launch. Configure profile/executable guidance globally, in trusted project config, or through `PI_AGENT_BROWSER_CONFIG`. Ask the agent to run `profiles` and `doctor` when profile resolution fails, then use the reported Chrome profile directory name, a full profile/user-data directory path if upstream accepts one, or the configured `browser.executablePath` with top-level `sessionMode: "fresh"`.
+Browser defaults are scoped: global/override `defaultProfile` with `policy: "always"` and a Chrome profile name (not a path), plus `executablePath`, become native subprocess defaults only for automatic root browsers and their helpers. Roots have distinct named sessions and restore keys; parents and descendants share one root through `PI_SUBAGENT_ROOT_SESSION_ID`. These defaults never apply to unrelated explicit sessions, script, or Electron launches. Profile paths, other policies, and project-only guidance remain advisory. Native restore keeps cookies/localStorage/sessionStorage, not new IndexedDB, service workers, or memory-only grants; verify app access after a real restart. Avoid global native profile changes or a shared writable profile path; see [shared browser defaults](../README.md#shared-browser-defaults). Configure profile/executable guidance globally, in trusted project config, or through `PI_AGENT_BROWSER_CONFIG`. Ask the agent to run `profiles` and `doctor` when profile resolution fails, then use the reported Chrome profile directory name, a full profile/user-data directory path if upstream accepts one, or the configured `browser.executablePath` with top-level `sessionMode: "fresh"`.
 
 ## Important global flags, config, and environment
 
@@ -1039,6 +1040,8 @@ Browser default config is conservative: it adds agent guidance for signed-in/acc
 
 ### Browser launch and runtime flags
 
+The extension composes stock `--args --no-startup-window` for local Chrome startup without changing the headless default or external browser engines/attachments. Caller arguments retain native precedence. Plain active follow-ups do not repeat bootstrap settings; older custom-argument sessions can restart once when the new argument changes native launch identity. URL-less `open` runs native `get url` to lazily launch or preserve the active page, including batch/script calls; the result exposes the actual command and URL, not a fabricated launch receipt. See [the startup contract](TOOL_CONTRACT.md#headed-and-local-fixture-limits).
+
 - `--executable-path <path>`: custom Chromium-compatible browser executable, such as Brave/Edge/Arc/Vivaldi when upstream can launch that binary. Environment: `AGENT_BROWSER_EXECUTABLE_PATH`.
 - `--extension <path>`: load browser extensions; repeatable. Environment: `AGENT_BROWSER_EXTENSIONS`.
 - `--args <args>`: browser launch args, comma or newline separated. Chromium switches belong in this value, for example `{ "args": ["--args", "--no-sandbox", "open", "https://example.com"], "sessionMode": "fresh" }`. A bare `--no-sandbox` is diagnosed when it occupies the command slot (unknown command) or an `open` / `goto` / `navigate` option position (ignored by upstream); literal operands in other commands are left alone. For batches, put `--args` before `batch` in top-level `args`, not inside a row. Environment: `AGENT_BROWSER_ARGS`.

package/docs/RELEASE.md

@@ -47,7 +47,7 @@ npm run verify -- pre-pr
 3. `npm run verify -- package-pi`, which first validates package contents via `npm pack --json --dry-run` and then smoke-loads the packed package in Pi isolation
 4. `npm run smoke:platform:doctor` and the full Crabbox matrix from [`platform-smoke.md`](platform-smoke.md): macOS SSH, Ubuntu local-container, and native Windows Parallels targets running fast target-local `platform-build` plus `browser-dogfood-smoke`
 
-The 0.6.12 release uses the documented [local macOS and hosted native-Windows alternatives](platform-smoke.md#alternate-native-transports) instead of SSH and Parallels. Run and inspect those target-local suites separately alongside the remaining release checks. The default composed gate is unchanged; alternate evidence must not be labeled a passing Crabbox matrix.
+The 0.6.13 release uses the documented [local macOS and hosted native-Windows alternatives](platform-smoke.md#alternate-native-transports) instead of SSH and Parallels. Run and inspect those target-local suites separately alongside the remaining release checks. The default composed gate is unchanged; alternate evidence must not be labeled a passing Crabbox matrix.
 
 `npm publish` runs npm’s `prepublishOnly` script from `package.json`, which executes the same `npm run verify -- release` gate and then `npm pack --dry-run`. That concatenated gate is everything in the default `npm run verify` step (generated playbook drift, clean `dist/` build, TypeScript, the unit/fake suite, generated command-reference blocks, and live upstream command-reference sampling against the targeted `agent-browser` on `PATH`), the configured-source lifecycle harness, the packaged Pi smoke in `package-pi`, and the release-blocking Crabbox platform matrix. Using `npm publish --ignore-scripts` skips that contract intentionally.
 
@@ -221,7 +221,7 @@ Run the automated harness for deterministic configured-source lifecycle regressi
 npm run verify -- lifecycle
 ```
 
-The harness creates an isolated `PI_CODING_AGENT_DIR`, writes settings with exactly one temporary configured package source, runs `pi` in `tmux` with `--approve`, default model **`zai/glm-5.2`**, and a deterministic `--session-id`, puts a deterministic fake `agent-browser` first on `PATH`, drives `/reload`, closes Pi, and relaunches with the same exact session id instead of typing `/resume`. It also asserts the JSONL session header id, same-page managed-session continuity, compiled JS code pickup after full process relaunch, persisted spill reachability, and real Pi `tool_result` failure-patch semantics for a QA reclassification. Per-step tmux waits default to **180000 ms** (three minutes) in [`scripts/verify-lifecycle.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/verify-lifecycle.mjs) (`DEFAULT_TIMEOUT_MS`); override with `--timeout-ms <ms>` when slower models or cold starts need more headroom. Override the model when needed:
+The harness creates an isolated `PI_CODING_AGENT_DIR`, writes settings with exactly one temporary configured package source, runs `pi` in `tmux` with `--approve`, default model **`zai/glm-5.2`**, and a deterministic `--session-id`, puts a deterministic fake `agent-browser` first on `PATH`, starts an explicit `sessionMode: "fresh"` managed browser, drives `/reload`, closes Pi, and relaunches with the same exact session id instead of typing `/resume`. It also asserts the JSONL session header id, same-page managed-session continuity, compiled JS code pickup after full process relaunch, persisted spill reachability, and real Pi `tool_result` failure-patch semantics for a QA reclassification. Per-step tmux waits default to **180000 ms** (three minutes) in [`scripts/verify-lifecycle.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/verify-lifecycle.mjs) (`DEFAULT_TIMEOUT_MS`); override with `--timeout-ms <ms>` when slower models or cold starts need more headroom. Override the model when needed:
 
 ```bash
 npm run verify -- lifecycle --model openai-codex/gpt-5.5:minimal
@@ -274,8 +274,8 @@ This suite requires the installed stable `agent-browser --version` to meet the m
 - **Navigation metadata and native tab setup:** plain pages stay quiet; a page with tools retains positive native `data.webmcp` and shows the `webmcp list` hint. New tabs inherit configured headers before their first request, and clearing headers removes them on the next tab. No wrapper inheritance code is involved.
 - **Recording FPS paths and pinning:** the opt-in `test/agent-browser.batch-fidelity.test.ts` native case checks direct/raw/stdin preflight before dispatch, actual start/restart destinations and pinned targets with leading `--fps`, conservative start-ref protection, FPS-only restart continuity, and valid 12-fps WebM output after explicitly logged 12-second fixture captures. Run it with `PI_AGENT_BROWSER_REAL_UPSTREAM=1`; it requires native 0.37 or newer. Keep focused older-native controls for fresh-page starts and the start-then-ref batch latch when changing that policy.
 - **Managed session core and safe diagnostic matrix:** fresh `open` on the contract fixture, then implicit reuse across `eval --stdin`, `snapshot -i`, interaction commands (`click`, `dblclick`, `fill`, `type`, `type --clear --delay`, `focus`, `keyboard` with `type` / `inserttext`, `press`, `hover`, `check`, `uncheck`, `select`, failed `select` no-match, `upload`, `drag`, `mouse`, `scroll`, off-viewport click, `scrollintoview`, `wait` on selectors in the main frame and a selected iframe), extraction (`get` variants, `is` variants, `find label … fill` via native `<label>`, `aria-label`, and `aria-labelledby`, inline `eval`), file outputs (`screenshot`, `pdf`), navigation (`back`, `forward`, `reload`, `tab list`, another `open` to the same fixture), `batch` stdin, `pushstate`, `vitals … --json`, network route/requests/HAR, diff snapshot/screenshot/url, trace/profiler, console/errors/highlight, stream enable/status/disable, and `cookies set --curl`.
-- **Managed restore correctness and persistence:** while the restore-enabled managed daemon is active, assert raw argument and stdin batches containing nested `connect` fail before upstream spawn; a new empty-transcript harness must also reject incompatible reuse of that live same-name daemon. Seed a cookie plus localStorage/sessionStorage, close the first managed browser while a conflicting parent namespace is set, verify the default-namespace daemon actually closed, create a new extension harness with the same cwd, reopen the fixture, and assert all three values restore before closing the second browser. On POSIX, separate isolated real-browser launches assert automatic restore stays disabled and no snapshot is written through either a symlinked `sessions` directory or a file symlink in `sessions/.tmp`; a relative `HOME`, untrusted writable HOME ancestry, and a non-Git cwd must fail closed. Verify a checkout rename preserves its generation identity but starts a fresh composite restore key (fail-closed, because the cwd-derived managed-session base name changes), a copied or path-replacement checkout gets a new key, and changing the Git-generation marker between planning and spawn prevents agent-browser from starting. Run two same-identity harnesses concurrently so a compatible launch publishes its daemon policy before a waiting incompatible launch re-inspects and fails without reaching its main spawn; also fail a fresh non-batch command after daemon creation and verify shutdown closes the retained identity.
-- **Cold first-read continuity:** the focused `contract suite matches cold URL reopen after quit` case runs actual quit cleanup, waits for the exact old daemon to exit, reloads the saved branch, and requests `snapshot -i` before any explicit navigation. Empty storage and origin storage must both reach their remembered non-root URL, report fresh refs in the main frame, and retain storage without pretending to retain unsaved forms or JavaScript memory. Separate deterministic cold-resume/boundary tests cover first `get url` and history commands, non-page daemon-starting calls and batch prefixes, hash routes, pending-state transcript replay, live missing tabs versus explicit URL destinations, close retirement, and caller-owned/attached/restore-disabled boundaries. Those fake-upstream checks do not replace native-browser or real Pi lifecycle qualification of the complete candidate.
+- **Managed restore correctness and persistence:** while the restore-enabled managed daemon is active, assert raw argument and stdin batches containing nested `connect` fail before upstream spawn; a new harness replaying the owned launch result must also reject incompatible reuse of that live same-name daemon. Seed a cookie plus localStorage/sessionStorage, close the first managed browser while a conflicting parent namespace is set, verify the default-namespace daemon actually closed, create a new extension harness with the same cwd, reopen the fixture with `sessionMode: "fresh"`, and assert all three values restore before closing the second browser. On POSIX, separate isolated real-browser launches assert automatic restore stays disabled and no snapshot is written through either a symlinked `sessions` directory or a file symlink in `sessions/.tmp`; a relative `HOME`, untrusted writable HOME ancestry, and a non-Git cwd must fail closed. Verify a checkout rename preserves its generation identity but starts a fresh composite restore key (fail-closed, because the cwd-derived managed-session base name changes), a copied or path-replacement checkout gets a new key, and changing the Git-generation marker between planning and spawn prevents agent-browser from starting. Run two same-identity harnesses concurrently so a compatible launch publishes its daemon policy before a waiting incompatible launch re-inspects and fails without reaching its main spawn; also fail a fresh non-batch command after daemon creation and verify shutdown closes the retained identity.
+- **Cold first-read continuity:** the focused `contract suite matches cold URL reopen after quit` case starts an explicit `sessionMode: "fresh"` managed browser, runs actual quit cleanup, waits for the exact old daemon to exit, reloads the saved branch, and requests `snapshot -i` before any explicit navigation. Empty storage and origin storage must both reach their remembered non-root URL, report fresh refs in the main frame, and retain storage without pretending to retain unsaved forms or JavaScript memory. Separate deterministic cold-resume/boundary tests cover first `get url` and history commands, non-page daemon-starting calls and batch prefixes, hash routes, pending-state transcript replay, live missing tabs versus explicit URL destinations, close retirement, and caller-owned/attached/restore-disabled boundaries. Those fake-upstream checks do not replace native-browser or real Pi lifecycle qualification of the complete candidate.
 - **Failure shape:** `react tree` on a page opened with `--enable react-devtools` but without a React app (expects a clear missing-renderer error with session-bound `details`).
 - **Async download:** `open` on the `/download` fixture, anchor-triggered export, then `wait --download <path>` metadata and wrapper artifact reporting for the requested path.
 

package/docs/SUPPORT_MATRIX.md

@@ -1,5 +1,7 @@
 # Current upstream support matrix
 
+Root browser groups use native named sessions plus per-root restore, with scoped Chrome profile-name bootstrap from existing package config. `test/agent-browser.shared-defaults.test.ts` covers root separation, descendant routing, exact root-name follow-ups, helper launch consistency, explicit overrides, and quit ownership; the companion pi-subagents tests cover foreground/detached launch and saved revive identity. Native JSON restore supports cookies and web storage, not new IndexedDB-only or memory credentials. Real SDK/native-browser restart and concurrency evidence is required for this boundary; a profile metadata match alone is not login proof.
+
 Related docs:
 - [`../README.md`](../README.md)
 - [`../AGENTS.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/AGENTS.md) (rebaselining and verification stack)
@@ -62,7 +64,7 @@ Current summary:
 | RQ-0144 | Managed restore keys are scoped to both checkout generation and Pi transcript so upstream 0.33.2's newest-file-wins loading cannot let concurrent chats clobber or inherit cookies/storage. Fresh rotations, reload, restart, and `/resume` of one transcript retain continuity; after a confirmed inactive daemon, a branch-restored compatible owned session retains its pending reopen through daemon-starting non-page calls and transcript replay, then reopens the complete recorded URL (including its fragment) before current-page operations such as `get url` or `reload`, verifies the actual target and invalidates old refs. This reloads a URL, not forms, JavaScript memory, or history; live wrong-tab recovery never auto-navigates. Passive and explicit upstream configs pass through, while explicit config selection suppresses the wrapper's automatic restore injection. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.managed-session-restore.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
 | RQ-0145 | Mega-dogfood correctness closes false-positive success paths: URL QA makes matched post-clear page-error evidence non-pass as unverified, counts definitely new errors separately, and waits 150 ms for immediate post-load diagnostics, stale pre-existing artifacts and missing/stale recordings finalized by restart fail verification, aliased destinations (including dangling symlinks, full macOS/Windows Unicode folds, final short/long diff output flags, and same-call `outputPath` aliases) and active recording-path reuse through artifacts, path-bearing HAR stops, long/short or reordered explicit download waits, interspersed-global command forms, Electron cleanup output, or normalized output writes is rejected through an atomic process-wide, transcript-backed namespace/session reservation index independent of bounded manifest eviction; cross-branch close tombstones survive reload and each direct or ordered nested close retires exact identity at that lifecycle point while terminal closes clear attached/ref/page/route state, later lifecycle-proven browser launches—including failed post-close rows and `record stop`—can reactivate/rebuild it without stale pre-close `about:blank` recovery while bounded launch evidence survives failed-step presentation and transcript replay, explicitly non-launching diagnostics preserve the close, missing evidence stays conservatively active even on the first managed call, every successful direct/nested close clears wrapper trace/profiler ownership before later successful rows can rebuild it, and namespace-scoped `close --all` clears all matching managed/attached/page/ref/route/trace/recording ownership, only the newest pending recording path remains authoritative even across same-timestamp restart rows, current recording transitions replay directly without artifact-manifest compatibility inference, definitive direct/batch no-recording stop failures retire stale state at their ordered step, recording starts after nested close are rejected, pending rows coalesce into terminal batch outcomes without retaining an intermediate close-abandoned duplicate after a later saved stop, and any later same-session failure retains exact cleanup actions, same-page getter refs are refreshed, locator select resolves exact current native controls, no-movement scroll fails honestly, and script cleanup always attempts fail-closed close. | [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md), `test/agent-browser.extension-input-modes.test.ts`, `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.presentation-artifacts-batch.test.ts`, `test/agent-browser.recording-reservations.test.ts`, `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.script.test.ts` |
 | RQ-0146 | Upstream `agent-browser 0.34.0` rebaseline adds sticky `--pin-tab` / `--no-pin-tab` (`AGENT_BROWSER_PIN_TAB`) for shared CDP/auto-connect sessions, CDP target ids as tab refs, and `tab_gone` recovery data (`data.targetId`, optional `data.lastUrl`). The wrapper parses those flags as optional global booleans rather than launch-scoped, classifies `tab_gone` as `failureCategory: "tab-gone"` with `list-tabs-after-tab-gone` / `open-tab-after-tab-gone`, and shows `targetId` in `tab list` presentation. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0340-rebaseline), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), `test/agent-browser.results.test.ts`, `test/agent-browser.runtime.test.ts` |
-| RQ-0147 | Native follow-ups preserve profiled and other launch-configured browser pages by omitting wrapper compatibility launch arguments while the daemon is active; daemon inspection reapplies the retained compatibility user agent only when relaunch is required. Caller `--args`, config, file access, and local navigation pass through unchanged, and cancellation wins over policy validation before spawn. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.runtime.test.ts`, `test/agent-browser.process.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
+| RQ-0147 | Local Chrome composes stock `--no-startup-window` with native launch defaults while headless remains the default; URL-less open uses native lazy URL reads across direct/batch/script paths. Existing root/owned daemon probes and explicit-local session info gate bootstrap, without tab cleanup or a launcher/state journal. See `test/agent-browser.stock-startup.test.ts` for stock browser PID/page/storage checks. Native follow-ups preserve profiled and other launch-configured browser pages by omitting wrapper compatibility launch arguments while the daemon is active; daemon inspection reapplies the retained compatibility user agent only when relaunch is required. Caller `--args` retain their values after the startup default and native precedence; config, file access, and explicit local navigation remain native-owned, and cancellation wins over policy validation before spawn. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.runtime.test.ts`, `test/agent-browser.process.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
 | RQ-0148 | Upstream 0.35.0 adds Linux Chromium private CA trust and the `protected-vercel-deployments` skill. The wrapper parses CA set/clear globals, requires fresh managed launches, suppresses automatic managed restore for CA-enabled sessions, passes caller certificate paths upstream unchanged, and uses 0.35.0 as its runtime floor. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0350-rebaseline), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.runtime.test.ts`, `test/agent-browser.managed-session-restore.test.ts`, `test/agent-browser.page-target-validation.test.ts` |
 | RQ-0149 | Upstream 0.35.1 fixes snapshot-diff ref lifecycle, active-main-frame stream URL updates, and Windows ARM64 launcher selection without adding commands or flags. The wrapper preserves the 0.35.0 stable floor and accepts newer stable versions without version-specific shims. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0351-rebaseline), [`scripts/agent-browser-target.mjs`](../scripts/agent-browser-target.mjs), `test/agent-browser.upstream-version.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
 | RQ-0150 | Upstream 0.35.2 hardens standalone dashboard origin access and fixes root remote CDP WebSocket query URLs. The wrapper parses `--allowed-origins` as a value and keeps explicit or implicit dashboard-start lifecycle calls sessionless; upstream owns origin validation, tokens, and the CDP fix. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0352-rebaseline), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#dashboard-reverse-proxy-origins), `test/agent-browser.runtime.test.ts` |

package/docs/TOOL_CONTRACT.md

@@ -174,6 +174,10 @@ Upstream 0.35.2 adds `dashboard start --allowed-origins <origins>` and `AGENT_BR
 
 ## Headed and local fixture limits
 
+Local Chrome uses stock `--args --no-startup-window` at bootstrap and composes it consistently with caller-configured Chrome arguments (CLI overrides environment, which overrides native config). Plain active-session follow-ups do not resend bootstrap settings. A pre-existing custom-argument browser may restart once because stock Chrome launch arguments form part of native session identity; there is no migration or launch-settings journal. Headless remains the default. CDP/auto-connect, providers, Electron, and Lightpanda do not receive this Chrome default. The wrapper does not delete tabs or edit profiles.
+
+URL-less `open` is executed as native `get url`, including effective raw/stdin batch rows and script calls. This lazily opens a missing browser without navigating an existing page or issuing a second incomplete launch. `details.args` retains the request; `effectiveArgs`, `command`, native URL data and lifecycle show what ran. No launch receipt is synthesized. Explicit URLs, required-URL errors for `goto`/`navigate`, and top-level help/version argv keep their native meanings. Ignored batch stdin remains unchanged.
+
 - Upstream 0.35.0 and newer require separate `args` entries for global flag values. The wrapper rejects `--flag=value` global tokens before normal command dispatch, including trailing tokens; `--restore=<key>` is the explicit upstream-supported exception. Plain help/version inspection preserves exact caller argv, matching upstream. These exceptions are top-level only: global flags for `batch` belong before `batch`, and row-local equals forms fail validation before dispatch.
 - A bare `--no-sandbox` in the command slot, or an option position after `open` / `goto` / `navigate`, fails validation before dispatch with Chromium launch-argument guidance. The former is an unknown upstream command; navigation ignores the latter. Pass the switch as a separate `--args` value and use `sessionMode: "fresh"` for launch changes. For native batches, `--args` belongs on the outer call before `batch`, not in a row. Other commands keep their native literal text, script, select, path and option-value handling; top-level help/version inspection remains unchanged.
 - `--headed` is an upstream global flag passed through `args` (for example `{ "args": ["--headed", "open", "https://example.com"], "sessionMode": "fresh" }`). Use it on the first launch for demos, human-observed QA, or a user-completed login. If a managed browser session already exists, use `sessionMode: "fresh"` so the launch-scoped headed/headless choice is not ignored. Wrapper-owned headed launches default `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` to `0` because upstream 0.33.2's multi-origin restore collector opens visible temporary tabs and can delay session policy inspection. The wrapper records the effective launch-time interval and reapplies it to every helper and follow-up subprocess, still-owned off-current session, Electron cleanup close, and transcript reload/resume so daemon configuration remains stable. Native close still saves, but direct window close can lose newer state because upstream exempts headed browsers from idle shutdown; set an explicit interval before launch when periodic preservation matters. Because upstream reads it when the daemon starts, changing the recorded effective interval in either direction on a running wrapper-owned headed session is rejected until close plus a fresh launch.
@@ -197,7 +201,7 @@ Upstream 0.35.2 adds `dashboard start --allowed-origins <origins>` and `AGENT_BR
 - For desktop or host-controlled rich inputs, if semanticAction fill misses, refresh refs and prefer a current editable @ref from details.richInputRecovery or the latest snapshot; focus or click that ref, then use keyboard type for framework-controlled editors that require real key events. keyboard inserttext is paste-like and can change a DOM value without updating application state, so use it only when later application-state evidence proves the edit was accepted. Do not auto-submit with Enter or a submit button unless the user flow explicitly calls for it.
 - Do not assume Playwright selector dialects such as text=Close or button:has-text('Close') are supported wrapper syntax unless current upstream agent-browser behavior has been verified.
 - For authenticated or user-specific content explicitly requested by the user, such as feeds, inboxes, account pages, or private dashboards, use a real profile only when the user/config asks for it or profiles have been inspected; do not assume --profile Default exists on every machine. Do not use a real profile for public pages just because they are dashboards. Treat visible page content from real profiles as model-visible transcript data. On macOS, copied Chrome profiles may omit encrypted cookies, so profile selection alone is not proof of authentication; verify the target page and use a user-approved headed login once when needed. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser. If profile/user-data-dir resolution fails, stop retrying opens, run profiles and/or doctor through agent_browser, then report what the user needs to configure.
-- Use bare calls for a configured native shared session; the wrapper honors its session/namespace across Pi agents without owning quit cleanup or idle policy. Otherwise use the implicit session for routine work. Coordinate shared tabs and do not close another agent's browser.
+- Ordinary bare calls share one native browser within your root Pi parent/subagent group; unrelated roots browse independently. Coordinate multi-call navigation inside your group with existing subagent/intercom tools. Explicit native session defaults still win. Pi quit does not close group browsers; never close an unrelated browser.
 - When using launch-scoped flags (--auto-connect, --allowed-domains, --namespace, --cdp, --ca-cert, --no-ca-cert, --enable, --executable-path, --webgpu, --no-webmcp, --init-script, --idle-timeout, --args, --user-agent, --headed, --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 and live-checks the URL before later page reads/interactions because an attached browser can drift externally; caller config, file access, launch arguments, and environment pass through unchanged. A successful close clears the marker. When several named sessions share one Chrome, pass --pin-tab once (AGENT_BROWSER_PIN_TAB) so a closed bound tab fails as tab_gone instead of acting on a neighbor; recover with tab new or tab list. --no-pin-tab turns the sticky pin off. tab list includes each tab's CDP targetId, accepted as a tab ref.
@@ -704,7 +708,7 @@ Example:
 
 ### `sessionMode`
 
-A native `session` default from user/project JSON or `AGENT_BROWSER_SESSION` selects a caller-owned browser for `args`, `semanticAction`, `job`, `qa`, and lookups. Per-call flags still win. Like literal `--session`, this selection takes precedence over `fresh`; it reports `usedImplicitSession: false` and is not closed when Pi quits. Without a selected native session, the implicit/fresh behavior below is unchanged. `qa.attached` can inspect this shared current session using the same live target checks. See [shared browser defaults](../README.md#shared-browser-defaults).
+A native `session` default from user/project JSON or `AGENT_BROWSER_SESSION` selects a caller-owned browser for `args`, `semanticAction`, `job`, `qa`, and lookups. Per-call flags still win. Like literal `--session`, this selection takes precedence over `fresh`; it reports `usedImplicitSession: false` and is not closed when Pi quits. Without a selected native session, attachment, or explicit fresh launch, auto calls select a stable root-Pi named session and root-specific native restore key. `PI_SUBAGENT_ROOT_SESSION_ID` carries the parent identity to descendants; ordinary new/fork/clone roots differ, while resume/cwd changes keep identity. Root sessions report `usedImplicitSession: false` and survive parent/child quit. Global/override package profile names with `policy: "always"` and executable defaults bootstrap only inactive automatic roots. Active roots preserve native launch settings/current restore key, including matching root-name follow-ups; unrelated explicit browsers are unchanged. Profile paths and project-only profile config remain advisory. Native restore covers cookies and web storage, not newly created IndexedDB or memory-only authentication. See the README for communal bootstrap and persistent-profile fallback. Active older/fresh managed sessions retain the lifecycle below. `qa.attached` can inspect this shared current session using the same live target checks. See [shared browser defaults](../README.md#shared-browser-defaults).
 
 - type: `"auto" | "fresh"`
 - optional

package/docs/platform-smoke.md

@@ -38,7 +38,7 @@ npm run verify -- platform-smoke run --target ubuntu --suite platform-build
 
 ## Alternate native transports
 
-For the 0.6.12 release, local macOS execution replaces localhost SSH, and the [Native Windows workflow](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/.github/workflows/windows-native.yml) runs the existing Windows suites on a GitHub-hosted Windows runner. These are native platform checks, not Crabbox SSH or Parallels passes. The default `release` and `prepublishOnly` commands still select the Crabbox matrix; record alternate suite evidence separately rather than reporting those commands as passed.
+For the 0.6.13 release, local macOS execution replaces localhost SSH, and the [Native Windows workflow](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/.github/workflows/windows-native.yml) runs the existing Windows suites on a GitHub-hosted Windows runner. These are native platform checks, not Crabbox SSH or Parallels passes. The default `release` and `prepublishOnly` commands still select the Crabbox matrix; record alternate suite evidence separately rather than reporting those commands as passed.
 
 On macOS, run the unchanged commands returned by `buildPlatformBuildCommand('macos', 'pi-agent-browser-native', 24)` and `buildBrowserDogfoodCommand('macos', '0.37.0', true)` in [`scripts/platform-smoke/targets.mjs`](../scripts/platform-smoke/targets.mjs), serially in a clean private source copy. Use private HOME, npm and Pi settings, and headless browser profiles. No Remote Login or host security change is required.
 
@@ -113,7 +113,7 @@ Each required target runs `platform-build` and `browser-dogfood-smoke` on one Cr
 ### `browser-dogfood-smoke`
 
 1. Run `npm ci` in the synced checkout if needed.
-2. Run the deterministic model-free browser smoke through `scripts/verify-agent-browser-dogfood.ts`.
+2. Run the deterministic model-free browser smoke through `scripts/verify-agent-browser-dogfood.ts`, starting with `sessionMode: "fresh"` so every browser stays in the test-owned managed lifecycle.
 3. Exercise native wrapper surfaces against the deterministic loopback HTTP fixture from `scripts/verify-agent-browser-dogfood.ts`: top-level `qa`, `semanticAction`, constrained `job`, screenshot artifact verification, and session close.
 4. Persist the dogfood JSON report and stdout/stderr evidence.
 5. Fail on missing browser artifacts, failed tool calls, leaked secrets, or unclosed sessions.

package/package.json

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