pi-agent-browser-native 0.9.0 → 0.9.2

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

@@ -104,9 +104,10 @@ async function runAgentBrowserToolInContext(options) {
             const output = await processBrowserOutput({ ...options, artifactRunStartedAtMs, prepared, processResult });
             applyBrowserRunStatePatch(options.state, output.statePatch);
             if (isRecord(output.result.details) && Array.isArray(output.result.details.imageObservations) && prepared.commandTokens[0] === "screenshot") {
-                output.result.details.imageObservations = redactSensitiveValue(output.result.details.imageObservations.map(image => ({
-                    ...image, geometry: buildScreenshotGeometry({ capture: image.capture, pixels: image.pixels, before, after }),
-                })));
+                output.result.details.imageObservations = redactSensitiveValue(output.result.details.imageObservations.map(image => {
+                    const rendering = image.rendering ?? before?.rendering ?? after?.rendering;
+                    return { ...image, ...(rendering ? { rendering } : {}), geometry: buildScreenshotGeometry({ rendering, capture: image.capture, pixels: image.pixels, before, after }) };
+                }));
             }
             return output.result;
         }

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

@@ -333,7 +333,7 @@ function resolveSemanticActionVisibleRefArgsFromSnapshot(compiled, snapshotData)
         return undefined;
     return { args: [...getCompiledSemanticActionSessionPrefix(compiled), ...resolution.args], snapshot: resolution.snapshot };
 }
-export async function resolveSemanticActionVisibleRefArgs(options) {
+async function resolveSemanticActionVisibleRefArgs(options) {
     if (!options.compiled || !options.sessionName)
         return undefined;
     const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });

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

@@ -1,4 +1,5 @@
 import { isRecord } from "../../parsing.js";
+import { LIGHTPANDA_IMAGE_REASON } from "../../results/presentation/common.js";
 import { getScreenshotPathTokenIndex, getScreenshotPositionalIndices } from "./artifact-paths.js";
 import { runSessionCommandData } from "./session-state.js";
 export function getScreenshotCapture(command) {
@@ -28,7 +29,8 @@ export async function collectScreenshotSample(options) {
 				element = { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
 			}
 		} catch {}
-		return { url: location.href, frame: window === window.top ? "main" : "child", childFrameCount: window.frames.length,
+		const textRendered = navigator.userAgentData?.brands?.some(b => b.brand === "Lightpanda") || /\\bLightpanda\\//i.test(navigator.userAgent);
+		return { ...(textRendered ? { rendering: "text" } : {}), url: location.href, frame: window === window.top ? "main" : "child", childFrameCount: window.frames.length,
 			viewport: { width: innerWidth, height: innerHeight },
 			document: { width: Math.max(root.scrollWidth, body?.scrollWidth || 0, innerWidth), height: Math.max(root.scrollHeight, body?.scrollHeight || 0, innerHeight) },
 			scroll: { x: scrollX, y: scrollY }, dpr: devicePixelRatio,
@@ -37,7 +39,7 @@ export async function collectScreenshotSample(options) {
     try {
         const data = await runSessionCommandData({ ...options, args: ["eval", "--stdin"], stdin: script, timeoutMs: 2_000 });
         const sample = isRecord(data) ? data.result : undefined;
-        if (!isRecord(sample) || typeof sample.url !== "string" || !["main", "child"].includes(String(sample.frame))
+        if (!isRecord(sample) || (sample.rendering !== undefined && sample.rendering !== "text") || typeof sample.url !== "string" || !["main", "child"].includes(String(sample.frame))
             || !finiteRecord(sample.viewport, ["width", "height"]) || !finiteRecord(sample.document, ["width", "height"])
             || !finiteRecord(sample.scroll, ["x", "y"]) || !finiteRecord(sample.visualViewport, ["x", "y", "scale"])
             || typeof sample.childFrameCount !== "number" || !Number.isInteger(sample.childFrameCount) || sample.childFrameCount < 0
@@ -53,6 +55,8 @@ export async function collectScreenshotSample(options) {
 export function buildScreenshotGeometry(options) {
     const { before, after, capture, pixels } = options;
     const unknown = (reason) => ({ status: "unknown", reason, before, after });
+    if (options.rendering === "text" || before?.rendering === "text" || after?.rendering === "text")
+        return unknown(LIGHTPANDA_IMAGE_REASON);
     if (!before || !after)
         return unknown("Capture was not bracketed by browser geometry samples; coordinates are unknown.");
     if (JSON.stringify(before) !== JSON.stringify(after))

package/dist/extensions/agent-browser/lib/orchestration/execution-queue.js

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "../argv-grammar.js";
+// Serializes managed-session read/modify/write work so overlapping tool calls cannot promote stale state or close an in-use session.
+export class AsyncExecutionQueue {
+    tail = Promise.resolve();
+    active = new AsyncLocalStorage();
+    isCurrent() { return this.active.getStore()?.active === true; }
+    run(work, signal, barrier = Promise.resolve()) {
+        if (this.isCurrent()) {
+            signal?.throwIfAborted();
+            return work();
+        }
+        const previous = this.tail;
+        let release;
+        this.tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        let rejectWaiting;
+        const cancelled = new Promise((_resolve, reject) => { rejectWaiting = reject; });
+        const abortWaiting = () => rejectWaiting(signal?.reason);
+        signal?.addEventListener("abort", abortWaiting, { once: true });
+        if (signal?.aborted)
+            abortWaiting();
+        const execution = (async () => {
+            await Promise.all([previous, barrier]);
+            signal?.removeEventListener("abort", abortWaiting);
+            try {
+                signal?.throwIfAborted();
+                const scope = { active: true };
+                try {
+                    return await this.active.run(scope, work);
+                }
+                finally {
+                    scope.active = false;
+                }
+            }
+            finally {
+                release();
+            }
+        })();
+        return signal ? Promise.race([execution, cancelled]) : execution;
+    }
+}
+export class KeyedAsyncExecutionQueue {
+    barriers = new Map();
+    entries = new Map();
+    async run(key, namespace, work, signal) {
+        const entry = this.entries.get(key) ?? { queue: new AsyncExecutionQueue(), users: 0 };
+        if (entry.queue.isCurrent())
+            return work();
+        const barrier = this.barriers.get(getAgentBrowserSessionIdentityKey("", namespace)) ?? Promise.resolve();
+        entry.users += 1;
+        this.entries.set(key, entry);
+        try {
+            return await entry.queue.run(work, signal, barrier);
+        }
+        finally {
+            entry.users -= 1;
+            if (entry.users === 0 && this.entries.get(key) === entry)
+                this.entries.delete(key);
+        }
+    }
+    async runExclusive(namespace, work) {
+        const namespaceKey = getAgentBrowserSessionIdentityKey("", namespace);
+        const previous = this.barriers.get(namespaceKey) ?? Promise.resolve();
+        let release;
+        const blocked = new Promise((resolve) => {
+            release = resolve;
+        });
+        const barrier = previous.then(() => blocked);
+        this.barriers.set(namespaceKey, barrier);
+        const drains = [...this.entries]
+            .filter(([key]) => isAgentBrowserSessionIdentityKeyInNamespace(key, namespace))
+            .map(([, { queue }]) => queue.run(async () => undefined));
+        await previous;
+        await Promise.all(drains);
+        try {
+            return await work();
+        }
+        finally {
+            release();
+            if (this.barriers.get(namespaceKey) === barrier)
+                this.barriers.delete(namespaceKey);
+        }
+    }
+}

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

@@ -100,11 +100,12 @@ export async function withNativeSessionDefaults(input, cwd, signal, run, root) {
     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 chromeEngine = engine === undefined || engine === "chrome";
     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");
+        && chromeEngine;
     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 => {
@@ -147,9 +148,9 @@ export async function withNativeSessionDefaults(input, cwd, signal, run, root) {
         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);
+            ?? (bootstrap && chromeEngine && 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);
+            ?? (bootstrap && chromeEngine && 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 } : {}),

package/dist/extensions/agent-browser/lib/pi-tool-rendering.js

@@ -157,7 +157,7 @@ export function formatAgentBrowserRenderCall(args, theme, expanded = false) {
     }
     return text;
 }
-export function formatAgentBrowserRenderResult(result, options, theme, isError) {
+function formatAgentBrowserRenderResult(result, options, theme, isError) {
     if (options.isPartial) {
         return theme.fg("warning", "Running agent-browser...");
     }

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

@@ -14,7 +14,7 @@ export const QUICK_START_GUIDELINES = [
     "Example agent_browser_code: { code: 'const result = await browser({args:[\"get\",\"title\"]}); if (!result.success) { emit(result); } else { emit({title:result.data}); }' }. Native batch still avoids extra CLI processes for fixed segments inside code. Explicit session/namespace controls select the browser for this cell without changing the default browser.",
     "Call agent_browser_tools with no fields for inventory, or { enable: [\"action\", \"qa\", \"electron\", \"source\", \"network\"] } for advanced native tools. It adds agent_browser_action, agent_browser_qa, agent_browser_electron, agent_browser_source, and agent_browser_network_source without disabling other tools. The browser instructions cover these capabilities; activation reveals their selected tool declarations.",
     "Use read <url> for readable web text; get title/url, get text/html/value/count <selector>, or get attr <selector> <name> for targeted state. For eval --stdin, put JavaScript in stdin and return the desired value. outputPath saves result data and must differ from screenshot/download/recording paths. Use --json only when JSON text is needed.",
-    "For artifacts, verify artifactVerification and artifacts before reporting success. A pending recording is not verified output; install ffmpeg before starting and pair start with stop. Native download owns the click and saves Blob/redirect downloads. Close keeps explicitly saved files. Save promptGuard-required paths before close. Screenshot pixels are not browser CSS coordinates: use imageObservations geometry (dimensions, viewport, crop/origin, scroll and DPR) before any visual-coordinate action; full-page and element captures are not current-viewport coordinates, and Pi resizing only maps sent pixels to original image pixels.",
+    "For artifacts, verify artifactVerification and artifacts before reporting success. A pending recording is not verified output; install ffmpeg before starting and pair start with stop. Native download owns the click and saves Blob/redirect downloads. Close keeps explicitly saved files. Save promptGuard-required paths before close. Screenshot pixels are not browser CSS coordinates: use imageObservations geometry (dimensions, viewport, crop/origin, scroll and DPR) before any visual-coordinate action; full-page and element captures are not current-viewport coordinates, and Pi resizing only maps sent pixels to original image pixels. Lightpanda images are text-rendered, not graphical layout; rendering:text never supports CSS/mouse-coordinate input.",
     "Follow model-visible nextActions when present, including identity and stdin, instead of guessing commands. Treat native pending confirmations and unknown mutation outcomes as inspection boundaries. For dense snapshots, inspect Omitted high-value controls before reading a full spill.",
 ];
 export const ADVANCED_TOOL_PROMPT_GUIDELINES = {
@@ -61,6 +61,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "Cooperating Pi processes serialize each complete browser operation and code cell by native socket context, namespace, and session, including target/ref helpers and state updates. Different identities remain concurrent; namespace-wide close waits for matching operations. All participating Pi instances must load this release; humans, third-party clients, and older extensions are outside that coordination. It is not a transaction or rollback. For raw batches whose later content depends on navigation, use exact batch --bail or split the calls.",
     "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.",
     `If you already used the implicit session and now need launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}), retry with top-level sessionMode set to fresh or pass an explicit --session for the new launch; never pass --session-mode inside args. After a successful unnamed fresh launch, later auto calls follow that new session.`,
+    "Chrome is the default. Use separately installed Lightpanda only when explicitly selected with --engine lightpanda, environment or native config; --engine is launch-scoped, so use sessionMode:fresh to change a managed browser. Lightpanda text-rendered screenshots do not prove graphical layout/visibility or mouse coordinates. Chrome profiles, headed mode, multi-tab, WebGPU and native WebMCP are not parity capabilities; choose Chrome explicitly when needed, never assume automatic fallback.",
     "For WebGPU pages, use args [\"--webgpu\", \"open\", \"<url>\"] on a fresh local browser launch; use doctor --webgpu (or --headed on Linux/Windows capture paths) to prove rendering before trusting a non-black screenshot. WebGPU cannot be combined with --cdp, --auto-connect, or provider launches unless --webgpu false overrides an enabled config/environment default.",
     "For experimental WebMCP page tools, use webmcp list, then webmcp invoke <tool> with --params and optional --frame/--detach/--timeout; use webmcp result or cancel for detached calls. Locally managed Chrome enables WebMCP by default; a positive navigation hint means the page has tools to list. --no-webmcp is launch-scoped and requires a fresh session; invoke/result/cancel can mutate or navigate, so refresh snapshot refs afterward.",
     "For --allowed-domains, use a fresh local Chrome context. Upstream rejects CDP/auto-connect, profiles, restore/state replay, direct-page providers, iOS/Safari, and startup/profile Chrome args because they cannot guarantee containment; Chromium also disables RTCPeerConnection while the allowlist is active.",
@@ -110,20 +111,20 @@ export const RUNTIME_PROMPT_GUIDELINES = [
     "For agent_browser, use open → snapshot -i → current @refs; re-snapshot after changes. Batch same-snapshot fills before submit; split on rerenders/navigation. Native args, profiles, auth, providers, paths, config and environment pass through. Use requested/configured profiles and verify authentication after restart.",
     "agent_browser bare calls share a root Pi browser with descendants, not unrelated roots; coordinate navigation within the group. Native explicit sessions win. sessionMode:fresh intentionally launches a separate managed browser. Never close an unrelated browser.",
     "For agent_browser and agent_browser_code, follow visible nextActions. Inspect unknown mutation outcomes before retry. Use exact user paths; verify artifactVerification/artifacts before success claims. Save promptGuard-required files before close; close keeps files; waited:timeout proves nothing.",
-    "For agent_browser screenshot coordinates, use imageObservations dimensions/viewport/crop/origin/scroll/DPR; full-page and element images are not viewport CSS coordinates. Pi image resizing maps sent pixels to original image pixels only. Prefer refs; inspect screenshots only when the task needs vision.",
+    "For agent_browser screenshot coordinates, use imageObservations dimensions/viewport/crop/origin/scroll/DPR; full-page and element images are not viewport CSS coordinates. Pi image resizing maps sent pixels to original image pixels only. Lightpanda rendering:text images never establish CSS/mouse coordinates. Prefer refs; inspect screenshots only when the task needs vision.",
     "In agent_browser workflows, ordinary requested non-destructive submissions may proceed in authenticated unattended/auto-approved flows. Honor explicit stops; require explicit authorization for purchases, production-control, destructive/irreversible, or account/security/privacy changes.",
     "agent_browser: read <url> for text, get title/url, get text/html/value/count <selector>, get attr <selector> <name>; heed visibility warnings and Omitted high-value controls. Verify nested scrolling via snapshot/screenshot. Use --json only for JSON text; recording needs ffmpeg before start and a verified stop.",
 ];
 export function buildBrowserExecutablePathGuideline(executablePath) {
     if (!executablePath)
         return undefined;
-    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.`;
+    return `agent_browser config sets browser.executablePath to ${JSON.stringify(executablePath)}. Global/override values bootstrap inactive automatic root Chrome browsers, not Lightpanda; 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. 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)} with policy always. Global/override Chrome profile names bootstrap automatic root Chrome browsers, not Lightpanda, 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

@@ -290,9 +290,6 @@ export async function getAgentBrowserSocketDirValidationError(socketDir, uid = t
         return `the directory could not be inspected (${error.code ?? "unknown error"})`;
     }
 }
-export async function ensureAgentBrowserSocketDir(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
-    return await getAgentBrowserSocketDirValidationError(socketDir, uid) === undefined;
-}
 export function getAgentBrowserSocketPathValidationError(options) {
     if ((options.platform ?? processPlatform) === "win32")
         return undefined;

package/dist/extensions/agent-browser/lib/results/artifact-manifest.js

@@ -7,8 +7,8 @@ export function isPendingRecordingArtifact(artifact) {
     return artifact.recordingState === "openRecording" || artifact.status === "pending"
         || (artifact.status === undefined && isPendingRecordingCommand(artifact.command, artifact.subcommand, artifact.kind));
 }
-export const SESSION_ARTIFACT_MANIFEST_VERSION = 1;
-export const SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES";
+const SESSION_ARTIFACT_MANIFEST_VERSION = 1;
+const SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES";
 export const DEFAULT_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES = 100;
 function parsePositiveSafeInteger(value) {
     if (value === undefined)

package/dist/extensions/agent-browser/lib/results/network-routes.js

@@ -31,7 +31,7 @@ function getRouteDiagnosticReason(item, route) {
         return "unfulfilled-routed-request";
     return undefined;
 }
-export function getNetworkRouteMode(args) {
+function getNetworkRouteMode(args) {
     if (args.includes("--abort"))
         return "abort";
     if (args.includes("--body"))

package/dist/extensions/agent-browser/lib/results/network.js

@@ -3,7 +3,7 @@ export function getStringRecordField(value, key) {
     const field = value[key];
     return typeof field === "string" && field.trim().length > 0 ? field.trim() : undefined;
 }
-export function getNetworkRequestUrlPath(url) {
+function getNetworkRequestUrlPath(url) {
     if (!url)
         return undefined;
     try {

package/dist/extensions/agent-browser/lib/results/presentation/artifacts.js

@@ -6,6 +6,7 @@ import { getExplicitArtifactDestination } from "../../orchestration/browser-run/
 import { isRecord, parsePositiveInteger } from "../../parsing.js";
 import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, isPendingRecordingCommand, mergeSessionArtifactManifest, } from "../artifact-manifest.js";
 import { classifyAgentBrowserSuccessCategory } from "../categories.js";
+import { LIGHTPANDA_IMAGE_REASON } from "./common.js";
 import { formatRecordingReceipt, getRecordingReceipt } from "../recording.js";
 const PNG_HEADER = Buffer.from("89504e470d0a1a0a0000000d49484452", "hex");
 const INLINE_IMAGE_MAX_BYTES_ENV = "PI_AGENT_BROWSER_INLINE_IMAGE_MAX_BYTES";
@@ -587,11 +588,16 @@ export async function attachInlineImage(presentation, imagePath, modelVisible =
             return presentation;
         const dimensions = getImageDimensions(header.toString("base64"), mimeType);
         presentation.imagePath = imagePath;
+        const lifecycle = isRecord(presentation.data) && isRecord(presentation.data.lifecycle) ? presentation.data.lifecycle : undefined;
+        const textRendered = isRecord(lifecycle?.effectiveLaunch) && lifecycle.effectiveLaunch.engine === "lightpanda";
         presentation.imageObservations = [{ path: imagePath, mimeType,
+                ...(textRendered ? { rendering: "text" } : {}),
                 pixels: dimensions ? { width: dimensions.widthPx, height: dimensions.heightPx } : undefined,
-                capture: "unknown", geometry: { status: "unknown", reason: dimensions ? "Capture geometry was not observed." : "Image dimensions could not be read from the bounded header." } }];
+                capture: "unknown", geometry: { status: "unknown", reason: textRendered ? LIGHTPANDA_IMAGE_REASON : dimensions ? "Capture geometry was not observed." : "Image dimensions could not be read from the bounded header." } }];
         if (!modelVisible)
             return presentation;
+        if (textRendered)
+            appendPresentationNotice(presentation, LIGHTPANDA_IMAGE_REASON);
         const inlineImageMaxBytes = getInlineImageMaxBytes();
         if (fileStats.size > inlineImageMaxBytes) {
             appendPresentationNotice(presentation, `Image attachment skipped: ${formatByteCount(fileStats.size)} exceeds the inline limit of ${formatByteCount(inlineImageMaxBytes)}.`);

package/dist/extensions/agent-browser/lib/results/presentation/batch.js

@@ -68,7 +68,7 @@ function getStatefulCommandSensitiveValues(command) {
         return [];
     const tokens = extractUpstreamCommandTokens(command);
     const values = [];
-    if (tokens[0] === "cookies" && tokens[1] === "set" && tokens[3])
+    if (tokens[0] === "cookies" && tokens[1] === "set" && !tokens.slice(2).includes("--curl") && tokens[3])
         values.push(tokens[3]);
     if (tokens[0] === "storage" && ["local", "session"].includes(tokens[1] ?? "") && tokens[2] === "set" && tokens[4])
         values.push(tokens[4]);

package/dist/extensions/agent-browser/lib/results/presentation/common.js

@@ -2,6 +2,7 @@ import { isRecord } from "../../parsing.js";
 import { redactSensitiveText, redactSensitiveValue } from "../../runtime.js";
 import { stringifyUnknown, truncateText } from "../text.js";
 const UNTITLED_PAGE_SUMMARY = "(untitled page)";
+export const LIGHTPANDA_IMAGE_REASON = "Lightpanda screenshot is a text-rendered page representation, not a graphical capture; CSS/mouse coordinate mapping is unknown.";
 export function stringifyModelFacing(value) {
     return stringifyUnknown(redactSensitiveValue(value));
 }

package/dist/extensions/agent-browser/lib/results/presentation/diagnostics.js

@@ -507,7 +507,7 @@ export function formatNetworkRouteDiagnosticsText(diagnostics) {
     lines.push("If this route is intended as a mock, inspect the request/headers and treat failed, pending, or CORS-looking rows as unfulfilled until a mocked response is observed.");
     return lines.join("\n");
 }
-export function buildNetworkRouteDiagnosticsNextActions(diagnostics, sessionName) {
+function buildNetworkRouteDiagnosticsNextActions(diagnostics, sessionName) {
     const diagnostic = diagnostics?.find((item) => item.requestId) ?? diagnostics?.[0];
     if (!diagnostic)
         return undefined;

package/dist/extensions/agent-browser/lib/results/presentation/semantic-action.js

@@ -19,7 +19,7 @@ function formatSemanticActionTarget(compiled) {
     const target = `${locator} ${quotedValue}`;
     return name ? `${target} (name ${JSON.stringify(name)})` : target;
 }
-export function formatSemanticActionCompactLine(compiled) {
+function formatSemanticActionCompactLine(compiled) {
     const target = formatSemanticActionTarget(compiled);
     switch (compiled.action) {
         case "click":
@@ -34,7 +34,7 @@ export function formatSemanticActionCompactLine(compiled) {
             return `${compiled.action}: ${target}`;
     }
 }
-export function resolveSemanticPresentationCommand(compiled) {
+function resolveSemanticPresentationCommand(compiled) {
     if (!compiled || !SEMANTIC_PRESENTATION_ACTIONS.has(compiled.action))
         return undefined;
     if (compiled.action === "select")

package/dist/extensions/agent-browser/lib/results/selector-recovery.js

@@ -256,6 +256,6 @@ export function formatRichInputRecoveryText(diagnostic) {
         `- ${diagnostic.inputMethodHint}`,
     ].join("\n");
 }
-export function normalizeSemanticActionAccessibleName(name) {
+function normalizeSemanticActionAccessibleName(name) {
     return name.replace(/\s+/g, " ").trim().toLowerCase();
 }

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

@@ -254,7 +254,7 @@ function redactBearerCredentials(text) {
         return formatRedactedCredential(label, credential, trailing);
     });
 }
-export function isSensitiveFieldName(key) {
+function isSensitiveFieldName(key) {
     SENSITIVE_FIELD_NAME_PATTERN.lastIndex = 0;
     return SENSITIVE_FIELD_NAME_PATTERN.test(key);
 }
@@ -347,7 +347,9 @@ export function redactInvocationArgs(args) {
             }
         }
     }
-    if (commandStartIndex !== undefined && args[commandStartIndex] === "cookies" && args[commandStartIndex + 1] === "set" && redacted[commandStartIndex + 3] !== undefined) {
+    if (commandStartIndex !== undefined && args[commandStartIndex] === "cookies" && args[commandStartIndex + 1] === "set"
+        && !extractUpstreamCommandTokens(args).slice(2).includes("--curl")
+        && redacted[commandStartIndex + 3] !== undefined) {
         redacted[commandStartIndex + 3] = "[REDACTED]";
     }
     if (commandStartIndex !== undefined

package/dist/extensions/agent-browser/lib/session-page-state.js

@@ -62,7 +62,7 @@ function extractStringResultField(data, fieldName) {
     const text = data[fieldName].trim();
     return text.length > 0 ? text : undefined;
 }
-export function extractSessionTabTargetFromData(data) {
+function extractSessionTabTargetFromData(data) {
     const directTarget = normalizeSessionTabTarget({
         targetId: isRecord(data) && typeof data.targetId === "string" ? data.targetId : undefined,
         title: extractStringResultField(data, "title"),

package/dist/extensions/agent-browser/lib/web-search.js

@@ -5,20 +5,20 @@ import { redactSensitiveText } from "./runtime.js";
 import { StringEnum as localStringEnum } from "./string-enum-schema.js";
 import { DEFAULT_WEB_SEARCH_PROVIDER, EXA_SEARCH_TYPES, WEB_SEARCH_PROVIDERS, resolvePreferredWebSearchCredential, } from "./config.js";
 export const AGENT_BROWSER_WEB_SEARCH_TOOL_NAME = "agent_browser_web_search";
-export const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
-export const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
-export const DEFAULT_SEARCH_RESULT_COUNT = 5;
-export const MAX_SEARCH_RESULT_COUNT = 10;
-export const SEARCH_REQUEST_TIMEOUT_MS = 15_000;
-export const EXA_DEEP_LITE_SEARCH_REQUEST_TIMEOUT_MS = 45_000;
-export const EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS = 60_000;
-export const EXA_DEEP_REASONING_SEARCH_REQUEST_TIMEOUT_MS = 90_000;
-export const EXA_DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
+const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
+const DEFAULT_SEARCH_RESULT_COUNT = 5;
+const MAX_SEARCH_RESULT_COUNT = 10;
+const SEARCH_REQUEST_TIMEOUT_MS = 15_000;
+const EXA_DEEP_LITE_SEARCH_REQUEST_TIMEOUT_MS = 45_000;
+const EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS = 60_000;
+const EXA_DEEP_REASONING_SEARCH_REQUEST_TIMEOUT_MS = 90_000;
+const EXA_DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
 export const WEB_SEARCH_MIN_REQUEST_INTERVAL_MS = 1_100;
 export const EXA_SEARCH_SYSTEM_PROMPT = "Prefer primary, official sources. Respect any requested version or date. Avoid duplicate or equivalent results.";
 export { EXA_SEARCH_TYPES };
-export const WEB_SEARCH_PROVIDER_PARAM_VALUES = ["auto", ...WEB_SEARCH_PROVIDERS];
-export const EXA_SEARCH_CATEGORIES = ["company", "people", "publication", "news", "personal site", "financial report"];
+const WEB_SEARCH_PROVIDER_PARAM_VALUES = ["auto", ...WEB_SEARCH_PROVIDERS];
+const EXA_SEARCH_CATEGORIES = ["company", "people", "publication", "news", "personal site", "financial report"];
 const MAX_EXA_DOMAIN_FILTERS = 20;
 const MAX_EXA_ADDITIONAL_QUERIES = 10;
 export function createAgentBrowserWebSearchParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
@@ -193,7 +193,7 @@ export function cleanSearchText(value, maxLength = 500) {
         return cleaned;
     return `${cleaned.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
 }
-export function normalizeSearchUrl(value) {
+function normalizeSearchUrl(value) {
     if (typeof value !== "string")
         return undefined;
     try {
@@ -258,7 +258,7 @@ export function normalizeExaSearchResult(result) {
 function getProviderLabel(provider) {
     return provider === "exa" ? "Exa" : "Brave";
 }
-export function formatSearchResults(provider, query, results) {
+function formatSearchResults(provider, query, results) {
     const providerLabel = getProviderLabel(provider);
     if (results.length === 0) {
         return `No ${providerLabel} web results found for: ${query}`;
@@ -538,14 +538,14 @@ const EXA_WEB_SEARCH_ADAPTER = {
         };
     },
 };
-export const WEB_SEARCH_PROVIDER_ADAPTERS = {
+const WEB_SEARCH_PROVIDER_ADAPTERS = {
     exa: EXA_WEB_SEARCH_ADAPTER,
     brave: BRAVE_WEB_SEARCH_ADAPTER,
 };
 export function getWebSearchProviderAdapter(provider) {
     return WEB_SEARCH_PROVIDER_ADAPTERS[provider];
 }
-export function dedupeSearchResults(results) {
+function dedupeSearchResults(results) {
     const seen = new Set();
     return results.filter((result) => {
         if (seen.has(result.url))

package/docs/ARCHITECTURE.md

@@ -46,15 +46,15 @@ The extension should:
 
 The child has an empty environment, Node permission mode without host capability allowlists, a 64 MiB heap ceiling, and a VM with string/WebAssembly code generation disabled. Null-prototype `browser`, `emit`, and `emitImage` functions use JSON-only IPC; parent promises/objects/functions are not exposed. There are no imports or host filesystem/network/process/timer APIs. Node's VM alone is not a security boundary. The retained child isolation is distinct from the selected browser's persistent authentication and native capabilities; no QuickJS, broker, second driver, or provider payload injection is involved.
 
-Limits are 25 attempted calls, 64 KiB source/final JSON, 1 MiB per IPC message, 8 MiB cumulative IPC, and a 120-second default/300-second maximum deadline. `browser()` returns a canonical observation. `emit` selects JSON; `emitImage` selects a cell-local verified image handle, with file identity rechecks and normal inline limits. `lib/orchestration/script-mode.ts` aggregates selected output, failures, and artifact receipts; retired isolated-session leases are normalized by the offline converter into UUID-owned cleanup facts.
+Limits are 25 attempted calls, 64 KiB source/final JSON, 1 MiB per IPC message, 8 MiB cumulative IPC, and a 120-second default/300-second maximum deadline. `lib/input-modes/types.ts` owns the maximum shared by the public code schema and runner. `browser()` returns a canonical observation. `emit` selects JSON; `emitImage` selects a cell-local verified image handle, with file identity rechecks and normal inline limits. `lib/orchestration/script-mode.ts` aggregates selected output, failures, and artifact receipts; retired isolated-session leases are normalized by the offline converter into UUID-owned cleanup facts.
 
 ### Ordered transitions and shared execution
 
-`lib/managed-session-policy-lock.ts` supplies cooperating-process execution coordination keyed by the **actual socket context**, canonical namespace, and session, separate from existing managed-daemon policy checks. The lock spans direct helper/action/state work and an entire code cell. Fresh replacement and multi-identity cleanup acquire sorted identity sets; namespace-wide direct close uses an exclusive namespace barrier. Existing local queues and branch-generation checks still protect in-process ownership/replay. Independent identities remain concurrent. Direct calls bound coordination waits using the existing configured/command-aware timeout, then retain their native subprocess and Electron action watchdogs. Code owns a whole-cell deadline, including local queue waits. Independently bounded cleanup can borrow an already-held covered claim after cancellation, but cannot acquire a new identity or release the outer claim.
+`lib/managed-session-policy-lock.ts` supplies cooperating-process execution coordination keyed by the **actual socket context**, canonical namespace, and session, separate from existing managed-daemon policy checks. The lock spans direct helper/action/state work and an entire code cell. Fresh replacement and multi-identity cleanup acquire sorted identity sets; namespace-wide direct close uses an exclusive namespace barrier. `lib/orchestration/execution-queue.ts` owns the existing local managed/artifact queues and keyed namespace barriers; branch-generation checks still protect in-process ownership/replay. Independent identities remain concurrent. Direct calls bound coordination waits using the existing configured/command-aware timeout, then retain their native subprocess and Electron action watchdogs. Code owns a whole-cell deadline, including local queue waits. Independently bounded cleanup can borrow an already-held covered claim after cancellation, but cannot acquire a new identity or release the outer claim.
 
 All participating Pi processes must restart with the updated package. The lock is not a browser transaction, rollback, or a guarantee against humans, third-party native clients, older extensions, or separately named sessions attached to one external Chrome. Separate tool calls still need workflow coordination.
 
-`lib/browser-transcript.ts` defines one canonical `data.event` format and optional once-stored `data.snapshot`. Direct, advanced, code and Electron host operations record begin/finish receipts before dispatch and after observed effects, using outer tool-call ID plus inner index and a unique operation ID. The shared page reducer retains an inaccessible candidate during unresolved work and requires explicit reuse/replace/invalidate/unknown disposition. Ordinary results omit unchanged maps and unrelated artifact receipts; journal events carry redacted artifact-row changes in commit order. Final rendering queues actual spill writes and manifest publication, allowing unrelated small observations to finish while another namespace holds its artifact/lifecycle operation. Native lifecycle evidence is retained before presentation/export. Failed begin blocks dispatch; failed finish stops dependent work and requires inspection without mutation replay. A named persistent journal requires actual publication even before Pi's first conversation. Disabled/no-file sessions use the native current in-memory ancestry for direct browser work without claiming durability; code still requires a published intent journal. Observation-only artifact receipts are optional without a published journal, so sessionless local results retain complete redacted private spills and selected files. Code lifecycle joins include outer finalization, and the shared generation guard keeps prior-branch observation spills process-private and prevents their artifact publication onto the new branch. JavaScript variables are never persisted.
+`lib/browser-transcript.ts` defines one canonical `data.event` format and optional once-stored `data.snapshot`. Direct, advanced, code and Electron host operations record begin/finish receipts before dispatch and after observed effects, using outer tool-call ID plus inner index and a unique operation ID. The shared page reducer retains an inaccessible candidate during unresolved work and requires explicit reuse/replace/invalidate/unknown disposition. Ordinary results omit unchanged maps and unrelated artifact receipts; journal events carry redacted artifact-row changes in commit order. Final rendering queues actual spill writes and manifest publication, allowing unrelated small observations to finish while another namespace holds its artifact/lifecycle operation. `lib/orchestration/browser-run/artifact-merge.ts` preserves concurrent three-way manifest updates and recording lifecycle order. Native lifecycle evidence is retained before presentation/export. Failed begin blocks dispatch; failed finish stops dependent work and requires inspection without mutation replay. A named persistent journal requires actual publication even before Pi's first conversation. Disabled/no-file sessions use the native current in-memory ancestry for direct browser work without claiming durability; code still requires a published intent journal. Observation-only artifact receipts are optional without a published journal, so sessionless local results retain complete redacted private spills and selected files. Code lifecycle joins include outer finalization, and the shared generation guard keeps prior-branch observation spills process-private and prevents their artifact publication onto the new branch. JavaScript variables are never persisted.
 
 `lib/browser-journal.ts` token-projects published envelopes and ancestry through public Pi file/header/leaf APIs, loading only winning snapshot definitions. It captures the selected leaf before asynchronous reads and validates that same branch through public `getEntry()` ancestry on both hosts. Capture-local admission reuses a validated append-only prefix while checking endpoint identity/parent and new suffixes; publication/durability checks remain independent. Startup/tree restoration uses one queued captured replay for branch state and cleanup leases, with one per-session launch-configuration fold. Stock official 1.0.0 still eagerly loads native history before extension startup. Legacy adapters live only in `lib/browser-session-conversion.ts`, which publishes a validated stopped separate copy while retaining the source. Native generation checks use PID/start and socket identity, never saved URL or delta revision alone. Filtered/helper captures share this check. Small owner-qualified launch receipts retain observed restore-key provenance; restart verifies the current native generation and key before treating that provenance as live. Full storage, migration and consumer-memory boundaries are documented in [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
 
@@ -64,7 +64,7 @@ All participating Pi processes must restart with the updated package. The lock i
 
 Native tool declarations share Browser namespace metadata and `outputSchema`; `structuredContent` reuses the bounded redacted observation or its existing compact/spill object. Loader inventory and normalized provider search keep their existing shapes. Internal ownership/replay details are not exported wholesale. This interoperates with host-selected native codemode without auto-enabling it or replacing the Browser VM. A path/handle is not native image data; verified content image blocks remain separate. Final results return native `isError` and retain prose failure notices while explicit JSON stays parseable and unchanged. Per-row TUI memoization skips unchanged formatting/Text updates without caching browser state or observations across calls.
 
-`orchestration/browser-run/screenshot-observation.ts` brackets standalone screenshots with CSS viewport/document/scroll/DPR/frame samples. Existing Pi image-dimension primitives measure saved pixels. Matching samples and dimensions can establish a crop mapping; changed, unmeasured batch, scrolled/ambiguous element, zoom, or frame-uncertain captures remain unknown. These samples are not an atomic capture guarantee. Native mouse input uses current viewport CSS pixels, not image pixels; full-page/element origin and any Pi resize must be accounted for separately. Unchanged conditional screenshots attach nothing. See [image observations](TOOL_CONTRACT.md#image-observations).
+`orchestration/browser-run/screenshot-observation.ts` brackets standalone screenshots with CSS viewport/document/scroll/DPR/frame samples. Existing Pi image-dimension primitives measure saved pixels. Matching samples and dimensions can establish a crop mapping; changed, unmeasured batch, scrolled/ambiguous element, zoom, or frame-uncertain captures remain unknown. These samples are not an atomic capture guarantee. Native mouse input uses current viewport CSS pixels, not image pixels; full-page/element origin and any Pi resize must be accounted for separately. Unchanged conditional screenshots attach nothing. Native Lightpanda engine metadata labels verified images as `rendering: "text"` through shared attachment handling, including batch/code. The existing standalone samples also recognize the Lightpanda browser brand without another probe or engine cache. Text-rendered images retain unknown geometry and no crop/scale mapping, even when synthetic dimensions match. See [image observations](TOOL_CONTRACT.md#image-observations).
 
 ### Agent-first UX
 
@@ -89,7 +89,7 @@ Config layers merge in that order: global, project, override. The shared policy
 
 `agent_browser_web_search` availability is conditional. Startup registration uses global, override, and environment fallback config without reading project-local config before Pi trust context exists; trusted project config can register the companion tool on `session_start`, and every execution reloads the final session config so `webSearch.enabled: false` still prevents a request even if a startup credential made the tool visible. A global disable is the normal user default and can still be overridden by project config or `PI_AGENT_BROWSER_CONFIG`; a project disable applies to one repo; an explicit `PI_AGENT_BROWSER_CONFIG` file with `webSearch.enabled: false` is the highest-priority hard disable for that run. Literal and env-backed sources must resolve before they make the tool available; command-backed sources are considered configured without running the command until tool execution, so secret managers do not slow startup or prompt unexpectedly. The tool resolves the selected key lazily, chooses Exa or Brave from available credentials (preferring Exa by default unless `webSearch.preferredProvider` says otherwise), then follows one provider-agnostic execution path through provider adapters for request building, HTTP JSON fetch, response normalization, and provider-specific detail fields. Exa search-type precedence is per-call value, merged config default, then `auto`; bounded Exa filters stay on the Exa adapter and explicit Exa-only options fail before a Brave request. The tool calls Exa `/search` with highlights plus a fixed primary-source/version/date/distinct-result system prompt, or Brave Search, then removes later exact normalized-URL duplicates while retaining provider order. It does not guess across distinct paths/query URLs or overfetch replacements; provider page dates remain clues rather than claimed crawl/version evidence. Compact result details report any `duplicatesRemoved` without exposing keys.
 
-Global/override package profile names with `policy: "always"` and executable defaults bootstrap inactive automatic root browsers through scoped native environment. Active roots retain native settings; paths, other policies, and project-only values remain advisory. Direct and code calls selecting that root share the same configuration. Unrelated explicit sessions and Electron launches retain their separate native/owned rules.
+Global/override package profile names with `policy: "always"` and executable defaults bootstrap inactive automatic root browsers through scoped native environment only when CLI → environment → native config resolves to Chrome. Lightpanda receives no wrapper Chrome defaults; explicit native settings are untouched. Active roots retain native settings; paths, other policies, and project-only values remain advisory. Direct and code calls selecting that root share the same configuration. Unrelated explicit sessions and Electron launches retain their separate native/owned rules.
 
 ### Prompt guidance budget
 
@@ -138,7 +138,7 @@ The optional `pi-change-working-dir` event protocol supplies one invocation exec
 
 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, 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; shared execution locks coordinate updated cooperating processes without a broker. An active older/fresh managed session keeps its existing lifecycle. A configured session has the same precedence over `fresh` as a literal `--session`; code follows the selected ordinary browser lifecycle; Electron launch retains its owned lifecycle. 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, only when the effective engine is Chrome. 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; shared execution locks coordinate updated cooperating processes without a broker. An active older/fresh managed session keeps its existing lifecycle. A configured session has the same precedence over `fresh` as a literal `--session`; code follows the selected ordinary browser lifecycle; Electron launch retains its owned lifecycle. 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
@@ -224,7 +224,7 @@ Input resolution replaces URL-less `open` with native `get url` before planning,
 `agent-browser` startup flags are sticky once a session is already running.
 The extension should surface that clearly and avoid hidden restart behavior.
 
-That means explicit startup-scoping flags like `--allowed-domains`, `--auto-connect`, `--args`, `--user-agent`, `--cdp`, `--enable`, `--executable-path`, `--webgpu`, `--no-webmcp`, `--headed`, `--init-script`, `--device`, `--namespace`, `--profile`, `--provider`, `-p`, `--restore`, `--restore-save`, restore check flags, `--session-name`, and `--state` should remain explicit upstream argv choices instead of being wrapped in extra hidden restart or cloning logic. The one deliberate exception is the env-only managed-session `AGENT_BROWSER_RESTORE` key above, which does not inject `--restore` into argv and therefore does not trip launch-scoped `sessionMode: "fresh"` recovery.
+That means explicit startup-scoping flags like `--allowed-domains`, `--auto-connect`, `--args`, `--user-agent`, `--cdp`, `--enable`, `--engine`, `--executable-path`, `--webgpu`, `--no-webmcp`, `--headed`, `--init-script`, `--device`, `--namespace`, `--profile`, `--provider`, `-p`, `--restore`, `--restore-save`, restore check flags, `--session-name`, and `--state` should remain explicit upstream argv choices instead of being wrapped in extra hidden restart or cloning logic. The one deliberate exception is the env-only managed-session `AGENT_BROWSER_RESTORE` key above, which does not inject `--restore` into argv and therefore does not trip launch-scoped `sessionMode: "fresh"` recovery.
 
 The wrapper may still apply narrow compatibility normalizations when observed behavior justifies them and the result remains thin, local, and opt-out. For example, OpenAI web properties and `dash.cloudflare.com` reject the default local `HeadlessChrome` user agent while the same flow works with a normal Chrome UA, so the extension injects a domain-specific fallback only when the caller did not already choose raw Chrome arguments, a custom user agent, headed mode, CDP, auto-connect, a provider-backed launch, or a non-Chrome engine through argv or matching upstream environment. Managed sessions retain the injected value as per-session wrapper state across helper calls and branch reload/resume. Active daemons omit both launch forms so upstream does not replace a launch-configured browser; a session proven inactive receives the retained compatibility launch values, including the same fixed compatibility value as a comma-safe Chrome launch argument covering tabs and SSO popups on supported native versions that do not inherit per-page CDP overrides. Wrapper-owned headed launches also default upstream periodic restore autosave off because agent-browser 0.33.2 collects non-current origins through visible temporary targets while holding the daemon state lock; save-on-close remains enabled, and an explicit `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` value opts in when the daemon launches. The effective interval is retained in owned-session state and transcript results; changing it in either direction on a running wrapper-owned headed daemon is rejected until close plus a fresh launch.
 
@@ -237,6 +237,7 @@ Implementation detail lives in `extensions/agent-browser/lib/launch-scoped-flags
 - **Command discovery:** Leading argv is scanned with a value-taking allowlist so known global flags and documented command flags consume their values before the upstream command word is identified. Missing-value prevalidation is intentionally limited to upstream global value flags; command-scoped flags and literal text are left to upstream parsing so values like `fill #field --password` are not rejected by wrapper heuristics before the CLI sees them. Upstream 0.35.0 and newer accept `--restore=<key>` but reject other global `--flag=value` tokens during normal command execution, so the wrapper rejects those unsupported assignments before they can be mistaken for command or artifact operands. Plain help/version inspection preserves exact caller argv because upstream accepts those top-level shapes. Nested batch rows do not parse global flags, so their equals forms never receive the top-level inspection or restore exceptions. When upstream adds new global flags that take values ahead of the command, extend both the command-discovery and prevalidation allowlists; when it adds command-specific flags, extend only command discovery/redaction as needed. A smaller set of global boolean flags may be followed by an optional `true`/`false` literal; when present, that literal is consumed as the flag value before command discovery continues.
 - **`--state` disambiguation:** Persisted browser `--state` before the command participates in launch-scoped validation and tab-correction hints. The same flag spelling after a `wait` command is excluded from startup-scoped detection so upstream help examples such as `wait @ref --state hidden` do not spuriously require `sessionMode: "fresh"` while an implicit session is active. As of the current upstream baseline, the parser still does not implement those `wait --state` examples as distinct wait modes, so agent-facing docs recommend `wait --fn` predicates for disappearance checks instead.
 - **`--auto-connect`:** Treated as launch-scoped only when enabled (`--auto-connect` bare or `true`). `--auto-connect false` is ignored for startup-scoped blocking so disabled attach hints do not force a fresh launch.
+- **`--engine`:** Treated as launch-scoped for Chrome and Lightpanda, using the same fresh-session recovery instead of letting native engine changes replace a running managed page. Caller-owned sessions remain native-owned. Chrome stays default; Lightpanda is opt-in with no bundle, second driver, emulation or automatic fallback. See [engine limits](COMMAND_REFERENCE.md#lightpanda-engine).
 - **`--webgpu`:** Treated as launch-scoped for both enabled and explicit `false` values. Enabled WebGPU selects upstream's platform-specific local-launch preset; explicit false can override an environment/config default and still belongs to a fresh browser launch. Upstream rejects enabled WebGPU with CDP, auto-connect, or provider launches.
 - **`--no-webmcp`:** Treated as launch-scoped for bare/`true` and explicit `false` values because it selects whether upstream 0.36.0 enables experimental WebMCP for a locally managed Chrome launch.
 - **`--headed`:** Treated as launch-scoped for both enabled and explicit `false` values so a visible-window choice cannot be silently ignored by an already-running managed session.
@@ -266,7 +267,7 @@ Upstream restore-state persistence remains upstream-owned. The wrapper passes an
 - subprocess execution and JSON parsing through `buildAgentBrowserProcessEnv` in `extensions/agent-browser/lib/process.ts`: copies the parent process environment so user-approved provider credentials and other runtime variables reach upstream, then applies wrapper overrides such as the managed socket directory and clamped default operation timeout
 - clear missing-binary errors
 - filtered `network requests --current-page` / `--current-origin` / `--current-url` preparation results use the same `redactPresentationData` credential redactor as ordinary diagnostics before populating `details.data` or writing `outputPath`
-- compact result summaries, including presentation-time redaction: stateful browser-context commands (`auth`, `cookies`, `storage`, `dialog`, `frame`, `state`) use field-aware value redaction and compact formatters, while other structured upstream JSON (for example `network`, `diff`, `trace` / `profiler` / `record`, `console` / `errors` / `highlight` / `inspect` / `clipboard`, `stream`, `dashboard`, and `chat`) is passed through `redactPresentationData` in `extensions/agent-browser/lib/results/presentation.ts` so model-facing `details.data` and batch roll-ups stay compact and do not echo bearer tokens, proxy passwords, or similar fields verbatim; `redactInvocationArgs` in `extensions/agent-browser/lib/runtime.ts` masks trailing values for sensitive global flags such as `--body`, `--headers`, `--password`, and `--proxy`, preserves positional rules for `cookies set` and `storage local|session set`, and nested `batch` steps use the same argv and error-body scrubbing before echoing commands or errors. Shared URL redaction covers SAMLRequest/SAMLResponse/RelayState and auth-context-only state/nonce at model/persisted-artifact boundaries while retaining exact internal page-target URLs; snapshot spills are redacted before disk writes
+- compact result summaries, including presentation-time redaction: stateful browser-context commands (`auth`, `cookies`, `storage`, `dialog`, `frame`, `state`) use field-aware value redaction and compact formatters, while other structured upstream JSON (for example `network`, `diff`, `trace` / `profiler` / `record`, `console` / `errors` / `highlight` / `inspect` / `clipboard`, `stream`, `dashboard`, and `chat`) is passed through `redactPresentationData` in `extensions/agent-browser/lib/results/presentation.ts` so model-facing `details.data` and batch roll-ups stay compact and do not echo bearer tokens, proxy passwords, or similar fields verbatim; `redactInvocationArgs` in `extensions/agent-browser/lib/runtime.ts` masks trailing values for sensitive global flags such as `--body`, `--headers`, `--password`, and `--proxy`, preserves positional rules for `cookies set` and `storage local|session set` while distinguishing native `--curl` file-import operands from inline cookie values (including failed batch diagnostics), and nested `batch` steps use the same argv and error-body scrubbing before echoing commands or errors. Shared URL redaction covers SAMLRequest/SAMLResponse/RelayState and auth-context-only state/nonce at model/persisted-artifact boundaries while retaining exact internal page-target URLs; snapshot spills are redacted before disk writes
 - bounded machine-readable outcome metadata on tool `details` (`resultCategory`, `successCategory`, `failureCategory`, optional `nextActions`, optional `pageChangeSummary` with observed-vs-dispatched evidence and per-step summaries on `batch`, optional `artifactVerification` with the same shape on each successful `batchSteps[]` row) so agents can branch without parsing prose; enums, classifier precedence, and generic follow-up payloads are implemented under `extensions/agent-browser/lib/results/` in focused modules (`contracts.ts` for shared types, `categories.ts` for `classifyAgentBrowserSuccessCategory` / `classifyAgentBrowserFailureCategory` / `buildAgentBrowserResultCategoryDetails`, `action-recommendations.ts` for `buildAgentBrowserNextActions`, `next-actions.ts` for the `AgentBrowserNextAction` shape and merge helpers, `recovery-actions.ts` for recovery id registries and `buildRecoveryNextActions`, `network.ts` for `classifyNetworkRequestFailure` / `summarizeNetworkFailures`, and related helpers). Per-session tab target, `refSnapshot` alignment, invalidation, and tab pinning observations flow through `extensions/agent-browser/lib/session-page-state.ts` from `extensions/agent-browser/index.ts`. Compact page-change summaries and artifact verification rollups are built in `extensions/agent-browser/lib/results/presentation.ts` (`buildPageChangeSummary`, `buildArtifactVerificationSummary`), and the human contract lives in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). Final public results return native `isError` after all wrapper reclassifications, without a `tool_result` repair hook. Prose retains the visible category notice; explicit parseable JSON stays unchanged. `lib/native-output.ts` and `finalizeAgentBrowserFailure` in `lib/pi-tool-rendering.ts` keep structured observations, transcript status and TUI affordances aligned (transcript semantics in the same contract doc)
 - inline screenshots/images for the plain `screenshot` command; other image-like saves (for example `diff screenshot`) still appear in `details.artifacts` and summaries but are not auto-inlined as Pi image attachments (see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details))
 - lightweight session convenience