pi-agent-browser-native 0.2.64 → 0.2.65

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.2.65 - 2026-07-06
+
+### Fixed
+
+- Fixed installed-package prompt guidance so the compiled `dist/` entrypoint points agents at package-root `README.md`, `docs/COMMAND_REFERENCE.md`, and `docs/TOOL_CONTRACT.md` instead of nonexistent `dist/docs/...` paths.
+- Tightened managed-session tab recovery so snapshot-scoped `@e...` follow-up commands can re-select the snapshot page after about:blank/tab drift without adding routine tab-list probes to ordinary same-session commands.
+- Resolved semantic role `click` / `fill` shortcuts from a fresh visible snapshot when exact current refs exist, avoiding stale cached-ref reuse after tab or page drift.
+
+### Validation
+
+- Ran `npm run verify`, focused extension-validation tests, `npm run docs`, `npm run typecheck`, `git diff --check`, and a thermo-nuclear reviewer subagent loop until it returned no material findings.
+
 ## 0.2.64 - 2026-07-01
 
 ### Fixed

package/README.md

@@ -703,8 +703,8 @@ These calls return plain text and stay stateless: the extension does not inject
 
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
-- After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --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.
-- After the wrapper observes tab-drift risk for a session (for example profile restore correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab is known.
+- 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 the wrapper observes tab-drift risk for a session (for example open correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab or ref snapshot is known.
 - 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.
 - 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.
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->

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

@@ -5,7 +5,8 @@
  * Usage: Loaded by pi through the package manifest in this package, or explicitly via `pi --no-extensions -e .` during local checkout development.
  * Invariants/Assumptions: agent-browser is installed separately on PATH, the wrapper targets the current locally installed upstream version only, and no backward-compatibility shims are provided.
  */
-import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Text } from "@earendil-works/pi-tui";
 import { PROJECT_RULE_PROMPT, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
@@ -446,8 +447,23 @@ class AsyncExecutionQueue {
         })();
     }
 }
+function findPackageRoot(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        const packageJsonPath = join(currentDir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+            if (packageJson.name === "pi-agent-browser-native")
+                return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir)
+            return startDir;
+        currentDir = parentDir;
+    }
+}
 function getInstalledDocsPaths() {
-    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const packageRoot = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
     return {
         readmePath: join(packageRoot, "README.md"),
         commandReferencePath: join(packageRoot, "docs", "COMMAND_REFERENCE.md"),

package/dist/extensions/agent-browser/lib/launch-scoped-flags.js

@@ -75,9 +75,4 @@ export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
 ];
 export const LAUNCH_SCOPED_FLAGS = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag);
 export const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAGS.join(", ");
-/**
- * The subset of launch-scoped flags that can restore browser/auth state with pre-existing tabs
- * and are plausible wrong-active-tab sources after a fresh launch. These trigger post-open
- * tab-correction (the `tab list` + re-select cycle).
- */
-export const LAUNCH_SCOPED_TAB_CORRECTION_FLAGS = new Set(["--profile", "--session-name", "--restore", "--state"]);
+export const OPEN_RESULT_TAB_CORRECTION_FLAGS = new Set(["--profile", "--restore", "--session-name", "--state"]);

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

@@ -15,7 +15,7 @@ import { buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextAction
 import { resolveVisibleRefActionFromSnapshot } from "../../results/selector-recovery.js";
 import { extractRefSnapshotFromData } from "../../session-page-state.js";
 import { buildExecutionPlan, createFreshSessionName, extractCommandTokens, redactInvocationArgs, } from "../../runtime.js";
-import { applyOpenResultTabCorrection, buildManagedSessionOutcome, buildPinnedBatchPlan, buildSessionDetailFields, buildStaleRefPreflight, getSessionContextKey, collectSessionTabSelection, getGuardedRefUsage, getTraceOwnerGuardMessage, runSessionCommandData, shouldPinSessionTabForCommand, } from "./session-state.js";
+import { applyOpenResultTabCorrection, buildManagedSessionOutcome, buildPinnedBatchPlan, buildSessionDetailFields, buildStaleRefPreflight, getSessionContextKey, collectAnySessionTabSelection, collectSessionTabSelection, getGuardedRefUsage, getTraceOwnerGuardMessage, runSessionCommandData, shouldPinSessionTabForCommand, } from "./session-state.js";
 import { parseBatchStdinJsonArray } from "../batch-stdin.js";
 import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
 import { prepareClickDispatchProbe } from "./click-dispatch.js";
@@ -278,14 +278,22 @@ export function validateStdinCommandContract(options) {
     const commandLabel = options.command ? `\`${options.command}\`` : "the requested command";
     return `agent_browser stdin is only supported for \`batch\`, \`eval --stdin\`, and \`auth save --password-stdin\`; remove stdin from ${commandLabel} or use one of those command forms.`;
 }
-export async function resolveSemanticActionVisibleRefArgs(options) {
-    if (!options.compiled || !options.sessionName || options.compiled.locator !== "role" || !["check", "click", "fill"].includes(options.compiled.action))
+function canResolveSemanticVisibleRef(compiled) {
+    return compiled !== undefined && compiled.locator === "role" && ["check", "click", "fill"].includes(compiled.action);
+}
+function resolveSemanticActionVisibleRefArgsFromSnapshot(compiled, snapshotData) {
+    if (!canResolveSemanticVisibleRef(compiled))
         return undefined;
-    const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });
-    const resolution = resolveVisibleRefActionFromSnapshot({ allowFill: true, compiledAction: options.compiled, snapshotData });
+    const resolution = resolveVisibleRefActionFromSnapshot({ allowFill: true, compiledAction: compiled, snapshotData });
     if (!resolution)
         return undefined;
-    return { args: [...getCompiledSemanticActionSessionPrefix(options.compiled), ...resolution.args], snapshot: resolution.snapshot };
+    return { args: [...getCompiledSemanticActionSessionPrefix(compiled), ...resolution.args], snapshot: resolution.snapshot };
+}
+export async function resolveSemanticActionVisibleRefArgs(options) {
+    if (!options.compiled || !options.sessionName)
+        return undefined;
+    const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });
+    return resolveSemanticActionVisibleRefArgsFromSnapshot(options.compiled, snapshotData);
 }
 export async function prepareBrowserRun(options) {
     const { cwd, implicitSessionIdleTimeoutMs, onUpdate, params, signal, state } = options;
@@ -332,8 +340,14 @@ export async function prepareBrowserRun(options) {
         managedSessionNamespace: state.managedSessionNamespace,
         sessionMode,
     });
+    const sessionStateKey = getSessionContextKey(executionPlan.sessionName, executionPlan.namespace);
+    const priorSessionPageState = sessionPageState.get(sessionStateKey);
+    const priorSessionTabTarget = priorSessionPageState.tabTarget;
+    const sessionTabPinningReason = priorSessionPageState.pinningReason;
+    const priorRefSnapshotState = priorSessionPageState.refSnapshot;
+    const priorRefSnapshotInvalidation = priorSessionPageState.refSnapshotInvalidation;
     let semanticActionVisibleRefResolution;
-    if (!executionPlan.validationError && executionPlan.managedSessionName !== freshSessionName) {
+    if (!executionPlan.validationError && executionPlan.managedSessionName !== freshSessionName && canResolveSemanticVisibleRef(compiledSemanticAction)) {
         semanticActionVisibleRefResolution = await resolveSemanticActionVisibleRefArgs({
             compiled: compiledSemanticAction,
             cwd,
@@ -341,15 +355,15 @@ export async function prepareBrowserRun(options) {
             sessionName: executionPlan.sessionName,
             signal,
         });
-        if (semanticActionVisibleRefResolution) {
-            executionPlan = buildExecutionPlan(semanticActionVisibleRefResolution.args, {
-                freshSessionName,
-                managedSessionActive: state.managedSessionActive,
-                managedSessionName: state.managedSessionName,
-                managedSessionNamespace: state.managedSessionNamespace,
-                sessionMode,
-            });
-        }
+    }
+    if (semanticActionVisibleRefResolution) {
+        executionPlan = buildExecutionPlan(semanticActionVisibleRefResolution.args, {
+            freshSessionName,
+            managedSessionActive: state.managedSessionActive,
+            managedSessionName: state.managedSessionName,
+            managedSessionNamespace: state.managedSessionNamespace,
+            sessionMode,
+        });
     }
     const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);
     const redactedRecoveryHint = redactRecoveryHint(executionPlan.recoveryHint);
@@ -386,7 +400,6 @@ export async function prepareBrowserRun(options) {
         commandTokens,
         stdin: runtimeToolStdin,
     });
-    const sessionStateKey = getSessionContextKey(executionPlan.sessionName, executionPlan.namespace);
     const traceOwnerGuardMessage = getTraceOwnerGuardMessage({
         command: executionPlan.commandInfo.command,
         sessionName: sessionStateKey,
@@ -430,11 +443,6 @@ export async function prepareBrowserRun(options) {
                 isError: true,
             } };
     }
-    const priorSessionPageState = sessionPageState.get(sessionStateKey);
-    const priorSessionTabTarget = priorSessionPageState.tabTarget;
-    const sessionTabPinningReason = priorSessionPageState.pinningReason;
-    const priorRefSnapshotState = priorSessionPageState.refSnapshot;
-    const priorRefSnapshotInvalidation = priorSessionPageState.refSnapshotInvalidation;
     const resolvedSemanticActionRefSnapshot = semanticActionVisibleRefResolution?.snapshot
         ? { ...semanticActionVisibleRefResolution.snapshot, target: semanticActionVisibleRefResolution.snapshot.target ?? priorSessionTabTarget }
         : undefined;
@@ -629,7 +637,8 @@ export async function prepareBrowserRun(options) {
             sessionName: executionPlan.sessionName,
             stdin: runtimeToolStdin,
         })) {
-        const plannedSessionTabSelection = await collectSessionTabSelection({
+        const collectTabSelection = promptRefSnapshot && getGuardedRefUsage(commandTokens, runtimeToolStdin).length > 0 ? collectAnySessionTabSelection : collectSessionTabSelection;
+        const plannedSessionTabSelection = await collectTabSelection({
             cwd,
             namespace: executionPlan.namespace,
             sessionName: executionPlan.sessionName,

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

@@ -1,5 +1,6 @@
 import { readFile, rm } from "node:fs/promises";
 import { isCloseCommand, isNavigationObservableCommandName, isOpenNavigationCommand } from "../../command-taxonomy.js";
+import { OPEN_RESULT_TAB_CORRECTION_FLAGS } from "../../launch-scoped-flags.js";
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
 import { getAllowedDomainsViolation, parseAllowedDomainsPolicyFromArgs } from "../../navigation-policy.js";
 import { analyzeNetworkSourceLookupResults, analyzeQaPresetResults, analyzeQaPresetTimeout, analyzeSourceLookupResults, buildQaCompactPassText, extractQaPageContext, redactNetworkSourceLookupAnalysis, } from "../../input-modes.js";
@@ -10,7 +11,7 @@ import { shouldCaptureSemanticActionNavigationSummary } from "../../results/pres
 import { commandExplicitlyTargetsAboutBlank, deriveSessionTabTarget, extractLatestRefSnapshotStateFromBatchResults, extractRefSnapshotFromData, extractSessionTabTargetFromBatchResults, extractSessionTabTargetFromCommandData, isAboutBlankSessionTabTarget, normalizeSessionTabTarget, } from "../../session-page-state.js";
 import { writePersistentSessionArtifactFile, writeSecureTempFile } from "../../temp.js";
 import { isRecord } from "../../parsing.js";
-import { createFreshSessionName, extractCommandTokens, hasLaunchScopedTabCorrectionFlag, resolveManagedSessionState } from "../../runtime.js";
+import { createFreshSessionName, extractCommandTokens, resolveManagedSessionState } from "../../runtime.js";
 import { applyOpenResultTabCorrection, buildAboutBlankRecoveryHint, buildAboutBlankWarning, buildElectronPostCommandHealthDiagnostic, buildElectronRefFreshnessDiagnostic, buildElectronSessionMismatch, buildManagedSessionOutcome, closeManagedSession, collectOpenResultTabCorrection, collectSessionTabSelection, extractNavigationSummaryFromData, extractStringResultField, findElectronLaunchRecordForSession, formatElectronPostCommandHealthText, formatElectronSessionMismatchText, getSessionContextKey, getStaleRefArgs, mergeNavigationSummaryIntoData, shouldCaptureNavigationSummary, shouldCorrectSessionTabAfterCommand, shouldInspectElectronPostCommandHealth, unwrapPinnedSessionBatchEnvelope, 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";
@@ -194,7 +195,7 @@ export async function processBrowserOutput(input) {
             presentationEnvelope = { ...presentationEnvelope, data: mergeNavigationSummaryIntoData(presentationEnvelope.data, navigationSummary) };
         let overlayBlockerDiagnostic;
         let openResultTabCorrection;
-        if (succeeded && prepared.executionPlan.sessionName && hasLaunchScopedTabCorrectionFlag(prepared.runtimeToolArgs) && isOpenNavigationCommand(prepared.executionPlan.commandInfo.command)) {
+        if (succeeded && prepared.executionPlan.sessionName && prepared.executionPlan.startupScopedFlags.some((flag) => OPEN_RESULT_TAB_CORRECTION_FLAGS.has(flag)) && isOpenNavigationCommand(prepared.executionPlan.commandInfo.command) && !commandExplicitlyTargetsAboutBlank(prepared.commandTokens)) {
             const targetTitle = extractStringResultField(presentationEnvelope?.data, "title");
             const targetUrl = extractStringResultField(presentationEnvelope?.data, "url");
             const plannedTabCorrection = await collectOpenResultTabCorrection({ cwd, namespace: prepared.executionPlan.namespace, sessionName: prepared.executionPlan.sessionName, signal, targetTitle, targetUrl });

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

@@ -407,6 +407,13 @@ export function shouldCorrectSessionTabAfterCommand(options) {
         options.command !== undefined &&
         !isSessionTabPostCommandCorrectionExcludedCommand(options.command));
 }
+function getTabSelection(tab) {
+    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)
+        return { selectedTab: tab.label.trim(), selectionKind: "label" };
+    return typeof tab.index === "number" ? { selectedTab: String(tab.index), selectionKind: "index" } : undefined;
+}
 function selectSessionTargetTab(options) {
     return chooseOpenResultTabCorrection({
         tabs: options.tabs,
@@ -414,6 +421,16 @@ function selectSessionTargetTab(options) {
         targetUrl: options.target.url,
     });
 }
+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 targetTitle = options.target.title?.trim() ?? "";
+    const selectedTab = (targetTitle ? matchingTabs.find((tab) => tab.title?.trim() === targetTitle) : undefined) ?? matchingTabs[0];
+    const selection = selectedTab ? getTabSelection(selectedTab) : undefined;
+    return selection ? { ...selection, ...(targetTitle ? { targetTitle } : {}), targetUrl } : undefined;
+}
 export function unwrapPinnedSessionBatchEnvelope(options) {
     if (!options.envelope) {
         return {};
@@ -509,13 +526,10 @@ export async function collectOpenResultTabCorrection(options) {
     }));
     return chooseOpenResultTabCorrection({ tabs, targetTitle, targetUrl });
 }
-export async function collectSessionTabSelection(options) {
-    const { cwd, namespace, sessionName, signal, target } = options;
-    const tabData = await runSessionCommandData({ args: ["tab", "list"], cwd, namespace, sessionName, signal });
-    if (!isRecord(tabData) || !Array.isArray(tabData.tabs)) {
+function mapTabData(tabData) {
+    if (!isRecord(tabData) || !Array.isArray(tabData.tabs))
         return undefined;
-    }
-    const tabs = tabData.tabs.filter(isRecord).map((tab, index) => ({
+    return tabData.tabs.filter(isRecord).map((tab, index) => ({
         active: tab.active === true,
         index: typeof tab.index === "number" ? tab.index : index,
         label: typeof tab.label === "string" ? tab.label : undefined,
@@ -523,7 +537,18 @@ export async function collectSessionTabSelection(options) {
         title: typeof tab.title === "string" ? tab.title : undefined,
         url: typeof tab.url === "string" ? tab.url : undefined,
     }));
-    return selectSessionTargetTab({ tabs, target });
+}
+export async function collectSessionTabSelection(options) {
+    const { cwd, namespace, sessionName, signal, target } = options;
+    const tabData = await runSessionCommandData({ args: ["tab", "list"], cwd, namespace, sessionName, signal });
+    const tabs = mapTabData(tabData);
+    return tabs ? selectSessionTargetTab({ tabs, target }) : undefined;
+}
+export async function collectAnySessionTabSelection(options) {
+    const { cwd, namespace, sessionName, signal, target } = options;
+    const tabData = await runSessionCommandData({ args: ["tab", "list"], cwd, namespace, sessionName, signal });
+    const tabs = mapTabData(tabData);
+    return tabs ? selectAnySessionTargetTab({ tabs, target }) : undefined;
 }
 export async function applyOpenResultTabCorrection(options) {
     const { correction, cwd, namespace, sessionName, signal } = options;

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

@@ -71,8 +71,8 @@ export const INSPECTION_TOOL_CALL_EXAMPLES = [
     '{ "args": ["--version"] }',
 ];
 export const WRAPPER_TAB_RECOVERY_BEHAVIOR = [
-    "After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --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.",
-    "After the wrapper observes tab-drift risk for a session (for example profile restore correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab is known.",
+    "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 the wrapper observes tab-drift risk for a session (for example open correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab or ref snapshot is known.",
     "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.",
     "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.",
 ];

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

@@ -13,7 +13,7 @@ import { findCommandStartIndex, parseArgvDescriptor, parseCommandInfo, } from ".
 import { GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, PREVALIDATED_VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, } from "./argv-grammar.js";
 import { needsManagedSession } from "./command-policy.js";
 import { isCloseCommand, isOpenNavigationCommand } from "./command-taxonomy.js";
-import { LAUNCH_SCOPED_FLAG_DEFINITIONS, LAUNCH_SCOPED_FLAG_LABEL, LAUNCH_SCOPED_TAB_CORRECTION_FLAGS } from "./launch-scoped-flags.js";
+import { LAUNCH_SCOPED_FLAG_DEFINITIONS, LAUNCH_SCOPED_FLAG_LABEL } from "./launch-scoped-flags.js";
 export { extractCommandTokens, findCommandStartIndex, parseArgvDescriptor, parseCommandInfo } from "./argv-descriptor.js";
 import { isRecord } from "./parsing.js";
 const OPENAI_HEADLESS_COMPAT_HOSTS = new Set(["chat.com", "chat.openai.com", "chatgpt.com"]);
@@ -773,15 +773,6 @@ export function getStartupScopedFlags(args) {
         .map((definition) => definition.flag)
         .filter((flag) => hasLaunchScopedFlagToken(args, flag));
 }
-export function hasLaunchScopedTabCorrectionFlag(args) {
-    return args.some((token) => {
-        for (const flag of LAUNCH_SCOPED_TAB_CORRECTION_FLAGS) {
-            if (token === flag || token.startsWith(`${flag}=`))
-                return true;
-        }
-        return false;
-    });
-}
 export function buildExecutionPlan(args, options) {
     const invalidValueFlag = getInvalidValueFlagDetails(args);
     const explicitNamespace = extractExplicitNamespace(args);

package/docs/COMMAND_REFERENCE.md

@@ -891,8 +891,8 @@ Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGE
 - If a `sessionMode: "fresh"` call fails (including upstream failure, timeout, missing binary, or **`qa`** reclassification after a nominally successful batch), read `details.managedSessionOutcome` before assuming where the next default call will go: `preserved` means the prior managed session remains current, while `abandoned` means no managed session became current. When the failure reason is not the fresh launch itself—for example `failureCategory: "qa-failure"`—`status`/`summary` may still describe the managed-session transition while `succeeded` on this object matches the final tool outcome.
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
-- After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --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.
-- After the wrapper observes tab-drift risk for a session (for example profile restore correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab is known.
+- 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 the wrapper observes tab-drift risk for a session (for example open correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab or ref snapshot is known.
 - 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.
 - 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.
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->

package/docs/TOOL_CONTRACT.md

@@ -877,8 +877,8 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
-- After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --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.
-- After the wrapper observes tab-drift risk for a session (for example profile restore correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab is known.
+- 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 the wrapper observes tab-drift risk for a session (for example open correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab or ref snapshot is known.
 - 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.
 - 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.
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->

package/package.json

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