pi-agent-browser-native 0.6.6 → 0.6.7

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

@@ -1,22 +1,43 @@
-import { readFile, stat } from "node:fs/promises";
+import { open, readFile, stat } from "node:fs/promises";
 import { extname, resolve } from "node:path";
 import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
+import { getExplicitArtifactDestination } from "../../orchestration/browser-run/artifact-paths.js";
 import { isRecord, parsePositiveInteger } from "../../parsing.js";
+import { extractUpstreamCommandTokens } from "../../runtime.js";
 import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, isPendingRecordingCommand, mergeSessionArtifactManifest, } from "../artifact-manifest.js";
 import { classifyAgentBrowserSuccessCategory } from "../categories.js";
-const IMAGE_EXTENSION_TO_MIME_TYPE = {
-    ".gif": "image/gif",
-    ".jpeg": "image/jpeg",
-    ".jpg": "image/jpeg",
-    ".png": "image/png",
-    ".webp": "image/webp",
-};
+const PNG_HEADER = Buffer.from("89504e470d0a1a0a0000000d49484452", "hex");
 const INLINE_IMAGE_MAX_BYTES_ENV = "PI_AGENT_BROWSER_INLINE_IMAGE_MAX_BYTES";
 const DEFAULT_INLINE_IMAGE_MAX_BYTES = 5 * 1_024 * 1_024;
 const ARTIFACT_MTIME_TOLERANCE_MS = 2_000;
-function getImageMimeType(filePath) {
-    const extension = extname(filePath).toLowerCase();
-    return IMAGE_EXTENSION_TO_MIME_TYPE[extension];
+function getImageMimeType(bytes) {
+    if (bytes.length < 16)
+        return undefined;
+    if (bytes.subarray(0, 16).equals(PNG_HEADER))
+        return "image/png";
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff && bytes[3] !== 0xf7)
+        return "image/jpeg";
+    if (["GIF87a", "GIF89a"].includes(bytes.toString("utf8", 0, 6)))
+        return "image/gif";
+    if (bytes.toString("utf8", 0, 4) === "RIFF" && bytes.toString("utf8", 8, 12) === "WEBP")
+        return "image/webp";
+    return undefined;
+}
+async function getFileImageMimeType(path) {
+    try {
+        const file = await open(path, "r");
+        try {
+            const bytes = Buffer.alloc(16);
+            const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+            return getImageMimeType(bytes.subarray(0, bytesRead));
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
 }
 function getInlineImageMaxBytes(env = process.env) {
     return parsePositiveInteger(env[INLINE_IMAGE_MAX_BYTES_ENV]) ?? DEFAULT_INLINE_IMAGE_MAX_BYTES;
@@ -74,17 +95,6 @@ const PATH_FIELD_CANDIDATES = [
     "profilePath",
     "videoPath",
 ];
-const ARTIFACT_EXTENSION_TO_MEDIA_TYPE = {
-    ".cpuprofile": "application/json",
-    ".har": "application/json",
-    ".html": "text/html",
-    ".json": "application/json",
-    ".pdf": "application/pdf",
-    ".txt": "text/plain",
-    ".webm": "video/webm",
-    ".zip": "application/zip",
-    ...IMAGE_EXTENSION_TO_MIME_TYPE,
-};
 function isDownloadWaitSubcommand(subcommand) {
     return subcommand === "--download" || subcommand === "-d";
 }
@@ -153,6 +163,7 @@ async function buildFileArtifactMetadata(options) {
     const pendingRecording = isPendingRecordingCommand(options.commandInfo.command, options.commandInfo.subcommand, kind);
     let exists;
     let sizeBytes;
+    let mediaType;
     let stale = false;
     let updatedAtMs;
     if (!pendingRecording) {
@@ -161,6 +172,7 @@ async function buildFileArtifactMetadata(options) {
             exists = true;
             sizeBytes = fileStats.size;
             updatedAtMs = fileStats.mtimeMs;
+            mediaType = fileStats.isFile() ? await getFileImageMimeType(absolutePath) : undefined;
             const commandCreatesArtifact = !(options.commandInfo.command === "wait" && isDownloadWaitSubcommand(options.commandInfo.subcommand));
             stale = commandCreatesArtifact && artifactMtimeIsOutsideCommandWindow(updatedAtMs, options.artifactMinUpdatedAtMs, options.artifactMaxUpdatedAtMs);
         }
@@ -176,11 +188,11 @@ async function buildFileArtifactMetadata(options) {
         exists,
         extension,
         kind,
-        mediaType: extension ? ARTIFACT_EXTENSION_TO_MEDIA_TYPE[extension] : undefined,
+        mediaType,
         namespace: options.namespace,
         path: displayPath,
         recordingState: pendingRecording ? "openRecording" : undefined,
-        requestedPath: options.artifactRequest?.path,
+        requestedPath: options.artifactRequest?.path ?? getExplicitArtifactDestination(extractUpstreamCommandTokens(options.commandInfo.commandTokens ?? [])),
         session: options.sessionName,
         sizeBytes,
         status: pendingRecording ? "pending" : exists === false ? "missing" : stale ? "stale" : options.artifactRequest?.status ?? "saved",
@@ -212,7 +224,7 @@ async function buildPreviousRestartRecordingArtifact(options) {
             exists: true,
             extension: previousRecording.extension ?? (extname(absolutePath).toLowerCase() || undefined),
             kind: "video",
-            mediaType: previousRecording.mediaType,
+            mediaType: fileStats.isFile() ? await getFileImageMimeType(absolutePath) : undefined,
             namespace: previousRecording.namespace ?? options.namespace,
             path: previousRecording.path,
             requestedPath: previousRecording.requestedPath,
@@ -232,7 +244,6 @@ async function buildPreviousRestartRecordingArtifact(options) {
             exists: false,
             extension: previousRecording.extension ?? (extname(absolutePath).toLowerCase() || undefined),
             kind: "video",
-            mediaType: previousRecording.mediaType,
             namespace: previousRecording.namespace ?? options.namespace,
             path: previousRecording.path,
             requestedPath: previousRecording.requestedPath,
@@ -449,13 +460,12 @@ export function formatArtifactMetadataLines(artifacts) {
             return [
                 `${formatArtifactLabel(artifact)}: ${artifact.path}`,
                 `Artifact type: ${artifact.kind}`,
-                `Requested path: ${artifact.requestedPath ?? artifact.path}`,
+                artifact.requestedPath ? `Requested path: ${artifact.requestedPath}` : undefined,
                 `Absolute path: ${artifact.absolutePath}`,
                 "Exists: pending until record stop",
                 `Status: ${artifact.status ?? "pending"}`,
                 `Recording state: ${artifact.recordingState ?? "openRecording"}`,
                 `Will exist on stop: ${artifact.willExistOnStop !== false}`,
-                artifact.subcommand === "start" ? "Page state: record start uses a fresh active page for video capture; prior in-page DOM and JavaScript state does not carry over. Take a fresh snapshot before continuing." : undefined,
                 artifact.session ? `Session: ${artifact.session}` : undefined,
                 artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
                 `Machine data: details.artifacts[${index}]`,
@@ -464,14 +474,14 @@ export function formatArtifactMetadataLines(artifacts) {
         return [
             `${formatArtifactLabel(artifact)}: ${artifact.path}`,
             `Artifact type: ${artifact.kind}`,
-            `Requested path: ${artifact.requestedPath ?? artifact.path}`,
+            artifact.requestedPath ? `Requested path: ${artifact.requestedPath}` : undefined,
             `Absolute path: ${artifact.absolutePath}`,
             `Exists: ${artifact.exists === true}`,
             artifact.exists === false ? "not found on disk" : undefined,
             typeof artifact.sizeBytes === "number" ? `Size: ${formatByteCount(artifact.sizeBytes)}` : undefined,
             typeof artifact.sizeBytes === "number" ? `Size bytes: ${artifact.sizeBytes}` : undefined,
             `Status: ${artifact.status ?? (artifact.exists === false ? "missing" : "saved")}`,
-            artifact.tempPath ? `Temp path: ${artifact.tempPath}` : undefined,
+            artifact.tempPath ? `Reported path: ${artifact.tempPath}` : undefined,
             artifact.mediaType ? `Media type: ${artifact.mediaType}` : undefined,
             artifact.session ? `Session: ${artifact.session}` : undefined,
             artifact.cwd ? `CWD: ${artifact.cwd}` : undefined,
@@ -519,21 +529,10 @@ export function extractImagePath(commandInfo, cwd, data) {
     if (!isTrustedScreenshotOutput(commandInfo)) {
         return undefined;
     }
-    if (typeof data === "string") {
-        const mimeType = getImageMimeType(data);
-        return mimeType ? resolve(cwd, data) : undefined;
-    }
-    if (!isRecord(data) || typeof data.path !== "string") {
-        return undefined;
-    }
-    const mimeType = getImageMimeType(data.path);
-    return mimeType ? resolve(cwd, data.path) : undefined;
+    const path = typeof data === "string" ? data : isRecord(data) && typeof data.path === "string" ? data.path : undefined;
+    return path?.trim() && !isNonFileArtifactPathCandidate(path) ? resolve(cwd, path) : undefined;
 }
 export async function attachInlineImage(presentation, imagePath) {
-    const mimeType = getImageMimeType(imagePath);
-    if (!mimeType) {
-        return presentation;
-    }
     try {
         const fileStats = await stat(imagePath);
         const inlineImageMaxBytes = getInlineImageMaxBytes();
@@ -543,6 +542,9 @@ export async function attachInlineImage(presentation, imagePath) {
             return presentation;
         }
         const file = await readFile(imagePath);
+        const mimeType = getImageMimeType(file);
+        if (!mimeType)
+            return presentation;
         presentation.content.push({ type: "image", data: file.toString("base64"), mimeType });
         presentation.imagePath = imagePath;
         return presentation;

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

@@ -45,11 +45,11 @@ function buildTabSnapshotRecoveryAction(options) {
         });
     }
     return buildNextToolAction({
-        args: options.sessionArgs(["batch"]),
+        args: options.sessionArgs(["batch", "--bail"]),
         id: options.id,
-        reason: `${options.reason} The batch selects the stable tab before snapshotting.`,
-        safety: `${options.safety} The snapshot retry is atomic with tab selection, so it does not assume the intended tab is already active.`,
-        stdin: JSON.stringify([["tab", options.tabId], ["snapshot", "-i"]]),
+        reason: `${options.reason} The batch selects and verifies the stable tab before snapshotting.`,
+        safety: `${options.safety} A failed tab selection or URL check stops before the snapshot.`,
+        stdin: JSON.stringify([["tab", options.tabId], ["get", "url"], ["snapshot", "-i"]]),
     });
 }
 export function buildRecoveryNextActions(recovery) {

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

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 import { extractUpstreamCommandTokens, findCommandStartIndex, parseArgvDescriptor, parseCommandInfo, } from "./argv-descriptor.js";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
-import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, getBooleanFlagValue, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, PREVALIDATED_VALUE_FLAGS, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
+import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, getBooleanFlagValue, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, PREVALIDATED_VALUE_FLAGS, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences, stripUpstreamGlobalFlags, } from "./argv-grammar.js";
 import { needsManagedSession } from "./command-policy.js";
 import { isCloseAllCommand, isCloseCommand, isOpenNavigationCommand } from "./command-taxonomy.js";
 import { hasLaunchScopedFlagToken, LAUNCH_SCOPED_FLAG_DEFINITIONS, LAUNCH_SCOPED_FLAG_LABEL, } from "./launch-scoped-flags.js";
@@ -607,6 +607,18 @@ function getUnsupportedInlineWaitDownloadError(args) {
         return undefined;
     return `agent-browser ${TARGET_AGENT_BROWSER_VERSION} does not support \`wait --download=<path>\`. Pass the optional path as a separate argument: \`wait --download <path>\` (or \`wait -d <path>\`).`;
 }
+function getBareNoSandboxValidationError(args, batchStep) {
+    // Native batch rows skip global parsing; --args is effective only on the outer CLI call.
+    const tokens = batchStep ? args : stripUpstreamGlobalFlags(args);
+    const command = tokens[0];
+    const leading = command === "--no-sandbox";
+    if (!leading && (!isOpenNavigationCommand(command) || !tokens.slice(1).includes("--no-sandbox")))
+        return undefined;
+    const explanation = leading
+        ? "`--no-sandbox` is not an agent-browser command."
+        : `\`--no-sandbox\` is ignored as an option by \`${command}\`.`;
+    return `${explanation} It is a Chromium launch argument. Put it in top-level \`--args\` and start a fresh session: { args: ["--args", "--no-sandbox", "open", "https://example.com"], sessionMode: "fresh" }. For batch, put --args before batch, not inside a step.`;
+}
 export function validateToolArgs(args, options = {}) {
     if (args.length === 0) {
         return "`args` must contain at least one agent-browser command token.";
@@ -623,7 +635,8 @@ export function validateToolArgs(args, options = {}) {
     const invalidValueFlag = inspection ? undefined : getInvalidValueFlagDetails(args, !options.batchStep);
     if (invalidValueFlag?.reason === "unsupported-assignment")
         return formatInvalidValueFlagError(invalidValueFlag, options.batchStep);
-    return getBareMcpValidationError(args) ?? getSingleKeyCommandValidationError(args) ?? getUnsupportedInlineWaitDownloadError(args);
+    return (inspection ? undefined : getBareNoSandboxValidationError(args, options.batchStep === true))
+        ?? getBareMcpValidationError(args) ?? getSingleKeyCommandValidationError(args) ?? getUnsupportedInlineWaitDownloadError(args);
 }
 function getInvalidValueFlagDetails(args, allowRestoreAssignment = true) {
     for (let index = 0; index < args.length; index += 1) {
@@ -885,6 +898,9 @@ export function buildExecutionPlan(args, options) {
         managedSessionName = options.freshSessionName;
         sessionName = options.freshSessionName;
     }
+    if (commandInfo.command !== undefined && !sessionName && !explicitNamespacePresent) {
+        namespace = resolveAgentBrowserNamespace(args, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+    }
     const targetsActiveManagedSession = options.managedSessionActive
         && sessionName
         && getAgentBrowserSessionIdentityKey(sessionName, namespace) === getAgentBrowserSessionIdentityKey(options.managedSessionName, options.managedSessionNamespace);

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

@@ -1,7 +1,7 @@
 import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
 import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "./argv-grammar.js";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
-import { isCloseAllCommand, isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWebMcpPageMutationCommand } from "./command-taxonomy.js";
+import { isCloseAllCommand, isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWebMcpPageMutationCommand, isWindowOrDiffPageTransitionCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
 import { getEditableRefEvidence } from "./results/editable-ref-evidence.js";
 import { enrichSnapshotRefEntries, getSnapshotRefEntries } from "./results/snapshot-refs.js";
@@ -24,8 +24,8 @@ export function normalizeSessionTabTarget(target) {
     if (!target) {
         return undefined;
     }
-    const url = normalizeComparableUrl(target.url);
-    if (!url) {
+    const url = target.url?.trim();
+    if (!url || normalizeComparableUrl(url) === undefined) {
         return undefined;
     }
     const title = target.title?.trim();
@@ -38,7 +38,7 @@ export function isAboutBlankSessionTabTarget(target) {
     return isAboutBlankUrl(target?.url);
 }
 export function commandExplicitlyTargetsAboutBlank(commandTokens) {
-    return commandTokens.some((token) => isAboutBlankUrl(token));
+    return (commandTokens[0] === "window" && commandTokens[1] === "new") || commandTokens.some((token) => isAboutBlankUrl(token));
 }
 export function targetsMatch(left, right) {
     if (!left || !right)
@@ -90,10 +90,15 @@ export function extractSessionTabTargetFromBatchResults(data) {
     let currentTarget;
     let pendingTitle;
     for (const item of data) {
-        if (!isRecord(item) || item.success === false) {
+        if (!isRecord(item))
             continue;
+        const [name, subcommand] = extractUpstreamCommandTokens(extractBatchResultCommand(item));
+        if (isWindowOrDiffPageTransitionCommand(name, subcommand)) {
+            currentTarget = undefined;
+            pendingTitle = undefined;
         }
-        const [name, subcommand] = extractBatchResultCommand(item);
+        if (item.success === false)
+            continue;
         const result = item.result;
         if (isCloseCommand(name)) {
             currentTarget = undefined;
@@ -213,6 +218,9 @@ export function buildPageTransitionRefSnapshotInvalidation(summary) {
 export function getCommandRefSnapshotInvalidation(commandTokens) {
     if (isRecordPageTransitionCommand(commandTokens))
         return buildPageTransitionRefSnapshotInvalidation();
+    if (isWindowOrDiffPageTransitionCommand(commandTokens[0], commandTokens[1])) {
+        return buildPageTransitionRefSnapshotInvalidation("A window new or diff url command replaced or navigated the active page and invalidated prior refs. Run snapshot -i before using page-scoped refs.");
+    }
     if (isWebMcpPageMutationCommand(commandTokens)) {
         return buildPageTransitionRefSnapshotInvalidation("A WebMCP invoke, result, or cancel command can mutate, rerender, or navigate the page, so the prior snapshot refs were invalidated. Run snapshot -i before using page-scoped refs.");
     }
@@ -228,7 +236,7 @@ export function extractLatestRefSnapshotStateFromBatchResults(data) {
     for (const item of data) {
         if (!isRecord(item))
             continue;
-        const commandTokens = extractBatchResultCommand(item);
+        const commandTokens = extractUpstreamCommandTokens(extractBatchResultCommand(item));
         const [name] = commandTokens;
         if (item.success !== false && isCloseCommand(name)) {
             latestState = undefined;
@@ -372,9 +380,10 @@ export class SessionPageState {
             }
             const tabTarget = getRestoredSessionTabTarget(details, command, subcommand);
             const tabTargetUnknown = details.sessionTabTargetUnknown === true;
+            const reopenPending = typeof details.sessionTabReopenPending === "boolean" ? details.sessionTabReopenPending : undefined;
             const refSnapshotInvalidation = getRestoredRefSnapshotInvalidation(details, command);
             const refSnapshot = refSnapshotInvalidation ? undefined : getRestoredRefSnapshot(details);
-            if (!tabTarget && !tabTargetUnknown && !refSnapshotInvalidation && !refSnapshot)
+            if (!tabTarget && !tabTargetUnknown && !refSnapshotInvalidation && !refSnapshot && reopenPending === undefined)
                 continue;
             restoredOrder += 1;
             if (tabTargetUnknown) {
@@ -389,8 +398,11 @@ export class SessionPageState {
             }
             if (tabTarget) {
                 state.tabTargetUnknownOrders.delete(sessionKey);
-                state.tabTargets.set(sessionKey, { order: restoredOrder, target: tabTarget });
+                state.tabTargets.set(sessionKey, { order: restoredOrder, reopenPending: state.tabTargets.get(sessionKey)?.reopenPending, target: tabTarget });
             }
+            const currentTarget = state.tabTargets.get(sessionKey);
+            if (currentTarget && reopenPending !== undefined)
+                currentTarget.reopenPending = reopenPending;
             if (refSnapshotInvalidation) {
                 state.refSnapshots.delete(sessionKey);
                 state.refSnapshotInvalidations.set(sessionKey, { ...refSnapshotInvalidation, order: restoredOrder });
@@ -421,6 +433,7 @@ export class SessionPageState {
             return {};
         return {
             pinningReason: this.tabPinningReasons.get(sessionName),
+            ...(this.tabTargets.get(sessionName)?.reopenPending !== undefined ? { tabReopenPending: this.tabTargets.get(sessionName)?.reopenPending } : {}),
             refSnapshot: stripRefSnapshotOrder(this.refSnapshots.get(sessionName)),
             refSnapshotInvalidation: stripRefSnapshotInvalidationOrder(this.refSnapshotInvalidations.get(sessionName)),
             ...(this.tabTargetUnknownOrders.has(sessionName) ? { tabTargetUnknown: true } : {}),
@@ -433,9 +446,15 @@ export class SessionPageState {
             return { ...this.get(options.sessionName), applied: false, stale: true };
         }
         this.tabTargetUnknownOrders.delete(options.sessionName);
-        this.tabTargets.set(options.sessionName, { order: options.update, target: options.target });
+        this.tabTargets.set(options.sessionName, { order: options.update, reopenPending: current?.reopenPending, target: options.target });
         return { ...this.get(options.sessionName), applied: true };
     }
+    setTabReopenPending(options) {
+        const current = this.tabTargets.get(options.sessionName);
+        if (!current || !shouldApplyTabTargetUpdate(current, this.tabTargetUnknownOrders.get(options.sessionName), options.update))
+            return;
+        this.tabTargets.set(options.sessionName, { ...current, order: options.update, reopenPending: options.pending });
+    }
     applyRefSnapshot(options) {
         if (!shouldApplyRefStateUpdate({
             currentInvalidation: this.refSnapshotInvalidations.get(options.sessionName),

package/docs/ARCHITECTURE.md

@@ -69,6 +69,8 @@ Browser isolation is separate from language isolation. A pre-spawn Pi custom ent
 
 ### Agent-first UX
 
+Artifact directory preparation has one filesystem-error boundary inside the existing cleanup/finally path: direct, stdin and raw-argv failures return structured validation and the attempted directory without launching the requested command. Raw batch strings and argv-over-stdin precedence stay native; absolute artifact paths avoid differing daemon/Pi working directories. Artifact metadata retains known requested and reported/resolved paths without a new canonicalization pass. A bounded 16-byte regular-file header read recognizes the existing PNG/JPEG/GIF/WebP formats; inline screenshots use the same classifier under their existing byte limit, and unknown MIME types are omitted. Recording page warnings use the shared transition predicate and confirmed CLI/reached-row evidence through the existing prose/JSON warning path, independently of conservative ref-state invalidation after an uncertain batch.
+
 The primary UX is the agent calling the tool directly.
 
 That means:
@@ -157,6 +159,7 @@ V1 ownership rule:
 Practical policy:
 - preserve the current branch-visible extension-managed session across `/reload`, exact-session relaunch, `/resume`, and Pi 0.84.0+ `session_tree` branch transitions so persisted sessions can keep following the live browser after lifecycle changes
 - close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone
+- after branch restore, use the existing locked daemon inspection to distinguish a confirmed inactive wrapper-owned daemon from a live, unknown, or unavailable one. For compatible automatic managed restore only, keep the pending reopen in ordered session page state and persist it as `sessionTabReopenPending`. Non-page calls such as `tab list` and explicit HTTP reads can start a daemon without fulfilling it, including across branch/reload replay. Before the first current-page operation (`get url`, history commands and relative `pushstate` included), reopen the complete recorded URL with native `open`, invalidate old refs with the existing `page-transition` state, and verify the actual tab. Native `open` resets frame scope. Consume the obligation on that attempt or an executed explicit context/navigation/close command, not an unreached batch row; a failed open does not permit repeated navigation of a now-live browser. After the reopen CLI starts, cancellation returns a structured `aborted` result through the ordinary result path with the exact namespace/session, consumed marker and ref invalidation; it does not throw away replay state or run later browser helpers. Cancellation before the CLI starts does not consume the pending reopen. Internal URLs retain their fragments while tab/ref comparisons remain fragment-insensitive and presentation keeps normal redaction. Older transcripts cannot recover a fragment they did not record. Caller-owned/attached browsers and restore-disabled sessions do not take this path; live wrong-tab recovery still only selects an existing target. Reopening reloads the URL, not unsaved forms, JavaScript memory, or history. There is no second restore store or lifecycle lock.
 - set an idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures, and apply that same `AGENT_BROWSER_IDLE_TIMEOUT_MS` value to every upstream subprocess (including wrapper helper snapshots, tab lists, and navigation-summary reads) because changing the launch environment between calls can make upstream restart the background browser, discard the active tab, and invalidate fresh refs
 - for wrapper-owned implicit sessions only, set a transcript- and checkout-scoped `AGENT_BROWSER_RESTORE` key on compatible calls so cookies and web storage can survive idle shutdown, reload, and resume. Explicit caller sessions, restore/state choices, profiles, upstream config, file access, launch arguments, environment variables, local pages, output paths, and close arguments remain upstream-owned and pass through unchanged. `piab-*` names are not reserved; session/state lists and restore identifiers are not filtered or redacted. The wrapper validates only its automatic restore checkout/storage identity and coordinates same-daemon reuse so its own restore pools cannot mix. Ambiguous page-target transitions still require live `get url` verification before content calls. The current v3 ticket-claim lock is the only managed-daemon coordination protocol; no earlier lock bridge or compatibility path remains.
 - redact snapshot spill payloads before writing them, clean up process-private temp spill artifacts on shutdown, and keep persisted-session spill files in a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` stays usable after reload/resume without unbounded growth
@@ -172,16 +175,16 @@ Practical policy:
 - expose `details.browserWindow` and one visible login handoff only when a successful first/fresh local wrapper-managed headed result, including `batch`, is not an attachment and has upstream `lifecycle.effectiveLaunch.browserLaunched: true` and a `created`/`replaced` managed-session outcome. Keep `visibility: "unverified"`: this is launch evidence, never a claim about the user's OS desktop
 - leave explicit caller-provided `--session` choices alone unless the caller closes them explicitly, but before any content-bearing read or interaction against a caller-owned explicit session, live-probe that session with `get url` instead of trusting missing or stale transcript page state; hold the effective canonical namespace/session queue from that probe through semantic snapshot resolution and the main command so another same-instance call cannot change tabs in between. Non-bail batch analysis retains every possible page left by a failed transition up to a fixed bound and blocks later content only when the target is unverified; exceeding the bound also fails closed to exact `batch --bail` guidance. Nested `batch` steps remain unsupported, and raw batch command strings mirror upstream's ASCII-space tokenizer, including quote/backslash handling, rather than splitting on other Unicode whitespace.
 - after profiled `open` / `goto` / `navigate` calls, verify the active tab still matches the returned page URL and best-effort switch back when restored profile tabs steal focus
-- once the wrapper observes tab-drift risk for a session (profile restore correction, overlapping stale opens, or restored session state), later active-tab commands may synthesize a tiny upstream `batch` that re-selects that tab and then runs the requested command in the same upstream invocation; routine same-session commands avoid `tab list` preflights to reduce probes that can perturb upstream click behavior
+- once the wrapper observes tab-drift risk for a session (profile restore correction, overlapping stale opens, or restored session state), later active-tab commands verify the intended tab under the existing session queue before semantic/ref helpers and user commands. Native selection runs only when the intended tab is not already active, because upstream selection clears refs and frame scope even on same-tab reselection. Missing targets, failed selection, and post-selection target mismatches fail before user commands. Caller argv/stdin and native `--pin-tab` / `--no-pin-tab` preferences remain unchanged. Local commands, live `get url`, explicit HTTP `read <url>` (including its flags), URL `a11y`/`vitals`/`web-vitals`, `diff url`, `window new`, URL-bearing recording commands, and explicit tab/navigation/`connect`/`state load` recovery do not require the old target; history back/forward/reload, `pushstate`, and page-content operations still do. The same classifier scans effective batch rows past non-page prefixes until a page dependency or explicit context change, without rewriting user rows or changing bail behavior. For `window new` and `diff url`, observe the resulting URL instead of retaining the old target or treating the requested second URL as redirect evidence. Fold only reached native batch rows when available, discard observations and refs from before those transitions, and let later successful snapshots rebuild refs even when another batch row fails. Retain an observed blank destination after either command instead of recovering the old page; if no final target is observed, use the existing unknown-target state. Caller batch arguments, stdin and bail behavior stay unchanged. Routine same-session commands avoid `tab list` preflights
 - for sessions with observed tab-drift risk, after a successful command on a known tab target, the wrapper may best-effort restore that same target again if restored/background tabs steal focus after the command returns; routine same-session commands skip this post-command `tab list` probe
 - after successful standalone tab selection or `tab close`, read the now-active URL and fresh non-blank title—even when two tabs share a URL—before updating per-session page state because upstream selection/close payloads are not sufficient page-target evidence; retain an explicitly selected existing `about:blank` tab or a blank tab revealed by close instead of treating either as accidental drift
-- keep a per-session `refSnapshot` aligned with the last successful `snapshot` (including refs merged from a successful `batch` by taking the last successful `snapshot` step in batch result order): restore it from persisted tool `details` when reloading, resuming, or moving to a different Pi session-tree branch, store bounded ref role/name metadata from the same snapshot for wrapper-side current-ref diagnostics, drop it on successful close commands (`close`, `quit`, or `exit`), replace it with a persisted `page-transition` invalidation after any upstream-executed `record start` attempt (direct or batch; upstream swaps the session to a fresh active page before its already-active check, so failed starts count), a `record restart` with a URL operand, or WebMCP `invoke` / `result` / `cancel` (these page-provided tools can mutate, rerender, or navigate; when a spawned `batch` yields no parseable result rows, for example after a wrapper timeout, planned transition steps still record the invalidation), or after a failed non-batch transition command (`eval`, `back`, `forward`, `reload`, `connect`, `state load`, `tab` selection) whose live URL re-verification probe observed the page (a failed transition can still have mutated or replaced the document before throwing, so keeping the verified URL must not keep the prior refs; transcript replay preserves the persisted invalidation summary), and refuse page-scoped `@e…` argv before spawn when the active tab URL no longer matches the snapshot URL, when a ref id was never in that snapshot, when the snapshot state is invalidated, or when a `batch` step would reuse `@e…` on a guarded getter or mutation step after an earlier invalidating step (including `record start`, URL-bearing `record restart`, and WebMCP `invoke` / `result` / `cancel`) without a later `snapshot` step in the same plan; batch steps come from the source upstream actually executes (raw batch argument strings exclusively when any exist — filtering only the exact `--bail` token like upstream — stdin only otherwise, via `getUpstreamEffectiveBatchSteps` in `extensions/agent-browser/lib/orchestration/batch-stdin.ts`); the tab-pinned batch rewrite (which re-emits the caller's exact `--bail` token so fail-fast semantics survive the rewrite), artifact/recording preflight, batch screenshot path preparation (parent directories are created for effective raw rows too, without rewriting raw strings), and stale-ref echo args use that same selection so pinning and preflights cannot act on upstream-ignored stdin, while the pre-spawn state-policy validator deliberately keeps scanning parseable stdin alongside argv as a fail-closed content superset and treats stdin parse failures as fatal only when upstream would actually read stdin (its raw-token filter also uses the exact `--bail` token only). Same-snapshot `fill @e…` rows are guarded but do not themselves set that invalidation latch, so ordinary form fills can precede a click/submit row in one batch—see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) for the agent-visible contract and failure text; typed per-session tab/ref/pinning state lives in `extensions/agent-browser/lib/session-page-state.ts` and is updated from `extensions/agent-browser/index.ts` after each tool result
+- keep a per-session `refSnapshot` aligned with the last successful `snapshot` (including refs merged from a successful `batch` by taking the last successful `snapshot` step in batch result order): restore it from persisted tool `details` when reloading, resuming, or moving to a different Pi session-tree branch, store bounded ref role/name metadata from the same snapshot for wrapper-side current-ref diagnostics, drop it on successful close commands (`close`, `quit`, or `exit`), replace it with a persisted `page-transition` invalidation after any upstream-executed `record start` attempt (direct or batch; upstream swaps the session to a fresh active page before its already-active check, so failed starts count), a `record restart` with a URL operand, `window new`, `diff url`, or WebMCP `invoke` / `result` / `cancel` (these page-provided tools can mutate, rerender, or navigate; when a spawned `batch` yields no parseable result rows, for example after a wrapper timeout, planned transition steps still record the invalidation), or after a failed non-batch transition command (`eval`, `back`, `forward`, `reload`, `connect`, `state load`, `tab` selection) whose live URL re-verification probe observed the page (a failed transition can still have mutated or replaced the document before throwing, so keeping the verified URL must not keep the prior refs; transcript replay preserves the persisted invalidation summary), and refuse page-scoped `@e…` argv before spawn when the active tab URL no longer matches the snapshot URL, when a ref id was never in that snapshot, when the snapshot state is invalidated, or when a `batch` step would reuse `@e…` on a guarded getter or mutation step after an earlier invalidating step (including `record start`, URL-bearing `record restart`, and WebMCP `invoke` / `result` / `cancel`) without a later `snapshot` step in the same plan; batch steps come from the source upstream actually executes (raw batch argument strings exclusively when any exist — filtering only the exact `--bail` token like upstream — stdin only otherwise, via `getUpstreamEffectiveBatchSteps` in `extensions/agent-browser/lib/orchestration/batch-stdin.ts`); tab recovery (which leaves user argv/stdin and continue-on-error control flow unchanged), artifact/recording preflight, batch screenshot path preparation (parent directories are created for effective raw rows too, without rewriting raw strings), and stale-ref echo args use that same selection so pinning and preflights cannot act on upstream-ignored stdin, while the pre-spawn state-policy validator deliberately keeps scanning parseable stdin alongside argv as a fail-closed content superset and treats stdin parse failures as fatal only when upstream would actually read stdin (its raw-token filter also uses the exact `--bail` token only). Same-snapshot `fill @e…` rows are guarded but do not themselves set that invalidation latch, so ordinary form fills can precede a click/submit row in one batch—see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) for the agent-visible contract and failure text; typed per-session tab/ref/pinning state lives in `extensions/agent-browser/lib/session-page-state.ts` and is updated from `extensions/agent-browser/index.ts` after each tool result
 - when a direct or batched WebMCP call returns `status: "pending"`, or `result` / `cancel` fails while that target is unknown, keep its tab target unknown and discard same-call snapshot evidence instead of treating an immediate post-dispatch URL probe as stable; `webmcp result` / `cancel`, `get url`, and explicit navigation remain available while unknown; replace the generic blocked snapshot action with `verify-page-target-after-pending-webmcp` (`get url`), and let a completed `batch --bail` use that verification before `snapshot -i` to re-establish both target and refs
-- for top-level non-Electron direct `click` commands with an eligible target, install a bounded in-page target-specific event probe before upstream runs; if upstream reports success but no trusted pointer/mouse/click event reached the resolved target, fail the tool and report `details.clickDispatch` with explicit retry/inspect next actions (the wrapper does not replay clicks in-page). The probe covers `xpath=` targets and current `@e…` / `ref=` refs whose latest stored `refSnapshot.refs` role is `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`; it uses that role/name metadata, including snapshot-order `duplicateIndex` for duplicate-name refs, instead of taking a fresh pre-click snapshot that could recycle upstream refs. The probe is intentionally skipped for CSS selector clicks, unresolved `find … click` locators, and `batch`/`job`/`qa` click steps
+- for top-level non-Electron direct `click` commands with an eligible target, install a bounded in-page target-specific event probe before upstream runs; if upstream reports success but no trusted pointer/mouse/click event reached the resolved target, fail the tool and report `details.clickDispatch` with explicit retry/inspect next actions (the wrapper does not replay clicks in-page). The probe covers `xpath=` targets and current `@e…` / `ref=` refs whose latest stored `refSnapshot.refs` role is `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`; it requires a unique role/name in the saved snapshot and the live candidates instead of taking a fresh pre-click snapshot that could recycle upstream refs. Duplicate-name refs pass through without a probe: their old ordinal is not target identity. The probe is intentionally skipped for CSS selector clicks, unresolved `find … click` locators, and `batch`/`job`/`qa` click steps
 - derive narrow prompt guards only for concrete evidence invariants: explicitly requested screenshot/recording output paths block browser close until the artifact manifest verifies those paths, while bare inbound attachment paths remain inputs. The wrapper intentionally does not infer broad business/user intent from prompt text such as order/payment/post boundaries; agents must follow those instructions themselves. The artifact guard is bounded preflight policy (`details.promptGuard`, `failureCategory: "policy-blocked"`), not a reusable browser recipe layer
 - reject direct and effective batch `scrollintoview text=...` / `scrollinto text=...` before dispatch because current upstream can falsely report success without movement, while leaving help forms untouched; return only native recovery (`find text ... hover` or fresh snapshot/ref), leaving CSS, XPath, and current-ref behavior upstream-owned
 - after successful `get text` on a qualifying non-ref CSS selector, optionally issue one read-only `eval --stdin` probe per selector when multiple DOM matches or a hidden first match with visible peers could misread tabbed or off-screen content; simple id selectors and sensitive-looking literals skip this probe. Merge `details.selectorTextVisibility` / `selectorTextVisibilityAll`, visible warning lines, and `inspect-visible-text-candidates*` next actions as documented in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) and `RQ-0074` in [`SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md)
-- for local Unix launches, set a short private socket directory so extension-generated session names do not fail on the upstream Unix socket-path length limit; require the selected path to be absolute, owned by the current uid, mode `0700`, under trusted non-replaceable ancestry, and free of symlink, foreign-owner, or special planted entries; reject pre-existing unsafe modes instead of repairing them, then recheck before spawn. Android/Termux uses `/data/data/<package>/piab`, treats the owner-only app-data directory as the trust anchor, permits the app's matching private uid/gid ancestry, compacts generated managed identities to one 80-bit digest so ordinary namespace plus fresh-session paths remain within the limit, and places policy-lock coordination under `os.tmpdir()` because Android `/tmp` is shell-owned and inaccessible
+- for local Unix launches, set a short private socket directory so extension-generated session names do not fail on the upstream Unix socket-path length limit; require the selected path to be absolute, owned by the current uid, mode `0700`, under checked ancestry, and free of symlink, foreign-owner, or special planted entries; reject pre-existing unsafe modes instead of repairing them, then recheck before spawn. The actual filesystem root `/` is supplied by the trusted operating environment: a directory without group/other write bits is accepted regardless of its reported owner, which can be unmapped in a Linux user namespace. Existing root-owned sticky-directory acceptance is unchanged. This boundary does not protect against whoever controls the root filesystem. Every non-root ancestor still needs trusted ownership and permissions, including the destination ancestry of root-owned aliases; a matching overflow UID is not trusted. Android/Termux uses `/data/data/<package>/piab`, treats the owner-only app-data directory as the trust anchor, permits the app's matching private uid/gid ancestry, compacts generated managed identities to one 80-bit digest so ordinary namespace plus fresh-session paths remain within the limit, and places policy-lock coordination under `os.tmpdir()` because Android `/tmp` is shell-owned and inaccessible
 - keep wrapper-spawned upstream CLI calls bounded by clamping `AGENT_BROWSER_DEFAULT_TIMEOUT` to the upstream documented 25-second default while deriving a longer subprocess watchdog for explicit long `wait <ms>` / `wait --timeout <ms>`, read, and WebMCP calls from the effective direct or raw-argument-else-stdin batch steps; dialog commands, likely dialog-trigger clicks/taps/finds, and `eval --stdin` snippets that look like alert/confirm/prompt/dialog triggers use shorter wrapper subprocess budgets so blocking JavaScript prompts surface recovery actions before the full default watchdog. Timeout recovery removes standalone snapshots when the target is unknown and emits one executable session-scoped `batch --bail` (`get url`, then `snapshot -i`); blocking-dialog status/accept/dismiss remains allowed under the same unknown-target guard
 
 This is primarily about ownership clarity and avoiding surprise, not adding a heavy safety wrapper. If the extension invented the session, the extension should own its lifecycle without breaking reload, resume, or branch-tree semantics. If the caller explicitly chose the upstream session model, the extension should stay out of the way.