mobile-debug-mcp 0.32.0 → 0.32.2

package/test/fixtures/latency-journey-app/src/MainActivity.java

@@ -1,10 +1,21 @@
 package dev.mobiledebugmcp.latencyfixture;
 
 import android.app.Activity;
+import android.content.Intent;
+import android.graphics.Canvas;
+import android.graphics.Color;
+import android.graphics.Paint;
 import android.os.Bundle;
+import android.view.View;
+import android.view.accessibility.AccessibilityNodeInfo;
 import android.widget.Button;
 import android.widget.LinearLayout;
 import android.widget.TextView;
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.net.URLEncoder;
 
 public final class MainActivity extends Activity {
     private static final class Selectors {
@@ -20,7 +31,83 @@ public final class MainActivity extends Activity {
     }
     private boolean active = false;
     private LinearLayout layout;
-    @Override public void onCreate(Bundle state) { super.onCreate(state); home(); }
+    @Override public void onCreate(Bundle state) {
+        super.onCreate(state);
+        String networkBaseUrl = getIntent().getStringExtra("networkBaseUrl");
+        String networkRunId = getIntent().getStringExtra("networkRunId");
+        if (getIntent().getBooleanExtra("silentTimer", false)) silentTimerScreen();
+        else if (networkBaseUrl != null && networkRunId != null) networkScreen(networkBaseUrl, networkRunId);
+        else home();
+    }
+    private void silentTimerScreen() {
+        layout = new LinearLayout(this);
+        layout.setPadding(32, 100, 32, 32);
+        setContentView(layout);
+        SilentTimerView timer = new SilentTimerView();
+        layout.addView(timer, new LinearLayout.LayoutParams(-1, 200));
+        timer.postDelayed(() -> timer.setValue("0:01"), 2000);
+    }
+    private final class SilentTimerView extends View {
+        private final Paint paint = new Paint(Paint.ANTI_ALIAS_FLAG);
+        private String value = "0:00";
+        SilentTimerView() {
+            super(MainActivity.this);
+            setImportantForAccessibility(IMPORTANT_FOR_ACCESSIBILITY_YES);
+            paint.setColor(Color.BLACK);
+            paint.setTextSize(72);
+        }
+        // Deliberately redraw without an accessibility event to expose stale node caches.
+        void setValue(String next) { value = next; invalidate(); }
+        @Override protected void onDraw(Canvas canvas) { canvas.drawText(value, 20, 110, paint); }
+        @Override public void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) {
+            super.onInitializeAccessibilityNodeInfo(info);
+            info.setContentDescription("silent timer " + value);
+        }
+    }
+    private void networkScreen(String baseUrl, String runId) {
+        layout = new LinearLayout(this);
+        layout.setOrientation(LinearLayout.VERTICAL);
+        layout.setPadding(32, 100, 32, 32);
+        setContentView(layout);
+        TextView loading = new TextView(this);
+        loading.setText("Loading");
+        loading.setContentDescription("loading");
+        layout.addView(loading);
+        TextView ready = new TextView(this);
+        ready.setText("Ready");
+        ready.setContentDescription("ready");
+        ready.setVisibility(android.view.View.GONE);
+        layout.addView(ready);
+        TextView value = new TextView(this);
+        value.setContentDescription("value");
+        value.setVisibility(android.view.View.GONE);
+        layout.addView(value);
+        new Thread(() -> {
+            HttpURLConnection connection = null;
+            try {
+                String encodedRunId = URLEncoder.encode(runId, "UTF-8");
+                connection = (HttpURLConnection) new URL(baseUrl + "/data?run_id=" + encodedRunId).openConnection();
+                connection.setConnectTimeout(10000);
+                connection.setReadTimeout(30000);
+                String response;
+                try (BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
+                    response = reader.readLine();
+                }
+                String[] fields = response == null ? new String[0] : response.split("\\|", 2);
+                if (fields.length == 2 && runId.equals(fields[0])) {
+                    runOnUiThread(() -> {
+                        ready.setVisibility(android.view.View.VISIBLE);
+                        value.setText(fields[1]);
+                        value.setVisibility(android.view.View.VISIBLE);
+                    });
+                }
+            } catch (Exception ignored) {
+                // A failed local fixture request leaves the screen in its observable loading state.
+            } finally {
+                if (connection != null) connection.disconnect();
+            }
+        }).start();
+    }
     private void screen(String id) {
         layout = new LinearLayout(this);
         layout.setOrientation(LinearLayout.VERTICAL);

package/test/fixtures/ui-tree-bridge/AndroidManifest.xml

@@ -0,0 +1,6 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="dev.mobiledebugmcp.treebridge">
+  <uses-sdk android:minSdkVersion="26" android:targetSdkVersion="36" />
+  <uses-permission android:name="android.permission.INTERNET" />
+  <application android:label="UI Tree Bridge" />
+  <instrumentation android:name=".TreeInstrumentation" android:targetPackage="dev.mobiledebugmcp.treebridge" android:exported="true" />
+</manifest>

package/test/fixtures/ui-tree-bridge/build.ts

@@ -0,0 +1,34 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export function buildBridge() {
+  const root = path.dirname(fileURLToPath(import.meta.url))
+  const out = path.join(root, 'build')
+  const sdk = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME ||
+    (process.platform === 'darwin' && process.env.HOME ? path.join(process.env.HOME, 'Library/Android/sdk') : '')
+  if (!sdk) throw new Error('Android SDK not found: set ANDROID_SDK_ROOT or ANDROID_HOME')
+  const buildTools = path.join(sdk, 'build-tools', '36.0.0')
+  const androidJar = path.join(sdk, 'platforms', 'android-36', 'android.jar')
+  if (!existsSync(androidJar) || !existsSync(buildTools)) {
+    throw new Error(`Android SDK 36 platform and build-tools 36.0.0 are required under ${sdk}`)
+  }
+  const java = process.env.JAVA_HOME
+  const tool = (name: string) => java ? path.join(java, 'bin', name) : name
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: out, stdio: 'pipe' })
+  mkdirSync(path.join(out, 'classes'), { recursive: true })
+  run(tool('javac'), ['--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(root, 'src/TreeInstrumentation.java')])
+  run(tool('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
+  run(path.join(buildTools, 'd8'), ['--lib', androidJar, '--output', out, 'classes.jar'])
+  run(path.join(buildTools, 'aapt2'), ['link', '-I', androidJar, '--manifest', path.join(root, 'AndroidManifest.xml'), '-o', 'unsigned.apk'])
+  run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
+  run(path.join(buildTools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
+  try { run(tool('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=UI Tree Bridge', '-keyalg', 'RSA', '-validity', '3650']) } catch { /* Existing local fixture key. */ }
+  run(path.join(buildTools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', 'bridge.apk', 'aligned.apk'])
+  return path.join(out, 'bridge.apk')
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  console.log(buildBridge())
+}

package/test/fixtures/ui-tree-bridge/src/TreeInstrumentation.java

@@ -0,0 +1,126 @@
+package dev.mobiledebugmcp.treebridge;
+
+import android.app.Instrumentation;
+import android.app.UiAutomation;
+import android.graphics.Rect;
+import android.os.Bundle;
+import android.os.Build;
+import android.util.Xml;
+import android.util.Log;
+import android.view.accessibility.AccessibilityNodeInfo;
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.io.OutputStreamWriter;
+import java.io.StringWriter;
+import java.net.InetAddress;
+import java.net.ServerSocket;
+import java.net.Socket;
+import org.xmlpull.v1.XmlSerializer;
+
+/** Benchmark-only bridge: one live accessibility acquisition per TREE request. */
+public final class TreeInstrumentation extends Instrumentation {
+  private static final int PORT = 39019;
+
+  @Override public void onCreate(Bundle arguments) {
+    super.onCreate(arguments);
+    start();
+  }
+
+  @Override public void onStart() {
+    try (ServerSocket server = new ServerSocket(PORT, 1, InetAddress.getByName("127.0.0.1"))) {
+      UiAutomation automation = getUiAutomation(UiAutomation.FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES);
+      while (true) {
+        try (Socket socket = server.accept()) {
+          socket.setSoTimeout(10000);
+          BufferedReader input = new BufferedReader(new InputStreamReader(socket.getInputStream(), "UTF-8"));
+          OutputStreamWriter output = new OutputStreamWriter(socket.getOutputStream(), "UTF-8");
+          String command = input.readLine();
+          if ("STOP".equals(command)) {
+            output.write("OK\n");
+            output.flush();
+            break;
+          }
+          if ("PING".equals(command)) {
+            output.write("OK\n");
+            output.flush();
+            continue;
+          }
+          if (!"TREE".equals(command)) {
+            output.write("ERROR invalid_command\n");
+          } else {
+            if (Build.VERSION.SDK_INT < 34) {
+              output.write("ERROR cache_clear_unavailable\n");
+            } else if (!automation.clearCache()) {
+              output.write("ERROR cache_clear_failed\n");
+            } else {
+              AccessibilityNodeInfo root = automation.getRootInActiveWindow();
+              if (root == null) {
+                output.write("ERROR null_root\n");
+              } else {
+                output.write("OK\n");
+                output.write(serialize(root));
+                root.recycle();
+              }
+            }
+          }
+          output.flush();
+        } catch (Exception error) {
+          // A failed client request cannot make a later acquisition reuse its tree.
+          Log.e("TreeBridge", "request failed", error);
+        }
+      }
+    } catch (Exception error) {
+      // The host-side probe detects failure to start or connect.
+      Log.e("TreeBridge", "bridge failed", error);
+    }
+    finish(0, new Bundle());
+  }
+
+  private static String serialize(AccessibilityNodeInfo root) throws Exception {
+    StringWriter writer = new StringWriter();
+    XmlSerializer xml = Xml.newSerializer();
+    xml.setOutput(writer);
+    xml.startDocument("UTF-8", true);
+    xml.startTag("", "hierarchy");
+    writeNode(xml, root, 0);
+    xml.endTag("", "hierarchy");
+    xml.endDocument();
+    return writer.toString();
+  }
+
+  private static void writeNode(XmlSerializer xml, AccessibilityNodeInfo node, int index) throws Exception {
+    Rect bounds = new Rect();
+    node.getBoundsInScreen(bounds);
+    xml.startTag("", "node");
+    xml.attribute("", "index", Integer.toString(index));
+    xml.attribute("", "class", value(node.getClassName()));
+    xml.attribute("", "package", value(node.getPackageName()));
+    xml.attribute("", "text", value(node.getText()));
+    xml.attribute("", "content-desc", value(node.getContentDescription()));
+    xml.attribute("", "resource-id", value(node.getViewIdResourceName()));
+    xml.attribute("", "checkable", Boolean.toString(node.isCheckable()));
+    xml.attribute("", "checked", Boolean.toString(node.isChecked()));
+    xml.attribute("", "clickable", Boolean.toString(node.isClickable()));
+    xml.attribute("", "enabled", Boolean.toString(node.isEnabled()));
+    xml.attribute("", "focusable", Boolean.toString(node.isFocusable()));
+    xml.attribute("", "focused", Boolean.toString(node.isFocused()));
+    xml.attribute("", "scrollable", Boolean.toString(node.isScrollable()));
+    xml.attribute("", "long-clickable", Boolean.toString(node.isLongClickable()));
+    xml.attribute("", "password", Boolean.toString(node.isPassword()));
+    xml.attribute("", "selected", Boolean.toString(node.isSelected()));
+    xml.attribute("", "visible-to-user", Boolean.toString(node.isVisibleToUser()));
+    xml.attribute("", "bounds", bounds.toShortString());
+    for (int childIndex = 0; childIndex < node.getChildCount(); childIndex++) {
+      AccessibilityNodeInfo child = node.getChild(childIndex);
+      if (child != null && child.isVisibleToUser()) {
+        writeNode(xml, child, childIndex);
+      }
+      if (child != null) child.recycle();
+    }
+    xml.endTag("", "node");
+  }
+
+  private static String value(CharSequence input) {
+    return input == null ? "" : input.toString();
+  }
+}

package/test/unit/observe/android_tree_acquisition.test.ts

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict'
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { AndroidObserve } from '../../../src/observe/android.js'
+import { resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-fake-adb-'))
+  const adbPath = path.join(directory, 'adb')
+  const previousAdb = process.env.ADB_PATH
+  const previousMetrics = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS
+  const previousFailure = process.env.MCP_FAKE_ADB_FAIL
+  const previousWrite = process.stderr.write
+  const lines: string[] = []
+  writeFileSync(adbPath, `#!/usr/bin/env node
+const args = process.argv.slice(2).join(' ')
+if (args.includes('ro.build.version.release')) console.log('16')
+else if (args.includes('ro.product.model')) console.log('Fake Android')
+else if (args.includes('ro.kernel.qemu')) console.log('1')
+else if (args.includes('wm size')) console.log('Physical size: 100x200')
+else if (args.includes('uiautomator dump')) { if (process.env.MCP_FAKE_ADB_FAIL === '1') process.exit(1); console.log('UI hierarchy dumped') }
+else if (args.includes('cat /sdcard/ui.xml')) console.log('<hierarchy><node class="android.widget.TextView" text="Ready" bounds="[0,0][50,50]" /></hierarchy>')
+else process.exit(1)
+`)
+  chmodSync(adbPath, 0o755)
+  process.env.ADB_PATH = adbPath
+  process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS = '1'
+  ;(process.stderr as any).write = (chunk: string) => { lines.push(chunk); return true }
+  resetSnapshotMetadataForTests()
+  try {
+    const observe = new AndroidObserve()
+    const first = await observe.getUITree('fake-a')
+    const second = await observe.getUITree('fake-b')
+    assert.equal(first.error, undefined)
+    assert.equal(second.error, undefined)
+    assert.equal(first.snapshot_revision, 1)
+    assert.notEqual(first.snapshot_revision, second.snapshot_revision)
+    assert.equal(second.snapshot_delta, null, 'different devices keep independent delta history')
+    assert.equal(first.elements[0].text, 'Ready')
+    process.env.MCP_FAKE_ADB_FAIL = '1'
+    const failed = await runWithBudget(1000, () => observe.getUITree('fake-a'))
+    assert.ok(failed.error)
+    delete process.env.MCP_FAKE_ADB_FAIL
+    const recovered = await observe.getUITree('fake-a')
+    assert.equal(recovered.error, undefined, 'the next request takes a fresh physical read')
+    const events = lines.filter((line) => line.startsWith('{')).map((line) => JSON.parse(line))
+    const started = events.filter((event) => event.type === 'physical_read_started')
+    const completed = events.filter((event) => event.type === 'physical_read_completed')
+    assert.equal(started.length, completed.length)
+    assert.ok(started.length >= 4)
+    assert.equal(events.filter((event) => event.type === 'physical_read_completed' && event.success).length, 3)
+    assert.ok(events.some((event) => event.type === 'physical_read_completed' && !event.success))
+    const successfulAcquisitions = new Set(events.filter((event) => event.type === 'acquisition_completed' && event.outcome === 'observed').map((event) => event.acquisition_id))
+    assert.equal(events.filter((event) => event.stage === 'observation_wait_ms' && successfulAcquisitions.has(event.acquisition_id)).length, 0, 'successful first attempts have no pre-read wait')
+  } finally {
+    ;(process.stderr as any).write = previousWrite
+    if (previousAdb === undefined) delete process.env.ADB_PATH
+    else process.env.ADB_PATH = previousAdb
+    if (previousMetrics === undefined) delete process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS
+    else process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS = previousMetrics
+    if (previousFailure === undefined) delete process.env.MCP_FAKE_ADB_FAIL
+    else process.env.MCP_FAKE_ADB_FAIL = previousFailure
+    rmSync(directory, { recursive: true, force: true })
+    resetSnapshotMetadataForTests()
+  }
+}
+
+run().catch((error) => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/android_tree_bridge_cleanup.test.ts

@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict'
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer } from 'node:net'
+import type { Socket } from 'node:net'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { readAndroidTreeFromBridge } from '../../../src/observe/android-tree-bridge.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-tree-bridge-'))
+  const adbPath = path.join(directory, 'adb')
+  const apkPath = path.join(directory, 'bridge.apk')
+  const launchesPath = path.join(directory, 'launches')
+  const getpropsPath = path.join(directory, 'getprops')
+  const previous = new Map(['ADB_PATH', 'MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK', 'MCP_FAKE_BRIDGE_PORT', 'MCP_FAKE_BRIDGE_LAUNCHES', 'MCP_FAKE_BRIDGE_GETPROPS', 'MCP_FAKE_FORCE_STOP_FAIL', 'MCP_FAKE_SDK'].map((key) => [key, process.env[key]]))
+  let invalidTree = false
+  const sockets = new Set<Socket>()
+  const server = createServer((socket) => {
+    sockets.add(socket)
+    socket.once('close', () => sockets.delete(socket))
+    socket.once('data', (chunk) => {
+      const command = chunk.toString().trim()
+      socket.end(command === 'TREE'
+        ? invalidTree ? 'ERROR null_root\n' : 'OK\n<hierarchy><node class="android.view.View" /></hierarchy>'
+        : 'OK\n')
+    })
+  })
+  writeFileSync(apkPath, '')
+  writeFileSync(launchesPath, '')
+  writeFileSync(getpropsPath, '')
+  writeFileSync(adbPath, `#!/usr/bin/env node
+const fs = require('node:fs')
+const args = process.argv.slice(2).join(' ')
+if (args.includes('am instrument')) {
+  fs.appendFileSync(process.env.MCP_FAKE_BRIDGE_LAUNCHES, 'launch\\n')
+  setInterval(() => {}, 1000)
+} else if (args.includes('am force-stop') && process.env.MCP_FAKE_FORCE_STOP_FAIL === '1') {
+  process.exit(1)
+} else if (args.includes('forward tcp:0')) {
+  console.log(process.env.MCP_FAKE_BRIDGE_PORT)
+} else if (args.includes('getprop ro.build.version.sdk')) {
+  fs.appendFileSync(process.env.MCP_FAKE_BRIDGE_GETPROPS, 'getprop\\n')
+  console.log(process.env.MCP_FAKE_SDK || '36')
+}
+`)
+  chmodSync(adbPath, 0o755)
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  const address = server.address()
+  if (!address || typeof address === 'string') throw new Error('No test port')
+  process.env.ADB_PATH = adbPath
+  process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK = apkPath
+  process.env.MCP_FAKE_BRIDGE_PORT = String(address.port)
+  process.env.MCP_FAKE_BRIDGE_LAUNCHES = launchesPath
+  process.env.MCP_FAKE_BRIDGE_GETPROPS = getpropsPath
+  try {
+    assert.match(await readAndroidTreeFromBridge('test-device') ?? '', /<hierarchy>/)
+    invalidTree = true
+    process.env.MCP_FAKE_FORCE_STOP_FAIL = '1'
+    await assert.rejects(() => readAndroidTreeFromBridge('test-device'), /BRIDGE_CLEANUP_UNCONFIRMED/)
+    await assert.rejects(() => readAndroidTreeFromBridge('test-device'), /BRIDGE_CLEANUP_UNCONFIRMED/)
+    assert.equal(readFileSync(launchesPath, 'utf8').trim().split('\n').length, 1, 'failed cleanup must block a second launch')
+    invalidTree = false
+    delete process.env.MCP_FAKE_FORCE_STOP_FAIL
+    assert.match(await readAndroidTreeFromBridge('test-device') ?? '', /<hierarchy>/, 'successful cleanup allows relaunch')
+    for (let attempt = 0; attempt < 20 && readFileSync(launchesPath, 'utf8').trim().split('\n').length < 2; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 50))
+    }
+    assert.equal(readFileSync(launchesPath, 'utf8').trim().split('\n').length, 2)
+    invalidTree = true
+    assert.equal(await readAndroidTreeFromBridge('test-device'), null, 'clean shutdown permits legacy fallback')
+    process.env.MCP_FAKE_SDK = '33'
+    assert.equal(await readAndroidTreeFromBridge('old-device'), null, 'older Android versions use the legacy reader')
+    assert.equal(await readAndroidTreeFromBridge('old-device'), null)
+    assert.equal(readFileSync(getpropsPath, 'utf8').trim().split('\n').length, 3, 'unsupported devices recheck SDK support')
+    process.env.MCP_FAKE_SDK = '36'
+    invalidTree = false
+    assert.match(await readAndroidTreeFromBridge('old-device') ?? '', /<hierarchy>/, 'a newly supported device can start the bridge')
+    for (let attempt = 0; attempt < 20 && readFileSync(launchesPath, 'utf8').trim().split('\n').length < 3; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 50))
+    }
+    assert.equal(readFileSync(launchesPath, 'utf8').trim().split('\n').length, 3)
+    invalidTree = true
+    assert.equal(await readAndroidTreeFromBridge('old-device'), null, 'the new bridge shuts down before fallback')
+  } finally {
+    for (const [key, value] of previous) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    for (const socket of sockets) socket.destroy()
+    await new Promise<void>((resolve) => server.close(() => resolve()))
+    rmSync(directory, { recursive: true, force: true })
+  }
+}
+
+run().catch((error) => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/ios_tree_acquisition.test.ts

@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict'
+import { chmodSync, existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { iOSObserve } from '../../../src/observe/ios.js'
+import { resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-fake-idb-'))
+  const idbPath = path.join(directory, 'idb')
+  const xcrunPath = path.join(directory, 'xcrun')
+  const previousIdb = process.env.IDB_PATH
+  const previousXcrun = process.env.XCRUN_PATH
+  const previousMetrics = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS
+  const previousSlow = process.env.MCP_FAKE_IDB_SLOW
+  const previousMarker = process.env.MCP_FAKE_IDB_CLOSE_MARKER
+  const previousWrite = process.stderr.write
+  const lines: string[] = []
+  writeFileSync(idbPath, `#!/usr/bin/env node
+const args = process.argv.slice(2).join(' ')
+if (args.includes('list-targets')) console.log('[]')
+else if (args.includes('ui describe-all')) {
+  if (process.env.MCP_FAKE_IDB_SLOW === '1') {
+    process.on('SIGTERM', () => setTimeout(() => { require('fs').writeFileSync(process.env.MCP_FAKE_IDB_CLOSE_MARKER, 'closed'); process.exit(0) }, 50))
+    setInterval(() => {}, 1000)
+  } else console.log(JSON.stringify({ AXElementType: 'Button', AXLabel: 'Ready', AXFrame: { x: 0, y: 0, width: 50, height: 50 } }))
+}
+else process.exit(1)
+`)
+  writeFileSync(xcrunPath, `#!/usr/bin/env node
+console.log(JSON.stringify({ devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-18-0': [{ udid: 'fake-a', name: 'Fake iPhone' }, { udid: 'fake-b', name: 'Fake iPhone' }] } }))
+`)
+  chmodSync(idbPath, 0o755)
+  chmodSync(xcrunPath, 0o755)
+  process.env.IDB_PATH = idbPath
+  process.env.XCRUN_PATH = xcrunPath
+  process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS = '1'
+  ;(process.stderr as any).write = (chunk: string) => { lines.push(chunk); return true }
+  resetSnapshotMetadataForTests()
+  try {
+    const observe = new iOSObserve()
+    const first = await observe.getUITree('fake-a')
+    const second = await observe.getUITree('fake-b')
+    assert.equal(first.error, undefined)
+    assert.equal(second.error, undefined)
+    assert.equal(first.elements[0].text, 'Ready')
+    assert.equal(second.snapshot_delta, null, 'different simulators keep independent delta history')
+    const events = lines.map((line) => JSON.parse(line))
+    assert.equal(events.filter((event) => event.type === 'physical_read_started').length, 2)
+    assert.equal(events.filter((event) => event.type === 'physical_read_completed' && event.success).length, 2)
+    const marker = path.join(directory, 'idb-closed')
+    process.env.MCP_FAKE_IDB_SLOW = '1'
+    process.env.MCP_FAKE_IDB_CLOSE_MARKER = marker
+    await assert.rejects(() => runWithBudget(1200, () => observe.getUITree('fake-a')), /ACTION_TIMEOUT/)
+    assert.equal(existsSync(marker), true, 'budget expiry waits for idb child close')
+    delete process.env.MCP_FAKE_IDB_SLOW
+    const recovered = await observe.getUITree('fake-a')
+    assert.equal(recovered.error, undefined, 'a cancelled iOS observation is not reused')
+  } finally {
+    ;(process.stderr as any).write = previousWrite
+    if (previousIdb === undefined) delete process.env.IDB_PATH
+    else process.env.IDB_PATH = previousIdb
+    if (previousXcrun === undefined) delete process.env.XCRUN_PATH
+    else process.env.XCRUN_PATH = previousXcrun
+    if (previousMetrics === undefined) delete process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS
+    else process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS = previousMetrics
+    if (previousSlow === undefined) delete process.env.MCP_FAKE_IDB_SLOW
+    else process.env.MCP_FAKE_IDB_SLOW = previousSlow
+    if (previousMarker === undefined) delete process.env.MCP_FAKE_IDB_CLOSE_MARKER
+    else process.env.MCP_FAKE_IDB_CLOSE_MARKER = previousMarker
+    rmSync(directory, { recursive: true, force: true })
+    resetSnapshotMetadataForTests()
+  }
+}
+
+run().catch((error) => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/performance_metrics.test.ts

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict'
+import { createObservationMeasurement, recordObservationConsumer, withObservationContext } from '../../../src/observe/performance-metrics.js'
+
+async function run() {
+  const previousFlag = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS
+  const previousWrite = process.stderr.write
+  const lines: string[] = []
+  process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS = '1'
+  ;(process.stderr as any).write = (chunk: string) => { lines.push(chunk); return true }
+  try {
+    const tree = { elements: [{ text: 'private UI value' }] }
+    await withObservationContext({ stepId: 'tap-1', purpose: 'target' }, async () => {
+      const measurement = createObservationMeasurement('android')
+      await measurement.physicalRead(async () => '<hierarchy/>')
+      measurement.bindObservation(tree)
+      measurement.setOutcome('observed')
+      measurement.finish()
+      recordObservationConsumer(tree, 'verification', 'tap-1')
+    })
+    const events = lines.map((line) => JSON.parse(line))
+    const starts = events.filter((event) => event.type === 'physical_read_started')
+    const completed = events.filter((event) => event.type === 'physical_read_completed')
+    const acquisitions = events.filter((event) => event.type === 'acquisition_completed')
+    const consumers = events.filter((event) => event.type === 'observation_consumer')
+    assert.equal(starts.length, 1)
+    assert.equal(completed.length, 1)
+    assert.equal(acquisitions.length, 1)
+    assert.equal(consumers.length, 2)
+    assert.ok(events.every((event) => event.acquisition_id === starts[0].acquisition_id))
+    assert.equal(consumers[1].consumer_purpose, 'verification')
+    assert.equal(consumers[1].reused_observations, 1)
+    assert.equal(lines.join('').includes('private UI value'), false)
+  } finally {
+    ;(process.stderr as any).write = previousWrite
+    if (previousFlag === undefined) delete process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS
+    else process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS = previousFlag
+  }
+}
+
+run().catch((error) => { console.error(error); process.exitCode = 1 })

package/test/unit/server/operation_budget.test.ts

@@ -1,10 +1,23 @@
 import assert from 'node:assert/strict'
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
 import { runWithBudget, remainingBudget, markDispatchStarted } from '../../../src/utils/operation-budget.js'
 import { execCmd } from '../../../src/utils/exec.js'
 import { ToolsInteract } from '../../../src/interact/index.js'
 import { ToolsObserve } from '../../../src/observe/index.js'
 
 async function run() {
+  const markerDir = mkdtempSync(path.join(tmpdir(), 'mcp-exec-close-'))
+  try {
+    const marker = path.join(markerDir, 'closed')
+    const command = `process.on('SIGTERM', () => setTimeout(() => { require('fs').writeFileSync(${JSON.stringify(marker)}, 'closed'); process.exit(0) }, 50)); setInterval(() => {}, 1000)`
+    const response = await execCmd(process.execPath, ['-e', command], { timeout: 250 })
+    assert.equal(response.stderr, 'ACTION_TIMEOUT')
+    assert.equal(existsSync(marker), true, 'timeout must await child close before returning')
+  } finally {
+    rmSync(markerDir, { recursive: true, force: true })
+  }
   await runWithBudget(100, async budget => {
     assert.equal(budget.dispatchStarted, false)
     markDispatchStarted()

package/test/unit/server/run_journey.test.ts

@@ -78,6 +78,36 @@ async function run() {
     assert.strictEqual(failedAssertion.success, false)
     assert.deepStrictEqual(failedAssertion.steps[0].result.verification, { mode: 'light', status: 'observed' })
     assert.strictEqual(postActionReads, 0)
+
+    ;(ToolsInteract as any).waitForUIHandler = originalWait
+    ;(ToolsInteract as any).expectElementVisibleHandler = originalExpectVisible
+    let dispatchedAt = 0
+    const readTimes: number[] = []
+    ;(ToolsObserve as any).getUITreeHandler = async () => {
+      readTimes.push(performance.now())
+      const target = readTimes.length === 1
+      return {
+        device: { platform: 'android', id: 'fixture' },
+        captured_at_ms: Date.now(),
+        elements: [{ contentDescription: target ? 'target' : 'result', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: true }]
+      }
+    }
+    ;(ToolsInteract as any).tapElementHandler = async () => {
+      dispatchedAt = performance.now()
+      return { success: true, action_id: 'tap', action_type: 'tap_element' }
+    }
+    const freshResponse: any = await handleToolCall('run_journey', {
+      platform: 'android', responseMode: 'compact', defaults: { verificationMode: 'light' },
+      steps: [
+        { id: 'tap-target', type: 'tap', selector: { accessibility_id: 'target' } },
+        { id: 'assert-result', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'result' } } }
+      ]
+    })
+    const fresh = JSON.parse(freshResponse.content[0].text)
+    assert.strictEqual(fresh.success, true)
+    assert.strictEqual(readTimes.length, 3, 'target selection and two stability samples require separate reads')
+    assert.ok(readTimes[0] < dispatchedAt)
+    assert.ok(readTimes[1] >= dispatchedAt && readTimes[2] >= dispatchedAt, 'assertion reads must follow dispatch')
   } finally {
     _resetDeviceListersForTests()
     ;(ToolsInteract as any).waitForUIHandler = originalWait