pi-agent-browser-native 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.8.0 - 2026-09-26
+
+### Breaking Changes
+
+- Require Node.js 24.21.0 or newer.
+
+### Changed
+
+- Update the official Pi validation graph to 0.87.1, adopt TypeScript 7, npm 12, and the latest compatible development tooling, and remove stale transitive dependency overrides.
+- Qualify official Pi, the forked Pi host, package smoke, native checkpoints, and platform builds on Node 24.
+
+### Fixed
+
+- Keep lifecycle sentinel replacement byte-stable outside its generated block without retaining the removed TypeScript compiler API.
+
+## 0.7.1 - 2026-09-22
+
+### Fixed
+
+- Defer the native replay helper import until awaited session restoration, preserving fast package registration and the complete restored tool surface. Public browser commands and saved-session behavior remain unchanged.
+
 ## 0.7.0 - 2026-09-22
 
 ### Changed

package/README.md

@@ -6,7 +6,7 @@ It is for Pi users who want agents to browse sites, inspect pages, click through
 
 ## Pi release qualification
 
-Development host dependencies are pinned to official Pi **0.87.0**, with wildcard runtime peers. `npm run check:compat` checks the installed candidate SDK/CLI identity, typechecks, runs the existing offline tests (including the native Pi pipeline with a controlled provider and fake browser), and tests a packed runtime-only installation through both the SDK and the actual bundled RPC CLI. The fork lane additionally requires the native idle checkpoint hook. It does not substitute a fork SDK while leaving official types or child CLI installed.
+Development host dependencies are pinned to official Pi **0.87.1**, with wildcard runtime peers. `npm run check:compat` checks the installed candidate SDK/CLI identity, typechecks, runs the existing offline tests (including the native Pi pipeline with a controlled provider and fake browser), and tests a packed runtime-only installation through both the SDK and the actual bundled RPC CLI. The fork lane additionally requires the native idle checkpoint hook. It does not substitute a fork SDK while leaving official types or child CLI installed.
 
 Run in an empty HOME with a **short** TMPDIR outside your real home. Long temporary paths can exceed macOS's 103-byte Unix socket limit; keep the fixture's socket safety checks intact. Real-browser/checkpoint controls, live upstream help sampling, lifecycle dogfood, and platform qualification remain the separate gates documented below. A Pi-only compatibility run uses no live browser profiles, credentials, or agent-browser fork, and does not certify those external integrations.
 
@@ -84,7 +84,7 @@ The result is optimized for agent work:
 | Agents build fragile shell commands or repeat browser calls for loops and branches | Exposes compact `agent_browser` for native commands and batch, `agent_browser_code` for fresh JavaScript against the same persistent browser, and discoverable action, QA, Electron, and source tools | `extensions/agent-browser/index.ts`, `extensions/agent-browser/lib/input-modes/`, [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md) |
 | Page snapshots are too large or viewport-blind | Shows compact, main-content-first summaries, surfaces an `Omitted high-value controls` section (plus `details.data.highValueControlRefIds`) when dense pages or desktop host screens hide editables, named surfaces/tabs, primary action buttons, and high-signal named links such as repository results from the trimmed ref lists, supports wrapper-side `snapshot -i --search <text>` / `--filter role=<role>` to trim dense pages while preserving full `details.refSnapshot`, supports `snapshot --viewport` for scroll/viewport metadata, supports `snapshot --diff` for quick ref-map deltas versus the prior tracked snapshot, and stores full redacted output in spill files when needed | `extensions/agent-browser/lib/results/snapshot.ts`, `extensions/agent-browser/lib/orchestration/browser-run/prepare.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.extension-validation.test.ts` |
 | Screenshots/downloads get lost in text | Normalizes artifact paths, creates missing parent directories, leaves click/download execution to native download, and reports existence, size, cwd, session, and repair status | [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#download-screenshot-and-pdf-files) |
-| Profile restores and tab drift confuse agents | Tracks managed sessions, keeps every upstream helper probe on the same idle-timeout launch configuration so the background browser is not restarted between a snapshot and action, re-selects target tabs after observed drift, live-verifies the active target and refreshes its title after successful tab selection or `tab close` (while retaining deliberate `about:blank` selections and post-close blank targets), rehydrates branch-backed session state on Pi session-tree changes, and pins later commands only for sessions with drift/restored-session risk | generated tab-recovery notes below; `test/agent-browser.extension-tab-recovery.test.ts` (drift and about:blank recovery), `test/agent-browser.extension-tabs.test.ts` (post-close target), `test/agent-browser.extension-ref-guards.test.ts` (snapshot/action environment and session-tree rehydration), `test/agent-browser.resume-state.test.ts` (persisted session / resume planning) |
+| Profile restores and tab drift confuse agents | Tracks managed sessions, keeps every upstream helper probe on the same idle-timeout launch configuration so the background browser is not restarted between a snapshot and action, retains native CDP target IDs so same-address tabs remain distinct after resume, re-selects target tabs after observed drift, live-verifies the active target and refreshes its title after successful tab selection or `tab close` (while retaining new blank tabs, deliberate `about:blank` selections, and post-close blank targets, including batch transitions), rehydrates branch-backed session state on Pi session-tree changes, and pins later commands only for sessions with drift/restored-session risk | generated tab-recovery notes below; `test/agent-browser.extension-tab-recovery.test.ts` (drift and about:blank recovery), `test/agent-browser.extension-tabs.test.ts` (post-close target), `test/agent-browser.extension-ref-guards.test.ts` (snapshot/action environment and session-tree rehydration), `test/agent-browser.resume-state.test.ts` (persisted session / resume planning) |
 | Auth/profile workflows can leak secrets | Supports `auth save --password-stdin`, redacts sensitive args, SAML/OAuth-bearing URLs, stdout/stderr, details, and snapshot spills, and discards malformed oversized stdout instead of persisting a parse-failure spill | `test/agent-browser.extension-security-redaction.test.ts` |
 | Stateful cookies/storage/auth output bloats or leaks context | Presentation layer redacts `details.data` for cookies and credential-like storage values while keeping low-risk local QA values such as `theme: dark` readable; recursively scrubs other structured upstream JSON (network, diff, trace/profiler, stream, dashboard, chat, auth, dialog, frame, state, and similar) using sensitive key names plus string heuristics; masks sensitive argv flags and positionals, including raw batch rows and ordered code journals; scrubs secrets from failed batch step errors; and exposes a compact redacted `batch` matrix on top-level `details.data` | `extensions/agent-browser/lib/results/presentation.ts`, `extensions/agent-browser/lib/results/presentation/diagnostics.ts`, `extensions/agent-browser/lib/runtime.ts`, `test/agent-browser.presentation-diagnostics.test.ts` |
 | Stale `@eN` refs fail mysteriously | Records per-session `details.refSnapshot`, rejects mismatched URLs / unknown refs / unsafe `batch` stdin ordering before spawn, adds recovery guidance to rerun `snapshot -i` or use stable `find` locators | `extensions/agent-browser/index.ts`, `extensions/agent-browser/lib/session-page-state.ts`, `test/agent-browser.session-page-state.test.ts`, `test/agent-browser.results.test.ts`, `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.extension-semantic-recovery.test.ts` |
@@ -102,7 +102,7 @@ Artifact results show known requested paths separately from reported/resolved lo
 
 ## Fastest way to try it
 
-Use Pi 0.87.0 or newer. This package keeps optional Pi core imports as wildcard `peerDependencies` because Pi package docs require the host Pi install to provide those packages, pins its direct Pi validation dependencies to 0.87.0, and makes hosts below 0.87.0 a setup failure through `pi-agent-browser-doctor`. There are no compatibility shims for older Pi releases.
+Use Node 24.21.0 or newer and Pi 0.87.0 or newer. This package keeps optional Pi core imports as wildcard `peerDependencies` because Pi package docs require the host Pi install to provide those packages, pins its direct Pi validation dependencies to 0.87.1, and makes Pi hosts below 0.87.0 a setup failure through `pi-agent-browser-doctor`. There are no compatibility shims for older Pi releases.
 
 Install upstream `agent-browser` first and make sure it is on `PATH`:
 
@@ -492,7 +492,7 @@ Use native `batch --bail` for known sequences. Add an explicit destination/text
 }
 ```
 
-Use the exact returned recovery payload after errors. Timeout partial progress distinguishes observed results from planned or unknown steps; it never proves an unobserved mutation did not run. For paced typing, native batch can interleave `keyboard type` characters and positional `wait <ms>` rows; see [the migration map](docs/TOOL_CONTRACT.md#07-migration). Do not assume a native `--delay` option reproduces the removed job behavior.
+Use the exact returned recovery payload after errors. Timeout partial progress reports current page and file observations separately from planned steps, whose outcomes remain unknown without upstream results. An existing artifact or matching URL does not prove any step ran. Multi-step timeouts offer inspection rather than guessing a retry position; a single retryable step may offer a retry candidate after inspection. For paced typing, native batch can interleave `keyboard type` characters and positional `wait <ms>` rows; see [the migration map](docs/TOOL_CONTRACT.md#07-migration). Do not assume a native `--delay` option reproduces the removed job behavior.
 
 Both JSON and prose results expose a bounded canonical observation with recovery actions and artifact receipts. Oversized observations name an `observationPath` for the complete redacted result; audit-only `details` is not the model's sole recovery channel. Inner code calls avoid full model rendering, spills, and image encoding until output is selected.
 
@@ -720,7 +720,7 @@ Install upstream `agent-browser`, then install dependencies:
 npm install
 ```
 
-Use the npm version declared in `package.json` `packageManager` when refreshing `package-lock.json` (for example `npx -y npm@11.14.0 install`) so optional-platform lockfile metadata does not drift. Use Pi 0.87.0 or newer for lifecycle and interactive browser smokes; the pinned Pi devDependencies are validation fixtures, not an exact-version requirement for the host CLI. See [Environment and automation pitfalls](docs/RELEASE.md#environment-and-automation-pitfalls) in `docs/RELEASE.md`.
+Use the npm version declared in `package.json` `packageManager` when refreshing `package-lock.json` (for example `npx -y npm@12.1.0 install`) so optional-platform lockfile metadata does not drift. Use Node 24.21.0 and Pi 0.87.0 or newer for lifecycle and interactive browser smokes; the pinned Pi 0.87.1 devDependencies are validation fixtures, not an exact-version requirement for the host CLI. See [Environment and automation pitfalls](docs/RELEASE.md#environment-and-automation-pitfalls) in `docs/RELEASE.md`.
 
 Checkout-only extension smoke test:
 
@@ -768,7 +768,7 @@ These calls return plain text and stay stateless: the extension does not inject
 - After open/goto/navigate calls with --profile, --restore, --session-name, or --state, agent_browser best-effort re-selects the tab whose URL matches the returned page when restored tabs steal focus during launch or reconnect.
 - After confirmed shutdown of an automatically restored managed session, the wrapper retains its complete recorded URL, including the fragment, until the first current-page operation (including get url and reload). Non-page calls such as tab list may start a daemon without fulfilling that reopen; explicit URL reads leave the managed browser and pending reopen untouched. The wrapper uses native open once, verifies the observed tab, and discards old refs/frame scope; it does not restore unsaved forms, JavaScript memory, or history. Explicit navigation, caller-owned/attached sessions, and restore-disabled sessions are not auto-reopened.
 - For a still-live browser after tab drift or resume, the wrapper verifies/selects the intended tab before ref/semantic helpers and page commands; failed selection stops the call without navigating. Local commands, read <url>, URL a11y/vitals, diff url, window new, and explicit tab/navigation/connection/state recovery do not require the prior tab. Batch checks follow effective rows past non-page prefixes and stop at explicit context changes, preserving caller argv/stdin and continue-on-error behavior. Same-tab reselection is avoided because it clears refs. Use exact batch --bail for fail-fast, not --bail=<value>. Routine same-session calls skip tab-list preflights.
-- For sessions with observed tab-drift risk, after a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes. Routine same-session commands skip this post-command tab-list probe.
+- For sessions with observed tab-drift risk, after a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes. Routine same-session commands skip focus correction; observed pages without a native targetId use tab list to establish their identity.
 - If a known session target unexpectedly reports about:blank, agent_browser best-effort re-selects the prior intended target when it still exists; if recovery fails, it records the observed about:blank target and reports exact recovery guidance instead of treating the prior page as active.
 - If upstream reports tab_gone, the pinned bound tab is gone; use details.nextActions (tab list / tab new) instead of assuming another tab is yours.
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->

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

@@ -2032,11 +2032,6 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             return finalizeObservation(result, params, ctx);
         },
         executionMode: beforeExecute ? "sequential" : undefined,
-        renderCodeCall(args, theme, context) {
-            const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-            text.setText(formatAgentBrowserRenderCall(args, theme, context.expanded));
-            return text;
-        },
         promptGuidelines: toolPromptGuidelines,
         renderCall: agentBrowserTool.renderCall, renderResult: agentBrowserTool.renderResult,
     });

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

@@ -784,81 +784,6 @@ function getTimeoutStepRetry(step) {
     const command = step.args[0];
     return command && TIMEOUT_RETRYABLE_COMMANDS.has(command) ? { args: ["batch"], stdin: JSON.stringify([step.args]) } : undefined;
 }
-function normalizeUrlForTimeoutComparison(url) {
-    if (!url)
-        return undefined;
-    try {
-        return new URL(url);
-    }
-    catch {
-        return undefined;
-    }
-}
-function currentUrlMatchesNavigationStep(currentUrl, plannedUrl) {
-    if (!currentUrl || !plannedUrl)
-        return false;
-    if (currentUrl === plannedUrl)
-        return true;
-    const current = normalizeUrlForTimeoutComparison(currentUrl);
-    const planned = normalizeUrlForTimeoutComparison(plannedUrl);
-    if (!current || !planned || current.origin !== planned.origin)
-        return false;
-    const plannedPath = planned.pathname.endsWith("/") ? planned.pathname : `${planned.pathname}/`;
-    const currentPath = current.pathname.endsWith("/") ? current.pathname : `${current.pathname}/`;
-    return planned.pathname === "/" || currentPath.startsWith(plannedPath);
-}
-function buildTimeoutProgressSteps(options) {
-    let retryStep;
-    let lastCompletedNavigationIndex;
-    const progressSteps = options.steps.map((step) => {
-        const stepArtifacts = options.artifacts.filter((artifact) => artifact.stepIndex === step.index);
-        const command = step.args[0];
-        const navigationUrl = isOpenNavigationCommand(command) || command === "pushstate" ? getLastPositionalToken(step.args) : undefined;
-        if (stepArtifacts.some((artifact) => artifact.exists)) {
-            return { ...step, reason: "Declared artifact exists on disk after timeout.", status: "completed" };
-        }
-        if (options.currentPageSource === "live" && currentUrlMatchesNavigationStep(options.currentPageUrl, navigationUrl)) {
-            lastCompletedNavigationIndex = step.index;
-            return { ...step, reason: "Live page URL was recovered after timeout.", status: "completed" };
-        }
-        return { ...step, reason: stepArtifacts.length > 0 ? "Declared artifact was not present when the watchdog fired." : undefined, status: "unknown" };
-    });
-    const highestCompletedIndex = Math.max(0, ...progressSteps.filter((step) => step.status === "completed").map((step) => step.index));
-    for (const step of progressSteps) {
-        if (step.status === "unknown" && step.index < highestCompletedIndex) {
-            step.status = "completed";
-            step.reason = "Later step completion evidence indicates the batch advanced past this step before timeout.";
-        }
-    }
-    for (const step of progressSteps) {
-        const command = step.args[0];
-        if (step.status === "completed" && (isOpenNavigationCommand(command) || command === "pushstate")) {
-            lastCompletedNavigationIndex = Math.max(lastCompletedNavigationIndex ?? 0, step.index);
-        }
-    }
-    for (const step of progressSteps) {
-        if (step.status === "completed")
-            continue;
-        if (!retryStep) {
-            const retry = getTimeoutStepRetry(step);
-            retryStep = {
-                ...step,
-                reason: step.reason ?? (retry ? "Likely active when the wrapper watchdog fired." : "Likely active when the wrapper watchdog fired; executable retry omitted because this step may have already mutated page state."),
-                retry,
-                status: "failed",
-            };
-            Object.assign(step, retryStep);
-            continue;
-        }
-        step.status = "pending";
-        step.reason = step.reason ?? `Pending behind timed-out step ${retryStep.index}.`;
-    }
-    return {
-        openedButPostOpenTimedOut: lastCompletedNavigationIndex !== undefined && retryStep !== undefined && retryStep.index > lastCompletedNavigationIndex,
-        retryStep,
-        steps: progressSteps,
-    };
-}
 export async function collectTimeoutPartialProgress(options) {
     if ((options.commandTokens[0] === "session" && options.commandTokens[1] === "info") || isBrowserIndependentRead(options.commandTokens, options.stdin))
         return undefined;
@@ -873,14 +798,16 @@ export async function collectTimeoutPartialProgress(options) {
     const plannedUrl = recoveredUrl ? undefined : getPlannedCurrentPageUrl(rawSteps);
     const url = recoveredUrl ?? plannedUrl;
     const currentPageSource = recoveredUrl ? "live" : plannedUrl ? "planned" : title ? "live" : undefined;
-    const stepProgress = buildTimeoutProgressSteps({ artifacts, currentPageSource: recoveredUrl ? "live" : undefined, currentPageUrl: recoveredUrl, steps: rawSteps });
+    // A matching URL or existing file is current state, not an execution receipt.
+    const steps = rawSteps.map(step => ({ ...step, status: "unknown", reason: "Upstream did not report this step's outcome before timeout." }));
+    const singleStep = steps.length === 1 ? steps[0] : undefined;
+    const retry = singleStep ? getTimeoutStepRetry(singleStep) : undefined;
+    const retryStep = singleStep && retry ? { ...singleStep, retry } : undefined;
     if (rawSteps.length === 0 && artifacts.length === 0 && !url && !title)
         return undefined;
     const foundArtifacts = artifacts.filter((artifact) => artifact.exists).length;
-    const completedSteps = stepProgress.steps.filter((step) => step.status === "completed").length;
     const pageStateSummary = recoveredUrl || title ? " and current page state" : plannedUrl ? " and planned page URL" : "";
-    const retrySummary = stepProgress.retryStep ? ` Retry step ${stepProgress.retryStep.index} is the first incomplete step.` : "";
-    return { artifacts, currentPage: url || title ? { source: currentPageSource, title, url } : undefined, liveUrlRecovered: recoveredUrl !== undefined, openedButPostOpenTimedOut: stepProgress.openedButPostOpenTimedOut, retryStep: stepProgress.retryStep, steps: stepProgress.steps.length > 0 ? stepProgress.steps : undefined, summary: `Timed out before upstream returned final results; recovered ${completedSteps}/${rawSteps.length} planned step state${rawSteps.length === 1 ? "" : "s"} and ${foundArtifacts}/${artifacts.length} declared artifact path${artifacts.length === 1 ? "" : "s"}${pageStateSummary}.${retrySummary}` };
+    return { artifacts, currentPage: url || title ? { source: currentPageSource, title, url } : undefined, liveUrlRecovered: recoveredUrl !== undefined, retryStep, steps: steps.length > 0 ? steps : undefined, summary: `Timed out before upstream returned final results; ${steps.length} planned step outcome${steps.length === 1 ? " is" : "s are"} unknown. Found ${foundArtifacts}/${artifacts.length} declared artifact path${artifacts.length === 1 ? "" : "s"}${pageStateSummary}; these observations do not prove step execution.` };
 }
 function redactSensitivePathSegmentsForDiagnostic(path) {
     return path.split(/([/\\]+)/).map((segment) => segment === "/" || segment === "\\" || /^[/\\]+$/.test(segment) ? segment : redactSensitiveText(segment) !== segment || /(?:secret|token|password|passwd|credential|auth|api[-_]?key|bearer)/i.test(segment) ? "[REDACTED]" : segment).join("");
@@ -934,7 +861,7 @@ export function formatTimeoutPartialProgressText(progress, pageTargetUnknown = f
         const payload = JSON.stringify({ ...progress.retryStep.retry, stdin: JSON.stringify([redactInvocationArgs(progress.retryStep.args)]) });
         lines.push(pageTargetUnknown
             ? `Retry candidate for step ${progress.retryStep.index}: ${payload}. Verify the current URL before running it.`
-            : `Retry failed step: ${payload}`);
+            : `Retry candidate for step ${progress.retryStep.index} (outcome unknown): ${payload}`);
     }
     for (const artifact of progress.artifacts)
         lines.push(`Artifact from step ${artifact.stepIndex}: ${redactSensitivePathSegmentsForDiagnostic(artifact.path)} (${artifact.exists ? `exists${typeof artifact.sizeBytes === "number" ? `, ${artifact.sizeBytes} bytes` : ""}` : "missing"})`);

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

@@ -217,7 +217,7 @@ function buildTimeoutPartialProgressNextActions(options) {
                     args: withOptionalSessionArgs(options.executionPlan.sessionName, ["batch", "--bail"]),
                     stdin: JSON.stringify([["get", "url"], ["snapshot", "-i"]]),
                 },
-                reason: `Verify the current URL, then inspect the page after timeout${stepIndex === undefined ? "" : ` before resuming from incomplete step ${stepIndex}`}.`,
+                reason: `Verify the current URL, then inspect the page after timeout${stepIndex === undefined ? "" : ` before considering a retry of step ${stepIndex}`}.`,
                 safety: "Fail-fast read-only recovery: snapshot runs only after get url succeeds, satisfying the wrapper page-target guard without trusting the planned URL.",
                 tool: "agent_browser",
             }];
@@ -229,8 +229,8 @@ function buildTimeoutPartialProgressNextActions(options) {
                     ? { ...retry, sessionMode: "fresh" }
                     : { ...retry, args: withOptionalSessionArgs(options.executionPlan.sessionName, retry.args) },
                 reason: freshSessionAbandoned
-                    ? `Retry the first incomplete timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} in a fresh browser session because the timed-out fresh session was not proven live.`
-                    : `Retry the first incomplete timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} against the current browser session.`,
+                    ? `Consider retrying the single timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} in a fresh browser session because the timed-out fresh session was not proven live.`
+                    : `Consider retrying the single timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} against the current browser session.`,
                 safety: "Only read-only or idempotent timeout steps get executable retry args; inspect current page/artifact state before using the action.",
                 tool: "agent_browser",
             }];
@@ -240,7 +240,7 @@ function buildTimeoutPartialProgressNextActions(options) {
     return [{
             id: "inspect-current-page-after-timeout",
             params: { args: withOptionalSessionArgs(options.executionPlan.sessionName, ["snapshot", "-i"]) },
-            reason: `Inspect the current page after timeout before deciding how to resume${stepIndex === undefined ? "" : ` from incomplete step ${stepIndex}`}.`,
+            reason: `Inspect the current page after timeout before deciding how to resume${stepIndex === undefined ? "" : ` with step ${stepIndex}`}.`,
             safety: "Read details.timeoutPartialProgress first. Do not blindly retry mutating steps such as clicks, fills, key presses, selects, or checks; split the remaining flow into shorter batches around the next navigation or DOM mutation boundary.",
             tool: "agent_browser",
         }];

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

@@ -8,6 +8,7 @@ import { prepareAgentBrowserSpawnArgs, withChromeStartupArgs } from "../../proce
 import { cleanupElectronLaunchResources } from "../../electron/cleanup.js";
 import { launchElectronApp } from "../../electron/launch.js";
 import { pathExists } from "../../fs-utils.js";
+import { isRecord } from "../../parsing.js";
 import { getCompiledSemanticActionSessionPrefix } from "../../input-modes/semantic-action.js";
 import { tryNetworkRequestsPageFilter } from "./prepare/network-page-filter.js";
 import { tryContainerScroll, tryPageScrollTo } from "./prepare/scroll-shims.js";
@@ -599,14 +600,20 @@ export async function prepareBrowserRun(options) {
             });
             if (!executionPlan.validationError && !executionPlan.plainTextInspection && !knownStaleRef && !invalidStdin && priorSessionTabTarget && pinSessionTab) {
                 signal?.throwIfAborted();
-                const reopened = !coldManagedSession || await runSessionCommandData({
+                const reopenedData = coldManagedSession ? await runSessionCommandData({
                     args: ["open", priorSessionTabTarget.url], cwd, namespace: executionPlan.namespace, sessionName: executionPlan.sessionName, signal, timeoutMs: params.timeoutMs,
                     onProcessResult: ({ agentBrowserStarted }) => {
                         // A started open may have navigated even if its CLI was aborted before replying.
                         if (agentBrowserStarted && sessionStateKey)
                             sessionPageState.setTabReopenPending({ pending: false, sessionName: sessionStateKey, update: options.sessionPageStateUpdate });
                     },
-                }) !== undefined;
+                }) : undefined;
+                const reopened = !coldManagedSession || reopenedData !== undefined;
+                if (coldManagedSession && reopened)
+                    priorSessionTabTarget = {
+                        ...priorSessionTabTarget,
+                        targetId: isRecord(reopenedData) && typeof reopenedData.targetId === "string" ? reopenedData.targetId : undefined,
+                    };
                 const selection = signal?.aborted ? undefined : reopened
                     ? await ensureSessionTabTarget({ cwd, namespace: executionPlan.namespace, sessionName: executionPlan.sessionName, signal, target: priorSessionTabTarget })
                     : { error: "agent-browser could not reopen the remembered URL after the managed browser shut down. Navigate explicitly, then run snapshot -i before retrying." };

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

@@ -4,7 +4,7 @@ import { parseArgvDescriptor } from "../../argv-descriptor.js";
 import { isBrowserIndependentRead, needsManagedSession } from "../../command-policy.js";
 import { deleteIdentityKeysInNamespace, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "../../argv-grammar.js";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "../../batch-lifecycle.js";
-import { isCloseAllCommand, isCloseCommand, isOpenNavigationCommand, isPageMutationCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWindowOrDiffPageTransitionCommand } from "../../command-taxonomy.js";
+import { isCloseAllCommand, isCloseCommand, isNavigationObservableCommandName, isOpenNavigationCommand, isPageMutationCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWindowOrDiffPageTransitionCommand } from "../../command-taxonomy.js";
 import { OPEN_RESULT_TAB_CORRECTION_FLAGS } from "../../launch-scoped-flags.js";
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
 import { getResultingPageTargetState, commandRequiresLivePageVerification } from "../../page-target-validation.js";
@@ -26,7 +26,7 @@ import { isManagedSessionRestoreKey } from "../../managed-session-storage.js";
 import { createFreshSessionName, extractUpstreamCommandTokens, resolveManagedSessionState } from "../../runtime.js";
 import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
 import { closeManagedSession, inspectManagedSessionDaemon } from "./managed-session-daemon-policy.js";
-import { applyOpenResultTabCorrection, buildAboutBlankRecoveryHint, buildAboutBlankWarning, buildElectronPostCommandHealthDiagnostic, buildElectronRefFreshnessDiagnostic, buildElectronSessionMismatch, buildManagedSessionOutcome, collectOpenResultTabCorrection, collectSessionTabSelection, commandChoosesSessionTabTarget, extractNavigationSummaryFromData, extractStringResultField, findElectronLaunchRecordForSession, formatElectronPostCommandHealthText, formatElectronSessionMismatchText, getSessionContextKey, getStaleRefArgs, mergeNavigationSummaryIntoData, runSessionCommandData, shouldCaptureNavigationSummary, shouldCorrectSessionTabAfterCommand, shouldInspectElectronPostCommandHealth, updateTraceOwnerState, } from "./session-state.js";
+import { applyOpenResultTabCorrection, buildAboutBlankRecoveryHint, buildAboutBlankWarning, buildElectronPostCommandHealthDiagnostic, buildElectronRefFreshnessDiagnostic, buildElectronSessionMismatch, buildManagedSessionOutcome, collectOpenResultTabCorrection, collectSessionTabSelection, collectSessionTabTarget, commandChoosesSessionTabTarget, extractNavigationSummaryFromData, extractStringResultField, findElectronLaunchRecordForSession, formatElectronPostCommandHealthText, formatElectronSessionMismatchText, getSessionContextKey, getStaleRefArgs, mergeNavigationSummaryIntoData, runSessionCommandData, shouldCaptureNavigationSummary, shouldCorrectSessionTabAfterCommand, shouldInspectElectronPostCommandHealth, updateTraceOwnerState, } from "./session-state.js";
 import { collectClickDispatchDiagnostic } from "./click-dispatch.js";
 import { buildScrollNoopDiagnostic, collectComboboxFocusDiagnostic, collectElectronBroadGetTextScopeDiagnostics, collectElectronHandoff, collectFillVerificationDiagnostic, collectNavigationSummary, collectOverlayBlockerDiagnostic, collectQaAttachedTarget, collectSnapshotOverlayBlockerDiagnostic, collectRecordingDependencyWarning, collectScrollPositionSnapshot, collectSelectorTextVisibilityDiagnostics, collectTimeoutPartialProgress, sleepMs, formatQaAttachedTargetText, getArtifactCleanupGuidance, getEvalResultWarning, getEvalStdinHint, getSourceLookupElectronContext, } from "./diagnostics.js";
 import { repairScreenshotData } from "./prepare.js";
@@ -296,7 +296,10 @@ export async function processBrowserOutput(input) {
                 presentationEnvelope = { ...(presentationEnvelope ?? {}), error: clickDispatchDiagnostic.summary, success: false };
             }
         }
-        const tabTransition = prepared.executionPlan.commandInfo.command === "tab" && prepared.executionPlan.commandInfo.subcommand !== undefined && !["list", "new"].includes(prepared.executionPlan.commandInfo.subcommand);
+        const tabTransition = dispatchedCommands.some((step) => {
+            const [command, subcommand] = extractUpstreamCommandTokens(step);
+            return command === "tab" && subcommand !== undefined && subcommand !== "list";
+        });
         // Non-page rows (including a failed prefix) cannot retire a cold target for a navigation that never ran.
         const resultingPageState = sessionPageState.get(sessionStateKey).tabReopenPending === true
             ? { currentPageUrl: prepared.priorSessionTabTarget?.url, pageTargetMayHaveChanged: false, pageUrlUnknown: prepared.priorSessionTabTargetUnknown === true }
@@ -306,11 +309,12 @@ export async function processBrowserOutput(input) {
                 currentPageUrl: prepared.priorSessionTabTarget?.url,
                 pageUrlUnknown: prepared.priorSessionTabTargetUnknown === true,
             });
-        if (succeeded &&
+        if (succeeded && !nestedBatchClosed &&
             (shouldCaptureNavigationSummary(prepared.executionPlan.commandInfo.command, presentationEnvelope?.data, prepared.executionPlan.commandInfo.subcommand) ||
+                (prepared.executionPlan.commandInfo.command === "batch" && dispatchedCommands.some(([command, subcommand]) => isNavigationObservableCommandName(command, subcommand))) ||
                 shouldCaptureSemanticActionNavigationSummary(prepared.compiledSemanticAction, presentationEnvelope?.data) ||
                 commandRequiresLivePageVerification(prepared.executionPlan.effectiveArgs, prepared.runtimeToolStdin) ||
-                (destinationTransition && !nestedBatchClosed) || tabTransition)) {
+                destinationTransition || tabTransition)) {
             navigationSummary = await collectNavigationSummary({ cwd, namespace: prepared.executionPlan.namespace, priorTarget: prepared.priorSessionTabTarget, reusePriorTitle: !tabTransition, sessionName: prepared.executionPlan.sessionName, signal });
         }
         // Failed transitions may already have changed the page; keep only a live observed URL.
@@ -319,8 +323,11 @@ export async function processBrowserOutput(input) {
             !processResult.aborted &&
             !processResult.timedOut &&
             !nestedBatchClosed &&
-            (destinationTransition || (prepared.executionPlan.commandInfo.command !== "batch" &&
-                isUnverifiedPageTransitionCommand(prepared.executionPlan.commandInfo.command, prepared.executionPlan.commandInfo.subcommand)))) {
+            dispatchedCommands.some((step) => {
+                const [command, subcommand] = extractUpstreamCommandTokens(step);
+                return (prepared.executionPlan.commandInfo.command === "batch" && isOpenNavigationCommand(command))
+                    || isUnverifiedPageTransitionCommand(command, subcommand);
+            })) {
             navigationSummary = await collectNavigationSummary({ cwd, namespace: prepared.executionPlan.namespace, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName, signal });
             // Re-verifying a failed transition's URL does not make its prior refs valid.
             failedTransitionReverification = navigationSummary !== undefined;
@@ -342,11 +349,21 @@ export async function processBrowserOutput(input) {
         const failedWebMcpSettlement = prepared.priorSessionTabTargetUnknown === true && ((!succeeded && isWebMcpSettlementCommand(prepared.executionPlan.commandInfo.command, prepared.executionPlan.commandInfo.subcommand))
             || (prepared.executionPlan.commandInfo.command === "batch" && batchHasFailedWebMcpSettlement(presentationEnvelope?.data)));
         const unsettledWebMcpMutation = pendingWebMcpMutation || failedWebMcpSettlement;
-        const observedSessionTabTarget = unsettledWebMcpMutation || (unobservedMutation && !failedTransitionReverification)
+        let observedSessionTabTarget = unsettledWebMcpMutation || (unobservedMutation && !failedTransitionReverification)
             ? undefined
             : normalizeSessionTabTarget(navigationSummary)
                 ?? (trustsReportedPageTarget ? extractSessionTabTargetFromBatchResults(presentationEnvelope?.data) : undefined)
                 ?? (succeeded && trustsReportedPageTarget ? extractSessionTabTargetFromCommandData(prepared.commandTokens, presentationEnvelope?.data) : undefined);
+        if (observedSessionTabTarget && !browserIndependentRead && !nestedBatchClosed && !isCloseCommand(prepared.executionPlan.commandInfo.command)) {
+            const reportedTarget = prepared.executionPlan.commandInfo.command === "batch"
+                ? extractSessionTabTargetFromBatchResults(presentationEnvelope?.data)
+                : prepared.commandTokens[0] === "tab" && prepared.commandTokens[1] === "close" ? undefined
+                    : extractSessionTabTargetFromCommandData(prepared.commandTokens, presentationEnvelope?.data);
+            if (reportedTarget?.targetId)
+                observedSessionTabTarget.targetId = reportedTarget.targetId;
+            else
+                observedSessionTabTarget = await collectSessionTabTarget({ cwd, namespace: prepared.executionPlan.namespace, sessionName: prepared.executionPlan.sessionName, signal, target: observedSessionTabTarget });
+        }
         const safeObservedSessionTabTarget = observedSessionTabTarget;
         let currentSessionTabTarget = safeObservedSessionTabTarget;
         if (!currentSessionTabTarget && nestedBatchClose === undefined && !unobservedMutation) {
@@ -459,7 +476,7 @@ export async function processBrowserOutput(input) {
                         : processResult.agentBrowserStarted && (directTransitionInvalidation || plannedBatchTransitionInvalidation)
                             ? directTransitionInvalidation ?? plannedBatchTransitionInvalidation
                             : failedTransitionReverification
-                                ? buildPageTransitionRefSnapshotInvalidation("A failed eval/back/forward/reload/connect/state-load/tab command may still have changed the page, so the prior snapshot refs were invalidated. Run snapshot -i before using page-scoped refs.")
+                                ? buildPageTransitionRefSnapshotInvalidation("A failed page transition may still have changed the page, so the prior snapshot refs were invalidated. Run snapshot -i before using page-scoped refs.")
                                 : batchRefSnapshotState?.invalidation?.reason === "page-transition"
                                     ? batchRefSnapshotState.invalidation
                                     : undefined;

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

@@ -460,6 +460,8 @@ export function shouldCorrectSessionTabAfterCommand(options) {
         !isSessionTabPostCommandCorrectionExcludedCommand(options.command));
 }
 function getTabSelection(tab) {
+    if (tab.targetId)
+        return { selectedTab: tab.targetId, selectionKind: "targetId" };
     if (typeof tab.tabId === "string" && tab.tabId.trim().length > 0)
         return { selectedTab: tab.tabId.trim(), selectionKind: "tabId" };
     if (typeof tab.label === "string" && tab.label.trim().length > 0)
@@ -467,6 +469,10 @@ function getTabSelection(tab) {
     return typeof tab.index === "number" ? { selectedTab: String(tab.index), selectionKind: "index" } : undefined;
 }
 function selectSessionTargetTab(options) {
+    if (options.target.targetId) {
+        const target = selectAnySessionTargetTab(options);
+        return target && options.tabs.find((tab) => tab.targetId === options.target.targetId)?.active !== true ? target : undefined;
+    }
     return chooseOpenResultTabCorrection({
         tabs: options.tabs,
         targetTitle: options.target.title,
@@ -477,7 +483,9 @@ function selectAnySessionTargetTab(options) {
     const targetUrl = typeof options.target.url === "string" ? normalizeComparableUrl(options.target.url) : undefined;
     if (!targetUrl)
         return undefined;
-    const matchingTabs = options.tabs.filter((tab) => normalizeComparableUrl(tab.url ?? "") === targetUrl);
+    const matchingTabs = options.tabs.filter((tab) => options.target.targetId
+        ? tab.targetId === options.target.targetId
+        : normalizeComparableUrl(tab.url ?? "") === targetUrl);
     const targetTitle = options.target.title?.trim() ?? "";
     const titledTabs = targetTitle ? matchingTabs.filter((tab) => tab.title?.trim() === targetTitle) : [];
     const selectedTab = titledTabs.find((tab) => tab.active) ?? titledTabs[0] ?? matchingTabs.find((tab) => tab.active) ?? matchingTabs[0];
@@ -538,6 +546,7 @@ export async function collectOpenResultTabCorrection(options) {
         index: typeof tab.index === "number" ? tab.index : index,
         label: typeof tab.label === "string" ? tab.label : undefined,
         tabId: typeof tab.tabId === "string" ? tab.tabId : undefined,
+        targetId: typeof tab.targetId === "string" ? tab.targetId : undefined,
         title: typeof tab.title === "string" ? tab.title : undefined,
         url: typeof tab.url === "string" ? tab.url : undefined,
     }));
@@ -551,10 +560,21 @@ function mapTabData(tabData) {
         index: typeof tab.index === "number" ? tab.index : index,
         label: typeof tab.label === "string" ? tab.label : undefined,
         tabId: typeof tab.tabId === "string" ? tab.tabId : undefined,
+        targetId: typeof tab.targetId === "string" ? tab.targetId : undefined,
         title: typeof tab.title === "string" ? tab.title : undefined,
         url: typeof tab.url === "string" ? tab.url : undefined,
     }));
 }
+export async function collectSessionTabTarget(options) {
+    const tabs = mapTabData(await runSessionCommandData({ ...options, args: ["tab", "list"] }));
+    const active = tabs?.find((tab) => tab.active);
+    const observedUrl = normalizeComparableUrl(options.target.url);
+    if (normalizeComparableUrl(active?.url) !== observedUrl && tabs?.some((tab) => normalizeComparableUrl(tab.url) === observedUrl))
+        return options.target;
+    return active?.targetId
+        ? { ...options.target, targetId: active.targetId }
+        : options.target;
+}
 export async function collectSessionTabSelection(options) {
     const { cwd, namespace, sessionName, signal, target } = options;
     const tabData = await runSessionCommandData({ args: ["tab", "list"], cwd, namespace, sessionName, signal });
@@ -569,13 +589,20 @@ export async function ensureSessionTabTarget(options) {
     const error = "agent-browser could not re-select and verify the intended tab before running the command. Run tab list and select the intended tab, then snapshot -i before retrying.";
     if (!correction)
         return { error };
+    const verifyUrl = async (tab) => {
+        if (normalizeComparableUrl(tab.url) === normalizeComparableUrl(options.target.url))
+            return true;
+        // Native tab metadata can retain the attempted URL while get url reports Chrome's error page.
+        const data = await runSessionCommandData({ ...options, args: ["get", "url"] });
+        return normalizeComparableUrl(extractStringResultField(data, "url")) === normalizeComparableUrl(options.target.url);
+    };
     // Native tab selection clears refs and frame scope even when selecting the current tab.
     if (active && getTabSelection(active)?.selectedTab === correction.selectedTab)
-        return {};
+        return await verifyUrl(active) ? {} : { error };
     if (!await applyOpenResultTabCorrection({ ...options, correction }))
         return { correction, error };
     const selected = (await readTabs())?.find((tab) => tab.active);
-    return selected && getTabSelection(selected)?.selectedTab === correction.selectedTab && normalizeComparableUrl(selected.url ?? "") === normalizeComparableUrl(options.target.url)
+    return selected && getTabSelection(selected)?.selectedTab === correction.selectedTab && await verifyUrl(selected)
         ? { correction }
         : { correction, error };
 }

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

@@ -92,7 +92,7 @@ export const WRAPPER_TAB_RECOVERY_BEHAVIOR = [
     "After open/goto/navigate calls with --profile, --restore, --session-name, or --state, agent_browser best-effort re-selects the tab whose URL matches the returned page when restored tabs steal focus during launch or reconnect.",
     "After confirmed shutdown of an automatically restored managed session, the wrapper retains its complete recorded URL, including the fragment, until the first current-page operation (including get url and reload). Non-page calls such as tab list may start a daemon without fulfilling that reopen; explicit URL reads leave the managed browser and pending reopen untouched. The wrapper uses native open once, verifies the observed tab, and discards old refs/frame scope; it does not restore unsaved forms, JavaScript memory, or history. Explicit navigation, caller-owned/attached sessions, and restore-disabled sessions are not auto-reopened.",
     "For a still-live browser after tab drift or resume, the wrapper verifies/selects the intended tab before ref/semantic helpers and page commands; failed selection stops the call without navigating. Local commands, read <url>, URL a11y/vitals, diff url, window new, and explicit tab/navigation/connection/state recovery do not require the prior tab. Batch checks follow effective rows past non-page prefixes and stop at explicit context changes, preserving caller argv/stdin and continue-on-error behavior. Same-tab reselection is avoided because it clears refs. Use exact batch --bail for fail-fast, not --bail=<value>. Routine same-session calls skip tab-list preflights.",
-    "For sessions with observed tab-drift risk, after a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes. Routine same-session commands skip this post-command tab-list probe.",
+    "For sessions with observed tab-drift risk, after a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes. Routine same-session commands skip focus correction; observed pages without a native targetId use tab list to establish their identity.",
     "If a known session target unexpectedly reports about:blank, agent_browser best-effort re-selects the prior intended target when it still exists; if recovery fails, it records the observed about:blank target and reports exact recovery guidance instead of treating the prior page as active.",
     "If upstream reports tab_gone, the pinned bound tab is gone; use details.nextActions (tab list / tab new) instead of assuming another tab is yours.",
 ];