mobile-debug-mcp 0.32.0 → 0.32.2

package/docs/specs/019-ui-tree-observation-performance/spec.md

@@ -0,0 +1,148 @@
+# Specification 019 — UI-Tree Observation Performance
+
+## Status
+
+Implemented for Android with a paired emulator benchmark. iOS correctness has
+unit and simulator smoke coverage; iOS latency remains unmeasured. See
+`docs/benchmarks/ui-tree-performance/` for the initial baseline, paired reports,
+and the retained failed first comparison attempt.
+
+## 1. Summary
+
+Reduce the elapsed time spent obtaining accessibility trees during interaction journeys while preserving fresh-state verification. Measure physical hierarchy reads and their cost first. Then remove demonstrably redundant work within a single observation or journey, and shorten platform acquisition where it can be done without returning an older tree as new evidence.
+
+No public tool, request field, default verification mode, or response shape changes in this specification.
+
+## 2. Current state and problem
+
+Specification 018's checked-in Android benchmark reports a 51.8-second p50 `light`/`compact` journey on a Pixel 9 Pro Android 16 emulator. That is faster than its full/debug comparison, but still slow for an agent completing a short flow. The 018 report does not attribute the compact journey's time to individual hierarchy reads, so it does not establish how much of the remaining 51.8 seconds this work can save.
+
+The present Android `getUITree` path obtains device metadata and display resolution, waits before an attempt, invokes `uiautomator dump`, reads the dumped XML, and parses it. The iOS path obtains device metadata, checks `idb`, waits, invokes `idb ui describe-all --json`, and parses the result. Both may retry. `wait_for_ui` and journey assertions can take multiple observations by design.
+
+Specification 018 already passes the selector-resolution tree into `tapElementHandler` and, for a compact light tap immediately followed by an element-visible assertion, uses that assertion as the post-action observation. Spec 019 must retain those savings. It must not count a pre-action selector tree as proof of a post-action state, or collapse independent samples required by stabilization.
+
+The roadmap's wait/synchronization work requires explicit freshness and reliable in-place UI updates. A network-backed screen can change without any MCP action. A time-based cross-request tree cache would therefore risk false assertions even if it improves a static fixture benchmark.
+
+An agent report describes faster app start, tap dispatch, and screenshots, while reporting that `find_element` remains the slowest operation and that `verificationMode: "light"` often returns `VERIFICATION_UNAVAILABLE` after consuming its verification budget. The report provides no device, platform, sample count, request sequence, timeout, or raw measurements, so these figures are investigation leads and are not baseline evidence or acceptance results. In this specification, measure target resolution, dispatch, post-action observation, and assertion costs separately. A failed light observation remains the successful-delivery/incomplete-evidence outcome defined by Spec 018; this work must not relabel it as an action failure or silently remove the observation.
+
+## 3. Goals
+
+1. Attribute journey latency to physical hierarchy acquisition, retries, metadata/resolution work, parsing, waits, and assertions, without recording UI contents or device serials.
+2. Reduce physical reads or their per-read cost on the measured hot path.
+3. Preserve fresh observations after actions and during asynchronous, in-place UI changes.
+4. Preserve selector actionability, stale-reference protection, snapshot revisions/deltas, timeout handling, and existing verification modes.
+5. Demonstrate the resulting speed and correctness on both a static fixture flow and a controlled network-backed flow.
+
+## 4. Non-goals
+
+- A cross-request or fixed-TTL cache of UI trees.
+- Treating elapsed time alone as evidence that a tree is current.
+- Weakening `expect_*` stabilization, two-sample checks, or the meaning of `light` and `full` verification.
+- Changing screenshot, log, network, or debugger tools except for test instrumentation needed to distinguish their cost.
+- Claiming an iOS latency gain from Android measurements.
+- Depending on a live external service for the acceptance benchmark.
+
+## 5. Observation and reuse contract
+
+A **physical tree read** is one invocation of Android `uiautomator dump` and retrieval of its XML, or one invocation of iOS `idb ui describe-all`. A retry is another physical read. Metadata queries, display-resolution queries, parsing, and selector evaluation are separate timing components. An **observation** is a successfully parsed tree from one physical read, with its platform, resolved device, capture completion time, and snapshot revision. Failed reads have an error but produce no reusable observation.
+
+An **observation transaction** is an internal call that names all consumers before starting one physical acquisition. It ends when that acquisition returns or fails. A consumer added later, including a later journey step, starts a new transaction unless an existing Spec 018 path explicitly passes the same tree within the ongoing step. This boundary avoids silently making a later assertion depend on a tree captured before a network update. Consumers must be declared before acquisition starts; this spec does not authorize coalescing independent concurrent calls. Existing same-step explicit tree passing remains permitted.
+
+The implementation may share one completed observation among consumers in the same observation transaction only if all of these hold:
+
+- The consumers use the same resolved platform and device.
+- No action dispatch, app lifecycle operation, scroll, or other operation capable of changing the visible hierarchy occurred between them.
+- Neither consumer requests a later or independent sample. In particular, stabilization windows, `not_exists` confirmation, and screen-fingerprint convergence retain their required separate reads.
+- A caller that requests post-action evidence receives a read started after that action's dispatch, never the tree used to find its target.
+- An observation that failed, timed out, or was cancelled is never reused.
+
+The implementation MUST NOT persist a reusable tree across MCP requests. It MUST NOT report a reused tree with a new `captured_at_ms` or `snapshot_revision`. This spec does not permit single-flight sharing across independently entered calls. If a future implementation proposes such sharing, it needs a separate contract for waiter cancellation, per-caller deadlines, acquisition deadline ownership, and process-exit confirmation before the sharing change is implemented.
+
+If these conditions cannot be proven at a call site, perform a fresh read. The specification permits optimizing metadata queries, resolution queries, the acquisition command, or parsing instead of introducing observation reuse.
+
+## 6. Platform and failure behavior
+
+The public `get_ui_tree`, `wait_for_ui`, selector tap, `expect_*`, `run_journey`, and debug-snapshot contracts remain as defined by existing specs. Compact responses continue to omit debug timing components. Diagnostic measurements are collected by the benchmark harness or an internal, opt-in test hook; they are not added to compact tool responses.
+
+An expired operation or verification budget stops polling and terminates the active device command under the existing `ACTION_TIMEOUT` or verification-unavailable rules. It does not leave a background tree read that can overlap the next action. For this contract, termination is complete only when the spawned hierarchy command has emitted its close/exit event; sending a kill signal alone does not satisfy it. The caller must not start a subsequent device action until termination is confirmed. A failed acquisition keeps the existing observable error and retry behavior. If an optimization cannot supply a qualifying fresh tree, it falls back to the existing acquisition path within the same remaining deadline. The fallback must not start after the deadline.
+
+Tree revisions and deltas are derived only from actual observations. Sharing one observation cannot create a new revision or a second stability sample. Device identity is resolved before any sharing decision; observations from different emulators, simulators, or platforms are isolated.
+
+## 7. Measurement contract
+
+Add internal instrumentation at the adapter boundary and journey call sites. For each measured run, record counts and elapsed milliseconds for:
+
+| Field | Meaning |
+|---|---|
+| `physical_tree_reads` | Number of platform hierarchy commands started, including retries. |
+| `tree_read_ms` | Android dump plus XML retrieval, or the iOS hierarchy command, from start to exit. |
+| `metadata_ms` | Device metadata and capability checks performed for tree acquisition. |
+| `capability_check_ms` | Platform tooling availability checks, when measured separately from metadata. |
+| `resolution_ms` | Display-size acquisition, where applicable. |
+| `parse_ms` | Parsing and conversion to the public element model. |
+| `observation_wait_ms` | Intentional pre-read waits and polling delays. |
+| `target_resolution_ms` | Time spent finding, selecting, and validating an actionable target before dispatch. |
+| `dispatch_ms` | Time from action dispatch start until the platform action command completes. |
+| `verification_budget_ms` | Effective light-verification budget for the action. |
+| `verification_elapsed_ms` | Time spent obtaining the light post-action observation, including waits and failed attempts. |
+| `verification_outcome` | `observed`, `unavailable`, or `not_requested`, matching the public action outcome. |
+| `reused_observations` | Consumers served by an eligible existing observation. |
+| `failed_tree_reads` | Commands that failed, timed out, or were cancelled. |
+
+The measurement record also includes the journey step ID, observation purpose (`target`, `verification`, `assertion`, or `debug`), platform, and whether the read started before or after the preceding dispatch. Each physical acquisition has one unique internal acquisition ID and is recorded exactly once; each consumer use has a separate consumer record referring to that ID. When one acquisition serves multiple purposes, record one acquisition and all consumer records; do not duplicate its duration or physical-read count in aggregate totals. Count `failed_tree_reads` once for each hierarchy command that fails to start, exits unsuccessfully, times out, or is cancelled before successful output retrieval. A successful hierarchy command followed by empty/invalid output is a failed acquisition and is counted once. For light verification, record whether the observation budget expired, how much of the effective budget elapsed, and the associated acquisition IDs, including failed attempts. This data is used to determine whether `VERIFICATION_UNAVAILABLE` is driven by command acquisition, metadata, intentional waits, parsing, or the configured budget. The report groups acquisition cost and consumer count by step and purpose; raw timestamps need not be checked in. It MUST NOT include tree nodes, UI text, app identifiers, screenshots, logs, network payloads, or device serials.
+
+The harness measures the full MCP request from write to complete response as in Spec 018. Timing components need not sum exactly to wall time where work overlaps, but the report must identify overlap and use wall time for performance gates.
+
+## 8. Reproducible benchmark flows
+
+Create `test/device/automated/ui-tree-performance/` and `docs/benchmarks/ui-tree-performance/`. Build on Spec 018's spawned `dist/server.js` client and Android fixture rather than introducing a second transport or test framework. First land only instrumentation and the benchmark fixture; capture that clean commit as the baseline using `benchmark.ts --baseline-only`, before changing acquisition behavior. The baseline-only run writes `baseline.json`. After choosing and implementing an optimization, measure the candidate against the same instrumentation, fixture APK SHA-256, emulator image, display settings, and host configuration. Record both commit SHAs, server version, platform/model/OS/API, command timeout, sample counts, failures, and request sequences.
+
+The harness accepts `UI_TREE_BASELINE_ROOT`, `UI_TREE_CANDIDATE_ROOT`, and `LATENCY_DEVICE_ID`. Each root must be a clean, built checkout containing `dist/server.js`; missing or dirty inputs fail before a device reset. It starts each server over stdio from the supplied root, uses the single candidate fixture APK for both modes, and writes `baseline.json`, `candidate.json`, and `comparison.md` under `docs/benchmarks/ui-tree-performance/`. A reviewer can reproduce the comparison with:
+
+```sh
+UI_TREE_BASELINE_ROOT=/path/to/instrumented-baseline \
+UI_TREE_CANDIDATE_ROOT=/path/to/optimized-candidate \
+LATENCY_DEVICE_ID=emulator-5554 \
+npx tsx test/device/automated/ui-tree-performance/benchmark.ts
+```
+
+Two flows are required:
+
+1. **Static journey:** the Spec 018 navigation/control journey using `light`/`compact`, with the same actions and assertions in baseline and candidate. It isolates hierarchy overhead without network variance.
+2. **Network-backed in-place update:** a deterministic local HTTP server drives an Android fixture screen from `loading` to `ready` after a configured delay, without navigation or a second MCP action. The fixture exposes stable accessibility IDs `loading`, `ready`, and `value`. For each attempt, the harness starts the fixture and server in a known reset state. The server holds the response until a completed MCP observation contains `loading` and contains neither `ready` nor `value`; it then starts the configured delay and sends `ready` with a run-unique value in the same response, recording a monotonic send timestamp and run ID. The harness then issues a fresh observation request after the response send event and asserts that one observation contains both `ready` and the matching run-unique value. A read that started before the response send event cannot satisfy this assertion even if it completes afterward. Run one response delay of 100 ms and one of 1,500 ms. Use emulator-to-host routing supplied by the harness; do not call a public service.
+
+Both flows run sequentially, with three warm-ups followed by exactly ten measured attempts per flow, response-delay setting, and baseline/candidate mode. Failed runs are counted and excluded from percentiles, with the failed step and selector reported; any failed measured attempt fails acceptance. Screenshots and debug snapshots are outside the timed journeys and may be reported separately. Baseline and candidate order should alternate by run pair to limit emulator drift; the fixture and local server are reset before every run. The reports must state the timing boundary for every metric and include per-attempt acquisition/consumer records so the aggregation rules in Section 7 can be reproduced.
+
+For iOS, automated unit tests with controlled `idb` output and the existing simulator smoke tests must cover correctness and cancellation. An iOS latency claim requires a reproducible iOS fixture and the same paired protocol; until then, report iOS performance as unmeasured.
+
+## 9. Acceptance criteria
+
+1. The baseline report identifies the physical-read count and p50/p95 time for each purpose and journey step, and distinguishes hierarchy command time from waits and parsing. It reports target-resolution, dispatch, and light-verification elapsed time and outcomes, including the rate and elapsed budget for `VERIFICATION_UNAVAILABLE`.
+2. On the static Android journey, candidate p50 end-to-end time improves by at least 15% against its paired baseline, with no more than 5% p95 regression. At least one measured hot-path component must account for the gain; a response-size-only gain does not satisfy this spec.
+3. On both network-backed delay settings, candidate p95 end-to-end time does not regress by more than 5%. The ready/value assertions never pass before the corresponding server response, and no run passes using a pre-update tree. The request start timestamp for the observation supplying the assertion must be later than that attempt's recorded response-send timestamp.
+4. Baseline and candidate have zero assertion failures across the ten measured attempts per flow. Every failed warm-up or measured attempt remains visible in the report; no failed run contributes to a percentile.
+5. Focused tests prove that a post-action assertion gets a post-dispatch read, two-sample stabilization uses two physical reads, device isolation holds, a failed/cancelled observation is not reused, and a budget expiry waits for hierarchy child-process exit before a subsequent device action can begin. Tests also prove one physical acquisition is counted once when explicitly passed to multiple same-step consumers, while all consumers receive records linked to that acquisition.
+6. `npm run verify` and `npm run test:device` pass. Existing Spec 018 response-shape and journey tests continue to pass. The checked-in JSON and Markdown reports identify exactly which platforms and flows were measured.
+
+If the 15% gate cannot be met without weakening freshness or verification, stop the optimization and report the measured bottleneck and failed gate. Do not lower the gate or mark this specification implemented on the strength of a synthetic unit benchmark.
+
+## 10. Implementation plan and ownership
+
+1. Add measurement hooks and reproduce the baseline before changing acquisition behavior. Validate the counters against a fake Android `adb` and fake iOS `idb` command so retries, invalid output, termination, and cancellations are counted once per actual acquisition and child-process exit is observable before the next action.
+2. Use the baseline breakdown to select one or more changes in `src/observe/android.ts`, `src/observe/ios.ts`, `src/observe/index.ts`, or `src/interact/index.ts`. Document why each changed read is redundant or why its replacement is equivalently fresh.
+3. Preserve the contracts in Section 5 with focused unit tests under `test/unit/observe/` and `test/unit/interact/`. Add the controlled network fixture and harness under `test/device/automated/`.
+4. Run the paired benchmarks and required repository gates. Check in baseline and candidate reports, update tool documentation only if user-visible behavior changes, and record any unmeasured platform separately.
+
+The benchmark and fixture belong to this repository. No backend or third-party service is required. Device testing requires the Android SDK/emulator and, for iOS smoke checks, a booted simulator with `idb`; inability to access either is an execution blocker for that platform's acceptance check, not evidence that it passed.
+
+## 11. Baseline decision and result
+
+The initial Android baseline found 20 physical tree reads in each measured
+static journey, including independent assertion samples, and an approximately
+400 ms intentional wait before every first attempt. No cross-request tree
+reuse was added. The candidate starts the first Android read immediately and
+retains the wait for retries. The clean repeat paired run improved static p50
+from 52.40 s to 43.82 s (16.4%) with no network p95 regression or failed
+attempts. A prior paired attempt had two network failures and is retained in
+the benchmark directory; its cause remains unconfirmed. This result does not
+claim that `VERIFICATION_UNAVAILABLE` is eliminated in other apps.

package/docs/tools/observe.md

@@ -92,6 +92,8 @@ Notes:
 - Elements may also include platform-native identity hints such as `stable_id`, `role`, `test_tag`, `selector`, and `semantic`.
 - The tree response may include `snapshot_revision`, `captured_at_ms`, and `loading_state` when a reliable signal is available.
 - Prefer `wait_for_ui` for deterministic element resolution in interactive flows.
+- Android 14+ can use the experimental persistent hierarchy reader. Build its APK with `npx tsx test/fixtures/ui-tree-bridge/build.ts`, then set `MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK` to its absolute path before starting the server. The reader clears Android's accessibility cache before every tree read, including when a screen changes without an accessibility event. Older Android versions use `uiautomator dump`.
+- If the bridge fails, the server stops it before falling back to `uiautomator dump`. While running, the bridge holds Android's UiAutomation connection, so other `uiautomator dump` clients may fail. Leave the variable unset for the default reader. To reproduce the device probe, set `LATENCY_DEVICE_ID` and run `npx tsx test/device/automated/ui-tree-performance/bridge-probe.ts`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.32.0",
+  "version": "0.32.2",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/skills/mobile-debug-tools-usage/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: mobile-debug-mcp
+description: Verify Android app behaviour efficiently with mobile-debug MCP, especially session playback, background work, and notifications. Use for emulator/device QA; do not use for implementation-only checks.
+metadata:
+  author: modul8-team
+  version: "1.0"
+---
+
+# Mobile-debug MCP verification
+
+Use mobile-debug MCP to make a product claim observable on a real device or emulator. A successful tap proves only that the input was delivered; verify the resulting UI, notification, or persisted state before reporting success.
+
+## Choose the lightest evidence that proves the claim
+
+- Use an accessibility assertion such as `expect_element_visible` or
+  `wait_for_ui` for an accessible label, enabled state, or changed control.
+- Use a screenshot when visual layout, system UI, or notification content matters.
+- Use a debug snapshot only when the screen does not explain a failed action or an accessibility-tree assertion is needed.
+- Use Android shell commands only for device navigation or system surfaces that MCP cannot expose. Do not treat shell output as proof of user-visible behaviour.
+
+Avoid repeated screenshots and snapshots when a targeted accessibility assertion is enough.
+
+## Keep interaction fast
+
+Treat each MCP call as a round trip and use the fastest path that still proves
+the behaviour. Prefer the following sequence:
+
+1. Wait for one stable, uniquely identifiable control.
+2. Tap its returned element id.
+3. Wait for the specific resulting state.
+
+Do not wait before every tap when the current screen and element id are already known. Do not poll unchanged screens. Use short timeouts for ordinary controls; reserve longer waits for known asynchronous work such as model initialisation or network calls.
+
+Use compact responses for routine actions. If action dispatch is reliable but
+verification is slow or unavailable, dispatch with verification disabled and
+verify at meaningful checkpoints with one focused accessibility assertion or
+screenshot. Do not assume `light` verification is faster: use it only when it
+has returned useful results reliably on the current MCP version and device.
+
+Prefer a stable element selector when the accessibility tree exposes one. Use
+coordinates only when needed, and take a fresh screenshot immediately before a
+coordinate tap on system UI, notifications, or any screen where layout may have
+changed. Never reuse coordinates after expanding/collapsing a notification,
+changing orientation, or switching screens.
+
+Element discovery can be the slowest part of a journey. Avoid repeated
+`find_element` calls for the same screen: resolve a control once, use the
+returned selector or coordinates while that screen is unchanged, and verify
+the resulting state before continuing. If a query fails, inspect the current
+screen once before retrying; controls represented only by icons may not have a
+matching visible text label.
+
+When the MCP offers a journey or batch action, use it only when its steps can
+express the needed observable checks and it returns enough evidence to report
+the outcome. Measure the whole journey and compare equivalent steps on the same
+device; do not infer a performance improvement from a single fast action.
+
+## Session playback checks
+
+For a claimed playback start, observe a running timer or Pause state after Play. For a claimed pause, observe Resume and unchanged elapsed time. For a claimed stop, observe that playback ends and the notification disappears.
+
+For background playback, press Home, open the notification shade, and verify
+the notification title, progress/status, and available actions. Expand the
+session notification if necessary, then capture its current layout before
+tapping an action. Exercise each action needed for the change and observe its
+result: Pause becomes Resume; Resume returns to active playback; Stop ends
+playback and clears the notification. After each action, reacquire the current
+screen state before using another coordinate.
+
+Do not claim spoken guidance was verified unless audio output was actually inspected. A running timer or active notification verifies playback state, not audible wording.
+
+## Report evidence precisely
+
+State the device journey, observed result, and any untested scope. Mention whether evidence came from an accessibility assertion, screenshot, or system notification. Do not say a feature works solely because the build compiled or an MCP action returned success.

package/src/observe/android-tree-bridge.ts

@@ -0,0 +1,178 @@
+import { execFile, spawn, spawnSync, type ChildProcess } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { connect } from 'node:net'
+import path from 'node:path'
+import { execAdb, getAdbCmd } from '../utils/android/utils.js'
+import { remainingBudget } from '../utils/operation-budget.js'
+
+const packageName = 'dev.mobiledebugmcp.treebridge'
+const component = `${packageName}/.TreeInstrumentation`
+const devicePort = 39019
+
+interface Bridge {
+  deviceId: string
+  hostPort: number
+  child: ChildProcess
+  closed: boolean
+  childClosed: boolean
+}
+
+const active = new Map<string, Bridge>()
+const starting = new Map<string, Promise<Bridge>>()
+const stopping = new Map<string, Promise<void>>()
+const bridgeSupport = new Map<string, boolean>()
+
+export function androidTreeBridgeEnabled(): boolean {
+  return Boolean(process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK)
+}
+
+function configuredApk() {
+  const configured = process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK
+  if (!configured) return null
+  const apk = path.resolve(configured)
+  if (!existsSync(apk)) throw new Error(`Android UI tree bridge APK does not exist: ${apk}`)
+  return apk
+}
+
+function unbudgetedAdb(deviceId: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    execFile(getAdbCmd(), ['-s', deviceId, ...args], { timeout: 5000 }, (error) => error ? reject(error) : resolve())
+  })
+}
+
+function request(bridge: Bridge, command: 'PING' | 'TREE' | 'STOP', timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let output = ''
+    const socket = connect(bridge.hostPort, '127.0.0.1', () => socket.write(`${command}\n`))
+    socket.setTimeout(timeoutMs, () => socket.destroy(new Error(`Android UI tree bridge ${command} timed out`)))
+    socket.on('data', (chunk) => {
+      output += chunk.toString()
+      if (command === 'STOP' && output.startsWith('OK\n')) {
+        resolve(output)
+        socket.destroy()
+      }
+    })
+    socket.on('error', reject)
+    socket.on('end', () => resolve(output))
+  })
+}
+
+function waitForChildClose(bridge: Bridge, timeoutMs: number): Promise<void> {
+  if (bridge.childClosed) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    const onClose = () => { clearTimeout(timer); resolve() }
+    const timer = setTimeout(() => {
+      bridge.child.off('close', onClose)
+      reject(new Error('Android UI tree bridge child did not exit'))
+    }, timeoutMs)
+    bridge.child.once('close', onClose)
+  })
+}
+
+async function stop(bridge: Bridge): Promise<void> {
+  const pending = stopping.get(bridge.deviceId)
+  if (pending) return pending
+  bridge.closed = true
+  const cleanup = (async () => {
+    await request(bridge, 'STOP', 1000).catch(() => '')
+    let forceStopError: unknown
+    try { await unbudgetedAdb(bridge.deviceId, ['shell', 'am', 'force-stop', packageName]) }
+    catch (error) { forceStopError = error }
+    try { await waitForChildClose(bridge, 1000) }
+    catch {
+      bridge.child.kill('SIGTERM')
+      try { await waitForChildClose(bridge, 1000) }
+      catch {
+        bridge.child.kill('SIGKILL')
+        await waitForChildClose(bridge, 2000).catch(() => {})
+      }
+    }
+    let forwardError: unknown
+    try { await unbudgetedAdb(bridge.deviceId, ['forward', '--remove', `tcp:${bridge.hostPort}`]) }
+    catch (error) { forwardError = error }
+    if (forceStopError || !bridge.childClosed || forwardError) {
+      const reason = forceStopError ?? (!bridge.childClosed ? 'instrumentation child did not close' : forwardError)
+      throw new Error(`BRIDGE_CLEANUP_UNCONFIRMED: ${reason instanceof Error ? reason.message : String(reason)}`)
+    }
+    if (active.get(bridge.deviceId) === bridge) active.delete(bridge.deviceId)
+  })()
+  stopping.set(bridge.deviceId, cleanup)
+  try { await cleanup } finally { stopping.delete(bridge.deviceId) }
+}
+
+async function launch(deviceId: string, apk: string): Promise<Bridge> {
+  await unbudgetedAdb(deviceId, ['shell', 'am', 'force-stop', packageName])
+  try {
+    await execAdb(['install', '-r', apk], deviceId)
+  } catch (error) {
+    if (!(error instanceof Error) || !error.message.includes('INSTALL_FAILED_UPDATE_INCOMPATIBLE')) throw error
+    await execAdb(['uninstall', packageName], deviceId)
+    await execAdb(['install', '-r', apk], deviceId)
+  }
+  const hostPort = Number(await execAdb(['forward', 'tcp:0', `tcp:${devicePort}`], deviceId))
+  if (!Number.isInteger(hostPort) || hostPort <= 0) throw new Error('Android UI tree bridge could not obtain a host port')
+  const child = spawn(getAdbCmd(), ['-s', deviceId, 'shell', 'am', 'instrument', '-w', component], { stdio: 'ignore' })
+  const bridge: Bridge = { deviceId, hostPort, child, closed: false, childClosed: false }
+  child.once('close', () => { bridge.childClosed = true })
+  child.once('error', () => { /* Startup detects the failed child before a tree read. */ })
+  active.set(deviceId, bridge)
+  try {
+    const deadline = Date.now() + Math.min(remainingBudget(3000), 3000)
+    while (Date.now() < deadline) {
+      if (bridge.childClosed || child.exitCode !== null || child.signalCode !== null) throw new Error('Android UI tree bridge exited during startup')
+      try {
+        if ((await request(bridge, 'PING', 250)).startsWith('OK\n')) {
+          return bridge
+        }
+      } catch { /* The instrumentation process may still be starting. */ }
+      await new Promise((resolve) => setTimeout(resolve, 100))
+    }
+    throw new Error('Android UI tree bridge did not become ready')
+  } catch (error) {
+    await stop(bridge)
+    throw error
+  }
+}
+
+async function ensure(deviceId: string, apk: string): Promise<Bridge> {
+  const pending = starting.get(deviceId)
+  if (pending) return pending
+  const ready = active.get(deviceId)
+  if (ready && !ready.closed && !ready.childClosed && ready.child.exitCode === null && ready.child.signalCode === null) return ready
+  if (ready) await stop(ready)
+  const promise = launch(deviceId, apk)
+  starting.set(deviceId, promise)
+  try { return await promise } finally { starting.delete(deviceId) }
+}
+
+/** Returns null only after the bridge has been stopped, so legacy acquisition is safe. */
+export async function readAndroidTreeFromBridge(deviceId: string): Promise<string | null> {
+  const apk = configuredApk()
+  if (!apk) return null
+  let bridge: Bridge | undefined
+  try {
+    let supported = bridgeSupport.get(deviceId)
+    if (supported === undefined) {
+      const sdkLevel = Number(await execAdb(['shell', 'getprop', 'ro.build.version.sdk'], deviceId))
+      supported = Number.isInteger(sdkLevel) && sdkLevel >= 34
+      if (supported) bridgeSupport.set(deviceId, true)
+    }
+    if (!supported) return null
+    bridge = await ensure(deviceId, apk)
+    const output = await request(bridge, 'TREE', remainingBudget(10000))
+    if (!output.startsWith('OK\n') || !output.includes('<hierarchy')) throw new Error('Android UI tree bridge returned invalid hierarchy output')
+    return output.slice(3)
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED')) throw error
+    if (bridge) await stop(bridge)
+    if (error instanceof Error && error.message === 'ACTION_TIMEOUT') throw error
+    return null
+  }
+}
+
+process.once('exit', () => {
+  for (const bridge of active.values()) {
+    spawnSync(getAdbCmd(), ['-s', bridge.deviceId, 'shell', 'am', 'force-stop', packageName], { timeout: 2000, stdio: 'ignore' })
+    spawnSync(getAdbCmd(), ['-s', bridge.deviceId, 'forward', '--remove', `tcp:${bridge.hostPort}`], { timeout: 2000, stdio: 'ignore' })
+  }
+})

package/src/observe/android.ts

@@ -9,6 +9,8 @@ import { computeScreenFingerprint } from "../utils/ui/index.js"
 import { parsePngSize } from "../utils/image.js"
 import { deriveSnapshotMetadata } from "./snapshot-metadata.js"
 import { remainingBudget } from '../utils/operation-budget.js'
+import { createObservationMeasurement } from './performance-metrics.js'
+import { androidTreeBridgeEnabled, readAndroidTreeFromBridge } from './android-tree-bridge.js'
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 
@@ -18,12 +20,20 @@ export class AndroidObserve {
   }
 
   async getUITree(deviceId?: string): Promise<GetUITreeResponse> {
-    const metadata = await getAndroidDeviceMetadata("", deviceId)
+    const measurement = createObservationMeasurement('android')
+    let metadata
+    try {
+      metadata = await measurement.timed('metadata_ms', () => getAndroidDeviceMetadata("", deviceId))
+    } catch (error) {
+      measurement.setOutcome('unavailable')
+      measurement.finish()
+      throw error
+    }
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     try {
       // Get screen resolution first
-      const resolution = await getScreenResolution(deviceId);
+      const resolution = await measurement.timed('resolution_ms', () => getScreenResolution(deviceId));
       if (resolution.width === 0 && resolution.height === 0) {
           throw new Error("Failed to get screen resolution. Is the device connected and authorized?");
       }
@@ -37,22 +47,34 @@ export class AndroidObserve {
         remainingBudget()
         attempts++;
         try {
-           // Stabilization delay
-           await delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))); // 300ms, 400ms, 500ms...
+           // The first read starts immediately so it remains fresh for in-place UI changes.
+           // Delay only a retry after a failed or invalid acquisition.
+           if (attempts > 1) {
+             await measurement.timed('observation_wait_ms', () => delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))));
+           }
            remainingBudget()
 
-           // Dump UI hierarchy
-           await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId);
-           
-           // Read the file
-           xmlContent = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId);
-           
-           // Check validity
-           if (xmlContent && xmlContent.trim().length > 0 && !xmlContent.includes("ERROR:")) {
-              break; // Success
+           let bridgeContent: string | null = null
+           if (androidTreeBridgeEnabled()) {
+             try {
+               bridgeContent = await measurement.physicalRead(async () => {
+                 const content = await readAndroidTreeFromBridge(deviceInfo.id)
+                 if (!content) throw new Error('Android UI tree bridge unavailable')
+                 return content
+               })
+             } catch (error) {
+               if (error instanceof Error && (error.message === 'ACTION_TIMEOUT' || error.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED'))) throw error
+             }
            }
+           xmlContent = bridgeContent ?? await measurement.physicalRead(async () => {
+             await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId)
+             const content = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId)
+             if (!content || !content.trim() || content.includes('ERROR:')) throw new Error('Empty or invalid UI dump')
+             return content
+           })
+           break
         } catch (e) {
-           if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
+           if (e instanceof Error && (e.message === 'ACTION_TIMEOUT' || e.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED'))) throw e
            console.error(`Attempt ${attempts} failed: ${e}`);
         }
         
@@ -65,7 +87,7 @@ export class AndroidObserve {
         ignoreAttributes: false,
         attributeNamePrefix: "@_"
       });
-      const result = parser.parse(xmlContent);
+      const result = await measurement.timed('parse_ms', async () => parser.parse(xmlContent));
       
       const elements: UIElement[] = [];
       
@@ -85,17 +107,22 @@ export class AndroidObserve {
         elements
       }, 'ui_tree')
 
-      return {
+      measurement.setOutcome('observed')
+      const response = measurement.bindObservation({
         device: deviceInfo,
         screen: "",
         resolution,
         elements,
         ...snapshotMetadata
-      };
+      })
+      measurement.finish()
+      return response
     } catch (e) {
       const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
       console.error(errorMessage);
       const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, null, 'ui_tree')
+      measurement.setOutcome('unavailable')
+      measurement.finish()
       return {
           device: deviceInfo,
           screen: "",