@deeeed/metamask-harness 0.2.0

package/orchestration/porcelain/mm-recipe

@@ -0,0 +1,1591 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage:
+  mm-recipe                         home status screen (default)
+  mm-recipe status [--json]         readiness summary + suggested next commands
+  mm-recipe ports [--json]          slot ports, runtime paths, device hints
+  mm-recipe up [--json] [--dry-run] decide + run minimum work to reach ready
+  mm-recipe decision [--json]           runtime-decision (deps + Metro bundle gate)
+  mm-recipe ios                     start/reuse Metro, launch iOS dev client
+  mm-recipe android                 start/reuse Metro, launch Android dev client
+  mm-recipe sync [--json]           refresh mobile harness + canonicalize wallet fixture
+  mm-recipe completion [install]    install shell tab completion (bash + zsh)
+  mm-recipe prepare                 install harness, start/reuse runtime, optionally setup wallet
+    --target <repo> --platform ios|android --preflight-mode fast|auto|default|rebuild-native|clean --port <port> --simulator <sim> --adb-serial <serial> --runtime-dir <dir> --wallet-setup [--wallet-fixture <json>]
+  mm-recipe setup:ios               ios + setup wallet fixture
+  mm-recipe setup:android           android + setup wallet fixture
+  mm-recipe refresh                 start/reuse Metro, relaunch detected dev client
+  mm-recipe reload                  alias for refresh
+  mm-recipe logs [--full]           tail last Metro events (default) or full log
+  mm-recipe interactive             interactive menu
+  mm-recipe runtime-status [--json] structured Metro/bundle/bridge status
+  mm-recipe route                   current route
+  mm-recipe navigate <Route> [json] navigate by React Navigation route
+  mm-recipe unlock [password]       unlock with fixture password if omitted
+  mm-recipe setup-wallet [fixture]  apply wallet fixture
+  mm-recipe accounts                list accounts
+  mm-recipe select-account <addr>   switch account
+  mm-recipe screenshot [path]       simulator/device screenshot
+  mm-recipe debug [--json]          open React Native DevTools / Hermes debugger
+  mm-recipe dev-menu [--json]       open the React Native developer menu
+  mm-recipe stop                    stop this slot's Metro
+  mm-recipe actions [--json]
+  mm-recipe doctor [--json]
+  mm-recipe run <recipe.json> [args] run recipe with detected slot env
+  mm-recipe <recipe.json> [args]    shortcut for run
+
+Detects Mobile root, .js.env, WATCHER_PORT, IOS_SIMULATOR/ANDROID_DEVICE.
+EOF
+  recipe_speed_ladder
+}
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+runner="$script_dir/metamask-recipe"
+# This script lives at <root>/orchestration/porcelain/; the runner root is two up.
+runner_root="$(cd "$script_dir/../.." && pwd -P)"
+# shellcheck disable=SC1091
+. "$runner_root/orchestration/lib/harness-path.sh"
+. "$runner_root/orchestration/lib/cli-ux.sh"
+RECIPE_RUNNER_ROOT="$runner_root"
+bridge="$runner_root/library/actions/mobile/bridge-runtime/cdp-bridge.cjs"
+setup_wallet_script="$runner_root/library/actions/mobile/bridge-runtime/setup-wallet.sh"
+open_debug_script="$runner_root/orchestration/lib/open-debug.mjs"
+
+find_mobile_root() {
+  local dir="$(pwd -P)"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/package.json" ] && { grep -q 'metamask-mobile' "$dir/package.json" 2>/dev/null || [[ "$(basename "$dir")" == metamask-mobile* ]]; }; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+load_env_file() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line#export }"
+    case "$line" in
+      WATCHER_PORT=*|CDP_PORT=*|IOS_SIMULATOR=*|SIM_UDID=*|ANDROID_DEVICE=*|ADB_SERIAL=*|ANDROID_SERIAL=*)
+        key="${line%%=*}"
+        val="${line#*=}"
+        val="${val%%#*}"
+        val="$(printf '%s' "$val" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' -e 's/^"//' -e 's/"$//' -e "s/^'//" -e "s/'$//")"
+        [ -n "${!key:-}" ] || export "$key=$val"
+        ;;
+    esac
+  done < "$file"
+}
+
+infer_slot_number() {
+  local root="$1" base
+  base="$(basename "$root")"
+  [[ "$base" =~ -([0-9]+)$ ]] && printf '%s\n' "${BASH_REMATCH[1]}"
+}
+
+infer_mobile_platform() {
+  if [ -n "${ANDROID_DEVICE:-${ADB_SERIAL:-${ANDROID_SERIAL:-}}}" ]; then
+    printf 'android\n'
+    return 0
+  fi
+  local platform="${RECIPE_HARNESS_PLATFORM:-${PLATFORM:-}}"
+  case "$platform" in
+    android|ios) printf '%s\n' "$platform"; return 0 ;;
+  esac
+  printf 'ios\n'
+}
+
+init_context() {
+  root="$(find_mobile_root)" || { echo "mm-recipe: run from a metamask-mobile checkout" >&2; exit 2; }
+  load_env_file "$root/.js.env"
+  load_env_file "$root/.env"
+  load_env_file "$root/.env.local"
+  slot="$(infer_slot_number "$root" || true)"
+  if [ -n "$slot" ]; then
+    [ -n "${WATCHER_PORT:-}" ] || export WATCHER_PORT="806$slot"
+    [ -n "${IOS_SIMULATOR:-}" ] || export IOS_SIMULATOR="mm-$slot"
+  fi
+  # Bare (non-slot) checkout: default to Metro's well-known port so the launch
+  # path never trips `set -u` on an unbound WATCHER_PORT. Farm dispatch sets the
+  # slot-derived port above; both are the single source read everywhere below.
+  [ -n "${WATCHER_PORT:-}" ] || export WATCHER_PORT=8081
+  [ -n "${CDP_PORT:-}" ] || export CDP_PORT="${WATCHER_PORT:-}"
+  runtime_dir="$(recipe_runtime_dir)"
+  export RECIPE_RUNTIME_DIR="$runtime_dir"
+  mkdir -p "$root/$runtime_dir" "$root/temp/recipe-artifacts"
+}
+
+
+pretty_json() {
+  node -e '
+let d="";
+process.stdin.on("data", c => d += c).on("end", () => {
+  const color = process.env.RECIPE_COLOR === "1";
+  const c = (code, s) => color ? `\x1b[${code}m${s}\x1b[0m` : s;
+  try {
+    const v = JSON.parse(d);
+    if (v.decision) {
+      console.log(`${c("1;33", "Decision")}: ${c("1;32", v.decision)}${v.reasonCode ? ` ${c("2", "-")} ${c("0;37", v.reasonCode)}` : ""}`);
+      if (Array.isArray(v.reasons)) for (const r of v.reasons) console.log(`  ${c("2", "-")} ${r}`);
+      return;
+    }
+    if (v.adapter && Array.isArray(v.actions) && v.actions.every(a => a && a.name)) {
+      console.log(`${c("1;36", "Actions")} ${c("2", `(${v.adapter})`)}:`);
+      for (const a of v.actions) {
+        console.log(`  ${c("1;32", a.name)}${a.description ? ` ${c("2", "-")} ${c("0;37", a.description)}` : ""}`);
+      }
+      return;
+    }
+    if (v.status && v.adapter) {
+      const status = String(v.status).toUpperCase();
+      const code = status === "PASS" || status === "OK" ? "1;32" : status === "FAIL" || status === "ERROR" ? "1;31" : "1;33";
+      console.log(`${c(code, status)} ${c("1;36", v.adapter)}${v.compatibilityMode ? ` ${c("2", "-")} ${v.compatibilityMode}` : ""}`);
+      return;
+    }
+    if (v.account || v.route || v.deviceName) {
+      console.log(`${c("1;36", "Device")}: ${v.deviceName || "?"}${v.platform ? ` ${c("2", `(${v.platform})`)}` : ""}`);
+      console.log(`${c("1;36", "Route")}: ${v.route && v.route.name ? v.route.name : JSON.stringify(v.route || null)}`);
+      if (v.account) console.log(`${c("1;36", "Account")}: ${v.account.name || "?"} ${c("2", v.account.address || "")}`);
+      return;
+    }
+    console.log(JSON.stringify(v, null, 2));
+  } catch {
+    process.stdout.write(d);
+  }
+})'
+}
+
+json_requested() {
+  for arg in "$@"; do [ "$arg" = "--json" ] && return 0; done
+  return 1
+}
+
+full_logs_requested() {
+  for arg in "$@"; do
+    case "$arg" in
+      --full|-f) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+dry_run_requested() {
+  for arg in "$@"; do
+    case "$arg" in
+      --dry-run|--explain|-n) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+color_requested() {
+  [ "${RECIPE_NO_COLOR:-}" != "1" ] && { [ "${RECIPE_COLOR:-}" = "1" ] || [ "${FORCE_COLOR:-}" = "1" ] || [ -t 1 ]; }
+}
+
+pipe_pretty() {
+  if color_requested; then (export RECIPE_COLOR=1; pretty_json); else pretty_json; fi
+}
+
+run_pretty() {
+  if json_requested "$@"; then "$@"; else "$@" | pipe_pretty; fi
+}
+
+run_json_pretty() {
+  if json_requested "$@"; then "$@"; else "$@" --json | pipe_pretty; fi
+}
+log() { printf 'mm-recipe: %s\n' "$*" >&2; }
+
+shell_quote() {
+  printf '%q' "$1"
+}
+
+resolve_mobile_harness_script() {
+  local candidate
+
+  for candidate in \
+    "${FARMSLOT_RECIPE_HARNESS_SCRIPT:-}" \
+    "${RECIPE_HARNESS_SCRIPT:-}"; do
+    if [ -n "$candidate" ] && [ -x "$candidate" ]; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+  done
+
+
+
+  return 1
+}
+
+install_mobile_harness() {
+  local harness_script runner_inject
+  if harness_script="$(resolve_mobile_harness_script)"; then
+    log "Installing mobile recipe harness via ${harness_script}"
+    RECIPE_HARNESS_ROOT="$(harness_root)" "$harness_script" mobile install --target "$root"
+    return 0
+  fi
+
+  runner_inject="$runner_root/orchestration/mobile/inject.sh"
+  if [ -x "$runner_inject" ]; then
+    log "Installing mobile recipe harness via ${runner_inject}"
+    RECIPE_HARNESS_ROOT="$(harness_root)" "$runner_inject" --target "$root"
+    return 0
+  fi
+
+  cat >&2 <<EOF
+mm-recipe: mobile recipe harness installer not found.
+
+Prepare requires either this runner's mobile injector or an explicit
+recipe-harness script. Set FARMSLOT_RECIPE_HARNESS_SCRIPT or
+RECIPE_HARNESS_SCRIPT to <recipe-harness>/scripts/recipe-harness.
+EOF
+  return 1
+}
+
+mobile_harness_patched() {
+  [ -f "$root/app/dev-tools/AgenticService/AgenticService.ts" ] \
+    && grep -q "AgenticService.install" "$root/app/core/NavigationService/NavigationService.ts" 2>/dev/null \
+    && grep -q "AgentStepHud" "$root/app/components/Nav/App/App.tsx" 2>/dev/null
+}
+
+ensure_mobile_harness_patched() {
+  init_context
+  if mobile_harness_patched; then
+    return 0
+  fi
+
+  local had_metro=false
+  if metro_ready; then
+    had_metro=true
+  fi
+
+  log "Mobile recipe harness patches missing or stale; reinstalling before launch"
+  install_mobile_harness
+
+  if ! mobile_harness_patched; then
+    echo "mm-recipe: mobile recipe harness install completed but required patch markers are still missing" >&2
+    return 1
+  fi
+
+  if [ "$had_metro" = true ]; then
+    log "Restarting Metro so the rebuilt graph includes the refreshed harness patches"
+    stop_metro
+  fi
+}
+
+# Fast, bounded teaching failure when dependencies are not installed. Metro/yarn
+# can never come up without them, so launching — or retrying the launch — only
+# loops. Grounded in the primary mobile deps marker runtime-decision reads
+# (node_modules/.yarn-state.yml, orchestration/mobile/deps-markers.ts).
+require_mobile_deps() {
+  [ -e "$root/node_modules/.yarn-state.yml" ] && return 0
+  log "dependencies not installed — run yarn install / yarn setup first."
+  log "Next: cd $(shell_quote "$root") && yarn setup"
+  return 2
+}
+
+metro_ready() {
+  curl -sf --max-time 2 "http://localhost:${WATCHER_PORT:-8081}/status" 2>/dev/null | grep -q 'packager-status:running'
+}
+
+metro_listener_pids() {
+  lsof -nP -iTCP:${WATCHER_PORT:-8081} -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' || true
+}
+
+metro_listener_valid() {
+  local pids pid command required_var
+  pids="$(metro_listener_pids)"
+  [ -n "$(printf '%s' "$pids" | tr -d ' ')" ] || return 1
+
+  for pid in $pids; do
+    command="$(ps eww -p "$pid" -o command= 2>/dev/null || true)"
+    case "$command" in
+      *"$root"*) ;;
+      *)
+        log "Metro listener on port ${WATCHER_PORT} is not owned by this checkout (pid ${pid}); restarting it"
+        return 1
+        ;;
+    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
+        log "Metro listener on port ${WATCHER_PORT} is missing required env ${required_var} (pid ${pid}); restarting it"
+        return 1
+      fi
+    done
+  done
+
+  return 0
+}
+
+metro_start_command() {
+  local metro_workers="$1" clear_arg="$2"
+  local quoted_port quoted_workers
+  quoted_port="$(shell_quote "$WATCHER_PORT")"
+  quoted_workers="$(shell_quote "$metro_workers")"
+  # No redirect here: the caller redirects the whole command to the log so that
+  # pre-exec output (env sourcing, set -e failures) is captured too, not just
+  # the bundler's own stdout.
+  cat <<EOF
+set -e
+set -a
+[ ! -f .js.env ] || . ./.js.env
+[ ! -f .env ] || . ./.env
+[ ! -f .env.local ] || . ./.env.local
+set +a
+export EXPO_NO_TYPESCRIPT_SETUP=1 WATCHER_PORT=${quoted_port} METRO_PORT=${quoted_port} METRO_MAX_WORKERS=${quoted_workers}
+exec yarn expo start --port ${quoted_port}${clear_arg}
+EOF
+}
+
+
+clear_stale_metro_listener() {
+  local pids
+  pids="$(metro_listener_pids)"
+  [ -n "$pids" ] || return 0
+  log "Clearing stale Metro listener on port ${WATCHER_PORT}: $pids"
+  # shellcheck disable=SC2086
+  kill $pids 2>/dev/null || true
+  for _ in $(seq 1 20); do
+    pids="$(metro_listener_pids)"
+    [ -z "$pids" ] && return 0
+    sleep 0.25
+  done
+  log "Metro listener still held on port ${WATCHER_PORT}; forcing: $pids"
+  # shellcheck disable=SC2086
+  kill -KILL $pids 2>/dev/null || true
+  for _ in $(seq 1 20); do
+    pids="$(metro_listener_pids)"
+    [ -z "$pids" ] && return 0
+    sleep 0.25
+  done
+  echo "mm-recipe: port ${WATCHER_PORT:-8081} is still occupied after killing stale Metro: $pids" >&2
+  return 1
+}
+
+
+start_metro_viewer_window() {
+  local metro_log_abs="$1"
+  local session window metro_tmux
+  command -v tmux >/dev/null 2>&1 || return 0
+  window="metro-${WATCHER_PORT}"
+  metro_tmux="$root/$(recipe_runtime_dir)/metro.tmux"
+  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 $(shell_quote "$metro_log_abs")"
+  printf '%s:%s\n' "$session" "$window" > "$metro_tmux"
+  log "Metro log viewer in tmux window ${session}:${window}"
+}
+
+default_metro_workers() {
+  if command -v sysctl >/dev/null 2>&1; then
+    local cores
+    cores="$(sysctl -n hw.perflevel0.physicalcpu 2>/dev/null || sysctl -n hw.physicalcpu 2>/dev/null || true)"
+    if [[ "$cores" =~ ^[0-9]+$ ]] && [ "$cores" -gt 0 ]; then
+      if [ "$cores" -gt 6 ]; then printf '6\n'; else printf '%s\n' "$cores"; fi
+      return 0
+    fi
+  fi
+  printf '4\n'
+}
+
+start_metro() {
+  init_context
+  if metro_ready; then
+    if [ "${MOBILE_METRO_CLEAR:-0}" = "1" ]; then
+      log "Restarting Metro on port ${WATCHER_PORT} with cleared cache (MOBILE_METRO_CLEAR=1)"
+      stop_metro
+    elif metro_listener_valid; then
+      log "Metro already running on port ${WATCHER_PORT}"
+      return 0
+    else
+      stop_metro
+    fi
+  fi
+  clear_stale_metro_listener
+  local metro_workers="${METRO_MAX_WORKERS:-$(default_metro_workers)}"
+  local runtime_dir="$(recipe_runtime_dir)"
+  local metro_log="$runtime_dir/metro.log"
+  local metro_log_abs="$root/$metro_log"
+  local metro_pid="$runtime_dir/metro.pid"
+  local tail_pid=""
+  local clear_arg=""
+  [ "${MOBILE_METRO_CLEAR:-0}" = "1" ] && clear_arg=" --clear"
+  local metro_cmd
+  metro_cmd="$(metro_start_command "$metro_workers" "$clear_arg")"
+  log "Starting Metro on port ${WATCHER_PORT} (METRO_MAX_WORKERS=${metro_workers}${MOBILE_METRO_CLEAR:+, clear=${MOBILE_METRO_CLEAR}})"
+  log "compact build events below (full log: ${metro_log}, recipe logs --full)"
+  # Metro runs detached writing to the log; the tmux window is a read-only tail viewer.
+  (
+    cd "$root"
+    mkdir -p "$(dirname "$metro_log")"
+    : > "$metro_log_abs"
+    bash -c "$metro_cmd" </dev/null > "$metro_log_abs" 2>&1 &
+    echo $! > "$metro_pid"
+  )
+  start_metro_viewer_window "$metro_log_abs"
+  if [ "$(recipe_log_ui_mode)" != "quiet" ]; then
+    node "$(recipe_log_tui_script)" watch \
+      --log "$metro_log_abs" \
+      --events "$(recipe_log_events_limit)" \
+      --mode "$(recipe_log_ui_mode)" \
+      --label "Metro bundler" \
+      --success-pattern 'Dev server ready' &
+    tail_pid=$!
+  fi
+  for _ in $(seq 1 90); do
+    if metro_ready; then
+      [ -n "$tail_pid" ] && kill "$tail_pid" 2>/dev/null && wait "$tail_pid" 2>/dev/null || true
+      log "Metro ready: http://localhost:${WATCHER_PORT}/status"
+      log "Metro log: $metro_log (tail with: recipe logs)"
+      return 0
+    fi
+    sleep 1
+  done
+  [ -n "$tail_pid" ] && kill "$tail_pid" 2>/dev/null && wait "$tail_pid" 2>/dev/null || true
+  node "$(recipe_log_tui_script)" events --log "$metro_log_abs" --events "$(recipe_log_events_limit)" >&2 || true
+  recipe_failure_playbook metro "Metro did not become ready on port ${WATCHER_PORT}" \
+    --prefix mm-recipe --log "$metro_log"
+  return 1
+}
+
+bundle_url() {
+  local platform="$1"
+  printf 'http://localhost:%s/index.bundle?platform=%s&dev=true&hot=false&lazy=true&transform.engine=hermes&transform.bytecode=1&transform.routerRoot=app&unstable_transformProfile=hermes-stable\n' \
+    "${WATCHER_PORT:-8081}" \
+    "$platform"
+}
+
+prewarm_bundle() {
+  local platform="$1"
+  local timeout="${MOBILE_BUNDLE_PREWARM_TIMEOUT:-900}"
+  local runtime_dir="$(recipe_runtime_dir)"
+  local metro_log="$root/$runtime_dir/metro.log"
+  local url bundle_pid elapsed=0 last_progress=""
+  [ "${MOBILE_BUNDLE_PREWARM:-1}" != "0" ] || { log "Skipping ${platform} bundle prewarm (MOBILE_BUNDLE_PREWARM=0)"; return 0; }
+  url="$(bundle_url "$platform")"
+  log "Prewarming ${platform} bundle before launching dev client (set MOBILE_BUNDLE_PREWARM=0 to skip)"
+  curl -sfL --connect-timeout 5 --max-time "$timeout" -o /dev/null "$url" &
+  bundle_pid=$!
+  while kill -0 "$bundle_pid" 2>/dev/null; do
+    local progress=""
+    if [ -f "$metro_log" ]; then
+      progress="$(grep -E "^[[:space:]]*(iOS|Android).*index\\.(js|tsx?).*%|Bundl(ed|ing)|Finished" "$metro_log" | tail -1 | tr -d '\r' || true)"
+    fi
+    if [ -n "$progress" ] && [ "$progress" != "$last_progress" ]; then
+      log "Bundle progress: $progress"
+      last_progress="$progress"
+    elif [ $((elapsed % 30)) -eq 0 ]; then
+      log "Waiting for ${platform} bundle (${elapsed}s/${timeout}s)${last_progress:+ — $last_progress}"
+    fi
+    if [ "$elapsed" -ge "$timeout" ]; then
+      kill "$bundle_pid" 2>/dev/null || true
+      wait "$bundle_pid" 2>/dev/null || true
+      echo "mm-recipe: ${platform} bundle did not become ready before launch timeout (${timeout}s)" >&2
+      tail -80 "$metro_log" >&2 || true
+      return 1
+    fi
+    sleep 3
+    elapsed=$((elapsed + 3))
+  done
+  if wait "$bundle_pid"; then
+    log "${platform} bundle ready"
+    return 0
+  fi
+  echo "mm-recipe: ${platform} bundle did not become ready before launch" >&2
+  tail -80 "$metro_log" >&2 || true
+  return 1
+}
+
+sim_target() { printf '%s\n' "${SIM_UDID:-${IOS_SIMULATOR:-booted}}"; }
+
+sim_udid_for_target() {
+  local target="$1"
+  if [[ "$target" =~ ^[0-9A-Fa-f-]{36}$ ]]; then
+    printf '%s\n' "$target"
+    return 0
+  fi
+  xcrun simctl list devices available | sed -n "s/.*${target} (\([0-9A-Fa-f-]*\)) (.*/\1/p" | head -1
+}
+
+
+ios_app_installed() {
+  local target="$1" bundle_id="$2"
+  xcrun simctl get_app_container "$target" "$bundle_id" app >/dev/null 2>&1
+}
+
+run_ios_native_build() {
+  local target="$1" reason="$2"
+  log "${reason}; installing with yarn start:ios (WATCHER_PORT=${WATCHER_PORT})"
+  (
+    cd "$root"
+    env WATCHER_PORT="$WATCHER_PORT" METRO_PORT="${METRO_PORT:-$WATCHER_PORT}" IOS_SIMULATOR="$target" EXPO_NO_TYPESCRIPT_SETUP=1 yarn start:ios
+  )
+}
+
+android_serial_args() {
+  if [ -n "${ADB_SERIAL:-${ANDROID_SERIAL:-${ANDROID_DEVICE:-}}}" ]; then
+    printf '%s\n' "-s" "${ADB_SERIAL:-${ANDROID_SERIAL:-${ANDROID_DEVICE}}}"
+  fi
+}
+
+android_app_installed() {
+  local package_id="$1"
+  local serial_args=()
+  # shellcheck disable=SC2207
+  serial_args=($(android_serial_args))
+  adb "${serial_args[@]}" shell pm path "$package_id" 2>/dev/null | grep -q '^package:'
+}
+
+run_android_native_build() {
+  local reason="$1"
+  local serial="${ADB_SERIAL:-${ANDROID_SERIAL:-${ANDROID_DEVICE:-}}}"
+  log "${reason}; installing with yarn start:android (WATCHER_PORT=${WATCHER_PORT}${serial:+, adb=${serial}})"
+  (
+    cd "$root"
+    env WATCHER_PORT="$WATCHER_PORT" METRO_PORT="${METRO_PORT:-$WATCHER_PORT}" \
+      ${serial:+ADB_SERIAL="$serial" ANDROID_SERIAL="$serial"} \
+      EXPO_NO_TYPESCRIPT_SETUP=1 yarn start:android
+  )
+}
+
+ensure_android_app_for_mode() {
+  local package_id="$1" mode="$2"
+  case "$mode" in
+    fast)
+      if android_app_installed "$package_id"; then
+        return 0
+      fi
+      cat >&2 <<EOF
+mm-recipe: fast mobile prepare requires an installed Android dev client (${package_id}).
+
+Fast mode only starts/reuses Metro, prewarms the JS bundle, opens the existing
+dev client, and waits for the bridge. Run with --preflight-mode auto or
+--preflight-mode rebuild-native when the native app needs to be installed.
+EOF
+      return 1
+      ;;
+    auto|default)
+      if android_app_installed "$package_id"; then
+        return 0
+      fi
+      run_android_native_build "Android dev client ${package_id} is not installed"
+      ;;
+    rebuild-native|clean)
+      run_android_native_build "Rebuilding Android dev client ${package_id} (--preflight-mode ${mode})"
+      ;;
+    *)
+      echo "mm-recipe: unknown mobile preflight mode: $mode" >&2
+      return 2
+      ;;
+  esac
+}
+
+ensure_ios_app_for_mode() {
+  local target="$1" bundle_id="$2" mode="$3"
+  case "$mode" in
+    fast)
+      if ios_app_installed "$target" "$bundle_id"; then
+        return 0
+      fi
+      cat >&2 <<EOF
+mm-recipe: fast mobile prepare requires an installed iOS dev client (${bundle_id}) on ${target}.
+
+Fast mode only starts/reuses Metro, prewarms the JS bundle, opens the existing
+dev client, and waits for the bridge. Run with --preflight-mode auto or
+--preflight-mode rebuild-native when the native app needs to be installed.
+EOF
+      return 1
+      ;;
+    auto|default)
+      if ios_app_installed "$target" "$bundle_id"; then
+        return 0
+      fi
+      run_ios_native_build "$target" "iOS dev client ${bundle_id} is not installed on ${target}"
+      ;;
+    rebuild-native|clean)
+      run_ios_native_build "$target" "Rebuilding iOS dev client ${bundle_id} on ${target} (--preflight-mode ${mode})"
+      ;;
+    *)
+      echo "mm-recipe: unknown mobile preflight mode: $mode" >&2
+      return 2
+      ;;
+  esac
+}
+
+show_simulator() {
+  local target="$1" udid=""
+  if [ "$target" = "booted" ]; then
+    log "Opening Simulator UI"
+    open -a Simulator >/dev/null 2>&1 || true
+    osascript -e 'tell application "Simulator" to activate' >/dev/null 2>&1 || true
+    return 0
+  fi
+  udid="$(sim_udid_for_target "$target")"
+  if [ -n "$udid" ]; then
+    log "Opening Simulator UI for ${target}"
+    open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+  else
+    log "Opening Simulator UI"
+    open -a Simulator >/dev/null 2>&1 || true
+  fi
+  osascript -e 'tell application "Simulator" to activate' >/dev/null 2>&1 || true
+}
+
+boot_simulator_if_needed() {
+  local target="$1" state=""
+  [ "$target" != "booted" ] || return 0
+  local line=""
+  line="$(xcrun simctl list devices available | grep -F "${target} (" | head -1 || true)"
+  case "$line" in *"(Booted)"*) state="Booted" ;; *"(Shutdown)"*) state="Shutdown" ;; esac
+  if [ "$state" = "Booted" ]; then return 0; fi
+  log "Booting iOS simulator ${target}${state:+ (${state})}"
+  xcrun simctl boot "$target" 2>/dev/null || true
+  xcrun simctl bootstatus "$target" -b >/dev/null
+}
+
+launch_ios() {
+  init_context
+  require_mobile_deps || return
+  ensure_mobile_harness_patched
+  start_metro || return
+  prewarm_bundle ios || return 1
+  local target url encoded bundle_id
+  target="$(sim_target)"
+  boot_simulator_if_needed "$target"
+  show_simulator "$target"
+  bundle_id="${IOS_BUNDLE_ID:-io.metamask.MetaMask}"
+  ensure_ios_app_for_mode "$target" "$bundle_id" "${MOBILE_PREFLIGHT_MODE:-fast}" || return $?
+  xcrun simctl spawn "$target" defaults write "$bundle_id" EXDevMenuIsOnboardingFinished -bool YES 2>/dev/null || true
+  encoded="$(python3 - <<PY
+import urllib.parse
+print(urllib.parse.quote('http://localhost:${WATCHER_PORT}?disableOnboarding=1', safe=''))
+PY
+)"
+  url="expo-metamask://expo-development-client/?url=${encoded}"
+  log "Launching iOS dev client on ${target}"
+  xcrun simctl openurl "$target" "$url"
+  log "Next: recipe logs   # tail Metro"
+  log "Next: recipe status # app route/account once loaded"
+}
+
+launch_android() {
+  init_context
+  require_mobile_deps || return
+  ensure_mobile_harness_patched
+  start_metro || return
+  prewarm_bundle android || return 1
+  local serial_args=() package_id encoded url
+  package_id="${ANDROID_PACKAGE_ID:-io.metamask}"
+  ensure_android_app_for_mode "$package_id" "${MOBILE_PREFLIGHT_MODE:-fast}" || return $?
+  # shellcheck disable=SC2207
+  serial_args=($(android_serial_args))
+  adb "${serial_args[@]}" reverse "tcp:${WATCHER_PORT}" "tcp:${WATCHER_PORT}" >/dev/null 2>&1 || true
+  encoded="$(python3 - <<PY
+import urllib.parse
+print(urllib.parse.quote('http://localhost:${WATCHER_PORT}?disableOnboarding=1', safe=''))
+PY
+)"
+  url="expo-metamask://expo-development-client/?url=${encoded}"
+  log "Launching Android dev client"
+  adb "${serial_args[@]}" shell am start -a android.intent.action.VIEW -d "$url" >/dev/null
+  log "Next: recipe logs   # tail Metro"
+  log "Next: recipe status # app route/account once loaded"
+}
+
+bridge_cmd() {
+  init_context
+  (cd "$root" && APP_ROOT="$root" node "$bridge" "$@")
+}
+
+report_open_debug() {
+  local payload="$1" want_json="$2"
+  if [ "$want_json" = true ]; then
+    printf '%s\n' "$payload"
+    return 0
+  fi
+  node - "$payload" <<'NODE'
+const [text] = process.argv.slice(2);
+try {
+  const v = JSON.parse(text);
+  if (v.ok) {
+    const detail = v.method ? ` via ${v.method}` : '';
+    const where = v.port ? ` (port ${v.port})` : '';
+    console.log(`mm-recipe: opened debugger${detail}${where}`);
+    if (v.target?.url) console.log(`mm-recipe: target ${v.target.url}`);
+    process.exit(0);
+  }
+  console.error(`mm-recipe: ${v.error || 'failed to open debugger'}`);
+  if (v.hint) console.error(`mm-recipe: ${v.hint}`);
+  process.exit(1);
+} catch (error) {
+  console.error(`mm-recipe: ${error.message}`);
+  process.exit(1);
+}
+NODE
+}
+
+_open_debug_ui() {
+  local action="$1"
+  shift
+  local want_json=false
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --json) want_json=true; shift ;;
+      -h|--help)
+        if [ "$action" = "dev-menu" ]; then
+          echo "Usage: mm-recipe dev-menu [--json]"
+        else
+          echo "Usage: mm-recipe debug [--json]"
+        fi
+        return 0
+        ;;
+      *) echo "mm-recipe debug: unknown arg: $1" >&2; return 2 ;;
+    esac
+  done
+  init_context
+  local payload exit_code=0
+  payload="$(node "$open_debug_script" --adapter mobile --port "${WATCHER_PORT:-8081}" --action "$action" --json 2>/dev/null)" || exit_code=$?
+  if [ "$exit_code" -eq 0 ]; then
+    report_open_debug "$payload" "$want_json"
+    return 0
+  fi
+  local fallback=""
+  fallback="$(node - "$payload" <<'NODE'
+const [text] = process.argv.slice(2);
+try {
+  const v = JSON.parse(text);
+  if (v.fallback) process.stdout.write(String(v.fallback));
+} catch {}
+NODE
+)"
+  if [ "$fallback" = "cdp-eval" ]; then
+    log "Metro HTTP failed; falling back to CDP eval"
+    case "$action" in
+      dev-menu)
+        if [ "$want_json" = true ]; then bridge_cmd eval "NativeModules?.DevSettings?.show?.() ?? 'not supported'"; else bridge_cmd eval "NativeModules?.DevSettings?.show?.() ?? 'not supported'" | pipe_pretty; fi
+        ;;
+      *)
+        if [ "$want_json" = true ]; then bridge_cmd eval "NativeModules?.DevSettings?.openDebugger?.() ?? 'not supported'"; else bridge_cmd eval "NativeModules?.DevSettings?.openDebugger?.() ?? 'not supported'" | pipe_pretty; fi
+        ;;
+    esac
+    return 0
+  fi
+  report_open_debug "$payload" "$want_json" || return 1
+}
+
+open_debug_ui() {
+  _open_debug_ui debug "$@"
+}
+
+open_dev_menu() {
+  _open_debug_ui dev-menu "$@"
+}
+
+fixture_password() {
+  init_context
+  node - "$root" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const root = process.argv[2];
+const runtimeDir = process.env.RECIPE_RUNTIME_DIR;
+if (!runtimeDir) throw new Error('RECIPE_RUNTIME_DIR is required');
+for (const rel of [`${runtimeDir}/wallet-fixture.json`]) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+    if (data.password) { process.stdout.write(String(data.password)); process.exit(0); }
+  } catch {}
+}
+process.exit(1);
+NODE
+}
+
+setup_wallet() {
+  init_context
+  local fixture="${1:-$(recipe_runtime_dir)/wallet-fixture.json}"
+  (cd "$root" && APP_ROOT="$root" "$setup_wallet_script" --fixture "$fixture")
+}
+
+setup_wallet_failure_recoverable() {
+  local setup_log="$1"
+  local metro_log="$root/$(recipe_runtime_dir)/metro.log"
+  grep -Eq 'CDP not reachable|Engine\.context\.KeyringController not available|Engine does not exist|Cannot read property '\''transactions'\''|bridge-not-ready|debug-target-missing' "$setup_log" 2>/dev/null && return 0
+  tail -200 "$metro_log" 2>/dev/null | grep -Eq 'Cannot read property '\''transactions'\''|Engine does not exist' && return 0
+  return 1
+}
+
+setup_wallet_with_runtime_recovery() {
+  init_context
+  local fixture="${1:-$(recipe_runtime_dir)/wallet-fixture.json}"
+  local platform="${2:-}"
+  local setup_log="$root/$(recipe_runtime_dir)/setup-wallet.last.log"
+  mkdir -p "$(dirname "$setup_log")"
+
+  if setup_wallet "$fixture" > "$setup_log" 2>&1; then
+    cat "$setup_log"
+    return 0
+  fi
+
+  local rc=$?
+  cat "$setup_log" >&2
+  if [ "${MOBILE_SETUP_CLEAN_RETRY:-1}" != "1" ] || ! setup_wallet_failure_recoverable "$setup_log"; then
+    return "$rc"
+  fi
+
+  log "Wallet setup failed during runtime startup; retrying once with a clean Metro cache for slot port ${WATCHER_PORT}"
+  stop_metro
+  case "$platform" in
+    ios) MOBILE_METRO_CLEAR=1 launch_ios ;;
+    android) MOBILE_METRO_CLEAR=1 launch_android ;;
+    *) MOBILE_METRO_CLEAR=1 refresh_mobile ;;
+  esac
+  if setup_wallet "$fixture" > "$setup_log" 2>&1; then
+    cat "$setup_log"
+    return 0
+  fi
+  rc=$?
+  cat "$setup_log" >&2
+  return "$rc"
+}
+
+screenshot() {
+  init_context
+  local out="${1:-temp/recipe-artifacts/screenshot-$(date -u +%Y%m%dT%H%M%SZ).png}"
+  mkdir -p "$root/$(dirname "$out")"
+  if [ -n "${ANDROID_DEVICE:-${ADB_SERIAL:-${ANDROID_SERIAL:-}}}" ]; then
+    local serial_args=()
+    [ -n "${ADB_SERIAL:-${ANDROID_SERIAL:-${ANDROID_DEVICE:-}}}" ] && serial_args=(-s "${ADB_SERIAL:-${ANDROID_SERIAL:-${ANDROID_DEVICE}}}")
+    adb "${serial_args[@]}" exec-out screencap -p > "$root/$out"
+  else
+    xcrun simctl io "$(sim_target)" screenshot "$root/$out" >/dev/null
+  fi
+  log "screenshot: $root/$out"
+}
+
+tail_logs() {
+  init_context
+  local log_file="$root/$(recipe_runtime_dir)/metro.log"
+  [ -f "$log_file" ] || { echo "mm-recipe: Metro log missing: $(recipe_runtime_dir)/metro.log. Start with: recipe ios|android" >&2; return 1; }
+  if full_logs_requested "$@"; then
+    log "full log: $(recipe_runtime_dir)/metro.log (Ctrl-C to stop)"
+    tail -f "$log_file"
+    return 0
+  fi
+  log "compact tail — full stream: recipe logs --full"
+  exec node "$(recipe_log_tui_script)" tail \
+    --log "$log_file" \
+    --events "$(recipe_log_events_limit)" \
+    --follow \
+    --mode compact
+}
+
+refresh_mobile() {
+  if [ -n "${ANDROID_DEVICE:-${ADB_SERIAL:-${ANDROID_SERIAL:-}}}" ]; then
+    launch_android
+  else
+    launch_ios
+  fi
+}
+
+status_home() {
+  init_context
+  if ! json_requested "$@"; then
+    recipe_instant_hint "checking mobile runtime..."
+    recipe_progress status start "probing Metro, bridge, and readiness"
+  fi
+  local rs_file="$root/$(recipe_runtime_dir)/runtime-status.json"
+  local harness_stale=false harness_root
+  harness_root="$(harness_root)"
+  mkdir -p "$root/$(recipe_runtime_dir)"
+  recipe_warn_harness_stale mobile "$root" "$harness_root" "$runner_root" && harness_stale=false || harness_stale=true
+  runtime_status --json > "$rs_file"
+  local home_args=(
+    --adapter mobile --target "$root" --runtime-dir "$(recipe_runtime_dir)"
+    --watcher-port "${WATCHER_PORT:-8081}"
+    --runtime-status-file "$rs_file"
+  )
+  [ "$harness_stale" = true ] && home_args+=(--harness-stale)
+  if json_requested "$@"; then
+    node "$(recipe_home_script)" "${home_args[@]}" --json
+  else
+    node "$(recipe_home_script)" "${home_args[@]}"
+  fi
+}
+
+show_ports() {
+  init_context
+  local slot_id="" runtime_json="$root/$(recipe_runtime_dir)/agentic-runtime.json"
+  if [ -f "$runtime_json" ]; then
+    slot_id="$(node - "$runtime_json" <<'NODE'
+const fs = require('fs');
+try {
+  const data = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  if (data.slotId) process.stdout.write(String(data.slotId));
+} catch {}
+NODE
+)"
+  fi
+  local args=(
+    --mode ports --adapter mobile --target "$root" --runtime-dir "$(recipe_runtime_dir)"
+    --watcher-port "${WATCHER_PORT:-8081}" --slot-id "${slot_id:-}"
+  )
+  if json_requested "$@"; then
+    node "$(recipe_home_script)" "${args[@]}" --json
+  else
+    node "$(recipe_home_script)" "${args[@]}"
+  fi
+}
+
+decision_field() {
+  node - "$1" "$2" <<'NODE'
+const [text, field] = process.argv.slice(2);
+try {
+  const value = JSON.parse(text);
+  const result = field.split('.').reduce((node, key) => node?.[key], value);
+  if (result !== undefined && result !== null) process.stdout.write(String(result));
+} catch {
+  process.exit(1);
+}
+NODE
+}
+
+runtime_decision_report() {
+  init_context
+  local metro_log="$root/$(recipe_runtime_dir)/metro.log"
+  "$runner" runtime-decision --adapter mobile --target "$root" \
+    --watcher-port "${WATCHER_PORT:-8081}" \
+    --metro-log "$metro_log" \
+    --platform "$(infer_mobile_platform)" \
+    "$@"
+}
+
+decision() {
+  init_context
+  run_json_pretty "$runner" runtime-decision --adapter mobile --target "$root" \
+    --watcher-port "${WATCHER_PORT:-8081}" \
+    --metro-log "$root/$(recipe_runtime_dir)/metro.log" \
+    --platform "$(infer_mobile_platform)" \
+    "$@"
+}
+
+run_mobile_install() {
+  init_context
+  log "Installing mobile dependencies (yarn setup)"
+  if ! (
+    cd "$root"
+    export PLATFORM="$(infer_mobile_platform)"
+    LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 yarn setup
+  ); then
+    echo "mm-recipe: yarn setup failed" >&2
+    return 1
+  fi
+  if metro_ready; then
+    log "Stopping Metro after yarn setup so the next launch rebundles with fresh deps"
+    stop_metro
+  fi
+  export MOBILE_METRO_CLEAR=1
+}
+
+record_mobile_deps_baseline() {
+  init_context
+  local metro_log="$root/$(recipe_runtime_dir)/metro.log"
+  if ! "$runner" runtime-decision --adapter mobile --target "$root" \
+    --watcher-port "${WATCHER_PORT:-8081}" \
+    --metro-log "$metro_log" \
+    --platform "$(infer_mobile_platform)" \
+    --record-baseline --json >/dev/null; then
+    log "failed to record mobile deps baseline"
+    return 1
+  fi
+}
+
+up_emit_json() {
+  local report="$1"
+  shift
+  if json_requested "$@"; then
+    printf '%s\n' "$report"
+  fi
+}
+
+up_final_json_report() {
+  runtime_decision_report --json --platform "$(infer_mobile_platform)"
+}
+
+do_up() {
+  init_context
+  local start=$SECONDS exit_code=0 report action metro_log
+  metro_log="$root/$(recipe_runtime_dir)/metro.log"
+  recipe_progress up start "evaluating mobile runtime"
+  report="$(runtime_decision_report --json)"
+  action="$(decision_field "$report" decision || true)"
+  if dry_run_requested "$@"; then
+    if json_requested "$@"; then
+      printf '%s\n' "$report"
+    else
+      printf '%s\n' "$report" | pipe_pretty
+    fi
+    case "$action" in
+      ready) log "dry-run: would wait for in-app bridge and show route/account" ;;
+      launch) log "dry-run: would start Metro + launch dev client ($(recipe_runtime_dir)/metro.log)" ;;
+      install) log "dry-run: would run yarn setup, then re-check" ;;
+      blocked|unknown|'') log "dry-run: blocked — inspect recipe status" ;;
+      *) log "dry-run: unsupported decision ($action)" ;;
+    esac
+    return 0
+  fi
+  if ! json_requested "$@"; then
+    printf '%s\n' "$report" | pipe_pretty
+  fi
+  case "$action" in
+    ready)
+      recipe_progress up bridge "waiting for in-app bridge"
+      wait_for_bridge || exit_code=$?
+      if [ "$exit_code" -eq 0 ]; then
+        record_mobile_deps_baseline || log "warning: deps baseline not recorded after bridge ready"
+        recipe_done up pass "mobile runtime ready" $((SECONDS - start))
+        up_emit_json "$(up_final_json_report)" "$@"
+        if ! json_requested "$@"; then
+          bridge_cmd status | pipe_pretty
+        fi
+        return 0
+      fi
+      recipe_done up fail "bridge not ready" $((SECONDS - start))
+      up_emit_json "$(up_final_json_report)" "$@"
+      recipe_failure_playbook up "bridge not ready" \
+        --prefix mm-recipe --log "$(recipe_runtime_dir)/metro.log"
+      return "$exit_code"
+      ;;
+    launch)
+      case "$(decision_field "$report" reasonCode || true)" in
+        native-module-stale) export MOBILE_PREFLIGHT_MODE=rebuild-native MOBILE_METRO_CLEAR=1 ;;
+        metro-stale-log|bundle-errors-recoverable) export MOBILE_METRO_CLEAR=1 ;;
+      esac
+      recipe_progress up metro "starting Metro and dev client"
+      refresh_mobile || {
+        recipe_done up fail "Metro/dev client launch failed" $((SECONDS - start))
+        up_emit_json "$(up_final_json_report)" "$@"
+        recipe_failure_playbook metro "Metro/dev client launch failed" \
+          --prefix mm-recipe --log "$(recipe_runtime_dir)/metro.log"
+        return $?
+      }
+      recipe_progress up bridge "waiting for in-app bridge"
+      wait_for_bridge || exit_code=$?
+      if [ "$exit_code" -eq 0 ]; then
+        record_mobile_deps_baseline || log "warning: deps baseline not recorded after bridge ready"
+        recipe_done up pass "mobile runtime ready" $((SECONDS - start))
+        up_emit_json "$(up_final_json_report)" "$@"
+        if ! json_requested "$@"; then
+          bridge_cmd status | pipe_pretty
+        fi
+        return 0
+      fi
+      recipe_done up fail "bridge not ready" $((SECONDS - start))
+      up_emit_json "$(up_final_json_report)" "$@"
+      recipe_failure_playbook up "bridge not ready" \
+        --prefix mm-recipe --log "$(recipe_runtime_dir)/metro.log"
+      return "$exit_code"
+      ;;
+    install)
+      if [ "${RECIPE_UP_INSTALL_ATTEMPTED:-0}" = "1" ]; then
+        report="$(runtime_decision_report --json)"
+        local reason_code
+        reason_code="$(decision_field "$report" reasonCode || true)"
+        recipe_done up fail "install did not resolve runtime (${reason_code:-install})" $((SECONDS - start))
+        up_emit_json "$report" "$@"
+        if ! json_requested "$@"; then
+          printf '%s\n' "$report" | pipe_pretty
+        fi
+        recipe_failure_playbook up "yarn setup completed but runtime-decision is still install" \
+          --prefix mm-recipe --log "$(recipe_runtime_dir)/metro.log"
+        return 2
+      fi
+      recipe_progress up install "installing dependencies"
+      export RECIPE_UP_INSTALL_ATTEMPTED=1
+      run_mobile_install || {
+        recipe_done up fail "yarn setup failed" $((SECONDS - start))
+        up_emit_json "$(up_final_json_report)" "$@"
+        return 1
+      }
+      record_mobile_deps_baseline || log "warning: deps baseline not recorded after yarn setup"
+      RECIPE_UP_INSTALL_ATTEMPTED=1 do_up "$@"
+      ;;
+    blocked|unknown|'')
+      recipe_done up fail "blocked (${action:-unknown})" $((SECONDS - start))
+      up_emit_json "$report" "$@"
+      recipe_failure_playbook up "blocked (${action:-unknown})" \
+        --prefix mm-recipe --log "$(recipe_runtime_dir)/metro.log"
+      return 2
+      ;;
+    *)
+      recipe_done up fail "unsupported decision: $action" $((SECONDS - start))
+      up_emit_json "$report" "$@"
+      recipe_failure_playbook up "unsupported decision: $action" \
+        --prefix mm-recipe --log "$(recipe_runtime_dir)/metro.log"
+      return 2
+      ;;
+  esac
+}
+
+stop_metro() {
+  init_context
+  local pids=""
+  local metro_pid="$root/$(recipe_runtime_dir)/metro.pid"
+  local metro_tmux="$root/$(recipe_runtime_dir)/metro.tmux"
+  local marker=""
+  [ -f "$metro_pid" ] && marker="$(cat "$metro_pid" 2>/dev/null || true)"
+  case "$marker" in
+    tmux:*)
+      # Back-compat: Metro started by a pre-upgrade binary stored the window here.
+      tmux kill-window -t "${marker#tmux:}" >/dev/null 2>&1 || true
+      ;;
+    tmux-session:*)
+      tmux kill-session -t "=${marker#tmux-session:}" >/dev/null 2>&1 || true
+      ;;
+    ''|*[!0-9]*)
+      ;;
+    *)
+      pids="$marker"
+      ;;
+  esac
+  if [ -f "$metro_tmux" ]; then
+    local viewer
+    viewer="$(cat "$metro_tmux" 2>/dev/null || true)"
+    [ -n "$viewer" ] && { log "Closing Metro log viewer ${viewer}"; tmux kill-window -t "$viewer" >/dev/null 2>&1 || true; }
+    rm -f "$metro_tmux"
+  fi
+  pids="$pids $(lsof -nP -iTCP:${WATCHER_PORT:-8081} -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' || true)"
+  if [ -n "$(printf '%s' "$pids" | tr -d ' ')" ]; then
+    log "Stopping Metro on port ${WATCHER_PORT}: $pids"
+    kill $pids 2>/dev/null || true
+    for _ in $(seq 1 20); do
+      pids="$(lsof -nP -iTCP:${WATCHER_PORT:-8081} -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' || true)"
+      [ -z "$pids" ] && break
+      sleep 0.25
+    done
+    if [ -n "$(printf '%s' "$pids" | tr -d ' ')" ]; then
+      log "Metro listener still held on port ${WATCHER_PORT}; forcing: $pids"
+      kill -KILL $pids 2>/dev/null || true
+    fi
+  else
+    log "No Metro listener on port ${WATCHER_PORT:-8081}"
+  fi
+  rm -f "$metro_pid"
+  log "next: recipe up | recipe ios | recipe android"
+}
+
+wait_for_bridge() {
+  init_context
+  local log_file="$root/$(recipe_runtime_dir)/bridge-status.log"
+  local metro_log="$root/$(recipe_runtime_dir)/metro.log"
+  mkdir -p "$(dirname "$log_file")"
+  local attempt max_polls
+  max_polls="${MOBILE_BRIDGE_READY_POLLS:-90}"
+  for attempt in $(seq 1 "$max_polls"); do
+    if bridge_cmd status > "$log_file" 2>&1 && node - "$log_file" <<'NODE'
+const fs = require('fs');
+const value = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const targets = Array.isArray(value) ? value : [value];
+if (!targets.some((target) => target && typeof target === 'object' && target.route)) process.exit(1);
+NODE
+    then
+      log "Mobile bridge ready"
+      return 0
+    fi
+    if [ "$attempt" = "1" ] || [ $((attempt % 5)) -eq 0 ]; then
+      log "Waiting for Mobile bridge (${attempt}/${max_polls}): $(bridge_wait_reason "$log_file" "$metro_log")"
+    fi
+    sleep 2
+  done
+  cat "$log_file" >&2 || true
+  recipe_failure_playbook up "bridge did not become ready on port ${WATCHER_PORT:-8081}" \
+    --prefix mm-recipe --log "$(recipe_runtime_dir)/metro.log"
+  return 1
+}
+
+bridge_wait_reason() {
+  local status_file="$1"
+  local metro_log="$2"
+  if ! metro_ready; then
+    printf 'Metro is not reachable on port %s' "${WATCHER_PORT:-8081}"
+    return 0
+  fi
+  local targets
+  targets="$(curl -sf --max-time 2 "http://localhost:${WATCHER_PORT:-8081}/json/list" 2>/dev/null || true)"
+  if [ "$targets" = "[]" ] || [ -z "$targets" ]; then
+    printf 'Metro is running; no React Native debug target yet'
+    bridge_bundle_progress "$metro_log"
+    return 0
+  fi
+  if [ -s "$status_file" ] && grep -qxF '[]' "$status_file"; then
+    printf 'React Native target is visible; in-app bridge is not ready yet'
+    bridge_bundle_progress "$metro_log"
+    return 0
+  fi
+  printf 'bridge probe failed'
+  bridge_bundle_progress "$metro_log"
+}
+
+bridge_bundle_progress() {
+  local metro_log="$1"
+  [ -f "$metro_log" ] || return 0
+  local progress
+  progress="$(grep -E '^[[:space:]]*(iOS|Android).*index\\.(js|tsx?).*%|Bundl(ed|ing)|Finished' "$metro_log" | tail -1 | tr -d '\r' || true)"
+  [ -n "$progress" ] && printf ' (%s)' "$progress"
+}
+
+runtime_status() {
+  local target="" port="" runtime_dir_arg=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --target) target="$2"; shift 2 ;;
+      --port|--cdp-port) port="$2"; shift 2 ;;
+      --runtime-dir) runtime_dir_arg="$2"; shift 2 ;;
+      --json) shift ;;
+      -h|--help)
+        echo "Usage: mm-recipe runtime-status [--target <repo>] [--port <port>] [--runtime-dir <dir>] [--json]"
+        return 0
+        ;;
+      *) echo "mm-recipe runtime-status: unknown arg: $1" >&2; return 2 ;;
+    esac
+  done
+  [ -n "$target" ] && cd "$target"
+  [ -n "$runtime_dir_arg" ] && export RECIPE_RUNTIME_DIR="$runtime_dir_arg"
+  [ -n "$port" ] && export WATCHER_PORT="$port" CDP_PORT="${CDP_PORT:-$port}"
+  init_context
+  local runtime_dir="$(recipe_runtime_dir)"
+  local runtime_abs="$root/$runtime_dir"
+  local status_file="$runtime_abs/runtime-status.json"
+  local metro_log="$runtime_abs/metro.log"
+  mkdir -p "$runtime_abs"
+  node - "$root" "$runtime_dir" "${WATCHER_PORT:-8081}" "$metro_log" "$bridge" "$status_file" <<'NODE'
+const fs = require('fs');
+const http = require('http');
+const cp = require('child_process');
+const [target, runtimeDir, port, metroLog, bridge, statusFile] = process.argv.slice(2);
+
+function get(path) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://localhost:${port}${path}`, { timeout: 1500 }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, body }));
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, body: '' }); });
+    req.on('error', () => resolve({ ok: false, body: '' }));
+  });
+}
+
+function bundleStatus() {
+  if (!fs.existsSync(metroLog)) return { phase: 'unknown', source: null };
+  const lines = fs.readFileSync(metroLog, 'utf8').split(/\r?\n/u).filter(Boolean);
+  const latest = [...lines].reverse().find((line) =>
+    /^\s*(iOS|Android).*index\.(js|tsx?).*%/u.test(line) ||
+    /Bundl(ed|ing)|Finished/u.test(line)
+  );
+  if (!latest) return { phase: 'unknown', source: metroLog };
+  const progress = /^(?:\s*)(iOS|Android).*?([0-9]+(?:\.[0-9]+)?)%/u.exec(latest);
+  if (progress) {
+    const percent = Number(progress[2]);
+    return {
+      phase: percent >= 100 ? 'bundled' : 'bundling',
+      platform: progress[1].toLowerCase(),
+      percent,
+      detail: latest.trim(),
+      source: metroLog,
+    };
+  }
+  return { phase: /Finished|Bundled/u.test(latest) ? 'bundled' : 'bundling', detail: latest.trim(), source: metroLog };
+}
+
+function bridgeStatus() {
+  try {
+    const out = cp.execFileSync(process.execPath, [bridge, 'status'], {
+      cwd: target,
+      env: { ...process.env, APP_ROOT: target, WATCHER_PORT: port },
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+    });
+    const value = JSON.parse(out || 'null');
+    const targets = Array.isArray(value) ? value : [value];
+    const readyTarget = targets.find((item) => item && typeof item === 'object' && item.route);
+    return { ready: Boolean(readyTarget), targetCount: targets.filter(Boolean).length, status: value, error: null };
+  } catch (error) {
+    return { ready: false, targetCount: 0, status: null, error: error.stderr?.toString?.() || error.message };
+  }
+}
+
+(async () => {
+  const metroRaw = await get('/status');
+  const metroReachable = metroRaw.ok && /packager-status:running/u.test(metroRaw.body);
+  const listRaw = await get('/json/list');
+  let targets = [];
+  let debugTargetError = null;
+  try {
+    targets = JSON.parse(listRaw.body || '[]');
+  } catch (error) {
+    debugTargetError = error.message;
+    targets = [];
+  }
+  if (!Array.isArray(targets)) {
+    debugTargetError = 'Metro /json/list did not return an array';
+    targets = [];
+  }
+  const bridge = bridgeStatus();
+  const bundle = bundleStatus();
+  const reason = !metroReachable
+    ? 'metro-down'
+    : targets.length === 0
+      ? (bundle.phase === 'bundling' ? 'bundle-in-progress' : 'debug-target-missing')
+      : !bridge.ready
+        ? 'bridge-not-ready'
+        : 'ready';
+  const status = {
+    schemaVersion: 1,
+    adapter: 'mobile',
+    target,
+    runtimeDir,
+    updatedAt: new Date().toISOString(),
+    ready: reason === 'ready',
+    reason,
+    metro: { reachable: metroReachable, port: Number(port) },
+    bundle,
+    debugTarget: { present: targets.length > 0, count: targets.length, error: debugTargetError },
+    bridge: { ready: bridge.ready, targetCount: bridge.targetCount, error: bridge.error, status: bridge.status },
+  };
+  fs.writeFileSync(statusFile, `${JSON.stringify(status, null, 2)}\n`);
+  console.log(JSON.stringify(status, null, 2));
+})();
+NODE
+}
+
+assert_runtime_ready() {
+  init_context
+  local status_json attempt max_polls
+  max_polls="${MOBILE_RUNTIME_READY_POLLS:-60}"
+  for attempt in $(seq 1 "$max_polls"); do
+    status_json="$(runtime_status --target "$root" --port "${WATCHER_PORT:-}" --runtime-dir "$(recipe_runtime_dir)" --json)"
+    if STATUS_JSON="$status_json" python3 -c 'import json, os, sys
+status = json.loads(os.environ["STATUS_JSON"])
+if status.get("ready"):
+    sys.exit(0)
+print(
+    "mm-recipe: runtime is not ready after prepare "
+    f"(reason={status.get('"'"'reason'"'"')}, metro={status.get('"'"'metro'"'"')}, "
+    f"debugTarget={status.get('"'"'debugTarget'"'"')}, bridge={status.get('"'"'bridge'"'"')})",
+    file=sys.stderr,
+)
+sys.exit(1)'
+    then
+      log "Runtime ready after prepare"
+      return 0
+    fi
+    if [ "$attempt" = "1" ] || [ $((attempt % 5)) -eq 0 ]; then
+      log "Waiting for runtime ready after prepare (${attempt}/${max_polls})"
+    fi
+    sleep 2
+  done
+  STATUS_JSON="$status_json" python3 -c 'import json, os, sys
+status = json.loads(os.environ["STATUS_JSON"])
+print(
+    "mm-recipe: runtime is not ready after prepare "
+    f"(reason={status.get('"'"'reason'"'"')}, metro={status.get('"'"'metro'"'"')}, "
+    f"debugTarget={status.get('"'"'debugTarget'"'"')}, bridge={status.get('"'"'bridge'"'"')})",
+    file=sys.stderr,
+)'
+  return 1
+}
+
+do_completion() {
+  local install_script="$runner_root/scripts/install-completions.sh"
+  bash "$install_script" "${1:-install}" "${@:2}"
+}
+
+do_sync() {
+  init_context
+  local start=$SECONDS farmslot_slot="" fixture_ready=false summary_file="" runtime_json=""
+  RECIPE_CLI_PREFIX=mm-recipe
+  recipe_progress sync start "refreshing mobile harness + fixture context"
+  runtime_json="$root/$(recipe_runtime_dir)/agentic-runtime.json"
+  if [ -f "$runtime_json" ]; then
+    farmslot_slot="$(node - "$runtime_json" <<'NODE'
+const fs = require('fs');
+try {
+  const data = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  if (data.slotId) process.stdout.write(String(data.slotId));
+} catch {}
+NODE
+)"
+  fi
+  [ -n "$farmslot_slot" ] || { [ -n "${slot:-}" ] && farmslot_slot="local-mobile-${slot}"; }
+  log "sync: refreshing harness scripts"
+  if ! install_mobile_harness; then
+    recipe_done sync fail "harness install failed" $((SECONDS - start))
+    return 1
+  fi
+  log "sync: canonicalizing wallet fixture"
+  if recipe_sync_wallet_fixture "$root" "$(recipe_runtime_dir)" "${CDP_PORT:-}" "" "$farmslot_slot"; then
+    fixture_ready=true
+    log "sync: fixture ready at $(recipe_runtime_dir)/wallet-fixture.json"
+  else
+    log "sync: fixture missing - create $(recipe_runtime_dir)/wallet-fixture.json"
+  fi
+  if recipe_check_harness_stale mobile "$root" "$(harness_root)" "$runner_root"; then
+    log "sync: warning - harness still reports stale after install"
+  else
+    log "sync: harness up to date"
+  fi
+  summary_file="$root/$(recipe_runtime_dir)/sync-summary.json"
+  node - "$summary_file" "$fixture_ready" <<'NODE'
+const fs = require('fs');
+const [file, fixtureReady] = process.argv.slice(2);
+fs.writeFileSync(file, `${JSON.stringify({
+  schemaVersion: 1,
+  adapter: 'mobile',
+  status: 'pass',
+  harnessRefreshed: true,
+  fixtureReady: fixtureReady === 'true',
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+  if json_requested "$@"; then
+    cat "$summary_file"
+  fi
+  if $fixture_ready; then
+    recipe_done sync pass "harness refreshed; fixture ready" $((SECONDS - start))
+  else
+    recipe_done sync pass "harness refreshed; fixture missing" $((SECONDS - start))
+  fi
+  return 0
+}
+
+prepare_mobile() {
+  local target="" platform="${PLATFORM:-ios}" port="${WATCHER_PORT:-${METRO_PORT:-}}" simulator="" adb_serial="" wallet_setup=false wallet_fixture="" runtime_dir="$(recipe_runtime_dir)" preflight_mode="${RECIPE_HARNESS_MOBILE_PREFLIGHT_MODE:-fast}"
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --target) target="$2"; shift 2 ;;
+      --platform) platform="$2"; shift 2 ;;
+      --preflight-mode|--mode) preflight_mode="$2"; shift 2 ;;
+      --port) port="$2"; shift 2 ;;
+      --simulator) simulator="$2"; shift 2 ;;
+      --adb-serial) adb_serial="$2"; shift 2 ;;
+      --runtime-dir) runtime_dir="$2"; shift 2 ;;
+      --wallet-setup) wallet_setup=true; shift ;;
+      --wallet-fixture) wallet_fixture="$2"; shift 2 ;;
+      -h|--help)
+        echo "Usage: mm-recipe prepare [--target <repo>] [--platform ios|android] [--preflight-mode fast|auto|default|rebuild-native|clean] [--port <port>] [--simulator <sim>] [--adb-serial <serial>] [--runtime-dir <dir>] [--wallet-setup] [--wallet-fixture <json>]"
+        return 0
+        ;;
+      *) echo "mm-recipe prepare: unknown arg: $1" >&2; return 2 ;;
+    esac
+  done
+  case "$preflight_mode" in fast|auto|default|rebuild-native|clean) ;; *) echo "mm-recipe prepare: unknown --preflight-mode: $preflight_mode" >&2; return 2 ;; esac
+  [ -n "$target" ] && cd "$target"
+  export RECIPE_RUNTIME_DIR="$runtime_dir"
+  export RECIPE_HARNESS_MOBILE_PREFLIGHT_MODE="$preflight_mode"
+  export MOBILE_PREFLIGHT_MODE="$preflight_mode"
+  [ -n "$port" ] && export WATCHER_PORT="$port" METRO_PORT="$port" CDP_PORT="${CDP_PORT:-$port}"
+  [ -n "$simulator" ] && export IOS_SIMULATOR="$simulator"
+  if [ -n "$adb_serial" ] && [ "$adb_serial" != "{{adb_serial}}" ]; then
+    export ADB_SERIAL="$adb_serial" ANDROID_SERIAL="$adb_serial"
+  fi
+  init_context
+  install_mobile_harness
+  case "$platform" in
+    ios) launch_ios ;;
+    android) launch_android ;;
+    *) echo "mm-recipe prepare: unknown platform: $platform" >&2; return 2 ;;
+  esac
+  wait_for_bridge
+  if $wallet_setup; then
+    setup_wallet_with_runtime_recovery "${wallet_fixture:-$(recipe_runtime_dir)/wallet-fixture.json}" "$platform"
+  fi
+  assert_runtime_ready
+}
+
+run_recipe() {
+  ensure_mobile_harness_patched
+  local recipe="$1"; shift
+  [ -f "$recipe" ] || { echo "mm-recipe: recipe not found: $recipe" >&2; exit 2; }
+  local out="$root/temp/recipe-artifacts/$(basename "$recipe" .json)-$(date -u +%Y%m%dT%H%M%SZ)"
+  log "root=$root port=${WATCHER_PORT:-?} sim=${IOS_SIMULATOR:-${ANDROID_DEVICE:-${ADB_SERIAL:-?}}} out=$out"
+  exec "$runner" run "$recipe" --adapter mobile --project-root "$root" --watcher-port "$WATCHER_PORT" --artifacts-dir "$out" "$@"
+}
+
+interactive() {
+  init_context
+  echo "mm-recipe (${root}, port=${WATCHER_PORT:-?}, sim=${IOS_SIMULATOR:-${ANDROID_DEVICE:-${ADB_SERIAL:-?}}})"
+  PS3='choose> '
+  select choice in status ports up refresh ios android logs runtime-status setup-wallet unlock accounts screenshot debug dev-menu doctor actions stop quit; do
+    case "$choice" in
+      status) status_home ;;
+      ports) show_ports ;;
+      up) do_up ;;
+      refresh) refresh_mobile ;;
+      ios) launch_ios ;;
+      android) launch_android ;;
+      logs) tail_logs ;;
+      runtime-status) runtime_status | pipe_pretty ;;
+      setup-wallet) setup_wallet_with_runtime_recovery ;;
+      unlock) bridge_cmd unlock "$(fixture_password)" ;;
+      accounts) bridge_cmd list-accounts | pipe_pretty ;;
+      screenshot) screenshot ;;
+      debug) open_debug_ui ;;
+      dev-menu) open_dev_menu ;;
+      doctor) run_json_pretty "$runner" doctor --adapter mobile --target "$root" ;;
+      actions) run_json_pretty "$runner" actions --adapter mobile ;;
+      stop) stop_metro ;;
+      quit|'') break ;;
+    esac
+    echo
+  done
+}
+
+cmd="${1:-status}"
+[ "$#" -gt 0 ] && shift
+case "$cmd" in
+  -h|--help) usage; exit 0 ;;
+  interactive|menu) interactive ;;
+  ports) show_ports "$@" ;;
+  up) do_up "$@" ;;
+  decision) decision "$@" ;;
+  sync) do_sync "$@" ;;
+  completion|complete) do_completion "$@" ;;
+  prepare) prepare_mobile "$@" ;;
+  runtime-status) runtime_status "$@" ;;
+  ios|start) launch_ios ;;
+  android) launch_android ;;
+  setup:ios) launch_ios; setup_wallet_with_runtime_recovery "$(recipe_runtime_dir)/wallet-fixture.json" ios ;;
+  setup:android) launch_android; setup_wallet_with_runtime_recovery "$(recipe_runtime_dir)/wallet-fixture.json" android ;;
+  refresh|reload|relaunch) refresh_mobile ;;
+  logs|tail) tail_logs "$@" ;;
+  status|home) status_home "$@" ;;
+  app-status|bridge-status) bridge_cmd status | pipe_pretty ;;
+  route|get-route) bridge_cmd get-route | pipe_pretty ;;
+  navigate) bridge_cmd navigate "$@" ;;
+  back|go-back) bridge_cmd go-back ;;
+  unlock) bridge_cmd unlock "${1:-$(fixture_password)}" ;;
+  setup-wallet|wallet-setup) setup_wallet_with_runtime_recovery "${1:-$(recipe_runtime_dir)/wallet-fixture.json}" ;;
+  accounts|list-accounts) bridge_cmd list-accounts | pipe_pretty ;;
+  select-account|switch-account) bridge_cmd switch-account "${1:?address required}" ;;
+  screenshot) screenshot "${1:-}" ;;
+  debug) open_debug_ui "$@" ;;
+  dev-menu|devmenu|menu) open_dev_menu "$@" ;;
+  stop) stop_metro ;;
+  actions) init_context; run_json_pretty "$runner" actions --adapter mobile "$@" ;;
+  doctor) init_context; run_json_pretty "$runner" doctor --adapter mobile --target "$root" "$@" ;;
+  run) recipe="${1:-}"; [ -n "$recipe" ] || { usage; exit 2; }; shift; run_recipe "$recipe" "$@" ;;
+  *.json) run_recipe "$cmd" "$@" ;;
+  *) echo "mm-recipe: unknown command or missing recipe: $cmd" >&2; usage; exit 2 ;;
+esac