@nuanu-ai/agentbrowse 0.2.23 → 0.2.25

package/dist/commands/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/commands/act.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAqCnD,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAyHxF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,CAAC;AA4V7B,wBAAsB,GAAG,CACvB,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmsBf"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/commands/act.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAsCnD,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA2HxF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,CAAC;AA4V7B,wBAAsB,GAAG,CACvB,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAitBf"}

package/dist/commands/act.js

@@ -7,6 +7,7 @@ import { outputContractFailure, outputFailure, outputJSON } from '../output.js';
 import { capturePageObservation, captureLocatorContextHash, captureLocatorState, createAcceptanceProbe, diagnoseNoObservableProgress, genericClickObservationChanged, locatorStateChanged, pageObservationChanged, rankLocatorCandidates, shouldVerifyObservableProgress, waitForAcceptanceProbe, } from './action-acceptance.js';
 import { captureActionFailureArtifacts, startActionTrace } from './action-artifacts.js';
 import { buildLocator, resolveLocatorRoot } from './action-fallbacks.js';
+import { clickActivationStrategyForTarget } from './click-activation-policy.js';
 import { resolveSubmitResult } from './action-result-resolution.js';
 import { projectActionValue } from './action-value-projection.js';
 import { applyActionWithFallbacks } from './action-executor.js';
@@ -23,6 +24,7 @@ function ensureValue(action, value) {
         return value;
     throw new Error(`Act value is required for action: ${action}`);
 }
+const MUTABLE_FIELD_REBIND_RETRY_DELAYS_MS = [0, 25, 50];
 function emitActPreflightFailure(params) {
     return outputContractFailure({
         error: params.error,
@@ -465,30 +467,41 @@ export async function act(session, targetRef, action, value) {
             if (!liveTarget.domSignature) {
                 return false;
             }
-            const snapshot = await readLocatorBindingSnapshot(resolvedLocator).catch(() => null);
-            if (!snapshot?.domSignature || snapshot.domSignature === liveTarget.domSignature) {
-                return false;
-            }
-            if (!isCompatibleMutableFieldBinding(liveTarget, snapshot)) {
-                return false;
-            }
-            attempts.push(`domSignature.rebound:${strategy}`);
-            const updatedTarget = updateTarget(session, targetRef, {
-                domSignature: snapshot.domSignature,
-                label: snapshot.label ?? liveTarget.label,
-                lifecycle: 'live',
-                lifecycleReason: undefined,
-                availability: { state: 'available' },
-                semantics: {
-                    ...liveTarget.semantics,
-                    name: snapshot.label ?? liveTarget.semantics?.name,
-                    role: snapshot.role ?? liveTarget.semantics?.role,
-                },
-            });
-            if (updatedTarget) {
-                liveTarget = updatedTarget;
+            for (let attemptIndex = 0; attemptIndex < MUTABLE_FIELD_REBIND_RETRY_DELAYS_MS.length; attemptIndex += 1) {
+                const delayMs = MUTABLE_FIELD_REBIND_RETRY_DELAYS_MS[attemptIndex] ?? 0;
+                if (attemptIndex > 0) {
+                    attempts.push(`domSignature.rebind.retry:${strategy}:${attemptIndex + 1}`);
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+                const snapshot = await readLocatorBindingSnapshot(resolvedLocator).catch(() => null);
+                if (!snapshot?.domSignature) {
+                    continue;
+                }
+                if (snapshot.domSignature === liveTarget.domSignature) {
+                    return false;
+                }
+                if (!isCompatibleMutableFieldBinding(liveTarget, snapshot)) {
+                    continue;
+                }
+                attempts.push(`domSignature.rebound:${strategy}`);
+                const updatedTarget = updateTarget(session, targetRef, {
+                    domSignature: snapshot.domSignature,
+                    label: snapshot.label ?? liveTarget.label,
+                    lifecycle: 'live',
+                    lifecycleReason: undefined,
+                    availability: { state: 'available' },
+                    semantics: {
+                        ...liveTarget.semantics,
+                        name: snapshot.label ?? liveTarget.semantics?.name,
+                        role: snapshot.role ?? liveTarget.semantics?.role,
+                    },
+                });
+                if (updatedTarget) {
+                    liveTarget = updatedTarget;
+                }
+                return true;
             }
-            return true;
+            return false;
         };
         const assertResolvedTargetStillValid = async (resolvedLocator, stage) => {
             if (liveTarget.pageSignature &&
@@ -596,6 +609,7 @@ export async function act(session, targetRef, action, value) {
                 });
                 attempts.push(`resolve:${strategy}`);
                 const usedFallback = await applyActionWithFallbacks(page, locatorRoot, resolvedLocator, action, executionValue, attempts, target.controlFamily, {
+                    clickActivationStrategy: clickActivationStrategyForTarget(target, action),
                     guards: {
                         assertStillValid: async (stage) => {
                             await assertResolvedTargetStillValid(resolvedLocator, stage);

package/dist/commands/action-executor.d.ts

@@ -3,9 +3,11 @@ import type { TargetControlFamily } from '../runtime-state.js';
 import type { BrowseAction } from './browse-actions.js';
 import type { LocatorRoot } from './action-fallbacks.js';
 import type { ActionExecutionGuards } from './action-execution-guards.js';
+import type { ClickActivationStrategy } from './click-activation-policy.js';
 type ActionExecutionOptions = {
     beforeClickRetry?: () => Promise<void>;
     guards?: ActionExecutionGuards;
+    clickActivationStrategy?: ClickActivationStrategy;
 };
 export declare function applyActionWithFallbacks(page: Page, root: LocatorRoot, locator: Locator, action: BrowseAction, value: string | undefined, attempts: string[], family?: TargetControlFamily, options?: ActionExecutionOptions): Promise<boolean>;
 export {};

package/dist/commands/action-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-executor.d.ts","sourceRoot":"","sources":["../../src/commands/action-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAc1E,KAAK,sBAAsB,GAAG;IAC5B,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,CAAC,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,OAAO,CAAC,CAqDlB"}
+{"version":3,"file":"action-executor.d.ts","sourceRoot":"","sources":["../../src/commands/action-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAc5E,KAAK,sBAAsB,GAAG;IAC5B,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,uBAAuB,CAAC,EAAE,uBAAuB,CAAC;CACnD,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,CAAC,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,OAAO,CAAC,CAsDlB"}

package/dist/commands/action-executor.js

@@ -14,6 +14,7 @@ export async function applyActionWithFallbacks(page, root, locator, action, valu
                 return applyTriggerAction(page, locator, attempts, {
                     beforeRetry: options?.beforeClickRetry,
                     guards: options?.guards,
+                    clickActivationStrategy: options?.clickActivationStrategy,
                 });
             }
             return applyEditableClickAction(page, locator, attempts, {

package/dist/commands/action-result-resolution.d.ts

@@ -1,5 +1,5 @@
 import { type AcceptanceProbe, type PageObservation } from './action-acceptance.js';
-export type SubmitResultClaimKind = 'hard_result' | 'hard_blocker' | 'soft_result_candidate' | 'noisy_change';
+export type SubmitResultClaimKind = 'hard_result' | 'hard_blocker' | 'intermediate_progress' | 'soft_result_candidate' | 'noisy_change';
 export type SubmitResultClaim = {
     kind: SubmitResultClaimKind;
     source: string;
@@ -7,7 +7,7 @@ export type SubmitResultClaim = {
     ownerScopeRef?: string;
 };
 export type SubmitResultResolution = {
-    finalVerdict: 'outcome' | 'blocked' | 'none';
+    finalVerdict: 'outcome' | 'blocked' | 'progress' | 'none';
     claims: SubmitResultClaim[];
     decisiveClaims: SubmitResultClaim[];
     acceptAsProgress: boolean;

package/dist/commands/action-result-resolution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-result-resolution.d.ts","sourceRoot":"","sources":["../../src/commands/action-result-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAGhC,MAAM,MAAM,qBAAqB,GAC7B,aAAa,GACb,cAAc,GACd,uBAAuB,GACvB,cAAc,CAAC;AAEnB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC7C,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,CAAC,iBAAiB,CAAC,GACvC,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,kBAAkB,CAAC,CAqB7D;AAmBD,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,eAAe,EACtB,oBAAoB,EAAE,eAAe,GAAG,IAAI,GAC3C,OAAO,CAAC,sBAAsB,CAAC,CAsEjC"}
+{"version":3,"file":"action-result-resolution.d.ts","sourceRoot":"","sources":["../../src/commands/action-result-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAGhC,MAAM,MAAM,qBAAqB,GAC7B,aAAa,GACb,cAAc,GACd,uBAAuB,GACvB,uBAAuB,GACvB,cAAc,CAAC;AAEnB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IAC1D,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,CAAC,iBAAiB,CAAC,GACvC,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,kBAAkB,CAAC,CA+B7D;AAmBD,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,eAAe,EACtB,oBAAoB,EAAE,eAAe,GAAG,IAAI,GAC3C,OAAO,CAAC,sBAAsB,CAAC,CAoFjC"}

package/dist/commands/action-result-resolution.js

@@ -15,6 +15,13 @@ export function reduceSubmitResultClaims(claims) {
             decisiveClaims: hardResults,
         };
     }
+    const intermediateProgressClaims = claims.filter((claim) => claim.kind === 'intermediate_progress');
+    if (intermediateProgressClaims.length > 0) {
+        return {
+            finalVerdict: 'progress',
+            decisiveClaims: intermediateProgressClaims,
+        };
+    }
     return {
         finalVerdict: 'none',
         decisiveClaims: [],
@@ -62,6 +69,8 @@ export async function resolveSubmitResult(probe, afterPageObservation) {
     }
     const resultSignalChanged = beforePageObservation.resultSignalHash !== afterPageObservation.resultSignalHash &&
         afterPageObservation.resultSignalHash !== null;
+    const submitSignalChanged = beforePageObservation.submitSignalHash !== afterPageObservation.submitSignalHash &&
+        afterPageObservation.submitSignalHash !== null;
     const afterSurfaceContextHash = await captureAfterSurfaceContextHash(probe);
     const ownerScopeChanged = probe.beforeSurfaceContextHash !== null &&
         afterSurfaceContextHash !== null &&
@@ -77,18 +86,29 @@ export async function resolveSubmitResult(probe, afterPageObservation) {
         });
     }
     else if (ownerScopeChanged) {
-        claims.push({
-            kind: 'noisy_change',
-            source: 'owner-scope',
-            reason: 'Owner scope changed after submit without a result-bearing signal.',
-            ownerScopeRef: probe.surface?.ref,
-        });
+        if (submitSignalChanged) {
+            claims.push({
+                kind: 'intermediate_progress',
+                source: 'owner-scope',
+                reason: 'Owner scope changed after submit with a submit-relevant follow-up state change.',
+                ownerScopeRef: probe.surface?.ref,
+            });
+        }
+        else {
+            claims.push({
+                kind: 'noisy_change',
+                source: 'owner-scope',
+                reason: 'Owner scope changed after submit without a result-bearing signal.',
+                ownerScopeRef: probe.surface?.ref,
+            });
+        }
     }
     const reduced = reduceSubmitResultClaims(claims);
     return {
         ...reduced,
         claims,
         acceptAsProgress: reduced.finalVerdict === 'outcome' ||
+            reduced.finalVerdict === 'progress' ||
             (reduced.finalVerdict === 'none' &&
                 claims.some((claim) => claim.kind === 'soft_result_candidate')),
     };

package/dist/commands/click-action-executor.d.ts

@@ -1,8 +1,10 @@
 import type { Locator, Page } from 'playwright-core';
+import type { ClickActivationStrategy } from './click-activation-policy.js';
 import { type ActionExecutionGuards } from './action-execution-guards.js';
 type ClickRetryOptions = {
     beforeRetry?: () => Promise<void>;
     guards?: ActionExecutionGuards;
+    clickActivationStrategy?: ClickActivationStrategy;
 };
 export declare function applyEditableClickAction(page: Page, locator: Locator, attempts: string[], options?: ClickRetryOptions): Promise<boolean>;
 export declare function applyTriggerAction(page: Page, locator: Locator, attempts: string[], options?: ClickRetryOptions): Promise<boolean>;

package/dist/commands/click-action-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"click-action-executor.d.ts","sourceRoot":"","sources":["../../src/commands/click-action-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAMrD,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAEnG,KAAK,iBAAiB,GAAG;IACvB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC,CAAC;AA+FF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAElB"}
+{"version":3,"file":"click-action-executor.d.ts","sourceRoot":"","sources":["../../src/commands/click-action-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAMrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAEnG,KAAK,iBAAiB,GAAG;IACvB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,uBAAuB,CAAC,EAAE,uBAAuB,CAAC;CACnD,CAAC;AA2GF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAElB"}

package/dist/commands/click-action-executor.js

@@ -28,6 +28,17 @@ async function ensureLocatorRetryReady(locator, error, options) {
 }
 async function applyClickSequence(page, locator, attempts, options) {
     await handoffFocusFromActiveIframe(locator, attempts);
+    if (options?.clickActivationStrategy === 'dom') {
+        await runActionExecutionGuard(options?.guards, 'click.evaluate.primary');
+        attempts.push('locator.evaluate.click.primary');
+        await locator.evaluate((element) => {
+            if (!(element instanceof HTMLElement)) {
+                throw new Error('unsupported_js_click_fallback');
+            }
+            element.click();
+        });
+        return false;
+    }
     attempts.push('locator.click');
     try {
         await locator.click({ timeout: LOCATOR_CLICK_TIMEOUT_MS });

package/dist/commands/click-activation-policy.d.ts

@@ -0,0 +1,5 @@
+import type { TargetDescriptor } from '../runtime-state.js';
+import type { BrowseAction } from './browse-actions.js';
+export type ClickActivationStrategy = 'pointer' | 'dom';
+export declare function clickActivationStrategyForTarget(target: Pick<TargetDescriptor, 'kind' | 'framePath' | 'semantics'>, action: BrowseAction): ClickActivationStrategy;
+//# sourceMappingURL=click-activation-policy.d.ts.map

package/dist/commands/click-activation-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"click-activation-policy.d.ts","sourceRoot":"","sources":["../../src/commands/click-activation-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,KAAK,CAAC;AAExD,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC,EAClE,MAAM,EAAE,YAAY,GACnB,uBAAuB,CAezB"}

package/dist/commands/click-activation-policy.js

@@ -0,0 +1,13 @@
+export function clickActivationStrategyForTarget(target, action) {
+    if (action !== 'click') {
+        return 'pointer';
+    }
+    const withinIframe = Boolean(target.framePath?.length);
+    if (!withinIframe) {
+        return 'pointer';
+    }
+    const kind = target.kind?.trim().toLowerCase();
+    const role = target.semantics?.role?.trim().toLowerCase();
+    const isTab = kind === 'tab' || role === 'tab';
+    return isTab ? 'dom' : 'pointer';
+}

package/dist/commands/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/commands/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAmMnD,wBAAsB,OAAO,CAC3B,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAkMf"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/commands/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAoMnD,wBAAsB,OAAO,CAC3B,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAyMf"}

package/dist/commands/extract.js

@@ -6,7 +6,7 @@ import { AgentpayStructuredOutputTruncatedError } from '../agentpay-stagehand-ll
 import { saveSession } from '../session.js';
 import { getSurface, getTarget, markSurfaceLifecycle, markTargetLifecycle, setCurrentPage, } from '../runtime-state.js';
 import { outputContractFailure, outputJSON } from '../output.js';
-import { connectPlaywright, disconnectPlaywright, resolvePageByRef as resolvePlaywrightPageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, resolvePageByRef as resolvePlaywrightPageByRef, syncSessionPage, } from '../playwright-runtime.js';
 import { normalizePageSignature } from './descriptor-validation.js';
 import { readScopedDialogText } from './extract-scoped-dialog-text.js';
 import { resolveScopedExtractContext } from './extract-scope-resolution.js';
@@ -174,7 +174,7 @@ export async function extract(session, schemaJson, scopeRef) {
     const targetScope = scopeRef ? getTarget(session, scopeRef) : null;
     const surfaceScope = !targetScope && scopeRef ? getSurface(session, scopeRef) : null;
     const scopeTarget = targetScope ?? surfaceScope;
-    const pageRef = scopeTarget?.pageRef ?? session.runtime?.currentPageRef ?? 'p0';
+    let pageRef = scopeTarget?.pageRef ?? session.runtime?.currentPageRef ?? 'p0';
     if (scopeRef && !scopeTarget) {
         return outputContractFailure({
             error: 'unknown_scope_ref',
@@ -221,7 +221,15 @@ export async function extract(session, schemaJson, scopeRef) {
         });
     }
     try {
-        const sourcePage = await resolvePlaywrightPageByRef(browser, session, pageRef);
+        let sourcePage;
+        if (scopeTarget) {
+            sourcePage = await resolvePlaywrightPageByRef(browser, session, pageRef);
+        }
+        else {
+            const resolvedPage = await resolveCurrentPageContext(browser, session);
+            pageRef = resolvedPage.pageRef;
+            sourcePage = resolvedPage.page;
+        }
         let page = sourcePage;
         let scopedResolution = null;
         const { url, title } = await syncSessionPage(session, pageRef, sourcePage);

package/dist/commands/launch.js

@@ -9,7 +9,7 @@ import { findChromePid } from '../stagehand.js';
 import { applyAgentpayGatewayEnv, tryResolveAgentpayGatewayConfig } from '../agentpay-gateway.js';
 import { connectPlaywright, disconnectPlaywright, syncLaunchPage } from '../playwright-runtime.js';
 import { summarizeSecretCatalog, syncSecretCatalogForUrl } from '../secrets/catalog-sync.js';
-import { terminateOwnedPid } from '../owned-process.js';
+import { cleanupManagedBrowserPids, terminateOwnedPid } from '../owned-process.js';
 import { info } from '../output.js';
 const DEFAULT_PROFILE = 'default';
 const COMPACT_WINDOW = {
@@ -30,12 +30,22 @@ export async function launch(url, opts) {
 }
 async function cleanupOwnedSession() {
     const existingSession = loadSession();
-    if (!isOwnedSession(existingSession)) {
-        return null;
+    const excludePids = new Set();
+    if (isOwnedSession(existingSession)) {
+        excludePids.add(existingSession.pid);
+        const termination = await terminateOwnedPid(existingSession.pid);
+        if (termination === 'still_alive') {
+            return buildLaunchFailure(new Error(`Existing owned browser pid ${existingSession.pid} did not exit after SIGTERM/SIGKILL.`));
+        }
+    }
+    // Phase-1 ownership removed port-global prekill, so launch needs a second guardrail
+    // for crashes that happen before a session record is persisted or cleaned up.
+    const orphanCleanup = await cleanupManagedBrowserPids({ excludePids });
+    if (orphanCleanup.blocked.length > 0) {
+        return buildLaunchFailure(new Error(`Orphaned managed browser pid${orphanCleanup.blocked.length === 1 ? '' : 's'} ${orphanCleanup.blocked.join(', ')} did not exit after SIGTERM/SIGKILL.`));
     }
-    const termination = await terminateOwnedPid(existingSession.pid);
-    if (termination === 'still_alive') {
-        return buildLaunchFailure(new Error(`Existing owned browser pid ${existingSession.pid} did not exit after SIGTERM/SIGKILL.`));
+    if (orphanCleanup.terminated.length > 0) {
+        info(`[launch] cleaned up orphaned managed browser pid${orphanCleanup.terminated.length === 1 ? '' : 's'} ${orphanCleanup.terminated.join(', ')}`);
     }
     return null;
 }

package/dist/commands/navigate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigate.d.ts","sourceRoot":"","sources":["../../src/commands/navigate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAiBnD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDvF"}
+{"version":3,"file":"navigate.d.ts","sourceRoot":"","sources":["../../src/commands/navigate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAgBnD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwDvF"}

package/dist/commands/navigate.js

@@ -1,11 +1,11 @@
 /**
  * browse navigate <url> — Navigate the current tab to a URL.
  */
-import { clearProtectedExposure } from '../runtime-state.js';
+import { clearProtectedExposure, setCurrentPage } from '../runtime-state.js';
 import { saveSession } from '../session.js';
 import { outputContractFailure, outputJSON, info } from '../output.js';
 import { summarizeSecretCatalog, syncSecretCatalogForUrl, tryResolveCatalogHost, } from '../secrets/catalog-sync.js';
-import { connectPlaywright, disconnectPlaywright, listPages, resolvePageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, syncSessionPage, } from '../playwright-runtime.js';
 export async function navigate(session, targetUrl) {
     let browser = null;
     let failureMessage = null;
@@ -22,18 +22,18 @@ export async function navigate(session, targetUrl) {
         });
     }
     try {
-        const pageRef = session.runtime?.currentPageRef ?? 'p0';
+        let pageRef = session.runtime?.currentPageRef ?? 'p0';
+        const resolvedPage = await resolveCurrentPageContext(browser, session);
+        pageRef = resolvedPage.pageRef;
+        const page = resolvedPage.page;
         const previousUrl = session.runtime?.pages?.[pageRef]?.url;
         const previousHost = tryResolveCatalogHost(previousUrl);
-        const pages = listPages(browser);
-        const page = session.runtime?.pages[pageRef] || pages.length > 1
-            ? await resolvePageByRef(browser, session, pageRef)
-            : pages[0];
         if (!page) {
             throw new Error('no_open_pages');
         }
         await page.goto(targetUrl, { waitUntil: 'domcontentloaded' });
         const { url, title } = await syncSessionPage(session, pageRef, page);
+        setCurrentPage(session, pageRef);
         clearProtectedExposure(session, pageRef);
         const nextHost = tryResolveCatalogHost(url);
         if (nextHost && nextHost !== previousHost) {

package/dist/commands/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/commands/observe.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAqDnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAU/D,eAAO,MAAM,yBAAyB;;;;iBA4TwQ,CAAC;gBAAwB,CAAC;;;;CA5TnQ,CAAC;AACtE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGrC,CAAC;AAEF,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqTzF"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/commands/observe.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA0DnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAU/D,eAAO,MAAM,yBAAyB;;;;iBA6T7B,CAAC;gBAEE,CAAA;;;;CA/TyD,CAAC;AACtE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGrC,CAAC;AAEF,wBAAsB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8TzF"}

package/dist/commands/observe.js

@@ -2,8 +2,8 @@
  * browse observe ["<instruction>"] — Discover available actions on the page.
  */
 import { saveSession } from '../session.js';
-import { ensureRuntimeState, incrementMetric, replaceTargetsForPage } from '../runtime-state.js';
-import { connectPlaywright, disconnectPlaywright, resolvePageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { ensureRuntimeState, incrementMetric, replaceTargetsForPage, setCurrentPage, } from '../runtime-state.js';
+import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, syncSessionPage, } from '../playwright-runtime.js';
 import { outputContractFailure, outputJSON } from '../output.js';
 import { domRuntimeResolution, stagehandRuntimeResolution } from '../runtime-resolution.js';
 import { withStagehand } from '../stagehand-runtime.js';
@@ -26,7 +26,7 @@ export const __testStagehandDescriptor = {
 };
 export async function observe(session, instruction) {
     const runtime = ensureRuntimeState(session);
-    const pageRef = runtime.currentPageRef;
+    let pageRef = runtime.currentPageRef;
     let domPassError = null;
     let stagehandFallbackReason = null;
     let browser = null;
@@ -34,8 +34,11 @@ export async function observe(session, instruction) {
     if (!instruction) {
         try {
             browser = await connectPlaywright(session.cdpUrl);
-            const page = await resolvePageByRef(browser, session, pageRef);
+            const resolvedPage = await resolveCurrentPageContext(browser, session);
+            pageRef = resolvedPage.pageRef;
+            const page = resolvedPage.page;
             const { url, title } = await syncSessionPage(session, pageRef, page);
+            setCurrentPage(session, pageRef);
             const collectedTargets = await collectDomTargets(page);
             let observeAccessibilityStats;
             const domTargets = compressSemanticallyDuplicateTargets(orderBySurfaceCompetition(annotateDomTargets(await enrichDomTargetsWithAccessibility(page, collectedTargets, {
@@ -96,8 +99,11 @@ export async function observe(session, instruction) {
             if (!browser) {
                 browser = await connectPlaywright(session.cdpUrl);
             }
-            const page = await resolvePageByRef(browser, session, pageRef);
+            const resolvedPage = await resolveCurrentPageContext(browser, session);
+            pageRef = resolvedPage.pageRef;
+            const page = resolvedPage.page;
             const { url, title } = await syncSessionPage(session, pageRef, page);
+            setCurrentPage(session, pageRef);
             const collectedTargets = await collectDomTargets(page, {
                 includeActivationAffordances: true,
             });
@@ -198,8 +204,11 @@ export async function observe(session, instruction) {
         });
     }
     try {
-        const page = await resolvePageByRef(browser, session, pageRef);
+        const resolvedPage = await resolveCurrentPageContext(browser, session);
+        pageRef = resolvedPage.pageRef;
+        const page = resolvedPage.page;
         const { url, title } = await syncSessionPage(session, pageRef, page);
+        setCurrentPage(session, pageRef);
         const signals = compactSignals(await collectPageSignals(page).catch(() => []));
         const actions = await withStagehand(session, async (stagehand) => {
             incrementMetric(session, 'stagehandCalls');

package/dist/commands/screenshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/commands/screenshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAYnD,wBAAsB,UAAU,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDzF"}
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/commands/screenshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAWnD,wBAAsB,UAAU,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmEzF"}

package/dist/commands/screenshot.js

@@ -1,20 +1,21 @@
 /**
  * browse screenshot [--path <file>] — Capture a screenshot of the current page.
  */
-import { getProtectedExposure } from '../runtime-state.js';
+import { getProtectedExposure, setCurrentPage } from '../runtime-state.js';
 import { saveSession } from '../session.js';
 import { outputFailure, outputJSON, outputContractFailure, info } from '../output.js';
-import { connectPlaywright, disconnectPlaywright, listPages, resolvePageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { connectPlaywright, disconnectPlaywright, resolveCurrentPageContext, syncSessionPage, } from '../playwright-runtime.js';
 import { buildProtectedScreenshotBlockedResult } from '../secrets/protected-artifact-guard.js';
 export async function screenshot(session, filePath) {
     const outputPath = filePath ?? `/tmp/browse-screenshot-${Date.now()}.png`;
-    const pageRef = session.runtime?.currentPageRef ?? 'p0';
-    const protectedExposure = getProtectedExposure(session, pageRef);
-    if (protectedExposure) {
-        return outputFailure(buildProtectedScreenshotBlockedResult(protectedExposure));
+    let pageRef = session.runtime?.currentPageRef ?? 'p0';
+    const initialProtectedExposure = getProtectedExposure(session, pageRef);
+    if (initialProtectedExposure) {
+        return outputFailure(buildProtectedScreenshotBlockedResult(initialProtectedExposure));
     }
     let browser = null;
     let failureMessage = null;
+    let page = null;
     try {
         browser = await connectPlaywright(session.cdpUrl);
     }
@@ -27,16 +28,29 @@ export async function screenshot(session, filePath) {
         });
     }
     try {
-        const pages = listPages(browser);
-        const page = session.runtime?.pages[pageRef] || pages.length > 1
-            ? await resolvePageByRef(browser, session, pageRef)
-            : pages[0];
+        const resolvedPage = await resolveCurrentPageContext(browser, session);
+        pageRef = resolvedPage.pageRef;
+        page = resolvedPage.page;
+    }
+    catch (err) {
+        failureMessage = `Screenshot failed: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const recoveredProtectedExposure = getProtectedExposure(session, pageRef);
+    if (recoveredProtectedExposure) {
+        if (browser) {
+            disconnectPlaywright(browser);
+            browser = null;
+        }
+        return outputFailure(buildProtectedScreenshotBlockedResult(recoveredProtectedExposure));
+    }
+    try {
         if (!page) {
-            throw new Error('no_open_pages');
+            throw new Error(failureMessage?.replace(/^Screenshot failed:\s*/, '') ?? 'no_open_pages');
         }
         await page.screenshot({ path: outputPath });
         info(`Screenshot saved: ${outputPath}`);
         const { url, title } = await syncSessionPage(session, pageRef, page);
+        setCurrentPage(session, pageRef);
         saveSession(session);
         outputJSON({ success: true, pageRef, path: outputPath, url, title });
     }

package/dist/commands/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoDH,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CA8F5C"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmKH,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAgG5C"}

package/dist/commands/status.js

@@ -3,6 +3,21 @@
  */
 import { loadSession, isSessionAlive, getSessionPort, supportsCaptchaSolve } from '../session.js';
 import { outputJSON } from '../output.js';
+function normalizeComparableUrl(url) {
+    const raw = url?.trim();
+    if (!raw) {
+        return null;
+    }
+    try {
+        const parsed = new URL(raw);
+        parsed.hash = '';
+        parsed.search = '';
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        return raw;
+    }
+}
 function tryResolveHost(url) {
     if (!url) {
         return undefined;
@@ -23,6 +38,7 @@ function buildProtectedStatusPayload(params) {
             ? { captchaSolveCapable: params.captchaSolveCapable }
             : {}),
         runtime: params.runtimeSummary,
+        ...(params.currentPageMismatch ? { currentPageMismatch: params.currentPageMismatch } : {}),
         protectedExposureActive: true,
         pageRef: params.protectedExposure.pageRef,
         url: params.pageUrl ?? 'unknown',
@@ -36,6 +52,70 @@ function buildProtectedStatusPayload(params) {
         reason: 'AgentBrowse is treating the current page as sensitive because a protected fill was executed and values may still be visible.',
     };
 }
+function matchesStoredPage(page, livePage) {
+    const storedUrl = normalizeComparableUrl(page?.url);
+    const currentUrl = normalizeComparableUrl(livePage.url);
+    if (!storedUrl || !currentUrl || storedUrl !== currentUrl) {
+        return null;
+    }
+    if (page?.title && livePage.title && page.title === livePage.title) {
+        return 'url-title-match';
+    }
+    return 'url-match';
+}
+function resolveCurrentPageMismatch(session, livePage) {
+    const runtime = session?.runtime;
+    if (!runtime || !livePage) {
+        return undefined;
+    }
+    const persistedPageRef = runtime.currentPageRef;
+    const currentPage = runtime.pages[persistedPageRef];
+    if (!currentPage) {
+        return {
+            persistedPageRef,
+        };
+    }
+    if (matchesStoredPage(currentPage, livePage)) {
+        return undefined;
+    }
+    const openerPageRef = currentPage.openerPageRef;
+    if (openerPageRef && matchesStoredPage(runtime.pages[openerPageRef], livePage)) {
+        return {
+            persistedPageRef,
+            livePageRef: openerPageRef,
+            recoveredVia: 'opener',
+        };
+    }
+    const exactMatches = Object.values(runtime.pages).filter((page) => {
+        if (page.pageRef === persistedPageRef || page.pageRef === openerPageRef) {
+            return false;
+        }
+        return matchesStoredPage(page, livePage) === 'url-title-match';
+    });
+    if (exactMatches.length === 1) {
+        return {
+            persistedPageRef,
+            livePageRef: exactMatches[0].pageRef,
+            recoveredVia: 'url-title-match',
+        };
+    }
+    const urlOnlyMatches = Object.values(runtime.pages).filter((page) => {
+        if (page.pageRef === persistedPageRef || page.pageRef === openerPageRef) {
+            return false;
+        }
+        return matchesStoredPage(page, livePage) === 'url-match';
+    });
+    if (urlOnlyMatches.length === 1) {
+        return {
+            persistedPageRef,
+            livePageRef: urlOnlyMatches[0].pageRef,
+            recoveredVia: 'url-match',
+        };
+    }
+    return {
+        persistedPageRef,
+    };
+}
 export async function status() {
     const session = loadSession();
     const port = getSessionPort(session);
@@ -57,15 +137,17 @@ export async function status() {
                 const listRes = await fetch(`http://localhost:${port}/json/list`);
                 const targets = (await listRes.json());
                 const page = targets.find((t) => t.type === 'page' && !t.url.startsWith('devtools://'));
-                const currentPageRef = session?.runtime?.currentPageRef;
-                const protectedExposure = currentPageRef
-                    ? session?.runtime?.protectedExposureByPage?.[currentPageRef]
+                const currentPageMismatch = resolveCurrentPageMismatch(session, page);
+                const effectivePageRef = currentPageMismatch?.livePageRef ?? session?.runtime?.currentPageRef;
+                const protectedExposure = effectivePageRef
+                    ? session?.runtime?.protectedExposureByPage?.[effectivePageRef]
                     : undefined;
                 if (protectedExposure) {
                     outputJSON(buildProtectedStatusPayload({
                         runtimeSummary,
                         pageUrl: page?.url,
                         pageTitle: page?.title,
+                        currentPageMismatch,
                         protectedExposure,
                     }));
                     return;
@@ -76,6 +158,7 @@ export async function status() {
                     url: page?.url ?? 'unknown',
                     title: page?.title ?? 'unknown',
                     runtime: runtimeSummary,
+                    ...(currentPageMismatch ? { currentPageMismatch } : {}),
                 });
                 return;
             }
@@ -90,9 +173,10 @@ export async function status() {
         const listRes = await fetch(`http://localhost:${port}/json/list`);
         const targets = (await listRes.json());
         const page = targets.find((t) => t.type === 'page' && !t.url.startsWith('devtools://'));
-        const currentPageRef = session.runtime?.currentPageRef;
-        const protectedExposure = currentPageRef
-            ? session.runtime?.protectedExposureByPage?.[currentPageRef]
+        const currentPageMismatch = resolveCurrentPageMismatch(session, page);
+        const effectivePageRef = currentPageMismatch?.livePageRef ?? session.runtime?.currentPageRef;
+        const protectedExposure = effectivePageRef
+            ? session.runtime?.protectedExposureByPage?.[effectivePageRef]
             : undefined;
         if (protectedExposure) {
             outputJSON(buildProtectedStatusPayload({
@@ -100,6 +184,7 @@ export async function status() {
                 pageUrl: page?.url,
                 pageTitle: page?.title,
                 captchaSolveCapable: supportsCaptchaSolve(session),
+                currentPageMismatch,
                 protectedExposure,
             }));
             return;
@@ -111,6 +196,7 @@ export async function status() {
             url: page?.url ?? 'unknown',
             title: page?.title ?? 'unknown',
             runtime: runtimeSummary,
+            ...(currentPageMismatch ? { currentPageMismatch } : {}),
         });
         return;
     }

package/dist/control-semantics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control-semantics.d.ts","sourceRoot":"","sources":["../src/control-semantics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;AAEzE,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAyCtF,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,oBAAoB,GAC1B,mBAAmB,GAAG,SAAS,CAuCjC;AAsCD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAYxE;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,oBAAoB,GAAG,mBAAmB,EAAE,CA6F/F;AAED,wBAAgB,0BAA0B,CACxC,MAAM,CAAC,EAAE,gBAAgB,EACzB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE;IACP,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC1B,GACL,uBAAuB,CAyBzB;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,EAC3B,cAAc,EAAE,aAAa,CAAC,mBAAmB,CAAC,GACjD,mBAAmB,GAAG,SAAS,CA0EjC;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,oBAAoB,EAC3B,cAAc,EAAE,aAAa,CAAC,mBAAmB,CAAC,GACjD,sBAAsB,GAAG,SAAS,CAiDpC"}
+{"version":3,"file":"control-semantics.d.ts","sourceRoot":"","sources":["../src/control-semantics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;AAEzE,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAyCtF,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,oBAAoB,GAC1B,mBAAmB,GAAG,SAAS,CAuCjC;AAsCD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAYxE;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,oBAAoB,GAAG,mBAAmB,EAAE,CAoG/F;AAED,wBAAgB,0BAA0B,CACxC,MAAM,CAAC,EAAE,gBAAgB,EACzB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE;IACP,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC1B,GACL,uBAAuB,CAyBzB;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,EAC3B,cAAc,EAAE,aAAa,CAAC,mBAAmB,CAAC,GACjD,mBAAmB,GAAG,SAAS,CA0EjC;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,oBAAoB,EAC3B,cAAc,EAAE,aAAa,CAAC,mBAAmB,CAAC,GACjD,sBAAsB,GAAG,SAAS,CAiDpC"}

package/dist/control-semantics.js

@@ -148,7 +148,12 @@ export function inferAllowedActionsFromFacts(facts) {
         actions.add('click');
         actions.add('press');
     }
-    if (kind === 'button' || kind === 'link' || role === 'button' || role === 'link') {
+    if (kind === 'button' ||
+        kind === 'link' ||
+        kind === 'tab' ||
+        role === 'button' ||
+        role === 'link' ||
+        role === 'tab') {
         actions.add('click');
         actions.add('press');
     }

package/dist/owned-process.d.ts

@@ -1,4 +1,14 @@
 export type OwnedPidTerminationResult = 'not_found' | 'terminated' | 'sigkilled' | 'still_alive';
+export type ManagedBrowserCleanupResult = {
+    terminated: number[];
+    blocked: number[];
+};
 export declare function isPidAlive(pid: number): boolean;
 export declare function terminateOwnedPid(pid: number): Promise<OwnedPidTerminationResult>;
+export declare function cleanupManagedBrowserPids(options?: {
+    excludePids?: Iterable<number>;
+}): Promise<ManagedBrowserCleanupResult>;
+export declare function listManagedBrowserPids(options?: {
+    processTable?: string;
+}): number[];
 //# sourceMappingURL=owned-process.d.ts.map

package/dist/owned-process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owned-process.d.ts","sourceRoot":"","sources":["../src/owned-process.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,yBAAyB,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,CAAC;AAEjG,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAW/C;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAsBvF"}
+{"version":3,"file":"owned-process.d.ts","sourceRoot":"","sources":["../src/owned-process.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,yBAAyB,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,CAAC;AACjG,MAAM,MAAM,2BAA2B,GAAG;IACxC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAW/C;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAsBvF;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;CAAO,GAC/C,OAAO,CAAC,2BAA2B,CAAC,CAqBtC;AAED,wBAAgB,sBAAsB,CACpC,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC;CAClB,GACL,MAAM,EAAE,CAuBV"}

package/dist/owned-process.js

@@ -1,7 +1,14 @@
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import path from 'node:path';
 const TERM_WAIT_ATTEMPTS = 10;
 const TERM_WAIT_MS = 100;
 const KILL_WAIT_ATTEMPTS = 5;
 const KILL_WAIT_MS = 20;
+const MANAGED_PROFILE_ROOTS = [
+    path.join(homedir(), '.agentpay', 'agentbrowse', 'profiles'),
+    path.join(homedir(), '.agentpay', 'solver', 'profiles'),
+];
 export function isPidAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -36,6 +43,45 @@ export async function terminateOwnedPid(pid) {
     }
     return 'still_alive';
 }
+export async function cleanupManagedBrowserPids(options = {}) {
+    const excludePids = new Set(options.excludePids ?? []);
+    const terminated = [];
+    const blocked = [];
+    for (const pid of listManagedBrowserPids()) {
+        if (excludePids.has(pid)) {
+            continue;
+        }
+        const result = await terminateOwnedPid(pid);
+        if (result === 'still_alive') {
+            blocked.push(pid);
+            continue;
+        }
+        if (result !== 'not_found') {
+            terminated.push(pid);
+        }
+    }
+    return { terminated, blocked };
+}
+export function listManagedBrowserPids(options = {}) {
+    const processTable = options.processTable ?? readProcessTable();
+    const pids = new Set();
+    for (const line of processTable.split(/\r?\n/)) {
+        const match = line.trimStart().match(/^(\d+)\s+(.*)$/);
+        if (!match) {
+            continue;
+        }
+        const pid = Number(match[1]);
+        const command = match[2] ?? '';
+        if (!Number.isFinite(pid) || pid <= 0 || pid === process.pid) {
+            continue;
+        }
+        if (!isManagedBrowserCommand(command)) {
+            continue;
+        }
+        pids.add(pid);
+    }
+    return Array.from(pids);
+}
 async function waitForPidExit(pid, attempts, intervalMs) {
     for (let attempt = 0; attempt < attempts; attempt++) {
         if (!isPidAlive(pid)) {
@@ -55,3 +101,31 @@ function getErrorCode(error) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function readProcessTable() {
+    try {
+        return execFileSync('ps', ['-Ao', 'pid=,command='], { encoding: 'utf-8' });
+    }
+    catch {
+        return '';
+    }
+}
+function isManagedBrowserCommand(command) {
+    if (!command.includes('--remote-debugging-address=127.0.0.1')) {
+        return false;
+    }
+    const userDataDir = readCommandFlag(command, '--user-data-dir');
+    if (!userDataDir) {
+        return false;
+    }
+    const normalizedUserDataDir = path.resolve(userDataDir);
+    return MANAGED_PROFILE_ROOTS.some((root) => isWithinRoot(normalizedUserDataDir, root));
+}
+function readCommandFlag(command, flag) {
+    const escapedFlag = flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = command.match(new RegExp(`${escapedFlag}=(?:"([^"]+)"|'([^']+)'|(\\S+))`));
+    return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+function isWithinRoot(candidatePath, rootPath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative.length > 0 && !relative.startsWith(`..${path.sep}`) && relative !== '..';
+}

package/dist/playwright-runtime.d.ts

@@ -9,6 +9,11 @@ type LaunchPageMetadata = {
     title: string;
     targetId?: string;
 };
+export type ResolvedCurrentPageContext = {
+    pageRef: string;
+    page: Page;
+    recoveredVia?: 'opener' | 'sole-live-page';
+};
 export declare function readLaunchPageMetadata(browser: Browser, options?: {
     requestedUrl?: string;
     fallbackUrl?: string;
@@ -26,6 +31,7 @@ export declare function syncLaunchPage(session: BrowseSession, browser: Browser,
     targetId?: string;
 }>;
 export declare function resolvePageByRef(browser: Browser, session: BrowseSession, pageRef: string): Promise<Page>;
+export declare function resolveCurrentPageContext(browser: Browser, session: BrowseSession): Promise<ResolvedCurrentPageContext>;
 export declare function syncSessionPage(session: BrowseSession, pageRef: string, page: Page, options?: {
     settleTimeoutMs?: number;
 }): Promise<{

package/dist/playwright-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-runtime.d.ts","sourceRoot":"","sources":["../src/playwright-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAO3D;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,EAAE,CAElD;AAmCD,KAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAkJF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,kBAAkB,CAAC,CA+C7B;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgC5D;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,EACV,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgB5D"}
+{"version":3,"file":"playwright-runtime.d.ts","sourceRoot":"","sources":["../src/playwright-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAO3D;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,EAAE,CAElD;AA8CD,KAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAQF,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,YAAY,CAAC,EAAE,QAAQ,GAAG,gBAAgB,CAAC;CAC5C,CAAC;AA4IF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,kBAAkB,CAAC,CA+C7B;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgC5D;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA8Cf;AA+CD,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,0BAA0B,CAAC,CAqCrC;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,EACV,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgB5D"}

package/dist/playwright-runtime.js

@@ -17,6 +17,10 @@ export function listPages(browser) {
 function buildPageResolutionError(kind, pageRef) {
     return new Error(`${kind === 'unknown' ? 'unknown_page_ref' : 'stale_page_ref'}:${pageRef}`);
 }
+function isPageResolutionError(error, kind, pageRef) {
+    return (error instanceof Error &&
+        error.message === `${kind === 'unknown' ? 'unknown_page_ref' : 'stale_page_ref'}:${pageRef}`);
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -250,6 +254,78 @@ export async function resolvePageByRef(browser, session, pageRef) {
     }
     throw buildPageResolutionError('stale', pageRef);
 }
+async function findRecoverableCurrentPageRef(browser, session, stalePageRef) {
+    const runtimePages = session.runtime?.pages ?? {};
+    const stalePageState = runtimePages[stalePageRef];
+    const openerPageRef = stalePageState?.openerPageRef;
+    if (openerPageRef && openerPageRef !== stalePageRef) {
+        try {
+            await resolvePageByRef(browser, session, openerPageRef);
+            return {
+                pageRef: openerPageRef,
+                recoveredVia: 'opener',
+            };
+        }
+        catch {
+            // Keep recovery fail-closed unless opener or a single live alternative is provably valid.
+        }
+    }
+    const liveCandidateRefs = [];
+    for (const candidatePageRef of Object.keys(runtimePages)) {
+        if (candidatePageRef === stalePageRef || candidatePageRef === openerPageRef) {
+            continue;
+        }
+        try {
+            await resolvePageByRef(browser, session, candidatePageRef);
+            liveCandidateRefs.push(candidatePageRef);
+        }
+        catch {
+            // Ignore stale or unknown candidates while looking for a single surviving live page.
+        }
+    }
+    if (liveCandidateRefs.length === 1) {
+        return {
+            pageRef: liveCandidateRefs[0],
+            recoveredVia: 'sole-live-page',
+        };
+    }
+    return null;
+}
+export async function resolveCurrentPageContext(browser, session) {
+    const currentPageRef = session.runtime?.currentPageRef ?? 'p0';
+    try {
+        const page = await resolvePageByRef(browser, session, currentPageRef);
+        return {
+            pageRef: currentPageRef,
+            page,
+        };
+    }
+    catch (error) {
+        if (isPageResolutionError(error, 'unknown', currentPageRef)) {
+            const pages = listPages(browser);
+            if (pages.length === 1) {
+                return {
+                    pageRef: currentPageRef,
+                    page: pages[0],
+                    recoveredVia: 'sole-live-page',
+                };
+            }
+            throw error;
+        }
+        if (!isPageResolutionError(error, 'stale', currentPageRef)) {
+            throw error;
+        }
+        const recovered = await findRecoverableCurrentPageRef(browser, session, currentPageRef);
+        if (!recovered) {
+            throw error;
+        }
+        return {
+            pageRef: recovered.pageRef,
+            page: await resolvePageByRef(browser, session, recovered.pageRef),
+            recoveredVia: recovered.recoveredVia,
+        };
+    }
+}
 export async function syncSessionPage(session, pageRef, page, options = {}) {
     ensureRuntimeState(session);
     const { url, title, targetId } = await readSettledSessionPageMetadata(session, pageRef, page, options);

package/dist/solver/browser-launcher.js

@@ -90,14 +90,9 @@ async function discoverCdpUrl(options) {
         }
         else {
             const activePort = readDevToolsActivePort(activePortPath);
-            if (activePort?.browserWSEndpoint) {
-                return activePort.browserWSEndpoint;
-            }
-            if (activePort?.port) {
-                const cdpUrl = await discoverCdpUrlOnPort(activePort.port);
-                if (cdpUrl) {
-                    return cdpUrl;
-                }
+            const discoveredViaActivePort = await discoverCdpUrlFromActivePort(activePort);
+            if (discoveredViaActivePort) {
+                return discoveredViaActivePort;
             }
         }
         await sleep(CDP_DISCOVERY_INTERVAL_MS);
@@ -117,6 +112,38 @@ async function discoverCdpUrlOnPort(port) {
         return null;
     }
 }
+async function discoverCdpUrlFromActivePort(activePort) {
+    if (!activePort) {
+        return null;
+    }
+    const candidatePorts = new Set();
+    if (activePort.browserWSEndpoint) {
+        const wsPort = portFromBrowserWSEndpoint(activePort.browserWSEndpoint);
+        if (wsPort) {
+            candidatePorts.add(wsPort);
+        }
+    }
+    if (activePort.port > 0) {
+        candidatePorts.add(activePort.port);
+    }
+    for (const port of candidatePorts) {
+        const cdpUrl = await discoverCdpUrlOnPort(port);
+        if (cdpUrl) {
+            return cdpUrl;
+        }
+    }
+    return null;
+}
+function portFromBrowserWSEndpoint(browserWSEndpoint) {
+    try {
+        const url = new URL(browserWSEndpoint);
+        const port = Number(url.port);
+        return Number.isFinite(port) && port > 0 ? port : null;
+    }
+    catch {
+        return null;
+    }
+}
 function readDevToolsActivePort(activePortPath) {
     if (!existsSync(activePortPath)) {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentbrowse",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "type": "module",
   "description": "Browser automation CLI for AI agents: control a CDP browser, observe UI surfaces, act on refs, extract data, capture screenshots, complete protected fills, and solve captchas",
   "keywords": [