mobile-debug-mcp 0.32.2 → 0.33.0

package/src/server/common.ts

@@ -1,3 +1,4 @@
+import { currentEvidenceActionId } from '../observe/evidence.js'
 import { recordTiming } from '../utils/timing.js'
 import type {
   ActionTrace,
@@ -11,6 +12,7 @@ import type {
   TraceStep
 } from '../types.js'
 import { ToolsObserve } from '../observe/index.js'
+import { isConditionBlocked } from '../interact/conditional-action.js'
 
 export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3
 export const DEFAULT_MAX_RETRY_DEPTH = 3
@@ -87,11 +89,14 @@ export function getArrayArg<T>(args: ToolCallArgs, key: string): T[] | undefined
 let actionSequence = 0
 
 export function nextActionId(actionType: string, timestamp: number) {
+  const current = currentEvidenceActionId()
+  if (current) return current
   actionSequence += 1
   return `${actionType}_${timestamp}_${actionSequence}`
 }
 
 export async function captureActionFingerprint(platform?: 'android' | 'ios', deviceId?: string): Promise<string | null> {
+  if (isConditionBlocked()) return null
   if (!platform) return null
   try {
     const result = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as any
@@ -317,6 +322,8 @@ function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
     case 'STALE_REFERENCE':
       return 'TargetResolutionFailure'
     case 'ELEMENT_NOT_INTERACTABLE':
+    case 'PRECONDITION_FAILED':
+    case 'PRECONDITION_UNAVAILABLE':
     case 'ACTION_TIMEOUT':
       return 'ExecutionFailure'
     case 'TIMEOUT':

package/src/server/condition-schema.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+export const conditionalTools = new Set(['tap', 'tap_element', 'swipe', 'type_text', 'press_back'])
+export const expectedStateSchema = z.object({
+  snapshotSessionId: z.string().min(1),
+  snapshotRevision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  timeoutMs: z.number().int().min(100).max(60000).optional()
+}).strict()
+
+export type ExpectedState = z.infer<typeof expectedStateSchema>
+
+export const expectedStateJson = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    snapshotSessionId: { type: 'string', minLength: 1 },
+    snapshotRevision: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER },
+    timeoutMs: { type: 'integer', minimum: 100, maximum: 60000, default: 15000 }
+  },
+  required: ['snapshotSessionId', 'snapshotRevision']
+}
+
+export function validateExpectedState(name: string, args: Record<string, unknown>): ExpectedState | undefined {
+  if (args.expectedState === undefined) return undefined
+  if (!conditionalTools.has(name)) throw new Error('INVALID_ARGUMENT: expectedState is not supported on this tool')
+  const parsed = expectedStateSchema.safeParse(args.expectedState)
+  if (!parsed.success) throw new Error('INVALID_ARGUMENT: invalid expectedState')
+  if ((args.platform !== 'android' && args.platform !== 'ios') ||
+      typeof args.deviceId !== 'string' || !args.deviceId.trim() ||
+      ['booted', 'default'].includes(args.deviceId)) throw new Error('INVALID_ARGUMENT: expectedState requires an explicit platform and concrete deviceId')
+  if (['type_text', 'press_back'].includes(name) && args.platform !== 'android') throw new Error('INVALID_ARGUMENT: this action supports only Android')
+  return parsed.data
+}

package/src/server/journey-schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { expectedStateSchema, expectedStateJson } from './condition-schema.js'
 
 const selector = z.object({
   text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
@@ -23,7 +24,7 @@ const assertion = z.union([
 const id = z.string().min(1)
 const step = z.union([
   z.object({ id, type: z.literal('start_app'), appId: z.string().min(1), verificationMode: verificationMode.optional() }).strict(),
-  z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional() }).strict().refine(exactlyOneTarget),
+  z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional(), expectedState: expectedStateSchema.optional() }).strict().refine(exactlyOneTarget),
   z.object({ id, type: z.literal('wait'), selector, condition: z.enum(['exists', 'not_exists', 'visible', 'clickable']).optional(), timeoutMs, pollIntervalMs }).strict(),
   z.object({ id, type: z.literal('assert'), assertion, timeoutMs, pollIntervalMs }).strict()
 ])
@@ -49,7 +50,7 @@ const objectJson = (properties: Record<string, unknown>, required: string[], ext
 export const journeyStepsJson = {
   type: 'array', minItems: 1, maxItems: 50, items: { oneOf: [
     objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'start_app' }, appId: { type: 'string', minLength: 1 }, verificationMode: modeJson }, ['id', 'type', 'appId']),
-    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson,
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson, expectedState: expectedStateJson,
       waitFor: objectJson({ ...intervalJson, timeoutMs: { type: 'integer', minimum: 100, maximum: 10000 }, condition: { enum: ['exists', 'visible', 'clickable'] }, match: objectJson({ index: { type: 'integer', minimum: 0 } }, []) }, [])
     }, ['id', 'type'], { oneOf: oneTargetJson }),
     objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'wait' }, selector: selectorJson, condition: { enum: ['exists', 'not_exists', 'visible', 'clickable'] }, ...intervalJson }, ['id', 'type', 'selector']),

package/src/server/readiness-schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod'
+const timeout = z.number().int().min(100).max(60000)
+export const readinessSchema = z.object({
+  platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
+  timeoutMs: timeout.optional(), stabilityMs: z.number().int().min(100).max(10000).optional()
+}).strict()
+export const readinessWaitSchema = readinessSchema.extend({ pollIntervalMs: z.number().int().min(100).max(1000).optional() }).strict()
+export const readinessPropertiesJson = {
+  platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 },
+  timeoutMs: { type: 'integer', minimum: 100, maximum: 60000 },
+  stabilityMs: { type: 'integer', minimum: 100, maximum: 10000, default: 500 }
+}

package/src/server/tool-definitions.ts

@@ -1,6 +1,17 @@
 import { journeyStepsJson } from './journey-schema.js'
+import { conditionalTools, expectedStateJson } from './condition-schema.js'
+import { readinessPropertiesJson } from './readiness-schema.js'
 
 export const toolDefinitions: any[] = [
+  ...['get_app_readiness', 'wait_for_app_ready'].map(name => ({
+    name,
+    description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Unresponsive/debugger-paused detection is unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
+    inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: {
+      ...readinessPropertiesJson,
+      timeoutMs: { ...readinessPropertiesJson.timeoutMs, default: name === 'get_app_readiness' ? 15000 : 30000 },
+      ...(name === 'wait_for_app_ready' ? { pollIntervalMs: { type: 'integer', minimum: 100, maximum: 1000, default: 500 } } : {})
+    } }
+  })),
   {
     name: 'start_app',
     description: `Purpose:
@@ -1130,6 +1141,26 @@ Returns { requests: [], count: 0 } when no credible network signals are found.`,
 
 // Keep the additive execution controls consistent across all action tools.
 for (const tool of toolDefinitions) {
+  if (['wait_for_ui', 'wait_for_ui_change'].includes(tool.name)) {
+    tool.inputSchema.properties.requireReady = { type: 'boolean', default: false }
+    tool.description += '\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.'
+  }
+  if (tool.name === 'get_ui_tree') tool.description += '\nSuccessful observations include snapshot_session_id and snapshot_revision for same-device conditional input. Compact errors preserve the error and cannot authorize an expectation.'
+  if (tool.name === 'run_journey') tool.description += '\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence even in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.'
+  if (conditionalTools.has(tool.name)) {
+    tool.inputSchema.properties.expectedState = expectedStateJson
+    tool.inputSchema.properties.platform ??= { type: 'string', enum: ['android'] }
+    tool.inputSchema.allOf = [...(tool.inputSchema.allOf ?? []), {
+      if: { required: ['expectedState'] },
+      then: { required: ['platform', 'deviceId'], properties: {
+        platform: { enum: ['type_text', 'press_back'].includes(tool.name) ? ['android'] : ['android', 'ios'] },
+        deviceId: { type: 'string', minLength: 1, pattern: '\\S', not: { enum: ['booted', 'default'] } }
+      } }
+    }]
+    tool.description += '\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.'
+  } else {
+    tool.inputSchema.allOf = [...(tool.inputSchema.allOf ?? []), { not: { required: ['expectedState'] } }]
+  }
   if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back'].includes(tool.name)) {
     Object.assign(tool.inputSchema.properties, {
       verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
@@ -1148,3 +1179,16 @@ for (const tool of toolDefinitions) {
     } }
   })
 }
+
+// Correlation is explicit; an omitted reference creates an independent observation.
+for (const tool of toolDefinitions) {
+  if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream'].includes(tool.name)) {
+    Object.assign(tool.inputSchema.properties, { actionRef: {
+      type: 'object', additionalProperties: false, required: ['sessionId', 'actionId'], properties: {
+        sessionId: { type: 'string', minLength: 1, maxLength: 128 },
+        actionId: { type: 'string', minLength: 1, maxLength: 128 }
+      }
+    } })
+    tool.description += '\nReturns evidence metadata with acquisition intervals and conservative freshness. Optional actionRef links a known same-session/device action; unavailable references collect independently. Device log times are not comparable with host dispatch times.'
+  }
+}

package/src/server/tool-handlers.ts

@@ -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 type {
   InstallAppResponse,
@@ -76,17 +81,42 @@ function compactAction(result: any, verificationMode: VerificationMode, started
   }
 }
 
+function correlatedHandler(name: string, handler: ToolHandler, action = false, journey = false): ToolHandler {
+  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: string, execute: ToolHandler): ToolHandler {
-  return async (args) => {
+  return correlatedHandler(type, async (args) => {
     const timing: Record<string, number> = {}
     return withTiming(timing, async () => {
     const started = performance.now()
     const controls = interactionControls(args)
+    const expected = validateExpectedState(type, args)
+    const condition = expected ? createConditionalAction(args.platform as PlatformArg, args.deviceId as string, expected) : undefined
     const budgetMs = controls.actionTimeoutMs ?? ({ start_app: 10000, restart_app: 15000, scroll_to_element: 10000 }[type] ?? 5000)
     let dispatchStarted = false
     let result: any
     const dispatchWithBudget = (timeoutMs: number) => runWithBudget(timeoutMs, async (budget) => {
-      try { return payloadOf(await execute(args)) }
+      try {
+        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 }
     })
     try {
@@ -95,13 +125,24 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
         ? await dispatchWithBudget(Infinity) : await dispatchWithBudget(budgetMs)
       if (result.success) dispatchStarted = true
     } catch (error) {
-      if (controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error))) return wrapToolError(type, 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 as string | undefined,
@@ -117,6 +158,7 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
       const tree = await withObservationContext({ stepId: args._stepId as string | undefined, purpose: 'verification' }, () =>
         measure('post_observation_ms', () => runWithBudget(controls.verificationTimeoutMs, () =>
           ToolsObserve.getUITreeHandler({ platform: (args.platform as PlatformArg | undefined) ?? result.device?.platform, deviceId: (args.deviceId as string | undefined) ?? result.device?.id })))).catch(() => null) as any
+      markEvidenceVerification()
       observationAvailable = !!tree && !tree.error
       recordObservationEvent({
         verification_budget_ms: controls.verificationTimeoutMs,
@@ -126,10 +168,18 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
       })
       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 } } : {})
     }
@@ -138,7 +188,7 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
       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)
@@ -155,7 +205,7 @@ async function executeStartApp(args: ToolCallArgs) {
   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({
@@ -194,7 +244,7 @@ async function executeRestartApp(args: ToolCallArgs) {
   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
@@ -425,10 +475,12 @@ async function handleAdjustControl(args: ToolCallArgs) {
     platform,
     deviceId
   })
+  markEvidenceVerification()
   return wrapResponse(res)
 }
 
 async function handleWaitForUI(args: ToolCallArgs) {
+  if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean') throw new Error('INVALID_ARGUMENT: requireReady must be boolean')
   const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
   const condition = (getStringArg(args, 'condition') as 'exists' | 'not_exists' | 'visible' | 'clickable' | undefined) ?? 'exists'
   const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000
@@ -437,11 +489,14 @@ async function handleWaitForUI(args: ToolCallArgs) {
   const retry = getObjectArg<WaitForUiRetryArg>(args, 'retry')
   const platform = getStringArg(args, 'platform') as PlatformArg | undefined
   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 as PlatformArg, 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: ToolCallArgs) {
+  if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean') throw new Error('INVALID_ARGUMENT: requireReady must be boolean')
   const platform = getStringArg(args, 'platform') as PlatformArg | undefined
   const deviceId = getStringArg(args, 'deviceId')
   const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000
@@ -449,7 +504,9 @@ async function handleWaitForUIChange(args: ToolCallArgs) {
   const expected_change = getStringArg(args, 'expected_change') as 'hierarchy_diff' | 'text_change' | 'state_change' | undefined
   const scope = getStringArg(args, 'scope') as 'screen' | 'subtree' | undefined
   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 as PlatformArg, 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)
 }
 
@@ -472,7 +529,7 @@ async function executeTap(args: ToolCallArgs) {
   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({
@@ -498,14 +555,15 @@ async function executeTapElement(args: ToolCallArgs) {
   if (selector) {
     const waitFor = getObjectArg<WaitForUiMatchArg>(args, 'waitFor') as any
     const targetStarted = performance.now()
+    const resolutionTimeoutMs = waitFor?.timeoutMs ?? actionTimeoutMs ?? 5000
     const resolution = await withObservationContext({ stepId: args._stepId as string | undefined, 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') as PlatformArg | undefined, deviceId: getStringArg(args, 'deviceId') })))) as any
+      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') as PlatformArg | undefined, deviceId: getStringArg(args, 'deviceId') })))) as any
     recordObservationEvent({ step_id: args._stepId as string | undefined, 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 as string | undefined)
   const res = await measure('dispatch_ms', () => ToolsInteract.tapElementHandler({ elementId: resolvedId!, freshTree, verificationMode, timeoutMs: actionTimeoutMs, platform: getStringArg(args, 'platform') as PlatformArg | undefined, deviceId: getStringArg(args, 'deviceId') })) as any
   return wrapResponse(res)
@@ -598,7 +656,8 @@ async function handleRunJourney(args: ToolCallArgs) {
     if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? '')) 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
@@ -608,6 +667,7 @@ async function handleRunJourney(args: ToolCallArgs) {
       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) { pending.state_delta = delta; pending.state_delta_available = true }
@@ -630,6 +690,7 @@ async function handleRunJourney(args: ToolCallArgs) {
   for (const step of results) for (const [key, value] of Object.entries(step.result?.timing ?? {})) {
     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')
   })
 }
@@ -644,7 +705,7 @@ async function executeSwipe(args: ToolCallArgs) {
   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({
@@ -668,7 +729,7 @@ async function executeScrollToElement(args: ToolCallArgs) {
   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({
@@ -697,7 +758,7 @@ async function executeTypeText(args: ToolCallArgs) {
   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({
@@ -716,7 +777,7 @@ async function executePressBack(args: ToolCallArgs) {
   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({
@@ -781,6 +842,16 @@ async function handleGetNetworkActivity(args: ToolCallArgs) {
 }
 
 export const toolHandlers: Record<string, ToolHandler> = {
+  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,
@@ -818,6 +889,10 @@ export const toolHandlers: Record<string, ToolHandler> = {
   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: string, args: ToolCallArgs = {}) {
   const handler = toolHandlers[name]
   if (!handler) throw new Error(`Unknown tool: ${name}`)
@@ -838,6 +913,7 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}) {
   }
   return withTiming(measured, async () => {
     try {
+      validateExpectedState(name, args)
       return addTiming(await handler(args))
     } catch (error) {
       console.error(`Error executing tool ${name}:`, error)

package/src/server-core.ts

@@ -16,7 +16,7 @@ export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.32.2'
+  version: '0.33.0'
 }
 
 export function createServer() {

package/src/types.ts

@@ -218,6 +218,7 @@ export interface UIElement {
 }
 
 export interface GetUITreeResponse {
+  readiness?: ReadinessSummary;
   device: DeviceInfo;
   screen: string;
   resolution: {
@@ -226,12 +227,27 @@ export interface GetUITreeResponse {
   };
   elements: UIElement[];
   snapshot_revision: number;
+  snapshot_session_id?: string;
   captured_at_ms: number;
   snapshot_delta?: SnapshotDelta | null;
   loading_state?: LoadingState | null;
   error?: string;
 }
 
+export interface ReadinessSummary {
+  state: 'loading' | 'transitioning' | 'settled' | 'unknown' | 'unresponsive' | 'debugger_paused';
+  scope: 'device_ui';
+  basis: 'observed' | 'heuristic' | 'insufficient';
+  captured_at_ms: number | null;
+  sample_count: number;
+  stable_for_ms: number;
+  snapshot_session_id: string | null;
+  snapshot_revision: number | null;
+  evidence: Array<{ code: string; source: string; captured_at_ms: number | null; snapshot_revision: number | null }>;
+  limitations: string[];
+  capabilities: { loading: boolean; transitioning: boolean; settled: boolean; unresponsive: boolean; debugger_paused: boolean };
+}
+
 export interface GetCurrentScreenResponse {
   device: DeviceInfo;
   package: string;
@@ -289,6 +305,8 @@ export interface TapResponse {
 }
 
 export type ActionFailureCode =
+  | 'PRECONDITION_FAILED'
+  | 'PRECONDITION_UNAVAILABLE'
   | 'ELEMENT_NOT_FOUND'
   | 'ELEMENT_NOT_INTERACTABLE'
   | 'TIMEOUT'
@@ -417,6 +435,15 @@ export interface TimingBreakdown {
   serialization_ms?: number;
 }
 
+export interface ActionConditionResult {
+  status: 'matched' | 'mismatch' | 'unavailable' | 'not_checked';
+  expected: { snapshot_session_id: string; snapshot_revision: number };
+  observed: GetUITreeResponse | null;
+  elapsed_ms: number;
+  reason?: 'BASELINE_UNAVAILABLE' | 'SESSION_MISMATCH' | 'DEVICE_MISMATCH' |
+    'OBSERVATION_FAILED' | 'OBSERVATION_INVALID' | 'CONDITION_TIMEOUT' | 'ACTION_NOT_REACHED';
+}
+
 export interface ActionExecutionResult {
   action_id: string;
   timestamp: string;
@@ -435,6 +462,7 @@ export interface ActionExecutionResult {
   dispatch_started?: boolean;
   verification?: { mode: 'none' | 'light' | 'full'; status: 'not_requested' | 'observed' | 'verified' | 'unavailable' | 'failed' };
   state_delta?: StateDelta;
+  condition?: ActionConditionResult;
   timing?: TimingBreakdown;
   recovery?: RecoveryState;
   trace: ActionTrace;
@@ -535,6 +563,7 @@ export interface AdjustControlResponse extends ActionExecutionResult {
 }
 
 export interface WaitForUIChangeResponse {
+  readiness?: ReadinessSummary;
   success: boolean;
   observed_change: 'hierarchy_diff' | 'text_change' | 'state_change' | null;
   snapshot_revision?: number;
@@ -554,7 +583,7 @@ export interface WaitForUIChangeResponse {
   reason?: string;
   loading_state?: LoadingState | null;
   error?: {
-    code: 'INVALID_SCOPE' | 'ELEMENT_NOT_FOUND';
+    code: 'INVALID_SCOPE' | 'ELEMENT_NOT_FOUND' | 'TIMEOUT' | 'DEVICE_UNAVAILABLE';
     message: string;
   };
 }

package/src/utils/ios/utils.ts

@@ -62,7 +62,7 @@ export async function isIDBInstalled(): Promise<boolean> {
   const cmd = getIdbCmd()
   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: unknown) {
     console.debug(`[isIDBInstalled] idb probe failed for '${cmd}': ${e instanceof Error ? e.message : String(e)}`)
@@ -200,7 +200,7 @@ export async function findAppBundle(dir: string): Promise<string | undefined> {
 export async function getIOSDeviceMetadata(deviceId: string = "booted"): Promise<DeviceInfo> {
   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: DeviceInfo = {
         platform: "ios",
         id: deviceId,
@@ -247,7 +247,7 @@ export async function getIOSDeviceMetadata(deviceId: string = "booted"): Promise
 export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
   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 {
         const data = JSON.parse(stdout)
@@ -256,7 +256,7 @@ export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
         const checks: Promise<void>[] = []
 
         // 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<string>()
           if (!err2 && stdout2) {
             try {

package/src/utils/operation-budget.ts

@@ -10,11 +10,31 @@ export function runWithBudget<T>(timeoutMs: number, operation: (budget: Operatio
 }
 export function remainingBudget(fallback = 0): number {
   const budget = budgets.getStore()
-  if (!budget || !Number.isFinite(budget.deadline)) return fallback
-  const remaining = Math.floor(budget.deadline - performance.now())
+  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(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<T>(timeoutMs: number, operation: () => Promise<T>): Promise<T> {
+  remainingBudget()
+  const action = budgets.getStore()
+  const started = performance.now()
+  const parent = action?.parent
+  const budget: OperationBudget = { 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()