@nuanu-ai/agentbrowse 0.2.46 → 0.2.48

package/dist/commands/act.js

@@ -2,21 +2,28 @@
  * browse act <targetRef> <action> [value] — Perform a deterministic action on a stored target.
  */
 import { saveSession } from '../session.js';
-import { bumpPageScopeEpoch, clearProtectedExposure, getProtectedExposure, getSurface, getTarget, incrementMetric, locatorCandidateKey, markTargetLifecycle, recordActionResult, registerPage, setTargetAvailability, setCurrentPage, updateTarget, } from '../runtime-state.js';
+import { getSurface, getTarget, markTargetLifecycle, setTargetAvailability, updateTarget, } from '../runtime-state.js';
+import { incrementMetric, recordActionResult } from '../runtime-metrics.js';
+import { bumpPageScopeEpoch, registerPage, setCurrentPage } from '../runtime-page-state.js';
+import { clearProtectedExposure, getProtectedExposure } from '../runtime-protected-state.js';
 import { outputContractFailure, outputFailure, outputJSON } from '../output.js';
-import { capturePageObservation, captureLocatorContextHash, captureLocatorState, createAcceptanceProbe, diagnoseNoObservableProgress, genericClickObservationChanged, locatorStateChanged, pageObservationChanged, rankLocatorCandidates, shouldVerifyObservableProgress, waitForAcceptanceProbe, } from './action-acceptance.js';
+import { capturePageObservation, captureLocatorContextHash, captureLocatorState, createAcceptanceProbe, diagnoseNoObservableProgress, genericClickObservationChanged, locatorStateChanged, pageObservationChanged, 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';
 import { BROWSE_ACTIONS, isBrowseAction } from './browse-actions.js';
 import { isCompatibleMutableFieldBinding, normalizePageSignature, readLocatorBindingSnapshot, readLocatorDomSignature, } from './descriptor-validation.js';
+import { assertStoredBindingStillValid, resolvePreparedLocatorCandidates, resolveInteractionRoots, targetUsesSurfaceAsPrimaryLocator, } from './interaction-kernel.js';
 import { isLocatorUserActionable } from './user-actionable.js';
 import { resolveSurfaceScopeRoot } from './target-resolution.js';
 import { buildProtectedArtifactsSuppressed } from '../secrets/protected-artifact-guard.js';
 import { connectPlaywright, disconnectPlaywright, listPages, resolvePageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { finishRunStep, saveArtifactManifest, startRunStep } from '../run-store.js';
+import { appendCommandLifecycleEventBestEffort, captureStepSnapshotBestEffort, } from '../run-observability.js';
+import { withApiTraceContext } from '../command-api-tracing.js';
+import { exportRunStepToOtlpHttpJsonBestEffort } from '../otel-exporter.js';
 function ensureValue(action, value) {
     if (action === 'click')
         return undefined;
@@ -25,7 +32,65 @@ function ensureValue(action, value) {
     throw new Error(`Act value is required for action: ${action}`);
 }
 const MUTABLE_FIELD_REBIND_RETRY_DELAYS_MS = [0, 25, 50, 100];
-function emitActPreflightFailure(params) {
+const PARTIAL_SELECTION_PROGRESS_MESSAGE = 'Text entered. Selection is not complete. Choose one option from the visible list.';
+async function readExpandedState(locator) {
+    if (!locator) {
+        return null;
+    }
+    const state = await captureLocatorState(locator, ['expanded']).catch(() => null);
+    return typeof state?.expanded === 'boolean' ? state.expanded : null;
+}
+async function partialProgressForAliasedSelection(args) {
+    const { requestedAction, probe } = args;
+    if ((requestedAction !== 'fill' && requestedAction !== 'type') || probe?.policy !== 'selection') {
+        return null;
+    }
+    const readExpanded = await readExpandedState(probe.readLocator);
+    if (readExpanded === true) {
+        return {
+            outcomeType: 'partial_progress',
+            message: PARTIAL_SELECTION_PROGRESS_MESSAGE,
+        };
+    }
+    const fallbackExpanded = probe.readLocator === probe.locator ? readExpanded : await readExpandedState(probe.locator);
+    if (fallbackExpanded === true) {
+        return {
+            outcomeType: 'partial_progress',
+            message: PARTIAL_SELECTION_PROGRESS_MESSAGE,
+        };
+    }
+    return null;
+}
+async function emitActPreflightFailure(params) {
+    finalizeActStepBestEffort(params.runId, params.stepId, {
+        success: false,
+        outcomeType: params.outcomeType,
+        message: params.message,
+        reason: params.reason,
+    });
+    const step = params.runId && params.stepId
+        ? {
+            runId: params.runId,
+            stepId: params.stepId,
+            command: 'act',
+        }
+        : null;
+    captureStepSnapshotBestEffort({
+        session: params.session,
+        step,
+        phase: 'point-in-time',
+        pageRef: params.session.runtime?.currentPageRef,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step,
+        phase: 'failed',
+        attributes: {
+            outcomeType: params.outcomeType,
+            targetRef: params.targetRef,
+            reason: params.reason,
+        },
+    });
+    await exportRunStepToOtlpHttpJsonBestEffort(params.runId, params.stepId);
     return outputContractFailure({
         error: params.error,
         outcomeType: params.outcomeType,
@@ -120,6 +185,81 @@ function redactNoObservableProgressDiagnosis(diagnosis) {
             : {}),
     };
 }
+function buildActArtifactManifest(params) {
+    if ('suppressed' in params.artifacts) {
+        return {
+            artifactManifestId: `${params.stepId}-artifacts`,
+            stepId: params.stepId,
+            screenshots: [],
+            htmlSnapshots: [],
+            traces: [],
+            logs: [],
+            suppressed: [
+                { kind: 'screenshot', reason: 'protected_exposure_active' },
+                { kind: 'html', reason: 'protected_exposure_active' },
+                { kind: 'trace', reason: 'protected_exposure_active' },
+                { kind: 'log', reason: 'protected_exposure_active' },
+            ],
+        };
+    }
+    return {
+        artifactManifestId: `${params.stepId}-artifacts`,
+        stepId: params.stepId,
+        screenshots: params.artifacts.screenshotPath
+            ? [{ path: params.artifacts.screenshotPath, purpose: 'failure_screenshot' }]
+            : [],
+        htmlSnapshots: params.artifacts.htmlPath
+            ? [{ path: params.artifacts.htmlPath, purpose: 'failure_html_snapshot' }]
+            : [],
+        traces: params.artifacts.tracePath
+            ? [{ path: params.artifacts.tracePath, purpose: 'failure_trace' }]
+            : [],
+        logs: [{ path: params.artifacts.actionLogPath, purpose: 'failure_action_log' }],
+        suppressed: [],
+    };
+}
+function persistActArtifactManifestBestEffort(runId, stepId, artifacts) {
+    if (!runId || !stepId || !artifacts) {
+        return undefined;
+    }
+    try {
+        const manifest = buildActArtifactManifest({
+            stepId,
+            artifacts,
+        });
+        saveArtifactManifest(runId, manifest);
+        return manifest.artifactManifestId;
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildActSnapshotArtifactRefs(artifacts) {
+    if (!artifacts || 'suppressed' in artifacts) {
+        return undefined;
+    }
+    return {
+        ...(artifacts.screenshotPath ? { screenshotPath: artifacts.screenshotPath } : {}),
+        ...(artifacts.htmlPath ? { htmlPath: artifacts.htmlPath } : {}),
+        ...(artifacts.tracePath ? { tracePath: artifacts.tracePath } : {}),
+        ...(artifacts.actionLogPath ? { logPath: artifacts.actionLogPath } : {}),
+    };
+}
+function finalizeActStepBestEffort(runId, stepId, options) {
+    if (!runId || !stepId) {
+        return;
+    }
+    try {
+        finishRunStep({
+            runId,
+            stepId,
+            ...options,
+        });
+    }
+    catch {
+        // Best effort only.
+    }
+}
 function isEditableLikeTarget(target) {
     if (target.controlFamily === 'text-input' ||
         target.controlFamily === 'select' ||
@@ -148,136 +288,6 @@ function shouldDeferSurfaceResolutionForEditablePress(target, action) {
         isEditableLikeTarget(target) &&
         !target.locatorCandidates.some((candidate) => candidate.scope === 'surface'));
 }
-function targetUsesSurfaceAsPrimaryLocator(target, surface) {
-    const surfaceCandidates = new Set(surface.locatorCandidates.map(locatorCandidateKey));
-    return target.locatorCandidates.some((candidate) => surfaceCandidates.has(locatorCandidateKey(candidate)));
-}
-async function resolveActionRoot(page, target, attempts, surface) {
-    const baseRoot = resolveLocatorRoot(page, target.framePath ?? surface?.framePath);
-    if (!surface) {
-        return {
-            baseRoot,
-            locatorRoot: baseRoot,
-            surfaceRoot: null,
-        };
-    }
-    const surfaceRoot = await resolveSurfaceScopeRoot(page, surface, attempts);
-    if (surfaceRoot) {
-        if (targetUsesSurfaceAsPrimaryLocator(target, surface)) {
-            attempts.push('surface.resolve.self-target');
-            return {
-                baseRoot,
-                locatorRoot: baseRoot,
-                surfaceRoot,
-            };
-        }
-        return {
-            baseRoot,
-            locatorRoot: surfaceRoot,
-            surfaceRoot,
-        };
-    }
-    attempts.push('surface.resolve.fallback:page');
-    return {
-        baseRoot,
-        locatorRoot: baseRoot,
-        surfaceRoot: null,
-    };
-}
-function resolveLocatorRootForCandidate(baseRoot, defaultRoot, surfaceRoot, candidate) {
-    if (candidate.scope === 'root') {
-        return baseRoot;
-    }
-    if (candidate.scope === 'surface') {
-        return surfaceRoot;
-    }
-    return defaultRoot;
-}
-async function prepareLocatorForAction(locator, action, strategy, attempts, options) {
-    const count = await locator.count().catch(() => 0);
-    if (count === 0) {
-        attempts.push(`resolve.skip:${strategy}:empty`);
-        return { locator: null };
-    }
-    if (action !== 'click' && count > 1) {
-        attempts.push(`resolve.skip:${strategy}:ambiguous:${count}`);
-        return { locator: null };
-    }
-    let resolvedLocator = locator.first();
-    if (action === 'click' && count > 1) {
-        const visibleCandidates = [];
-        for (let index = 0; index < count; index += 1) {
-            const candidate = locator.nth(index);
-            const visible = await isLocatorUserActionable(candidate);
-            if (!visible) {
-                continue;
-            }
-            visibleCandidates.push(candidate);
-        }
-        if (visibleCandidates.length === 1) {
-            attempts.push(`resolve.visible-unique:${strategy}`);
-            resolvedLocator = visibleCandidates[0] ?? locator.first();
-        }
-        else if (visibleCandidates.length > 1) {
-            attempts.push(`resolve.skip:${strategy}:ambiguous-visible:${visibleCandidates.length}`);
-            return { locator: null };
-        }
-        else {
-            attempts.push(`resolve.skip:${strategy}:hidden`);
-            return { locator: null };
-        }
-    }
-    const visible = await isLocatorUserActionable(resolvedLocator);
-    if (!visible) {
-        attempts.push(`resolve.skip:${strategy}:hidden`);
-        return { locator: null };
-    }
-    const disabled = await resolvedLocator.isDisabled?.().catch(() => false);
-    if (disabled) {
-        attempts.push(`resolve.skip:${strategy}:disabled`);
-        return { locator: null, blockedReason: 'disabled' };
-    }
-    if (action === 'fill' || action === 'type' || options?.allowDescendantPressFallback) {
-        const editable = await resolvedLocator.isEditable().catch(() => false);
-        if (!editable) {
-            const descendantSelector = options?.allowDescendantPressFallback
-                ? 'input:not([type="hidden"]), textarea, select, [contenteditable="true"], [role="textbox"], [role="combobox"]'
-                : 'input:not([type="hidden"]), textarea, select, [contenteditable="true"]';
-            const descendantCandidates = resolvedLocator.locator(descendantSelector);
-            const descendantCount = await descendantCandidates.count().catch(() => 0);
-            const candidateDescendants = [];
-            for (let index = 0; index < descendantCount; index += 1) {
-                const descendant = descendantCandidates.nth(index);
-                const descendantVisible = await isLocatorUserActionable(descendant);
-                if (!descendantVisible)
-                    continue;
-                if (!options?.allowDescendantPressFallback || action === 'fill' || action === 'type') {
-                    const descendantEditable = await descendant.isEditable().catch(() => false);
-                    if (!descendantEditable)
-                        continue;
-                }
-                candidateDescendants.push(descendant);
-            }
-            if (candidateDescendants.length === 1) {
-                attempts.push(options?.allowDescendantPressFallback && action === 'press'
-                    ? `resolve.descendant-press:${strategy}`
-                    : `resolve.descendant-editable:${strategy}`);
-                return { locator: candidateDescendants[0] ?? null };
-            }
-            if (candidateDescendants.length > 1) {
-                attempts.push(`resolve.skip:${strategy}:descendant-ambiguous:${candidateDescendants.length}`);
-                return { locator: null };
-            }
-            if (options?.allowReadonlyFallback) {
-                attempts.push(`resolve.readonly-fallback:${strategy}`);
-                return { locator: resolvedLocator };
-            }
-            attempts.push(`resolve.skip:${strategy}:readonly`);
-            return { locator: null, blockedReason: 'readonly' };
-        }
-    }
-    return { locator: resolvedLocator };
-}
 async function recoverLocatorFromSurfaceRoot(locatorRoot, target, action, attempts) {
     if (action !== 'press' ||
         !(target.controlFamily === 'text-input' ||
@@ -340,599 +350,741 @@ async function waitForLatePage(browser, beforePages, timeoutMs = 2_000) {
     return null;
 }
 export async function act(session, targetRef, action, value) {
-    const target = getTarget(session, targetRef);
-    if (!target) {
-        return emitActPreflightFailure({
-            error: 'unknown_target_ref',
-            outcomeType: 'blocked',
-            message: 'The requested targetRef is unknown.',
-            reason: `No stored target matches targetRef ${targetRef}.`,
-            targetRef,
-            action,
-        });
-    }
-    if (target.lifecycle !== 'live') {
-        return emitActPreflightFailure({
-            error: 'stale_target_ref',
-            outcomeType: 'binding_stale',
-            message: 'The requested target is no longer live.',
-            reason: `Target ${targetRef} is ${target.lifecycle}${target.lifecycleReason ? ` because ${target.lifecycleReason}` : ''}.`,
-            targetRef,
-            action,
-        });
-    }
-    if (target.capability !== 'actionable') {
-        return emitActPreflightFailure({
-            error: 'target_not_actionable',
-            outcomeType: 'unsupported',
-            message: 'The requested target cannot be used for actions.',
-            reason: `Target ${targetRef} has capability ${target.capability}, not actionable.`,
-            targetRef,
-            action,
-        });
-    }
-    if (!target.allowedActions.includes(action)) {
-        return emitActPreflightFailure({
-            error: 'action_not_allowed_for_target',
-            outcomeType: 'unsupported',
-            message: 'The requested action is not allowed for this target.',
-            reason: `Target ${targetRef} allows ${target.allowedActions.join(', ')}, not ${action}.`,
-            targetRef,
-            action,
-        });
-    }
-    if (target.availability.state === 'gated' &&
-        (target.availability.reason === 'occupied' || target.availability.reason === 'not-selectable')) {
-        return emitActPreflightFailure({
-            error: 'target_gated',
-            outcomeType: 'blocked',
-            message: 'The requested target is currently gated.',
-            reason: `Target ${targetRef} is gated${target.availability.reason ? ` because ${target.availability.reason}` : ''}.`,
-            targetRef,
-            action,
-        });
-    }
-    const surface = target.surfaceRef ? getSurface(session, target.surfaceRef) : null;
-    if (surface && surface.lifecycle !== 'live') {
-        setTargetAvailability(session, targetRef, 'surface-inactive', surface.lifecycleReason ?? `surface-${surface.lifecycle}`);
-        saveSession(session);
-        return emitActPreflightFailure({
-            error: 'target_surface_not_live',
-            outcomeType: 'blocked',
-            message: 'The requested target surface is no longer live.',
-            reason: `Surface ${surface.ref} is ${surface.lifecycle}${surface.lifecycleReason ? ` because ${surface.lifecycleReason}` : ''}.`,
-            targetRef,
-            action,
-        });
-    }
-    if (surface && surface.availability.state !== 'available') {
-        setTargetAvailability(session, targetRef, 'surface-inactive', surface.availability.reason ?? `surface-${surface.availability.state}`);
-        saveSession(session);
-        return emitActPreflightFailure({
-            error: 'target_surface_unavailable',
-            outcomeType: 'blocked',
-            message: 'The requested target surface is not currently available.',
-            reason: `Surface ${surface.ref} is ${surface.availability.state}${surface.availability.reason ? ` because ${surface.availability.reason}` : ''}.`,
-            targetRef,
-            action,
-        });
-    }
-    const actionValue = ensureValue(action, value);
-    const attempts = [];
-    const startedAt = Date.now();
-    let browser = null;
-    let failureMessage = null;
-    let failureArtifacts;
-    let currentPage = null;
-    let currentPageRef = target.pageRef;
-    const startingPageUrl = session.runtime?.pages?.[target.pageRef]?.url ?? null;
-    const protectedExposureAtStart = getProtectedExposure(session, target.pageRef);
-    let locatorStrategy = null;
-    let recoveredAfterError = false;
-    let recoveredAcceptancePolicy = null;
-    let staleReason = null;
-    let progressProbe = null;
-    let noProgressDiagnosis = null;
-    let liveTarget = target;
-    let trace = {
-        finishSuccess: async () => { },
-        finishFailure: async (_artifactDir) => undefined,
-    };
-    try {
-        browser = await connectPlaywright(session.cdpUrl);
-    }
-    catch (err) {
-        return emitActPreflightFailure({
-            error: 'browser_connection_failed',
-            outcomeType: 'blocked',
-            message: 'The action could not start because AgentBrowse failed to connect to the browser.',
-            reason: err instanceof Error ? err.message : String(err),
+    const requestedAction = action;
+    const runId = session.activeRunId;
+    const actStep = runId
+        ? startRunStep({
+            runId,
+            command: 'act',
+            input: {
+                targetRef,
+                action: requestedAction,
+                valueSupplied: typeof value === 'string' && value.length > 0,
+            },
+            refs: {
+                targetRef,
+            },
+        })
+        : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step: actStep,
+        phase: 'before',
+        pageRef: session.runtime?.currentPageRef,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step: actStep,
+        phase: 'started',
+        attributes: {
             targetRef,
-            action,
-        });
-    }
-    try {
-        const page = await resolvePageByRef(browser, session, target.pageRef);
-        currentPage = page;
-        setCurrentPage(session, target.pageRef);
-        const { url } = await syncSessionPage(session, target.pageRef, page);
-        trace = await startActionTrace(page, {
-            suppressSensitiveArtifacts: Boolean(protectedExposureAtStart),
-        });
-        if (liveTarget.pageSignature && normalizePageSignature(url) !== liveTarget.pageSignature) {
-            staleReason = 'page-signature-mismatch';
-            throw new Error('stale_target_page_signature_changed');
+            action: requestedAction,
+            valueSupplied: typeof value === 'string' && value.length > 0,
+        },
+    });
+    return withApiTraceContext({
+        runId,
+        stepId: actStep?.stepId,
+        command: 'act',
+    }, async () => {
+        const target = getTarget(session, targetRef);
+        if (!target) {
+            return emitActPreflightFailure({
+                session,
+                error: 'unknown_target_ref',
+                outcomeType: 'blocked',
+                message: 'The requested targetRef is unknown.',
+                reason: `No stored target matches targetRef ${targetRef}.`,
+                targetRef,
+                action,
+                runId,
+                stepId: actStep?.stepId,
+            });
         }
-        const tryRebindMutableFieldTarget = async (resolvedLocator, strategy) => {
-            if (!liveTarget.domSignature) {
-                return false;
+        if (target.lifecycle !== 'live') {
+            return emitActPreflightFailure({
+                session,
+                error: 'stale_target_ref',
+                outcomeType: 'binding_stale',
+                message: 'The requested target is no longer live.',
+                reason: `Target ${targetRef} is ${target.lifecycle}${target.lifecycleReason ? ` because ${target.lifecycleReason}` : ''}.`,
+                targetRef,
+                action,
+                runId,
+                stepId: actStep?.stepId,
+            });
+        }
+        if (target.capability !== 'actionable') {
+            return emitActPreflightFailure({
+                session,
+                error: 'target_not_actionable',
+                outcomeType: 'unsupported',
+                message: 'The requested target cannot be used for actions.',
+                reason: `Target ${targetRef} has capability ${target.capability}, not actionable.`,
+                targetRef,
+                action: requestedAction,
+                runId,
+                stepId: actStep?.stepId,
+            });
+        }
+        if (!target.allowedActions.includes(action)) {
+            const canAliasFillLikeToSelect = (requestedAction === 'fill' || requestedAction === 'type') &&
+                target.controlFamily === 'select' &&
+                target.allowedActions.includes('select') &&
+                typeof value === 'string' &&
+                value.length > 0;
+            if (canAliasFillLikeToSelect) {
+                action = 'select';
             }
-            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,
-                    },
+            else {
+                return emitActPreflightFailure({
+                    session,
+                    error: 'action_not_allowed_for_target',
+                    outcomeType: 'unsupported',
+                    message: 'The requested action is not allowed for this target.',
+                    reason: `Target ${targetRef} allows ${target.allowedActions.join(', ')}, not ${requestedAction}.`,
+                    targetRef,
+                    action: requestedAction,
                 });
-                if (updatedTarget) {
-                    liveTarget = updatedTarget;
-                }
-                return true;
             }
-            return false;
+        }
+        if (target.availability.state === 'gated' &&
+            (target.availability.reason === 'occupied' || target.availability.reason === 'not-selectable')) {
+            return emitActPreflightFailure({
+                session,
+                error: 'target_gated',
+                outcomeType: 'blocked',
+                message: 'The requested target is currently gated.',
+                reason: `Target ${targetRef} is gated${target.availability.reason ? ` because ${target.availability.reason}` : ''}.`,
+                targetRef,
+                action: requestedAction,
+            });
+        }
+        const surface = target.surfaceRef ? getSurface(session, target.surfaceRef) : null;
+        if (surface && surface.lifecycle !== 'live') {
+            setTargetAvailability(session, targetRef, 'surface-inactive', surface.lifecycleReason ?? `surface-${surface.lifecycle}`);
+            saveSession(session);
+            return emitActPreflightFailure({
+                session,
+                error: 'target_surface_not_live',
+                outcomeType: 'blocked',
+                message: 'The requested target surface is no longer live.',
+                reason: `Surface ${surface.ref} is ${surface.lifecycle}${surface.lifecycleReason ? ` because ${surface.lifecycleReason}` : ''}.`,
+                targetRef,
+                action: requestedAction,
+            });
+        }
+        if (surface && surface.availability.state !== 'available') {
+            setTargetAvailability(session, targetRef, 'surface-inactive', surface.availability.reason ?? `surface-${surface.availability.state}`);
+            saveSession(session);
+            return emitActPreflightFailure({
+                session,
+                error: 'target_surface_unavailable',
+                outcomeType: 'blocked',
+                message: 'The requested target surface is not currently available.',
+                reason: `Surface ${surface.ref} is ${surface.availability.state}${surface.availability.reason ? ` because ${surface.availability.reason}` : ''}.`,
+                targetRef,
+                action: requestedAction,
+            });
+        }
+        const actionValue = ensureValue(action, value);
+        const attempts = [];
+        if (action !== requestedAction) {
+            attempts.push(`action.alias:${requestedAction}->${action}`);
+        }
+        const startedAt = Date.now();
+        let browser = null;
+        let failureMessage = null;
+        let failureArtifacts;
+        let currentPage = null;
+        let currentPageRef = target.pageRef;
+        const startingPageUrl = session.runtime?.pages?.[target.pageRef]?.url ?? null;
+        const protectedExposureAtStart = getProtectedExposure(session, target.pageRef);
+        let locatorStrategy = null;
+        let recoveredAfterError = false;
+        let recoveredAcceptancePolicy = null;
+        let recoveredProgressProbe = null;
+        let staleReason = null;
+        let progressProbe = null;
+        let noProgressDiagnosis = null;
+        let partialProgressResult = null;
+        let liveTarget = target;
+        let trace = {
+            finishSuccess: async () => { },
+            finishFailure: async (_artifactDir) => undefined,
         };
-        const assertResolvedTargetStillValid = async (resolvedLocator, stage) => {
-            if (liveTarget.pageSignature &&
-                normalizePageSignature(page.url()) !== liveTarget.pageSignature) {
-                attempts.push(`stale.page-signature:${stage}`);
+        try {
+            browser = await connectPlaywright(session.cdpUrl);
+        }
+        catch (err) {
+            return emitActPreflightFailure({
+                session,
+                error: 'browser_connection_failed',
+                outcomeType: 'blocked',
+                message: 'The action could not start because AgentBrowse failed to connect to the browser.',
+                reason: err instanceof Error ? err.message : String(err),
+                targetRef,
+                action,
+            });
+        }
+        try {
+            const page = await resolvePageByRef(browser, session, target.pageRef);
+            currentPage = page;
+            setCurrentPage(session, target.pageRef);
+            const { url } = await syncSessionPage(session, target.pageRef, page);
+            trace = await startActionTrace(page, {
+                suppressSensitiveArtifacts: Boolean(protectedExposureAtStart),
+            });
+            if (liveTarget.pageSignature && normalizePageSignature(url) !== liveTarget.pageSignature) {
                 staleReason = 'page-signature-mismatch';
                 throw new Error('stale_target_page_signature_changed');
             }
-            const liveCount = await resolvedLocator.count().catch(() => 0);
-            if (liveCount === 0) {
-                attempts.push(`stale.locator:${stage}`);
-                staleReason = 'locator-resolution-failed';
-                throw new Error('stale_target_locator_resolution_failed');
-            }
-            if (liveTarget.domSignature) {
-                const rebound = await tryRebindMutableFieldTarget(resolvedLocator, stage);
-                if (!rebound) {
-                    const liveSignature = await readLocatorDomSignature(resolvedLocator).catch(() => null);
-                    if (liveSignature && liveSignature !== liveTarget.domSignature) {
-                        attempts.push(`stale.dom-signature:${stage}`);
-                        staleReason = 'dom-signature-mismatch';
-                        throw new Error('stale_target_dom_signature_changed');
-                    }
-                }
-            }
-        };
-        let resolvedBy = null;
-        const beforePages = listPages(browser);
-        const shouldCheckProgress = shouldVerifyObservableProgress(target, action);
-        const beforePageObservation = shouldCheckProgress ? await capturePageObservation(page) : null;
-        const deferSurfaceResolution = shouldDeferSurfaceResolutionForEditablePress(target, action);
-        let baseRoot = resolveLocatorRoot(page, target.framePath ?? surface?.framePath);
-        let locatorRoot = baseRoot;
-        let surfaceRoot = null;
-        if (!deferSurfaceResolution) {
-            ({ baseRoot, locatorRoot, surfaceRoot } = await resolveActionRoot(page, target, attempts, surface));
-        }
-        let lastError = null;
-        let sawDomSignatureMismatch = false;
-        let sawDisabledTarget = false;
-        let sawReadonlyTarget = false;
-        const attemptResolvedLocator = async (resolvedLocator, strategy, options) => {
-            if (!options?.skipDomSignature && liveTarget.domSignature) {
-                const rebound = await tryRebindMutableFieldTarget(resolvedLocator, strategy);
-                if (!rebound) {
-                    const liveSignature = await readLocatorDomSignature(resolvedLocator);
-                    if (liveSignature && liveSignature !== liveTarget.domSignature) {
-                        attempts.push(`domSignature.mismatch:${strategy}`);
-                        sawDomSignatureMismatch = true;
-                        return false;
-                    }
-                }
-            }
-            let acceptanceProbe = null;
-            const tryRecoverActionErrorAcceptance = async () => {
-                if (!acceptanceProbe) {
-                    return false;
-                }
-                const acceptance = await waitForAcceptanceProbe(acceptanceProbe).catch(() => null);
-                if (acceptance?.polls && acceptance.polls > 1) {
-                    attempts.push(`acceptance.polled:${acceptance.polls}`);
-                }
-                if (!acceptance?.accepted) {
+            const tryRebindMutableFieldTarget = async (resolvedLocator, strategy) => {
+                if (!liveTarget.domSignature) {
                     return false;
                 }
-                if (acceptanceProbe.policy === 'submit') {
-                    const submitResolution = await resolveSubmitResult(acceptanceProbe, acceptance.afterPageObservation);
-                    if (!submitResolution.acceptAsProgress) {
+                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;
                     }
-                    attempts.push(`submit-resolution:${submitResolution.finalVerdict}`);
-                    if (submitResolution.claims.some((claim) => claim.kind === 'soft_result_candidate')) {
-                        attempts.push('submit-resolution:soft-result-candidate');
+                    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;
                 }
-                attempts.push(`acceptance.recovered:${acceptanceProbe.policy}`);
-                incrementMetric(session, 'fallbackActions');
-                resolvedBy = 'playwright-locator';
-                locatorStrategy = strategy;
-                progressProbe = null;
-                lastError = null;
-                recoveredAfterError = true;
-                recoveredAcceptancePolicy = acceptanceProbe.policy;
-                setTargetAvailability(session, targetRef, 'available');
-                return true;
+                return false;
             };
-            try {
-                const valueProjection = await projectActionValue({
-                    target,
-                    action,
-                    actionValue,
-                    locator: resolvedLocator,
-                    attempts,
-                });
-                const executionValue = valueProjection?.executionValue ?? actionValue;
-                const acceptanceValue = valueProjection?.acceptanceValue ?? actionValue;
-                acceptanceProbe = await createAcceptanceProbe({
-                    session,
-                    page,
-                    target,
-                    action,
-                    actionValue: acceptanceValue,
-                    locator: resolvedLocator,
-                    beforePageObservation,
-                });
-                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);
-                        },
+            const assertResolvedTargetStillValid = async (resolvedLocator, stage) => {
+                await assertStoredBindingStillValid(page, resolvedLocator, liveTarget, stage, {
+                    onReason: async (reason, staleStage) => {
+                        switch (reason) {
+                            case 'page_signature_mismatch':
+                                attempts.push(`stale.page-signature:${staleStage}`);
+                                staleReason = 'page-signature-mismatch';
+                                return false;
+                            case 'locator_resolution_failed':
+                                attempts.push(`stale.locator:${staleStage}`);
+                                staleReason = 'locator-resolution-failed';
+                                return false;
+                            case 'dom_signature_mismatch': {
+                                const rebound = await tryRebindMutableFieldTarget(resolvedLocator, staleStage);
+                                if (rebound) {
+                                    return true;
+                                }
+                                attempts.push(`stale.dom-signature:${staleStage}`);
+                                staleReason = 'dom-signature-mismatch';
+                                return false;
+                            }
+                        }
+                    },
+                    errorForReason: (reason) => {
+                        switch (reason) {
+                            case 'page_signature_mismatch':
+                                return 'stale_target_page_signature_changed';
+                            case 'locator_resolution_failed':
+                                return 'stale_target_locator_resolution_failed';
+                            case 'dom_signature_mismatch':
+                                return 'stale_target_dom_signature_changed';
+                        }
                     },
                 });
-                if (usedFallback) {
-                    incrementMetric(session, 'fallbackActions');
-                }
-                resolvedBy = 'playwright-locator';
-                locatorStrategy = strategy;
-                progressProbe = acceptanceProbe;
-                setTargetAvailability(session, targetRef, 'available');
-                return true;
+            };
+            let resolvedBy = null;
+            const beforePages = listPages(browser);
+            const shouldCheckProgress = shouldVerifyObservableProgress(target, action);
+            const beforePageObservation = shouldCheckProgress ? await capturePageObservation(page) : null;
+            const deferSurfaceResolution = shouldDeferSurfaceResolutionForEditablePress(target, action);
+            let baseRoot = page;
+            let locatorRoot = baseRoot;
+            let surfaceRoot = null;
+            if (!deferSurfaceResolution) {
+                ({ baseRoot, locatorRoot, surfaceRoot } = await resolveInteractionRoots(page, target, surface, attempts, {
+                    recordSelfTargetReuse: true,
+                }));
             }
-            catch (err) {
-                lastError = err instanceof Error ? err : new Error(String(err));
-                const shouldAttemptAcceptanceRecovery = acceptanceProbe !== null &&
-                    (acceptanceProbe.policy === 'value-change' ||
-                        acceptanceProbe.policy === 'selection' ||
-                        acceptanceProbe.policy === 'date-selection' ||
-                        acceptanceProbe.policy === 'navigation' ||
-                        acceptanceProbe.policy === 'submit');
-                if (shouldAttemptAcceptanceRecovery && (await tryRecoverActionErrorAcceptance())) {
-                    return true;
-                }
-                if (staleReason) {
-                    throw lastError;
+            let lastError = null;
+            let sawDomSignatureMismatch = false;
+            let sawDisabledTarget = false;
+            let sawReadonlyTarget = false;
+            const attemptResolvedLocator = async (resolvedLocator, strategy, options) => {
+                if (!options?.skipDomSignature && liveTarget.domSignature) {
+                    const rebound = await tryRebindMutableFieldTarget(resolvedLocator, strategy);
+                    if (!rebound) {
+                        const liveSignature = await readLocatorDomSignature(resolvedLocator);
+                        if (liveSignature && liveSignature !== liveTarget.domSignature) {
+                            attempts.push(`domSignature.mismatch:${strategy}`);
+                            sawDomSignatureMismatch = true;
+                            return false;
+                        }
+                    }
                 }
+                let acceptanceProbe = null;
+                const tryRecoverActionErrorAcceptance = async () => {
+                    if (!acceptanceProbe) {
+                        return false;
+                    }
+                    const acceptance = await waitForAcceptanceProbe(acceptanceProbe).catch(() => null);
+                    if (acceptance?.polls && acceptance.polls > 1) {
+                        attempts.push(`acceptance.polled:${acceptance.polls}`);
+                    }
+                    if (!acceptance?.accepted) {
+                        return false;
+                    }
+                    if (acceptanceProbe.policy === 'submit') {
+                        const submitResolution = await resolveSubmitResult(acceptanceProbe, acceptance.afterPageObservation);
+                        if (!submitResolution.acceptAsProgress) {
+                            return false;
+                        }
+                        attempts.push(`submit-resolution:${submitResolution.finalVerdict}`);
+                        if (submitResolution.claims.some((claim) => claim.kind === 'soft_result_candidate')) {
+                            attempts.push('submit-resolution:soft-result-candidate');
+                        }
+                    }
+                    attempts.push(`acceptance.recovered:${acceptanceProbe.policy}`);
+                    incrementMetric(session, 'fallbackActions');
+                    resolvedBy = 'playwright-locator';
+                    locatorStrategy = strategy;
+                    recoveredProgressProbe = acceptanceProbe;
+                    progressProbe = null;
+                    lastError = null;
+                    recoveredAfterError = true;
+                    recoveredAcceptancePolicy = acceptanceProbe.policy;
+                    setTargetAvailability(session, targetRef, 'available');
+                    return true;
+                };
                 try {
-                    await assertResolvedTargetStillValid(resolvedLocator, `after-error:${strategy}`);
+                    const valueProjection = await projectActionValue({
+                        target,
+                        action,
+                        actionValue,
+                        locator: resolvedLocator,
+                        attempts,
+                    });
+                    const executionValue = valueProjection?.executionValue ?? actionValue;
+                    const acceptanceValue = valueProjection?.acceptanceValue ?? actionValue;
+                    acceptanceProbe = await createAcceptanceProbe({
+                        session,
+                        page,
+                        target,
+                        action,
+                        actionValue: acceptanceValue,
+                        locator: resolvedLocator,
+                        beforePageObservation,
+                    });
+                    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);
+                            },
+                        },
+                    });
+                    if (usedFallback) {
+                        incrementMetric(session, 'fallbackActions');
+                    }
+                    resolvedBy = 'playwright-locator';
+                    locatorStrategy = strategy;
+                    progressProbe = acceptanceProbe;
+                    setTargetAvailability(session, targetRef, 'available');
+                    return true;
                 }
-                catch (validationError) {
-                    if ((acceptanceProbe?.policy === 'navigation' || acceptanceProbe?.policy === 'submit') &&
-                        validationError instanceof Error &&
-                        validationError.message === 'stale_target_page_signature_changed' &&
-                        (await tryRecoverActionErrorAcceptance())) {
+                catch (err) {
+                    lastError = err instanceof Error ? err : new Error(String(err));
+                    const shouldAttemptAcceptanceRecovery = acceptanceProbe !== null &&
+                        (acceptanceProbe.policy === 'value-change' ||
+                            acceptanceProbe.policy === 'selection' ||
+                            acceptanceProbe.policy === 'date-selection' ||
+                            acceptanceProbe.policy === 'navigation' ||
+                            acceptanceProbe.policy === 'submit');
+                    if (shouldAttemptAcceptanceRecovery && (await tryRecoverActionErrorAcceptance())) {
                         return true;
                     }
-                    throw validationError;
-                }
-                return false;
-            }
-        };
-        const watchForNewPage = shouldWatchForNewPageAfterAction(target, action);
-        const popupPromise = watchForNewPage
-            ? waitForPopup(page.context())
-            : Promise.resolve(null);
-        const tryRankedCandidates = async () => {
-            for (const candidate of rankLocatorCandidates(target.locatorCandidates, action)) {
-                const candidateRoot = resolveLocatorRootForCandidate(baseRoot, locatorRoot, surfaceRoot, candidate);
-                if (!candidateRoot) {
-                    attempts.push(`resolve.skip:${candidate.strategy}:surface-unavailable`);
-                    continue;
+                    if (staleReason) {
+                        throw lastError;
+                    }
+                    try {
+                        await assertResolvedTargetStillValid(resolvedLocator, `after-error:${strategy}`);
+                    }
+                    catch (validationError) {
+                        if ((acceptanceProbe?.policy === 'navigation' || acceptanceProbe?.policy === 'submit') &&
+                            validationError instanceof Error &&
+                            validationError.message === 'stale_target_page_signature_changed' &&
+                            (await tryRecoverActionErrorAcceptance())) {
+                            return true;
+                        }
+                        throw validationError;
+                    }
+                    return false;
                 }
-                const locator = buildLocator(candidateRoot, candidate);
-                if (!locator)
-                    continue;
-                const preparedLocator = await prepareLocatorForAction(locator, action, candidate.strategy, attempts, {
-                    allowReadonlyFallback: action === 'fill' && target.controlFamily === 'datepicker',
-                    allowDescendantPressFallback: action === 'press' &&
-                        (target.controlFamily === 'text-input' ||
-                            target.controlFamily === 'select' ||
-                            target.controlFamily === 'datepicker'),
+            };
+            const watchForNewPage = shouldWatchForNewPageAfterAction(target, action);
+            const popupPromise = watchForNewPage
+                ? waitForPopup(page.context())
+                : Promise.resolve(null);
+            const tryRankedCandidates = async () => {
+                const resolution = await resolvePreparedLocatorCandidates({
+                    target,
+                    action,
+                    baseRoot,
+                    locatorRoot,
+                    surfaceRoot,
+                    attempts,
+                    prepareOptions: {
+                        allowReadonlyFallback: action === 'fill' && target.controlFamily === 'datepicker',
+                        allowDescendantPressFallback: action === 'press' &&
+                            (target.controlFamily === 'text-input' ||
+                                target.controlFamily === 'select' ||
+                                target.controlFamily === 'datepicker'),
+                        isUserActionable: isLocatorUserActionable,
+                    },
+                    onPreparedLocator: async (resolvedLocator, strategy) => attemptResolvedLocator(resolvedLocator, strategy),
                 });
-                if (preparedLocator.blockedReason === 'disabled') {
+                if (resolution.sawDisabledTarget) {
                     sawDisabledTarget = true;
                 }
-                if (preparedLocator.blockedReason === 'readonly') {
+                if (resolution.sawReadonlyTarget) {
                     sawReadonlyTarget = true;
                 }
-                const resolvedLocator = preparedLocator.locator;
-                if (!resolvedLocator) {
-                    continue;
-                }
-                const resolved = await attemptResolvedLocator(resolvedLocator, candidate.strategy);
-                if (resolved) {
-                    break;
+            };
+            await tryRankedCandidates();
+            if (!resolvedBy && !lastError && deferSurfaceResolution && surface) {
+                const deferredSurfaceRoot = await resolveSurfaceScopeRoot(page, surface, attempts);
+                if (deferredSurfaceRoot) {
+                    surfaceRoot = deferredSurfaceRoot;
+                    locatorRoot = targetUsesSurfaceAsPrimaryLocator(target, surface) ? baseRoot : surfaceRoot;
+                    await tryRankedCandidates();
                 }
             }
-        };
-        await tryRankedCandidates();
-        if (!resolvedBy && !lastError && deferSurfaceResolution && surface) {
-            const deferredSurfaceRoot = await resolveSurfaceScopeRoot(page, surface, attempts);
-            if (deferredSurfaceRoot) {
-                surfaceRoot = deferredSurfaceRoot;
-                locatorRoot = targetUsesSurfaceAsPrimaryLocator(target, surface) ? baseRoot : surfaceRoot;
-                await tryRankedCandidates();
-            }
-        }
-        if (!resolvedBy && !lastError && surfaceRoot) {
-            const recoveredLocator = await recoverLocatorFromSurfaceRoot(surfaceRoot, target, action, attempts);
-            if (recoveredLocator) {
-                await attemptResolvedLocator(recoveredLocator, 'surface-descendant', {
-                    skipDomSignature: true,
-                });
-            }
-        }
-        if (!resolvedBy) {
-            if (sawDomSignatureMismatch) {
-                staleReason = 'dom-signature-mismatch';
-                throw new Error('stale_target_dom_signature_changed');
-            }
-            if (sawDisabledTarget) {
-                setTargetAvailability(session, targetRef, 'gated', 'disabled');
-                throw new Error('target_disabled');
-            }
-            if (sawReadonlyTarget && (action === 'fill' || action === 'type')) {
-                setTargetAvailability(session, targetRef, 'gated', 'readonly');
-                throw new Error('target_readonly');
-            }
-            if (!lastError &&
-                target.surfaceRef &&
-                (target.acceptancePolicy === 'selection' || target.acceptancePolicy === 'date-selection')) {
-                setTargetAvailability(session, targetRef, 'surface-inactive', 'surface-not-active');
-                throw new Error('target_surface_inactive');
+            if (!resolvedBy && !lastError && surfaceRoot) {
+                const recoveredLocator = await recoverLocatorFromSurfaceRoot(surfaceRoot, target, action, attempts);
+                if (recoveredLocator) {
+                    await attemptResolvedLocator(recoveredLocator, 'surface-descendant', {
+                        skipDomSignature: true,
+                    });
+                }
             }
             if (!resolvedBy) {
+                if (sawDomSignatureMismatch) {
+                    staleReason = 'dom-signature-mismatch';
+                    throw new Error('stale_target_dom_signature_changed');
+                }
+                if (sawDisabledTarget) {
+                    setTargetAvailability(session, targetRef, 'gated', 'disabled');
+                    throw new Error('target_disabled');
+                }
+                if (sawReadonlyTarget && (action === 'fill' || action === 'type')) {
+                    setTargetAvailability(session, targetRef, 'gated', 'readonly');
+                    throw new Error('target_readonly');
+                }
                 if (!lastError &&
-                    (target.controlFamily === 'text-input' ||
-                        target.controlFamily === 'select' ||
-                        target.controlFamily === 'datepicker')) {
-                    staleReason = 'locator-resolution-failed';
-                    throw new Error('stale_target_locator_resolution_failed');
+                    target.surfaceRef &&
+                    (target.acceptancePolicy === 'selection' || target.acceptancePolicy === 'date-selection')) {
+                    setTargetAvailability(session, targetRef, 'surface-inactive', 'surface-not-active');
+                    throw new Error('target_surface_inactive');
                 }
-                if (lastError) {
-                    throw lastError;
+                if (!resolvedBy) {
+                    if (!lastError &&
+                        (target.controlFamily === 'text-input' ||
+                            target.controlFamily === 'select' ||
+                            target.controlFamily === 'datepicker')) {
+                        staleReason = 'locator-resolution-failed';
+                        throw new Error('stale_target_locator_resolution_failed');
+                    }
+                    if (lastError) {
+                        throw lastError;
+                    }
+                    throw new Error('deterministic_target_resolution_failed');
                 }
-                throw new Error('deterministic_target_resolution_failed');
             }
-        }
-        const popup = await popupPromise;
-        const latePage = !popup && watchForNewPage ? await waitForLatePage(browser, beforePages) : null;
-        if (latePage) {
-            attempts.push('late-page-captured');
-        }
-        const discoveredPage = popup ?? latePage;
-        const afterPages = discoveredPage ? [...beforePages, discoveredPage] : listPages(browser);
-        const capturedPopup = await capturePopupIfOpened(session, beforePages, afterPages, target.pageRef, attempts);
-        let finalPageRef = target.pageRef;
-        if (capturedPopup) {
-            await syncSessionPage(session, capturedPopup.page.pageRef, capturedPopup.popup, {
-                settleTimeoutMs: 1_500,
-            });
-            setCurrentPage(session, capturedPopup.page.pageRef);
-            finalPageRef = capturedPopup.page.pageRef;
-            currentPageRef = finalPageRef;
-        }
-        else {
-            const syncedPage = await syncSessionPage(session, target.pageRef, page);
-            currentPageRef = target.pageRef;
-            if (startingPageUrl && syncedPage.url && syncedPage.url !== startingPageUrl) {
-                clearProtectedExposure(session, target.pageRef);
+            const popup = await popupPromise;
+            const latePage = !popup && watchForNewPage ? await waitForLatePage(browser, beforePages) : null;
+            if (latePage) {
+                attempts.push('late-page-captured');
+            }
+            const discoveredPage = popup ?? latePage;
+            const afterPages = discoveredPage ? [...beforePages, discoveredPage] : listPages(browser);
+            const capturedPopup = await capturePopupIfOpened(session, beforePages, afterPages, target.pageRef, attempts);
+            let finalPageRef = target.pageRef;
+            if (capturedPopup) {
+                await syncSessionPage(session, capturedPopup.page.pageRef, capturedPopup.popup, {
+                    settleTimeoutMs: 1_500,
+                });
+                setCurrentPage(session, capturedPopup.page.pageRef);
+                finalPageRef = capturedPopup.page.pageRef;
+                currentPageRef = finalPageRef;
             }
-            const finalProgressProbe = progressProbe;
-            if (finalProgressProbe) {
-                const acceptance = await waitForAcceptanceProbe(finalProgressProbe);
-                const afterPageObservation = acceptance.afterPageObservation;
-                const accepted = acceptance.accepted;
-                if (acceptance.polls > 1) {
-                    attempts.push(`acceptance.polled:${acceptance.polls}`);
+            else {
+                const syncedPage = await syncSessionPage(session, target.pageRef, page);
+                currentPageRef = target.pageRef;
+                if (startingPageUrl && syncedPage.url && syncedPage.url !== startingPageUrl) {
+                    clearProtectedExposure(session, target.pageRef);
                 }
-                if (!accepted) {
-                    if (finalProgressProbe.policy === 'value-change') {
-                        attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
-                        throw new Error('action_postcondition_failed:value-change');
-                    }
-                    if ((finalProgressProbe.policy === 'selection' ||
-                        finalProgressProbe.policy === 'date-selection') &&
-                        finalProgressProbe.expectedValue !== null) {
-                        attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
-                        throw new Error(`action_postcondition_failed:${finalProgressProbe.policy}`);
+                const progressProbeForVerification = progressProbe;
+                if (progressProbeForVerification) {
+                    const finalProgressProbe = progressProbeForVerification;
+                    const acceptance = await waitForAcceptanceProbe(finalProgressProbe);
+                    const afterPageObservation = acceptance.afterPageObservation;
+                    const accepted = acceptance.accepted;
+                    if (acceptance.polls > 1) {
+                        attempts.push(`acceptance.polled:${acceptance.polls}`);
                     }
-                    if (finalProgressProbe.policy === 'submit') {
-                        const submitResolution = await resolveSubmitResult(finalProgressProbe, afterPageObservation);
-                        if (submitResolution.acceptAsProgress) {
-                            attempts.push(`submit-resolution:${submitResolution.finalVerdict}`);
-                            if (submitResolution.claims.some((claim) => claim.kind === 'soft_result_candidate')) {
-                                attempts.push('submit-resolution:soft-result-candidate');
+                    if (!accepted) {
+                        if (finalProgressProbe.policy === 'value-change') {
+                            attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
+                            throw new Error('action_postcondition_failed:value-change');
+                        }
+                        if ((finalProgressProbe.policy === 'selection' ||
+                            finalProgressProbe.policy === 'date-selection') &&
+                            finalProgressProbe.expectedValue !== null) {
+                            attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
+                            throw new Error(`action_postcondition_failed:${finalProgressProbe.policy}`);
+                        }
+                        if (finalProgressProbe.policy === 'submit') {
+                            const submitResolution = await resolveSubmitResult(finalProgressProbe, afterPageObservation);
+                            if (submitResolution.acceptAsProgress) {
+                                attempts.push(`submit-resolution:${submitResolution.finalVerdict}`);
+                                if (submitResolution.claims.some((claim) => claim.kind === 'soft_result_candidate')) {
+                                    attempts.push('submit-resolution:soft-result-candidate');
+                                }
+                            }
+                            else {
+                                attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
+                                attempts.push('no-progress.detected');
+                                noProgressDiagnosis = await diagnoseNoObservableProgress(page, finalProgressProbe.locator);
+                                if (noProgressDiagnosis) {
+                                    attempts.push(`no-progress.diagnosis:${noProgressDiagnosis.kind}`);
+                                }
+                                throw new Error('no_observable_progress');
                             }
                         }
                         else {
-                            attempts.push(`acceptance.failed:${finalProgressProbe.policy}`);
-                            attempts.push('no-progress.detected');
-                            noProgressDiagnosis = await diagnoseNoObservableProgress(page, finalProgressProbe.locator);
-                            if (noProgressDiagnosis) {
-                                attempts.push(`no-progress.diagnosis:${noProgressDiagnosis.kind}`);
+                            const afterLocatorObservation = finalProgressProbe.trackedStateKeys.length > 0
+                                ? await captureLocatorState(finalProgressProbe.locator, finalProgressProbe.trackedStateKeys)
+                                : null;
+                            const afterContextHash = await captureLocatorContextHash(finalProgressProbe.locator);
+                            const hasComparableSignal = finalProgressProbe.trackedStateKeys.length > 0 ||
+                                Boolean(finalProgressProbe.beforeContextHash || afterContextHash) ||
+                                Boolean(finalProgressProbe.beforePage || afterPageObservation);
+                            const pageProgressChanged = finalProgressProbe.policy === 'generic-click'
+                                ? genericClickObservationChanged(finalProgressProbe.beforePage, afterPageObservation)
+                                : pageObservationChanged(finalProgressProbe.beforePage, afterPageObservation);
+                            if (hasComparableSignal &&
+                                !pageProgressChanged &&
+                                finalProgressProbe.beforeContextHash === afterContextHash &&
+                                !locatorStateChanged(finalProgressProbe.beforeLocator, afterLocatorObservation)) {
+                                attempts.push('no-progress.detected');
+                                noProgressDiagnosis = await diagnoseNoObservableProgress(page, finalProgressProbe.locator);
+                                if (noProgressDiagnosis) {
+                                    attempts.push(`no-progress.diagnosis:${noProgressDiagnosis.kind}`);
+                                }
+                                throw new Error('no_observable_progress');
                             }
-                            throw new Error('no_observable_progress');
                         }
                     }
                     else {
-                        const afterLocatorObservation = finalProgressProbe.trackedStateKeys.length > 0
-                            ? await captureLocatorState(finalProgressProbe.locator, finalProgressProbe.trackedStateKeys)
-                            : null;
-                        const afterContextHash = await captureLocatorContextHash(finalProgressProbe.locator);
-                        const hasComparableSignal = finalProgressProbe.trackedStateKeys.length > 0 ||
-                            Boolean(finalProgressProbe.beforeContextHash || afterContextHash) ||
-                            Boolean(finalProgressProbe.beforePage || afterPageObservation);
-                        const pageProgressChanged = finalProgressProbe.policy === 'generic-click'
-                            ? genericClickObservationChanged(finalProgressProbe.beforePage, afterPageObservation)
-                            : pageObservationChanged(finalProgressProbe.beforePage, afterPageObservation);
-                        if (hasComparableSignal &&
-                            !pageProgressChanged &&
-                            finalProgressProbe.beforeContextHash === afterContextHash &&
-                            !locatorStateChanged(finalProgressProbe.beforeLocator, afterLocatorObservation)) {
-                            attempts.push('no-progress.detected');
-                            noProgressDiagnosis = await diagnoseNoObservableProgress(page, finalProgressProbe.locator);
-                            if (noProgressDiagnosis) {
-                                attempts.push(`no-progress.diagnosis:${noProgressDiagnosis.kind}`);
-                            }
-                            throw new Error('no_observable_progress');
+                        partialProgressResult = await partialProgressForAliasedSelection({
+                            requestedAction,
+                            probe: finalProgressProbe,
+                        });
+                        if (partialProgressResult) {
+                            attempts.push('outcome.partial-progress:selection-not-complete');
                         }
                     }
                 }
-            }
-        }
-        if (resolvedBy === 'playwright-locator') {
-            incrementMetric(session, 'deterministicActions');
-        }
-        bumpPageScopeEpoch(session, target.pageRef);
-        recordActionResult(session, true, Date.now() - startedAt);
-        saveSession(session);
-        await trace.finishSuccess();
-        outputJSON({
-            success: true,
-            targetRef,
-            action,
-            value: actionValue,
-            resolvedBy,
-            locatorStrategy,
-            pageRef: finalPageRef,
-            attempts,
-            popup: Boolean(capturedPopup),
-            overlayHandled: attempts.includes('overlay.dismissed'),
-            iframe: Boolean(target.framePath?.length),
-            jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
-            ...(recoveredAfterError
-                ? {
-                    recoveredAfterError: true,
-                    recoveredAcceptancePolicy: recoveredAcceptancePolicy ?? undefined,
+                else if (recoveredProgressProbe) {
+                    partialProgressResult = await partialProgressForAliasedSelection({
+                        requestedAction,
+                        probe: recoveredProgressProbe,
+                    });
+                    if (partialProgressResult) {
+                        attempts.push('outcome.partial-progress:selection-not-complete');
+                    }
                 }
-                : {}),
-            durationMs: Date.now() - startedAt,
-            metrics: session.runtime?.metrics,
-        });
-    }
-    catch (err) {
-        failureMessage = `Act failed: ${err instanceof Error ? err.message : String(err)}`;
-        recordActionResult(session, false, Date.now() - startedAt);
-        if (staleReason) {
-            markTargetLifecycle(session, targetRef, 'stale', staleReason);
+            }
+            if (resolvedBy === 'playwright-locator') {
+                incrementMetric(session, 'deterministicActions');
+            }
+            bumpPageScopeEpoch(session, target.pageRef);
+            recordActionResult(session, true, Date.now() - startedAt);
+            saveSession(session);
+            await trace.finishSuccess();
+            captureStepSnapshotBestEffort({
+                session,
+                step: actStep,
+                phase: 'after',
+                pageRef: finalPageRef,
+            });
+            appendCommandLifecycleEventBestEffort({
+                step: actStep,
+                phase: 'completed',
+                attributes: {
+                    outcomeType: partialProgressResult?.outcomeType ?? 'action_completed',
+                    targetRef,
+                    action: requestedAction,
+                    pageRef: finalPageRef,
+                },
+            });
+            finalizeActStepBestEffort(runId, actStep?.stepId, {
+                success: true,
+                outcomeType: partialProgressResult?.outcomeType ?? 'action_completed',
+                message: partialProgressResult?.message ?? 'The requested action completed successfully.',
+            });
+            await exportRunStepToOtlpHttpJsonBestEffort(runId, actStep?.stepId);
+            outputJSON({
+                success: true,
+                targetRef,
+                action: requestedAction,
+                ...(action !== requestedAction ? { executedAs: action } : {}),
+                value: actionValue,
+                resolvedBy,
+                locatorStrategy,
+                pageRef: finalPageRef,
+                attempts,
+                popup: Boolean(capturedPopup),
+                overlayHandled: attempts.includes('overlay.dismissed'),
+                iframe: Boolean(target.framePath?.length),
+                jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
+                ...(recoveredAfterError
+                    ? {
+                        recoveredAfterError: true,
+                        recoveredAcceptancePolicy: recoveredAcceptancePolicy ?? undefined,
+                    }
+                    : {}),
+                ...(partialProgressResult ?? {}),
+                durationMs: Date.now() - startedAt,
+                metrics: session.runtime?.metrics,
+            });
         }
-        saveSession(session);
-        if (currentPage) {
-            try {
-                const protectedExposure = getProtectedExposure(session, currentPageRef);
-                if (protectedExposure) {
-                    await trace.finishSuccess();
-                    failureArtifacts = buildProtectedArtifactsSuppressed(protectedExposure);
+        catch (err) {
+            failureMessage = `Act failed: ${err instanceof Error ? err.message : String(err)}`;
+            recordActionResult(session, false, Date.now() - startedAt);
+            if (staleReason) {
+                markTargetLifecycle(session, targetRef, 'stale', staleReason);
+            }
+            saveSession(session);
+            if (currentPage) {
+                try {
+                    const protectedExposure = getProtectedExposure(session, currentPageRef);
+                    if (protectedExposure) {
+                        await trace.finishSuccess();
+                        failureArtifacts = buildProtectedArtifactsSuppressed(protectedExposure);
+                    }
+                    else {
+                        failureArtifacts = await captureActionFailureArtifacts({
+                            page: currentPage,
+                            targetRef,
+                            action: requestedAction,
+                            pageRef: currentPageRef,
+                            attempts,
+                            locatorStrategy,
+                            popup: attempts.includes('popup-captured'),
+                            overlayHandled: attempts.includes('overlay.dismissed'),
+                            iframe: Boolean(target.framePath?.length),
+                            jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
+                            durationMs: Date.now() - startedAt,
+                            error: failureMessage,
+                            finishTrace: (artifactDir) => trace.finishFailure(artifactDir),
+                        });
+                    }
                 }
-                else {
-                    failureArtifacts = await captureActionFailureArtifacts({
-                        page: currentPage,
-                        targetRef,
-                        action,
-                        pageRef: currentPageRef,
-                        attempts,
-                        locatorStrategy,
-                        popup: attempts.includes('popup-captured'),
-                        overlayHandled: attempts.includes('overlay.dismissed'),
-                        iframe: Boolean(target.framePath?.length),
-                        jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
-                        durationMs: Date.now() - startedAt,
-                        error: failureMessage,
-                        finishTrace: (artifactDir) => trace.finishFailure(artifactDir),
-                    });
+                catch {
+                    // Best effort only. Preserve the original action failure.
                 }
             }
-            catch {
-                // Best effort only. Preserve the original action failure.
-            }
         }
-    }
-    finally {
-        if (browser) {
-            disconnectPlaywright(browser);
+        finally {
+            if (browser) {
+                await disconnectPlaywright(browser);
+            }
         }
-    }
-    if (failureMessage) {
-        if (failureMessage === 'Act failed: no_observable_progress' && noProgressDiagnosis) {
-            failureMessage = `Act failed: no_observable_progress (${noProgressDiagnosis.kind})`;
+        if (failureMessage) {
+            if (failureMessage === 'Act failed: no_observable_progress' && noProgressDiagnosis) {
+                failureMessage = `Act failed: no_observable_progress (${noProgressDiagnosis.kind})`;
+            }
+            const failureContract = describeActFailure({
+                failureMessage,
+                staleReason,
+                diagnosis: noProgressDiagnosis,
+            });
+            const protectedExposure = getProtectedExposure(session, currentPageRef);
+            const outputDiagnosis = protectedExposure && noProgressDiagnosis
+                ? redactNoObservableProgressDiagnosis(noProgressDiagnosis)
+                : noProgressDiagnosis;
+            const artifactManifestId = persistActArtifactManifestBestEffort(runId, actStep?.stepId, failureArtifacts ?? null);
+            captureStepSnapshotBestEffort({
+                session,
+                step: actStep,
+                phase: 'point-in-time',
+                pageRef: currentPageRef,
+                artifactRefs: buildActSnapshotArtifactRefs(failureArtifacts ?? null),
+            });
+            appendCommandLifecycleEventBestEffort({
+                step: actStep,
+                phase: 'failed',
+                attributes: {
+                    outcomeType: failureContract.outcomeType,
+                    targetRef,
+                    action: requestedAction,
+                    pageRef: currentPageRef,
+                    ...(artifactManifestId ? { artifactManifestId } : {}),
+                },
+            });
+            finalizeActStepBestEffort(runId, actStep?.stepId, {
+                success: false,
+                outcomeType: failureContract.outcomeType,
+                message: failureContract.message,
+                reason: failureContract.reason,
+                artifactManifestId,
+            });
+            await exportRunStepToOtlpHttpJsonBestEffort(runId, actStep?.stepId);
+            outputFailure({
+                error: failureMessage,
+                outcomeType: failureContract.outcomeType,
+                message: failureContract.message,
+                reason: failureContract.reason,
+                targetRef,
+                action: requestedAction,
+                ...(action !== requestedAction ? { executedAs: action } : {}),
+                value: actionValue,
+                pageRef: currentPageRef,
+                locatorStrategy,
+                attempts,
+                popup: attempts.includes('popup-captured'),
+                overlayHandled: attempts.includes('overlay.dismissed'),
+                iframe: Boolean(target.framePath?.length),
+                jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
+                durationMs: Date.now() - startedAt,
+                staleTarget: Boolean(staleReason),
+                staleReason: staleReason ?? undefined,
+                diagnosis: outputDiagnosis ?? undefined,
+                artifacts: failureArtifacts,
+                metrics: session.runtime?.metrics,
+            });
         }
-        const failureContract = describeActFailure({
-            failureMessage,
-            staleReason,
-            diagnosis: noProgressDiagnosis,
-        });
-        const protectedExposure = getProtectedExposure(session, currentPageRef);
-        const outputDiagnosis = protectedExposure && noProgressDiagnosis
-            ? redactNoObservableProgressDiagnosis(noProgressDiagnosis)
-            : noProgressDiagnosis;
-        outputFailure({
-            error: failureMessage,
-            outcomeType: failureContract.outcomeType,
-            message: failureContract.message,
-            reason: failureContract.reason,
-            targetRef,
-            action,
-            value: actionValue,
-            pageRef: currentPageRef,
-            locatorStrategy,
-            attempts,
-            popup: attempts.includes('popup-captured'),
-            overlayHandled: attempts.includes('overlay.dismissed'),
-            iframe: Boolean(target.framePath?.length),
-            jsFallback: attempts.some((attempt) => attempt.startsWith('locator.evaluate.')),
-            durationMs: Date.now() - startedAt,
-            staleTarget: Boolean(staleReason),
-            staleReason: staleReason ?? undefined,
-            diagnosis: outputDiagnosis ?? undefined,
-            artifacts: failureArtifacts,
-            metrics: session.runtime?.metrics,
-        });
-    }
+    });
 }