mobile-debug-mcp 0.32.4 → 0.34.0

package/test/unit/server/conditional_schema.test.ts

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict'
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv'
+import { toolDefinitions } from '../../../src/server/tool-definitions.js'
+import { conditionalTools, validateExpectedState } from '../../../src/server/condition-schema.js'
+import { journeySchema } from '../../../src/server/journey-schema.js'
+
+const provider = new AjvJsonSchemaValidator()
+const expectedState = { snapshotSessionId: 'session-fixture', snapshotRevision: 1 }
+for (const name of conditionalTools) {
+  const schema = toolDefinitions.find(tool => tool.name === name)!.inputSchema
+  const validate = provider.getValidator(schema)
+  const args = { platform: 'android', deviceId: 'emulator-5554', expectedState,
+    ...({ tap: { x: 1, y: 1 }, tap_element: { selector: { text: 'Go' } }, swipe: { x1: 1, y1: 1, x2: 2, y2: 2, duration: 100 }, type_text: { text: 'hello' }, press_back: {} }[name]) }
+  assert.equal(validate(args).valid, true, `${name} schema accepts valid guarded input`)
+  assert.deepEqual(validateExpectedState(name, args), expectedState)
+  for (const extra of [
+    { expectedState: null }, { expectedState: {} }, { expectedState: { ...expectedState, extra: true } },
+    { expectedState: { ...expectedState, snapshotRevision: 0 } }, { expectedState: { ...expectedState, snapshotRevision: 1.5 } },
+    { expectedState: { ...expectedState, snapshotRevision: Number.MAX_SAFE_INTEGER + 1 } },
+    { expectedState: { ...expectedState, snapshotSessionId: '' } }, { expectedState: { ...expectedState, timeoutMs: 99 } },
+    { expectedState: { ...expectedState, timeoutMs: 60001 } }, { expectedState: { ...expectedState, timeoutMs: '15000' } },
+    { platform: null }, { deviceId: 'booted' }, { deviceId: 'default' }, { deviceId: '' }, { deviceId: ' ' }
+  ]) {
+    const input = { ...args, ...extra }
+    assert.equal(validate(input).valid, false, JSON.stringify(input))
+    assert.throws(() => validateExpectedState(name, input), /INVALID_ARGUMENT/)
+  }
+  const withoutDevice: any = { ...args }; delete withoutDevice.deviceId
+  assert.equal(validate(withoutDevice).valid, false)
+  assert.throws(() => validateExpectedState(name, withoutDevice), /INVALID_ARGUMENT/)
+  const ios = { ...args, platform: 'ios', deviceId: 'concrete-udid' }
+  const supported = !['type_text', 'press_back'].includes(name)
+  assert.equal(validate(ios).valid, supported)
+  if (supported) assert.deepEqual(validateExpectedState(name, ios), expectedState)
+  else assert.throws(() => validateExpectedState(name, ios), /INVALID_ARGUMENT/)
+}
+for (const name of ['start_app', 'restart_app', 'terminate_app', 'reset_app_data', 'scroll_to_element', 'adjust_control', 'get_ui_tree']) {
+  const schema = toolDefinitions.find(tool => tool.name === name)!.inputSchema
+  const args = { platform: 'android', deviceId: 'emulator-5554', appId: 'example.app', selector: { text: 'Go' }, targetValue: 1, expectedState }
+  assert.equal(provider.getValidator(schema)(args).valid, false)
+  assert.throws(() => validateExpectedState(name, args), /INVALID_ARGUMENT/)
+}
+const validateJourney = provider.getValidator(toolDefinitions.find(tool => tool.name === 'run_journey')!.inputSchema)
+const step = { id: 'tap', type: 'tap', selector: { text: 'Go' }, expectedState }
+const journey = { platform: 'android', steps: [step] }
+assert.equal(validateJourney(journey).valid, true)
+assert.equal(journeySchema.safeParse(journey).success, true)
+for (const input of [
+  { ...journey, expectedState },
+  { ...journey, defaults: { expectedState } },
+  { ...journey, steps: [{ id: 'wait', type: 'wait', selector: { text: 'Go' }, expectedState }] },
+  { ...journey, steps: [{ id: 'launch', type: 'start_app', appId: 'example.app', expectedState }] },
+  { ...journey, steps: [{ id: 'assert', type: 'assert', assertion: { kind: 'element_visible', selector: { text: 'Go' } }, expectedState }] },
+  { ...journey, steps: [{ ...step, expectedState: { ...expectedState, timeoutMs: 0 } }] }
+]) {
+  assert.equal(validateJourney(input).valid, false)
+  assert.equal(journeySchema.safeParse(input).success, false)
+}
+console.log('Conditional JSON schema/runtime parity: PASS')

package/test/unit/server/correlated-evidence.test.ts

@@ -0,0 +1,194 @@
+import assert from 'node:assert/strict'
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
+import { AndroidObserve } from '../../../src/observe/android.js'
+import { iOSObserve, _setIOSActiveLogStream, _clearIOSActiveLogStream } from '../../../src/observe/ios.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { deriveSnapshotMetadata } from '../../../src/observe/snapshot-metadata.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-evidence-'))
+  const binary = path.join(directory, 'native')
+  const events = path.join(directory, 'events')
+  const keys = ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH', 'EVIDENCE_FAIL_INPUT', 'EVIDENCE_INPUT_SLOW']
+  const env = Object.fromEntries(keys.map(key => [key, process.env[key]]))
+  writeFileSync(events, '')
+  writeFileSync(binary, `#!/usr/bin/env node
+const fs = require('fs')
+const args = process.argv.slice(2).join(' ')
+fs.appendFileSync(${JSON.stringify(events)}, args + '\\n')
+if (args.includes('ro.build.version.release')) console.log('16')
+else if (args.includes('ro.product.model')) console.log('Fixture')
+else if (args.includes('ro.kernel.qemu')) console.log('1')
+else if (args.includes('simctl list devices')) console.log(JSON.stringify({devices:{'iOS-18':[{udid:'fixture-ios',name:'Fixture',state:'Booted'}]}}))
+else if (args.includes('list-targets')) console.log('[]')
+else if (args.includes('shell input') || args.includes('ui tap') || args.includes('ui swipe')) { if (process.env.EVIDENCE_FAIL_INPUT) process.exit(1); if (process.env.EVIDENCE_INPUT_SLOW) setTimeout(() => process.exit(0), 2000) }
+else if (args.includes('pidof')) console.log('123')
+else if (args.includes('logcat')) { console.log('2026-10-30 10:00:00.000 123 123 I Fixture: stream-owned'); setInterval(() => {}, 1000) }
+else if (args.includes('monkey') || args.includes('simctl launch')) console.log('launched: 123')
+else process.exit(1)
+`)
+  chmodSync(binary, 0o755)
+  for (const key of keys.slice(0, 4)) process.env[key] = binary
+  const device = (platform: 'android' | 'ios', id?: string) => ({ platform, id: id ?? `fixture-${platform}`, osVersion: '16', model: 'Fixture', simulator: true })
+  _setDeviceListersForTests({ listAndroidDevices: async () => [device('android'), device('android', 'other')], listIOSDevices: async () => [device('ios')] })
+  const originals: Array<() => void> = []
+  let captureCount = 0
+  let failScreenshot = false
+  for (const [platform, klass] of [['android', AndroidObserve], ['ios', iOSObserve]] as const) {
+    const prototype = klass.prototype as any
+    const replace = (name: string, fn: (...args: any[]) => any) => {
+      const original = prototype[name]; originals.push(() => { prototype[name] = original }); prototype[name] = fn
+    }
+    replace('collectGetUITree', async (id: string) => {
+      captureCount++
+      const body = { device: device(platform, id), elements: [{ text: 'Ready', resourceId: 'target', contentDescription: 'target', type: 'Button', clickable: true, enabled: true, visible: true, bounds: [0, 0, 50, 50] }], resolution: { width: 100, height: 200 }, screen: 'Ready' }
+      return { ...body, ...deriveSnapshotMetadata(`${platform}:${id}`, body as any, 'ui_tree') }
+    })
+    replace(platform === 'android' ? 'collectCaptureScreen' : 'collectCaptureScreenshot', async (id: string) => {
+      captureCount++
+      if (failScreenshot) throw new Error('screenshot offline')
+      return { device: device(platform, id), screenshot: 'fixture-image', screenshot_mime: 'image/png', resolution: { width: 100, height: 200 } }
+    })
+    replace('collectGetLogs', async (filters: any) => {
+      captureCount++
+      return { device: device(platform, filters.deviceId), logs: [{ timestamp: '2020-01-01T00:00:00Z', level: 'INFO', message: 'preserved' }], logCount: 1 }
+    })
+    if (platform === 'android') replace('collectGetCurrentScreen', async (id: string) => ({ device: device(platform, id), activity: 'FixtureActivity', package: 'fixture.app' }))
+  }
+  const payload = (r: any) => JSON.parse(r.content[0].text)
+  const call = async (name: string, args: Record<string, unknown>) => payload(await handleToolCall(name, args))
+  const refFor = (value: any) => ({ sessionId: value.evidence.session_id, actionId: value.evidence.action_id })
+  try {
+    for (const platform of ['android', 'ios'] as const) {
+      const target = { platform, deviceId: `fixture-${platform}` }
+      for (const responseMode of ['compact', 'debug']) {
+        const a = await call('tap', { ...target, responseMode, verificationMode: 'none', x: 10, y: 10 })
+        assert.equal(a.success, true)
+        assert.equal(a.action_id, a.evidence.action_id)
+        assert.equal(a.evidence.action_id, a.evidence.correlation_id)
+        assert.ok(a.evidence.dispatch_started_at_ms)
+        assert.ok(a.evidence.dispatch_completed_at_ms >= a.evidence.dispatch_started_at_ms)
+        assert.equal(a.evidence.verification_completed_at_ms, null)
+        if (responseMode === 'debug') assert.equal(a.trace.action_id, a.action_id)
+        const actionRef = refFor(a)
+        const image = await handleToolCall('capture_screenshot', { ...target, actionRef })
+        const imageMeta = payload(image)
+        assert.equal(imageMeta.evidence.action_id, a.action_id)
+        assert.equal(imageMeta.evidence.correlation_id, a.evidence.correlation_id)
+        assert.equal(image.content[1].data, 'fixture-image')
+        assert.equal(imageMeta.evidence.observations[0].freshness, 'fresh')
+        const logs = await handleToolCall('get_logs', { ...target, actionRef })
+        assert.equal(payload(logs).evidence.action_id, a.action_id)
+        assert.equal(JSON.parse(logs.content[1].text!).logs[0].message, 'preserved')
+        assert.equal(payload(logs).evidence.observations[0].event_time_comparable, false)
+        const tree = await call('get_ui_tree', { ...target, responseMode, actionRef })
+        assert.equal(tree.evidence.action_id, a.action_id)
+        assert.ok(tree.evidence.observations[0].snapshot_revision)
+        const verified = await call('tap', { ...target, responseMode, verificationMode: 'full', x: 10, y: 10 })
+        assert.ok(verified.evidence.verification_completed_at_ms >= verified.evidence.dispatch_completed_at_ms)
+        assert.ok(verified.evidence.observations.some((v: any) => v.freshness_reasons.includes('BEFORE_ACTION')))
+        assert.ok(verified.evidence.observations.some((v: any) => v.freshness === 'fresh'))
+        process.env.EVIDENCE_FAIL_INPUT = '1'
+        const failed = await call('tap', { ...target, responseMode, verificationMode: 'none', x: 10, y: 10 })
+        assert.equal(failed.success, false)
+        assert.ok(failed.evidence.dispatch_started_at_ms)
+        assert.equal(failed.evidence.verification_completed_at_ms, null)
+        delete process.env.EVIDENCE_FAIL_INPUT
+        const blocked = await call('tap', { ...target, responseMode, verificationMode: 'none', x: 10, y: 10,
+          expectedState: { snapshotSessionId: 'expired-session', snapshotRevision: 1 } })
+        assert.equal(blocked.failure_code, 'PRECONDITION_UNAVAILABLE')
+        assert.equal(blocked.evidence.dispatch_started_at_ms, null)
+        assert.equal(blocked.evidence.verification_completed_at_ms, null)
+      }
+      failScreenshot = true
+      const partial = await call('capture_debug_snapshot', { ...target, includeLogs: false })
+      assert.equal(partial.raw.screenshot_error, 'screenshot offline')
+      assert.equal(partial.evidence.observations.find((v: any) => v.kind === 'screenshot').status, 'failed')
+      assert.equal(partial.evidence.observations.find((v: any) => v.kind === 'logs').status, 'omitted')
+      failScreenshot = false
+      const disabled = await call('capture_debug_snapshot', { ...target, includeScreenshot: false, includeLogs: false })
+      assert.equal(disabled.raw.screenshot, null)
+      assert.equal(disabled.evidence.observations.find((v: any) => v.kind === 'screenshot').status, 'omitted')
+      const snapshot = await call('capture_debug_snapshot', target)
+      assert.equal(snapshot.raw.screenshot, 'fixture-image')
+      assert.equal(snapshot.raw.logs[0].message, 'preserved')
+      assert.ok(snapshot.evidence.observations.every((v: any) => !v.device || v.device.id === target.deviceId))
+    }
+    process.env.EVIDENCE_INPUT_SLOW = '1'
+    const timeout = await call('tap', { platform: 'android', deviceId: 'fixture-android', x: 1, y: 1,
+      verificationMode: 'none', responseMode: 'compact', actionTimeoutMs: 500 })
+    delete process.env.EVIDENCE_INPUT_SLOW
+    assert.equal(timeout.failure_code, 'ACTION_TIMEOUT')
+    assert.ok(timeout.evidence.dispatch_started_at_ms)
+    assert.ok(timeout.evidence.dispatch_completed_at_ms)
+    assert.equal(timeout.evidence.verification_completed_at_ms, null)
+    const before = captureCount
+    const malformed = await call('capture_screenshot', { platform: 'android', actionRef: { actionId: '' } })
+    assert.match(malformed.error.message, /INVALID_ARGUMENT/)
+    assert.equal(captureCount, before)
+    const a = await call('tap', { platform: 'android', deviceId: 'fixture-android', x: 1, y: 1, verificationMode: 'none' })
+    const mismatch = await call('capture_screenshot', { platform: 'android', deviceId: 'other', actionRef: refFor(a) })
+    assert.equal(mismatch.evidence.association_reason, 'DEVICE_MISMATCH')
+    assert.notEqual(mismatch.evidence.correlation_id, a.evidence.correlation_id)
+    const journey = await call('run_journey', { platform: 'android', deviceId: 'fixture-android', responseMode: 'debug',
+      defaults: { verificationMode: 'full' }, steps: [{ id: 'one', type: 'start_app', appId: 'fixture.app' }, { id: 'two', type: 'start_app', appId: 'fixture.app' }] })
+    assert.equal(journey.success, true)
+    assert.equal(journey.steps[0].result.evidence.correlation_id, journey.evidence.correlation_id)
+    assert.equal(journey.steps[1].result.evidence.correlation_id, journey.evidence.correlation_id)
+    assert.notEqual(journey.steps[0].result.evidence.action_id, journey.steps[1].result.evidence.action_id)
+    assert.ok(journey.steps[0].result.evidence.observations.some((v: any) => v.freshness === 'stale'))
+
+    assert.ok(journey.steps[0].result.evidence.operation_completed_at_ms <= journey.steps[1].result.evidence.operation_started_at_ms)
+    const light = await call('run_journey', { platform: 'android', deviceId: 'fixture-android', responseMode: 'compact',
+      defaults: { verificationMode: 'light' }, steps: [
+        { id: 'tap', type: 'tap', selector: { accessibility_id: 'target' } },
+        { id: 'verify', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'target' } } }
+      ] })
+    assert.equal(light.success, true)
+    const lightStep = light.steps[0].result
+    assert.ok(lightStep.evidence.verification_completed_at_ms)
+    const afterLight = await call('capture_screenshot', { platform: 'android', deviceId: 'fixture-android', actionRef: refFor(lightStep) })
+    assert.equal(afterLight.evidence.verification_completed_at_ms, lightStep.evidence.verification_completed_at_ms)
+
+    const started = await call('start_log_stream', { platform: 'android', deviceId: 'other', sessionId: 'evidence-owned', packageName: 'fixture.app' })
+    assert.equal(started.success, true)
+    let androidStream: any
+    for (let i = 0; i < 100; i++) {
+      androidStream = await call('read_log_stream', { platform: 'android', sessionId: 'evidence-owned', actionRef: refFor(a) })
+      if (androidStream.entries.length) break
+      await new Promise(resolve => setTimeout(resolve, 10))
+    }
+    assert.ok(androidStream.entries.length)
+    assert.equal(androidStream.evidence.device.id, 'other')
+    assert.equal(androidStream.evidence.association_reason, 'DEVICE_MISMATCH')
+    assert.match(readFileSync(events, 'utf8'), /-s other logcat/)
+    assert.equal((await call('stop_log_stream', { platform: 'android', sessionId: 'evidence-owned' })).success, true)
+    const streamFile = path.join(directory, 'stream.ndjson')
+    writeFileSync(streamFile, JSON.stringify({ message: 'stream-owned', _iso: '2020-01-01T00:00:00Z' }) + '\n')
+    _setIOSActiveLogStream('owned', streamFile, { platform: 'ios', id: 'fixture-ios' })
+    // Discovery returning a different device must not retarget this stream read.
+    _setDeviceListersForTests({ listIOSDevices: async () => { throw new Error('discovery must not run') } })
+    const stream = await call('read_log_stream', { platform: 'ios', sessionId: 'owned' })
+    assert.equal(stream.entries[0].message, 'stream-owned')
+    assert.equal(stream.evidence.device.id, 'fixture-ios')
+    assert.equal(stream.evidence.observations[0].device.id, 'fixture-ios')
+    for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream']) {
+      assert.ok((toolDefinitions.find(v => v.name === name)!.inputSchema.properties as any).actionRef)
+    }
+    assert.match(readFileSync(events, 'utf8'), /shell input tap/)
+    assert.match(readFileSync(events, 'utf8'), /ui tap/)
+  } finally {
+    await new AndroidObserve().stopLogStream('evidence-owned')
+    rmSync(path.join(tmpdir(), 'mobile-debug-log-evidence-owned.ndjson'), { force: true })
+    _clearIOSActiveLogStream('owned')
+    for (const restore of originals) restore()
+    _resetDeviceListersForTests()
+    for (const [key, value] of Object.entries(env)) { if (value === undefined) delete process.env[key]; else process.env[key] = value }
+    rmSync(directory, { recursive: true, force: true })
+  }
+  console.log('Correlated MCP response, native dispatch, snapshot, journey and stream contracts: PASS')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/server/readiness.test.ts

@@ -0,0 +1,170 @@
+import assert from 'node:assert/strict'
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv'
+import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
+import { ToolsObserve, AndroidObserve } from '../../../src/observe/index.js'
+import { deriveSnapshotMetadata, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests, withResolvedDevice } from '../../../src/utils/resolve-device.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const originalTree = ToolsObserve.getUITreeHandler
+  const originalNative = AndroidObserve.prototype.getUITree
+  const device = { platform: 'android', id: 'fixture', model: 'Fixture', osVersion: '16', simulator: true }
+  let reads = 0
+  let mode = 'stable'
+  let delayed = 0
+  let expireDuringRead: (() => void) | undefined
+  const tree = () => {
+    const label = mode === 'changing' ? `Item ${reads}` : mode === 'changeThenStable' && reads === 1 ? 'Before' : 'Ready'
+    const elements = [{ type: 'Button', text: label, contentDescription: 'target', visible: true, enabled: true, clickable: true, bounds: [0, 0, 50, 50] }]
+    if (mode === 'loading' || mode === 'loadingThenTimeout' || (mode === 'loaderThenReady' && reads <= 2)) elements.push({ type: 'android.widget.ProgressBar', text: '', contentDescription: '', visible: true, enabled: true, clickable: false, bounds: [0, 60, 20, 80] })
+    const body = { device, elements, screen: '', resolution: { width: 100, height: 200 } }
+    return { ...body, ...deriveSnapshotMetadata('android:fixture', body, 'ui_tree') }
+  }
+  ToolsObserve.getUITreeHandler = async () => {
+    reads++
+    if (delayed) await new Promise(resolve => setTimeout(resolve, delayed))
+    if (mode === 'loadingThenTimeout' && reads === 2) { expireDuringRead?.(); throw new Error('ACTION_TIMEOUT') }
+    if (mode === 'error') throw new Error('observation failed')
+    if (mode === 'disconnect') return { ...tree(), error: 'device fixture offline' } as any
+    return tree()
+  }
+  _setDeviceListersForTests({ listAndroidDevices: async () => [device] })
+  // Sample counts depend on elapsed time, not the host timer's wakeup precision.
+  // Advance both clocks exactly when a fixture/poll timer completes.
+  const originalDateNow = Date.now
+  const originalPerformanceNow = Object.getOwnPropertyDescriptor(performance, 'now')
+  const originalSetTimeout = globalThis.setTimeout
+  const epoch = originalDateNow()
+  let elapsed = 0
+  Date.now = () => epoch + elapsed
+  Object.defineProperty(performance, 'now', { configurable: true, value: () => elapsed })
+  globalThis.setTimeout = ((callback: (...args: any[]) => void, delay = 0, ...args: any[]) => {
+    queueMicrotask(() => { elapsed += Math.max(0, Number(delay) || 0); callback(...args) })
+    return {} as ReturnType<typeof setTimeout>
+  }) as typeof setTimeout
+  const call = async (name: string, args: any = {}) => JSON.parse((await handleToolCall(name, { platform: 'android', deviceId: 'fixture', ...args })).content[0].text!)
+  try {
+    let result = await call('get_app_readiness', { stabilityMs: 100 })
+    assert.equal(result.readiness.state, 'settled')
+    assert.equal(result.success, true)
+    assert.equal(reads, 2)
+    mode = 'loading'; reads = 0
+    result = await call('get_app_readiness')
+    assert.equal(result.readiness.state, 'loading')
+    assert.equal(reads, 1)
+    mode = 'changing'; reads = 0
+    result = await call('get_app_readiness', { stabilityMs: 100 })
+    assert.equal(result.readiness.state, 'transitioning')
+    assert.equal(result.success, true)
+    mode = 'loaderThenReady'; reads = 0
+    result = await call('wait_for_app_ready', { stabilityMs: 100, pollIntervalMs: 100, timeoutMs: 1500 })
+    assert.equal(result.readiness.state, 'settled')
+    assert.equal(result.success, true)
+    assert.equal(reads, 4)
+    mode = 'loading'; reads = 0
+    result = await call('wait_for_app_ready', { timeoutMs: 200, pollIntervalMs: 100 })
+    assert.equal(result.failure_code, 'READINESS_TIMEOUT')
+    assert.equal(result.readiness.state, 'loading')
+    assert.ok(result.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    assert.equal(result.readiness.capabilities.unresponsive, false)
+    mode = 'stable'; reads = 0; delayed = 150
+    result = await call('get_app_readiness', { timeoutMs: 100 })
+    assert.equal(result.success, false, 'late physical read cannot produce success')
+    assert.equal(result.readiness.state, 'unknown')
+    delayed = 0
+    mode = 'disconnect'; reads = 0
+    result = await call('wait_for_app_ready')
+    assert.equal(result.failure_code, 'DEVICE_UNAVAILABLE')
+    assert.equal(reads, 1)
+    mode = 'loading'; reads = 0
+    const ordinary = await call('wait_for_ui', { selector: { text: 'Ready' }, timeout_ms: 1500, poll_interval_ms: 100 })
+    assert.equal(ordinary.status, 'success', 'default wait keeps predicate-only semantics')
+    assert.equal(ordinary.readiness, undefined)
+    assert.equal(reads, 2)
+    reads = 0
+    const blocked = await call('wait_for_ui', { selector: { text: 'Ready' }, requireReady: true, timeout_ms: 650, poll_interval_ms: 100 })
+    assert.equal(blocked.status, 'timeout')
+    assert.equal(blocked.readiness.state, 'loading')
+    assert.equal(blocked.observed.condition_satisfied, true, 'a readiness timeout must not pretend the visible target was absent')
+    assert.ok(blocked.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    // Force expiry inside a later acquisition rather than depending on timer rounding.
+    for (const tool of ['wait_for_ui', 'wait_for_app_ready']) {
+      const originalNow = Object.getOwnPropertyDescriptor(performance, 'now')
+      const nativeNow = performance.now.bind(performance)
+      let advance = 0
+      Object.defineProperty(performance, 'now', { configurable: true, value: () => nativeNow() + advance })
+      expireDuringRead = () => { advance += 2000 }
+      mode = 'loadingThenTimeout'; reads = 0
+      try {
+        const timedOut = await call(tool, tool === 'wait_for_ui'
+          ? { selector: { text: 'Ready' }, requireReady: true, timeout_ms: 1000, poll_interval_ms: 100 }
+          : { timeoutMs: 1000, pollIntervalMs: 100 })
+        assert.equal(reads, 2)
+        assert.equal(timedOut.readiness.state, 'loading', 'expiry retains the last valid loading evidence')
+        assert.ok(timedOut.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+        assert.equal(timedOut.readiness.evidence.at(-1).code, 'NATIVE_LOADING_INDICATOR')
+        if (tool === 'wait_for_ui') assert.equal(timedOut.observed.condition_satisfied, true)
+        else assert.equal(timedOut.failure_code, 'READINESS_TIMEOUT')
+      } finally {
+        expireDuringRead = undefined
+        if (originalNow) Object.defineProperty(performance, 'now', originalNow)
+        else delete (performance as any).now
+      }
+    }
+    mode = 'loaderThenReady'; reads = 0
+    const ready = await call('wait_for_ui', { selector: { text: 'Ready' }, requireReady: true, timeout_ms: 2000, poll_interval_ms: 100 })
+    assert.equal(ready.status, 'success')
+    assert.equal(ready.readiness.state, 'settled')
+    assert.equal(reads, ready.readiness.sample_count, 'predicate and readiness share samples')
+    mode = 'changeThenStable'; reads = 0
+    const changed = await call('wait_for_ui_change', { requireReady: true, timeout_ms: 2500, stability_window_ms: 0 })
+    assert.equal(changed.success, true, JSON.stringify(changed))
+    assert.equal(changed.readiness.state, 'settled')
+    assert.equal(reads, changed.readiness.sample_count)
+    mode = 'stable'; reads = 0
+    result = await runWithBudget(100, () => call('wait_for_app_ready', { timeoutMs: 2000, stabilityMs: 500 }))
+    assert.equal(result.success, false, 'outer budget bounds the wait')
+    assert.ok(result.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    _setDeviceListersForTests({ listAndroidDevices: async () => { await new Promise(resolve => setTimeout(resolve, 140)); return [] } })
+    const discoveryTimeout = await call('wait_for_app_ready', { timeoutMs: 100 })
+    assert.equal(discoveryTimeout.failure_code, 'READINESS_TIMEOUT', 'discovery deadline is not proof of a missing device')
+    assert.ok(discoveryTimeout.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    _setDeviceListersForTests({ listAndroidDevices: async () => [device] })
+    // The ordinary tree path adds single-sample metadata without extra acquisition.
+    ToolsObserve.getUITreeHandler = originalTree
+    let nativeReads = 0
+    AndroidObserve.prototype.getUITree = async () => { nativeReads++; return tree() as any }
+    for (const responseMode of ['debug', 'compact'] as const) {
+      const observed: any = await withResolvedDevice(device, () => ToolsObserve.getUITreeHandler({ platform: 'android', deviceId: 'fixture', responseMode }))
+      assert.equal(observed.readiness.state, 'unknown')
+      assert.equal(observed.readiness.sample_count, 1)
+    }
+    assert.equal(nativeReads, 2, 'one native read per public tree response')
+    const validator = new AjvJsonSchemaValidator()
+    for (const name of ['get_app_readiness', 'wait_for_app_ready']) {
+      const schema = validator.getValidator(toolDefinitions.find(tool => tool.name === name)!.inputSchema)
+      assert.equal(schema({ platform: 'android' }).valid, true)
+      for (const args of [{ platform: 'other' }, { platform: 'android', timeoutMs: 99 }, { platform: 'android', stabilityMs: 10001 }, { platform: 'android', extra: true }, { platform: 'android', deviceId: '' }]) {
+        assert.equal(schema(args).valid, false)
+        const result = JSON.parse((await handleToolCall(name, args)).content[0].text!)
+        assert.match(result.error.message, /INVALID_ARGUMENT/)
+      }
+    }
+    for (const name of ['wait_for_ui', 'wait_for_ui_change']) {
+      const bad = await call(name, { requireReady: 'yes' })
+      assert.match(bad.error.message, /INVALID_ARGUMENT/)
+    }
+    console.log('Readiness tools, schemas and opt-in waits: PASS')
+  } finally {
+    globalThis.setTimeout = originalSetTimeout
+    Date.now = originalDateNow
+    if (originalPerformanceNow) Object.defineProperty(performance, 'now', originalPerformanceNow)
+    else delete (performance as any).now
+    ToolsObserve.getUITreeHandler = originalTree
+    AndroidObserve.prototype.getUITree = originalNative
+    _resetDeviceListersForTests()
+    resetSnapshotMetadataForTests()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/selector_tap_target.test.ts

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { remainingBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const originalTree = ToolsObserve.getUITreeHandler
+  const originalTap = ToolsInteract.tapHandler
+  const tab = () => ({ bounds: [244, 1408, 476, 1528], clickable: true, visible: true, enabled: true, children: [1] })
+  const label = () => ({ text: 'GENER8', bounds: [330, 1489, 391, 1513], clickable: false, visible: true, enabled: true, parentId: 0 })
+  let elements: any[] = [tab(), label()]
+  let error: string | undefined
+  let observedBudget = 0
+  let reads = 0
+  const taps: Array<{ x: number; y: number }> = []
+  ToolsObserve.getUITreeHandler = async () => {
+    observedBudget = remainingBudget()
+    reads++
+    return { device: { platform: 'android', id: 'fixture' }, elements, captured_at_ms: Date.now(), error } as any
+  }
+  ToolsInteract.tapHandler = async args => {
+    taps.push({ x: args.x, y: args.y })
+    return { device: { platform: 'android', id: 'fixture' }, success: true } as any
+  }
+  const call = async (args: Record<string, unknown> = {}) => JSON.parse((await handleToolCall('tap_element', {
+    platform: 'android', deviceId: 'fixture', selector: { text: 'GENER8' }, responseMode: 'compact', verificationMode: 'none', ...args
+  })).content[0].text!)
+  try {
+    for (const waitFor of [undefined, {}, { condition: 'exists' }, { condition: 'visible' }, { condition: 'clickable' }]) {
+      reads = 0
+      const result = await call(waitFor ? { waitFor } : {})
+      assert.equal(result.success, true)
+      assert.deepEqual(taps.at(-1), { x: 360, y: 1468 })
+      assert.equal(reads, 1, 'Reuse the selector acquisition for dispatch resolution')
+      assert.ok(observedBudget > 1500 && observedBudget <= 5000, `One acquisition should use the action budget: ${observedBudget}`)
+    }
+    await call({ actionTimeoutMs: 12000 })
+    assert.ok(observedBudget > 10000 && observedBudget <= 12000)
+    await call({ actionTimeoutMs: 12000, waitFor: { condition: 'exists', timeoutMs: 700 } })
+    assert.ok(observedBudget > 0 && observedBudget <= 700)
+    const tapCount = taps.length
+    error = 'Failed to get UI tree: ACTION_TIMEOUT'
+    const timeout = await call()
+    assert.equal(timeout.failure_code, 'ACTION_TIMEOUT', 'Observation timeout must not claim that the label is missing')
+    assert.equal(timeout.evidence.dispatch_started_at_ms, null)
+    assert.equal(taps.length, tapCount)
+    error = undefined
+
+    for (const patch of [{ enabled: false }, { visible: false }]) {
+      for (const condition of ['exists', 'visible', 'clickable']) {
+        elements = [tab(), { ...label(), ...patch }]
+        // A short explicit wait bounds unsatisfied visible/clickable conditions.
+        const result = await call({ waitFor: { condition, timeoutMs: 100 } })
+        assert.equal(result.success, false)
+        assert.equal(taps.length, tapCount, 'Never bypass hidden/disabled labels through an enabled parent')
+      }
+    }
+    elements = [{ ...tab(), enabled: false }, label()]
+    assert.equal((await call({ waitFor: { condition: 'exists' } })).failure_code, 'ELEMENT_NOT_INTERACTABLE')
+    assert.equal(taps.length, tapCount)
+    elements = [label()]
+    assert.equal((await call({ waitFor: { condition: 'exists' } })).failure_code, 'ELEMENT_NOT_INTERACTABLE')
+    assert.equal(taps.length, tapCount, 'A plain label without an actionable container remains untappable')
+    elements = [tab(), label(), { ...label(), parentId: 0 }]
+    assert.equal((await call()).failure_code, 'AMBIGUOUS_TARGET')
+    assert.equal(taps.length, tapCount)
+    // Standalone waits keep returning the matched leaf for exists; promotion is tap-only.
+    elements = [tab(), label()]
+    const wait = await ToolsInteract.waitForUIHandler({ selector: { text: 'GENER8' }, condition: 'exists', platform: 'android', singleObservation: true })
+    assert.equal(wait.element.index, 1)
+  } finally {
+    ToolsObserve.getUITreeHandler = originalTree
+    ToolsInteract.tapHandler = originalTap
+    ToolsInteract._resetResolvedUiElementsForTests()
+  }
+  console.log('Selector tap acquisition budget, executable ancestor, and rejection guards: PASS')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/server/system-trace.test.ts

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict'
+import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
+import { systemTraces } from '../../../src/observe/system-trace.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { AndroidManage } from '../../../src/manage/index.js'
+import { withEvidence, bindSystemTrace, bindEvidenceDevice } from '../../../src/observe/evidence.js'
+
+const parse = (r: any) => JSON.parse(r.content[0].text)
+async function run() {
+  const originalLink = systemTraces.link, originalStart = systemTraces.start, originalControl = systemTraces.control
+  const originalApp = AndroidManage.prototype.startApp
+  const id = '62a51510-c303-4a1b-af0e-f97cc976d740'
+  let dispatched = 0, starts = 0
+  _setDeviceListersForTests({ listAndroidDevices: async () => [{ id: 'trace-device', platform: 'android', osVersion: '16', simulator: true, model: 'fixture' }] })
+  try {
+    for (const name of ['get_system_trace_capabilities', 'start_system_trace', 'get_system_trace_status', 'stop_system_trace', 'cancel_system_trace']) {
+      const tool = toolDefinitions.find(t => t.name === name)
+      assert.ok(tool); assert.equal(tool.inputSchema.additionalProperties, false)
+    }
+    assert.equal(toolDefinitions.find(t => t.name === 'run_journey').inputSchema.properties.systemTraceId.format, 'uuid')
+    for (const args of [ {}, { platform: 'android', extra: true }, { platform: 'android', expectedState: {} }, { platform: 'android', durationMs: 0 }, { platform: 'android', durationMs: 1000.5 }, { platform: 'android', durationMs: 120001 } ]) {
+      const r = await handleToolCall('start_system_trace', args)
+      assert.equal(r.isError, true); assert.equal(parse(r).error.code, 'INVALID_ARGUMENT')
+    }
+    systemTraces.start = async () => { starts++; throw new Error('must not run') }
+    const ios = await handleToolCall('start_system_trace', { platform: 'ios' })
+    assert.equal(parse(ios).error.code, 'UNSUPPORTED_PLATFORM'); assert.equal(starts, 0)
+    assert.equal(parse(await handleToolCall('get_system_trace_capabilities', { platform: 'ios' })).supported, false)
+    for (const name of ['stop_system_trace', 'cancel_system_trace', 'get_system_trace_status']) {
+      assert.equal(parse(await handleToolCall(name, { traceId: id, deviceId: 'wrong' })).error.code, 'INVALID_ARGUMENT')
+      assert.equal(parse(await handleToolCall(name, { traceId: id })).error.code, 'TRACE_NOT_FOUND')
+    }
+    AndroidManage.prototype.startApp = async () => { dispatched++; return { appStarted: true } as any }
+    const journey = { platform: 'android', deviceId: 'trace-device', systemTraceId: id, steps: [{ id: 'start', type: 'start_app', appId: 'com.android.settings', verificationMode: 'none' }] }
+    const rejected = await handleToolCall('run_journey', journey)
+    assert.equal(rejected.isError, true); assert.equal(dispatched, 0)
+    let correlation = ''
+    systemTraces.link = async (trace, device, cid) => {
+      assert.equal(trace, id); assert.equal(device.id, 'trace-device'); correlation = cid
+      return async () => ({ trace_id: trace, coverage: 'covered', clock_alignment: 'unknown' })
+    }
+    const result = parse(await handleToolCall('run_journey', journey))
+    assert.equal(result.success, true, JSON.stringify(result)); assert.equal(dispatched, 1)
+    assert.equal(result.evidence.trace_context.trace_id, id)
+    assert.equal(result.evidence.trace_context.supported, true)
+    assert.equal(result.evidence.correlation_id, correlation)
+    assert.equal(result.steps[0].result.evidence.trace_context.trace_id, id)
+    assert.equal(result.steps[0].result.evidence.correlation_id, correlation)
+    assert.equal(result.system_trace.coverage, 'covered')
+    const plain = parse(await handleToolCall('run_journey', { ...journey, systemTraceId: undefined }))
+    assert.deepEqual(plain.evidence.trace_context, { supported: false, trace_id: null, markers: [] })
+    const [linked, independent] = await Promise.all([
+      withEvidence({ journey: true }, async () => { bindSystemTrace(id); bindEvidenceDevice({ platform: 'android', id: 'trace-device' }); return withEvidence({ action: true }, async () => {}) }),
+      withEvidence({ journey: true }, async () => {})
+    ])
+    assert.equal(linked.result.evidence.trace_context.trace_id, id)
+    assert.equal(independent.evidence.trace_context.trace_id, null)
+    console.log('system trace tool contracts and journey evidence: PASS')
+  } finally {
+    systemTraces.link = originalLink; systemTraces.start = originalStart; systemTraces.control = originalControl
+    AndroidManage.prototype.startApp = originalApp; _resetDeviceListersForTests()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/tap_selector.test.ts

@@ -24,6 +24,8 @@ async function run() {
     assert.equal(success.success, true)
     assert.equal(tapCount, 1)
     assert.equal(lastWait.condition, 'clickable')
+    assert.equal(lastWait.timeout_ms, 5000)
+    assert.equal(lastWait.resolveTapTarget, true)
     assert.equal(lastWait.singleObservation, true)
     assert.equal(lastWait.singleAttempt, true)
     assert.equal(lastWait.rejectAmbiguous, true)