mobile-debug-mcp 0.32.4 → 0.34.0

package/test/unit/observe/readiness_native.test.ts

@@ -0,0 +1,68 @@
+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 } from '../../../src/server-core.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-ready-native-'))
+  const binary = path.join(directory, 'native')
+  const marker = path.join(directory, 'closed')
+  const keys = ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH', 'READY_SLOW', 'READY_LOADER', 'READY_SLOW_META']
+  const previous = Object.fromEntries(keys.map(key => [key, process.env[key]]))
+  writeFileSync(binary, `#!/usr/bin/env node
+const fs = require('fs'); const a = process.argv.slice(2).join(' ')
+function slow() { process.on('SIGTERM', () => setTimeout(() => { fs.writeFileSync(${JSON.stringify(marker)}, 'closed'); process.exit(0) }, 40)); setInterval(() => {}, 1000) }
+if (a.includes('ro.build.version.release')) console.log('16')
+else if (a.includes('ro.product.model')) console.log('Fixture')
+else if (a.includes('ro.kernel.qemu')) console.log('1')
+else if (a.includes('wm size')) console.log('Physical size: 100x200')
+else if (a.includes('uiautomator dump')) { if (process.env.READY_SLOW) slow(); else console.log('dumped') }
+else if (a.includes('cat /sdcard/ui.xml')) console.log('<hierarchy><node class="' + (process.env.READY_LOADER ? 'android.widget.ProgressBar' : 'android.widget.Button') + '" text="Ready" visible-to-user="true" enabled="true" bounds="[0,0][100,200]" /></hierarchy>')
+else if (a.includes('simctl list devices')) { if (process.env.READY_SLOW_META) { fs.writeFileSync(${JSON.stringify(marker)}, String(process.pid)); setInterval(() => {}, 1000) } else console.log(JSON.stringify({ devices: { 'iOS-18': [{ udid: 'fixture', name: 'Fixture', state: 'Booted' }] } })) }
+else if (a.includes('list-targets')) console.log('[]')
+else if (a.includes('ui describe-all')) { if (process.env.READY_SLOW) slow(); else console.log(JSON.stringify({ AXElementType: process.env.READY_LOADER ? 'ActivityIndicator' : 'Button', AXLabel: 'Ready', AXFrame: { x: 0, y: 0, width: 100, height: 200 } })) }
+else process.exit(1)
+`)
+  chmodSync(binary, 0o755)
+  for (const key of ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH']) process.env[key] = binary
+  const device = (platform: string) => ({ platform, id: 'fixture', model: 'Fixture', simulator: true, osVersion: '16' })
+  _setDeviceListersForTests({ listAndroidDevices: async () => [device('android')], listIOSDevices: async () => [device('ios')] })
+  const call = async (platform: string, args: any) => JSON.parse((await handleToolCall('get_app_readiness', { platform, deviceId: 'fixture', ...args })).content[0].text!)
+  try {
+    for (const platform of ['android', 'ios']) {
+      const stable = await call(platform, { stabilityMs: 100 })
+      assert.equal(stable.readiness.state, 'settled', JSON.stringify(stable))
+      assert.equal(stable.readiness.sample_count, 2)
+      process.env.READY_LOADER = '1'
+      const loader = await call(platform, {})
+      assert.equal(loader.readiness.state, 'loading')
+      assert.equal(loader.readiness.basis, 'observed')
+      delete process.env.READY_LOADER
+      process.env.READY_SLOW = '1'
+      writeFileSync(marker, '')
+      const timed = await call(platform, { timeoutMs: 1500 })
+      assert.equal(timed.success, false)
+      assert.equal(timed.readiness.state, 'unknown')
+      assert.ok(timed.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+      assert.equal(readFileSync(marker, 'utf8'), 'closed', 'timed-out native acquisition closes its child before responding')
+      delete process.env.READY_SLOW
+    }
+    process.env.READY_SLOW_META = '1'
+    writeFileSync(marker, '')
+    const metadataTimeout = await call('ios', { timeoutMs: 300 })
+    assert.equal(metadataTimeout.success, false)
+    assert.ok(metadataTimeout.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    const pid = Number(readFileSync(marker, 'utf8'))
+    assert.ok(pid > 0)
+    assert.throws(() => process.kill(pid, 0), (error: any) => error.code === 'ESRCH', 'metadata child must be closed after its deadline')
+    delete process.env.READY_SLOW_META
+    console.log('Readiness native Android/iOS acquisition and timeout cleanup: PASS')
+  } finally {
+    _resetDeviceListersForTests()
+    for (const key of keys) { if (previous[key] === undefined) delete process.env[key]; else process.env[key] = previous[key] }
+    rmSync(directory, { recursive: true, force: true })
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/system-trace-android.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import { AndroidTraceNative } from '../../../src/observe/system-trace-android.js'
+import type { execCmd } from '../../../src/utils/exec.js'
+
+async function run() {
+  const calls: Array<{ args: string[]; timeout: number | undefined }> = []
+  let failure = '', processes = ''
+  const execute: typeof execCmd = async (_cmd, args, options = {}) => {
+    calls.push({ args, timeout: options.timeout })
+    assert.equal(args[0], '-s'); assert.equal(args[1], 'serial with spaces')
+    if (failure && args.join(' ').includes(failure)) return { exitCode: null, stdout: '', stderr: 'ACTION_TIMEOUT' }
+    let out = ''
+    if (args.includes('--help')) return { exitCode: 1, stdout: '', stderr: 'Usage: perfetto --background-wait --config' }
+    if (args.includes('getprop')) out = '36'
+    if (args.includes('--list_categories')) out = ' sched - Scheduling\n input - Input\n gfx - Graphics'
+    if (args.join(' ').includes('YQ==')) out = 'a'
+    if (args.join(' ').includes('for pid')) out = processes
+    if (args.includes('stat')) out = '1024'
+    return { exitCode: 0, stdout: out, stderr: '' }
+  }
+  const native = new AndroidTraceNative(execute)
+  const remote = '/data/misc/perfetto-traces/mcp-62a51510-c303-4a1b-af0e-f97cc976d740.perfetto-trace'
+  assert.equal((await native.capabilities('serial with spaces')).supported, true)
+  for (const probe of ['--help', '--query', 'getprop', '--list_categories', 'test -w', 'YQ==']) {
+    failure = probe
+    assert.equal((await native.capabilities('serial with spaces')).supported, false, probe)
+  }
+  failure = ''
+  await native.start('serial with spaces', remote, 1001, ['sched', 'input'])
+  assert.equal(calls.at(-1)!.timeout, 35000)
+  assert.ok(calls.at(-1)!.args.join(' ').includes('--background-wait -c -'))
+  assert.equal(await native.find('serial with spaces', remote), null)
+  processes = '123 456'
+  assert.deepEqual(await native.find('serial with spaces', remote), { pid: 123, startTime: '456' })
+  assert.ok(calls.at(-1)!.args.join(' ').includes('stat=$(cat "$p/stat" 2>/dev/null) || { [ ! -d "$p" ] && continue; exit 1; }'), 'Unreadable process identity must fail closed')
+  processes = '123 456\n999 888'
+  await assert.rejects(() => native.find('serial with spaces', remote), /IDENTITY_UNAVAILABLE/)
+  const previous = calls.length
+  await assert.rejects(() => native.stop('serial with spaces', remote, { pid: 0, startTime: '4' }))
+  await assert.rejects(() => native.start('serial with spaces', '/tmp/other; killall perfetto', 1000, []))
+  assert.equal(calls.length, previous)
+  await native.stop('serial with spaces', remote, { pid: 123, startTime: '456' })
+  const signal = calls.at(-1)!.args.join(' ')
+  assert.ok(signal.indexOf('awk') < signal.indexOf('kill -TERM'))
+  assert.ok(signal.indexOf('grep -Fx') < signal.indexOf('kill -TERM'))
+  assert.ok(!signal.includes('killall'))
+  failure = 'pull'
+  await assert.rejects(() => native.pull('serial with spaces', remote, '/tmp/fixture'), /ACTION_TIMEOUT/)
+  assert.equal(calls.at(-1)!.timeout, 30000)
+  console.log('Android Perfetto adapter probes, targeting, guards and deadlines: PASS')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

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

@@ -0,0 +1,166 @@
+import assert from 'node:assert/strict'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { SystemTraceSessions, type TraceClock } from '../../../src/observe/system-trace.js'
+import { TRACE_MAX_BYTES, traceConfig, type TraceNative, type TraceCapabilities, type TraceProcess } from '../../../src/observe/system-trace-android.js'
+
+function fixture() {
+  let now = 1000000
+  let failStart = '', failStop = '', failPull = '', failRemove = '', failFind = ''
+  let supported = true, empty = false, oversized = false, stuck = false
+  let starts = 0, stops = 0, pulls = 0, removes = 0
+  const processes = new Map<string, TraceProcess>()
+  const pending = new Map<any, () => void>()
+  const time: TraceClock = { wall: () => now, mono: () => now, sleep: async ms => { now += ms },
+    schedule(fn) { const id = {} as any; pending.set(id, fn); return id }, clear: id => { pending.delete(id) } }
+  const native: TraceNative = {
+    async capabilities(device) { return { supported, backend: 'perfetto', device: { platform: 'android', id: device }, prerequisites: {}, reasons: [], enabled_sources: ['sched', 'input'], unavailable_categories: [], limitations: [] } as TraceCapabilities },
+    async start(_d, remote) { starts++; processes.set(remote, { pid: starts + 100, startTime: String(starts) }); if (failStart) throw new Error(failStart) },
+    async find(_d, remote) { if (failFind) throw new Error(failFind); return processes.get(remote) ?? null },
+    async stop(_d, remote) { stops++; if (failStop) throw new Error(failStop); if (!stuck) processes.delete(remote) },
+    async pull(_d, _r, local) { pulls++; await fs.writeFile(local, empty ? '' : 'perfetto-fixture'); if (oversized) await fs.truncate(local, TRACE_MAX_BYTES + 1); if (failPull) throw new Error(failPull) },
+    async remove() { removes++; if (failRemove) throw new Error(failRemove) }
+  }
+  const sessions = new SystemTraceSessions(native, time)
+  const files: string[] = []
+  return { sessions, native, time, processes, pending, files,
+    tick(ms: number) { now += ms }, get counts() { return { starts, stops, pulls, removes } },
+    flags(v: { start?: string; stop?: string; pull?: string; remove?: string; find?: string; supported?: boolean; empty?: boolean; oversized?: boolean; stuck?: boolean }) {
+      failStart = v.start ?? ''; failStop = v.stop ?? ''; failPull = v.pull ?? ''; failRemove = v.remove ?? ''; failFind = v.find ?? ''
+      supported = v.supported ?? true; empty = v.empty ?? false; oversized = v.oversized ?? false; stuck = v.stuck ?? false
+    },
+    async cleanup() { await sessions.shutdown(); await Promise.all(files.map(file => fs.rm(path.dirname(file), { recursive: true, force: true }))) }
+  }
+}
+async function run() {
+  const f = fixture()
+  try {
+    const a = await f.sessions.start('a', 1001)
+    assert.equal(a.state, 'recording')
+    assert.equal(a.capture_completed_at_ms, null)
+    await assert.rejects(() => f.sessions.start('a'), /TRACE_BUSY/)
+    const b = await f.sessions.start('b')
+    const end = await f.sessions.link(a.trace_id, { platform: 'android', id: 'a' }, 'journey-a')
+    await assert.rejects(() => f.sessions.link(a.trace_id, { platform: 'android', id: 'b' }, 'wrong'), /TRACE_NOT_FOUND/)
+    await assert.rejects(() => f.sessions.link(a.trace_id, { platform: 'ios', id: 'a' }, 'wrong'), /TRACE_NOT_FOUND/)
+    const [stop, again] = await Promise.all([f.sessions.control(a.trace_id, 'stop'), f.sessions.control(a.trace_id, 'stop')])
+    assert.equal(stop.state, 'completed'); assert.deepEqual(stop, again)
+    f.files.push(stop.artifact!.path)
+    assert.equal((await end()).coverage, 'partial') // another call stopped capture during the linked journey
+    assert.deepEqual(stop.correlation_ids, ['journey-a'])
+    assert.equal((await fs.stat(stop.artifact!.path)).mode & 0o777, 0o600)
+    assert.equal((await f.sessions.control(a.trace_id, 'cancel')).artifact?.path, stop.artifact?.path)
+    assert.equal(f.counts.pulls, 1)
+    assert.equal((await f.sessions.control(b.trace_id, 'cancel')).state, 'cancelled')
+    assert.equal(f.counts.pulls, 1)
+    const expired = await f.sessions.start('c', 1000)
+    f.tick(1001)
+    const duration = await f.sessions.control(expired.trace_id, 'status')
+    assert.equal(duration.completion_reason, 'duration_limit'); f.files.push(duration.artifact!.path)
+    f.tick(600001)
+    await assert.rejects(() => f.sessions.control(a.trace_id, 'status'), /TRACE_NOT_FOUND/)
+    await assert.rejects(() => f.sessions.control('previous-server', 'stop'), /TRACE_NOT_FOUND/)
+  } finally { await f.cleanup() }
+
+  for (const failure of ['start', 'stop', 'pull', 'remove', 'find', 'empty', 'oversized'] as const) {
+    const f = fixture()
+    try {
+      if (failure === 'start') f.flags({ start: 'ACTION_TIMEOUT' })
+      const a = await f.sessions.start('a')
+      if (failure === 'start') {
+        assert.equal(a.reason, 'ACTION_TIMEOUT'); assert.equal(a.state, 'failed'); assert.equal(a.cleanup.status, 'complete')
+        assert.equal(f.processes.size, 0); continue
+      }
+      f.flags(failure === 'empty' || failure === 'oversized' ? { [failure]: true } : { [failure]: 'ACTION_TIMEOUT' })
+      const stop = await f.sessions.control(a.trace_id, 'stop')
+      assert.equal(stop.state, 'failed', failure); assert.equal(stop.cleanup.status, 'failed', failure)
+      if (stop.artifact) f.files.push(stop.artifact.path)
+      if (failure === 'pull' || failure === 'empty' || failure === 'oversized') assert.equal(stop.artifact, null)
+      f.flags({})
+      const retry = await f.sessions.control(a.trace_id, 'stop')
+      assert.equal(retry.state, 'completed', failure); assert.equal(retry.cleanup.status, 'complete')
+      if (!f.files.includes(retry.artifact!.path)) f.files.push(retry.artifact!.path)
+    } finally { await f.cleanup() }
+  }
+  const reuse = fixture()
+  try {
+    const a = await reuse.sessions.start('a')
+    const [remote, process] = [...reuse.processes.entries()][0]
+    reuse.processes.set(remote, { ...process, startTime: '999999' })
+    const result = await reuse.sessions.control(a.trace_id, 'stop')
+    assert.equal(result.reason, 'TRACE_STOP_FAILED'); assert.equal(reuse.counts.stops, 0)
+    reuse.processes.delete(remote)
+    assert.equal((await reuse.sessions.control(a.trace_id, 'cancel')).state, 'cancelled')
+  } finally { await reuse.cleanup() }
+  const cap = fixture()
+  try {
+    cap.flags({ supported: false })
+    assert.equal((await cap.sessions.start('a')).reason, 'TRACE_UNSUPPORTED'); assert.equal(cap.counts.starts, 0)
+    cap.flags({})
+    await Promise.all(['a', 'b', 'c', 'd'].map(d => cap.sessions.start(d)))
+    await assert.rejects(() => cap.sessions.start('e'), /TRACE_BUSY/)
+    await cap.sessions.shutdown(); assert.equal(cap.processes.size, 0)
+    await assert.rejects(() => cap.sessions.start('e'), /TRACE_BUSY/)
+  } finally { await cap.cleanup() }
+  const timer = fixture()
+  try {
+    const a = await timer.sessions.start('timer', 1000)
+    timer.tick(1000)
+    for (const callback of timer.pending.values()) callback()
+    const ended = await timer.sessions.control(a.trace_id, 'status')
+    assert.equal(ended.state, 'completed'); assert.equal(ended.completion_reason, 'duration_limit')
+    timer.files.push(ended.artifact!.path)
+  } finally { await timer.cleanup() }
+  const stuck = fixture()
+  try {
+    const a = await stuck.sessions.start('stuck')
+    stuck.flags({ stuck: true })
+    const failed = await stuck.sessions.control(a.trace_id, 'stop')
+    assert.equal(failed.reason, 'ACTION_TIMEOUT'); assert.equal(failed.artifact, null)
+    assert.equal(stuck.counts.pulls, 0)
+    stuck.flags({})
+    assert.equal((await stuck.sessions.control(a.trace_id, 'cancel')).cleanup.status, 'complete')
+  } finally { await stuck.cleanup() }
+  const natural = fixture()
+  try {
+    const a = await natural.sessions.start('natural')
+    natural.native.stop = async (_device, remote) => { natural.processes.delete(remote); throw new Error('PROCESS_ALREADY_EXITED') }
+    assert.equal((await natural.sessions.control(a.trace_id, 'cancel')).state, 'cancelled')
+  } finally { await natural.cleanup() }
+  const interrupted = fixture()
+  try {
+    const a = await interrupted.sessions.start('journey')
+    const finish = await interrupted.sessions.link(a.trace_id, { platform: 'android', id: 'journey' }, 'j')
+    interrupted.flags({ find: 'DEVICE_DISCONNECTED' })
+    assert.equal((await finish()).coverage, 'partial')
+    interrupted.flags({})
+  } finally { await interrupted.cleanup() }
+  const racing = fixture()
+  let release!: () => void
+  const gate = new Promise<void>(resolve => { release = resolve })
+  const originalCapabilities = racing.native.capabilities
+  racing.native.capabilities = async device => { await gate; return originalCapabilities(device) }
+  const starting = racing.sessions.start('race')
+  const closing = racing.sessions.shutdown()
+  release()
+  assert.equal((await starting).reason, 'TRACE_BUSY')
+  assert.deepEqual(await closing, [])
+  assert.equal(racing.counts.starts, 0)
+  const retention = fixture()
+  try {
+    const first = await retention.sessions.start('retention')
+    await retention.sessions.control(first.trace_id, 'cancel')
+    for (let n = 0; n < 100; n++) {
+      const next = await retention.sessions.start('retention')
+      await retention.sessions.control(next.trace_id, 'cancel')
+    }
+    await assert.rejects(() => retention.sessions.control(first.trace_id, 'status'), /TRACE_NOT_FOUND/)
+  } finally { await retention.cleanup() }
+  // Wire bytes decode independently to protect actual proto field numbers/limits.
+  const config = traceConfig(1001, ['sched', 'input'])
+  assert.ok(config.includes(Buffer.from('linux.ftrace')))
+  assert.ok(config.includes(Buffer.from([0x18, 0xe9, 0x07]))) // TraceConfig.duration_ms = 3
+  assert.ok(config.includes(Buffer.from([0x50, 0x80, 0x80, 0x80, 0x10]))) // max_file_size_bytes = 10
+  console.log('system trace session lifecycle: PASS')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/conditional_actions.test.ts

@@ -0,0 +1,299 @@
+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 { ToolsObserve } from '../../../src/observe/index.js'
+import { ToolsNetwork } from '../../../src/network/index.js'
+import { deriveSnapshotMetadata, getSnapshotSessionId, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-conditional-'))
+  const eventsPath = path.join(directory, 'events')
+  const native = path.join(directory, 'native')
+  const changedPath = path.join(directory, 'prepared')
+  const envKeys = ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH', 'MCP_CONDITION_PREPARE', 'MCP_CONDITION_INPUT_FAIL', 'MCP_CONDITION_TREE_TEXT', 'MCP_CONDITION_SLOW']
+  const originalEnv = Object.fromEntries(envKeys.map(key => [key, process.env[key]]))
+  writeFileSync(eventsPath, '')
+  writeFileSync(native, `#!/usr/bin/env node
+const fs = require('fs')
+const args = process.argv.slice(2).join(' ')
+function slow() {
+  process.on('SIGTERM', () => setTimeout(() => { fs.writeFileSync(${JSON.stringify(changedPath)}, 'closed'); process.exit(0) }, 40))
+  setInterval(() => {}, 1000)
+}
+fs.appendFileSync(${JSON.stringify(eventsPath)}, args + '\\n')
+if (args.includes('ro.build.version.release')) console.log('16')
+else if (args.includes('ro.product.model')) { if (process.env.MCP_CONDITION_PREPARE) fs.writeFileSync(${JSON.stringify(changedPath)}, 'changed'); 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', name: 'Fixture', state: 'Booted' }] } }))
+else if (args.includes('list-targets')) { if (process.env.MCP_CONDITION_PREPARE) fs.writeFileSync(${JSON.stringify(changedPath)}, 'changed'); console.log('[]') }
+else if (args.includes('wm size')) console.log('Physical size: 100x200')
+else if (args.includes('uiautomator dump')) { if (process.env.MCP_CONDITION_SLOW) slow(); else console.log('dumped') }
+else if (args.includes('cat /sdcard/ui.xml')) console.log('<hierarchy><node class="android.widget.Button" resource-id="target" text="' + (process.env.MCP_CONDITION_TREE_TEXT || 'Ready') + '" clickable="true" enabled="true" visible-to-user="true" bounds="[0,0][50,50]" /></hierarchy>')
+else if (args.includes('ui describe-all')) { if (process.env.MCP_CONDITION_SLOW) slow(); else console.log(JSON.stringify({ AXElementType: 'Button', AXLabel: process.env.MCP_CONDITION_TREE_TEXT || 'Ready', AXUniqueId: 'target', AXFrame: { x: 0, y: 0, width: 100, height: 200 } })) }
+else if (args.includes('shell input') || args.includes('ui tap') || args.includes('ui swipe')) { if (process.env.MCP_CONDITION_INPUT_FAIL) process.exit(1) }
+else process.exit(1)
+`)
+  chmodSync(native, 0o755)
+  for (const key of ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH']) process.env[key] = native
+  const originalTree = ToolsObserve.getUITreeHandler
+  const originalFingerprint = ToolsObserve.getScreenFingerprintHandler
+  const originalNotify = ToolsNetwork.notifyActionStart
+  let networkStarts = 0
+  let reads = 0
+  let observationMode = 'normal'
+  let readDelay = 0
+  let uiState = 'Ready'
+  let propertyChange: Record<string, unknown> = {}
+  let platform: 'android' | 'ios' = 'android'
+  const device = () => ({ platform, id: 'fixture', osVersion: '16', model: 'Fixture', simulator: true })
+  const tree = () => {
+    const elements = [{ text: uiState, contentDescription: 'target', type: 'Button', stable_id: 'target', resourceId: 'target', bounds: [0, 0, 50, 50], enabled: true, visible: true, clickable: true, state: { checked: false }, ...propertyChange }]
+    const body = { device: device(), screen: '', resolution: { width: 100, height: 200 }, elements }
+    return { ...body, ...deriveSnapshotMetadata(`${platform}:fixture`, body, 'ui_tree') }
+  }
+  ToolsObserve.getUITreeHandler = async () => {
+    reads++
+    if (readDelay) await new Promise(resolve => setTimeout(resolve, readDelay))
+    if (process.env.MCP_CONDITION_PREPARE && readFileSync(changedPath, 'utf8') === 'changed') uiState = 'Changed during preparation'
+    if (observationMode === 'throw') throw new Error('offline')
+    const fresh = tree()
+    if (observationMode === 'error') return { ...fresh, error: 'offline' } as any
+    if (observationMode === 'invalid') return { ...fresh, snapshot_session_id: undefined } as any
+    if (observationMode === 'device') return { ...fresh, device: { ...device(), id: 'other' } } as any
+    return fresh
+  }
+  ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'unchanged-screen' }) as any
+  ToolsNetwork.notifyActionStart = () => { networkStarts++ }
+  _setDeviceListersForTests({ listAndroidDevices: async () => [device()], listIOSDevices: async () => [device()] })
+  const payload = (response: any) => JSON.parse(response.content[0].text)
+  const nativeInputs = () => readFileSync(eventsPath, 'utf8').split('\n').filter(line => /shell input|ui tap|ui swipe/.test(line))
+  const baseline = () => {
+    uiState = 'Ready'; propertyChange = {}; observationMode = 'normal'; readDelay = 0
+    const value = tree()
+    return { snapshotSessionId: value.snapshot_session_id, snapshotRevision: value.snapshot_revision }
+  }
+  const argsFor = (tool: string) => ({
+    platform, deviceId: 'fixture', verificationMode: 'none', responseMode: 'compact',
+    ...({ tap: { x: 10, y: 10 }, tap_element: { selector: { accessibility_id: 'target' } }, swipe: { x1: 10, y1: 10, x2: 20, y2: 20, duration: 100 }, type_text: { text: 'hello' }, press_back: {} }[tool])
+  })
+  const call = async (tool: string, extra: Record<string, unknown> = {}) => payload(await handleToolCall(tool, { ...argsFor(tool), ...extra }))
+  try {
+    resetSnapshotMetadataForTests()
+    // Exercise production dispatch adapters, not mocked ToolsInteract input handlers.
+    for (platform of ['android', 'ios'] as const) {
+      const tools = platform === 'android' ? ['tap', 'tap_element', 'swipe', 'type_text', 'press_back'] : ['tap', 'tap_element', 'swipe']
+      for (const tool of tools) {
+        const expectedState = baseline()
+        const inputs = nativeInputs().length
+        const starts = networkStarts
+        const result = await call(tool, { expectedState })
+        assert.equal(result.success, true, JSON.stringify(result))
+        assert.equal(result.condition.status, 'matched')
+        assert.equal(result.condition.observed.elements, undefined, 'compact matching conditions omit tree')
+        assert.equal(result.condition.observed.snapshot_revision, expectedState.snapshotRevision)
+        assert.equal(nativeInputs().length, inputs + 1, `${platform} ${tool} dispatches once`)
+        assert.equal(networkStarts, starts + 1)
+      }
+      // Change happens after ordinary resolution and metadata/capability preparation.
+      for (const tool of ['tap', 'tap_element', 'swipe']) {
+        const expectedState = baseline()
+        writeFileSync(changedPath, '')
+        process.env.MCP_CONDITION_PREPARE = '1'
+        const inputs = nativeInputs().length
+        const starts = networkStarts
+        const result = await call(tool, { expectedState, responseMode: 'debug' })
+        delete process.env.MCP_CONDITION_PREPARE
+        assert.equal(result.failure_code, 'PRECONDITION_FAILED', JSON.stringify(result))
+        assert.equal(result.dispatch_started, false)
+        assert.equal(result.condition.observed.elements[0].text, 'Changed during preparation')
+        assert.equal(nativeInputs().length, inputs)
+        assert.equal(networkStarts, starts)
+        assert.ok(!result.trace.steps.some((step: any) => step.stage === 'execute'))
+      }
+    }
+    platform = 'android'
+    for (const verificationMode of ['none', 'light', 'full']) for (const responseMode of ['compact', 'debug']) {
+      for (const changed of [{ text: 'Changed' }, { bounds: [1, 1, 51, 51] }, { enabled: false }, { state: { checked: true } }]) {
+        const expectedState = baseline()
+        propertyChange = changed
+        const inputs = nativeInputs().length
+        const starts = networkStarts
+        reads = 0
+        const result = await call('tap', { expectedState, verificationMode, responseMode })
+        assert.equal(result.failure_code, 'PRECONDITION_FAILED')
+        assert.equal(result.condition.status, 'mismatch')
+        assert.equal(result.retryable, false)
+        assert.equal(result.delivery_status, 'not_delivered')
+        assert.equal(result.verification.status, 'not_requested')
+        assert.deepEqual(result.condition.observed.elements[0], tree().elements[0])
+        assert.equal(reads, 1, 'no post-dispatch tree read after guard failure')
+        assert.equal(nativeInputs().length, inputs)
+        assert.equal(networkStarts, starts)
+      }
+      const expectedState = baseline()
+      const matched = await call('tap', { expectedState, verificationMode, responseMode })
+      assert.equal(matched.success, true)
+      assert.equal(matched.condition.status, 'matched')
+      assert.equal(Array.isArray(matched.condition.observed.elements), responseMode === 'debug')
+    }
+    for (const [mode, reason] of [['error', 'OBSERVATION_FAILED'], ['throw', 'OBSERVATION_FAILED'], ['invalid', 'OBSERVATION_INVALID'], ['device', 'DEVICE_MISMATCH']]) {
+      const expectedState = baseline()
+      observationMode = mode
+      const inputs = nativeInputs().length
+      const result = await call('tap', { expectedState })
+      assert.equal(result.failure_code, 'PRECONDITION_UNAVAILABLE')
+      assert.equal(result.condition.reason, reason)
+      assert.equal(result.condition.observed, null)
+      assert.equal(nativeInputs().length, inputs)
+    }
+    for (const expectation of [
+      { ...baseline(), snapshotSessionId: 'previous-process' },
+      { ...baseline(), snapshotRevision: 999999 }
+    ]) {
+      reads = 0
+      const result = await call('tap', { expectedState: expectation })
+      assert.equal(result.failure_code, 'PRECONDITION_UNAVAILABLE')
+      assert.equal(reads, 0, 'unknown expectations cannot authorize a read/input')
+    }
+    const foreign = baseline()
+    platform = 'ios'
+    const foreignResult = await call('tap', { expectedState: foreign })
+    assert.equal(foreignResult.condition.reason, 'BASELINE_UNAVAILABLE')
+    platform = 'android'
+    const expired = baseline()
+    const originalNow = Date.now
+    try {
+      Date.now = () => originalNow() + 11 * 60 * 1000
+      const result = await call('tap', { expectedState: expired })
+      assert.equal(result.condition.reason, 'BASELINE_UNAVAILABLE')
+    } finally { Date.now = originalNow }
+    const evicted = baseline()
+    for (let index = 0; index < 9; index++) { uiState = `screen-${index}`; tree() }
+    assert.equal((await call('tap', { expectedState: evicted })).condition.reason, 'BASELINE_UNAVAILABLE')
+
+    const timed = baseline()
+    readDelay = 180
+    const inputs = nativeInputs().length
+    const timedResult = await call('tap', { expectedState: { ...timed, timeoutMs: 100 } })
+    assert.equal(timedResult.condition.reason, 'CONDITION_TIMEOUT')
+    assert.equal(timedResult.dispatch_started, false)
+    assert.equal(nativeInputs().length, inputs, 'late observation never dispatches')
+    const budgeted = baseline()
+    readDelay = 180
+    const separate = await call('tap', { expectedState: budgeted, actionTimeoutMs: 150 })
+    assert.equal(separate.success, true, 'condition read does not consume the action budget')
+    const outerExpected = baseline()
+    readDelay = 180
+    const outerInputs = nativeInputs().length
+    const outer = await runWithBudget(150, () => call('tap', { expectedState: outerExpected, actionTimeoutMs: 5000 }))
+    assert.equal(outer.success, false)
+    assert.equal(nativeInputs().length, outerInputs, 'outer budget still prevents dispatch')
+
+    // A matched condition cannot turn a native dispatch failure into success.
+    const nativeFailure = baseline()
+    process.env.MCP_CONDITION_INPUT_FAIL = '1'
+    const failedInput = await call('tap', { expectedState: nativeFailure })
+    delete process.env.MCP_CONDITION_INPUT_FAIL
+    assert.equal(failedInput.success, false)
+    assert.equal(failedInput.condition.status, 'matched')
+    assert.equal(failedInput.dispatch_started, true)
+    assert.equal(failedInput.delivery_status, 'unknown')
+
+    const targetFailure = baseline()
+    const notChecked = await call('tap_element', { expectedState: targetFailure, selector: undefined, elementId: 'missing' })
+    assert.equal(notChecked.condition.status, 'not_checked')
+    assert.equal(notChecked.condition.reason, 'ACTION_NOT_REACHED')
+
+    const valid = baseline()
+    const badConditions: unknown[] = [null, {}, { ...valid, extra: true }, { ...valid, snapshotRevision: 0 }, { ...valid, snapshotRevision: Number.MAX_SAFE_INTEGER + 1 }, { ...valid, timeoutMs: 99 }, { ...valid, timeoutMs: '100' }, { ...valid, snapshotSessionId: '' }]
+    for (const expectedState of badConditions) {
+      const count = readFileSync(eventsPath, 'utf8').length
+      const result = await call('tap', { expectedState })
+      assert.match(result.error.message, /INVALID_ARGUMENT/)
+      assert.equal(readFileSync(eventsPath, 'utf8').length, count)
+    }
+    for (const extra of [{ platform: undefined }, { deviceId: 'booted' }, { deviceId: 'default' }, { deviceId: ' ' }, { platform: ['android'] }]) {
+      const result = await call('tap', { ...extra, expectedState: valid })
+      assert.match(result.error.message, /INVALID_ARGUMENT/)
+    }
+    for (const name of ['start_app', 'restart_app', 'terminate_app', 'reset_app_data', 'scroll_to_element', 'adjust_control', 'get_ui_tree']) {
+      const result = payload(await handleToolCall(name, { platform, deviceId: 'fixture', expectedState: valid }))
+      assert.match(result.error.message, /INVALID_ARGUMENT/)
+    }
+    for (const tool of toolDefinitions) {
+      assert.equal(!!tool.inputSchema.properties.expectedState, ['tap', 'tap_element', 'swipe', 'type_text', 'press_back'].includes(tool.name))
+    }
+    for (const responseMode of ['compact', 'debug']) {
+      const expectedState = baseline()
+      uiState = 'Changed'
+      const before = nativeInputs().length
+      const journey = payload(await handleToolCall('run_journey', { platform, deviceId: 'fixture', responseMode, defaults: { verificationMode: 'light' }, steps: [
+        { id: 'ready', type: 'wait', selector: { accessibility_id: 'target' }, timeoutMs: 500 },
+        { id: 'guarded', type: 'tap', selector: { accessibility_id: 'target' }, expectedState },
+        { id: 'later', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'target' } } }
+      ] }))
+      assert.equal(journey.stopped_at_step_id, 'guarded')
+      assert.equal(journey.steps[0].status, 'passed')
+      assert.equal(journey.steps[1].result.failure_code, 'PRECONDITION_FAILED')
+      assert.equal(journey.steps[1].result.condition.observed.elements[0].text, 'Changed')
+      assert.equal(journey.steps[1].result.verification.status, 'not_requested')
+      assert.equal(journey.steps[2].status, 'not_run')
+      assert.equal(nativeInputs().length, before)
+    }
+    // Calls overlap, but only the request with its own expectation is rejected.
+    const overlapping = baseline()
+    uiState = 'Changed'
+    const before = nativeInputs().length
+    const [guarded, unguarded] = await Promise.all([call('tap', { expectedState: overlapping }), call('tap')])
+    assert.equal(guarded.failure_code, 'PRECONDITION_FAILED')
+    assert.equal(unguarded.success, true)
+    assert.equal(unguarded.condition, undefined)
+    assert.equal(nativeInputs().length, before + 1)
+    assert.equal(getSnapshotSessionId(), valid.snapshotSessionId)
+    // Complete native observation + input paths with fake platform tools, including
+    // subprocess timeout cleanup. No mocked tree or adapter is used in these checks.
+    ToolsObserve.getUITreeHandler = originalTree
+    for (platform of ['android', 'ios'] as const) {
+      delete process.env.MCP_CONDITION_TREE_TEXT
+      const observed: any = await ToolsObserve.getUITreeHandler({ platform, deviceId: 'fixture' })
+      assert.equal(observed.error, undefined)
+      const expectedState = { snapshotSessionId: observed.snapshot_session_id, snapshotRevision: observed.snapshot_revision }
+      const matched = await call('tap', { expectedState })
+      assert.equal(matched.success, true, JSON.stringify(matched))
+      process.env.MCP_CONDITION_TREE_TEXT = 'Changed through native hierarchy'
+      const before = nativeInputs().length
+      const mismatch = await call('tap', { expectedState })
+      assert.equal(mismatch.failure_code, 'PRECONDITION_FAILED', JSON.stringify(mismatch))
+      assert.equal(mismatch.condition.observed.elements[0].text, 'Changed through native hierarchy')
+      assert.equal(nativeInputs().length, before)
+      const compact: any = await ToolsObserve.getUITreeHandler({ platform, deviceId: 'fixture', responseMode: 'compact' })
+      assert.equal(compact.snapshot_session_id, expectedState.snapshotSessionId)
+      const current: any = await ToolsObserve.getUITreeHandler({ platform, deviceId: 'fixture' })
+      process.env.MCP_CONDITION_SLOW = '1'
+      writeFileSync(changedPath, '')
+      const unavailable = await call('tap', { expectedState: { snapshotSessionId: current.snapshot_session_id, snapshotRevision: current.snapshot_revision, timeoutMs: 1200 } })
+      delete process.env.MCP_CONDITION_SLOW
+      assert.equal(unavailable.condition.reason, 'CONDITION_TIMEOUT', JSON.stringify(unavailable))
+      assert.equal(unavailable.dispatch_started, false)
+      assert.equal(readFileSync(changedPath, 'utf8'), 'closed', 'timed-out hierarchy subprocess closed before response')
+      assert.equal(nativeInputs().length, before)
+    }
+    console.log('Conditional actions: PASS (production Android/iOS input adapters with fake native tools)')
+  } finally {
+    ToolsObserve.getUITreeHandler = originalTree
+    ToolsObserve.getScreenFingerprintHandler = originalFingerprint
+    ToolsNetwork.notifyActionStart = originalNotify
+    _resetDeviceListersForTests()
+    resetSnapshotMetadataForTests()
+    for (const key of envKeys) {
+      if (originalEnv[key] === undefined) delete process.env[key]
+      else process.env[key] = originalEnv[key]
+    }
+    rmSync(directory, { recursive: true, force: true })
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })