@deeeed/metamask-harness 0.33.3 → 0.34.1

package/adapters/mobile/start-metro.sh

@@ -2,9 +2,10 @@
 # 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).
+# Clears stale or foreign listeners before starting. Uses the checkout's canonical
+# yarn watch script and sets EXPO_NO_TYPESCRIPT_SETUP=1. Cache clearing is
+# injected as Expo --clear without invoking Mobile's global watchman cleanup.
+# Metro owns its default worker count; METRO_MAX_WORKERS is an explicit override.
 #
 # Inputs:
 #   --target <metamask-mobile dir>  (default $PWD)
@@ -49,7 +50,7 @@ fi
 # only ever inspect or signal a Metro listening on $PORT.
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/metro-listener.sh"
-MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID} MM_HARNESS_METRO_PROJECT_ROOT EXPO_OVERRIDE_METRO_CONFIG"
+MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID METAMASK_BUILD_TYPE METAMASK_ENVIRONMENT}"
 
 # RECIPE_RUNTIME_DIR (relative, validated) makes runtime state per-run so jobs
 # sharing one checkout do not collide on metro.log / metro.pid / metro.tmux.
@@ -57,39 +58,90 @@ LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
 mkdir -p "$LOG_DIR"
 LOG_FILE="$LOG_DIR/metro.log"
 PID_FILE="$LOG_DIR/metro.pid"
-INLINE_ENV_FILE="$LOG_DIR/metro-inline-env.sh"
+METRO_BUILD_ENV_FILE="$LOG_DIR/metro-build-env.sh"
 
 # --- helpers ------------------------------------------------------------------
 
-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"
+write_metro_build_env() {
+  local temporary name staged_name product_values build_type environment sentry_dsn clear_value=0
+  for name in $MOBILE_METRO_REQUIRED_ENV; do
+    if ! printf '%s' "$name" | grep -Eq '^[A-Za-z_][A-Za-z0-9_]*$'; then
+      printf 'start-metro: invalid required environment variable name: %s\n' "$name" >&2
+      return 1
+    fi
+  done
+  temporary="$(mktemp "$LOG_DIR/.metro-build-env.XXXXXX")" || return 1
+  chmod 600 "$temporary" || { rm -f "$temporary"; return 1; }
+  product_values="$(
+    cd "$TARGET" || exit 1
+    set -a
+    # shellcheck disable=SC1091
+    [ ! -f .js.env ] || eval "$(tr -d '\r' < .js.env)"
+    set +a
+    METAMASK_BUILD_TYPE="${METAMASK_BUILD_TYPE:-main}"
+    METAMASK_ENVIRONMENT="${METAMASK_ENVIRONMENT:-dev}"
+    printf 'build_type=%q\n' "$METAMASK_BUILD_TYPE"
+    printf 'environment=%q\n' "$METAMASK_ENVIRONMENT"
+    printf 'sentry_dsn=%q\n' "${MM_SENTRY_DSN:-${MM_SENTRY_DSN_DEV:-}}"
+    for name in $MOBILE_METRO_REQUIRED_ENV; do
+      printf 'required_%s=%q\n' "$name" "${!name-}"
+    done
+  )" || { rm -f "$temporary"; return 1; }
+  eval "$product_values"
+  [ "$CLEAR" = true ] && clear_value=1
+  {
+    printf 'export MM_HARNESS_METRO_WATCHER_PORT=%q\n' "$PORT"
+    printf 'export MM_HARNESS_METRO_BUILD_TYPE=%q\n' "$build_type"
+    printf 'export MM_HARNESS_METRO_ENVIRONMENT=%q\n' "$environment"
+    printf 'export MM_HARNESS_METRO_SENTRY_DSN=%q\n' "$sentry_dsn"
+    printf 'export MM_HARNESS_METRO_CLEAR=%q\n' "$clear_value"
+    cat <<'BUILD_ENV'
+mm_harness_restore_metro_env() {
+  export WATCHER_PORT="$MM_HARNESS_METRO_WATCHER_PORT"
+  export METRO_PORT="$MM_HARNESS_METRO_WATCHER_PORT"
+  export METAMASK_BUILD_TYPE="$MM_HARNESS_METRO_BUILD_TYPE"
+  export METAMASK_ENVIRONMENT="$MM_HARNESS_METRO_ENVIRONMENT"
+  export MM_SENTRY_DSN="$MM_HARNESS_METRO_SENTRY_DSN"
+BUILD_ENV
+    for name in $MOBILE_METRO_REQUIRED_ENV; do
+      staged_name="required_$name"
+      printf '  export %s=%q\n' "$name" "${!staged_name}"
+    done
+    for name in \
+      SEGMENT_PROXY_URL \
+      SEGMENT_WRITE_KEY \
+      SEGMENT_FLUSH_INTERVAL \
+      SEGMENT_FLUSH_EVENT_LIMIT
+    do
+      if declare -p "$name" >/dev/null 2>&1; then
+        printf '  export %s=%q\n' "$name" "${!name}"
+      fi
+    done
+    cat <<'BUILD_ENV'
+}
+eval() {
+  builtin eval "$@"
+  local status=$?
+  mm_harness_restore_metro_env
+  return "$status"
+}
+source() {
+  builtin source "$@"
+  local status=$?
+  mm_harness_restore_metro_env
+  return "$status"
+}
+yarn() {
+  if [ "$MM_HARNESS_METRO_CLEAR" = 1 ] && [ "${1:-}" = expo ] && [ "${2:-}" = start ]; then
+    command yarn "$@" --clear
   else
-    printf '4\n'
+    command yarn "$@"
   fi
 }
-
-write_inline_metro_env() {
-  local temporary name
-  temporary="$(mktemp "$LOG_DIR/.metro-inline-env.XXXXXX")" || return 1
-  chmod 600 "$temporary" || { rm -f "$temporary"; return 1; }
-  for name in \
-    SEGMENT_PROXY_URL \
-    SEGMENT_WRITE_KEY \
-    SEGMENT_FLUSH_INTERVAL \
-    SEGMENT_FLUSH_EVENT_LIMIT
-  do
-    if declare -p "$name" >/dev/null 2>&1; then
-      printf 'export %s=%q\n' "$name" "${!name}" >> "$temporary" \
-        || { rm -f "$temporary"; return 1; }
-    fi
-  done
-  mv -f "$temporary" "$INLINE_ENV_FILE"
+mm_harness_restore_metro_env
+BUILD_ENV
+  } > "$temporary" || { rm -f "$temporary"; return 1; }
+  mv -f "$temporary" "$METRO_BUILD_ENV_FILE"
 }
 
 # Log-tail viewer window (session-safe): sourced so its run-owned-session rule is
@@ -99,37 +151,20 @@ write_inline_metro_env() {
 
 write_metro_runner() {
   local runner="$1"
-  local clear_flag=""
-  [ "$CLEAR" = true ] && clear_flag=' --clear'
+  local watcher_script="watch"
+  local worker_env_line='unset METRO_MAX_WORKERS'
+  if [ -n "$METRO_WORKERS" ]; then
+    worker_env_line="export METRO_MAX_WORKERS=$(printf '%q' "$METRO_WORKERS")"
+  fi
   cat > "$runner" <<EOF
 #!/usr/bin/env bash
 set -uo pipefail
 cd "$(printf '%q' "$TARGET")"
 : > "$(printf '%q' "$LOG_FILE")"
-set -a
-[ ! -f .js.env ]    || . ./.js.env
-[ ! -f .env ]       || . ./.env
-[ ! -f .env.local ] || . ./.env.local
-set +a
-[ -n "\${METAMASK_BUILD_TYPE:-}" ] || export METAMASK_BUILD_TYPE=main
-# build.sh remaps MM_SENTRY_DSN from MM_SENTRY_DSN_DEV for dev builds; quick-launch
-# bypasses it, so without this Sentry never initializes in the dev client.
-[ -n "\${MM_SENTRY_DSN:-}" ] || export MM_SENTRY_DSN="\${MM_SENTRY_DSN_DEV:-}"
-[ ! -f $(printf '%q' "$INLINE_ENV_FILE") ] || {
-  . $(printf '%q' "$INLINE_ENV_FILE")
-  rm -f $(printf '%q' "$INLINE_ENV_FILE")
-}
 export EXPO_NO_TYPESCRIPT_SETUP=1
 export WATCHER_PORT="$(printf '%q' "$PORT")" METRO_PORT="$(printf '%q' "$PORT")"
-export METRO_MAX_WORKERS="$(printf '%q' "$METRO_WORKERS")"
-export MM_HARNESS_METRO_PROJECT_ROOT="$(printf '%q' "$TARGET")"
-if [ -n "\${EXPO_OVERRIDE_METRO_CONFIG:-}" ]; then
-  export MM_HARNESS_METRO_BASE_CONFIG="\$EXPO_OVERRIDE_METRO_CONFIG"
-else
-  export MM_HARNESS_METRO_BASE_CONFIG=$(printf '%q' "$TARGET/metro.config.js")
-fi
-export EXPO_OVERRIDE_METRO_CONFIG="$(printf '%q' "$SCRIPT_DIR/metro-config.cjs")"
-yarn expo start --port "$(printf '%q' "$PORT")"$clear_flag 2>&1 | tee -a "$(printf '%q' "$LOG_FILE")"
+$worker_env_line
+BASH_ENV=$(printf '%q' "$METRO_BUILD_ENV_FILE") command yarn $(printf '%q' "$watcher_script") 2>&1 | tee -a "$(printf '%q' "$LOG_FILE")"
 EOF
   chmod +x "$runner"
 }
@@ -180,64 +215,61 @@ fi
 
 stop_metro_listener || exit 1
 
-METRO_WORKERS="${METRO_MAX_WORKERS:-$(default_metro_workers)}"
+METRO_WORKERS="${METRO_MAX_WORKERS:-}"
+if [ -n "$METRO_WORKERS" ] && ! printf '%s' "$METRO_WORKERS" | grep -Eq '^[1-9][0-9]*$'; then
+  printf 'start-metro: METRO_MAX_WORKERS must be a positive integer, got %s\n' "$METRO_WORKERS" >&2
+  exit 2
+fi
+READY_TIMEOUT="${MOBILE_METRO_READY_TIMEOUT_SECONDS:-180}"
+if ! printf '%s' "$READY_TIMEOUT" | grep -Eq '^[1-9][0-9]*$'; then
+  printf 'start-metro: MOBILE_METRO_READY_TIMEOUT_SECONDS must be a positive integer, got %s\n' "$READY_TIMEOUT" >&2
+  exit 2
+fi
 CLEAR_LABEL=""
 [ "$CLEAR" = true ] && CLEAR_LABEL=", clear"
 
-printf 'Starting Metro on port %s (workers=%s%s)\n' \
-  "$PORT" "$METRO_WORKERS" "$CLEAR_LABEL" >&2
+if [ -n "$METRO_WORKERS" ]; then
+  printf 'Starting Metro on port %s (workers=%s%s)\n' \
+    "$PORT" "$METRO_WORKERS" "$CLEAR_LABEL" >&2
+else
+  printf 'Starting Metro on port %s (workers=Metro default%s)\n' \
+    "$PORT" "$CLEAR_LABEL" >&2
+fi
 printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FILE" >&2
 
-write_inline_metro_env || {
-  printf 'start-metro: could not stage inline Metro environment\n' >&2
+write_metro_build_env || {
+  printf 'start-metro: could not stage the scoped Metro environment\n' >&2
   exit 1
 }
 
-if ! start_metro_tmux; then
+STARTED_METRO_PID=""
+STARTED_METRO_TMUX=""
+if start_metro_tmux; then
+  STARTED_METRO_TMUX="$(cat "$LOG_DIR/metro.tmux" 2>/dev/null || true)"
+else
   # 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
-    # The quick-launch runs `expo start` directly, bypassing scripts/build.sh which
-    # passes the build type as an argument (start:ios = build.sh ios main dev). The
-    # fixture .js.env ships METAMASK_BUILD_TYPE="" (empty), which Metro's transform
-    # rejects. Default to the main dev client (what runway installs / launch targets)
-    # so already-installed slots work without re-syncing fixtures.
-    [ -n "${METAMASK_BUILD_TYPE:-}" ] || export METAMASK_BUILD_TYPE=main
-    # build.sh remaps MM_SENTRY_DSN from MM_SENTRY_DSN_DEV for dev builds (start:ios
-    # = build.sh ios main dev); quick-launch bypasses build.sh, so without this the
-    # dev client's MM_SENTRY_DSN stays empty and Sentry never initializes.
-    [ -n "${MM_SENTRY_DSN:-}" ] || export MM_SENTRY_DSN="${MM_SENTRY_DSN_DEV:-}"
-    [ ! -f "$INLINE_ENV_FILE" ] || {
-      # shellcheck disable=SC1090
-      . "$INLINE_ENV_FILE"
-      rm -f "$INLINE_ENV_FILE"
-    }
     export EXPO_NO_TYPESCRIPT_SETUP=1
     export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
-    export METRO_MAX_WORKERS="${METRO_WORKERS}"
-    export MM_HARNESS_METRO_PROJECT_ROOT="$TARGET"
-    export MM_HARNESS_METRO_BASE_CONFIG="${EXPO_OVERRIDE_METRO_CONFIG:-$TARGET/metro.config.js}"
-    export EXPO_OVERRIDE_METRO_CONFIG="$SCRIPT_DIR/metro-config.cjs"
+    if [ -n "$METRO_WORKERS" ]; then
+      export METRO_MAX_WORKERS="${METRO_WORKERS}"
+    else
+      unset METRO_MAX_WORKERS
+    fi
     launcher_args=(
       --target "$TARGET"
       --port "$PORT"
       --log "$LOG_FILE"
       --pid-file "$PID_FILE"
-      --workers "$METRO_WORKERS"
+      --build-env "$METRO_BUILD_ENV_FILE"
     )
+    [ -z "$METRO_WORKERS" ] || launcher_args+=(--workers "$METRO_WORKERS")
     [ "$CLEAR" = true ] && launcher_args+=(--clear)
     node "$SCRIPT_DIR/launch-metro.cjs" "${launcher_args[@]}"
   ) || exit 1
+  STARTED_METRO_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
 
   start_viewer_window "$LOG_FILE"
 fi
@@ -256,9 +288,11 @@ if [ -f "$LOG_TUI" ] && command -v node >/dev/null 2>&1 \
   TAIL_PID=$!
 fi
 
-# Ready-poll: 90 × 1s = 90 s timeout.
+# Cold main bundles can spend more than 90 seconds initializing Metro before the
+# status listener opens. Keep the wait bounded, but do not trigger a duplicate
+# recovery process while the checkout-owned launch is still making progress.
 READY=false
-for _i in $(seq 1 90); do
+for _i in $(seq 1 "$READY_TIMEOUT"); do
   if metro_ready; then
     READY=true
     break
@@ -277,12 +311,50 @@ if [ "$READY" = true ]; then
   exit 0
 fi
 
+cleanup_timed_out_metro() {
+  local pid pgid i group_alive=false owned_listener_alive=false listener_pid command
+  pid="$STARTED_METRO_PID"
+  # launch-metro creates a detached group whose PGID equals its initial child
+  # PID. The leader can exit before Expo, so probe the group rather than the PID.
+  pgid="$pid"
+  if [ -n "$pgid" ] && kill -0 -- "-$pgid" 2>/dev/null; then
+    printf 'start-metro: stopping timed-out Metro process group %s\n' "$pgid" >&2
+    kill -TERM -- "-$pgid" 2>/dev/null || true
+    for i in $(seq 1 20); do
+      kill -0 -- "-$pgid" 2>/dev/null || break
+      sleep 0.25
+    done
+    if kill -0 -- "-$pgid" 2>/dev/null; then
+      kill -KILL -- "-$pgid" 2>/dev/null || true
+      for i in $(seq 1 20); do
+        kill -0 -- "-$pgid" 2>/dev/null || break
+        sleep 0.25
+      done
+    fi
+    kill -0 -- "-$pgid" 2>/dev/null && group_alive=true
+  fi
+  if [ -n "$STARTED_METRO_TMUX" ] && command -v tmux >/dev/null 2>&1; then
+    tmux kill-window -t "$STARTED_METRO_TMUX" >/dev/null 2>&1 || true
+  fi
+  for listener_pid in $(metro_listener_pids); do
+    command="$(ps eww -p "$listener_pid" -o command= 2>/dev/null || true)"
+    case "$command" in *"$TARGET"*) owned_listener_alive=true ;; esac
+  done
+  if [ "$group_alive" = true ] || [ "$owned_listener_alive" = true ]; then
+    printf 'start-metro: timed-out checkout-owned process is still alive; retaining launch metadata for recovery\n' >&2
+    return 1
+  fi
+  rm -f "$PID_FILE" "$LOG_DIR/metro-launch.json" "$LOG_DIR/metro-build-env.sh" "$LOG_DIR/metro.tmux"
+  return 0
+}
+
 # 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
+cleanup_timed_out_metro || true
+printf 'start-metro: Metro did not become ready on port %s within %ss\n' "$PORT" "$READY_TIMEOUT" >&2
 printf '  Next: check %s for errors, or run mm-harness logs\n' "$LOG_FILE" >&2
 exit 1

package/adapters/mobile/stop-metro.sh

@@ -62,6 +62,7 @@ fi
 set +e
 rm -f "$PID_FILE"
 rm -f "$LOG_DIR/metro-launch.json"
+rm -f "$LOG_DIR/metro-build-env.sh"
 
 # start-metro runs a per-checkout console-forwarder holding the device debugger
 # slot; Metro going down must take it too, or the orphan keeps polling and later

package/dist/adapters/mobile/prepare.js

@@ -60,6 +60,20 @@ async function prepareMobile(target, opts = {}) {
     return { status: EXIT.runtime, output: msg };
   }
   const iosAccessibilityChanged = platform === "ios" && report.decision !== "unknown" && enableIosAccessibility(json);
+  if (report.decision === "ready" && clearMetro) {
+    const launch = await dispatchActionSequence(
+      withAppRestart(
+        launchActions(path.resolve(target), true),
+        restartApp || iosAccessibilityChanged
+      ),
+      target,
+      platform,
+      json,
+      preflightMode,
+      opts.watcherPort
+    );
+    return launch.status === 0 ? startMobileConsoleForwarder(target, platform, json, opts.watcherPort) : launch;
+  }
   if (report.decision === "ready") {
     if (restartApp || iosAccessibilityChanged) {
       const launch2 = await dispatchActionSequence(

package/dist/adapters/mobile/video-recorder.js

@@ -0,0 +1,284 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  ANDROID_RECORDING_TARGET_PREFIX,
+  IOS_SIMULATOR_RECORDING_TARGET_PREFIX
+} from "../../recording-target.js";
+const RECORDING_START_TIMEOUT_MS = 5e3;
+const RECORDING_STOP_TIMEOUT_MS = 1e4;
+const RECORDING_TIME_LIMIT_SECONDS = 0;
+function androidScreenrecordArgs(remotePath) {
+  return [
+    "shell",
+    "screenrecord",
+    "--time-limit",
+    String(RECORDING_TIME_LIMIT_SECONDS),
+    remotePath
+  ];
+}
+function createAndroidVideoRecorder(serial) {
+  return {
+    name: "adb-screenrecord",
+    platform: "android",
+    doctor: async () => doctorAndroidRecorder(serial),
+    start: (request) => startAndroidRecording(serial, request)
+  };
+}
+function createIosSimulatorVideoRecorder(simulator) {
+  return {
+    name: "simctl-recordVideo",
+    platform: "ios",
+    doctor: async () => doctorIosSimulatorRecorder(simulator),
+    start: (request) => startIosSimulatorRecording(simulator, request)
+  };
+}
+function doctorIosSimulatorRecorder(simulator) {
+  const state = runSimctl(["getenv", simulator, "SIMULATOR_UDID"]);
+  if (state.status !== 0 || !state.stdout.trim()) {
+    return {
+      ok: false,
+      code: "ios_simulator_unavailable",
+      message: `iOS simulator ${simulator} is not booted: ${commandFailure(state)}`,
+      suggestedFix: `Boot ${simulator} and run xcrun simctl getenv ${simulator} SIMULATOR_UDID.`
+    };
+  }
+  return {
+    ok: true,
+    code: "ok",
+    message: `iOS simulator recording is ready on ${simulator}.`
+  };
+}
+async function startIosSimulatorRecording(simulator, request) {
+  const targetSimulator = iosTargetSimulator(request);
+  if (targetSimulator !== simulator) {
+    throw new Error(
+      `iOS recording target ${targetSimulator ?? "<missing>"} does not match selected simulator ${simulator}.`
+    );
+  }
+  fs.mkdirSync(path.dirname(request.outputPath), { recursive: true });
+  const child = spawn(
+    "xcrun",
+    [
+      "simctl",
+      "io",
+      simulator,
+      "recordVideo",
+      "--codec=h264",
+      "--force",
+      request.outputPath
+    ],
+    { stdio: ["ignore", "pipe", "pipe"] }
+  );
+  const output = [];
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => output.push(String(chunk)));
+  child.stderr?.on("data", (chunk) => output.push(String(chunk)));
+  await waitForIosRecordingStart(child, output);
+  let stopped = false;
+  return {
+    async stop() {
+      if (stopped) {
+        throw new Error(
+          `iOS simulator recording on ${simulator} was already stopped.`
+        );
+      }
+      stopped = true;
+      child.kill("SIGINT");
+      await waitForChildExit(
+        child,
+        RECORDING_STOP_TIMEOUT_MS,
+        "iOS simulator recordVideo"
+      );
+      const recorded = fs.statSync(request.outputPath);
+      if (!recorded.isFile() || recorded.size <= 0) {
+        throw new Error(
+          `iOS simulator recording output is empty: ${request.outputPath}`
+        );
+      }
+      return {
+        recorder: {
+          name: "simctl-recordVideo",
+          platform: "ios",
+          target: { selector: "simulator", value: simulator }
+        }
+      };
+    }
+  };
+}
+function doctorAndroidRecorder(serial) {
+  const state = runAdb(serial, ["get-state"]);
+  if (state.status !== 0 || state.stdout.trim() !== "device") {
+    return {
+      ok: false,
+      code: "android_device_unavailable",
+      message: `Android device ${serial} is not ready: ${commandFailure(state)}`,
+      suggestedFix: `Run adb -s ${serial} get-state and reconnect or unlock the device.`
+    };
+  }
+  const screenrecord = runAdb(serial, ["shell", "screenrecord", "--help"]);
+  if (screenrecord.status !== 0) {
+    return {
+      ok: false,
+      code: "android_screenrecord_unavailable",
+      message: `Android screenrecord is unavailable on ${serial}: ${commandFailure(screenrecord)}`,
+      suggestedFix: `Run adb -s ${serial} shell screenrecord --help.`
+    };
+  }
+  return {
+    ok: true,
+    code: "ok",
+    message: `Android screen recording is ready on ${serial}.`
+  };
+}
+async function startAndroidRecording(serial, request) {
+  const targetSerial = androidTargetSerial(request);
+  if (targetSerial !== serial) {
+    throw new Error(
+      `Android recording target ${targetSerial ?? "<missing>"} does not match selected device ${serial}.`
+    );
+  }
+  const existingPid = screenrecordPid(serial);
+  if (existingPid) {
+    throw new Error(
+      `Android screenrecord is already running on ${serial} (pid ${existingPid}). Stop that recording before retrying.`
+    );
+  }
+  const remotePath = `/sdcard/Download/mm-harness-recipe-${Date.now()}-${process.pid}.mp4`;
+  const child = spawn(
+    "adb",
+    ["-s", serial, ...androidScreenrecordArgs(remotePath)],
+    { stdio: ["ignore", "pipe", "pipe"] }
+  );
+  const stderr = [];
+  child.stderr?.setEncoding("utf8");
+  child.stderr?.on("data", (chunk) => stderr.push(String(chunk)));
+  child.stdout?.resume();
+  const recorderPid = await waitForScreenrecordStart(serial, child, stderr);
+  let stopped = false;
+  return {
+    async stop() {
+      if (stopped) {
+        throw new Error(`Android screen recording on ${serial} was already stopped.`);
+      }
+      stopped = true;
+      try {
+        stopRemoteScreenrecord(serial, recorderPid);
+        await waitForChildExit(
+          child,
+          RECORDING_STOP_TIMEOUT_MS,
+          "Android screenrecord"
+        );
+        fs.mkdirSync(path.dirname(request.outputPath), { recursive: true });
+        const pull = runAdb(serial, ["pull", remotePath, request.outputPath]);
+        if (pull.status !== 0) {
+          throw new Error(
+            `Could not pull Android recording from ${serial}: ${commandFailure(pull)}`
+          );
+        }
+        const output = fs.statSync(request.outputPath);
+        if (!output.isFile() || output.size <= 0) {
+          throw new Error(`Android recording output is empty: ${request.outputPath}`);
+        }
+        return {
+          recorder: {
+            name: "adb-screenrecord",
+            platform: "android",
+            target: { selector: "adb-serial", value: serial }
+          }
+        };
+      } finally {
+        runAdb(serial, ["shell", "rm", "-f", remotePath]);
+      }
+    }
+  };
+}
+function androidTargetSerial(request) {
+  if (request.target.kind !== "window-id") return void 0;
+  if (!request.target.windowId.startsWith(ANDROID_RECORDING_TARGET_PREFIX)) return void 0;
+  return request.target.windowId.slice(ANDROID_RECORDING_TARGET_PREFIX.length) || void 0;
+}
+async function waitForScreenrecordStart(serial, child, stderr) {
+  const deadline = Date.now() + RECORDING_START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(
+        `Android screenrecord exited before capture started (exit ${child.exitCode}): ${stderr.join("").trim() || "no recorder output"}`
+      );
+    }
+    const pid = screenrecordPid(serial);
+    if (pid) return pid;
+    await sleep(100);
+  }
+  child.kill("SIGTERM");
+  throw new Error(
+    `Android screenrecord did not start on ${serial} within ${RECORDING_START_TIMEOUT_MS}ms.`
+  );
+}
+function stopRemoteScreenrecord(serial, pid) {
+  const stop = runAdb(serial, ["shell", "kill", "-2", pid]);
+  if (stop.status !== 0 && screenrecordPid(serial) === pid) {
+    throw new Error(`Could not stop Android screenrecord pid ${pid}: ${commandFailure(stop)}`);
+  }
+}
+async function waitForChildExit(child, timeoutMs, recorderName) {
+  if (child.exitCode !== null) return;
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error(`${recorderName} did not stop within ${timeoutMs}ms.`));
+    }, timeoutMs);
+    child.once("exit", () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+}
+async function waitForIosRecordingStart(child, output) {
+  const deadline = Date.now() + RECORDING_START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(
+        `iOS simulator recordVideo exited before capture started (exit ${child.exitCode}): ${output.join("").trim() || "no recorder output"}`
+      );
+    }
+    if (output.join("").includes("Recording started")) return;
+    await sleep(100);
+  }
+  if (child.exitCode === null) return;
+  throw new Error(
+    `iOS simulator recordVideo did not start within ${RECORDING_START_TIMEOUT_MS}ms.`
+  );
+}
+function iosTargetSimulator(request) {
+  if (request.target.kind !== "window-id") return void 0;
+  if (!request.target.windowId.startsWith(
+    IOS_SIMULATOR_RECORDING_TARGET_PREFIX
+  )) {
+    return void 0;
+  }
+  return request.target.windowId.slice(IOS_SIMULATOR_RECORDING_TARGET_PREFIX.length) || void 0;
+}
+function screenrecordPid(serial) {
+  const result = runAdb(serial, ["shell", "pidof", "screenrecord"]);
+  if (result.status !== 0) return void 0;
+  return result.stdout.trim().split(/\s+/u).find(Boolean);
+}
+function runAdb(serial, args) {
+  return spawnSync("adb", ["-s", serial, ...args], { encoding: "utf8" });
+}
+function runSimctl(args) {
+  return spawnSync("xcrun", ["simctl", ...args], { encoding: "utf8" });
+}
+function commandFailure(result) {
+  return result.stderr.trim() || result.stdout.trim() || `exit ${result.status ?? "unknown"}`;
+}
+function sleep(durationMs) {
+  return new Promise((resolve) => setTimeout(resolve, durationMs));
+}
+export {
+  androidScreenrecordArgs,
+  createAndroidVideoRecorder,
+  createIosSimulatorVideoRecorder
+};