@deeeed/metamask-harness 0.2.0 → 0.3.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' }));
 }

package/adapters/mobile/wait-for-bridge.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# wait-for-bridge — poll the CDP bridge until a route target is registered.
+#
+# Calls cdp-bridge.cjs status in a poll loop. Emits structured diagnostics on
+# each probe failure: Metro reachability, React Native target visibility, bundle
+# progress. Fails with non-zero if the bridge is not ready within the poll limit.
+#
+# Inputs:
+#   --target <metamask-mobile dir>  (default $PWD)
+#   --port <number>                 (default WATCHER_PORT env, else METRO_PORT, else 8081)
+#   --max-polls <n>                 (default MOBILE_BRIDGE_READY_POLLS env, else 90; 2s each = 180s)
+# Outputs:
+#   Progress on stderr; exit 0 bridge ready; 1 timeout.
+#
+# Single device op: wait for bridge readiness. Does not start Metro or open the dev client.
+set -uo pipefail
+
+TARGET="$PWD"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+MAX_POLLS="${MOBILE_BRIDGE_READY_POLLS:-90}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)     TARGET="$2"; shift 2 ;;
+    --port)       PORT="$2"; shift 2 ;;
+    --max-polls)  MAX_POLLS="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>]\n'
+      exit 0
+      ;;
+    *) printf 'wait-for-bridge: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+TARGET="$(cd "$TARGET" && pwd)"
+LOG_DIR="$TARGET/temp/recipe/runtime"
+mkdir -p "$LOG_DIR"
+
+BRIDGE_CJS="$(dirname "$0")/bridge-runtime/cdp-bridge.cjs"
+STATUS_LOG="$LOG_DIR/bridge-status.log"
+METRO_LOG="$LOG_DIR/metro.log"
+
+if [ ! -f "$BRIDGE_CJS" ]; then
+  printf 'wait-for-bridge: cdp-bridge.cjs not found at %s\n' "$BRIDGE_CJS" >&2
+  exit 1
+fi
+
+metro_ready() {
+  curl -sf --max-time 2 "http://localhost:${PORT}/status" 2>/dev/null | grep -q 'packager-status:running'
+}
+
+bundle_progress() {
+  local log="$1"
+  [ -f "$log" ] || return 0
+  local p
+  p="$(grep -E '^[[:space:]]*(iOS|Android).*index\.(js|tsx?).*%|Bundl(ed|ing)|Finished' "$log" 2>/dev/null | tail -1 | tr -d '\r' || true)"
+  [ -n "$p" ] && printf ' (%s)' "$p"
+}
+
+bridge_wait_reason() {
+  if ! metro_ready; then
+    printf 'Metro not reachable on port %s' "$PORT"
+    return
+  fi
+  local targets
+  targets="$(curl -sf --max-time 2 "http://localhost:${PORT}/json/list" 2>/dev/null || true)"
+  if [ "$targets" = "[]" ] || [ -z "$targets" ]; then
+    printf 'Metro running; no React Native debug target yet'
+    bundle_progress "$METRO_LOG"
+    return
+  fi
+  if [ -s "$STATUS_LOG" ] && grep -qxF '[]' "$STATUS_LOG"; then
+    printf 'React Native target visible; in-app bridge not ready yet'
+    bundle_progress "$METRO_LOG"
+    return
+  fi
+  printf 'bridge probe failed'
+  bundle_progress "$METRO_LOG"
+}
+
+bridge_has_route() {
+  (cd "$TARGET" && APP_ROOT="$TARGET" node "$BRIDGE_CJS" status > "$STATUS_LOG" 2>&1) \
+  && node - "$STATUS_LOG" <<'NODE'
+const fs = require('fs');
+try {
+  const value = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  const targets = Array.isArray(value) ? value : [value];
+  if (!targets.some((t) => t && typeof t === 'object' && t.route)) process.exit(1);
+} catch { process.exit(1); }
+NODE
+}
+
+for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
+  if bridge_has_route; then
+    printf 'Mobile bridge ready\n' >&2
+    exit 0
+  fi
+  if [ "$ATTEMPT" = "1" ] || [ $((ATTEMPT % 5)) -eq 0 ]; then
+    printf 'Waiting for Mobile bridge (%s/%s): %s\n' "$ATTEMPT" "$MAX_POLLS" "$(bridge_wait_reason)" >&2
+  fi
+  sleep 2
+done
+
+cat "$STATUS_LOG" >&2 || true
+printf 'wait-for-bridge: bridge did not become ready on port %s (%s polls × 2s = %ss)\n' \
+  "$PORT" "$MAX_POLLS" "$((MAX_POLLS * 2))" >&2
+printf '  Next: check %s — or run mm-harness app-status\n' "$STATUS_LOG" >&2
+exit 1

package/adapters/mobile/yarn-setup.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# yarn-setup — install node_modules for MetaMask Mobile.
+#
+# Inputs:  --target <metamask-mobile dir>  (default $PWD)
+# Outputs: yarn install output on stderr; exit 0 pass, 1 install failed, 2 bad args.
+#
+# Single device op: install node_modules. No other sequencing.
+set -euo pipefail
+
+TARGET="$PWD"
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)  TARGET="$2"; shift 2 ;;
+    -h|--help) printf 'Usage: yarn-setup.sh [--target <dir>]\n'; exit 0 ;;
+    *) printf 'yarn-setup: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+TARGET="$(cd "$TARGET" && pwd)"
+cd "$TARGET" && exec yarn setup

package/{orchestration/lib → adapters/shared}/cli-ux.sh

@@ -26,19 +26,15 @@ recipe_color() {
 }
 
 recipe_progress_script() {
-  printf '%s' "${RECIPE_PROGRESS_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/progress.mjs}"
-}
-
-recipe_home_script() {
-  printf '%s' "${RECIPE_HOME_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/cli-home.mjs}"
+  printf '%s' "${RECIPE_PROGRESS_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/src/progress.ts}"
 }
 
 recipe_log_tui_script() {
-  printf '%s' "${RECIPE_LOG_TUI_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/log-tui.mjs}"
+  printf '%s' "${RECIPE_LOG_TUI_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/adapters/shared/log-tui.mjs}"
 }
 
 recipe_version_script() {
-  printf '%s' "${RECIPE_VERSION_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/cli-version.mjs}"
+  printf '%s' "${RECIPE_VERSION_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/src/cli-version.ts}"
 }
 
 recipe_log_ui_mode() {
@@ -79,7 +75,7 @@ recipe_instant_hint() {
 
 recipe_progress() {
   local verb="$1" phase="$2" message="$3" elapsed="${4:-}"
-  local args=(emit --verb "$verb" --phase "$phase" --message "$message")
+  local args=(emit --command "$verb" --phase "$phase" --message "$message")
   [ -n "$elapsed" ] && args+=(--elapsed-ms "$elapsed")
   [ "${RECIPE_PROGRESS_JSON:-}" = "1" ] && args+=(--json)
   node "$(recipe_progress_script)" "${args[@]}" || true
@@ -87,7 +83,7 @@ recipe_progress() {
 
 recipe_done() {
   local verb="$1" status="$2" message="$3" elapsed="${4:-}"
-  local args=(done --verb "$verb" --status "$status" --message "$message")
+  local args=(done --command "$verb" --status "$status" --message "$message")
   [ -n "$elapsed" ] && args+=(--elapsed-ms "$elapsed")
   [ "${RECIPE_PROGRESS_JSON:-}" = "1" ] && args+=(--json)
   node "$(recipe_progress_script)" "${args[@]}" || true

package/{orchestration/lib → adapters/shared}/log-tui.mjs

@@ -4,7 +4,63 @@
  */
 import fs from 'node:fs';
 import { parseArgs } from 'node:util';
-import { color, colorLogEvent } from './cli-color.mjs';
+// Inline color helpers — self-contained so both the runner copy and any
+// installed copy work without an external module dependency.
+const STYLES = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  label: '\x1b[1;36m',
+  cmd: '\x1b[1m',
+  ok: '\x1b[1;32m',
+  warn: '\x1b[1;33m',
+  err: '\x1b[1;31m',
+  info: '\x1b[0;37m',
+  accent: '\x1b[1;35m',
+  path: '\x1b[2m',
+  comment: '\x1b[2m',
+  active: '\x1b[1m',
+};
+
+function colorEnabled(stream = process.stderr) {
+  if (process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0') {
+    return false;
+  }
+  if (process.env.RECIPE_NO_COLOR === '1') return false;
+  if (process.env.RECIPE_COLOR === '1' || process.env.FORCE_COLOR === '1') return true;
+  return Boolean(stream?.isTTY);
+}
+
+function color(style, text, { stream = process.stderr } = {}) {
+  const value = String(text);
+  if (!colorEnabled(stream)) return value;
+  const code = STYLES[style];
+  if (!code) return value;
+  return `${code}${value}${STYLES.reset}`;
+}
+
+function classifyLogEvent(event) {
+  const text = String(event || '');
+  if (/Module build failed|^ERROR in |BUILD FAILED|compiled with [1-9][0-9]* error/iu.test(text)) {
+    return 'err';
+  }
+  if (/compiled successfully|compiled with [0-9]+ warning|PASS runtime-launch|launch pass|verify pass|build complete/iu.test(text)) {
+    return 'ok';
+  }
+  if (/phase [0-9]\/[0-9]|prepare pipeline|snapshot|fixture:|dist-freshness|build-health/iu.test(text)) {
+    return 'label';
+  }
+  if (/webpack [0-9]+%|Bundl(ed|ing)|(iOS|Android).*%/iu.test(text)) {
+    return 'warn';
+  }
+  return 'info';
+}
+
+function colorLogEvent(event, { latest = false, stream = process.stderr } = {}) {
+  const style = classifyLogEvent(event);
+  const painted = color(style === 'label' ? 'label' : style, event, { stream });
+  return latest ? color('active', painted, { stream }) : painted;
+}
 
 const DEFAULT_EVENTS = 10;
 

package/{orchestration/lib → adapters/shared}/open-debug.mjs

@@ -115,16 +115,34 @@ function openUrl(url) {
   return null;
 }
 
+// CDP-eval fallback: invoke DevSettings native module directly via the bridge
+// when the Metro HTTP endpoint is unreachable or returns a non-OK response.
+// Used for both debug (openDebugger) and dev-menu (show).
+async function tryDevSettingsCdpFallback(numericPort, normalizedAction) {
+  const bridgePath = new URL('cdp-bridge.cjs', import.meta.url).pathname;
+  const expression =
+    normalizedAction === 'dev-menu'
+      ? 'NativeModules.DevSettings.show()'
+      : 'NativeModules.DevSettings.openDebugger()';
+  const result = spawnSync(process.execPath, [bridgePath, 'eval', expression], {
+    encoding: 'utf8',
+    env: { ...process.env, WATCHER_PORT: String(numericPort) },
+    timeout: 15000,
+  });
+  return result.status === 0;
+}
+
 async function openMobileDebugger(port, action, shouldOpen) {
   const normalizedAction = action === 'dev-menu' ? 'dev-menu' : 'debug';
-  const path = normalizedAction === 'dev-menu' ? '/open-dev-menu' : '/open-debugger';
+  const urlPath = normalizedAction === 'dev-menu' ? '/open-dev-menu' : '/open-debugger';
   const numericPort = Number.parseInt(String(port), 10);
   if (!Number.isInteger(numericPort) || numericPort <= 0) {
     return { ok: false, adapter: 'mobile', action: normalizedAction, error: 'invalid-port', port };
   }
 
+  let metroError = null;
   try {
-    const opened = await fetchOk(`http://127.0.0.1:${numericPort}${path}`, { method: 'POST' });
+    const opened = await fetchOk(`http://127.0.0.1:${numericPort}${urlPath}`, { method: 'POST' });
     if (opened) {
       return {
         ok: true,
@@ -135,16 +153,21 @@ async function openMobileDebugger(port, action, shouldOpen) {
         opened: shouldOpen,
       };
     }
+    metroError = 'metro-http-nok';
   } catch (error) {
+    metroError = error instanceof Error ? error.message : String(error);
+  }
+
+  // CDP-eval fallback via DevSettings native module.
+  const cdpOk = await tryDevSettingsCdpFallback(numericPort, normalizedAction);
+  if (cdpOk) {
     return {
-      ok: false,
+      ok: true,
       adapter: 'mobile',
       action: normalizedAction,
-      method: 'metro-http',
+      method: 'cdp-eval',
       port: numericPort,
-      error: error instanceof Error ? error.message : String(error),
-      hint: 'Metro may be down or the debug target is not ready. Try recipe refresh, then recipe runtime-status.',
-      fallback: 'cdp-eval',
+      opened: shouldOpen,
     };
   }
 
@@ -154,9 +177,8 @@ async function openMobileDebugger(port, action, shouldOpen) {
     action: normalizedAction,
     method: 'metro-http',
     port: numericPort,
-    error: 'metro-http-failed',
-    hint: 'Metro rejected the open-debugger request. Try recipe refresh, then recipe runtime-status.',
-    fallback: 'cdp-eval',
+    error: metroError,
+    hint: 'Metro may be down or the debug target is not ready. Check metro status and try again.',
   };
 }
 

package/{orchestration/lib → adapters/shared}/resolve-farmslot-ports.sh

@@ -142,3 +142,50 @@ apply_resolved_extension_ports() {
     esac
   done <<< "$resolved"
 }
+
+# Mobile slot defaults: derive Metro port + iOS simulator name from directory suffix.
+# Port formula: 8060 + N (slot 1 → 8061). iOS simulator: mm-N.
+# Mirrors the extension convention (6660+N / 9010+N) for multi-slot mobile farms.
+resolve_mobile_slot_defaults() {
+  local repo="$1" n
+  n="$(infer_extension_slot_suffix "$repo" || true)"
+  [ -n "$n" ] || return 1
+  printf 'WATCHER_PORT=%s\n' "$((8060 + n))"
+  printf 'IOS_SIMULATOR=mm-%s\n' "$n"
+  printf 'SLOT_ID=local-mobile-%s\n' "$n"
+}
+
+resolve_mobile_runtime_ports() {
+  local repo="${1:-.}"
+  if resolve_farmslot_ports_by_repo "$repo"; then
+    return 0
+  fi
+  resolve_mobile_slot_defaults "$repo"
+}
+
+apply_resolved_mobile_ports() {
+  local repo="${1:-.}" line key val from_pool=false resolved=""
+  if resolved="$(resolve_farmslot_ports_by_repo "$repo" 2>/dev/null)"; then
+    from_pool=true
+  elif resolved="$(resolve_mobile_slot_defaults "$repo" 2>/dev/null)"; then
+    from_pool=false
+  else
+    return 0
+  fi
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      WATCHER_PORT)
+        if [ "$from_pool" = true ] || [ -z "${WATCHER_PORT:-}" ]; then WATCHER_PORT="$val"; fi
+        ;;
+      IOS_SIMULATOR)
+        if [ "$from_pool" = true ] || [ -z "${IOS_SIMULATOR:-}" ]; then IOS_SIMULATOR="$val"; fi
+        ;;
+      SLOT_ID)
+        if [ "$from_pool" = true ] || [ -z "${RECIPE_SLOT_ID:-}" ]; then RECIPE_SLOT_ID="$val"; fi
+        ;;
+    esac
+  done <<< "$resolved"
+}