@deeeed/metamask-harness 0.2.0 → 0.3.0

package/adapters/mobile/open-device.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# open-device — open the MetaMask Mobile dev client on a simulator or device.
+#
+# iOS: boots simulator if needed, writes EXDevMenuIsOnboardingFinished default,
+# then opens via the expo-development-client deep link (disableOnboarding=1).
+# Android: sets adb reverse for Metro port reachability, then opens via deep link.
+# Preflight-mode guard: fast (teaching error if not installed), auto (install if missing),
+# rebuild-native / clean (always rebuild), default (same as auto).
+#
+# Inputs:
+#   --platform ios|android              (default ios)
+#   --target <metamask-mobile dir>      (default $PWD)
+#   --simulator <udid|name|"booted">    iOS simulator (default: IOS_SIMULATOR env, else "booted")
+#   --adb-serial <serial>               Android device serial (default: ADB_SERIAL env)
+#   --preflight-mode fast|auto|rebuild-native|clean  (default: fast; env MOBILE_PREFLIGHT_MODE)
+# Outputs:
+#   Progress on stderr; exit 0 pass; 1 open failed; 2 bad args.
+#
+# Single device op: open the dev client. Does not start Metro or install node_modules.
+set -uo pipefail
+
+PLATFORM="ios"
+TARGET="$PWD"
+SIMULATOR="${IOS_SIMULATOR:-${SIM_UDID:-booted}}"
+ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
+PREFLIGHT_MODE="${MOBILE_PREFLIGHT_MODE:-fast}"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --platform)       PLATFORM="$2"; shift 2 ;;
+    --target)         TARGET="$2"; shift 2 ;;
+    --simulator)      SIMULATOR="$2"; shift 2 ;;
+    --adb-serial)     ADB_SERIAL_ARG="$2"; shift 2 ;;
+    --preflight-mode) PREFLIGHT_MODE="$2"; shift 2 ;;
+    --port)           PORT="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: open-device.sh [--platform ios|android] [--target <dir>]\n'
+      printf '  [--simulator <udid|name|booted>] [--adb-serial <serial>]\n'
+      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>]\n'
+      exit 0
+      ;;
+    *) printf 'open-device: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+case "$PLATFORM" in
+  ios|android) ;;
+  *) printf 'open-device: --platform must be ios or android (got: %s)\n' "$PLATFORM" >&2; exit 2 ;;
+esac
+
+TARGET="$(cd "$TARGET" && pwd)"
+
+# --- iOS helpers --------------------------------------------------------------
+
+ios_app_installed() {
+  local sim_target="$1" bundle_id="$2"
+  xcrun simctl get_app_container "$sim_target" "$bundle_id" app >/dev/null 2>&1
+}
+
+run_ios_native_build() {
+  local sim_target="$1" reason="$2"
+  printf '%s; installing with yarn start:ios (WATCHER_PORT=%s)\n' "$reason" "$PORT" >&2
+  (cd "$TARGET" && WATCHER_PORT="$PORT" METRO_PORT="$PORT" IOS_SIMULATOR="$sim_target" EXPO_NO_TYPESCRIPT_SETUP=1 yarn start:ios 2>&1)
+}
+
+ensure_ios_app_for_mode() {
+  local sim_target="$1" bundle_id="$2" mode="$3"
+  case "$mode" in
+    fast)
+      if ios_app_installed "$sim_target" "$bundle_id"; then return 0; fi
+      printf >&2 'open-device: fast mode requires an installed iOS dev client (%s) on %s.\n' \
+        "$bundle_id" "$sim_target"
+      printf >&2 'Fast mode only prewarms the bundle and opens the existing client.\n'
+      printf >&2 'Next: use --preflight-mode auto to install if missing.\n'
+      return 1
+      ;;
+    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}"
+      ;;
+    rebuild-native|clean)
+      run_ios_native_build "$sim_target" "Rebuilding iOS dev client ${bundle_id} (--preflight-mode ${mode})"
+      ;;
+    *)
+      printf 'open-device: unknown --preflight-mode: %s\n' "$mode" >&2; return 2 ;;
+  esac
+}
+
+sim_udid_for_target() {
+  local target="$1"
+  # Already a UDID
+  if printf '%s' "$target" | grep -Eq '^[0-9A-Fa-f-]{36}$'; then
+    printf '%s\n' "$target"; return 0
+  fi
+  xcrun simctl list devices available 2>/dev/null \
+    | sed -n "s/.*${target} (\([0-9A-Fa-f-]*\)) (.*/\1/p" | head -1
+}
+
+boot_simulator_if_needed() {
+  local target="$1" state=""
+  [ "$target" != "booted" ] || return 0
+  local line=""
+  line="$(xcrun simctl list devices available 2>/dev/null | grep -F "${target} (" | head -1 || true)"
+  case "$line" in *"(Booted)"*) state="Booted" ;; *"(Shutdown)"*) state="Shutdown" ;; esac
+  [ "$state" = "Booted" ] && return 0
+  printf 'Booting iOS simulator %s%s\n' "$target" "${state:+ ($state)}" >&2
+  xcrun simctl boot "$target" 2>/dev/null || true
+  xcrun simctl bootstatus "$target" -b >/dev/null
+}
+
+show_simulator() {
+  local target="$1" udid=""
+  if [ "$target" = "booted" ]; then
+    printf 'Opening Simulator UI\n' >&2
+    open -a Simulator >/dev/null 2>&1 || true
+  else
+    udid="$(sim_udid_for_target "$target")"
+    if [ -n "$udid" ]; then
+      open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+    else
+      open -a Simulator >/dev/null 2>&1 || true
+    fi
+  fi
+  osascript -e 'tell application "Simulator" to activate' >/dev/null 2>&1 || true
+}
+
+# --- Android helpers ----------------------------------------------------------
+
+android_app_installed() {
+  local pkg="$1"
+  shift
+  adb "$@" 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)
+}
+
+ensure_android_app_for_mode() {
+  local pkg="$1" mode="$2"
+  shift 2
+  case "$mode" in
+    fast)
+      if android_app_installed "$pkg" "$@"; then return 0; fi
+      printf >&2 'open-device: fast mode requires an installed Android dev client (%s).\n' "$pkg"
+      printf >&2 'Next: use --preflight-mode auto to install if missing.\n'
+      return 1
+      ;;
+    auto|default)
+      if android_app_installed "$pkg" "$@"; then return 0; fi
+      run_android_native_build "Android dev client ${pkg} not installed"
+      ;;
+    rebuild-native|clean)
+      run_android_native_build "Rebuilding Android dev client ${pkg} (--preflight-mode ${mode})"
+      ;;
+    *)
+      printf 'open-device: unknown --preflight-mode: %s\n' "$mode" >&2; return 2 ;;
+  esac
+}
+
+# URL-encode using python3 (same as baseline).
+urlencode() {
+  python3 - "$1" <<'PY'
+import sys, urllib.parse
+print(urllib.parse.quote(sys.argv[1], safe=''))
+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 [ "$PLATFORM" = "ios" ]; then
+  SIM_TARGET="$SIMULATOR"
+
+  boot_simulator_if_needed "$SIM_TARGET"
+  show_simulator "$SIM_TARGET"
+
+  LAUNCHED=false
+  for BUNDLE_ID in "${BUNDLE_IDS[@]}"; do
+    ensure_ios_app_for_mode "$SIM_TARGET" "$BUNDLE_ID" "$PREFLIGHT_MODE" || continue
+
+    # Dismiss Expo dev-menu onboarding for clean headless runs.
+    xcrun simctl spawn "$SIM_TARGET" defaults write "$BUNDLE_ID" \
+      EXDevMenuIsOnboardingFinished -bool YES 2>/dev/null || true
+
+    # Open via expo-development-client deep link so the app connects to our Metro.
+    ENCODED_URL="$(urlencode "http://localhost:${PORT}?disableOnboarding=1" 2>/dev/null \
+      || printf 'http%%3A%%2F%%2Flocalhost%%3A%s%%3FdisableOnboarding%%3D1' "$PORT")"
+    DEEP_LINK="expo-metamask://expo-development-client/?url=${ENCODED_URL}"
+
+    printf 'Launching iOS dev client %s on %s\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
+    if xcrun simctl openurl "$SIM_TARGET" "$DEEP_LINK" 2>/dev/null; then
+      LAUNCHED=true
+      printf 'open-device: iOS dev client opened (%s on %s)\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
+      break
+    fi
+    # Fallback: plain launch (older Expo / non-development-client build).
+    if xcrun simctl launch "$SIM_TARGET" "$BUNDLE_ID" 2>/dev/null; then
+      LAUNCHED=true
+      printf 'open-device: iOS dev client launched (fallback) (%s on %s)\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
+      break
+    fi
+  done
+
+  if [ "$LAUNCHED" = false ]; then
+    printf 'open-device: no MetaMask bundle found on simulator %s\n' "$SIM_TARGET" >&2
+    printf '  tried: %s\n' "${BUNDLE_IDS[*]}" >&2
+    exit 1
+  fi
+
+else
+  ADB_ARGS=()
+  [ -n "$ADB_SERIAL_ARG" ] && ADB_ARGS+=("-s" "$ADB_SERIAL_ARG")
+
+  # Reverse-tunnel Metro port so the device can reach localhost:PORT.
+  adb "${ADB_ARGS[@]}" reverse "tcp:${PORT}" "tcp:${PORT}" >/dev/null 2>&1 || \
+    printf 'open-device: adb reverse failed (non-fatal — device may already be reachable)\n' >&2
+
+  LAUNCHED=false
+  for PKG in "${ANDROID_PKGS[@]}"; do
+    ensure_android_app_for_mode "$PKG" "$PREFLIGHT_MODE" "${ADB_ARGS[@]}" || continue
+
+    ENCODED_URL="$(urlencode "http://localhost:${PORT}?disableOnboarding=1" 2>/dev/null \
+      || printf 'http%%3A%%2F%%2Flocalhost%%3A%s%%3FdisableOnboarding%%3D1' "$PORT")"
+    DEEP_LINK="expo-metamask://expo-development-client/?url=${ENCODED_URL}"
+
+    printf 'Launching Android dev client %s\n' "$PKG" >&2
+    if adb "${ADB_ARGS[@]}" shell am start \
+        -a android.intent.action.VIEW \
+        -d "$DEEP_LINK" >/dev/null 2>&1; then
+      LAUNCHED=true
+      printf 'open-device: Android dev client opened (%s)\n' "$PKG" >&2
+      break
+    fi
+  done
+
+  if [ "$LAUNCHED" = false ]; then
+    printf 'open-device: no MetaMask package found on Android device %s\n' \
+      "${ADB_SERIAL_ARG:-<default>}" >&2
+    printf '  tried: %s\n' "${ANDROID_PKGS[*]}" >&2
+    exit 1
+  fi
+fi
+
+printf '  Next: mm-harness logs   # tail Metro\n' >&2

package/{orchestration/compat-overlays → adapters/mobile/overlay/compat}/README.md

@@ -7,13 +7,22 @@ up empty here by design: the feature's purpose is non-current checkouts.
 
 - Purpose: make historical product checkouts bootable/bridgeable under the
   current local toolchain so Recipe v1 evals can replay against them.
-- When it applies: mobile checkouts predating React Native 0.81 polyfill
-  fixes (see mobile/README.md for the per-patch details).
+- When it applies: mobile checkouts predating React Native 0.81 polyfill fixes.
 - How it is applied: MANUALLY (no automatic apply logic in this repo).
   The operator or the `/recipe-harness` skill applies the patch reversibly
   before a historical rebuild (`git apply <patch>` in the product checkout,
   `git apply -R` to remove) and records the overlay path in validation
-  evidence. `orchestration/mobile/inject.sh` does NOT apply these.
+  evidence. `adapters/mobile/inject.sh` does NOT apply these.
 
-Listed in orchestration/manifest.json (kind: compat-overlay) so the doctor
+Kept in the external runner repository, not Farmslot root scripts, so a
+`/recipe-harness` skill can apply the same reversible overlay before a
+historical rebuild and record the overlay path in validation evidence.
+
+Listed in adapters/manifest.json (kind: compat-overlay) so the doctor
 verifies the surface and this directory is never flagged as unused again.
+
+## Patches
+
+- `rn81-message-event-source.patch`: adds a read-only `MessageEvent.prototype.source`
+  getter for React Native 0.81 historical checkouts whose bundled polyfill omits
+  it while CDP websocket clients expect browser-compatible `MessageEvent` shape.

package/adapters/mobile/prewarm-bundle.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# prewarm-bundle — curl the Metro bundle URL before the dev client opens.
+#
+# Triggers Metro to compile and cache the bundle so the app connects instantly.
+# Streams progress from the Metro log every 30s until the bundle curl finishes
+# or MOBILE_BUNDLE_PREWARM_TIMEOUT seconds elapse.
+# Set MOBILE_BUNDLE_PREWARM=0 to skip.
+#
+# Inputs:
+#   --platform ios|android          (default ios)
+#   --target <metamask-mobile dir>  (default $PWD)
+#   --port <number>                 (default WATCHER_PORT env, else METRO_PORT, else 8081)
+# Outputs:
+#   Progress on stderr; exit 0 bundle ready; 1 timeout or curl error; 2 bad args.
+#
+# Single device op: prewarm the bundle. Does not start Metro or open the dev client.
+set -uo pipefail
+
+PLATFORM="ios"
+TARGET="$PWD"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --platform) PLATFORM="$2"; shift 2 ;;
+    --target)   TARGET="$2"; shift 2 ;;
+    --port)     PORT="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: prewarm-bundle.sh [--platform ios|android] [--target <dir>] [--port <n>]\n'
+      exit 0
+      ;;
+    *) printf 'prewarm-bundle: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+case "$PLATFORM" in
+  ios|android) ;;
+  *) printf 'prewarm-bundle: --platform must be ios or android (got: %s)\n' "$PLATFORM" >&2; exit 2 ;;
+esac
+
+TARGET="$(cd "$TARGET" && pwd)"
+LOG_DIR="$TARGET/temp/recipe/runtime"
+mkdir -p "$LOG_DIR"
+METRO_LOG="$LOG_DIR/metro.log"
+
+if [ "${MOBILE_BUNDLE_PREWARM:-1}" = "0" ]; then
+  printf 'Skipping %s bundle prewarm (MOBILE_BUNDLE_PREWARM=0)\n' "$PLATFORM" >&2
+  exit 0
+fi
+
+TIMEOUT="${MOBILE_BUNDLE_PREWARM_TIMEOUT:-900}"
+
+BUNDLE_URL="http://localhost:${PORT}/index.bundle?platform=${PLATFORM}&dev=true&hot=false&lazy=true&transform.engine=hermes&transform.bytecode=1&transform.routerRoot=app&unstable_transformProfile=hermes-stable"
+
+printf 'Prewarming %s bundle before launching dev client (set MOBILE_BUNDLE_PREWARM=0 to skip)\n' "$PLATFORM" >&2
+printf '  url: %s\n' "$BUNDLE_URL" >&2
+
+curl -sfL --connect-timeout 5 --max-time "$TIMEOUT" -o /dev/null "$BUNDLE_URL" &
+BUNDLE_PID=$!
+
+ELAPSED=0
+LAST_PROGRESS=""
+while kill -0 "$BUNDLE_PID" 2>/dev/null; do
+  PROGRESS=""
+  if [ -f "$METRO_LOG" ]; then
+    PROGRESS="$(grep -E '^[[:space:]]*(iOS|Android).*index\.(js|tsx?).*%|Bundl(ed|ing)|Finished' "$METRO_LOG" 2>/dev/null | tail -1 | tr -d '\r' || true)"
+  fi
+  if [ -n "$PROGRESS" ] && [ "$PROGRESS" != "$LAST_PROGRESS" ]; then
+    printf 'Bundle progress: %s\n' "$PROGRESS" >&2
+    LAST_PROGRESS="$PROGRESS"
+  elif [ $((ELAPSED % 30)) -eq 0 ] && [ "$ELAPSED" -gt 0 ]; then
+    printf 'Waiting for %s bundle (%ss/%ss)%s\n' "$PLATFORM" "$ELAPSED" "$TIMEOUT" \
+      "${LAST_PROGRESS:+ — $LAST_PROGRESS}" >&2
+  fi
+  if [ "$ELAPSED" -ge "$TIMEOUT" ]; then
+    kill "$BUNDLE_PID" 2>/dev/null || true
+    wait "$BUNDLE_PID" 2>/dev/null || true
+    printf 'prewarm-bundle: %s bundle did not become ready before timeout (%ss)\n' "$PLATFORM" "$TIMEOUT" >&2
+    [ -f "$METRO_LOG" ] && tail -80 "$METRO_LOG" >&2 || true
+    printf '  Next: check %s for errors or reduce MOBILE_BUNDLE_PREWARM_TIMEOUT\n' "$METRO_LOG" >&2
+    exit 1
+  fi
+  sleep 3
+  ELAPSED=$((ELAPSED + 3))
+done
+
+if wait "$BUNDLE_PID"; then
+  printf '%s bundle ready\n' "$PLATFORM" >&2
+  exit 0
+fi
+
+printf 'prewarm-bundle: %s bundle curl failed\n' "$PLATFORM" >&2
+[ -f "$METRO_LOG" ] && tail -80 "$METRO_LOG" >&2 || true
+printf '  Next: check %s for Metro errors\n' "$METRO_LOG" >&2
+exit 1

package/adapters/mobile/start-metro.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+# start-metro — ensure the Metro bundler is running for this MetaMask Mobile checkout.
+#
+# Checks if Metro is already running and owned by this checkout with required env vars.
+# Clears stale or foreign listeners before starting. Uses yarn expo start --port (not
+# yarn start), sources .js.env/.env/.env.local, sets EXPO_NO_TYPESCRIPT_SETUP=1, and
+# caps METRO_MAX_WORKERS to 6 (or the physical CPU count).
+#
+# Inputs:
+#   --target <metamask-mobile dir>  (default $PWD)
+#   --port <number>                 (default: WATCHER_PORT env, else METRO_PORT, else 8081)
+#   --clear                         reset Metro bundler cache before starting
+# Outputs:
+#   Progress on stderr; exit 0 Metro ready; 1 failed to start; 2 bad args.
+#
+# Single device op: ensure Metro is running. Does not open the dev client or install deps.
+set -uo pipefail
+
+TARGET="$PWD"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+CLEAR=false
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --port)   PORT="$2"; shift 2 ;;
+    --clear)  CLEAR=true; shift ;;
+    -h|--help)
+      printf 'Usage: start-metro.sh [--target <dir>] [--port <port>] [--clear]\n'
+      printf '  --target  MetaMask Mobile checkout directory\n'
+      printf '  --port    Metro port (default: WATCHER_PORT env or 8081)\n'
+      printf '  --clear   restart with cleared cache\n'
+      exit 0
+      ;;
+    *) printf 'start-metro: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+TARGET="$(cd "$TARGET" && pwd)"
+LOG_DIR="$TARGET/temp/recipe/runtime"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/metro.log"
+PID_FILE="$LOG_DIR/metro.pid"
+
+# --- helpers ------------------------------------------------------------------
+
+metro_ready() {
+  curl -sf --max-time 2 "http://localhost:${PORT}/status" 2>/dev/null | grep -q 'packager-status:running'
+}
+
+metro_listener_pids() {
+  lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' || true
+}
+
+metro_listener_valid() {
+  local pids pid command rv
+  pids="$(metro_listener_pids)"
+  [ -n "$(printf '%s' "$pids" | tr -d ' ')" ] || return 1
+  rv=0
+  for pid in $pids; do
+    command="$(ps eww -p "$pid" -o command= 2>/dev/null || true)"
+    case "$command" in
+      *"$TARGET"*) ;;
+      *)
+        printf 'Metro on port %s not owned by this checkout (pid %s); restarting\n' "$PORT" "$pid" >&2
+        rv=1; break
+        ;;
+    esac
+    for required_var in ${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID}; do
+      if ! printf '%s\n' "$command" | grep -Eq "(^|[[:space:]])${required_var}="; then
+        printf 'Metro on port %s missing required env %s (pid %s); restarting\n' "$PORT" "$required_var" "$pid" >&2
+        rv=1; break 2
+      fi
+    done
+  done
+  return "$rv"
+}
+
+stop_metro_listener() {
+  local pids i
+  pids="$(metro_listener_pids)"
+  [ -n "$(printf '%s' "$pids" | tr -d ' ')" ] || return 0
+  printf 'Stopping Metro listener on port %s: %s\n' "$PORT" "$pids" >&2
+  # shellcheck disable=SC2086
+  kill $pids 2>/dev/null || true
+  for i in $(seq 1 20); do
+    pids="$(metro_listener_pids)"
+    [ -z "$(printf '%s' "$pids" | tr -d ' ')" ] && return 0
+    sleep 0.25
+  done
+  printf 'Metro listener still held; force-killing: %s\n' "$pids" >&2
+  # shellcheck disable=SC2086
+  kill -KILL $pids 2>/dev/null || true
+  for i in $(seq 1 20); do
+    pids="$(metro_listener_pids)"
+    [ -z "$(printf '%s' "$pids" | tr -d ' ')" ] && return 0
+    sleep 0.25
+  done
+  printf 'start-metro: port %s still occupied after force-kill: %s\n' "$PORT" "$pids" >&2
+  return 1
+}
+
+default_metro_workers() {
+  local cores=""
+  if command -v sysctl >/dev/null 2>&1; then
+    cores="$(sysctl -n hw.perflevel0.physicalcpu 2>/dev/null || sysctl -n hw.physicalcpu 2>/dev/null || true)"
+  fi
+  if printf '%s' "${cores:-}" | grep -Eq '^[0-9]+$' && [ "${cores:-0}" -gt 0 ]; then
+    [ "${cores:-4}" -gt 6 ] && cores=6
+    printf '%s\n' "$cores"
+  else
+    printf '4\n'
+  fi
+}
+
+start_viewer_window() {
+  local metro_log="$1"
+  command -v tmux >/dev/null 2>&1 || return 0
+  local window="metro-${PORT}"
+  local metro_tmux="$LOG_DIR/metro.tmux"
+  local session=""
+  if [ -n "${slot:-}" ] && tmux has-session -t "=mm-${slot}" 2>/dev/null; then
+    session="mm-${slot}"
+  fi
+  if [ -z "$session" ]; then
+    session="$(tmux display-message -p '#S' 2>/dev/null || true)"
+  fi
+  [ -n "$session" ] || return 0
+  tmux kill-window -t "${session}:${window}" >/dev/null 2>&1 || true
+  tmux new-window -d -t "$session" -n "$window" "exec tail -n +1 -F $(printf '%q' "$metro_log")"
+  printf '%s:%s\n' "$session" "$window" > "$metro_tmux"
+  printf 'Metro log viewer → tmux %s:%s\n' "$session" "$window" >&2
+}
+
+# --- main ---------------------------------------------------------------------
+
+# Decide whether to (re)start or skip.
+if metro_ready; then
+  if [ "$CLEAR" = true ]; then
+    printf 'Restarting Metro on port %s with cleared cache\n' "$PORT" >&2
+    stop_metro_listener || exit 1
+    rm -f "$PID_FILE"
+  elif metro_listener_valid; then
+    printf 'Metro already running and valid on port %s\n' "$PORT" >&2
+    exit 0
+  else
+    stop_metro_listener || exit 1
+    rm -f "$PID_FILE"
+  fi
+fi
+
+stop_metro_listener || exit 1
+
+METRO_WORKERS="${METRO_MAX_WORKERS:-$(default_metro_workers)}"
+CLEAR_SUFFIX=""
+[ "$CLEAR" = true ] && CLEAR_SUFFIX=" --clear"
+
+printf 'Starting Metro on port %s (workers=%s%s)\n' \
+  "$PORT" "$METRO_WORKERS" "${CLEAR:+, clear}" >&2
+printf '(Full log: %s — recipe logs | recipe logs --full)\n' "$LOG_FILE" >&2
+
+# Metro runs detached, writing to the log. The tmux window is a read-only tail.
+(
+  cd "$TARGET"
+  : > "$LOG_FILE"
+  # Source product env files (provides MM_INFURA_PROJECT_ID and friends).
+  set -a
+  # shellcheck disable=SC1091
+  [ ! -f .js.env ]    || . ./.js.env
+  # shellcheck disable=SC1091
+  [ ! -f .env ]       || . ./.env
+  # shellcheck disable=SC1091
+  [ ! -f .env.local ] || . ./.env.local
+  set +a
+  export EXPO_NO_TYPESCRIPT_SETUP=1
+  export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
+  export METRO_MAX_WORKERS="${METRO_WORKERS}"
+  # shellcheck disable=SC2094
+  bash -c "exec yarn expo start --port ${PORT}${CLEAR_SUFFIX}" \
+    </dev/null >> "$LOG_FILE" 2>&1 &
+  echo "$!" > "$PID_FILE"
+)
+# Disown the background process so it outlives this script.
+disown "$(cat "$PID_FILE" 2>/dev/null || true)" 2>/dev/null || true
+
+start_viewer_window "$LOG_FILE"
+
+# Attach a log-tui watcher for compact event display (best-effort; non-blocking).
+LOG_TUI="$(dirname "$0")/../shared/log-tui.mjs"
+TAIL_PID=""
+if [ -f "$LOG_TUI" ] && command -v node >/dev/null 2>&1 \
+   && [ "${METAMASK_RECIPE_AUTO_HUD:-1}" != "0" ]; then
+  node "$LOG_TUI" watch \
+    --log "$LOG_FILE" \
+    --events "${RECIPE_LOG_EVENTS:-12}" \
+    --mode compact \
+    --label "Metro bundler" \
+    --success-pattern 'Dev server ready' &
+  TAIL_PID=$!
+fi
+
+# Ready-poll: 90 × 1s = 90 s timeout.
+READY=false
+for _i in $(seq 1 90); do
+  if metro_ready; then
+    READY=true
+    break
+  fi
+  sleep 1
+done
+
+[ -n "$TAIL_PID" ] && { kill "$TAIL_PID" 2>/dev/null; wait "$TAIL_PID" 2>/dev/null || true; }
+
+if [ "$READY" = true ]; then
+  printf 'Metro ready on port %s\n' "$PORT" >&2
+  printf '  Next: mm-harness logs  (tail Metro)\n' >&2
+  exit 0
+fi
+
+# Failure: dump log events for diagnosis.
+if [ -f "$LOG_TUI" ] && command -v node >/dev/null 2>&1; then
+  node "$LOG_TUI" events --log "$LOG_FILE" --events 20 >&2 || true
+else
+  tail -40 "$LOG_FILE" >&2 || true
+fi
+printf 'start-metro: Metro did not become ready on port %s within 90s\n' "$PORT" >&2
+printf '  Next: check %s for errors, or run mm-harness logs\n' "$LOG_FILE" >&2
+exit 1

package/{runner → adapters}/mobile/verify.sh

@@ -58,12 +58,12 @@ esac
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
-for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../../orchestration/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../../adapters/shared/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
   [ -f "$_hp" ] && { . "$_hp"; break; }
 done
 unset _hp
 if ! command -v harness_root >/dev/null 2>&1; then
-  echo "mobile verify: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  echo "mobile verify: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
 fi
 TARGET="$(cd "$TARGET" && pwd)"
@@ -71,7 +71,7 @@ RUNTIME_DIR="$(recipe_runtime_dir)"
 HARNESS_ROOT="$(harness_root)"
 HARNESS_REL="$HARNESS_ROOT/mobile"
 HARNESS_DIR="$(harness_dir "$TARGET" mobile)"
-RUNNER_BIN="$HARNESS_DIR/runner/bin/metamask-recipe"
+RUNNER_BIN="$HARNESS_DIR/runner/bin/mm-harness"
 ARTIFACTS="${ARTIFACTS:-$HARNESS_DIR/verify/$(date -u +%Y%m%dT%H%M%SZ)}"
 mkdir -p "$ARTIFACTS/logs"
 
@@ -221,7 +221,7 @@ check_file() {
 
 check_file "$HARNESS_REL/manifest.json"
 check_file "$HARNESS_REL/action-manifest.json"
-check_file "$HARNESS_REL/runner/bin/metamask-recipe"
+check_file "$HARNESS_REL/runner/bin/mm-harness"
 check_file "package.json"
 check_file "app/dev-tools/AgenticService/AgenticService.ts"
 
@@ -263,7 +263,7 @@ if (!runnerDir) {
   process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner source unavailable; overlay freshness compare skipped' }));
   process.exit(0);
 }
-const overlayDir = path.join(runnerDir, 'library', 'actions', 'mobile', 'app-overlay', 'app', 'core', 'AgenticService');
+const overlayDir = path.join(runnerDir, 'adapters', 'mobile', 'overlay', 'app', 'core', 'AgenticService');
 let checked = 0;
 const drifted = [];
 const missing = [];
@@ -289,7 +289,7 @@ if (checked === 0) {
   const parts = [];
   if (drifted.length) parts.push('behind runner: ' + drifted.join(', '));
   if (missing.length) parts.push('absent in repo: ' + missing.join(', '));
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun metamask-recipe install --force-overlay or recipe sync to refresh the in-repo HUD/AgenticService from the runner' }));
+  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun mm-harness install --force-overlay or recipe sync to refresh the in-repo HUD/AgenticService from the runner' }));
 } else {
   process.stdout.write(JSON.stringify({ name, status: 'pass' }));
 }