mobile-debug-mcp 0.32.2 → 0.33.0

package/dist/server/tool-handlers.js

@@ -1,7 +1,12 @@
+import { withEvidence, currentEvidenceActionId, validateActionRef, markEvidenceVerification, refreshJourneyEvidence, completeJourneyVerification } from '../observe/evidence.js';
 import { measure, withTiming } from '../utils/timing.js';
 import { randomUUID } from 'node:crypto';
 import { runWithBudget } from '../utils/operation-budget.js';
 import { journeySchema, tapElementControlsSchema } from './journey-schema.js';
+import { readinessSchema, readinessWaitSchema } from './readiness-schema.js';
+import { getAppReadiness, withReadyWait } from '../observe/readiness-service.js';
+import { validateExpectedState } from './condition-schema.js';
+import { conditionFailureCode, createConditionalAction, notifyActionStart, withConditionalAction } from '../interact/conditional-action.js';
 import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js';
 import { AndroidManage, iOSManage, ToolsManage } from '../manage/index.js';
 import { ToolsInteract } from '../interact/index.js';
@@ -43,18 +48,45 @@ function compactAction(result, verificationMode, started = true, stateDelta, tot
         timing: { total_ms: totalMs }
     };
 }
-function actionHandler(type, execute) {
+function correlatedHandler(name, handler, action = false, journey = false) {
     return async (args) => {
+        const ref = validateActionRef(args.actionRef);
+        const { result, evidence } = await withEvidence({ action, journey, ref }, async () => {
+            try {
+                return await handler(args);
+            }
+            catch (error) {
+                return wrapToolError(name, error);
+            }
+        });
+        const item = result.content.find(item => item.type === 'text');
+        if (item?.text) {
+            const payload = JSON.parse(item.text);
+            payload.evidence = evidence;
+            item.text = JSON.stringify(payload);
+        }
+        return result;
+    };
+}
+function actionHandler(type, execute) {
+    return correlatedHandler(type, async (args) => {
         const timing = {};
         return withTiming(timing, async () => {
             const started = performance.now();
             const controls = interactionControls(args);
+            const expected = validateExpectedState(type, args);
+            const condition = expected ? createConditionalAction(args.platform, args.deviceId, expected) : undefined;
             const budgetMs = controls.actionTimeoutMs ?? ({ start_app: 10000, restart_app: 15000, scroll_to_element: 10000 }[type] ?? 5000);
             let dispatchStarted = false;
             let result;
             const dispatchWithBudget = (timeoutMs) => runWithBudget(timeoutMs, async (budget) => {
                 try {
-                    return payloadOf(await execute(args));
+                    if (!condition)
+                        return payloadOf(await execute(args));
+                    return await withConditionalAction(condition, async () => {
+                        const device = await resolveTargetDevice({ platform: condition.platform, deviceId: condition.deviceId });
+                        return withResolvedDevice(device, async () => payloadOf(await execute(args)));
+                    });
                 }
                 finally {
                     dispatchStarted = budget.dispatchStarted;
@@ -68,17 +100,28 @@ function actionHandler(type, execute) {
                     dispatchStarted = true;
             }
             catch (error) {
-                if (controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error)))
+                if (!condition && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error)))
                     return wrapToolError(type, error);
                 result = { success: false, failure_code: /TIMEOUT|timed out/i.test(String(error)) ? 'ACTION_TIMEOUT' : 'UNKNOWN', error: String(error) };
             }
+            const blocked = condition && ['mismatch', 'unavailable'].includes(condition.result.status);
+            if (blocked) {
+                dispatchStarted = false;
+                result = buildActionExecutionResult({
+                    actionType: type, sourceModule: 'server', device: condition.result.observed?.device,
+                    selector: result?.target?.selector ?? null, resolved: result?.target?.resolved,
+                    success: false, uiFingerprintBefore: result?.ui_fingerprint_before ?? null, uiFingerprintAfter: null,
+                    failure: { failureCode: conditionFailureCode(condition), retryable: false },
+                    traceSteps: [{ stage: 'verify', timestamp: Date.now(), result: 'failure', attempt_index: 0, metadata: { phase: 'precondition', dispatch_started: false } }]
+                });
+            }
             if (result.failure_code === 'TIMEOUT' || /ACTION_TIMEOUT|timeout/i.test(result.error ?? result.reason ?? result.details?.error ?? ''))
                 result.failure_code = 'ACTION_TIMEOUT';
             if (result.failure_code === 'ACTION_TIMEOUT')
                 result.retryable = !dispatchStarted;
             if (!result.success && typeof result.retryable !== 'boolean')
                 result.retryable = !dispatchStarted;
-            result.action_id ??= randomUUID();
+            result.action_id ??= currentEvidenceActionId() ?? randomUUID();
             result.action_type ??= type;
             recordObservationEvent({
                 step_id: args._stepId,
@@ -92,6 +135,7 @@ function actionHandler(type, execute) {
             if (result.success && controls.verificationMode === 'light') {
                 const verificationStarted = performance.now();
                 const tree = await withObservationContext({ stepId: args._stepId, purpose: 'verification' }, () => measure('post_observation_ms', () => runWithBudget(controls.verificationTimeoutMs, () => ToolsObserve.getUITreeHandler({ platform: args.platform ?? result.device?.platform, deviceId: args.deviceId ?? result.device?.id })))).catch(() => null);
+                markEvidenceVerification();
                 observationAvailable = !!tree && !tree.error;
                 recordObservationEvent({
                     verification_budget_ms: controls.verificationTimeoutMs,
@@ -102,11 +146,21 @@ function actionHandler(type, execute) {
                 if (observationAvailable && tree.device)
                     delta = ToolsObserve.getLatestStateDelta(tree.device.platform, tree.device.id) ?? undefined;
             }
+            if (!blocked && controls.verificationMode === 'full' && dispatchStarted)
+                markEvidenceVerification();
             const compact = compactAction(result, controls.verificationMode, dispatchStarted, delta, performance.now() - started);
+            if (blocked)
+                compact.verification.status = 'not_requested';
             if (result.success && controls.verificationMode === 'light' && !observationAvailable)
                 compact.verification.status = 'unavailable';
             const evidence = {
                 ...compact,
+                ...(condition ? { condition: controls.responseMode === 'compact' && condition.result.status === 'matched'
+                        ? { ...condition.result, observed: condition.result.observed ? {
+                                snapshot_session_id: condition.result.observed.snapshot_session_id,
+                                snapshot_revision: condition.result.observed.snapshot_revision,
+                                captured_at_ms: condition.result.observed.captured_at_ms
+                            } : null } : condition.result } : {}),
                 ...(controls.verificationMode === 'light' ? { state_delta_available: !!delta } : {}),
                 ...(result.success && controls.verificationMode === 'light' && !observationAvailable ? { verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true } } : {})
             };
@@ -115,7 +169,7 @@ function actionHandler(type, execute) {
                 effective_controls: { ...controls, actionTimeoutMs: args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined ? null : budgetMs, timeout_bound: !(args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined) }
             }, controls.responseMode === 'debug');
         });
-    };
+    }, true);
 }
 const handleStartApp = actionHandler('start_app', executeStartApp);
 const handleRestartApp = actionHandler('restart_app', executeRestartApp);
@@ -131,7 +185,7 @@ async function executeStartApp(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     const res = await measure('dispatch_ms', () => (platform === 'android' ? new AndroidManage().startApp(appId, deviceId, actionTimeoutMs ?? (verificationMode === 'full' && getStringArg(args, 'responseMode') === undefined && args._journey !== true ? undefined : 10000)) : new iOSManage().startApp(appId, deviceId, verificationMode === 'full')));
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     const result = buildActionExecutionResult({
@@ -168,7 +222,7 @@ async function executeRestartApp(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     const bounded = args._journey === true || verificationMode !== 'full' || args.responseMode !== undefined || actionTimeoutMs !== undefined;
     const res = await measure('dispatch_ms', () => (platform === 'android' ? new AndroidManage().restartApp(appId, deviceId, bounded, actionTimeoutMs ?? 15000) : new iOSManage().restartApp(appId, deviceId, verificationMode === 'full', bounded, actionTimeoutMs ?? 15000)));
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
@@ -381,9 +435,12 @@ async function handleAdjustControl(args) {
         platform,
         deviceId
     });
+    markEvidenceVerification();
     return wrapResponse(res);
 }
 async function handleWaitForUI(args) {
+    if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean')
+        throw new Error('INVALID_ARGUMENT: requireReady must be boolean');
     const selector = getObjectArg(args, 'selector');
     const condition = getStringArg(args, 'condition') ?? 'exists';
     const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
@@ -392,10 +449,13 @@ async function handleWaitForUI(args) {
     const retry = getObjectArg(args, 'retry');
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
-    const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId });
+    const execute = (targetPlatform = platform, targetId = deviceId) => ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform: targetPlatform, deviceId: targetId });
+    const res = args.requireReady === true ? await withReadyWait({ platform, deviceId }, timeout_ms, device => execute(device.platform, device.id), (code, elapsed, samples) => ({ status: 'timeout', error: { code, message: 'Readiness wait could not complete' }, metrics: { latency_ms: elapsed, poll_count: samples, attempts: samples ? 1 : 0 }, requested: { selector, condition, match }, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } })) : await execute();
     return wrapResponse(res);
 }
 async function handleWaitForUIChange(args) {
+    if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean')
+        throw new Error('INVALID_ARGUMENT: requireReady must be boolean');
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
     const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
@@ -403,7 +463,8 @@ async function handleWaitForUIChange(args) {
     const expected_change = getStringArg(args, 'expected_change');
     const scope = getStringArg(args, 'scope');
     const target = getStringArg(args, 'target');
-    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change, scope, target });
+    const execute = (targetPlatform = platform, targetId = deviceId) => ToolsInteract.waitForUIChangeHandler({ platform: targetPlatform, deviceId: targetId, timeout_ms, stability_window_ms, expected_change, scope, target });
+    const res = args.requireReady === true ? await withReadyWait({ platform, deviceId }, timeout_ms, device => execute(device.platform, device.id), (code, elapsed) => ({ success: false, timeout: true, observed_change: null, elapsed_ms: elapsed, reason: code, error: { code, message: 'Readiness wait could not complete' } })) : await execute();
     return wrapResponse(res);
 }
 async function handleFindElement(args) {
@@ -424,7 +485,7 @@ async function executeTap(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     const res = await measure('dispatch_ms', () => ToolsInteract.tapHandler({ platform, x, y, deviceId, timeoutMs: actionTimeoutMs }));
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     const result = buildActionExecutionResult({
@@ -450,14 +511,15 @@ async function executeTapElement(args) {
     if (selector) {
         const waitFor = getObjectArg(args, 'waitFor');
         const targetStarted = performance.now();
-        const resolution = await withObservationContext({ stepId: args._stepId, purpose: 'target' }, () => measure('target_resolution_ms', () => runWithBudget(waitFor?.timeoutMs ?? 1500, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: waitFor?.timeoutMs ?? 1500, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, platform: getStringArg(args, 'platform'), deviceId: getStringArg(args, 'deviceId') }))));
+        const resolutionTimeoutMs = waitFor?.timeoutMs ?? actionTimeoutMs ?? 5000;
+        const resolution = await withObservationContext({ stepId: args._stepId, purpose: 'target' }, () => measure('target_resolution_ms', () => runWithBudget(resolutionTimeoutMs, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: resolutionTimeoutMs, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, resolveTapTarget: true, platform: getStringArg(args, 'platform'), deviceId: getStringArg(args, 'deviceId') }))));
         recordObservationEvent({ step_id: args._stepId, purpose: 'target', target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: resolution.status });
         if (resolution.status !== 'success' || !resolution.element?.elementId)
             return wrapResponse({ success: false, action_type: 'tap_element', failure_code: resolution.error?.code ?? 'ELEMENT_NOT_FOUND', retryable: true });
         resolvedId = resolution.element.elementId;
         freshTree = resolution._tree;
     }
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     if (freshTree)
         recordObservationConsumer(freshTree, 'target', args._stepId);
     const res = await measure('dispatch_ms', () => ToolsInteract.tapElementHandler({ elementId: resolvedId, freshTree, verificationMode, timeoutMs: actionTimeoutMs, platform: getStringArg(args, 'platform'), deviceId: getStringArg(args, 'deviceId') }));
@@ -563,7 +625,8 @@ async function handleRunJourney(args) {
                 result.failure_code = 'ASSERTION_TIMEOUT';
             const success = !!result?.success;
             if (lightCoveredByAssertion) {
-                result.verification = { mode: 'light', status: success ? 'unavailable' : 'failed' };
+                result.verification = { mode: 'light', status: success ? 'unavailable' :
+                        (['mismatch', 'unavailable'].includes(result.condition?.status) ? 'not_requested' : 'failed') };
                 if (success) {
                     result.verification_diagnostic = { code: 'VERIFICATION_UNAVAILABLE', retryable: true };
                     pendingLightStep = results.length;
@@ -573,6 +636,8 @@ async function handleRunJourney(args) {
                 const pending = results[pendingLightStep].result;
                 if (typeof result?.observed?.matched_count === 'number') {
                     pending.verification.status = 'observed';
+                    if (pending.evidence)
+                        completeJourneyVerification(pending.evidence.action_id);
                     delete pending.verification_diagnostic;
                     const delta = ToolsObserve.getLatestStateDelta(platform, deviceId);
                     if (delta) {
@@ -602,6 +667,7 @@ async function handleRunJourney(args) {
                 if (key !== 'total_ms' && typeof value === 'number')
                     componentTiming[key] = (componentTiming[key] ?? 0) + value;
             }
+        refreshJourneyEvidence(results);
         return wrapResponse({ success: stoppedAt === null, stopped_at_step_id: stoppedAt, steps: results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...componentTiming, total_ms: performance.now() - started } }, responseMode === 'debug');
     });
 }
@@ -615,7 +681,7 @@ async function executeSwipe(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     const res = await measure('dispatch_ms', () => ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId, timeoutMs: actionTimeoutMs }));
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     const result = buildActionExecutionResult({
@@ -638,7 +704,7 @@ async function executeScrollToElement(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     const res = await measure('dispatch_ms', () => ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId }));
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     const result = buildActionExecutionResult({
@@ -666,7 +732,7 @@ async function executeTypeText(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     const res = await measure('dispatch_ms', () => ToolsInteract.typeTextHandler({ text, deviceId, timeoutMs: actionTimeoutMs }));
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
     const result = buildActionExecutionResult({
@@ -684,7 +750,7 @@ async function executePressBack(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     const res = await measure('dispatch_ms', () => ToolsInteract.pressBackHandler({ deviceId, timeoutMs: actionTimeoutMs }));
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
     const result = buildActionExecutionResult({
@@ -743,6 +809,18 @@ async function handleGetNetworkActivity(args) {
     return wrapResponse(result);
 }
 export const toolHandlers = {
+    get_app_readiness: async (args) => {
+        const parsed = readinessSchema.safeParse(args);
+        if (!parsed.success)
+            throw new Error('INVALID_ARGUMENT: invalid readiness arguments');
+        return wrapResponse(await getAppReadiness(parsed.data));
+    },
+    wait_for_app_ready: async (args) => {
+        const parsed = readinessWaitSchema.safeParse(args);
+        if (!parsed.success)
+            throw new Error('INVALID_ARGUMENT: invalid readiness arguments');
+        return wrapResponse(await getAppReadiness(parsed.data, true));
+    },
     start_app: handleStartApp,
     terminate_app: handleTerminateApp,
     restart_app: handleRestartApp,
@@ -779,6 +857,9 @@ export const toolHandlers = {
     classify_action_outcome: handleClassifyActionOutcome,
     get_network_activity: handleGetNetworkActivity
 };
+for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream', 'run_journey', 'adjust_control']) {
+    toolHandlers[name] = correlatedHandler(name, toolHandlers[name], name === 'adjust_control', name === 'run_journey');
+}
 export async function handleToolCall(name, args = {}) {
     const handler = toolHandlers[name];
     if (!handler)
@@ -801,6 +882,7 @@ export async function handleToolCall(name, args = {}) {
     };
     return withTiming(measured, async () => {
         try {
+            validateExpectedState(name, args);
             return addTiming(await handler(args));
         }
         catch (error) {

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.32.2'
+    version: '0.33.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/dist/utils/ios/utils.js

@@ -75,7 +75,7 @@ export async function isIDBInstalled() {
     if (!cmd)
         return false;
     try {
-        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: remainingBudget(5000), killSignal: 'SIGKILL' });
         return true;
     }
     catch (e) {
@@ -197,7 +197,7 @@ export async function findAppBundle(dir) {
 export async function getIOSDeviceMetadata(deviceId = "booted") {
     return new Promise((resolve) => {
         // If deviceId is provided (and not "booted"), attempt to find that device among booted simulators.
-        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err, stdout) => {
             const fallback = {
                 platform: "ios",
                 id: deviceId,
@@ -240,7 +240,7 @@ export async function getIOSDeviceMetadata(deviceId = "booted") {
 export async function listIOSDevices(appId) {
     return new Promise((resolve) => {
         // Query all devices and separately query booted devices to mark them
-        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err, stdout) => {
             if (err || !stdout)
                 return resolve([]);
             try {
@@ -249,7 +249,7 @@ export async function listIOSDevices(appId) {
                 const out = [];
                 const checks = [];
                 // Get booted devices set
-                execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err2, stdout2) => {
+                execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err2, stdout2) => {
                     const bootedSet = new Set();
                     if (!err2 && stdout2) {
                         try {

package/dist/utils/operation-budget.js

@@ -8,13 +8,35 @@ export function runWithBudget(timeoutMs, operation) {
 }
 export function remainingBudget(fallback = 0) {
     const budget = budgets.getStore();
-    if (!budget || !Number.isFinite(budget.deadline))
+    let deadline = budget?.deadline ?? Infinity;
+    for (let ancestor = budget?.parent; ancestor; ancestor = ancestor.parent)
+        deadline = Math.min(deadline, ancestor.deadline);
+    if (!Number.isFinite(deadline))
         return fallback;
-    const remaining = Math.floor(budget.deadline - performance.now());
+    const remaining = Math.floor(deadline - performance.now());
     if (remaining <= 0)
         throw new Error('ACTION_TIMEOUT');
     return fallback > 0 ? Math.min(fallback, remaining) : remaining;
 }
+// Pause only this action's budget. Any enclosing operation still bounds the read.
+export async function runWithSeparateBudget(timeoutMs, operation) {
+    remainingBudget();
+    const action = budgets.getStore();
+    const started = performance.now();
+    const parent = action?.parent;
+    const budget = { deadline: Math.min(parent?.deadline ?? Infinity, started + timeoutMs), dispatchStarted: false, parent };
+    try {
+        return await budgets.run(budget, async () => {
+            const result = await operation();
+            remainingBudget();
+            return result;
+        });
+    }
+    finally {
+        if (action)
+            action.deadline += performance.now() - started;
+    }
+}
 export function markDispatchStarted() {
     remainingBudget();
     let budget = budgets.getStore();

package/dist/utils/resolve-device.js

@@ -1,3 +1,4 @@
+import { bindEvidenceDevice } from '../observe/evidence.js';
 import { retainConnectedDeviceSnapshots } from '../observe/snapshot-metadata.js';
 import { measure } from './timing.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -37,9 +38,15 @@ export async function listDevices(platform, appId) {
 }
 const deviceContext = new AsyncLocalStorage();
 export function withResolvedDevice(device, operation) {
+    bindEvidenceDevice(device);
     return deviceContext.run(device, operation);
 }
 export async function resolveTargetDevice(opts) {
+    const device = await resolveDevice(opts);
+    bindEvidenceDevice(device);
+    return device;
+}
+async function resolveDevice(opts) {
     const { platform, appId, prefer, deviceId } = opts;
     const current = deviceContext.getStore();
     if (current && current.platform === platform && (!deviceId || current.id === deviceId))

package/docs/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## Unreleased
+- Made readiness unit-test polling time deterministic while retaining exact sample-count and timeout assertions, eliminating host timer-rounding flakes.
+- Isolated snapshot unit tests from physical device discovery and native handlers so they run without connected devices. Readiness deadline expiry now retains the last valid observation instead of intermittently resetting loading to unknown.
+
+## [0.33.0]
+- Fixed selector taps timing out before one normal Android UI-tree acquisition: a default single lookup now uses the action budget (5 seconds). Selector taps with exists/visible waits resolve actionable containers consistently with clickable waits; hidden/disabled labels remain protected. Acquisition timeouts retain `ACTION_TIMEOUT` instead of reporting a missing element.
+- Added correlated action/observation evidence, explicit `actionRef`, phase/acquisition timestamps, conservative freshness, and bounded metadata history. Journey steps share correlation IDs; snapshot components and stream reads retain their actual device scope. Device log times remain explicitly incomparable with host dispatch times; tracing is unsupported.
+- Added evidence-backed foreground UI readiness observations, bounded readiness waits, and opt-in `requireReady` for existing UI waits. Tree responses include single-sample readiness without extra reads. Unresponsive/debugger-paused signals are explicitly unsupported; iOS probes and metadata reads now respect active operation budgets.
+- Added optional conditional input to `tap`, `tap_element`, `swipe`, Android `type_text`/`press_back`, and journey tap steps. A fresh snapshot check at native dispatch blocks stale or uncheckable expectations and returns condition evidence, including fresh trees in compact failures.
+- Added process-scoped `snapshot_session_id` metadata to UI-tree responses so conditional expectations cannot be reused across server restarts. Successful repeated observations refresh retained revision history timestamps.
+
+## [0.32.4]
+- Removed the optional Android UI-tree bridge runtime and its APK build tooling. Android UI-tree reads use `uiautomator dump` through ADB.
+
 ## [0.32.2]
 - bug fix
 
@@ -26,7 +40,7 @@ All notable changes to the **Mobile Debug MCP** project will be documented in th
 ## [0.30.0]
 - Folded RFC 013 synchronization semantics into the main spec and aligned the interact docs with the shipped `wait_for_ui_change` behavior.
 - Updated `wait_for_ui_change` to use a 300ms stabilization default and to reset stabilization on new in-place mutations.
-- Validated the in-place UI mutation flow on the Modul8 emulator app, including a delayed state-change case.
+- Validated the in-place UI mutation flow on an Android emulator, including a delayed state-change case.
 
 ## [0.29.0]
 - Added empty resource handlers and declared the `resources` capability so Codex MCP discovery can complete the handshake against the published npm package.
@@ -57,7 +71,7 @@ All notable changes to the **Mobile Debug MCP** project will be documented in th
 - RFC-003 wait/synchronization contract with `snapshot_revision`, `captured_at_ms`, and `loading_state`
 - Added `wait_for_ui_change` for stable in-place UI mutations
 - Updated `get_ui_tree` and `capture_debug_snapshot` to surface snapshot metadata
-- Emulator-validated the new UI-change flow against the Modul8 app
+- Validated the new UI-change flow on an Android emulator
 
 ## [0.25.1]
 - Platform-native element identity metadata for UI targeting

package/docs/benchmarks/ui-tree-performance/README.md

@@ -50,9 +50,10 @@ The report commit SHAs are available locally as `codex/spec-019-baseline` and
 `codex/spec-019-candidate`; create clean, built checkouts of those refs to
 reproduce the paired measurement.
 
-For the opt-in Android bridge, run
-`LATENCY_DEVICE_ID=emulator-5554 node --import tsx test/device/automated/ui-tree-performance/bridge-probe.ts`.
-Its `bridge-probe.json` compares ten bridge and legacy reads, checks a network
+The historical `bridge-probe.json` compares ten bridge and legacy reads, checks a network
 update, and checks a timer that changes visually without emitting an
 accessibility event. The timer check catches a stale accessibility cache even
 when every bridge request calls `getRootInActiveWindow()`.
+The bridge APK source, generator, and build/install probe have been removed;
+this report is retained as historical evidence, not a runnable benchmark in
+the current checkout.

package/docs/specs/020-conditional-actions/intent.md

@@ -0,0 +1,62 @@
+# Intent: conditional actions
+
+Originator: repository maintainer (user in the current conversation).
+Date: 2026-10-29.
+Status: approved.
+
+## Original problem
+
+“Conditional actions: Check expected state immediately before acting; stop and
+return fresh evidence if it changed.”
+
+Source: user request in the current conversation, following adoption of the
+repository development process.
+
+## Desired outcome
+
+An MCP client can make an action conditional on an expected UI state. The server
+checks that expectation against a fresh observation of the same target device
+immediately before dispatching the action. If the expectation no longer holds,
+the server does not dispatch the action and returns fresh evidence so the client
+can reassess its next step.
+
+Affected users and systems: MCP clients/agents, interaction tool dispatch,
+state observation, and Android/iOS adapters for supported actions.
+
+## Observable success criteria
+
+- A matching expectation allows the requested action to proceed normally.
+- A mismatching expectation prevents dispatch and clearly reports that the
+  action was not performed, together with the newly observed state.
+- If the expected state cannot be checked reliably, the action is not dispatched;
+  the response explains the observation failure without inventing evidence.
+- The check and action target the same device.
+- A mismatch does not automatically retry the action or adopt the new state.
+- Existing calls without a condition preserve their behaviour.
+
+## Constraints and exclusions
+
+- Reuse existing action, observation, and response conventions where suitable.
+- Define precise supported conditions, actions, evidence, and platform coverage
+  in the spec after approval of this intent.
+- A pre-dispatch check cannot guarantee the UI remains unchanged between the
+  observation and native input delivery; do not claim atomic device execution.
+- Automatic replanning, rollback, and post-action success verification are
+  outside this feature's scope.
+- Preserve unrelated checkout changes.
+
+## Assumptions and open questions for specification
+
+- Proposed compatibility approach: conditions are optional on supported actions.
+- Determine the initial action set, including whether journey steps are covered.
+- Determine whether expectations use screen identity, element properties,
+  snapshot revisions, or a supported combination.
+- Define fresh mismatch evidence and how it is preserved in compact responses.
+- Existing screen fingerprints deliberately omit some changing values; assess
+  their suitability rather than assuming they detect every relevant state change.
+
+## Approval
+
+Approved by the originator in the current conversation on 2026-10-29: “yes”,
+in direct response to the complete intent summary and linked artifact. Approval
+covers the captured intent; specification approval remains a separate gate.