mobile-debug-mcp 0.35.0 → 0.37.0

package/src/utils/android/utils.ts

@@ -2,7 +2,8 @@ import { DeviceInfo } from "../../types.js"
 import { promises as fsPromises } from 'fs'
 import path from 'path'
 export { findInPath, resolveAdbCmd, getAdbCmd, ensureAdbAvailable, getAdbArgs, getAdbTimeout, type SpawnOptionsWithTimeout, execAdb, spawnAdb } from './commands.js'
-import { execAdb } from './commands.js'
+import { execAdb, getAdbCmd } from './commands.js'
+import { installationFields, probeInstallation } from '../app-installation.js'
 export { type GradleEnvOverrides, mergeEnv, prepareGradle } from './gradle.js'
 export { parseBounds, getCenter, parseBooleanAttr, parseNumberAttr, normalizeClassName, inferAndroidRole, buildAndroidSelectorConfidence, buildAndroidSelector, buildAndroidSemantic, isSliderLikeAndroid, extractAndroidState, traverseNode } from './ui-tree.js'
 export { parseLogLine } from './logs.js'
@@ -82,15 +83,12 @@ export async function listAndroidDevices(appId?: string): Promise<DeviceInfo[]>
           execAdb(['shell', 'getprop', 'ro.kernel.qemu'], serial).catch(() => '0')
         ])
         const simulator = simOutput === '1'
-        let appInstalled = false
-        if (appId) {
-          try {
-            const pm = await execAdb(['shell', 'pm', 'path', appId], serial)
-            appInstalled = !!(pm && pm.includes('package:'))
-          } catch (e: unknown) { console.debug(`[listAndroidDevices] pm check failed for ${serial}: ${String(e)}`); appInstalled = false }
-        }
-        return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled } as DeviceInfo & { appInstalled?: boolean }
-      } catch (e: unknown) { console.debug(`[listAndroidDevices] failed gathering metadata for ${serial}: ${String(e)}`); return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false } as DeviceInfo & { appInstalled?: boolean } }
+        const check = await probeInstallation(getAdbCmd(), serial, appId, 'android-current-user', deviceLines.find(line => line.split(/\s+/)[0] === serial)?.split(/\s+/)[1] === 'device')
+        return { platform: 'android', id: serial, osVersion, model, simulator, ...installationFields(check) } as DeviceInfo
+      } catch {
+        const check = await probeInstallation(getAdbCmd(), serial, appId, 'android-current-user', false)
+        return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, ...installationFields(check) } as DeviceInfo
+      }
     }))
 
     return infos

package/src/utils/app-installation.ts

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process'
+import { execCmd } from './exec.js'
+import { remainingBudget } from './operation-budget.js'
+
+export interface AppInstallation {
+  status: 'installed' | 'absent' | 'unknown'
+  appId: string | null
+  deviceId: string
+  scope: 'android-current-user' | 'ios-simulator'
+  checkedAt: string | null
+  reason?: 'APP_ID_NOT_PROVIDED' | 'DEVICE_UNAVAILABLE' | 'CHECK_FAILED' | 'UNRECOGNIZED_RESPONSE'
+}
+export function validAppId(appId: string) { return /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(appId) }
+export function installationContext(deviceId: string, appId: string | undefined, scope: AppInstallation['scope']): AppInstallation {
+  return { status: 'unknown', appId: appId ?? null, deviceId, scope, checkedAt: null, reason: appId === undefined ? 'APP_ID_NOT_PROVIDED' : 'CHECK_FAILED' }
+}
+export function installationFields(appInstallation: AppInstallation) {
+  return { appInstallation, ...(appInstallation.status === 'unknown' ? {} : { appInstalled: appInstallation.status === 'installed' }) }
+}
+export async function probeInstallation(command: string, deviceId: string, appId: string | undefined, scope: AppInstallation['scope'], available = true): Promise<AppInstallation> {
+  const result = installationContext(deviceId, appId, scope)
+  if (appId === undefined || !validAppId(appId)) return result
+  if (!available) return { ...result, reason: 'DEVICE_UNAVAILABLE' }
+  try {
+    return await runProbe(command, result)
+  } catch {
+    return { ...result, checkedAt: new Date().toISOString(), reason: 'CHECK_FAILED' }
+  }
+}
+async function runProbe(command: string, context: AppInstallation): Promise<AppInstallation> {
+  const android = context.scope === 'android-current-user'
+  const started = performance.now()
+  const timeout = remainingBudget(5000)
+  const args = android ? ['-s', context.deviceId, 'shell', 'pm', 'path', context.appId!] : ['simctl', 'listapps', context.deviceId]
+  const output = await execCmd(command, args, { timeout })
+  const result = { ...context, checkedAt: new Date().toISOString() }
+  if (output.exitCode !== 0) {
+    if (android && !output.stdout && !output.stderr) return confirmAndroidAbsence(command, result, Math.max(1, timeout - (performance.now() - started)))
+    return { ...result, reason: 'CHECK_FAILED' }
+  }
+  let status: AppInstallation['status']
+  if (android) {
+    const lines = output.stdout.trim().split('\n').filter(Boolean)
+    if (lines.some(line => !/^package:\/\S+$/.test(line.trim()))) return { ...result, reason: 'UNRECOGNIZED_RESPONSE' }
+    status = lines.length ? 'installed' : 'absent'
+  } else {
+    try {
+      const budget = remainingBudget(Math.max(1, Math.floor(timeout - (performance.now() - started))))
+      if (performance.now() - started >= timeout) return { ...result, reason: 'CHECK_FAILED' }
+      const json = await new Promise<string>((resolve, reject) => {
+        const child = execFile('/usr/bin/plutil', ['-convert', 'json', '-o', '-', '--', '-'], { timeout: budget, killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => error ? reject(error) : resolve(stdout))
+        child.stdin?.on('error', reject)
+        child.stdin?.end(output.stdout)
+      })
+      const apps: unknown = JSON.parse(json)
+      if (!apps || typeof apps !== 'object' || Array.isArray(apps)) return { ...result, reason: 'UNRECOGNIZED_RESPONSE' }
+      if (Object.values(apps).some(value => !value || typeof value !== 'object' || Array.isArray(value))) return { ...result, reason: 'UNRECOGNIZED_RESPONSE' }
+      status = Object.hasOwn(apps, context.appId!) ? 'installed' : 'absent'
+    } catch { return { ...result, reason: 'UNRECOGNIZED_RESPONSE' } }
+  }
+  const { reason: _reason, ...confirmed } = result
+  return { ...confirmed, status }
+}
+
+async function confirmAndroidAbsence(command: string, context: AppInstallation, timeout: number): Promise<AppInstallation> {
+  const output = await execCmd(command, ['-s', context.deviceId, 'shell', 'pm', 'list', 'packages', context.appId!], { timeout })
+  const result = { ...context, checkedAt: new Date().toISOString() }
+  if (output.exitCode !== 0) return { ...result, reason: 'CHECK_FAILED' }
+  const lines = output.stdout.split('\n').map(line => line.trim()).filter(Boolean)
+  if (lines.some(line => !/^package:[A-Za-z0-9_.-]+$/.test(line))) return { ...result, reason: 'UNRECOGNIZED_RESPONSE' }
+  const { reason: _reason, ...confirmed } = result
+  return { ...confirmed, status: lines.includes(`package:${context.appId}`) ? 'installed' : 'absent' }
+}

package/src/utils/benchmark-metrics.ts

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+
+interface Span { stage: string; start_ms: number; end_ms: number }
+interface Measurement { id: string; started: number; spans: Span[] }
+const measurement = new AsyncLocalStorage<Measurement>()
+
+// Private benchmark diagnostics: no arguments, device IDs or response contents.
+export function recordBenchmarkSpan(stage: string, duration: number) {
+  const current = measurement.getStore()
+  if (!current) return
+  const end = performance.now() - current.started
+  current.spans.push({ stage, start_ms: Math.max(0, end - duration), end_ms: end })
+}
+
+export async function benchmarkSubprocess<T>(operation: () => Promise<T>): Promise<T> {
+  return benchmarkStage('subprocess_ms', operation)
+}
+
+export async function benchmarkStage<T>(stage: string, operation: () => Promise<T>): Promise<T> {
+  if (!measurement.getStore()) return operation()
+  const started = performance.now()
+  try { return await operation() }
+  finally { recordBenchmarkSpan(stage, performance.now() - started) }
+}
+
+export async function withBenchmarkRequest<T>(tool: string, operation: () => Promise<T>): Promise<T> {
+  if (process.env.MOBILE_DEBUG_MCP_LATENCY_METRICS !== '1') return operation()
+  const current: Measurement = { id: randomUUID(), started: performance.now(), spans: [] }
+  return measurement.run(current, async () => {
+    let completed = false
+    try {
+      const result = await operation()
+      completed = true
+      return result
+    } finally {
+      process.stderr.write(`${JSON.stringify({ event: 'latency_metric', request_id: current.id,
+        tool, handler_completed: completed, elapsed_ms: performance.now() - current.started,
+        spans: current.spans })}\n`)
+    }
+  })
+}

package/src/utils/exec.ts

@@ -1,10 +1,15 @@
 import { checkDebuggerGuard } from '../debugger/guard.js'
 import { remainingBudget } from './operation-budget.js'
 import { spawn } from 'child_process'
+import { benchmarkSubprocess } from './benchmark-metrics.js'
 
 export type ExecOptions = { timeout?: number; env?: NodeJS.ProcessEnv; cwd?: string; shell?: boolean }
 
 export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {}): Promise<{ exitCode: number | null, stdout: string, stderr: string }> {
+  return benchmarkSubprocess(() => execute(cmd, args, opts))
+}
+
+async function execute(cmd: string, args: string[], opts: ExecOptions): Promise<{ exitCode: number | null, stdout: string, stderr: string }> {
   const { env, cwd, shell } = opts
   const timeout = remainingBudget(opts.timeout ?? 0)
   return new Promise((resolve, reject) => {

package/src/utils/ios/utils.ts

@@ -1,3 +1,5 @@
+import { installationFields, probeInstallation } from '../app-installation.js'
+import { checkDebuggerGuard } from '../../debugger/guard.js'
 import { remainingBudget } from '../operation-budget.js'
 import { execFile, spawn, execSync, spawnSync } from "child_process"
 import { DeviceInfo } from "../../types.js"
@@ -85,6 +87,7 @@ export function execCommand(args: string[], deviceId: string = "booted"): Promis
   return new Promise((resolve, reject) => {
     // Use spawn for better stream control and consistency with Android implementation
     const budgetMs = remainingBudget()
+    checkDebuggerGuard()
     const child = spawn(getXcrunCmd(), args)
 
     let stdout = ''
@@ -132,6 +135,7 @@ export function execCommandWithDiagnostics(args: string[], deviceId: string = "b
   const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000
   const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000
   const timeoutMs = budgetMs || (args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT)
+  checkDebuggerGuard()
   const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs })
   const runResult = {
     exitCode: typeof res.status === 'number' ? res.status : null,
@@ -279,16 +283,9 @@ export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
                 booted: bootedSet.has(device.udid)
               }
 
-              if (appId) {
-                // check if installed
-                const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
-                  .then(() => { info.appInstalled = true })
-                  .catch(() => { info.appInstalled = false })
-                  .then(() => { out.push(info) })
-                checks.push(p)
-              } else {
-                out.push(info)
-              }
+              out.push(info)
+              checks.push(probeInstallation(getXcrunCmd(), device.udid, appId, 'ios-simulator', info.booted === true)
+                .then(check => { Object.assign(info, installationFields(check)) }))
             }
           }
 

package/src/utils/resolve-device.ts

@@ -51,6 +51,8 @@ export async function listDevices(platform?: "android" | "ios", appId?: string):
 
 const deviceContext = new AsyncLocalStorage<DeviceInfo>()
 
+export function currentResolvedDevice() { return deviceContext.getStore() }
+
 export function withResolvedDevice<T>(device: DeviceInfo, operation: () => Promise<T>): Promise<T> {
   bindEvidenceDevice(device)
   return deviceContext.run(device, operation)
@@ -92,7 +94,7 @@ function selectDevice(devices: DeviceInfo[], platform: string, appId?: string, p
   if (prefer === "emulator") candidates = candidates.filter(d => d.simulator)
 
   if (appId) {
-    const installed = candidates.filter(d => d.appInstalled)
+    const installed = candidates.filter(d => d.appInstallation ? d.appInstallation.status === 'installed' && d.appInstallation.appId === appId && d.appInstallation.deviceId === d.id : d.appInstalled === true)
     if (installed.length > 0) candidates = installed
   }
 
@@ -117,7 +119,7 @@ function selectDevice(devices: DeviceInfo[], platform: string, appId?: string, p
       return candidates[0]
     }
 
-    const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: d.appInstalled }))
+    const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: d.appInstalled, appInstallation: d.appInstallation }))
     const err = Object.assign(new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`), { devices: list })
     throw err
   }

package/src/utils/timing.ts

@@ -1,7 +1,9 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { recordBenchmarkSpan } from './benchmark-metrics.js'
 const timings = new AsyncLocalStorage<Record<string, number>>()
 export function withTiming<T>(values: Record<string, number>, operation: () => Promise<T>) { return timings.run(values, operation) }
 export function recordTiming(component: string, milliseconds: number) {
+  recordBenchmarkSpan(component, milliseconds)
   const values = timings.getStore()
   if (values) values[component] = (values[component] ?? 0) + milliseconds
 }
@@ -9,7 +11,6 @@ export async function measure<T>(component: string, operation: () => Promise<T>)
   const start = performance.now()
   try { return await operation() }
   finally {
-    const values = timings.getStore()
-    if (values) values[component] = (values[component] ?? 0) + performance.now() - start
+    recordTiming(component, performance.now() - start)
   }
 }

package/test/device/automated/debugger/runtime.android.test.ts

@@ -104,6 +104,11 @@ if (!process.env.MCP_DEBUGGER_DEVICE) {
     assert.equal(object.value.type, 'java.lang.Object'); assert.equal(typeof object.value.object_id, 'string')
     const readiness = await call('get_app_readiness', { platform: 'android', deviceId })
     assert.equal(readiness.readiness.state, 'debugger_paused')
+    assert.deepEqual(readiness.device_readiness.blockers, ['DEBUGGER_PAUSED'])
+    assert.equal(readiness.device_readiness.input_ready, false)
+    const readyWait = await call('wait_for_app_ready', { platform: 'android', deviceId })
+    assert.equal(readyWait.failure_code, 'DEBUGGER_PAUSED')
+    assert.deepEqual(readyWait.device_readiness.blockers, ['DEBUGGER_PAUSED'])
     for (const name of ['tap', 'wait_for_ui', 'terminate_app', 'run_journey']) {
       const blocked = await call(name, { platform: 'android', deviceId, x: 5, y: 5, appId: debuggerAppId })
       assert.equal(blocked.failure_code, 'DEBUGGER_PAUSED', name)

package/test/device/automated/debugger/runtime.ios.test.ts

@@ -0,0 +1,227 @@
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { readFile, rm, readdir, writeFile, rename } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildIOSDebuggerFixture, iosDebuggerAppId, iosDebuggerSource } from '../../../fixtures/ios-debugger-app/build.js'
+
+if (!process.env.MCP_IOS_DEBUGGER_DEVICE) {
+  console.log('UNRUN iOS debugger: select a booted simulator with MCP_IOS_DEBUGGER_DEVICE')
+} else {
+  const deviceId = process.env.MCP_IOS_DEBUGGER_DEVICE
+  const sim = (...args: string[]) => execFileSync('xcrun', ['simctl', ...args], { encoding: 'utf8', timeout: 30000 }).trim()
+  console.log('Building disposable iOS fixture')
+  const fixture = buildIOSDebuggerFixture()
+  console.log('Fixture built')
+  const source = await readFile(iosDebuggerSource, 'utf8')
+  const line = (marker: string) => source.split('\n').findIndex(row => row.includes('// ' + marker)) + 1
+  const client = new Client({ name: 'ios-debugger-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  transport.stderr?.on('data', data => process.stderr.write(data))
+  const call = async (name: string, args: Record<string, unknown> = {}, signal?: AbortSignal) => {
+    const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 45000, signal })
+    return JSON.parse((response.content as { type: string; text: string }[]).find(item => item.type === 'text')!.text)
+  }
+  const hash = createHash('sha256')
+  const fingerprint = async (directory: string): Promise<void> => {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = directory + '/' + entry.name
+      if (entry.isDirectory()) await fingerprint(file)
+      else if (!file.includes('__pycache__')) hash.update(file).update(await readFile(file))
+    }
+  }
+  await fingerprint('dist'); await fingerprint('src/debugger/lldb')
+  const serverHash = hash.digest('hex')
+  const target = { platform: 'ios', deviceId, appId: iosDebuggerAppId }
+  let debugSessionId = '', cursor = 0
+  const session = () => ({ debugSessionId })
+  const attach = async () => {
+    const response = await call('attach_debugger', { ...target, timeoutMs: 30000 })
+    assert.equal(response.success, true, JSON.stringify(response))
+    assert.equal(response.device.platform, 'ios')
+    debugSessionId = response.debug_session_id; cursor = 0
+  }
+  const breakpoint = async (marker: string) => {
+    const response = await call('set_debugger_breakpoint', { ...session(), sourceFile: iosDebuggerSource, line: line(marker) })
+    assert.equal(response.success, true, JSON.stringify(response))
+    assert.equal(response.result.status, 'resolved', JSON.stringify(response))
+    assert.ok(response.result.locations.every((loc: any) => loc.line === line(marker)))
+    return response.result.breakpoint_id
+  }
+  const remove = (breakpointId: string) => call('remove_debugger_breakpoint', { ...session(), breakpointId })
+  const stop = async () => {
+    for (let i = 0; i < 15; i++) {
+      const response = await call('wait_for_debugger_event', { ...session(), afterSequence: cursor, timeoutMs: 1000 })
+      assert.equal(response.success, true, JSON.stringify(response)); cursor = response.next_cursor
+      const found = response.events.find((event: any) => event.event === 'stopped')
+      if (found) { console.log('STOP', JSON.stringify(found)); return found }
+    }
+    throw new Error('No iOS debugger stop observed')
+  }
+  const resume = (event: any) => call('resume_debugger', { ...session(), stopId: event.stop_id })
+  const locals = async (event: any) => {
+    const stack = await call('get_debugger_stack', { ...session(), stopId: event.stop_id, threadId: event.thread_id })
+    assert.equal(stack.success, true, JSON.stringify(stack))
+    const frame = stack.result.frames.find((f: any) => f.source_file === iosDebuggerSource)
+    assert.ok(frame, JSON.stringify(stack))
+    const result = await call('get_debugger_locals', { ...session(), stopId: event.stop_id, frameId: frame.frame_id })
+    assert.equal(result.success, true, JSON.stringify(result)); console.log('LOCALS', JSON.stringify(result.result))
+    return { result: result.result, frame }
+  }
+  const expectLocal = (result: any, name: string, value: string) => assert.equal(result.locals.find((v: any) => v.name === name)?.value, value, JSON.stringify(result))
+  let commandFile = ''
+  const trigger = async (command: string) => {
+    console.log('TRIGGER', command)
+    await writeFile(commandFile + '.next', command)
+    await rename(commandFile + '.next', commandFile)
+  }
+  const tap = async (text: string) => {
+    const tree = await call('get_ui_tree', { platform: 'ios', deviceId })
+    assert.ok(tree.elements.some((e: any) => e.text === text), JSON.stringify(tree))
+    const commands: Record<string, string> = { Calculate: 'calculate', 'Run async': 'async', 'Start cancellation': 'start-cancellation', 'Cancel task': 'cancel' }
+    // The installed idb HID backend is unavailable. A fixture-only main-loop
+    // command file invokes the same button actions without debugger evaluation.
+    await trigger(commands[text])
+  }
+  const expectUI = async (text: string) => {
+    for (let i = 0; i < 15; i++) {
+      const tree = await call('get_ui_tree', { platform: 'ios', deviceId })
+      if (tree.elements.some((e: any) => e.text === text)) return
+      await new Promise(resolve => setTimeout(resolve, 200))
+    }
+    throw new Error('Missing independent UI state: ' + text)
+  }
+  const detach = async () => {
+    const response = await call('detach_debugger', session())
+    assert.equal(response.cleanup.status, 'complete', JSON.stringify(response))
+    assert.deepEqual(response.cleanup.remaining_resources, [])
+    assert.equal((await call('detach_debugger', session())).cleanup.status, 'complete')
+  }
+  try {
+    sim('install', deviceId, fixture.app)
+    sim('launch', deviceId, iosDebuggerAppId)
+    commandFile = sim('get_app_container', deviceId, iosDebuggerAppId, 'data') + '/Documents/debugger-command'
+    await client.connect(transport)
+    const shortProbe = await call('get_debugger_capabilities', { ...target, timeoutMs: 100 })
+    assert.equal(shortProbe.error?.code, 'DEBUGGER_TIMEOUT')
+    const absent = await call('get_debugger_capabilities', { ...target, appId: 'dev.mobiledebug.absentfixture' })
+    assert.equal(absent.supported, false); assert.ok(absent.reasons.includes('PROCESS_NOT_FOUND'))
+    const cap = await call('get_debugger_capabilities', target)
+    assert.equal(cap.supported, true, JSON.stringify(cap))
+    assert.equal(cap.capabilities.async_execution_inspection, true)
+    assert.equal(cap.capabilities.async_stepping, true)
+    const foreign = await call('attach_debugger', { ...target, processId: process.pid })
+    assert.equal(foreign.success, false); assert.equal(foreign.error.code, 'PROCESS_NOT_FOUND')
+    await attach()
+    const bp = await breakpoint('BREAK_CALCULATE')
+    const pending = await call('set_debugger_breakpoint', { ...session(), sourceFile: '/tmp/nonexistent-ios-debugger-source.swift', line: 1 })
+    assert.equal(pending.result.status, 'pending'); await remove(pending.result.breakpoint_id)
+    const noncode = await call('set_debugger_breakpoint', { ...session(), sourceFile: iosDebuggerSource, line: 9999 })
+    assert.equal(noncode.result.status, 'rejected'); await remove(noncode.result.breakpoint_id)
+    const storedHandle = await call('wait_for_ui', { platform: 'ios', deviceId, selector: { text: 'Calculate' }, condition: 'exists', timeout_ms: 10000 })
+    assert.equal(storedHandle.status, 'success', JSON.stringify(storedHandle))
+    assert.ok(storedHandle.element.elementId)
+    await tap('Calculate')
+    let event = await stop()
+    const originalStop = event
+    assert.equal(event.location.line, line('BREAK_CALCULATE'))
+    const inspected = await locals(event); expectLocal(inspected.result, 'known', '41')
+    const guarded = await call('tap', { platform: 'ios', deviceId, x: 10, y: 10 })
+    assert.equal(guarded.failure_code, 'DEBUGGER_PAUSED'); assert.equal(guarded.delivery_status, 'not_delivered')
+    const storedTap = await call('tap_element', { elementId: storedHandle.element.elementId, verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(storedTap.failure_code, 'DEBUGGER_PAUSED', JSON.stringify(storedTap))
+    assert.equal(storedTap.delivery_status, 'not_delivered'); assert.equal(storedTap.dispatch_started, false)
+    assert.deepEqual(storedTap.debugger.device, { platform: 'ios', id: deviceId })
+    console.log('PASS paused stored iOS handle without platform/device hints rejected before dispatch')
+    const readiness = await call('get_app_readiness', { platform: 'ios', deviceId })
+    assert.equal(readiness.readiness.state, 'debugger_paused')
+    assert.deepEqual(readiness.device_readiness.blockers, ['DEBUGGER_PAUSED'])
+    assert.equal(readiness.device_readiness.input_ready, false)
+    const readyWait = await call('wait_for_app_ready', { platform: 'ios', deviceId })
+    assert.equal(readyWait.failure_code, 'DEBUGGER_PAUSED')
+    assert.deepEqual(readyWait.device_readiness.blockers, ['DEBUGGER_PAUSED'])
+    await remove(bp)
+    for (const kind of ['into', 'over', 'out']) {
+      const response = await call('step_debugger', { ...session(), stopId: event.stop_id, threadId: event.thread_id, kind })
+      assert.equal(response.success, true, JSON.stringify(response)); event = await stop()
+    }
+    const stale = await call('get_debugger_locals', { ...session(), stopId: originalStop.stop_id, frameId: inspected.frame.frame_id })
+    assert.equal(stale.error.code, 'DEBUGGER_STALE_REFERENCE')
+    await resume(event)
+    await expectUI('Debugger result 42')
+    const controller = new AbortController()
+    const waiting = call('wait_for_debugger_event', { ...session(), afterSequence: cursor, timeoutMs: 30000 }, controller.signal)
+    setTimeout(() => controller.abort(), 100)
+    await assert.rejects(waiting)
+    assert.equal((await call('get_debugger_state', session())).state, 'running')
+    await detach()
+
+    await attach()
+    const before = await breakpoint('BEFORE_AWAIT'), after = await breakpoint('AFTER_AWAIT')
+    await tap('Run async')
+    event = await stop(); assert.equal(event.location.line, line('BEFORE_AWAIT'))
+    expectLocal((await locals(event)).result, 'known', '42')
+    await remove(before)
+    await resume(event)
+    event = await stop(); assert.equal(event.location.line, line('AFTER_AWAIT'))
+    expectLocal((await locals(event)).result, 'after', '43')
+    await remove(after); await resume(event)
+    await expectUI('Async result 44')
+    await detach()
+
+    // Boundary stepping has a distinct evidence result, independent of breakpoint coverage.
+    await attach()
+    const boundary = await breakpoint('BEFORE_AWAIT')
+    await tap('Run async'); event = await stop(); await remove(boundary)
+    assert.equal((await call('step_debugger', { ...session(), stopId: event.stop_id, threadId: event.thread_id, kind: 'over' })).success, true)
+    event = await stop()
+    assert.equal(event.location.source_file, iosDebuggerSource)
+    assert.equal(event.location.line, line('AFTER_AWAIT'), 'Advertised async stepping must follow the continuation')
+    console.log('ASYNC_BOUNDARY_STEP', JSON.stringify({ expected_line: line('AFTER_AWAIT'), observed: event.location }))
+    await detach(); await expectUI('Async result 44')
+
+    await attach()
+    const cancel = await breakpoint('CANCELLED')
+    await tap('Start cancellation'); await expectUI('Task running'); await tap('Cancel task')
+    event = await stop(); expectLocal((await locals(event)).result, 'cancelled', 'true')
+    await remove(cancel); await resume(event); await detach(); await expectUI('Task cancelled')
+
+    if (process.env.MCP_IOS_DEBUGGER_EXTENDED === '1') {
+      await attach(); await breakpoint('BREAK_CALCULATE'); await tap('Calculate'); await stop()
+      const deadline = Date.now() + 75000
+      let state: any
+      do { await new Promise(resolve => setTimeout(resolve, 1000)); state = await call('get_debugger_state', session()) } while (state.state === 'paused' && Date.now() < deadline)
+      assert.equal(state.reason, 'pause_limit'); assert.equal(state.cleanup.status, 'complete')
+      await expectUI('Debugger result 42')
+    }
+    await attach()
+    await trigger('exit')
+    let exited: any
+    for (let i = 0; i < 100; i++) {
+      exited = await call('get_debugger_state', session())
+      if (exited.state === 'disconnected' && exited.cleanup.status === 'complete') break
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+    assert.equal(exited.state, 'disconnected'); assert.equal(exited.cleanup.status, 'complete')
+    sim('launch', deviceId, iosDebuggerAppId); await expectUI('Debugger ready')
+    // Clear the earlier calculate result before proving shutdown recovery.
+    await tap('Start cancellation'); await expectUI('Task running'); await tap('Cancel task'); await expectUI('Task cancelled')
+    // Closing the server while paused must release its owned suspension.
+    await attach(); await breakpoint('BREAK_CALCULATE'); await tap('Calculate'); await stop()
+    await client.close()
+    const verifier = new Client({ name: 'ios-cleanup-verifier', version: '1.0.0' })
+    await verifier.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' }))
+    try {
+      const response = await verifier.callTool({ name: 'get_ui_tree', arguments: { platform: 'ios', deviceId } })
+      const tree = JSON.parse((response.content as any[])[0].text)
+      assert.ok(tree.elements.some((e: any) => e.text === 'Debugger result 42'), JSON.stringify(tree))
+    } finally { await verifier.close() }
+    console.log('PASS iOS MCP debugger core/async/cancellation/cleanup', JSON.stringify({ deviceId, server_sha256: serverHash, source_sha256: createHash('sha256').update(source).digest('hex'), xcode: execFileSync('xcodebuild', ['-version'], { encoding: 'utf8' }).trim(), lldb: execFileSync('xcrun', ['lldb', '--version'], { encoding: 'utf8' }).trim() }))
+  } finally {
+    if (debugSessionId) { try { await call('detach_debugger', session()) } catch {} }
+    await client.close().catch(() => {})
+    sim('uninstall', deviceId, iosDebuggerAppId)
+    await rm(fixture.directory, { recursive: true, force: true })
+  }
+}

package/test/device/automated/interact/compact-results.smoke.ts

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+const client = new Client({ name: 'compact-results-smoke', version: '1.0.0' })
+const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+async function call(name: string, args: Record<string, unknown> = {}) {
+  const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 120000 })
+  const item = response.content.find(item => item.type === 'text')
+  assert(item?.type === 'text')
+  return { value: JSON.parse(item.text), bytes: Buffer.byteLength(item.text) }
+}
+async function details(value: Record<string, any>) {
+  const result = await call('get_interaction_diagnostics', { sessionId: value.diagnostics.session_id, resultId: value.diagnostics.result_id })
+  assert.equal(result.value.success, true)
+  return result.value.result
+}
+try {
+  await client.connect(transport)
+  const discovery = await call('list_devices')
+  for (const platform of ['android', 'ios']) {
+    const device = discovery.value.devices.find((d: Record<string, any>) => d.platform === platform && d.simulator && (platform === 'android' || d.booted))
+    assert(device, `A booted ${platform} simulator/emulator is required`)
+    const target = { platform, deviceId: device.id }, appId = platform === 'android' ? 'com.android.settings' : 'com.apple.Preferences'
+    const none = await call('start_app', { ...target, appId, verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(none.value.success, true)
+    assert.equal(none.value.verification.status, 'not_requested')
+    assert.equal(none.value.observed_state.status, 'unknown')
+    assert.ok(none.bytes <= 1280 + Buffer.byteLength(device.id))
+    assert.equal((await details(none.value)).evidence.action_id, none.value.action_id)
+    const observed = await call('start_app', { ...target, appId, verificationMode: 'light', verificationTimeoutMs: 30000, responseMode: 'compact' })
+    assert.equal(observed.value.success, true)
+    assert.equal(observed.value.observed_state.status, 'observed', JSON.stringify(observed.value))
+    assert.ok(observed.bytes <= 1280 + Buffer.byteLength(device.id))
+    const blocked = await call('tap_element', { ...target, selector: { text: '__mcp_absent_compact_fixture__' }, verificationMode: 'none', responseMode: 'compact', actionTimeoutMs: 1000 })
+    assert.equal(blocked.value.success, false)
+    assert.equal(blocked.value.dispatch_started, false)
+    assert.equal(blocked.value.observed_state.status, 'unknown')
+    assert.equal((await details(blocked.value)).success, false)
+    const tree = await call('get_ui_tree', target)
+    const element = tree.value.elements?.find((e: Record<string, any>) => e.visible && typeof e.text === 'string' && e.text.trim())
+    assert(element, 'Settings must expose a visible text target')
+    const journey = await call('run_journey', { ...target, defaults: { verificationMode: 'none' }, steps: [
+      { id: 'open', type: 'start_app', appId },
+      { id: 'observe', type: 'assert', assertion: { kind: 'element_visible', selector: { text: element.text } }, timeoutMs: 15000 }
+    ] })
+    assert.equal(journey.value.success, true, JSON.stringify(journey.value))
+    assert.equal(journey.value.steps[1].result.observed_state.status, 'observed')
+    const retainedJourney = await details(journey.value)
+    const retainedStep = await details(journey.value.steps[0].result)
+    assert.equal(retainedJourney.steps[0].result.evidence.action_id, retainedStep.evidence.action_id)
+    assert.ok(retainedStep.evidence.dispatch_completed_at_ms)
+    console.log(JSON.stringify({ status: 'PASS', platform, device: device.id, os: device.osVersion, server: client.getServerVersion(),
+      bytes: { none: none.bytes, observed: observed.bytes, blocked: blocked.bytes, journey: journey.bytes },
+      observed: observed.value.observed_state, journeyAssertion: journey.value.steps[1].result.observed_state,
+      checks: ['dispatch-only unknown', 'fresh post-observation', 'no-dispatch failure', 'journey', 'read-only original/child lookup'], cleanup: 'Settings remains foreground; no app data/settings changed' }))
+  }
+} finally { await client.close() }

package/test/device/automated/latency/end-to-end-environment.ts

@@ -0,0 +1,61 @@
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFileSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+export function command(command: string, args: string[], timeout = 30000) {
+  return execFileSync(command, args, { encoding: 'utf8', timeout, killSignal: 'SIGKILL', stdio: 'pipe' }).trim()
+}
+export function fixturePresent(adb: (...args: string[]) => string, app: string) {
+  return adb('shell', 'pm', 'list', 'packages', app).split('\n').includes(`package:${app}`)
+}
+
+export function cleanupFixture(adb: (...args: string[]) => string, app: string, remove: boolean) {
+  if (!fixturePresent(adb, app)) return false
+  adb('shell', 'am', 'force-stop', app)
+  if (!remove) return false
+  adb('uninstall', app)
+  if (fixturePresent(adb, app)) throw new Error('FIXTURE_REMOVAL_FAILED')
+  return true
+}
+
+export const sha256 = (file: string) => createHash('sha256').update(readFileSync(file)).digest('hex')
+export function treeHash(root: string): string {
+  const hash = createHash('sha256')
+  const visit = (directory: string) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = path.join(directory, entry.name)
+      if (entry.isDirectory()) visit(file)
+      else if (entry.isFile()) { hash.update(path.relative(root, file)); hash.update(readFileSync(file)) }
+    }
+  }
+  visit(root)
+  return hash.digest('hex')
+}
+function version(tool: string, args: string[]) {
+  try { return command(tool, args).split('\n').filter(line => !/Installed as/.test(line)).slice(0, 3).join('\n') }
+  catch { return 'unavailable' }
+}
+export function environment(deviceId: string, apk: string) {
+  const adb = (...args: string[]) => command('adb', ['-s', deviceId, ...args])
+  const connected = command('adb', ['devices']).split('\n').filter(line => /\sdevice$/.test(line.trim()))
+  return {
+    commit: command('git', ['rev-parse', 'HEAD']),
+    working_tree: command('git', ['status', '--porcelain', '--untracked-files=all']),
+    source_sha256: treeHash('src'), build_sha256: treeHash('dist'), harness_sha256: treeHash('test/device/automated/latency'), fixture_sha256: sha256(apk),
+    package_version: JSON.parse(readFileSync('package.json', 'utf8')).version,
+    node: process.version, host: { platform: os.platform(), release: os.release(), arch: os.arch() },
+    platform: 'android', model: adb('shell', 'getprop', 'ro.product.model'),
+    discovery_topology: { android_emulators: connected.filter(line => line.startsWith('emulator-')).length,
+      android_other_devices: connected.filter(line => !line.startsWith('emulator-')).length },
+    os: adb('shell', 'getprop', 'ro.build.version.release'), api: adb('shell', 'getprop', 'ro.build.version.sdk'),
+    avd: adb('emu', 'avd', 'name').split('\n')[0], display: adb('shell', 'wm', 'size'), density: adb('shell', 'wm', 'density'),
+    tool_versions: { adb: version('adb', ['version']), javac: version(process.env.JAVA_HOME ? path.join(process.env.JAVA_HOME, 'bin', 'javac') : 'javac', ['--version']), android_build_tools: '36.0.0',
+      emulator: version(path.join(process.env.ANDROID_HOME ?? path.join(os.homedir(), 'Library/Android/sdk'), 'emulator/emulator'), ['-version']),
+      android_compile_platform: '36', xcode: version('xcodebuild', ['-version']), idb: version('idb', ['--version']) },
+    timeouts: { setup_ms: 30000, call_ms: 300000, action_ms: 30000, wait_ms: 10000, verification_ms: 60000,
+      adb_ms: Number(process.env.MCP_ADB_TIMEOUT ?? 20000) },
+    ios: { journey: 'blocked: shared #89 fixture unavailable', observations: 'blocked: idb executable unavailable and no booted simulator at investigation', physical_device: 'excluded' }
+  }
+}