mobile-debug-mcp 0.26.5 → 0.28.0

package/dist/interact/index.js

@@ -5,7 +5,26 @@ export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
 import { computeSnapshotSignature } from '../observe/snapshot-metadata.js';
-import { buildActionExecutionResult } from '../server/common.js';
+import { buildActionExecutionResult, createTraceStep, nextActionId } from '../server/common.js';
+function buildObservationTrace({ actionType, stage, success, attempts, metadata }) {
+    const now = Date.now();
+    const actionId = nextActionId(actionType, now);
+    const steps = [
+        createTraceStep({
+            stage,
+            timestamp: now,
+            result: success ? 'success' : 'failure',
+            attemptIndex: 0,
+            metadata
+        })
+    ];
+    return {
+        action_id: actionId,
+        steps,
+        final_outcome: success ? 'success' : 'failure',
+        attempts: Math.max(1, Math.floor(attempts || 1))
+    };
+}
 export class ToolsInteract {
     static _maxResolvedUiElements = 256;
     static _uiChangeKinds = ['hierarchy_diff', 'text_change', 'state_change'];
@@ -291,6 +310,38 @@ export class ToolsInteract {
         const safeRatio = Math.min(1 - (endpointMargin * 0.25), Math.max(endpointMargin, targetRatio + centerBias + directionBias + edgeBias));
         return ToolsInteract._buildControlPoint(bounds, safeRatio, axis);
     }
+    static _buildAdjustmentProbePoints(bounds, targetValue, currentValue, min, max, axis) {
+        const targetPoint = ToolsInteract._buildConservativeControlPoint(bounds, targetValue, currentValue, min, max, axis);
+        const currentPoint = currentValue !== null
+            ? ToolsInteract._buildControlPoint(bounds, (currentValue - min) / (max - min), axis)
+            : ToolsInteract._buildControlPoint(bounds, 0.5, axis);
+        const [left, top, right, bottom] = bounds;
+        const width = Math.max(1, right - left);
+        const height = Math.max(1, bottom - top);
+        const crossAxisBumps = axis === 'horizontal'
+            ? [Math.max(24, Math.floor(height * 0.75)), Math.max(40, Math.floor(height * 1.5))]
+            : [Math.max(24, Math.floor(width * 0.75)), Math.max(40, Math.floor(width * 1.5))];
+        const clampPoint = (point) => ({
+            x: axis === 'horizontal'
+                ? Math.max(left, Math.min(right, point.x))
+                : Math.max(left, Math.min(right + Math.max(width, height), point.x)),
+            y: axis === 'vertical'
+                ? Math.max(top, Math.min(bottom, point.y))
+                : Math.max(top, Math.min(bottom + Math.max(height, width), point.y))
+        });
+        const probes = [targetPoint, currentPoint];
+        for (const bump of crossAxisBumps) {
+            if (axis === 'horizontal') {
+                probes.push({ x: targetPoint.x, y: bottom + bump }, { x: currentPoint.x, y: bottom + bump });
+            }
+            else {
+                probes.push({ x: right + bump, y: targetPoint.y }, { x: right + bump, y: currentPoint.y });
+            }
+        }
+        return Array.from(new Map(probes
+            .map(clampPoint)
+            .map((point) => [`${point.x}:${point.y}`, point])).values());
+    }
     static _controlAxis(el, bounds) {
         const type = ToolsInteract._normalize(el.type ?? el.class ?? '');
         const role = ToolsInteract._normalize(el.role ?? '');
@@ -501,7 +552,33 @@ export class ToolsInteract {
         let resolvedDeviceId = deviceId;
         const fingerprintBefore = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
         let semanticFallbackElement = null;
+        const traceSteps = [];
+        let traceAttemptIndex = 0;
+        const recordTraceStep = (stage, result, metadata) => {
+            traceSteps.push(createTraceStep({
+                stage,
+                timestamp: Date.now(),
+                result,
+                attemptIndex: traceAttemptIndex++,
+                metadata
+            }));
+        };
         const buildFailure = (failureCode, reason, resolved, device, actualState, attempts, adjustmentMode = 'gesture', retryable = false, uiFingerprintAfter = null) => {
+            if (!traceSteps.some((step) => step.stage === 'resolve')) {
+                recordTraceStep('resolve', 'failure', {
+                    reason,
+                    failure_code: failureCode
+                });
+            }
+            if (!traceSteps.some((step) => step.stage === 'recover')) {
+                recordTraceStep('recover', retryable ? 'retry' : 'failure', {
+                    reason,
+                    failure_code: failureCode,
+                    retry_allowed: retryable,
+                    recovery_attempts: attempts,
+                    retry_depth: attempts
+                });
+            }
             const base = buildActionExecutionResult({
                 actionType,
                 sourceModule: 'interact',
@@ -522,7 +599,8 @@ export class ToolsInteract {
                     converged: false,
                     within_tolerance: false,
                     reason
-                }
+                },
+                traceSteps
             });
             return {
                 ...base,
@@ -684,10 +762,23 @@ export class ToolsInteract {
                 ? { property, value: currentValue, raw_value: typeof currentEl.state?.raw_value === 'number' ? currentEl.state.raw_value : undefined }
                 : null;
             lastObservedState = actualState;
+            if (!traceSteps.some((step) => step.stage === 'resolve')) {
+                recordTraceStep('resolve', 'success', {
+                    resolved_target: resolvedTarget,
+                    current_value: currentValue,
+                    adjustment_mode: lastAdjustmentMode
+                });
+            }
             if (property !== 'value' && property !== 'raw_value') {
                 return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjust_control currently supports numeric value and raw_value properties only', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
             }
             if (currentValue !== null && Math.abs(currentValue - targetValue) <= normalizedTolerance) {
+                recordTraceStep('verify', 'success', {
+                    property,
+                    target_value: targetValue,
+                    actual_state: actualState,
+                    reason: 'control already within tolerance'
+                });
                 const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
                 const base = buildActionExecutionResult({
                     actionType,
@@ -708,7 +799,8 @@ export class ToolsInteract {
                         converged: true,
                         within_tolerance: true,
                         reason: 'control already within tolerance'
-                    }
+                    },
+                    traceSteps
                 });
                 return {
                     ...base,
@@ -743,6 +835,7 @@ export class ToolsInteract {
             const currentPoint = currentValue !== null
                 ? ToolsInteract._buildControlPoint(bounds, (currentValue - min) / (max - min), axis)
                 : ToolsInteract._buildControlPoint(bounds, 0.5, axis);
+            const probePoints = ToolsInteract._buildAdjustmentProbePoints(bounds, targetValue, currentValue, min, max, axis);
             const runVerification = async () => {
                 const verification = await ToolsInteract.expectStateHandler({
                     element_id: resolvedTarget?.elementId ?? element_id,
@@ -770,37 +863,92 @@ export class ToolsInteract {
                     withinTolerance: observedValue !== null && Math.abs(observedValue - targetValue) <= normalizedTolerance
                 };
             };
-            lastAdjustmentMode = 'coordinate';
-            const primaryActionResult = await ToolsInteract.tapHandler({
-                platform: resolvedPlatform,
-                x: targetPoint.x,
-                y: targetPoint.y,
-                deviceId: resolvedDeviceId
-            });
-            let actionDevice = primaryActionResult.device ?? currentDevice;
-            attemptCount++;
-            if (!primaryActionResult.success) {
-                lastAdjustmentMode = 'gesture';
-                const fallbackActionResult = await ToolsInteract.swipeHandler({
+            let actionDevice = currentDevice;
+            let observedState = actualState;
+            let verification = null;
+            let verificationResult = { verification: null, observedState: actualState, withinTolerance: false };
+            for (let i = 0; i < probePoints.length; i++) {
+                const probePoint = probePoints[i];
+                lastAdjustmentMode = 'coordinate';
+                recordTraceStep('execute', 'retry', {
+                    attempt: attemptCount + 1,
+                    mode: 'coordinate',
+                    point: probePoint
+                });
+                const actionResult = await ToolsInteract.tapHandler({
                     platform: resolvedPlatform,
-                    x1: currentPoint.x,
-                    y1: currentPoint.y,
-                    x2: targetPoint.x,
-                    y2: targetPoint.y,
-                    duration: 220,
+                    x: probePoint.x,
+                    y: probePoint.y,
                     deviceId: resolvedDeviceId
                 });
                 attemptCount++;
-                if (!fallbackActionResult.success) {
-                    return buildFailure('UNKNOWN', fallbackActionResult.error ?? primaryActionResult.error ?? 'adjustment gesture failed', resolvedTarget, fallbackActionResult.device ?? primaryActionResult.device, actualState, attemptCount, lastAdjustmentMode, false);
+                actionDevice = actionResult.device ?? actionDevice;
+                if (!actionResult.success) {
+                    recordTraceStep('execute', 'retry', {
+                        attempt: attemptCount,
+                        mode: 'coordinate',
+                        point: probePoint,
+                        success: false
+                    });
+                    continue;
+                }
+                verificationResult = await runVerification();
+                observedState = verificationResult.observedState;
+                lastObservedState = observedState;
+                recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+                    attempt: attemptCount,
+                    property,
+                    target_value: targetValue,
+                    actual_state: observedState,
+                    reason: verificationResult.verification?.reason ?? 'control did not converge yet'
+                });
+                if (verificationResult.withinTolerance) {
+                    const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
+                    const base = buildActionExecutionResult({
+                        actionType,
+                        sourceModule: 'interact',
+                        device: actionDevice ?? currentDevice,
+                        selector: targetSelector,
+                        resolved: resolvedTarget,
+                        success: true,
+                        uiFingerprintBefore: fingerprintBefore,
+                        uiFingerprintAfter,
+                        details: {
+                            target_value: targetValue,
+                            tolerance: normalizedTolerance,
+                            property,
+                            attempts: attemptCount,
+                            adjustment_mode: lastAdjustmentMode,
+                            actual_state: observedState,
+                            converged: true,
+                            within_tolerance: true,
+                            reason: verificationResult.verification?.reason ?? 'control converged to target value'
+                        },
+                        traceSteps
+                    });
+                    return {
+                        ...base,
+                        target_state: {
+                            property,
+                            target_value: targetValue,
+                            tolerance: normalizedTolerance
+                        },
+                        actual_state: observedState,
+                        within_tolerance: true,
+                        converged: true,
+                        attempts: attemptCount,
+                        adjustment_mode: lastAdjustmentMode
+                    };
                 }
-                actionDevice = fallbackActionResult.device ?? actionDevice;
             }
-            let verificationResult = await runVerification();
-            let observedState = verificationResult.observedState;
-            lastObservedState = observedState;
-            if (!verificationResult.withinTolerance && currentValue !== null) {
+            if (currentValue !== null) {
                 lastAdjustmentMode = 'gesture';
+                recordTraceStep('execute', 'retry', {
+                    attempt: attemptCount + 1,
+                    mode: 'gesture',
+                    start: currentPoint,
+                    end: targetPoint
+                });
                 const fallbackActionResult = await ToolsInteract.swipeHandler({
                     platform: resolvedPlatform,
                     x1: currentPoint.x,
@@ -812,14 +960,75 @@ export class ToolsInteract {
                 });
                 attemptCount++;
                 if (!fallbackActionResult.success) {
-                    return buildFailure('UNKNOWN', fallbackActionResult.error ?? 'adjustment gesture failed', resolvedTarget, fallbackActionResult.device, observedState ?? actualState, attemptCount, lastAdjustmentMode, false);
+                    recordTraceStep('execute', 'failure', {
+                        attempt: attemptCount,
+                        mode: 'gesture',
+                        start: currentPoint,
+                        end: targetPoint,
+                        success: false
+                    });
+                    return buildFailure('UNKNOWN', fallbackActionResult.error ?? 'adjustment gesture failed', resolvedTarget, fallbackActionResult.device ?? actionDevice, observedState ?? actualState, attemptCount, lastAdjustmentMode, false);
                 }
+                actionDevice = fallbackActionResult.device ?? actionDevice;
                 verificationResult = await runVerification();
                 observedState = verificationResult.observedState;
+                lastObservedState = observedState;
+                recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+                    attempt: attemptCount,
+                    property,
+                    target_value: targetValue,
+                    actual_state: observedState,
+                    reason: verificationResult.verification?.reason ?? 'gesture adjustment did not converge yet'
+                });
+                if (verificationResult.withinTolerance) {
+                    const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
+                    const base = buildActionExecutionResult({
+                        actionType,
+                        sourceModule: 'interact',
+                        device: actionDevice ?? currentDevice,
+                        selector: targetSelector,
+                        resolved: resolvedTarget,
+                        success: true,
+                        uiFingerprintBefore: fingerprintBefore,
+                        uiFingerprintAfter,
+                        details: {
+                            target_value: targetValue,
+                            tolerance: normalizedTolerance,
+                            property,
+                            attempts: attemptCount,
+                            adjustment_mode: lastAdjustmentMode,
+                            actual_state: observedState,
+                            converged: true,
+                            within_tolerance: true,
+                            reason: verificationResult.verification?.reason ?? 'control converged to target value'
+                        },
+                        traceSteps
+                    });
+                    return {
+                        ...base,
+                        target_state: {
+                            property,
+                            target_value: targetValue,
+                            tolerance: normalizedTolerance
+                        },
+                        actual_state: observedState,
+                        within_tolerance: true,
+                        converged: true,
+                        attempts: attemptCount,
+                        adjustment_mode: lastAdjustmentMode
+                    };
+                }
             }
-            const verification = verificationResult.verification;
+            verification = verificationResult.verification;
             lastObservedState = observedState;
             if (verificationResult.withinTolerance) {
+                recordTraceStep('verify', 'success', {
+                    attempt: attemptCount,
+                    property,
+                    target_value: targetValue,
+                    actual_state: observedState,
+                    reason: verification?.reason ?? 'control converged to target value'
+                });
                 const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
                 const base = buildActionExecutionResult({
                     actionType,
@@ -840,7 +1049,8 @@ export class ToolsInteract {
                         converged: true,
                         within_tolerance: true,
                         reason: verification?.reason ?? 'control converged to target value'
-                    }
+                    },
+                    traceSteps
                 });
                 return {
                     ...base,
@@ -1224,6 +1434,10 @@ export class ToolsInteract {
         let lastMatchedCount = 0;
         let lastMatchedElement = null;
         let lastConditionSatisfied = false;
+        let matchedAt = null;
+        let stableMatchCount = 0;
+        const stableObservationCount = 2;
+        const snapshotStaleThresholdMs = 500;
         // Precompute normalized selector values and helpers (constant across polls)
         const normalize = ToolsInteract._normalize;
         const containsFlag = !!selector?.contains;
@@ -1338,23 +1552,34 @@ export class ToolsInteract {
                         lastMatchedCount = matchedCount;
                         lastConditionSatisfied = conditionMet;
                         lastMatchedElement = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null;
-                        if (conditionMet) {
-                            const now = Date.now();
-                            const latency_ms = now - overallStart;
-                            const outEl = lastMatchedElement;
-                            return {
-                                status: 'success',
-                                matched: matchedCount,
-                                element: outEl,
-                                metrics: { latency_ms, poll_count: totalPollCount, attempts },
-                                requested,
-                                observed: {
-                                    matched_count: matchedCount,
-                                    condition_satisfied: true,
-                                    selected_index: outEl?.index ?? null,
-                                    last_matched_element: outEl
-                                }
-                            };
+                        const now = Date.now();
+                        const snapshotAgeMs = typeof tree?.captured_at_ms === 'number' ? now - tree.captured_at_ms : null;
+                        const snapshotFresh = snapshotAgeMs === null || snapshotAgeMs <= snapshotStaleThresholdMs;
+                        if (conditionMet && snapshotFresh) {
+                            if (matchedAt === null)
+                                matchedAt = now;
+                            stableMatchCount++;
+                            if (stableMatchCount >= stableObservationCount) {
+                                const latency_ms = now - overallStart;
+                                const outEl = lastMatchedElement;
+                                return {
+                                    status: 'success',
+                                    matched: matchedCount,
+                                    element: outEl,
+                                    metrics: { latency_ms, poll_count: totalPollCount, attempts },
+                                    requested,
+                                    observed: {
+                                        matched_count: matchedCount,
+                                        condition_satisfied: true,
+                                        selected_index: outEl?.index ?? null,
+                                        last_matched_element: outEl
+                                    }
+                                };
+                            }
+                        }
+                        else {
+                            stableMatchCount = 0;
+                            matchedAt = null;
                         }
                     }
                     catch (e) {
@@ -1599,7 +1824,24 @@ export class ToolsInteract {
                 basis,
                 matched: success,
                 reason
-            }
+            },
+            trace: buildObservationTrace({
+                actionType: 'expect_screen',
+                stage: 'verify',
+                success,
+                attempts: 1,
+                metadata: {
+                    expected_screen: expectedScreen,
+                    observed_screen: {
+                        fingerprint: observedScreen.fingerprint,
+                        screen: observedScreenLabel
+                    },
+                    comparison: {
+                        basis,
+                        matched: success
+                    }
+                }
+            })
         };
     }
     static async expectElementVisibleHandler({ selector, element_id, timeout_ms = 5000, poll_interval_ms = 300, platform, deviceId }) {
@@ -1653,7 +1895,18 @@ export class ToolsInteract {
                         semantic: result.element.semantic ?? null
                     }
                 },
-                reason: 'selector is visible'
+                reason: 'selector is visible',
+                trace: buildObservationTrace({
+                    actionType: 'expect_element_visible',
+                    stage: 'verify',
+                    success: true,
+                    attempts: 1,
+                    metadata: {
+                        selector,
+                        element_id: result.element.elementId ?? element_id ?? null,
+                        status: result.status
+                    }
+                })
             };
         }
         const errorCode = result?.error?.code === 'INTERNAL_ERROR' ? 'UNKNOWN' : 'TIMEOUT';
@@ -1671,177 +1924,318 @@ export class ToolsInteract {
             },
             reason: result?.error?.message ?? 'selector is not visible',
             failure_code: errorCode,
-            retryable: errorCode === 'TIMEOUT'
+            retryable: errorCode === 'TIMEOUT',
+            trace: buildObservationTrace({
+                actionType: 'expect_element_visible',
+                stage: 'verify',
+                success: false,
+                attempts: 1,
+                metadata: {
+                    selector,
+                    element_id: element_id ?? null,
+                    status: result?.status ?? null,
+                    reason: result?.error?.message ?? 'selector is not visible'
+                }
+            })
         };
     }
-    static async expectStateHandler({ selector, element_id, property, expected, platform, deviceId }) {
-        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
-        const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
-        const treeDeviceId = tree?.device?.id || deviceId;
-        let matched = null;
-        if (element_id) {
-            const resolved = ToolsInteract._resolvedUiElements.get(element_id);
-            if (resolved) {
-                const current = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved);
-                if (current)
-                    matched = { el: current.el, idx: current.index };
-            }
-        }
-        if (!matched && selector) {
-            matched = ToolsInteract._findFirstMatchingElement(elements, selector);
-        }
-        if (!matched) {
-            return {
-                success: false,
-                selector,
-                element_id: element_id ?? null,
-                expected_state: { property, expected },
-                reason: 'element not found',
-                failure_code: 'ELEMENT_NOT_FOUND',
-                retryable: true
-            };
-        }
-        const resolvedElement = ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(treePlatform, treeDeviceId, matched.el, matched.idx), matched.el, matched.idx);
-        const observedState = matched.el.state ?? null;
-        const actual = observedState?.[property] ?? null;
+    static async expectStateHandler({ selector, element_id, property, expected, platform, deviceId, stabilization_window_ms = 1000, stable_observation_count = 2, snapshot_stale_threshold_ms = 500, poll_interval_ms = 150 }) {
         const compareBoolean = (value) => typeof value === 'boolean' ? value : null;
         const compareString = (value) => typeof value === 'string' ? value : null;
         const compareNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
-        let success = false;
-        let reason = '';
-        let rawValue = null;
-        let observedValue = actual;
-        switch (property) {
-            case 'checked':
-            case 'focused':
-            case 'expanded':
-            case 'enabled': {
-                const expectedBool = compareBoolean(expected);
-                const actualBool = compareBoolean(actual);
-                if (expectedBool === null) {
-                    reason = `expected ${property} must be boolean`;
-                }
-                else if (actualBool === null) {
-                    reason = `${property} state unavailable`;
-                }
-                else {
-                    rawValue = actualBool;
-                    success = actualBool === expectedBool;
-                    reason = success ? `${property} matches expected value` : `expected ${property}=${expectedBool} but observed ${actualBool}`;
+        const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+        const start = Date.now();
+        const deadline = start + Math.max(500, stabilization_window_ms);
+        const stableTarget = Math.max(1, Math.floor(stable_observation_count || 2));
+        const pollDelay = Math.max(100, Math.min(poll_interval_ms || 150, 200));
+        const staleThreshold = Math.max(300, Math.min(snapshot_stale_threshold_ms || 500, 800));
+        let attempts = 0;
+        let stableCount = 0;
+        let lastReason = 'element not found';
+        let lastFailureCode = 'ELEMENT_NOT_FOUND';
+        let lastObservedElement = null;
+        let lastObservedValue = null;
+        let lastRawValue = null;
+        let lastResolvedElementId = element_id ?? null;
+        const traceSteps = [];
+        let traceAttemptIndex = 0;
+        let resolveRecorded = false;
+        const recordTraceStep = (stage, result, metadata) => {
+            traceSteps.push(createTraceStep({
+                stage,
+                timestamp: Date.now(),
+                result,
+                attemptIndex: traceAttemptIndex++,
+                metadata
+            }));
+        };
+        const buildStateTrace = (outcome) => ({
+            action_id: nextActionId('expect_state', Date.now()),
+            steps: traceSteps,
+            final_outcome: outcome,
+            attempts
+        });
+        while (Date.now() <= deadline) {
+            attempts++;
+            const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+            const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+            const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
+            const treeDeviceId = tree?.device?.id || deviceId;
+            const treeAgeMs = typeof tree?.captured_at_ms === 'number' ? Date.now() - tree.captured_at_ms : null;
+            let matched = null;
+            if (element_id) {
+                const resolved = ToolsInteract._resolvedUiElements.get(element_id);
+                if (resolved) {
+                    const current = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved);
+                    if (current)
+                        matched = { el: current.el, idx: current.index };
                 }
-                observedValue = actualBool;
-                break;
             }
-            case 'value':
-            case 'raw_value': {
-                const expectedNumber = compareNumber(expected);
-                const actualNumber = compareNumber(actual);
-                if (expectedNumber !== null && actualNumber !== null) {
-                    success = actualNumber === expectedNumber;
-                    rawValue = actualNumber;
-                    observedValue = actualNumber;
-                    reason = success ? 'value matches expected value' : `expected value=${expectedNumber} but observed ${actualNumber}`;
-                    break;
-                }
-                const expectedString = typeof expected === 'string' ? expected : null;
-                const actualString = compareString(actual);
-                if (expectedString !== null && actualString !== null) {
-                    success = actualString === expectedString;
-                    rawValue = actualString;
-                    observedValue = actualString;
-                    reason = success ? 'value matches expected value' : `expected value=${expectedString} but observed ${actualString}`;
-                }
-                else {
-                    reason = 'value state unavailable';
-                }
-                break;
+            if (!matched && selector) {
+                matched = ToolsInteract._findFirstMatchingElement(elements, selector);
             }
-            case 'selected': {
-                const expectedBool = typeof expected === 'boolean' ? expected : null;
-                const expectedString = typeof expected === 'string'
-                    ? expected
-                    : expected && typeof expected === 'object'
-                        ? String(expected.id ?? expected.label ?? '')
-                        : null;
-                if (!observedState || observedState.selected === undefined || observedState.selected === null) {
-                    reason = 'selected state unavailable';
+            if (!matched) {
+                lastReason = 'element not found';
+                lastFailureCode = 'ELEMENT_NOT_FOUND';
+                stableCount = 0;
+                recordTraceStep('resolve', 'retry', {
+                    selector: selector ?? null,
+                    element_id: lastResolvedElementId,
+                    matched: false,
+                    reason: lastReason,
+                    attempt: attempts
+                });
+                recordTraceStep('stabilize', 'retry', {
+                    stabilization_attempts: attempts,
+                    stable_observation_count: stableCount,
+                    snapshot_freshness_ms: treeAgeMs,
+                    reason: lastReason
+                });
+                await sleep(pollDelay);
+                continue;
+            }
+            const resolvedElement = ToolsInteract._resolvedTargetFromElement(ToolsInteract._computeElementId(treePlatform, treeDeviceId, matched.el, matched.idx), matched.el, matched.idx);
+            lastResolvedElementId = resolvedElement.elementId;
+            lastObservedElement = { ...resolvedElement, state: matched.el.state ?? null };
+            if (treeAgeMs !== null && treeAgeMs > staleThreshold) {
+                lastReason = 'stale snapshot';
+                lastFailureCode = 'UNKNOWN';
+                stableCount = 0;
+                recordTraceStep('resolve', 'retry', {
+                    selector: selector ?? null,
+                    element_id: lastResolvedElementId,
+                    matched: true,
+                    reason: lastReason,
+                    attempt: attempts
+                });
+                recordTraceStep('stabilize', 'retry', {
+                    stabilization_attempts: attempts,
+                    stable_observation_count: stableCount,
+                    snapshot_freshness_ms: treeAgeMs,
+                    reason: lastReason
+                });
+                await sleep(pollDelay);
+                continue;
+            }
+            if (!resolveRecorded) {
+                recordTraceStep('resolve', 'success', {
+                    selector: selector ?? null,
+                    element_id: lastResolvedElementId,
+                    matched: true,
+                    reason: 'element resolved'
+                });
+                resolveRecorded = true;
+            }
+            const observedState = matched.el.state ?? null;
+            const actual = observedState?.[property] ?? null;
+            let success = false;
+            let reason = '';
+            let rawValue = null;
+            let observedValue = actual;
+            switch (property) {
+                case 'checked':
+                case 'focused':
+                case 'expanded':
+                case 'enabled': {
+                    const expectedBool = compareBoolean(expected);
+                    const actualBool = compareBoolean(actual);
+                    if (expectedBool === null) {
+                        reason = `expected ${property} must be boolean`;
+                    }
+                    else if (actualBool === null) {
+                        reason = `${property} state unavailable`;
+                    }
+                    else {
+                        rawValue = actualBool;
+                        success = actualBool === expectedBool;
+                        reason = success ? `${property} matches expected value` : `expected ${property}=${expectedBool} but observed ${actualBool}`;
+                    }
+                    observedValue = actualBool;
                     break;
                 }
-                if (expectedBool !== null) {
-                    const actualBool = typeof observedState.selected === 'boolean' ? observedState.selected : null;
-                    if (actualBool === null) {
-                        reason = 'selected state is not boolean';
+                case 'value':
+                case 'raw_value': {
+                    const expectedNumber = compareNumber(expected);
+                    const actualNumber = compareNumber(actual);
+                    if (expectedNumber !== null && actualNumber !== null) {
+                        success = actualNumber === expectedNumber;
+                        rawValue = actualNumber;
+                        observedValue = actualNumber;
+                        reason = success ? 'value matches expected value' : `expected value=${expectedNumber} but observed ${actualNumber}`;
                         break;
                     }
-                    rawValue = actualBool;
-                    observedValue = actualBool;
-                    success = actualBool === expectedBool;
-                    reason = success ? 'selected matches expected value' : `expected selected=${expectedBool} but observed ${actualBool}`;
+                    const expectedString = typeof expected === 'string' ? expected : null;
+                    const actualString = compareString(actual);
+                    if (expectedString !== null && actualString !== null) {
+                        success = actualString === expectedString;
+                        rawValue = actualString;
+                        observedValue = actualString;
+                        reason = success ? 'value matches expected value' : `expected value=${expectedString} but observed ${actualString}`;
+                    }
+                    else {
+                        reason = 'value state unavailable';
+                    }
                     break;
                 }
-                const actualSelected = typeof observedState.selected === 'object' && observedState.selected !== null
-                    ? String(observedState.selected.id ?? observedState.selected.label ?? '')
-                    : String(observedState.selected);
-                const actualString = actualSelected.trim();
-                if (!expectedString) {
-                    reason = 'expected selected must be boolean, string, or object with id/label';
+                case 'selected': {
+                    const expectedBool = typeof expected === 'boolean' ? expected : null;
+                    const expectedString = typeof expected === 'string'
+                        ? expected
+                        : expected && typeof expected === 'object'
+                            ? String(expected.id ?? expected.label ?? '')
+                            : null;
+                    if (!observedState || observedState.selected === undefined || observedState.selected === null) {
+                        reason = 'selected state unavailable';
+                        break;
+                    }
+                    if (expectedBool !== null) {
+                        const actualBool = typeof observedState.selected === 'boolean' ? observedState.selected : null;
+                        if (actualBool === null) {
+                            reason = 'selected state is not boolean';
+                            break;
+                        }
+                        rawValue = actualBool;
+                        observedValue = actualBool;
+                        success = actualBool === expectedBool;
+                        reason = success ? 'selected matches expected value' : `expected selected=${expectedBool} but observed ${actualBool}`;
+                        break;
+                    }
+                    const actualSelected = typeof observedState.selected === 'object' && observedState.selected !== null
+                        ? String(observedState.selected.id ?? observedState.selected.label ?? '')
+                        : String(observedState.selected);
+                    const actualString = actualSelected.trim();
+                    if (!expectedString) {
+                        reason = 'expected selected must be boolean, string, or object with id/label';
+                        break;
+                    }
+                    rawValue = actualString;
+                    observedValue = actualString;
+                    success = actualString === expectedString;
+                    reason = success ? 'selected matches expected value' : `expected selected=${expectedString} but observed ${actualString}`;
                     break;
                 }
-                rawValue = actualString;
-                observedValue = actualString;
-                success = actualString === expectedString;
-                reason = success ? 'selected matches expected value' : `expected selected=${expectedString} but observed ${actualString}`;
-                break;
-            }
-            case 'text_value': {
-                const expectedString = typeof expected === 'string' ? expected : null;
-                const actualString = compareString(actual);
-                if (!expectedString) {
-                    reason = 'expected text_value must be string';
-                }
-                else if (!actualString) {
-                    reason = 'text_value state unavailable';
+                case 'text_value': {
+                    const expectedString = typeof expected === 'string' ? expected : null;
+                    const actualString = compareString(actual);
+                    if (!expectedString) {
+                        reason = 'expected text_value must be string';
+                    }
+                    else if (!actualString) {
+                        reason = 'text_value state unavailable';
+                    }
+                    else {
+                        success = actualString === expectedString;
+                        rawValue = actualString;
+                        observedValue = actualString;
+                        reason = success ? 'text_value matches expected value' : `expected text_value=${expectedString} but observed ${actualString}`;
+                    }
+                    break;
                 }
-                else {
-                    success = actualString === expectedString;
-                    rawValue = actualString;
-                    observedValue = actualString;
-                    reason = success ? 'text_value matches expected value' : `expected text_value=${expectedString} but observed ${actualString}`;
+                default: {
+                    if (actual !== null && actual !== undefined) {
+                        success = actual === expected;
+                        observedValue = actual;
+                        rawValue = typeof actual === 'string' || typeof actual === 'number' || typeof actual === 'boolean' ? actual : null;
+                        reason = success ? `${property} matches expected value` : `expected ${property} to match but observed ${String(actual)}`;
+                    }
+                    else {
+                        reason = `unsupported or unavailable state property: ${property}`;
+                    }
                 }
-                break;
             }
-            default: {
-                if (actual !== null && actual !== undefined) {
-                    success = actual === expected;
-                    observedValue = actual;
-                    rawValue = typeof actual === 'string' || typeof actual === 'number' || typeof actual === 'boolean' ? actual : null;
-                    reason = success ? `${property} matches expected value` : `expected ${property} to match but observed ${String(actual)}`;
-                }
-                else {
-                    reason = `unsupported or unavailable state property: ${property}`;
+            if (success) {
+                stableCount++;
+                recordTraceStep('stabilize', 'success', {
+                    stabilization_attempts: attempts,
+                    stable_observation_count: stableCount,
+                    snapshot_freshness_ms: treeAgeMs,
+                    reason
+                });
+                recordTraceStep('verify', 'success', {
+                    property,
+                    expected,
+                    observed_value: observedValue,
+                    reason
+                });
+                if (stableCount >= stableTarget) {
+                    return {
+                        success: true,
+                        selector,
+                        element_id: lastResolvedElementId,
+                        expected_state: { property, expected },
+                        element: lastObservedElement,
+                        observed_state: {
+                            property,
+                            value: observedValue,
+                            ...(rawValue !== null ? { raw_value: rawValue } : {})
+                        },
+                        reason,
+                        stabilization_attempts: attempts,
+                        stabilization_window_ms: Date.now() - start,
+                        stable_observation_count: stableCount,
+                        snapshot_freshness_ms: treeAgeMs ?? undefined,
+                        trace: buildStateTrace('success')
+                    };
                 }
             }
-        }
-        if (!success && !reason) {
-            reason = `${property} did not match expected value`;
+            else {
+                stableCount = 0;
+                lastReason = reason || lastReason;
+                lastFailureCode = 'UNKNOWN';
+                recordTraceStep('stabilize', 'retry', {
+                    stabilization_attempts: attempts,
+                    stable_observation_count: stableCount,
+                    snapshot_freshness_ms: treeAgeMs,
+                    reason: lastReason
+                });
+                recordTraceStep('verify', 'retry', {
+                    property,
+                    expected,
+                    observed_value: observedValue,
+                    reason: lastReason
+                });
+            }
+            if (!success) {
+                lastObservedValue = observedValue;
+                lastRawValue = rawValue;
+            }
+            await sleep(pollDelay);
         }
         return {
-            success,
+            success: false,
             selector,
-            element_id: element_id ?? resolvedElement.elementId,
+            element_id: lastResolvedElementId,
             expected_state: { property, expected },
-            element: {
-                ...resolvedElement,
-                state: observedState
-            },
+            element: lastObservedElement,
             observed_state: {
                 property,
-                value: observedValue,
-                ...(rawValue !== null ? { raw_value: rawValue } : {})
+                value: lastObservedValue,
+                ...(lastRawValue !== null ? { raw_value: lastRawValue } : {})
             },
-            reason,
-            ...(success ? {} : { failure_code: 'UNKNOWN', retryable: false })
+            reason: lastReason,
+            failure_code: lastFailureCode,
+            retryable: true,
+            trace: buildStateTrace('failure')
         };
     }
     static async waitForUICore({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {