@deeeed/metamask-harness 0.33.3 → 0.34.1

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 0.34.1 - 2026-08-09
+
+### Fixed
+
+- Launch Mobile Metro through the product's canonical watcher while preserving slot, build, Sentry, and Segment environment settings, applying cache clears only to the selected Metro instance, and removing the config override that could corrupt cold bundles.
+- Pin native Mobile builds to the exact supported Main or Flask app identity and Android device, rejecting ambiguous physical-device names instead of building or launching on the wrong target.
+- Clean up timed-out Metro process groups safely and require the cold-disk-cache Perps freshness gate to report the expected lifecycle.
+- Allow performance recipes to enforce a first-fresh socket-to-subscriber latency budget for a stream and subscriber throttle, optionally scoped to a lifecycle while always reporting the observed lifecycle.
+- Allow Mobile wallet unlock actions to use their declared target and unlock timeouts without the live-adapter process ending first.
+- Remove Android's 180-second `screenrecord` cap so `--record-video=full-run` covers long recipe runs.
+- Retry empty Metro target lists, derive the Android model pin from `ADB_SERIAL`, and use pin-aware wallet status while Hermes re-registers between recipe actions.
+- Keep compound Mobile actions under one debugger lease so nested bridge calls cannot race another recipe action.
+- Let Android `scroll_into_view` fall back to a scrollable ancestor when the target itself is not a scroll container.
+- Leave Metro's worker count at its native default unless `METRO_MAX_WORKERS` is explicitly configured.
+- Bound each Mobile wallet-status probe by its polling deadline, raise the default unlock verification window to 30 seconds, and give the Android cold-no-cache recipe an explicit cold-start allowance, preventing a successful physical-device unlock from being reported as a timeout.
+
+## 0.34.0 - 2026-08-07
+
+### Fixed
+
+- Record Mobile Android recipe runs with the selected device's native `screenrecord` capability when `--record-video=full-run` is requested.
+- Record iOS Simulator recipe runs with `simctl recordVideo`, avoiding hidden/offscreen Simulator-window captures that produce empty videos.
+- Keep pinned Android commands on their requested device while its Hermes target re-registers with Metro after a runtime rotation.
+- Make Mobile account selection wait for the selected account state without disconnecting or reinitializing the Perps controller, preventing duplicate account-change reconnections and transient Perps errors.
+- Resolve shutdown iOS simulators to their canonical bridge-visible name while preserving the requested UDID for native launch.
+- Keep lifecycle performance recipes free from HUD bridge timeouts while the app is backgrounded or its runtime target is rotating.
+- Make Android coordinate swipes and scroll-into-view use the selected device consistently, including the native fallback path.
+
+### Added
+
+- Add manifest-declared Mobile `app.lifecycle` and `app.network` actions with device targeting, runtime readiness, and Android offline/online recovery.
+- Add reusable Perps Homepage performance capture with lifecycle, delivery-source, visible-content, and socket-pipeline validation.
+- Bundle the device-proven Android/iOS Perps Homepage short-resume, reconnect, cold-cache, cold-no-cache, and Android network-recovery recipes with explicit cleanup and full-run evidence commands.
+- Add wallet setup/account-selection readiness checks and source-freshness recovery evidence for Mobile recipe runs.
+
 ## 0.33.3 - 2026-08-05
 
 ### Changed

package/adapters/manifest.json

@@ -42,14 +42,6 @@
       "inputs": "--target --port --log --pid-file [--workers] [--clear]",
       "outputs": "Metro PID/launch metadata and redirected log; exit 0/1/2"
     },
-    {
-      "id": "mobile/metro-config",
-      "entry": "adapters/mobile/metro-config.cjs",
-      "kind": "module",
-      "purpose": "Preserve the product Metro config while excluding harness-owned checkout temp artifacts.",
-      "inputs": "base Metro config; env MM_HARNESS_METRO_PROJECT_ROOT, MM_HARNESS_METRO_BASE_CONFIG",
-      "outputs": "merged Metro config with resolver.blockList for <projectRoot>/temp"
-    },
     {
       "id": "mobile/stop-metro",
       "entry": "adapters/mobile/stop-metro.sh",

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -305,6 +305,7 @@ const COMMANDS = {
     let testId;
     let offset = 300;
     let animated = false;
+    let intoView = false;
     for (let i = 0; i < args.length; i++) {
       if (args[i] === '--test-id' && i + 1 < args.length) {
         testId = args[++i];
@@ -312,14 +313,20 @@ const COMMANDS = {
         offset = Number(args[++i]);
       } else if (args[i] === '--animated') {
         animated = true;
+      } else if (args[i] === '--into-view') {
+        intoView = true;
       } else if (args[i] === '--no-animated') {
         animated = false;
       }
     }
-    const optsJson = JSON.stringify({ testId, offset, animated });
+    const optsJson = JSON.stringify({ testId, offset, animated, intoView });
     // Try __AGENTIC__ bridge first, fall back to inline fiber walking
     const expr = `(function() {
-      if (globalThis.__AGENTIC__?.scrollView) return globalThis.__AGENTIC__.scrollView(${optsJson});
+      // The app helper implements generic scrolling by searching inside the
+      // selector fiber. For into-view requests the scroll container is commonly
+      // an ancestor (for example, a Wallet Home section row), so use the
+      // ancestor-aware bridge fallback below instead.
+      if (!${intoView} && globalThis.__AGENTIC__?.scrollView) return globalThis.__AGENTIC__.scrollView(${optsJson});
       var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
       if (!hook) return { ok: false, error: 'No React DevTools hook' };
       var renderers = hook.renderers;
@@ -340,6 +347,19 @@ const COMMANDS = {
         }
         return false;
       }
+      function tryScrollNear(anchor) {
+        if (!opts.intoView && tryScroll(anchor, false)) return true;
+        var current = anchor ? anchor.return : null;
+        while (current) {
+          var sn = current.stateNode;
+          if (sn) {
+            if (typeof sn.scrollTo === 'function') { sn.scrollTo({ y: opts.offset, animated: opts.animated }); return true; }
+            if (typeof sn.scrollToOffset === 'function') { sn.scrollToOffset({ offset: opts.offset, animated: opts.animated }); return true; }
+          }
+          current = current.return;
+        }
+        return opts.intoView ? tryScroll(anchor, false) : false;
+      }
       function findTestId(fiber) {
         if (!fiber) return null;
         var props = fiber.memoizedProps;
@@ -354,7 +374,7 @@ const COMMANDS = {
           if (scrolled) return;
           if (opts.testId) {
             var anchor = findTestId(r.current);
-            if (anchor) scrolled = tryScroll(anchor, false);
+            if (anchor) scrolled = tryScrollNear(anchor);
           } else {
             scrolled = tryScroll(r.current);
           }
@@ -665,6 +685,11 @@ const BRIDGE_LOCK_FILE = path.join(
   process.env.RECIPE_RUNTIME_DIR || path.join('temp', 'recipe', 'runtime'),
   'cdp-bridge.lock',
 );
+const BRIDGE_LOCK_OWNER_PID = /^\d+$/.test(
+  process.env.CDP_BRIDGE_LOCK_OWNER_PID || '',
+)
+  ? process.env.CDP_BRIDGE_LOCK_OWNER_PID
+  : String(process.pid);
 
 // Ownership semantics: last writer wins. Each bridge stamps its own pid; the
 // forwarder honors the lock while the pid IN THE FILE is alive. Overlapping
@@ -675,7 +700,7 @@ let bridgeLockHeld = false;
 
 function acquireBridgeLock() {
   try {
-    fs.writeFileSync(BRIDGE_LOCK_FILE, String(process.pid));
+    fs.writeFileSync(BRIDGE_LOCK_FILE, BRIDGE_LOCK_OWNER_PID);
     bridgeLockHeld = true;
   } catch {
     // Lock is best-effort: a missing runtime dir must not break bridge commands.
@@ -749,7 +774,7 @@ Environment:
     process.exit(0);
   }
 
-  const handler = COMMANDS[command];
+  const handler = COMMANDS[command === 'status-selected' ? 'status' : command];
   if (!handler) {
     console.error(`Unknown command: ${command}`);
     console.error(`Available: ${Object.keys(COMMANDS).join(', ')}`);
@@ -764,6 +789,8 @@ Environment:
   const timeout = Number.parseInt(process.env.CDP_TIMEOUT || '5000', 10);
 
   // `status` probes ALL connected targets so both platforms are visible.
+  // `status-selected` falls through to the normal pinned discovery path for
+  // action code that must survive one device's Hermes runtime rotation.
   if (command === 'status') {
     const { discoverAllTargets } = require('./lib/target-discovery.cjs');
     const allTargets = await discoverAllTargets(port);

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -6,7 +6,12 @@ const { createWSClient } = require('./ws-client.cjs');
 const { BRIDGE_ERROR_CODES, coded } = require('./bridge-errors.cjs');
 
 const FETCH_TIMEOUT_MS = Number.parseInt(process.env.CDP_TIMEOUT || '30000', 10);
-const FETCH_RETRIES = Number.parseInt(process.env.CDP_DISCOVERY_RETRIES || '3', 10);
+const DISCOVERY_RETRY_DELAY_MS = 500;
+const FETCH_RETRIES = Number.parseInt(
+  process.env.CDP_DISCOVERY_RETRIES ||
+    String(Math.max(3, Math.ceil(FETCH_TIMEOUT_MS / DISCOVERY_RETRY_DELAY_MS))),
+  10,
+);
 
 /** Fetch JSON from a URL (http only, no external deps) */
 function fetchJSONOnce(url) {
@@ -30,17 +35,25 @@ function fetchJSONOnce(url) {
   });
 }
 
-async function fetchJSON(url) {
+async function fetchJSON(url, acceptResponse) {
   let lastError;
+  let lastResponse;
   for (let attempt = 1; attempt <= FETCH_RETRIES; attempt++) {
     try {
-      return await fetchJSONOnce(url);
+      const response = await fetchJSONOnce(url);
+      lastError = undefined;
+      lastResponse = response;
+      if (!acceptResponse || await acceptResponse(response)) return response;
     } catch (error) {
       lastError = error;
-      if (attempt === FETCH_RETRIES) break;
-      await new Promise((resolve) => setTimeout(resolve, attempt * 1000));
     }
+    if (attempt === FETCH_RETRIES) break;
+    await new Promise((resolve) =>
+      setTimeout(resolve, DISCOVERY_RETRY_DELAY_MS),
+    );
   }
+  if (lastError !== undefined) throw lastError;
+  if (lastResponse !== undefined) return lastResponse;
   throw lastError;
 }
 
@@ -103,6 +116,19 @@ function rankRuntimeCandidates(targets) {
   return candidates;
 }
 
+function targetDeviceIdentity(target) {
+  try {
+    const device = new URL(target.webSocketDebuggerUrl).searchParams.get('device');
+    if (device) return device;
+  } catch {
+    // Fall back to Metro's display identity when the debugger URL is malformed.
+  }
+  // Without Metro's device id there is no safe way to collapse same-name pages
+  // into one physical device. Keep each debugger target distinct and fail closed
+  // on ambiguity instead of silently choosing between devices.
+  return target.webSocketDebuggerUrl || target.deviceName || '';
+}
+
 /**
  * Discover the Hermes CDP WebSocket URL from Metro's /json/list endpoint.
  *
@@ -114,9 +140,34 @@ function rankRuntimeCandidates(targets) {
  */
 async function discoverTarget(port) {
   const listUrl = `http://localhost:${port}/json/list`;
+  const androidTargetName = loadAndroidTargetDeviceName();
+  const androidDevice = loadAndroidDevice();
+  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
+  const androidPinned = Boolean(androidTargetName || androidDevice);
+  const simName = loadSimulatorName();
+  const matchesAndroidPin = (target) => androidTargetName
+    ? target.deviceName !== simName &&
+      (target.deviceName === androidTargetName ||
+        (target.deviceName != null && target.deviceName.startsWith(androidTargetName)))
+    : target.deviceName === androidDevice;
+  let acceptedPinnedCandidate;
   let targets;
   try {
-    targets = await fetchJSON(listUrl);
+    targets = await fetchJSON(listUrl, async (response) => {
+      const runtimeCandidates = rankRuntimeCandidates(response);
+      if (runtimeCandidates.length === 0) return false;
+      if (androidPinned) {
+        const pinnedCandidates = runtimeCandidates.filter(matchesAndroidPin);
+        for (const candidate of pinnedCandidates) {
+          if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+            acceptedPinnedCandidate = candidate;
+            return true;
+          }
+        }
+        return false;
+      }
+      return true;
+    });
   } catch (e) {
     throw coded(
       new Error(`Cannot reach Metro at ${listUrl}. Is Metro running?\n  ${e.message}`),
@@ -137,17 +188,11 @@ async function discoverTarget(port) {
   //     from the adb serial via `adb -s <serial> shell getprop ro.product.model`.
   //     Example: "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36".
   //   ANDROID_DEVICE — exact user-specified Metro deviceName.
-  const androidTargetName = loadAndroidTargetDeviceName();
-  const androidDevice = loadAndroidDevice();
-  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
-  const androidPinned = Boolean(androidTargetName || androidDevice);
-
   // Filter by simulator name if IOS_SIMULATOR is set — but never when an android
   // pin is present: dual-platform slots carry an ambient IOS_SIMULATOR in their
   // context, and letting it win here sends a pinned android action to the iOS
   // target. No-match keeps the full candidate set (ambient sim configs tolerate a
   // sim that is not currently attached).
-  const simName = loadSimulatorName();
   if (simName && !androidPinned && candidates.length > 1) {
     const deviceFiltered = candidates.filter(
       (t) => t.deviceName === simName,
@@ -163,7 +208,7 @@ async function discoverTarget(port) {
   // remained; the pin was ignored and the recipe drove the simulator). When a
   // device is pinned, we MUST NOT silently fall back to another target; an
   // unmatchable pin fails fast with diagnostics.
-  if (androidPinned && candidates.length > 0) {
+  if (androidPinned) {
     let androidFiltered = [];
 
     if (androidTargetName) {
@@ -171,20 +216,19 @@ async function discoverTarget(port) {
       // /json/list has no explicit platform field, so scope the ANDROID pin by
       // excluding the one iOS identity we do know (the pinned simulator name) —
       // a simulator named to shadow a model string must not satisfy an android pin.
-      androidFiltered = candidates.filter(
-        (t) => t.deviceName !== simName &&
-               (t.deviceName === androidTargetName ||
-                (t.deviceName != null && t.deviceName.startsWith(androidTargetName))),
-      );
-      if (androidFiltered.length > 1) {
+      androidFiltered = candidates.filter(matchesAndroidPin);
+      const matchingDeviceIdentities = [...new Set(
+        androidFiltered.map(targetDeviceIdentity),
+      )];
+      if (matchingDeviceIdentities.length > 1) {
         // Two same-model devices produce identical Metro model prefixes — the pin
-        // is genuinely ambiguous; picking one silently is exactly the bug this
-        // path exists to prevent.
+        // is genuinely ambiguous. Native + JS pages share the same Metro device
+        // identity and must remain available for probing.
         const ambiguousList = androidFiltered
-          .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
+          .map((target) => `  deviceName=${JSON.stringify(target.deviceName || '')} ws=${target.webSocketDebuggerUrl || ''}`)
           .join('\n');
         throw coded(new Error(
-          `Pinned Android device is ambiguous: model '${androidTargetName}' matches ${androidFiltered.length} Metro targets.\n` +
+          `Pinned Android device is ambiguous: model '${androidTargetName}' matches ${matchingDeviceIdentities.length} Metro devices.\n` +
           `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
           `  Matching Metro targets:\n${ambiguousList}\n` +
           `  Set ANDROID_DEVICE to the exact Metro deviceName to disambiguate.`,
@@ -206,7 +250,7 @@ async function discoverTarget(port) {
       candidates = androidFiltered;
     } else if (androidDevice) {
       // Exact Metro deviceName match when the user set ANDROID_DEVICE directly.
-      androidFiltered = candidates.filter((t) => t.deviceName === androidDevice);
+      androidFiltered = candidates.filter(matchesAndroidPin);
       if (androidFiltered.length === 0) {
         // Pinned by exact Metro name but no candidate matched — fail fast.
         const candidateList = targets
@@ -233,6 +277,17 @@ async function discoverTarget(port) {
     );
   }
 
+  if (acceptedPinnedCandidate) {
+    for (const candidate of candidates) {
+      if (candidate.webSocketDebuggerUrl === acceptedPinnedCandidate.webSocketDebuggerUrl) {
+        return {
+          wsUrl: acceptedPinnedCandidate.webSocketDebuggerUrl,
+          deviceName: acceptedPinnedCandidate.deviceName || '',
+        };
+      }
+    }
+  }
+
   // Sort by page number descending (JS runtime has higher page number than C++
   // native). rankRuntimeCandidates output arrives pre-sorted; this re-sort is
   // load-bearing only when the raw targets.filter() fallback above repopulated
@@ -251,6 +306,18 @@ async function discoverTarget(port) {
     }
   }
 
+  if (androidPinned) {
+    const candidateList = candidates
+      .map((target) => `  deviceName=${JSON.stringify(target.deviceName || '')} ws=${target.webSocketDebuggerUrl || ''}`)
+      .join('\n');
+    throw coded(new Error(
+      `Pinned Android device has no responding __AGENTIC__ JS runtime after ${FETCH_RETRIES} discovery attempt(s).\n` +
+      `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
+      `  Matching non-agentic targets:\n${candidateList}\n` +
+      `  The native C++ page is not a valid recipe target; wait for Android Hermes to re-register or relaunch the Android app.`,
+    ), BRIDGE_ERROR_CODES.NO_TARGET);
+  }
+
   // Fallback: return highest page number (most likely the JS runtime)
   return { wsUrl: candidates[0].webSocketDebuggerUrl, deviceName: candidates[0].deviceName || '' };
 }

package/adapters/mobile/launch-metro.cjs

@@ -26,10 +26,10 @@ function parseArgs(argv) {
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
-    console.log('Usage: launch-metro.cjs --target <path> --port <port> --log <path> --pid-file <path> [--workers <n>] [--clear]');
+    console.log('Usage: launch-metro.cjs --target <path> --port <port> --log <path> --pid-file <path> --build-env <path> [--workers <n>] [--clear]');
     return;
   }
-  for (const required of ['target', 'port', 'log', 'pid-file']) {
+  for (const required of ['target', 'port', 'log', 'pid-file', 'build-env']) {
     if (!args[required]) throw new Error(`--${required} is required`);
   }
   const target = path.resolve(args.target);
@@ -38,9 +38,9 @@ async function main() {
   fs.mkdirSync(path.dirname(log), { recursive: true });
   fs.mkdirSync(path.dirname(pidFile), { recursive: true });
   const logFd = fs.openSync(log, 'a');
-  const childArgs = ['expo', 'start', '--port', String(args.port)];
-  if (args.clear) childArgs.push('--clear');
+  const childArgs = ['watch'];
   const env = { ...process.env };
+  env.BASH_ENV = args['build-env'];
   if (args.workers) env.METRO_MAX_WORKERS = String(args.workers);
   const child = spawn('yarn', childArgs, {
     cwd: target,
@@ -59,10 +59,12 @@ async function main() {
     `${JSON.stringify({
       schemaVersion: 1,
       pid: child.pid,
+      pgid: child.pid,
       startedAt: new Date().toISOString(),
       target,
       port: Number(args.port),
       clear: Boolean(args.clear),
+      command: `yarn ${childArgs[0]}`,
     }, null, 2)}\n`,
   );
   child.unref();

package/adapters/mobile/open-device.sh

@@ -90,19 +90,29 @@ ios_app_installed() {
 }
 
 run_ios_native_build() (
-  local sim_target="$1" reason="$2" build_env=""
-  printf '%s; installing with yarn start:ios (WATCHER_PORT=%s)\n' "$reason" "$PORT" >&2
+  local sim_target="$1" bundle_id="$2" reason="$3" build_env="" build_script="" build_type=""
+  case "$bundle_id" in
+    io.metamask.MetaMask|io.metamask) build_script="start:ios"; build_type="main" ;;
+    io.metamask.MetaMask-Flask) build_script="start:ios:flask"; build_type="flask" ;;
+    *)
+      printf 'open-device: no supported local build script for iOS bundle %s\n' "$bundle_id" >&2
+      return 1
+      ;;
+  esac
+  printf '%s; installing with yarn %s (WATCHER_PORT=%s)\n' "$reason" "$build_script" "$PORT" >&2
   build_env="$(mktemp "${TMPDIR:-/tmp}/mm-harness-ios-build-env.XXXXXX")" || return 1
   chmod 600 "$build_env" || { rm -f "$build_env"; return 1; }
   trap 'rm -f "$build_env"' EXIT HUP INT TERM
   {
     printf 'export MM_HARNESS_BUILD_WATCHER_PORT=%q\n' "$PORT"
     printf 'export MM_HARNESS_BUILD_IOS_SIMULATOR=%q\n' "$sim_target"
+    printf 'export MM_HARNESS_BUILD_TYPE=%q\n' "$build_type"
     cat <<'BUILD_ENV'
 mm_harness_restore_build_target() {
   export WATCHER_PORT="$MM_HARNESS_BUILD_WATCHER_PORT"
   export METRO_PORT="$MM_HARNESS_BUILD_WATCHER_PORT"
   export IOS_SIMULATOR="$MM_HARNESS_BUILD_IOS_SIMULATOR"
+  export METAMASK_BUILD_TYPE="$MM_HARNESS_BUILD_TYPE"
 }
 eval() {
   builtin eval "$@"
@@ -122,7 +132,7 @@ BUILD_ENV
   (
     cd "$TARGET"
     command -v activate_repo_ruby_best_effort >/dev/null 2>&1 && activate_repo_ruby_best_effort "$TARGET"
-    BASH_ENV="$build_env" WATCHER_PORT="$PORT" METRO_PORT="$PORT" IOS_SIMULATOR="$sim_target" EXPO_NO_TYPESCRIPT_SETUP=1 yarn start:ios 2>&1
+    BASH_ENV="$build_env" WATCHER_PORT="$PORT" METRO_PORT="$PORT" IOS_SIMULATOR="$sim_target" METAMASK_BUILD_TYPE="$build_type" EXPO_NO_TYPESCRIPT_SETUP=1 yarn "$build_script" 2>&1
   )
 )
 
@@ -138,10 +148,16 @@ ensure_ios_app_for_mode() {
       ;;
     auto|default)
       if ios_app_installed "$sim_target" "$bundle_id"; then return 0; fi
-      run_ios_native_build "$sim_target" "iOS dev client ${bundle_id} not installed on ${sim_target}"
+      if ! run_ios_native_build "$sim_target" "$bundle_id" "iOS dev client ${bundle_id} not installed on ${sim_target}"; then
+        printf 'open-device: iOS native build failed\n' >&2
+        return 1
+      fi
       ;;
     rebuild-native|clean)
-      run_ios_native_build "$sim_target" "Rebuilding iOS dev client ${bundle_id} (--preflight-mode ${mode})"
+      if ! run_ios_native_build "$sim_target" "$bundle_id" "Rebuilding iOS dev client ${bundle_id} (--preflight-mode ${mode})"; then
+        printf 'open-device: iOS native build failed\n' >&2
+        return 1
+      fi
       ;;
     *)
       printf 'open-device: unknown --preflight-mode: %s\n' "$mode" >&2; return 2 ;;
@@ -264,14 +280,113 @@ android_app_installed() {
   "$ADB_BIN" "$@" shell pm list packages 2>/dev/null | grep -q "package:${pkg}"
 }
 
-run_android_native_build() {
-  local reason="$1"
-  printf '%s; installing with yarn start:android (WATCHER_PORT=%s)\n' "$reason" "$PORT" >&2
-  (cd "$TARGET" && WATCHER_PORT="$PORT" yarn start:android 2>&1)
+run_android_native_build() (
+  local serial="$1" expo_device="$2" pkg="$3" reason="$4" build_env="" build_script=""
+  case "$pkg" in
+    io.metamask) build_script="start:android" ;;
+    io.metamask.flask) build_script="start:android:flask" ;;
+    *)
+      printf 'open-device: no supported local build script for Android package %s\n' "$pkg" >&2
+      return 1
+      ;;
+  esac
+  printf '%s; installing with yarn %s (WATCHER_PORT=%s)\n' "$reason" "$build_script" "$PORT" >&2
+  build_env="$(mktemp "${TMPDIR:-/tmp}/mm-harness-android-build-env.XXXXXX")" || return 1
+  chmod 600 "$build_env" || { rm -f "$build_env"; return 1; }
+  trap 'rm -f "$build_env"' EXIT HUP INT TERM
+  {
+    printf 'export MM_HARNESS_BUILD_ANDROID_SERIAL=%q\n' "$serial"
+    printf 'export MM_HARNESS_BUILD_ANDROID_EXPO_DEVICE=%q\n' "$expo_device"
+    printf 'export MM_HARNESS_BUILD_WATCHER_PORT=%q\n' "$PORT"
+    cat <<'BUILD_ENV'
+mm_harness_restore_android_build_target() {
+  export WATCHER_PORT="$MM_HARNESS_BUILD_WATCHER_PORT"
+  export METRO_PORT="$MM_HARNESS_BUILD_WATCHER_PORT"
+  export ADB_SERIAL="$MM_HARNESS_BUILD_ANDROID_SERIAL"
+  export ANDROID_SERIAL="$MM_HARNESS_BUILD_ANDROID_SERIAL"
+}
+eval() {
+  builtin eval "$@"
+  local status=$?
+  mm_harness_restore_android_build_target
+  return "$status"
+}
+source() {
+  builtin source "$@"
+  local status=$?
+  mm_harness_restore_android_build_target
+  return "$status"
+}
+yarn() {
+  if [ "${1:-}" = expo ] && [ "${2:-}" = run:android ]; then
+    command yarn "$@" "$MM_HARNESS_BUILD_ANDROID_EXPO_DEVICE"
+  else
+    command yarn "$@"
+  fi
+}
+mm_harness_restore_android_build_target
+BUILD_ENV
+  } > "$build_env"
+  (
+    cd "$TARGET"
+    BASH_ENV="$build_env" \
+      WATCHER_PORT="$PORT" METRO_PORT="$PORT" \
+      ADB_SERIAL="$serial" ANDROID_SERIAL="$serial" \
+      EXPO_NO_TYPESCRIPT_SETUP=1 yarn "$build_script" 2>&1
+  )
+)
+
+resolve_android_expo_device() {
+  local serial="$1" rows="" selected_line="" expo_device="" row_serial="" row_state="" row_name="" matches=0
+  [ -n "$serial" ] || return 0
+  rows="$($ADB_BIN devices -l 2>/dev/null || true)"
+  selected_line="$(printf '%s\n' "$rows" | awk -v wanted="$serial" '$1 == wanted { print; exit }')"
+  if [ -z "$selected_line" ]; then
+    printf 'open-device: configured Android device %s is not attached\n' "$serial" >&2
+    return 1
+  fi
+  row_state="$(printf '%s\n' "$selected_line" | awk '{print $2}')"
+  if [ "$row_state" != "device" ]; then
+    printf 'open-device: configured Android device %s is not ready (state: %s)\n' "$serial" "$row_state" >&2
+    return 1
+  fi
+  if printf '%s' "$serial" | grep -q '^emulator-'; then
+    expo_device="$($ADB_BIN -s "$serial" emu avd name 2>/dev/null | tr -d '\r' | sed '/^OK$/d' | head -1 || true)"
+  else
+    expo_device="$(printf '%s\n' "$selected_line" | awk '{ for (i = 3; i <= NF; i += 1) if ($i ~ /^model:/) { sub(/^model:/, "", $i); print $i; exit } }')"
+  fi
+  [ -n "$expo_device" ] || expo_device="${ANDROID_TARGET_DEVICE_NAME:-}"
+  expo_device="${expo_device// /_}"
+  if [ -z "$expo_device" ]; then
+    printf 'open-device: could not resolve Expo device name for Android serial %s\n' "$serial" >&2
+    return 1
+  fi
+
+  while IFS= read -r selected_line; do
+    row_serial="$(printf '%s\n' "$selected_line" | awk '{print $1}')"
+    row_state="$(printf '%s\n' "$selected_line" | awk '{print $2}')"
+    [ "$row_state" = "device" ] || continue
+    if printf '%s' "$row_serial" | grep -q '^emulator-'; then
+      row_name="$($ADB_BIN -s "$row_serial" emu avd name 2>/dev/null | tr -d '\r' | sed '/^OK$/d' | head -1 || true)"
+    else
+      row_name="$(printf '%s\n' "$selected_line" | awk '{ for (i = 3; i <= NF; i += 1) if ($i ~ /^model:/) { sub(/^model:/, "", $i); print $i; exit } }')"
+    fi
+    row_name="${row_name// /_}"
+    [ "$row_name" = "$expo_device" ] && matches=$((matches + 1))
+  done <<EOF
+$rows
+EOF
+  if [ "$matches" -ne 1 ]; then
+    printf 'open-device: Expo device name %s is ambiguous across %s attached Android devices; Expo cannot select serial %s safely\n' \
+      "$expo_device" "$matches" "$serial" >&2
+    return 1
+  fi
+  printf '%s\n' "$expo_device"
 }
 
 ensure_android_app_for_mode() {
   local pkg="$1" mode="$2"
+  local expo_device=""
   shift 2
   case "$mode" in
     fast)
@@ -281,10 +396,26 @@ ensure_android_app_for_mode() {
       ;;
     auto|default)
       if android_app_installed "$pkg" "$@"; then return 0; fi
-      run_android_native_build "Android dev client ${pkg} not installed"
+      if [ -n "$ADB_SERIAL_ARG" ]; then
+        expo_device="$(resolve_android_expo_device "$ADB_SERIAL_ARG")" || return 1
+      fi
+      [ -n "$expo_device" ] || expo_device="${ANDROID_TARGET_DEVICE_NAME:-}"
+      expo_device="${expo_device// /_}"
+      if ! run_android_native_build "$ADB_SERIAL_ARG" "$expo_device" "$pkg" "Android dev client ${pkg} not installed"; then
+        printf 'open-device: Android native build failed\n' >&2
+        return 1
+      fi
       ;;
     rebuild-native|clean)
-      run_android_native_build "Rebuilding Android dev client ${pkg} (--preflight-mode ${mode})"
+      if [ -n "$ADB_SERIAL_ARG" ]; then
+        expo_device="$(resolve_android_expo_device "$ADB_SERIAL_ARG")" || return 1
+      fi
+      [ -n "$expo_device" ] || expo_device="${ANDROID_TARGET_DEVICE_NAME:-}"
+      expo_device="${expo_device// /_}"
+      if ! run_android_native_build "$ADB_SERIAL_ARG" "$expo_device" "$pkg" "Rebuilding Android dev client ${pkg} (--preflight-mode ${mode})"; then
+        printf 'open-device: Android native build failed\n' >&2
+        return 1
+      fi
       ;;
     *)
       printf 'open-device: unknown --preflight-mode: %s\n' "$mode" >&2; return 2 ;;
@@ -301,8 +432,16 @@ PY
 
 # --- dispatch -----------------------------------------------------------------
 
-BUNDLE_IDS=("${IOS_BUNDLE_ID:-io.metamask.MetaMask}" "io.metamask" "io.metamask.flask" "io.metamask.qa")
-ANDROID_PKGS=("${ANDROID_PACKAGE_ID:-io.metamask}" "io.metamask.flask" "io.metamask.qa")
+if [ -n "${IOS_BUNDLE_ID:-}" ]; then
+  BUNDLE_IDS=("$IOS_BUNDLE_ID")
+else
+  BUNDLE_IDS=("io.metamask.MetaMask" "io.metamask" "io.metamask.MetaMask-Flask" "io.metamask.qa")
+fi
+if [ -n "${ANDROID_PACKAGE_ID:-}" ]; then
+  ANDROID_PKGS=("$ANDROID_PACKAGE_ID")
+else
+  ANDROID_PKGS=("io.metamask" "io.metamask.flask" "io.metamask.qa")
+fi
 
 if [ "$PLATFORM" = "ios" ]; then
   SIM_TARGET="$(sim_udid_for_target "$SIMULATOR")"
@@ -330,7 +469,12 @@ if [ "$PLATFORM" = "ios" ]; then
 
   LAUNCHED=false
   for BUNDLE_ID in "${BUNDLE_IDS[@]}"; do
-    ensure_ios_app_for_mode "$SIM_TARGET" "$BUNDLE_ID" "$PREFLIGHT_MODE" || continue
+    if ! ensure_ios_app_for_mode "$SIM_TARGET" "$BUNDLE_ID" "$PREFLIGHT_MODE"; then
+      case "$PREFLIGHT_MODE" in
+        fast) continue ;;
+        *) exit 1 ;;
+      esac
+    fi
     if $RESTART; then
       xcrun simctl terminate "$SIM_TARGET" "$BUNDLE_ID" >/dev/null 2>&1 || true
       printf 'Restarting iOS dev client %s on %s\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
@@ -384,7 +528,12 @@ else
 
   LAUNCHED=false
   for PKG in "${ANDROID_PKGS[@]}"; do
-    ensure_android_app_for_mode "$PKG" "$PREFLIGHT_MODE" "${ADB_ARGS[@]}" || continue
+    if ! ensure_android_app_for_mode "$PKG" "$PREFLIGHT_MODE" "${ADB_ARGS[@]}"; then
+      case "$PREFLIGHT_MODE" in
+        fast) continue ;;
+        *) exit 1 ;;
+      esac
+    fi
     if $RESTART; then
       "$ADB_BIN" "${ADB_ARGS[@]}" shell am force-stop "$PKG" >/dev/null 2>&1 || true
       printf 'Restarting Android dev client %s\n' "$PKG" >&2