@deeeed/metamask-harness 0.34.0 → 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/video-recorder.js

@@ -7,7 +7,16 @@ import {
 } from "../../recording-target.js";
 const RECORDING_START_TIMEOUT_MS = 5e3;
 const RECORDING_STOP_TIMEOUT_MS = 1e4;
-const RECORDING_TIME_LIMIT_SECONDS = 180;
+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",
@@ -139,15 +148,7 @@ async function startAndroidRecording(serial, request) {
   const remotePath = `/sdcard/Download/mm-harness-recipe-${Date.now()}-${process.pid}.mp4`;
   const child = spawn(
     "adb",
-    [
-      "-s",
-      serial,
-      "shell",
-      "screenrecord",
-      "--time-limit",
-      String(RECORDING_TIME_LIMIT_SECONDS),
-      remotePath
-    ],
+    ["-s", serial, ...androidScreenrecordArgs(remotePath)],
     { stdio: ["ignore", "pipe", "pipe"] }
   );
   const stderr = [];
@@ -277,6 +278,7 @@ function sleep(durationMs) {
   return new Promise((resolve) => setTimeout(resolve, durationMs));
 }
 export {
+  androidScreenrecordArgs,
   createAndroidVideoRecorder,
   createIosSimulatorVideoRecorder
 };

package/dist/commands/launch/index.js

@@ -316,6 +316,15 @@ async function handleLaunchLocked(argv, stream) {
       originalError: attempt.output.trim() || void 0
     });
   }
+  if (adapter === "mobile" && tier === "build" && /open-device: (?:Android|iOS) native build failed/u.test(attempt.output)) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "MOBILE_NATIVE_BUILD_FAILED",
+      message: "the selected Mobile native build failed; refusing to repeat the expensive build as a Metro recovery.",
+      recoverable: false,
+      exitCode: EXIT.runtime,
+      originalError: attempt.output.trim() || void 0
+    });
+  }
   const bound = checkHealBounds(target, attempt.output, state);
   if (bound !== null) {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {

package/dist/commands/launch/mobile.js

@@ -4,7 +4,7 @@ async function launchMobile(target, mobileTarget, tier, json, restartApp = false
   await ensureHarnessFresh(target, "mobile");
   const platform = mobileTarget ?? "ios";
   const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : void 0;
-  const preflightMode = tier === "build" ? "auto" : "fast";
+  const preflightMode = tier === "build" ? "rebuild-native" : "fast";
   return prepareMobile(target, {
     platform,
     json,

package/dist/live-adapter-contract.js

@@ -356,6 +356,13 @@ function liveAdapterProcessTimeoutMs(node) {
     const timeoutMs = Number(node.timeout_ms);
     return Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs + settleAllowance + 5e3 : 6e4;
   }
+  const actionTimeouts = [node.target_timeout_ms, node.unlock_timeout_ms].map(Number).filter((value) => Number.isFinite(value) && value > 0);
+  if (actionTimeouts.length > 0) {
+    return Math.max(
+      6e4,
+      actionTimeouts.reduce((total, value) => total + value, 0) + 5e3
+    );
+  }
   return 6e4 + settleAllowance;
 }
 function commandForPrepared(projectRoot, platform) {

package/library/actions/mobile/perps/performance-capture.mjs

@@ -205,12 +205,65 @@ function socketPipelineMeasurements(records) {
   });
 }
 
+function firstFreshDeliveryChecks(records, requirements) {
+  return requirements.map((requirement) => {
+    const stream = String(requirement.stream);
+    const requiredLifecycle =
+      requirement.lifecycle === undefined
+        ? null
+        : String(requirement.lifecycle);
+    const subscriberThrottleMs = Number(requirement.subscriber_throttle_ms);
+    const maxSocketToSubscriberMs = Number(
+      requirement.max_socket_to_subscriber_ms,
+    );
+    const socket = records.find(
+      (record) =>
+        record.stage === 'socket_received' &&
+        record.source === 'fresh_socket' &&
+        record.stream === stream &&
+        (requiredLifecycle === null ||
+          record.lifecycle === requiredLifecycle) &&
+        record.delivery_id,
+    );
+    const delivery = socket
+      ? records.find(
+          (record) =>
+            record.stage === 'subscriber_delivery' &&
+            record.delivery_id === socket.delivery_id &&
+            record.stream === stream &&
+            record.lifecycle === socket.lifecycle &&
+            Number(record.throttle_ms ?? 0) === subscriberThrottleMs,
+        )
+      : null;
+    const socketAt = Number(socket?.monotonic_ms);
+    const subscriberAt = Number(delivery?.monotonic_ms);
+    const socketToSubscriberMs =
+      Number.isFinite(socketAt) && Number.isFinite(subscriberAt)
+        ? roundMs(subscriberAt - socketAt)
+        : null;
+    return {
+      stream,
+      lifecycle: socket?.lifecycle ?? requiredLifecycle,
+      subscriberThrottleMs,
+      maxSocketToSubscriberMs,
+      deliveryId: socket?.delivery_id ?? null,
+      socketToSubscriberMs,
+      status:
+        socketToSubscriberMs !== null &&
+        socketToSubscriberMs <= maxSocketToSubscriberMs
+          ? 'pass'
+          : 'fail',
+    };
+  });
+}
+
 function summarize(
   records,
   sourcePath,
   offset,
   bytesScanned,
   requiredFreshContentVariants = [],
+  firstFreshDeliveryRequirements = [],
 ) {
   const stages = {};
   const lifecycles = {};
@@ -240,6 +293,10 @@ function summarize(
     lastMonotonicMs: monotonicValues.length > 0 ? Math.max(...monotonicValues) : null,
     visibleMeasurements: visibleMeasurements(records, requiredFreshContentVariants),
     socketPipelineMeasurements: socketPipelineMeasurements(records),
+    firstFreshDeliveryChecks: firstFreshDeliveryChecks(
+      records,
+      firstFreshDeliveryRequirements,
+    ),
   };
 }
 
@@ -317,6 +374,18 @@ export async function captureHomepagePerformance(input) {
         contentVariantSatisfies(actual, variant),
       ),
   );
+  const firstFreshDeliveryRequirements = Array.isArray(
+    node.first_fresh_delivery_requirements,
+  )
+    ? node.first_fresh_delivery_requirements
+    : [];
+  const deliveryChecks = firstFreshDeliveryChecks(
+    records,
+    firstFreshDeliveryRequirements,
+  );
+  const failedFirstFreshDeliveries = deliveryChecks.filter(
+    (check) => check.status === 'fail',
+  );
 
   const prefix = String(node.artifact_prefix ?? 'logs/homepage-performance');
   const logPath = `${prefix}.log`;
@@ -329,7 +398,8 @@ export async function captureHomepagePerformance(input) {
       missingStages.length === 0 &&
       missingLifecycles.length === 0 &&
       missingSources.length === 0 &&
-      missingFreshContentVariants.length === 0
+      missingFreshContentVariants.length === 0 &&
+      failedFirstFreshDeliveries.length === 0
         ? 'pass'
         : 'fail',
     requireRecords,
@@ -337,6 +407,7 @@ export async function captureHomepagePerformance(input) {
     missingLifecycles,
     missingSources,
     missingFreshContentVariants,
+    failedFirstFreshDeliveries,
   };
   const summary = {
     ...summarize(
@@ -345,6 +416,7 @@ export async function captureHomepagePerformance(input) {
       offset,
       content.length - offset,
       requiredFreshContentVariants,
+      firstFreshDeliveryRequirements,
     ),
     validation,
   };
@@ -371,6 +443,16 @@ export async function captureHomepagePerformance(input) {
       `Missing required fresh ${MARKER} content variants: ${missingFreshContentVariants.join(', ')}.`,
     );
   }
+  if (failedFirstFreshDeliveries.length > 0) {
+    const failures = failedFirstFreshDeliveries.map(
+      (check) =>
+        `${check.stream}/${check.lifecycle ?? 'any'} throttle=${check.subscriberThrottleMs}ms ` +
+        `measured=${check.socketToSubscriberMs ?? 'missing'}ms max=${check.maxSocketToSubscriberMs}ms`,
+    );
+    throw new Error(
+      `First fresh ${MARKER} delivery requirements failed: ${failures.join('; ')}.`,
+    );
+  }
 
   return {
     phase,

package/library/actions/mobile/platform/bridge.mjs

@@ -23,6 +23,41 @@ export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
 
 const execFileAsync = promisify(execFile);
 
+let adapterActionActive = false;
+let actionBridgeLockPath = null;
+
+function resolveBridgeLockPath(input, env) {
+  const configuredRuntime = env.RECIPE_RUNTIME_DIR;
+  const runtime = configuredRuntime
+    ? (path.isAbsolute(configuredRuntime)
+      ? configuredRuntime
+      : path.resolve(input.context.projectRoot, configuredRuntime))
+    : path.join(input.context.projectRoot, 'temp', 'recipe', 'runtime');
+  return path.join(runtime, 'cdp-bridge.lock');
+}
+
+async function acquireActionBridgeLock(input, env) {
+  if (actionBridgeLockPath) return String(process.pid);
+  const lockPath = resolveBridgeLockPath(input, env);
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  await writeFile(lockPath, String(process.pid));
+  actionBridgeLockPath = lockPath;
+  return String(process.pid);
+}
+
+async function releaseActionBridgeLock() {
+  const lockPath = actionBridgeLockPath;
+  actionBridgeLockPath = null;
+  if (!lockPath) return;
+  try {
+    if ((await readFile(lockPath, 'utf8')).trim() === String(process.pid)) {
+      await rm(lockPath, { force: true });
+    }
+  } catch {
+    // The bridge child or a newer owner may already have replaced the lock.
+  }
+}
+
 // Recover the typed code a cdp-bridge child reported: the stderr marker is
 // authoritative (it carries the class the bridge classified at the source), the
 // coded exit status is the fallback for output-less failures, and a raw message
@@ -52,8 +87,14 @@ export async function writeOutput(input, output) {
 
 export async function runAdapter(callback) {
   const input = await loadInput();
-  const output = await callback(input);
-  await writeOutput(input, output);
+  adapterActionActive = true;
+  try {
+    const output = await callback(input);
+    await writeOutput(input, output);
+  } finally {
+    adapterActionActive = false;
+    await releaseActionBridgeLock();
+  }
 }
 
 function bridgeScript(input) {
@@ -127,7 +168,13 @@ export async function bridgeEnv(input) {
   // (e.g. "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36").
   const serialStr = adbSerial != null ? String(adbSerial) : '';
   const deviceStr = androidDevice != null ? String(androidDevice) : '';
-  if (serialStr && deviceStr === serialStr) {
+  if (
+    shouldResolveAndroidTargetModel(
+      serialStr,
+      deviceStr,
+      androidTargetDeviceName,
+    )
+  ) {
     const model = await resolveAndroidModel(serialStr);
     if (model) {
       env.ANDROID_TARGET_DEVICE_NAME = model;
@@ -150,6 +197,17 @@ export async function bridgeEnv(input) {
   return env;
 }
 
+export function shouldResolveAndroidTargetModel(
+  adbSerial,
+  androidDevice,
+  androidTargetDeviceName,
+) {
+  const serial = String(adbSerial ?? '').trim();
+  const device = String(androidDevice ?? '').trim();
+  const targetName = String(androidTargetDeviceName ?? '').trim();
+  return Boolean(serial && !targetName && (!device || device === serial));
+}
+
 function resolveMobileTarget(input) {
   const contextEnv = input.context?.env || {};
   const watcherPort = input.node?.watcher_port ?? input.node?.metro_port ?? input.node?.cdp_port ?? contextEnv.WATCHER_PORT ?? contextEnv.CDP_PORT ?? contextEnv.RECIPE_CDP_PORT ?? process.env.WATCHER_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
@@ -314,6 +372,9 @@ export async function bridgeCommand(input, args) {
   const script = bridgeScript(input);
   // bridgeEnv is async: it may call `adb getprop` to resolve the Metro device name.
   const env = await bridgeEnv(input);
+  if (adapterActionActive) {
+    env.CDP_BRIDGE_LOCK_OWNER_PID = await acquireActionBridgeLock(input, env);
+  }
   const result = await new Promise((resolve, reject) => {
     const timeoutMs = Number(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? 30000);
     const child = spawn(process.execPath, [script, ...args], {