mobile-debug-mcp 0.36.0 → 0.37.0

package/dist/server.js

@@ -7,7 +7,7 @@ import { getSystemStatus } from './system/index.js';
 const server = createServer();
 if (process.env.MOBILE_DEBUG_MCP_STARTUP_HEALTHCHECK === '1') {
     getSystemStatus().then((res) => {
-        console.info('[startup] system status summary:', { adb: res.adbAvailable, ios: res.iosAvailable, devices: res.devices, iosDevices: res.iosDevices });
+        console.info('[startup] system status summary:', { adb: 'adbAvailable' in res ? res.adbAvailable : false, ios: 'iosAvailable' in res ? res.iosAvailable : false, devices: 'devices' in res ? res.devices : 0, iosDevices: 'iosDevices' in res ? res.iosDevices : 0 });
     }).catch((e) => console.warn('[startup] healthcheck failed:', e instanceof Error ? e.message : String(e)));
 }
 const transport = new StdioServerTransport();

package/dist/system/android.js

@@ -1,3 +1,4 @@
+import { probeInstallation, validAppId } from '../utils/app-installation.js';
 import { execSync } from 'child_process';
 import { ensureAdbAvailable } from '../utils/android/utils.js';
 export async function checkAndroid() {
@@ -9,6 +10,8 @@ export async function checkAndroid() {
     let logsAvailable = false;
     let envValid = false;
     let appInstalled = undefined;
+    let appInstallations = [];
+    let targets = [];
     try {
         const adbCheck = ensureAdbAvailable();
         const adbCmd = adbCheck.adbCmd || 'adb';
@@ -19,6 +22,7 @@ export async function checkAndroid() {
         try {
             const out = execSync(`${adbCmd} devices -l`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
             const state = parseDevices(out, issues);
+            targets = out.split('\n').map(line => line.trim().split(/\s+/)).filter(parts => parts[0] && !['List', '*'].includes(parts[0])).map(parts => ({ id: parts[0], available: parts[1] === 'device' }));
             devices = state.devices;
             deviceStates = state.deviceStates;
         }
@@ -43,15 +47,15 @@ export async function checkAndroid() {
         if (!envValid)
             issues.push('ANDROID_SDK_ROOT/ANDROID_HOME missing and adb not found in PATH');
         const pkg = process.env.MCP_TARGET_PACKAGE || process.env.MCP_TARGET_APP_ID;
-        if (pkg && adbAvailable && devices > 0) {
-            appInstalled = probeAppInstalled(adbCmd, pkg, issues);
-        }
+        appInstallations = await Promise.all(targets.map(target => probeInstallation(adbCmd, target.id, pkg, 'android-current-user', adbAvailable && target.available)));
+        reportInstallations(appInstallations, pkg, issues);
+        appInstalled = installationSummary(appInstallations);
     }
     catch (e) {
         console.debug('[get_system_status] adb availability check failed: ' + String(e));
         issues.push('ADB check failed');
     }
-    return { adbAvailable, adbVersion, devices, deviceStates, logsAvailable, envValid, appInstalled, issues };
+    return { adbAvailable, adbVersion, devices, deviceStates, logsAvailable, envValid, appInstalled, appInstallations, issues };
 }
 function parseDevices(out, issues) {
     const lines = out.split('\n').map(l => l.trim()).filter(Boolean);
@@ -73,16 +77,16 @@ function parseDevices(out, issues) {
         issues.push(`${stateCounts['offline']} device(s) offline`);
     return { devices, deviceStates };
 }
-function probeAppInstalled(adbCmd, pkg, issues) {
-    try {
-        const pm = execSync(`${adbCmd} shell pm path ${pkg}`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
-        const appInstalled = (pm || '').includes('package:');
-        if (!appInstalled)
-            issues.push(`App ${pkg} not installed on devices`);
-        return appInstalled;
-    }
-    catch (e) {
-        console.debug('[get_system_status] pm check failed: ' + String(e));
-        return false;
+function installationSummary(checks) {
+    return checks.length === 1 && checks[0].status !== 'unknown' ? checks[0].status === 'installed' : undefined;
+}
+function reportInstallations(checks, pkg, issues) {
+    if (pkg !== undefined && !validAppId(pkg))
+        issues.push('Invalid target app identifier');
+    for (const check of checks) {
+        if (check.status === 'absent')
+            issues.push(`App ${check.appId} not installed on device ${check.deviceId}`);
+        if (check.status === 'unknown' && check.reason !== 'APP_ID_NOT_PROVIDED')
+            issues.push(`Installation check unavailable on device ${check.deviceId}: ${check.reason}`);
     }
 }

package/dist/system/index.js

@@ -40,7 +40,8 @@ export async function getSystemStatus() {
             logsAvailable: androidRaw.logsAvailable,
             envValid: androidRaw.envValid,
             issues,
-            appInstalled: androidRaw.appInstalled,
+            ...(androidRaw.appInstalled === undefined ? {} : { appInstalled: androidRaw.appInstalled }),
+            appInstallations: androidRaw.appInstallations,
             iosAvailable: iosRaw.iosAvailable,
             iosDevices: iosRaw.iosDevices,
             gradleJavaHome: gradle.gradleJavaHome,

package/dist/utils/android/utils.js

@@ -1,7 +1,8 @@
 import { promises as fsPromises } from 'fs';
 import path from 'path';
 export { findInPath, resolveAdbCmd, getAdbCmd, ensureAdbAvailable, getAdbArgs, getAdbTimeout, execAdb, spawnAdb } from './commands.js';
-import { execAdb } from './commands.js';
+import { execAdb, getAdbCmd } from './commands.js';
+import { installationFields, probeInstallation } from '../app-installation.js';
 export { 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';
@@ -79,22 +80,12 @@ export async function listAndroidDevices(appId) {
                     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) {
-                        console.debug(`[listAndroidDevices] pm check failed for ${serial}: ${String(e)}`);
-                        appInstalled = false;
-                    }
-                }
-                return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled };
+                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) };
             }
-            catch (e) {
-                console.debug(`[listAndroidDevices] failed gathering metadata for ${serial}: ${String(e)}`);
-                return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false };
+            catch {
+                const check = await probeInstallation(getAdbCmd(), serial, appId, 'android-current-user', false);
+                return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, ...installationFields(check) };
             }
         }));
         return infos;

package/dist/utils/app-installation.js

@@ -0,0 +1,77 @@
+import { execFile } from 'node:child_process';
+import { execCmd } from './exec.js';
+import { remainingBudget } from './operation-budget.js';
+export function validAppId(appId) { return /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(appId); }
+export function installationContext(deviceId, appId, scope) {
+    return { status: 'unknown', appId: appId ?? null, deviceId, scope, checkedAt: null, reason: appId === undefined ? 'APP_ID_NOT_PROVIDED' : 'CHECK_FAILED' };
+}
+export function installationFields(appInstallation) {
+    return { appInstallation, ...(appInstallation.status === 'unknown' ? {} : { appInstalled: appInstallation.status === 'installed' }) };
+}
+export async function probeInstallation(command, deviceId, appId, scope, available = true) {
+    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, context) {
+    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;
+    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((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 = 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, context, timeout) {
+    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/dist/utils/benchmark-metrics.js

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+const measurement = new AsyncLocalStorage();
+// Private benchmark diagnostics: no arguments, device IDs or response contents.
+export function recordBenchmarkSpan(stage, duration) {
+    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(operation) {
+    return benchmarkStage('subprocess_ms', operation);
+}
+export async function benchmarkStage(stage, operation) {
+    if (!measurement.getStore())
+        return operation();
+    const started = performance.now();
+    try {
+        return await operation();
+    }
+    finally {
+        recordBenchmarkSpan(stage, performance.now() - started);
+    }
+}
+export async function withBenchmarkRequest(tool, operation) {
+    if (process.env.MOBILE_DEBUG_MCP_LATENCY_METRICS !== '1')
+        return operation();
+    const current = { 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/dist/utils/exec.js

@@ -1,7 +1,11 @@
 import { checkDebuggerGuard } from '../debugger/guard.js';
 import { remainingBudget } from './operation-budget.js';
 import { spawn } from 'child_process';
+import { benchmarkSubprocess } from './benchmark-metrics.js';
 export async function execCmd(cmd, args, opts = {}) {
+    return benchmarkSubprocess(() => execute(cmd, args, opts));
+}
+async function execute(cmd, args, opts) {
     const { env, cwd, shell } = opts;
     const timeout = remainingBudget(opts.timeout ?? 0);
     return new Promise((resolve, reject) => {

package/dist/utils/ios/utils.js

@@ -1,3 +1,4 @@
+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";
@@ -279,17 +280,9 @@ export async function listIOSDevices(appId) {
                                 simulator: true,
                                 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)); }));
                         }
                     }
                     Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out));

package/dist/utils/resolve-device.js

@@ -38,6 +38,7 @@ export async function listDevices(platform, appId) {
     return iosDeviceLister(appId);
 }
 const deviceContext = new AsyncLocalStorage();
+export function currentResolvedDevice() { return deviceContext.getStore(); }
 export function withResolvedDevice(device, operation) {
     bindEvidenceDevice(device);
     return deviceContext.run(device, operation);
@@ -75,7 +76,7 @@ function selectDevice(devices, platform, appId, prefer) {
     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;
     }
@@ -101,7 +102,7 @@ function selectDevice(devices, platform, appId, prefer) {
         if (candidates.length > 1 && parseNumericVersion(candidates[0].osVersion) > parseNumericVersion(candidates[1].osVersion)) {
             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/dist/utils/timing.js

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

package/docs/CHANGELOG.md

@@ -8,6 +8,31 @@ and [tool reference](tools/TOOLS.md) for the current checkout.
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.37.0]
+
+- Updated the agent plugin to `0.0.7`, pinned to MCP `0.37.0`.
+
+- Android debug snapshots use one fresh UI tree for the returned hierarchy and
+  screen fingerprint, removing a duplicate acquisition.
+
+- Add an end-to-end latency benchmark with repeated mode comparisons, visible
+  failed attempts, source/build identity, and opt-in timing-only request and
+  subprocess diagnostics. Public tool contracts and verification are unchanged.
+
+- Compact interaction/journey results now summarize observations, readiness, conditions and state deltas within explicit byte budgets. Detailed original results are available through session-local `get_interaction_diagnostics` references without replaying input. Debug output and response-mode defaults are unchanged.
+
+- Report device-scoped app installation as installed, absent or unknown. Publish
+  `list_devices.appId`; omit legacy installation booleans for inconclusive or
+  multi-device system checks instead of reporting false absence.
+
+- Clean up discarded iOS trace files after a recorder-stop failure when process
+  exit is confirmed, while retaining the failure and protecting live recordings.
+
+- Add timestamped device-readiness evidence to launch/interaction results and
+  readiness waits, preserving dispatch outcomes and compact/journey evidence.
+  Android power/keyguard blockers prevent readiness success; iOS reports
+  per-signal unknown/unsupported evidence. No automatic wake or unlock.
+
 ## [0.36.0]
 
 - Updated the agent plugin to `0.0.6`, pinned to MCP `0.36.0`.

package/docs/benchmarks/README.md

@@ -14,5 +14,6 @@ iOS latency.
 | --- | --- | --- | --- |
 | Interaction latency | [Run the benchmark](interaction-latency/README.md) | [Android measurements](interaction-latency/final.md), [iOS interaction validation](interaction-latency/ios-validation.md) | [018](../specs/018-interaction-latency-and-batched-journeys/spec.md) |
 | UI-tree observation | [Run the paired benchmark](ui-tree-performance/README.md) | [Comparison and limitations](ui-tree-performance/comparison.md) | [019](../specs/019-ui-tree-observation-performance/spec.md) |
+| End-to-end interaction latency | [Run the benchmarks](end-to-end-latency/README.md) | [Provisional Android results and iOS blocker](end-to-end-latency/investigation.md) | [036](../specs/036-end-to-end-interaction-latency/spec.md) |
 
 Fixture instructions: [latency journey app](../../test/fixtures/latency-journey-app/README.md).

package/docs/benchmarks/end-to-end-latency/README.md

@@ -0,0 +1,98 @@
+# End-to-end interaction latency
+
+[Benchmark index](../README.md) · [Specification](../../specs/036-end-to-end-interaction-latency/spec.md)
+
+This investigation reuses the Spec 018 Android fixture and Spec 019 tree metrics.
+It does not replace their historical results or optimization acceptance gates.
+Requires Node >=22, Java supporting `--release 8`, Android platform 36 and
+build-tools 36.0.0. Start an Android emulator, then run from the repository root:
+
+```sh
+npm run verify
+LATENCY_DEVICE_ID=emulator-5554 MCP_ADB_TIMEOUT=30000 npx tsx test/device/automated/latency/end-to-end.ts --smoke
+LATENCY_DEVICE_ID=emulator-5554 MCP_ADB_TIMEOUT=30000 npx tsx test/device/automated/latency/end-to-end.ts
+```
+
+Only explicitly named Android emulators are accepted; physical phones are not
+selected. Existing device resolution can enumerate other attached devices;
+the report records discovery counts without serials. No display configuration is changed. The dedicated fixture is built,
+installed, and reset; an installation created by this run is removed on exit.
+A pre-existing fixture installation is left installed, with reset fixture data.
+The harness owns isolated POSIX server process groups, closes them on exit and
+interrupt, and verifies their termination. An unsafe timeout stops the run;
+semantic failures are retained before the next explicitly recorded reset.
+
+The smoke uses one attempt per case and writes `smoke.json`/`smoke.md`; it is not
+performance evidence. The full run writes `baseline.json`/`baseline.md` after
+each attempt, preserving partial results on failure/interruption. It performs
+three warm-ups and ten measured attempts per case, reversing mode order every
+round. Do not run other device workloads concurrently.
+
+`baseline-attempt-1.json`/`.md` retain the first failed warm-up run: the emulator
+disappeared, the next reset failed, and fixture cleanup could not be confirmed.
+No measured samples were produced. Both owned server groups exited. The retry
+restores the same AVD headlessly using `emulator -avd Pixel_9_Pro -port 5554
+-no-window -no-snapshot-save`; it does not wipe data. This startup configuration
+is distinct from the earlier development smoke and failed attempt.
+
+Cases compare the original standalone handle flow and four full/light ×
+debug/compact journeys, retaining all six destination assertions. Screenshot,
+UI tree and screenshot/log-free snapshot calls are separate cases on the known
+fixture home screen, with instrumentation on and off. Light/compact has existing
+assertion-based observation sharing; mode differences can therefore include
+acquisition counts as well as response construction costs. They are not a pure
+serialization microbenchmark.
+
+Raw reports include source/build/harness/fixture hashes, dirty paths, environment,
+request order, byte counts, timing-only events, setup/startup durations and
+cleanup. Device serials, raw responses and unrestricted stderr are not retained.
+Source/build/harness changes during measurement invalidate the run. Externally
+run builds and validation suites are separate from MCP request time. This fixture
+uses offline SDK tools rather than Gradle. Device application work inside requests
+is included; it is not established as pure MCP overhead.
+
+Percentiles use nearest rank and successful attempts only; failures remain in
+raw records and fail the run. Warm-up failures are counted separately. Ten samples
+provide a preliminary p95, not a robust tail estimate. Inclusive component spans
+overlap and must not be summed. Handler residual subtracts their interval union;
+client-minus-handler includes scheduling, transport and uninstrumented work.
+Existing serialization spans cover selected response construction, not all SDK
+wire serialization. Tree event stages expose acquisition, retry and parse costs.
+Subprocess spans cover `execCmd`; direct platform spawns can remain in residuals.
+
+Compare observation `on`/`off` results to assess probe overhead; these include
+normal device variability and are not automatically a causal overhead estimate.
+`missing_request_metrics` is expected for `off` cases only. Instrumentation uses
+`MOBILE_DEBUG_MCP_LATENCY_METRICS=1` and the existing
+`MOBILE_DEBUG_MCP_UI_TREE_METRICS=1` only in instrumented benchmark servers.
+Normal MCP contracts and diagnostic output are unchanged.
+
+For standalone iOS observations, use an isolated booted simulator with working
+idb discovery and English Settings. The runner confirms the Settings root
+before each timed request and records preparation time separately.
+
+```sh
+IOS_LATENCY_DEVICE_ID=YOUR_SIMULATOR_ID npx tsx test/device/automated/latency-ios/benchmark.ts --smoke
+IOS_LATENCY_DEVICE_ID=YOUR_SIMULATOR_ID npx tsx test/device/automated/latency-ios/benchmark.ts
+```
+
+Equivalent iOS fixture journeys depend on [#89](https://github.com/clivejefferies/mobile-debug-tools/issues/89).
+See the [investigation report](investigation.md) for the Android measurements
+and the observed iOS setup blocker.
+
+For a focused [Android snapshot comparison](android-snapshot-pair.md), build
+the pre-change checkout and preserve its emitted `dist` directory and source
+hash. The preserved build needs its ESM `package.json` and the same installed
+dependencies. Build the candidate in the current checkout, then run:
+
+```sh
+LATENCY_DEVICE_ID=emulator-5554 \
+SNAPSHOT_BASELINE_SERVER=/absolute/path/to/baseline/dist/server.js \
+SNAPSHOT_BASELINE_SOURCE_SHA=BASELINE_SOURCE_SHA256 \
+MCP_ADB_TIMEOUT=30000 \
+node --import tsx test/device/automated/latency/snapshot-pair.ts
+```
+
+Use the `treeHash` helper in `end-to-end-environment.ts` to hash baseline `src`
+before editing it. This command writes `android-snapshot-pair.json` with the
+attempts and acceptance result.