mobile-debug-mcp 0.35.0 → 0.37.0

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

package/test/device/automated/latency/snapshot-pair.ts

@@ -0,0 +1,143 @@
+import { writeFileSync } from 'node:fs'
+import { dirname, isAbsolute } from 'node:path'
+import assert from 'node:assert/strict'
+import { computeScreenFingerprint } from '../../../../src/utils/ui/index.js'
+import type { CaptureDebugSnapshotRawResponse, GetCurrentScreenResponse } from '../../../../src/types.js'
+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, type Attempt } from './end-to-end-report.js'
+
+const device = process.env.LATENCY_DEVICE_ID ?? ''
+const baseline = process.env.SNAPSHOT_BASELINE_SERVER ?? ''
+const baselineSource = process.env.SNAPSHOT_BASELINE_SOURCE_SHA ?? ''
+assert.match(device, /^emulator-\d+$/)
+assert.ok(isAbsolute(baseline) && /^[a-f0-9]{64}$/.test(baselineSource), 'Provide the frozen baseline server path and source hash')
+const adb = (...args: string[]) => command('adb', ['-s', device, ...args])
+const app = 'dev.mobiledebugmcp.latencyfixture'
+const fixtureActivity = `${app}.MainActivity`
+const options = { includeScreenshot: false, includeLogs: false }
+const attempts: Attempt[] = []
+const sessions = {
+  baseline: new BenchmarkSession(device, true, baseline),
+  candidate: new BenchmarkSession(device, true)
+}
+type Build = keyof typeof sessions
+let installAttempted = false, launched = false, interrupted = false
+let fatal: string | undefined, metadata: ReturnType<typeof environment> | undefined
+let fixtureSha: string | undefined
+let nativeFreshness = false
+const baselineHash = treeHash(dirname(baseline))
+const cleanup = { servers: false, fixture: false }
+
+async function checkFixtureActivity(session: BenchmarkSession) {
+  const screen = await session.call('get_current_screen', {}, [])
+  assert.equal(screen.package, app)
+  assert.equal(screen.activity, fixtureActivity)
+}
+
+function verifyFingerprint(raw: CaptureDebugSnapshotRawResponse) {
+  const tree = raw.ui_tree
+  assert.ok(tree && tree.device.id === device && tree.snapshot_revision)
+  assert.equal(raw.snapshot_revision, tree.snapshot_revision)
+  assert.equal(raw.captured_at_ms, tree.captured_at_ms)
+  assert.match(raw.fingerprint ?? '', /^[a-f0-9]{64}$/)
+  const current: GetCurrentScreenResponse = { device: tree.device, activity: fixtureActivity, package: app, shortActivity: '' }
+  assert.equal(raw.fingerprint, computeScreenFingerprint(tree, current, 'android').fingerprint)
+}
+
+async function sample(build: Build, iteration: number) {
+  if (interrupted) throw new UnsafeMeasurement('INTERRUPTED')
+  const attempt: Attempt = { case: build, iteration, warmup: iteration < 3, success: false, setup_ms: 0, requests: [] }
+  attempts.push(attempt)
+  try {
+    await checkFixtureActivity(sessions[build])
+    const data = await sessions[build].call('capture_debug_snapshot', options, attempt.requests)
+    const raw = data.raw as CaptureDebugSnapshotRawResponse
+    assert.ok(raw.ui_tree?.elements.some(element => element.contentDescription === 'home-screen' || element.text === 'home-screen'))
+    await checkFixtureActivity(sessions[build])
+    if (build === 'candidate') {
+      verifyFingerprint(raw)
+      assert.equal(attempt.requests[0].tree.filter(event => event.type === 'acquisition_completed').length, 1)
+    }
+    attempt.success = true
+  } catch (error) {
+    attempt.failure = attempt.requests[0]?.failure ?? 'SNAPSHOT_ASSERTION_FAILED'
+    if (error instanceof UnsafeMeasurement) throw error
+  }
+}
+
+async function checkFreshness() {
+  const candidate = sessions.candidate
+  const before = (await candidate.call('capture_debug_snapshot', options, [])).raw as CaptureDebugSnapshotRawResponse
+  await candidate.call('run_journey', { steps: [
+    { id: 'open', type: 'tap', selector: { accessibility_id: 'saved-session' } },
+    { id: 'check', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'idle-detail' } }, timeoutMs: 15000 }
+  ], defaults: { verificationMode: 'light' }, responseMode: 'compact' }, [])
+  await checkFixtureActivity(candidate)
+  const after = (await candidate.call('capture_debug_snapshot', options, [])).raw as CaptureDebugSnapshotRawResponse
+  await checkFixtureActivity(candidate)
+  verifyFingerprint(after)
+  assert.ok(after.ui_tree?.elements.some(element => element.contentDescription === 'idle-detail'))
+  assert.ok(after.snapshot_revision > before.snapshot_revision)
+  assert.notEqual(after.fingerprint, before.fingerprint)
+  nativeFreshness = true
+}
+
+async function main() {
+  const stop = () => { interrupted = true; for (const session of Object.values(sessions)) session.abort() }
+  process.on('SIGINT', stop); process.on('SIGTERM', stop)
+  try {
+    assert.equal(adb('get-state'), 'device')
+    assert.equal(adb('shell', 'getprop', 'ro.kernel.qemu'), '1')
+    const apk = buildFixture()
+    if (!fixturePresent(adb, app)) {
+      installAttempted = true
+      adb('install', apk)
+    }
+    const packagePath = adb('shell', 'pm', 'path', app).match(/^package:(.+)$/)?.[1]
+    assert.ok(packagePath)
+    fixtureSha = adb('shell', 'sha256sum', packagePath).split(/\s+/)[0]
+    assert.match(fixtureSha, /^[a-f0-9]{64}$/)
+    metadata = { ...environment(device, apk), fixture_sha256: fixtureSha }
+    adb('shell', 'am', 'force-stop', app)
+    launched = true
+    adb('shell', 'am', 'start', '-W', '-n', `${app}/.MainActivity`)
+    for (const session of Object.values(sessions)) await session.connect()
+    await sessions.baseline.call('expect_element_visible', { selector: { accessibility_id: 'home-screen' }, timeout_ms: 30000 }, [])
+    for (let iteration = 0; iteration < 13; iteration++) {
+      const order: Build[] = iteration % 2 ? ['candidate', 'baseline'] : ['baseline', 'candidate']
+      for (const build of order) {
+        console.log(`Round ${iteration + 1}/13 ${build}`)
+        await sample(build, iteration)
+      }
+    }
+    await checkFreshness()
+  } catch (error) { fatal = error instanceof UnsafeMeasurement ? error.message : 'SETUP_OR_FRESHNESS_FAILED' }
+  finally {
+    cleanup.servers = true
+    for (const session of Object.values(sessions)) {
+      try { await session.close(); cleanup.servers &&= session.transport.cleanupVerified }
+      catch { cleanup.servers = false }
+    }
+    try {
+      if (launched || installAttempted) cleanupFixture(adb, app, installAttempted)
+      cleanup.fixture = true
+    } catch { cleanup.fixture = false }
+    process.off('SIGINT', stop); process.off('SIGTERM', stop)
+  }
+  const summaries = summarizeAttempts(attempts)
+  const prior = summaries.baseline
+  const next = summaries.candidate
+  const sourceStable = metadata?.source_sha256 === treeHash('src') && metadata?.build_sha256 === treeHash('dist') &&
+    metadata?.harness_sha256 === treeHash('test/device/automated/latency') && baselineHash === treeHash(dirname(baseline))
+  const passed = !fatal && !interrupted && sourceStable && cleanup.servers && cleanup.fixture && nativeFreshness &&
+    attempts.length === 26 && attempts.every(attempt => attempt.success) && prior?.total_ms?.count === 10 && next?.total_ms?.count === 10 &&
+    next.physical_reads < prior.physical_reads && next.total_ms.p50 <= prior.total_ms.p50 && next.total_ms.p95 < prior.total_ms.p95
+  const report = { passed, fatal, interrupted, unrun_attempts: 26 - attempts.length, sourceStable, cleanup, nativeFreshness,
+    metadata, expected_fixture_activity: fixtureActivity, fixture_installed_sha256: fixtureSha, baseline: { source_sha256: baselineSource, build_sha256: baselineHash }, summaries, attempts }
+  writeFileSync('docs/benchmarks/end-to-end-latency/android-snapshot-pair.json', JSON.stringify(report, null, 2) + '\n')
+  process.exitCode = passed ? 0 : 1
+}
+
+main().catch(() => { console.error('Snapshot comparison could not write its report'); process.exitCode = 1 })