mobile-debug-mcp 0.36.0 → 0.37.0

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

@@ -134,7 +134,13 @@ if (!process.env.MCP_IOS_DEBUGGER_DEVICE) {
     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')
-    assert.equal((await call('get_app_readiness', { platform: 'ios', deviceId })).readiness.state, 'debugger_paused')
+    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 })

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' }
+  }
+}

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

@@ -0,0 +1,90 @@
+import { summarize } from './report.js'
+
+export interface Span { stage: string; start_ms: number; end_ms: number }
+export interface RequestMetric {
+  event: 'latency_metric'; request_id: string; tool: string
+  handler_completed: boolean; elapsed_ms: number; spans: Span[]
+}
+export interface TreeMetric {
+  event: 'ui_tree_metric'; type: string; stage?: string; elapsed_ms?: number
+  acquisition_id?: string; success?: boolean; durations_ms?: Record<string, number>
+}
+export interface RequestSample {
+  tool: string; elapsed_ms: number; response_bytes?: number; success: boolean
+  failure?: string; failed_step?: string; failure_code?: string; metrics: RequestMetric[]; tree: TreeMetric[]
+}
+export interface Attempt {
+  case: string; iteration: number; warmup: boolean; success: boolean
+  failure?: string; setup_ms: number; requests: RequestSample[]
+}
+
+export function unionDuration(spans: Span[], limit: number) {
+  const sorted = spans.map(span => [Math.max(0, span.start_ms), Math.min(limit, span.end_ms)])
+    .filter(([start, end]) => Number.isFinite(start) && Number.isFinite(end) && end >= start)
+    .sort((a, b) => a[0] - b[0])
+  let end = 0, total = 0
+  for (const [start, stop] of sorted) { total += Math.max(0, stop - Math.max(end, start)); end = Math.max(end, stop) }
+  return total
+}
+
+export function summarizeAttempts(attempts: Attempt[]) {
+  return Object.fromEntries([...new Set(attempts.map(attempt => attempt.case))].map(name => {
+    const selected = attempts.filter(attempt => attempt.case === name)
+    const measured = selected.filter(attempt => !attempt.warmup)
+    const successful = measured.filter(attempt => attempt.success)
+    const requests = successful.flatMap(attempt => attempt.requests)
+    const metrics = requests.flatMap(request => request.metrics)
+    const tree = requests.flatMap(request => request.tree)
+    const stages = [...new Set(metrics.flatMap(metric => metric.spans.map(span => span.stage)))]
+    const treeStages = [...new Set(tree.filter(event => event.type === 'stage').map(event => event.stage!))]
+    return [name, {
+      attempts: measured.length, failures: measured.filter(attempt => !attempt.success).length,
+      warmup_failures: selected.filter(attempt => attempt.warmup && !attempt.success).length,
+      total_ms: summarize(successful.map(attempt => attempt.requests.reduce((sum, request) => sum + request.elapsed_ms, 0))),
+      response_bytes: summarize(successful.map(attempt => attempt.requests.reduce((sum, request) => sum + (request.response_bytes ?? 0), 0))),
+      handler_ms: summarize(metrics.map(metric => metric.elapsed_ms)),
+      handler_unattributed_ms: summarize(metrics.map(metric => Math.max(0, metric.elapsed_ms - unionDuration(metric.spans, metric.elapsed_ms)))),
+      client_minus_handler_ms: summarize(requests.filter(request => request.metrics.length === 1)
+        .map(request => request.elapsed_ms - request.metrics[0].elapsed_ms)),
+      inclusive_components_ms: Object.fromEntries(stages.map(stage => [stage, summarize(metrics.map(metric =>
+        metric.spans.filter(span => span.stage === stage).reduce((sum, span) => sum + span.end_ms - span.start_ms, 0)))])),
+      physical_reads: tree.filter(event => event.type === 'physical_read_completed').length,
+      failed_physical_reads: tree.filter(event => event.type === 'physical_read_completed' && event.success === false).length,
+      tree_stages_ms: Object.fromEntries(treeStages.map(stage => [stage, summarize(tree.filter(event => event.type === 'stage' && event.stage === stage).map(event => event.elapsed_ms ?? 0))])),
+      tree_acquisition_ms: summarize(tree
+        .filter(event => event.type === 'acquisition_completed').map(event => event.elapsed_ms ?? 0)),
+      missing_request_metrics: requests.filter(request => request.metrics.length !== 1).length
+    }]
+  }))
+}
+
+export function observationOverhead(attempts: Attempt[]) {
+  return Object.fromEntries(['screenshot', 'tree', 'snapshot'].map(name => {
+    const pairs = attempts.filter(attempt => attempt.case === `${name}-on` && !attempt.warmup && attempt.success)
+      .flatMap(on => {
+        const off = attempts.find(attempt => attempt.case === `${name}-off` && attempt.iteration === on.iteration && !attempt.warmup && attempt.success)
+        return off ? [on.requests.reduce((sum, request) => sum + request.elapsed_ms, 0) - off.requests.reduce((sum, request) => sum + request.elapsed_ms, 0)] : []
+      })
+    return [name, { paired_on_minus_off_ms: summarize(pairs), interpretation: 'Includes device/order variability; not an isolated causal overhead estimate' }]
+  }))
+}
+
+// Whitelist timing metadata rather than persisting unrestricted server stderr.
+export function parseMetric(line: string): RequestMetric | TreeMetric | null {
+  try {
+    const value = JSON.parse(line)
+    const finite = (number: unknown) => typeof number === 'number' && Number.isFinite(number) && number >= 0
+    if (value.event === 'latency_metric' && typeof value.tool === 'string' && typeof value.request_id === 'string' &&
+      typeof value.handler_completed === 'boolean' && finite(value.elapsed_ms) && Array.isArray(value.spans) &&
+      value.spans.every((span: Span) => typeof span.stage === 'string' && finite(span.start_ms) && finite(span.end_ms) && span.end_ms >= span.start_ms)) {
+      return { event: value.event, request_id: value.request_id, tool: value.tool,
+        handler_completed: value.handler_completed, elapsed_ms: value.elapsed_ms,
+        spans: value.spans.map((span: Span) => ({ stage: span.stage, start_ms: span.start_ms, end_ms: span.end_ms })) }
+    }
+    if (value.event === 'ui_tree_metric' && typeof value.type === 'string' &&
+      (value.elapsed_ms === undefined || finite(value.elapsed_ms))) return { event: value.event, type: value.type,
+      stage: value.stage, elapsed_ms: value.elapsed_ms, acquisition_id: value.acquisition_id,
+      success: value.success, durations_ms: value.durations_ms }
+  } catch { /* Non-metric stderr is intentionally discarded. */ }
+  return null
+}

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

@@ -0,0 +1,98 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { setTimeout as delay } from 'node:timers/promises'
+import { OwnedTransport } from './owned-transport.js'
+import { parseMetric, type RequestMetric, type TreeMetric, type RequestSample } from './end-to-end-report.js'
+
+function object(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' ? value as Record<string, unknown> : {}
+}
+export function validObservation(tool: string, data: Record<string, unknown>, content: unknown, deviceId: string) {
+  const treeValid = (value: Record<string, unknown>) => !value.error && Array.isArray(value.elements) && value.elements.length > 0 && object(value.device).id === deviceId
+  if (tool === 'get_ui_tree') return treeValid(data)
+  if (tool === 'capture_screenshot') return object(data.device).id === deviceId && Array.isArray(content) && content.some(item => {
+    const block = object(item)
+    return block.type === 'image' && typeof block.data === 'string' && block.data.length > 0
+  })
+  if (tool === 'capture_debug_snapshot') {
+    const raw = object(data.raw)
+    return treeValid(object(raw.ui_tree)) && !Object.keys(raw).some(key => key.endsWith('_error') && raw[key])
+  }
+  return true
+}
+
+export class UnsafeMeasurement extends Error {}
+export class BenchmarkSession {
+  readonly client = new Client({ name: 'end-to-end-latency', version: '1.0' })
+  readonly transport: OwnedTransport
+  private events: (RequestMetric | TreeMetric)[] = []
+  private pending = ''
+  private interrupted = new AbortController()
+  constructor(readonly deviceId: string, readonly instrumented: boolean, server = 'dist/server.js') {
+    this.transport = new OwnedTransport({ ...process.env,
+      MOBILE_DEBUG_MCP_LATENCY_METRICS: instrumented ? '1' : '0',
+      MOBILE_DEBUG_MCP_UI_TREE_METRICS: instrumented ? '1' : '0'
+    }, chunk => {
+      this.pending += chunk
+      let index: number
+      while ((index = this.pending.indexOf('\n')) >= 0) {
+        const event = parseMetric(this.pending.slice(0, index))
+        if (event) this.events.push(event)
+        this.pending = this.pending.slice(index + 1)
+      }
+      if (this.pending.length > 1024 * 1024) this.pending = ''
+    }, [server])
+  }
+
+  async connect() { await this.client.connect(this.transport, { timeout: 15000 }) }
+  abort() { this.interrupted.abort() }
+  async close() { await this.client.close(); await this.transport.close() }
+
+  async call(tool: string, args: Record<string, unknown>, samples: RequestSample[]) {
+    if (this.interrupted.signal.aborted) throw new UnsafeMeasurement('INTERRUPTED')
+    this.events = []
+    const started = performance.now()
+    const sample: RequestSample = { tool, elapsed_ms: 0, success: false, metrics: [], tree: [] }
+    samples.push(sample)
+    try {
+      const response = await this.client.callTool({ name: tool,
+        arguments: { platform: 'android', deviceId: this.deviceId, ...args }
+      }, undefined, { timeout: 300000, signal: this.interrupted.signal })
+      sample.elapsed_ms = performance.now() - started
+      console.log(`  ${tool}: ${Math.round(sample.elapsed_ms)} ms`)
+      sample.response_bytes = Buffer.byteLength(JSON.stringify(response))
+      // Stderr and stdout are independent streams. Await the matching metric
+      // outside the measured round trip before dispatching the next request.
+      const deadline = performance.now() + 1000
+      while (this.instrumented && !this.events.some(event => event.event === 'latency_metric') && performance.now() < deadline) await delay(5)
+      sample.metrics = this.events.filter((event): event is RequestMetric => event.event === 'latency_metric')
+      sample.tree = this.events.filter((event): event is TreeMetric => event.event === 'ui_tree_metric')
+      const text = (response.content as { type: string; text?: string }[]).find(item => item.type === 'text')?.text
+      const data = JSON.parse(text ?? '{}')
+      sample.success = !response.isError && data.success !== false && !data.error && data.status !== 'timeout' && validObservation(tool, data, response.content, this.deviceId)
+      if (!sample.success) {
+        sample.failure = 'TOOL_OUTCOME_FAILED'
+        // Only fixture-generated step IDs and enum-style codes may be saved.
+        const step = typeof data.stopped_at_step_id === 'string' ? data.stopped_at_step_id : ''
+        if (/^(launch|tap-\d+|assert-\d+)$/.test(step)) sample.failed_step = step
+        const failed = Array.isArray(data.steps) ? data.steps.find((value: Record<string, unknown>) => value.id === step) : undefined
+        const code = data.failure_code ?? object(object(failed).result).failure_code ?? object(data.error).code
+        if (typeof code === 'string' && /^[A-Z][A-Z_]{0,63}$/.test(code)) sample.failure_code = code
+        throw new Error(sample.failure)
+      }
+      if (this.instrumented && (sample.metrics.length !== 1 || sample.metrics[0].tool !== tool)) {
+        sample.success = false; sample.failure = 'METRIC_CORRELATION_FAILED'
+        throw new UnsafeMeasurement(sample.failure)
+      }
+      return data as Record<string, unknown>
+    } catch (error) {
+      if (!sample.elapsed_ms) sample.elapsed_ms = performance.now() - started
+      sample.metrics = this.events.filter((event): event is RequestMetric => event.event === 'latency_metric')
+      sample.tree = this.events.filter((event): event is TreeMetric => event.event === 'ui_tree_metric')
+      if (!sample.failure) {
+        sample.failure = this.interrupted.signal.aborted ? 'INTERRUPTED' : 'TRANSPORT_OR_RESPONSE_FAILED'
+        throw new UnsafeMeasurement(sample.failure)
+      }
+      throw error
+    }
+  }
+}

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

@@ -0,0 +1,149 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { buildFixture } from '../../../fixtures/latency-journey-app/build.js'
+import { BenchmarkSession, UnsafeMeasurement } from './end-to-end-session.js'
+import { cleanupFixture, command, environment, fixturePresent, treeHash } from './end-to-end-environment.js'
+import { summarizeAttempts, observationOverhead, type Attempt } from './end-to-end-report.js'
+
+const deviceId = process.env.LATENCY_DEVICE_ID
+if (!deviceId || !deviceId.startsWith('emulator-')) throw new Error('Set LATENCY_DEVICE_ID to an explicit Android emulator serial')
+const adb = (...args: string[]) => command('adb', ['-s', deviceId, ...args])
+const appId = 'dev.mobiledebugmcp.latencyfixture'
+const smoke = process.argv.includes('--smoke')
+const rounds = smoke ? 1 : 13
+const warmups = smoke ? 0 : 3
+const cases = ['standalone', 'full-debug', 'full-compact', 'light-debug', 'light-compact',
+  'screenshot-on', 'screenshot-off', 'tree-on', 'tree-off', 'snapshot-on', 'snapshot-off']
+const flow = [['saved-session', 'idle-detail'], ['activate', 'active-detail'], ['home', 'home-screen'],
+  ['saved-session', 'active-detail'], ['deactivate', 'idle-detail'], ['stop', 'stopped']]
+const selector = (id: string) => ({ accessibility_id: id })
+const controls = { actionTimeoutMs: 30000, verificationTimeoutMs: 60000 }
+const attempts: Attempt[] = []
+const phases: { phase: string; elapsed_ms: number; success: boolean }[] = []
+const sessions = new Map<boolean, BenchmarkSession>()
+const cleanup: { server?: boolean; fixture?: boolean; removed_install?: boolean } = {}
+let metadata: ReturnType<typeof environment> | undefined
+let interrupted = false
+let fatal: string | undefined
+let fixtureExisted = false
+let installAttempted = false
+let sourceStable: boolean | undefined
+const startedAt = new Date().toISOString()
+const root = 'docs/benchmarks/end-to-end-latency'
+const reportName = smoke ? 'smoke' : 'baseline'
+async function phase<T>(name: string, operation: () => T | Promise<T>) {
+  const start = performance.now()
+  let success = false
+  try { const result = await operation(); success = true; return result }
+  finally { phases.push({ phase: name, elapsed_ms: performance.now() - start, success }) }
+}
+function save() {
+  mkdirSync(root, { recursive: true })
+  const summaries = summarizeAttempts(attempts)
+  const report = { status: fatal ? 'stopped' : interrupted ? 'interrupted' : attempts.length === rounds * cases.length ? 'finished' : 'in_progress',
+    performance_evidence: !smoke && sourceStable !== false, smoke, warmups, measured_attempts_per_case: smoke ? 1 : 10,
+    started_at: startedAt, source_and_build_unchanged: sourceStable,
+    planned_cases: cases, unrun_attempts: rounds * cases.length - attempts.length,
+    outcome: fatal || interrupted || attempts.some(value => !value.success) || cleanup.server === false || cleanup.fixture === false ? 'fail' : cleanup.server && cleanup.fixture ? 'pass' : 'pending',
+    invocation: `LATENCY_DEVICE_ID=[emulator] MCP_ADB_TIMEOUT=${process.env.MCP_ADB_TIMEOUT ?? '20000'} npx tsx test/device/automated/latency/end-to-end.ts${smoke ? ' --smoke' : ''}`,
+    metadata, phases, fatal, cleanup, summaries, observation_overhead: observationOverhead(attempts), attempts }
+  writeFileSync(`${root}/${reportName}.json`, JSON.stringify(report, null, 2) + '\n')
+  const rows = Object.entries(summaries).map(([name, value]) => `| ${name} | ${value.total_ms?.count ?? 0}/${value.attempts} | ${value.total_ms?.p50.toFixed(1) ?? 'n/a'} | ${value.total_ms?.p95.toFixed(1) ?? 'n/a'} | ${value.failures} | ${value.warmup_failures} |`)
+  writeFileSync(`${root}/${reportName}.md`, `# End-to-end latency ${smoke ? 'smoke (not performance evidence)' : 'baseline'}\n\nStatus: ${report.status}. Build: ${metadata?.build_sha256 ?? 'unavailable'}.\n\n| Case | Successful/measured | p50 ms | p95 ms | Failures | Warm-up failures |\n| --- | ---: | ---: | ---: | ---: | ---: |\n${rows.join('\n')}\n\nSee ${reportName}.json for exact source/build hashes, environment, phase durations, attempt order, inclusive components and failure records. Percentiles use the successful measured count shown for each case. With 1–19 successful samples, nearest-rank p95 is the sample maximum. Zero successful samples yield no percentiles. Failed attempts are excluded from percentiles, retained in raw data, and fail the run.\n\nIntervals can overlap; component sums are not an additive latency budget. Client-minus-handler includes scheduling, transport and uninstrumented work. Handler residual excludes the union of recorded spans. Tree acquisition/parse/retry events are separate nested diagnostics. Application work inside requests remains included. Startup, fixture builds/resets and external validation are excluded from steady-state round trips. SDK wire serialization is not isolated.\n`)
+}
+async function reset(session: BenchmarkSession, observation: boolean) {
+  adb('shell', 'am', 'force-stop', appId)
+  if (!adb('shell', 'pm', 'clear', appId).includes('Success')) throw new Error('RESET_FAILED')
+  if (observation) {
+    adb('shell', 'am', 'start', '-W', '-n', `${appId}/.MainActivity`)
+    await session.call('expect_element_visible', { selector: selector('home-screen'), timeout_ms: 30000, poll_interval_ms: 100 }, [])
+  }
+}
+async function journey(session: BenchmarkSession, mode: string, attempt: Attempt) {
+  if (mode === 'standalone') {
+    await session.call('start_app', { appId, ...controls }, attempt.requests)
+    for (const [target, expected] of flow) {
+      const found = await session.call('wait_for_ui', { selector: selector(target), condition: 'clickable', timeout_ms: 10000, poll_interval_ms: 100 }, attempt.requests)
+      const element = found.element as { elementId?: string } | undefined
+      if (!element?.elementId) throw new Error('TARGET_HANDLE_MISSING')
+      await session.call('tap_element', { elementId: element.elementId, ...controls }, attempt.requests)
+      await session.call('expect_element_visible', { selector: selector(expected), timeout_ms: 30000, poll_interval_ms: 100 }, attempt.requests)
+    }
+    return
+  }
+  const [verificationMode, responseMode] = mode.split('-')
+  const steps: Record<string, unknown>[] = [{ id: 'launch', type: 'start_app', appId }]
+  flow.forEach(([target, expected], index) => {
+    steps.push({ id: `tap-${index}`, type: 'tap', selector: selector(target), waitFor: { condition: 'clickable', timeoutMs: 10000, pollIntervalMs: 100 } })
+    steps.push({ id: `assert-${index}`, type: 'assert', assertion: { kind: 'element_visible', selector: selector(expected) }, timeoutMs: 30000, pollIntervalMs: 100 })
+  })
+  await session.call('run_journey', { defaults: { verificationMode, ...controls }, responseMode, steps }, attempt.requests)
+}
+async function attempt(name: string, iteration: number) {
+  if (interrupted) throw new UnsafeMeasurement('INTERRUPTED')
+  const instrumented = !name.endsWith('-off')
+  const session = sessions.get(instrumented)!
+  const observation = /^(screenshot|tree|snapshot)-/.test(name)
+  const value: Attempt = { case: name, iteration, warmup: iteration < warmups, success: false, setup_ms: 0, requests: [] }
+  attempts.push(value)
+  const start = performance.now()
+  try {
+    await reset(session, observation)
+    value.setup_ms = performance.now() - start
+    if (!observation) await journey(session, name, value)
+    else {
+      const tool = name.startsWith('screenshot') ? 'capture_screenshot' : name.startsWith('tree') ? 'get_ui_tree' : 'capture_debug_snapshot'
+      await session.call(tool, tool === 'capture_debug_snapshot' ? { includeScreenshot: false, includeLogs: false } : {}, value.requests)
+    }
+    value.success = true
+  } catch (error) {
+    if (!value.setup_ms) value.setup_ms = performance.now() - start
+    value.failure = error instanceof UnsafeMeasurement ? error.message : value.requests.at(-1)?.failure ?? 'SETUP_OR_ASSERTION_FAILED'
+    if (error instanceof UnsafeMeasurement || !value.requests.length) throw new UnsafeMeasurement(value.failure)
+  } finally { save() }
+}
+async function main() {
+  const signal = () => { interrupted = true; for (const session of sessions.values()) session.abort() }
+  process.on('SIGINT', signal); process.on('SIGTERM', signal)
+  try {
+    if (adb('get-state') !== 'device' || adb('shell', 'getprop', 'ro.kernel.qemu') !== '1') throw new Error('EMULATOR_REQUIRED')
+    fixtureExisted = fixturePresent(adb, appId)
+    const apk = await phase('fixture_build', buildFixture)
+    metadata = environment(deviceId!, apk)
+    installAttempted = true
+    await phase('fixture_install', () => adb('install', '-r', apk))
+    for (const enabled of [true, false]) {
+      const session = new BenchmarkSession(deviceId!, enabled)
+      sessions.set(enabled, session)
+      await phase(`server_startup_metrics_${enabled}`, () => session.connect())
+    }
+    for (let round = 0; round < rounds; round++) {
+      const order = round % 2 ? [...cases].reverse() : cases
+      for (const name of order) {
+        console.log(`${smoke ? 'smoke' : `round ${round + 1}/${rounds}`} ${name}`)
+        await attempt(name, round)
+      }
+    }
+  } catch (error) {
+    fatal = error instanceof UnsafeMeasurement ? error.message : 'PREREQUISITE_OR_CLEANUP_FAILED'
+    process.exitCode = 1
+  } finally {
+    cleanup.server = true
+    for (const session of sessions.values()) {
+      try { await session.close(); cleanup.server &&= session.transport.cleanupVerified }
+      catch { cleanup.server = false }
+    }
+    try {
+      if (installAttempted && cleanupFixture(adb, appId, !fixtureExisted)) cleanup.removed_install = true
+      cleanup.fixture = true
+    } catch { cleanup.fixture = false }
+    if (!cleanup.server || !cleanup.fixture || interrupted || attempts.some(value => !value.success)) process.exitCode = 1
+    if (!cleanup.server || !cleanup.fixture) fatal = 'CLEANUP_FAILED'
+    if (metadata) {
+      sourceStable = metadata.source_sha256 === treeHash('src') && metadata.build_sha256 === treeHash('dist') && metadata.harness_sha256 === treeHash('test/device/automated/latency')
+      if (!sourceStable) { fatal = 'MEASURED_SOURCE_CHANGED'; process.exitCode = 1 }
+    }
+    save()
+    process.off('SIGINT', signal); process.off('SIGTERM', signal)
+  }
+}
+main().catch(() => { console.error('Benchmark failed; inspect timing report'); process.exitCode = 1 })

package/test/device/automated/latency/owned-transport.ts

@@ -0,0 +1,81 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { setTimeout as delay } from 'node:timers/promises'
+import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/sdk/shared/stdio.js'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js'
+
+// A dedicated POSIX process group bounds cleanup to this benchmark's server
+// and its children. The SDK client and stdio wire protocol are unchanged.
+export class OwnedTransport implements Transport {
+  onclose?: () => void
+  onerror?: (error: Error) => void
+  onmessage?: (message: JSONRPCMessage) => void
+  private child?: ChildProcessWithoutNullStreams
+  private buffer = new ReadBuffer({ maxBufferSize: 64 * 1024 * 1024 })
+  private closed?: Promise<void>
+  private closing?: Promise<void>
+  cleanupVerified = false
+  constructor(private env: NodeJS.ProcessEnv, private stderr: (chunk: string) => void,
+    private args = ['dist/server.js']) {}
+
+  async start() {
+    if (process.platform === 'win32') throw new Error('POSIX benchmark transport required')
+    if (this.child) throw new Error('Already started')
+    this.child = spawn(process.execPath, this.args, { env: this.env, detached: true, stdio: 'pipe' })
+    this.closed = new Promise(resolve => this.child!.once('close', () => { this.onclose?.(); resolve() }))
+    this.child.on('error', error => this.onerror?.(error))
+    this.child.stdin.on('error', error => this.onerror?.(error))
+    this.child.stderr.on('data', chunk => this.stderr(String(chunk)))
+    this.child.stdout.on('data', chunk => {
+      try {
+        this.buffer.append(chunk)
+        let message
+        while ((message = this.buffer.readMessage()) !== null) this.onmessage?.(message)
+      } catch (error) { this.onerror?.(error as Error) }
+    })
+    await new Promise<void>((resolve, reject) => { this.child!.once('spawn', resolve); this.child!.once('error', reject) })
+  }
+
+  async send(message: JSONRPCMessage) {
+    if (!this.child) throw new Error('Not started')
+    await new Promise<void>((resolve, reject) => this.child!.stdin.write(serializeMessage(message), error => error ? reject(error) : resolve()))
+  }
+
+  private groupExists() {
+    if (!this.child?.pid) return false
+    try { process.kill(-this.child.pid, 0); return true }
+    catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      if (code === 'ESRCH') return false
+      // Darwin can return EPERM while a killed group is being reaped. It is
+      // still unconfirmed: retry until ESRCH, never count EPERM as absence.
+      if (code === 'EPERM') return true
+      throw error
+    }
+  }
+
+  private signal(signal: NodeJS.Signals) {
+    if (!this.child?.pid) return
+    try { process.kill(-this.child.pid, signal) }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error }
+  }
+
+  close() {
+    this.closing ??= this.cleanup()
+    return this.closing
+  }
+
+  private async cleanup() {
+    if (!this.child) { this.cleanupVerified = true; return }
+    this.child.stdin.end()
+    await Promise.race([this.closed, delay(1000)])
+    if (this.groupExists()) this.signal('SIGTERM')
+    await Promise.race([this.closed, delay(1000)])
+    if (this.groupExists()) this.signal('SIGKILL')
+    const deadline = performance.now() + 3000
+    while (this.groupExists() && performance.now() < deadline) await delay(50)
+    this.cleanupVerified = !this.groupExists()
+    this.buffer.clear()
+    if (!this.cleanupVerified) throw new Error('Owned process group did not exit')
+  }
+}