mobile-debug-mcp 0.32.4 → 0.33.0

package/src/utils/resolve-device.ts

@@ -1,3 +1,4 @@
+import { bindEvidenceDevice } from '../observe/evidence.js'
 import { retainConnectedDeviceSnapshots } from '../observe/snapshot-metadata.js'
 import { measure } from './timing.js'
 import { AsyncLocalStorage } from 'node:async_hooks'
@@ -50,10 +51,17 @@ export async function listDevices(platform?: "android" | "ios", appId?: string):
 const deviceContext = new AsyncLocalStorage<DeviceInfo>()
 
 export function withResolvedDevice<T>(device: DeviceInfo, operation: () => Promise<T>): Promise<T> {
+  bindEvidenceDevice(device)
   return deviceContext.run(device, operation)
 }
 
 export async function resolveTargetDevice(opts: ResolveOptions): Promise<DeviceInfo> {
+  const device = await resolveDevice(opts)
+  bindEvidenceDevice(device)
+  return device
+}
+
+async function resolveDevice(opts: ResolveOptions): Promise<DeviceInfo> {
   const { platform, appId, prefer, deviceId } = opts
   const current = deviceContext.getStore()
   if (current && current.platform === platform && (!deviceId || current.id === deviceId)) return current

package/test/device/automated/observe/correlated-evidence.smoke.ts

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+// Exercises the rebuilt stdio server, not the connected/published MCP instance.
+async function run() {
+  if (process.env.SKIP_DEVICE_TESTS === '1') {
+    console.log('Correlated evidence device smoke: SKIPPED (SKIP_DEVICE_TESTS=1)')
+    return
+  }
+  const client = new Client({ name: 'correlated-evidence-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const parse = (response: any) => JSON.parse(response.content.find((item: any) => item.type === 'text').text)
+  const call = (name: string, args: Record<string, unknown> = {}) => client.callTool({ name, arguments: args }, undefined, { timeout: 120000 })
+  try {
+    await client.connect(transport)
+    const discovery = parse(await call('list_devices'))
+    for (const platform of ['android', 'ios'] as const) {
+      const device = discovery.devices.find((d: any) => d.platform === platform && d.simulator &&
+        (platform === 'android' || d.booted === true))
+      assert.ok(device, `A running ${platform} emulator/simulator is required`)
+      const target = { platform, deviceId: device.id }
+      const appId = platform === 'android' ? 'com.android.settings' : 'com.apple.Preferences'
+      const action = parse(await call('start_app', { ...target, appId, verificationMode: 'none', responseMode: 'compact' }))
+      assert.equal(action.success, true, JSON.stringify(action))
+      assert.equal(action.action_id, action.evidence.action_id)
+      assert.ok(action.evidence.dispatch_started_at_ms)
+      assert.ok(action.evidence.dispatch_completed_at_ms >= action.evidence.dispatch_started_at_ms)
+      assert.equal(action.evidence.verification_completed_at_ms, null)
+      const actionRef = { sessionId: action.evidence.session_id, actionId: action.evidence.action_id }
+      const screenResponse: any = await call('capture_screenshot', { ...target, actionRef })
+      const screen = parse(screenResponse)
+      assert.equal(screen.evidence.action_id, action.action_id)
+      assert.equal(screen.evidence.correlation_id, action.evidence.correlation_id)
+      assert.equal(screen.evidence.association, 'explicit')
+      assert.ok(screenResponse.content.some((item: any) => item.type === 'image' && item.data.length > 0))
+      const screenshot = screen.evidence.observations.find((v: any) => v.kind === 'screenshot')
+      assert.equal(screenshot.status, 'captured')
+      assert.equal(screenshot.freshness, 'fresh')
+      assert.ok(screenshot.capture_started_at_ms >= action.evidence.dispatch_completed_at_ms)
+      const logsResponse: any = await call('get_logs', { ...target, appId, limit: 5, actionRef })
+      const logs = parse(logsResponse)
+      assert.equal(logs.evidence.action_id, action.action_id)
+      assert.ok(Array.isArray(JSON.parse(logsResponse.content[1].text).logs))
+      const log = logs.evidence.observations.find((v: any) => v.kind === 'logs')
+      assert.equal(log.status, 'captured', log.error)
+      assert.equal(log.event_time_comparable, false)
+      assert.equal(log.freshness, 'unknown')
+      const snapshot = parse(await call('capture_debug_snapshot', { ...target, actionRef, includeScreenshot: false, includeLogs: false }))
+      assert.equal(snapshot.evidence.action_id, action.action_id)
+      assert.equal(snapshot.raw.screenshot, null)
+      assert.equal(snapshot.evidence.observations.find((v: any) => v.kind === 'screenshot').status, 'omitted')
+      assert.equal(snapshot.evidence.observations.find((v: any) => v.kind === 'logs').status, 'omitted')
+      assert.ok(snapshot.evidence.observations.every((v: any) => !v.device || v.device.id === device.id))
+      const tree = snapshot.evidence.observations.find((v: any) => v.kind === 'ui_tree')
+      assert.equal(tree.status, 'captured', tree.error)
+      const unassociated = parse(await call('get_ui_tree', { ...target, responseMode: 'compact', actionRef: { ...actionRef, sessionId: 'previous-process' } }))
+      assert.equal(unassociated.evidence.association_reason, 'SESSION_MISMATCH')
+      assert.equal(unassociated.evidence.action_id, null)
+      console.log(JSON.stringify({ status: 'PASS', server: client.getServerVersion(), platform, device: device.id,
+        osVersion: device.osVersion, startingApp: appId, actionId: action.action_id,
+        phases: { dispatchStarted: action.evidence.dispatch_started_at_ms, dispatchCompleted: action.evidence.dispatch_completed_at_ms,
+          screenshotStarted: screenshot.capture_started_at_ms, screenshotCompleted: screenshot.capture_completed_at_ms },
+        screenshot: screenshot.status, logs: log.status, uiTree: tree.status,
+        disabledComponents: 'omitted', foreignReference: 'unavailable',
+        cleanup: 'No settings, app data or streams changed; Settings remains foreground. No content artifacts saved.' }))
+    }
+  } finally { await client.close() }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/device/manual/interact/conditional_actions.manual.ts

@@ -0,0 +1,95 @@
+// Run against a built checkout and an explicitly selected simulator in system Settings.
+import assert from 'node:assert/strict'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { writeFile } from 'node:fs/promises'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+function arg(name: string) { const index = process.argv.indexOf(name); return index >= 0 ? process.argv[index + 1] : undefined }
+async function run() {
+  const platform = arg('--platform')
+  const deviceId = arg('--id')
+  const targetText = arg('--target-text')
+  const destinationText = arg('--destination-text')
+  const output = arg('--output')
+  assert.ok(platform === 'android' || platform === 'ios', '--platform android|ios is required')
+  assert.ok(deviceId && targetText && destinationText && output, '--id, --target-text, --destination-text and --output are required')
+  const repository = fileURLToPath(new URL('../../../../', import.meta.url))
+  const transport = new StdioClientTransport({ command: process.execPath, args: [path.join(repository, 'dist/server.js')], cwd: repository, stderr: 'pipe' })
+  const client = new Client({ name: 'conditional-device-verification', version: '1.0.0' })
+  const evidence: any = { platform, deviceId, checked_at: new Date().toISOString(), source: 'built dist/server.js over MCP stdio', scenarios: [] }
+  transport.stderr?.on('data', chunk => process.stderr.write(chunk))
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const result = await client.callTool({ name, arguments: { platform, deviceId, ...args } }, undefined, { timeout: 120000 })
+    const item: any = result.content.find((item: any) => item.type === 'text')
+    return JSON.parse(item.text)
+  }
+  const observe = async () => {
+    const result = await call('get_ui_tree', {})
+    assert.equal(result.error, undefined, JSON.stringify(result))
+    assert.ok(result.resolution.width > 0 && result.elements.length > 0, 'nonempty usable hierarchy required')
+    return result
+  }
+  const contains = (tree: any, text: string) => tree.elements.some((element: any) => element.text === text || element.contentDescription === text || element.resourceId === text)
+  try {
+    await client.connect(transport)
+    evidence.server = client.getServerVersion()
+    const tools = await client.listTools()
+    assert.ok((tools.tools.find(tool => tool.name === 'tap')?.inputSchema.properties as any)?.expectedState, 'newly built server advertises the condition')
+    const baseline = await observe()
+    assert.ok(contains(baseline, targetText), `starting screen must contain ${targetText}`)
+    assert.ok(!contains(baseline, destinationText), 'destination must not already be present on the starting screen')
+    const expectedState = { snapshotSessionId: baseline.snapshot_session_id, snapshotRevision: baseline.snapshot_revision, timeoutMs: 30000 }
+    const target = baseline.elements.find((element: any) => element.text === targetText)
+    assert.ok(target?.bounds, `target ${targetText} needs bounds`)
+    const [left, top, right, bottom] = target.bounds
+    const matched = await call('tap', { x: Math.floor((left + right) / 2), y: Math.floor((top + bottom) / 2), expectedState, verificationMode: 'none', responseMode: 'compact', actionTimeoutMs: 30000 })
+    evidence.scenarios.push({ name: 'matching snapshot dispatch', result: matched })
+    assert.equal(matched.success, true, JSON.stringify(matched))
+    assert.equal(matched.condition.status, 'matched')
+    const destination = await observe()
+    assert.ok(contains(destination, destinationText), `destination must contain ${destinationText}`)
+    evidence.scenarios[0].observed_destination = { snapshot_revision: destination.snapshot_revision, labels: destination.elements.map((e: any) => e.text || e.contentDescription).filter(Boolean) }
+    evidence.scenarios[0].status = 'pass'
+    const back = destination.elements.find((element: any) => element.contentDescription === 'Navigate up' || element.contentDescription === 'Back' || (element.text === 'Settings' && element.clickable))
+    assert.ok(back, 'safe back-navigation target required on destination')
+    const [bl, bt, br, bb] = back.bounds
+    const selector = back.resourceId ? { resource_id: back.resourceId } :
+      back.text ? { text: back.text } : { accessibility_id: back.contentDescription }
+    for (const responseMode of ['compact', 'debug']) {
+      const mismatch = await call('tap', { x: Math.floor((bl + br) / 2), y: Math.floor((bt + bb) / 2), expectedState, verificationMode: 'none', responseMode, actionTimeoutMs: 30000 })
+      evidence.scenarios.push({ name: `mismatch blocks back navigation (${responseMode})`, result: mismatch })
+      assert.equal(mismatch.failure_code, 'PRECONDITION_FAILED', JSON.stringify(mismatch))
+      assert.equal(mismatch.dispatch_started, false)
+      assert.equal(mismatch.delivery_status, 'not_delivered')
+      assert.ok(contains(mismatch.condition.observed, destinationText))
+      const after = await observe()
+      assert.ok(contains(after, destinationText), 'blocked back navigation must leave destination visible')
+      evidence.scenarios.at(-1).status = 'pass'
+      const journey = await call('run_journey', { responseMode, defaults: { verificationMode: 'none', actionTimeoutMs: 30000 }, steps: [
+        { id: 'destination-visible', type: 'wait', selector: { text: destinationText }, condition: 'visible', timeoutMs: 30000 },
+        { id: 'conditional-back', type: 'tap', selector, waitFor: { condition: 'visible', timeoutMs: 10000 }, expectedState },
+        { id: 'must-not-run', type: 'tap', selector, waitFor: { condition: 'visible', timeoutMs: 10000 } }
+      ] })
+      evidence.scenarios.push({ name: `conditional journey stops (${responseMode})`, result: journey })
+      assert.equal(journey.stopped_at_step_id, 'conditional-back', JSON.stringify(journey))
+      assert.equal(journey.steps[0].status, 'passed')
+      assert.equal(journey.steps[1].result.failure_code, 'PRECONDITION_FAILED')
+      assert.ok(contains(journey.steps[1].result.condition.observed, destinationText))
+      assert.equal(journey.steps[2].status, 'not_run')
+      assert.ok(contains(await observe(), destinationText))
+      evidence.scenarios.at(-1).status = 'pass'
+    }
+    evidence.status = 'pass'
+    console.log(JSON.stringify({ platform, deviceId, server: evidence.server, status: evidence.status, scenarios: evidence.scenarios.map((scenario: any) => ({ name: scenario.name, status: scenario.status })), output }, null, 2))
+  } catch (error) {
+    evidence.status = 'fail'
+    evidence.error = String(error)
+    throw error
+  } finally {
+    await writeFile(output!, JSON.stringify(evidence, null, 2))
+    await client.close()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/device/manual/interact/modul8_selector_tap.manual.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import { writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+// Explicit Modul8 fixture: run after npm run build with the Android emulator booted.
+async function run() {
+  const client = new Client({ name: 'modul8-selector-tap-verification', version: '1' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const target = { platform: 'android', deviceId: 'emulator-5554' }
+  const report: any = { verified_on: new Date().toISOString(), device: target, package: 'com.ideamechanics.modul8.dev',
+    source: 'rebuilt local MCP stdio server', build_sha256: createHash('sha256').update(readFileSync('dist/server/tool-handlers.js')).digest('hex'),
+    steps: [], status: 'UNRUN', cleanup: 'UNRUN' }
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const response: any = await client.callTool({ name, arguments: { ...target, ...args } }, undefined, { timeout: 120000 })
+    return JSON.parse(response.content.find((item: any) => item.type === 'text').text)
+  }
+  const assertVisible = async (selector: Record<string, string>) => {
+    const result = await call('expect_element_visible', { selector, timeout_ms: 10000, poll_interval_ms: 100 })
+    assert.equal(result.success, true, `Visible fixture landmark: ${JSON.stringify(selector)}`)
+  }
+  const tap = async (text: string, condition?: string) => {
+    const args: Record<string, unknown> = { selector: { text }, verificationMode: 'none', responseMode: condition ? 'debug' : 'compact' }
+    if (condition) { args.waitFor = { condition, timeoutMs: 10000 }; args.actionTimeoutMs = 15000 }
+    const result = await call('tap_element', args)
+    report.steps.push({ selector: { text }, waitForCondition: condition ?? 'default', status: result.success ? 'PASS' : 'FAIL',
+      failure_code: result.failure_code ?? null, resolved_target: result.target?.resolved, evidence: result.evidence })
+    assert.equal(result.success, true, `tap_element ${text}: ${result.failure_code ?? result.error?.message}`)
+    assert.ok(result.evidence.dispatch_started_at_ms)
+    assert.ok(result.evidence.dispatch_completed_at_ms >= result.evidence.dispatch_started_at_ms)
+    assert.equal(result.evidence.verification_completed_at_ms, null)
+  }
+  try {
+    await client.connect(transport)
+    report.server = client.getServerVersion()
+    const launch = await call('start_app', { appId: report.package, verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(launch.success, true)
+    await assertVisible({ text: 'Subscription' })
+    report.starting_state = 'Subscription'
+    await tap('FAVOURITES')
+    await assertVisible({ accessibility_id: 'Favourites' })
+    await tap('GENER8')
+    await assertVisible({ text: 'Personalised breathing' })
+    await tap('SETTINGS', 'exists')
+    await assertVisible({ text: 'Subscription' })
+    await tap('FAVOURITES', 'visible')
+    await assertVisible({ accessibility_id: 'Favourites' })
+    await tap('SETTINGS')
+    await assertVisible({ text: 'Subscription' })
+    report.cleanup = 'PASS: restored Subscription; no settings, account data, favourites or sessions changed; no streams or screenshots created'
+    report.status = 'PASS'
+  } catch (error) {
+    report.status = 'FAIL'; report.error = String(error)
+    throw error
+  } finally {
+    writeFileSync('docs/specs/022-correlated-evidence/modul8-selector-fix-evidence.json', JSON.stringify(report, null, 2) + '\n')
+    console.log(JSON.stringify({ status: report.status, server: report.server, device: target, steps: report.steps.map((s: any) => ({ selector: s.selector, condition: s.waitForCondition, status: s.status })), cleanup: report.cleanup }))
+    await client.close()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/device/manual/interact/readiness.manual.ts

@@ -0,0 +1,99 @@
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { rmSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildReadinessFixture, readinessAppId } from '../../../fixtures/readiness-app/build.js'
+
+const arg = (name: string) => { const index = process.argv.indexOf(name); return index >= 0 ? process.argv[index + 1] : undefined }
+async function run() {
+  const platform = arg('--platform')
+  const deviceId = arg('--id')
+  const output = arg('--output')
+  assert.ok(platform === 'android' || platform === 'ios')
+  assert.ok(deviceId && output, '--id and --output are required')
+  const repository = fileURLToPath(new URL('../../../../', import.meta.url))
+  const client = new Client({ name: 'readiness-device-verification', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: [path.join(repository, 'dist/server.js')], cwd: repository, stderr: 'pipe' })
+  transport.stderr?.on('data', chunk => process.stderr.write(chunk))
+  const evidence: any = { platform, deviceId, source: 'built dist/server.js over MCP stdio', checked_at: new Date().toISOString(), scenarios: [] }
+  let fixture: ReturnType<typeof buildReadinessFixture> | undefined
+  let installed = false
+  let restoreApp: string | undefined
+  const call = async (name: string, args: any = {}) => {
+    const result = await client.callTool({ name, arguments: { platform, deviceId, ...args } }, undefined, { timeout: 120000 })
+    const item: any = result.content.find((item: any) => item.type === 'text')
+    return JSON.parse(item.text)
+  }
+  const record = (name: string, result: any) => { evidence.scenarios.push({ name, result }); return result }
+  try {
+    await client.connect(transport)
+    evidence.server = client.getServerVersion()
+    const devices = await call('list_devices', { appId: readinessAppId })
+    const device = devices.devices.find((device: any) => device.id === deviceId)
+    assert.ok(device?.simulator, 'fixture mutations require an explicitly selected simulator')
+    assert.ok(!device.appInstalled, 'refuse to replace a pre-existing fixture app')
+    if (platform === 'android') restoreApp = (await call('get_current_screen')).package
+    fixture = buildReadinessFixture(platform)
+    const install = await call('install_app', { projectType: 'native', appPath: fixture.artifact })
+    assert.equal(install.installed, true, JSON.stringify(install))
+    installed = true
+    assert.equal((await call('start_app', { appId: readinessAppId, verificationMode: 'none', responseMode: 'compact' })).success, true)
+    const tree = await call('get_ui_tree')
+    assert.equal(tree.readiness.state, 'unknown', 'single-sample tree never settles')
+    evidence.initial_tree = tree
+    const target = tree.elements.find((element: any) => element.contentDescription === 'show-loader' || element.resourceId === 'show-loader' || element.text?.toLowerCase() === 'show loader')
+    assert.ok(target?.bounds)
+    const [left, top, right, bottom] = target.bounds
+    const trigger = () => call('tap', { x: (left + right) / 2, y: (top + bottom) / 2, verificationMode: 'none', responseMode: 'compact' })
+    const stable = record('stable foreground UI', await call('get_app_readiness'))
+    assert.equal(stable.success, true, JSON.stringify(stable))
+    assert.equal(stable.readiness.state, 'settled')
+    assert.equal(stable.readiness.capabilities.unresponsive, false)
+    evidence.scenarios.at(-1).status = 'pass'
+    assert.equal((await trigger()).success, true)
+    const loading = record('controlled loader observation', await call('get_app_readiness'))
+    assert.equal(loading.readiness.state, 'loading', JSON.stringify(loading))
+    evidence.scenarios.at(-1).status = 'pass'
+    const bounded = record('bounded wait cannot claim readiness', await call('wait_for_app_ready', { timeoutMs: 100, pollIntervalMs: 100 }))
+    assert.equal(bounded.success, false)
+    assert.ok(bounded.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    assert.notEqual(bounded.readiness.state, 'unresponsive')
+    evidence.scenarios.at(-1).status = 'pass'
+    const predicate = record('visible predicate waits for loader completion', await call('wait_for_ui', { selector: { text: 'Ready' }, condition: 'visible', requireReady: true, timeout_ms: 30000, poll_interval_ms: 500 }))
+    assert.equal(predicate.status, 'success', JSON.stringify(predicate))
+    assert.equal(predicate.readiness.state, 'settled')
+    const finished = await call('get_ui_tree')
+    assert.ok(finished.elements.some((element: any) => element.text === 'Done'))
+    evidence.scenarios.at(-1).status = 'pass'
+    assert.equal((await trigger()).success, true)
+    const changed = record('changed UI settles after loader', await call('wait_for_ui_change', { requireReady: true, timeout_ms: 30000, stability_window_ms: 0 }))
+    assert.equal(changed.success, true, JSON.stringify(changed))
+    assert.equal(changed.readiness.state, 'settled')
+    evidence.scenarios.at(-1).status = 'pass'
+    const wait = record('readiness wait succeeds on settled content', await call('wait_for_app_ready', { timeoutMs: 15000 }))
+    assert.equal(wait.success, true)
+    assert.equal(wait.readiness.state, 'settled')
+    evidence.scenarios.at(-1).status = 'pass'
+    evidence.status = 'pass'
+    console.log(JSON.stringify({ platform, deviceId, status: 'pass', scenarios: evidence.scenarios.map((entry: any) => ({ name: entry.name, status: entry.status })), output }, null, 2))
+  } catch (error) { evidence.status = 'fail'; evidence.error = String(error); throw error }
+  finally {
+    if (installed) {
+      await call('terminate_app', { appId: readinessAppId }).catch(() => null)
+      try {
+        if (platform === 'android') execFileSync(process.env.ADB_PATH || path.join(process.env.HOME!, 'Library/Android/sdk/platform-tools/adb'), ['-s', deviceId!, 'uninstall', readinessAppId], { stdio: 'pipe', timeout: 30000 })
+        else execFileSync('xcrun', ['simctl', 'uninstall', deviceId!, readinessAppId], { stdio: 'pipe', timeout: 30000 })
+        evidence.cleanup = 'fixture uninstalled'
+      } catch (error) { evidence.cleanup = String(error) }
+      if (restoreApp) await call('start_app', { appId: restoreApp, verificationMode: 'none', responseMode: 'compact' }).catch(() => null)
+    }
+    if (fixture) rmSync(fixture.directory, { recursive: true, force: true })
+    await writeFile(output!, JSON.stringify(evidence, null, 2))
+    await client.close()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/fixtures/readiness-app/MainActivity.java

@@ -0,0 +1,23 @@
+package tools.mobiledebug.readinessfixture;
+import android.app.Activity;
+import android.os.Bundle;
+import android.os.Handler;
+import android.widget.*;
+import android.view.View;
+public class MainActivity extends Activity {
+  private int generation = 0;
+  public void onCreate(Bundle state) {
+    super.onCreate(state);
+    LinearLayout layout = new LinearLayout(this);
+    layout.setOrientation(LinearLayout.VERTICAL); layout.setPadding(32, 120, 32, 32);
+    TextView ready = new TextView(this); ready.setText("Ready"); ready.setContentDescription("ready"); layout.addView(ready);
+    TextView status = new TextView(this); status.setText("Idle"); layout.addView(status);
+    ProgressBar loader = new ProgressBar(this); loader.setVisibility(View.GONE); layout.addView(loader);
+    Button start = new Button(this); start.setText("Show loader"); start.setContentDescription("show-loader"); layout.addView(start);
+    start.setOnClickListener(view -> {
+      int current = ++generation; loader.setVisibility(View.VISIBLE); status.setText("Loading");
+      new Handler(getMainLooper()).postDelayed(() -> { if (current == generation) { loader.setVisibility(View.GONE); status.setText("Done"); } }, 12000);
+    });
+    setContentView(layout);
+  }
+}

package/test/fixtures/readiness-app/README.md

@@ -0,0 +1,12 @@
+# Readiness fixture
+
+Offline native Android/iOS simulator apps used only for explicit readiness
+verification. Ready stays visible while Show loader starts a 12-second loader;
+completion hides the loader and changes its status to Done. No permissions,
+accounts, networking, or persistence are used. These are test apps, not hierarchy
+inspection helpers.
+
+The manual helper builds them in a temporary directory with Android SDK 36 /
+build-tools 36.0.0 and the installed JDK, or the installed iOS simulator SDK and
+Clang. It installs only on an explicitly selected simulator and cleans up its
+own app and temporary artifacts afterward.

package/test/fixtures/readiness-app/build.ts

@@ -0,0 +1,37 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const readinessAppId = 'tools.mobiledebug.readinessfixture'
+export function buildReadinessFixture(platform: 'android' | 'ios') {
+  const source = path.dirname(fileURLToPath(import.meta.url))
+  const directory = mkdtempSync(path.join(tmpdir(), `mcp-readiness-${platform}-`))
+  const java = process.env.JAVA_HOME ?? (existsSync('/Applications/Android Studio.app/Contents/jbr/Contents/Home') ? '/Applications/Android Studio.app/Contents/jbr/Contents/Home' : undefined)
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: directory, encoding: 'utf8', env: { ...process.env, ...(java ? { JAVA_HOME: java } : {}) }, stdio: 'pipe' })
+  if (platform === 'ios') {
+    const sdk = run('xcrun', ['--sdk', 'iphonesimulator', '--show-sdk-path']).trim()
+    const artifact = path.join(directory, 'Readiness.app'); mkdirSync(artifact)
+    writeFileSync(path.join(artifact, 'Info.plist'), `<?xml version="1.0" encoding="UTF-8"?><plist version="1.0"><dict><key>CFBundleExecutable</key><string>Readiness</string><key>CFBundleIdentifier</key><string>${readinessAppId}</string><key>CFBundleName</key><string>Readiness fixture</string><key>CFBundlePackageType</key><string>APPL</string><key>CFBundleVersion</key><string>1</string><key>CFBundleShortVersionString</key><string>1.0</string><key>LSRequiresIPhoneOS</key><true/><key>MinimumOSVersion</key><string>18.0</string><key>UILaunchScreen</key><dict/></dict></plist>`)
+    run('xcrun', ['--sdk', 'iphonesimulator', 'clang', '-target', `${process.arch === 'arm64' ? 'arm64' : 'x86_64'}-apple-ios18.0-simulator`, '-isysroot', sdk, '-fobjc-arc', '-framework', 'UIKit', '-framework', 'Foundation', path.join(source, 'main.m'), '-o', path.join(artifact, 'Readiness')])
+    run('codesign', ['--force', '--sign', '-', artifact])
+    return { artifact, directory }
+  }
+  const sdk = process.env.ANDROID_HOME ?? path.join(process.env.HOME!, 'Library/Android/sdk')
+  const tools = path.join(sdk, 'build-tools/36.0.0')
+  const androidJar = path.join(sdk, 'platforms/android-36/android.jar')
+  const jdk = (name: string) => java ? path.join(java, 'bin', name) : name
+  mkdirSync(path.join(directory, 'classes'))
+  writeFileSync(path.join(directory, 'AndroidManifest.xml'), `<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="${readinessAppId}" android:versionCode="1" android:versionName="1.0"><uses-sdk android:minSdkVersion="26" android:targetSdkVersion="36"/><application android:label="Readiness fixture" android:theme="@android:style/Theme.Material.Light.NoActionBar"><activity android:name=".MainActivity" android:exported="true"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter></activity></application></manifest>`)
+  run(jdk('javac'), ['--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(source, 'MainActivity.java')])
+  run(jdk('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
+  run(path.join(tools, 'd8'), ['--lib', androidJar, '--output', directory, 'classes.jar'])
+  run(path.join(tools, 'aapt2'), ['link', '-I', androidJar, '--manifest', 'AndroidManifest.xml', '-o', 'unsigned.apk'])
+  run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
+  run(path.join(tools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
+  run(jdk('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Readiness Fixture', '-keyalg', 'RSA', '-validity', '365'])
+  const artifact = path.join(directory, 'Readiness.apk')
+  run(path.join(tools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', artifact, 'aligned.apk'])
+  return { artifact, directory }
+}

package/test/fixtures/readiness-app/main.m

@@ -0,0 +1,27 @@
+#import <UIKit/UIKit.h>
+@interface ReadinessApp : UIResponder <UIApplicationDelegate>
+@property(strong, nonatomic) UIWindow *window;
+@property(strong, nonatomic) UILabel *status;
+@property(strong, nonatomic) UIActivityIndicatorView *loader;
+@property(nonatomic) NSInteger generation;
+@end
+@implementation ReadinessApp
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)options {
+  self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];
+  UIViewController *controller = [UIViewController new]; controller.view.backgroundColor = UIColor.whiteColor;
+  self.window.rootViewController = controller;
+  UILabel *ready = [[UILabel alloc] initWithFrame:CGRectMake(30, 140, 300, 50)]; ready.text = @"Ready"; ready.accessibilityIdentifier = @"ready";
+  [controller.view addSubview:ready];
+  self.status = [[UILabel alloc] initWithFrame:CGRectMake(30, 200, 300, 50)]; self.status.text = @"Idle"; [controller.view addSubview:self.status];
+  self.loader = [[UIActivityIndicatorView alloc] initWithActivityIndicatorStyle:UIActivityIndicatorViewStyleMedium]; self.loader.frame = CGRectMake(30, 260, 50, 50); [controller.view addSubview:self.loader];
+  UIButton *start = [UIButton buttonWithType:UIButtonTypeSystem]; start.frame = CGRectMake(30, 340, 300, 60);
+  [start setTitle:@"Show loader" forState:UIControlStateNormal]; start.accessibilityIdentifier = @"show-loader";
+  [start addTarget:self action:@selector(showLoader) forControlEvents:UIControlEventTouchUpInside]; [controller.view addSubview:start];
+  [self.window makeKeyAndVisible]; return YES;
+}
+- (void)showLoader {
+  NSInteger current = ++self.generation; self.status.text = @"Loading"; [self.loader startAnimating];
+  dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 12 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{ if (current == self.generation) { self.status.text = @"Done"; [self.loader stopAnimating]; } });
+}
+@end
+int main(int argc, char **argv) { @autoreleasepool { return UIApplicationMain(argc, argv, nil, NSStringFromClass(ReadinessApp.class)); } }

package/test/unit/observe/android_tree_acquisition.test.ts

@@ -36,6 +36,8 @@ else process.exit(1)
     const first = await observe.getUITree('fake-a')
     const second = await observe.getUITree('fake-b')
     assert.equal(first.error, undefined)
+    assert.equal(typeof first.snapshot_session_id, 'string')
+    assert.equal(first.snapshot_session_id, second.snapshot_session_id)
     assert.equal(second.error, undefined)
     assert.equal(first.snapshot_revision, 1)
     assert.notEqual(first.snapshot_revision, second.snapshot_revision)

package/test/unit/observe/capture_debug_snapshot.test.ts

@@ -1,5 +1,6 @@
 import { ToolsObserve } from '../../../src/observe/index.js'
 import assert from 'assert'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
 
 async function run() {
   console.log('Starting capture_debug_snapshot unit tests...')
@@ -12,24 +13,41 @@ async function run() {
   const origReadLogStreamHandler = (ToolsObserve as any).readLogStreamHandler
   const origGetLogsHandler = (ToolsObserve as any).getLogsHandler
 
+  const device = { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }
+  let resolutions = 0
+  _setDeviceListersForTests({
+    listAndroidDevices: async () => { resolutions++; return [device] },
+    listIOSDevices: async () => { throw new Error('Android snapshot must not discover iOS devices') }
+  })
+  const assertTarget = (args: any) => {
+    assert.strictEqual(args.platform, 'android')
+    assert.strictEqual(args.deviceId, device.id, 'Every component must use the resolved fixture device')
+  }
+
   try {
     // --- Test 1: all components succeed and logs come from stream ---
-    ;(ToolsObserve as any).captureScreenshotHandler = async function() {
+    ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) {
+      assertTarget(args)
       return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screenshot: 'BASE64PNG', resolution: { width: 1080, height: 1920 } }
     }
-    ;(ToolsObserve as any).getCurrentScreenHandler = async function() {
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function(args: any) {
+      assert.strictEqual(args.deviceId, device.id)
       return { device: { platform: 'android', id: 'mock' }, package: 'com.example', activity: 'com.example.Main', shortActivity: 'Main' }
     }
-    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() {
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function(args: any) {
+      assertTarget(args)
       return { fingerprint: 'abc123', activity: 'Main' }
     }
-    ;(ToolsObserve as any).getUITreeHandler = async function() {
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) {
+      assertTarget(args)
       return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] }
     }
-    ;(ToolsObserve as any).readLogStreamHandler = async function() {
+    ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) {
+      assertTarget(args)
       return { entries: [ { timestamp: '2026-03-23T20:00:00.000Z', level: 'ERROR', message: 'Boom' } ], crash_summary: { crash_detected: true } }
     }
-    ;(ToolsObserve as any).getLogsHandler = async function() {
+    ;(ToolsObserve as any).getLogsHandler = async function(args: any) {
+      assertTarget(args)
       return { device: { platform: 'android', id: 'mock' }, logs: [], logCount: 0 }
     }
 
@@ -41,20 +59,13 @@ async function run() {
     assert.strictEqual(res1.semantic.confidence >= 0.7, true)
     assert.deepStrictEqual(res1.semantic.actions_available, null)
     console.log('Test 1:', pass1 ? 'PASS' : 'FAIL')
-
-    // Restore handlers before next test
-    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
-    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
-    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
-    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
-    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
-    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
+    assert.strictEqual(resolutions, 1, 'Resolve one device for the entire snapshot')
 
     // --- Test 2: screenshot and ui tree fail; logs fallback to getLogs ---
-    ;(ToolsObserve as any).captureScreenshotHandler = async function() { throw new Error('screencap failed') }
-    ;(ToolsObserve as any).getUITreeHandler = async function() { throw new Error('uie_error') }
-    ;(ToolsObserve as any).readLogStreamHandler = async function() { return { entries: [] } }
-    ;(ToolsObserve as any).getLogsHandler = async function() { return { device: { platform: 'android', id: 'mock' }, logs: ['INFO starting','ERROR crash here'], logCount: 2 } }
+    ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); throw new Error('screencap failed') }
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) { assertTarget(args); throw new Error('uie_error') }
+    ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) { assertTarget(args); return { entries: [] } }
+    ;(ToolsObserve as any).getLogsHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, logs: ['INFO starting','ERROR crash here'], logCount: 2 } }
 
     const res2: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: true, logLines: 10, appId: 'com.example' })
     console.log('res2:', JSON.stringify(res2, null, 2))
@@ -62,20 +73,12 @@ async function run() {
     assert.ok(pass2, 'captureDebugSnapshot should surface partial failures and fallback logs')
     console.log('Test 2:', pass2 ? 'PASS' : 'FAIL')
 
-    // Restore handlers before next test
-    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
-    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
-    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
-    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
-    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
-    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
-
     // --- Test 3: includeLogs=false should omit logs ---
-    ;(ToolsObserve as any).captureScreenshotHandler = async function() { return { device: { platform: 'android', id: 'mock' }, screenshot: null } }
-    ;(ToolsObserve as any).getCurrentScreenHandler = async function() { return { device: { platform: 'android', id: 'mock' }, package: '', activity: '', shortActivity: '' } }
-    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() { return { fingerprint: null } }
-    ;(ToolsObserve as any).getUITreeHandler = async function() { return { device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 0, height: 0 }, elements: [] } }
-    ;(ToolsObserve as any).readLogStreamHandler = async function() { return { entries: [] } }
+    ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, screenshot: null } }
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function(args: any) { assert.strictEqual(args.deviceId, device.id); return { device: { platform: 'android', id: 'mock' }, package: '', activity: '', shortActivity: '' } }
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function(args: any) { assertTarget(args); return { fingerprint: null } }
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 0, height: 0 }, elements: [] } }
+    ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) { assertTarget(args); return { entries: [] } }
 
     const res3: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false })
     console.log('res3:', JSON.stringify(res3, null, 2))
@@ -84,12 +87,19 @@ async function run() {
     console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
 
     let screenshotCalls = 0
-    ;(ToolsObserve as any).captureScreenshotHandler = async function() { screenshotCalls++; return { screenshot: 'unexpected' } }
+    ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); screenshotCalls++; return { screenshot: 'unexpected' } }
     const res4: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false, includeScreenshot: false })
     assert.strictEqual(screenshotCalls, 0, 'includeScreenshot=false must not invoke screenshot capture')
     assert.strictEqual(res4.raw.screenshot, null)
+    assert.strictEqual(resolutions, 4, 'Each snapshot resolves its own target once')
+
+    // Discovery failure must not collect from an arbitrary/default device.
+    _setDeviceListersForTests({ listAndroidDevices: async () => { throw new Error('fixture discovery unavailable') } })
+    await assert.rejects(() => ToolsObserve.captureDebugSnapshotHandler({ platform: 'android' }), /fixture discovery unavailable/)
+    assert.strictEqual(screenshotCalls, 0, 'No component capture should run without a resolved target')
 
   } finally {
+    _resetDeviceListersForTests()
     ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
     ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
     ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler

package/test/unit/observe/compact_tree_error.test.ts

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { AndroidObserve, ToolsObserve } from '../../../src/observe/index.js'
+import { deriveSnapshotMetadata, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { withResolvedDevice } from '../../../src/utils/resolve-device.js'
+
+async function run() {
+  const original = AndroidObserve.prototype.getUITree
+  const device = { platform: 'android', id: 'fixture', model: 'Fixture', osVersion: '16', simulator: true }
+  const body = { screen: '', resolution: { width: 100, height: 200 }, elements: [] }
+  const metadata = deriveSnapshotMetadata('android:fixture', body, 'ui_tree')
+  AndroidObserve.prototype.getUITree = async () => ({ ...body, device, ...metadata, error: 'observation unavailable' })
+  try {
+    const compact: any = await withResolvedDevice(device, () => ToolsObserve.getUITreeHandler({ platform: 'android', deviceId: 'fixture', responseMode: 'compact', sinceSnapshotRevision: metadata.snapshot_revision }))
+    assert.equal(compact.error, 'observation unavailable', 'compact observations must not conceal an error behind a retained revision')
+    assert.equal(compact.delta_available, false)
+    assert.equal(compact.snapshot_session_id, metadata.snapshot_session_id)
+    assert.equal(compact.state_delta, undefined)
+    console.log('Compact UI-tree error evidence: PASS')
+  } finally {
+    AndroidObserve.prototype.getUITree = original
+    resetSnapshotMetadataForTests()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })