@deeeed/metamask-harness 0.67.0 → 0.67.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.67.1 - 2026-09-29
+
+### Fixed
+
+- Prepare the selected Android display on cold and ready-path launches. Locked or unreadable states return `MOBILE_DEVICE_LOCKED` or `MOBILE_DEVICE_UI_UNAVAILABLE` without recovery; the internal `--ui-only` mode supports Android.
+- Honor the full Mobile bridge startup deadline with integer probe timeouts and aligned fixture-reset bounds, instead of restarting slow cold starts prematurely. Unresponsive runtimes still fail at the caller's deadline.
+
+### Removed
+
+- The undocumented `MOBILE_BRIDGE_AGENTIC_GRACE_MS` and `MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS` early-abort settings; use `MOBILE_BRIDGE_READY_TIMEOUT_MS` to set the startup budget.
+
 ## 0.67.0 - 2026-09-28
 
 ### Fixed

package/adapters/mobile/open-device.sh

@@ -14,7 +14,7 @@
 #   --adb-serial <serial>               Android device serial (default: ADB_SERIAL env)
 #   --preflight-mode fast|auto|rebuild-native|clean  (default: fast; env MOBILE_PREFLIGHT_MODE)
 #   --restart                            terminate the selected app before opening it
-#   --ui-only                           iOS only: show the assigned simulator window without relaunching the app
+#   --ui-only                           prepare the selected device UI without launching the app
 #   MM_HARNESS_SIMULATOR_APP             absolute Simulator.app or DeviceHub.app path; GUI only
 #   MM_HARNESS_SHOW_SIMULATOR=0          opt out of automatic GUI opening
 #   MM_HARNESS_FOCUS_SIMULATOR=1         explicitly open/activate the GUI, even with SHOW_SIMULATOR=0
@@ -69,10 +69,6 @@ if [ "$PLATFORM" = "android" ]; then
   fi
   export MM_HARNESS_ADB_PATH="$ADB_BIN"
 fi
-if $UI_ONLY && [ "$PLATFORM" != "ios" ]; then
-  printf 'open-device: --ui-only is supported only for ios.\n' >&2
-  exit 2
-fi
 
 TARGET="$(cd "$TARGET" && pwd)"
 
@@ -345,6 +341,52 @@ focus_simulator() {
 
 # --- Android helpers ----------------------------------------------------------
 
+prepare_android_display() {
+  local power_state="" wake_state="" trust_state="" lock_state="" _attempt
+  printf 'Waking selected Android device before launch\n' >&2
+  if ! "$ADB_BIN" "${ADB_ARGS[@]}" shell input keyevent KEYCODE_WAKEUP >&2; then
+    printf 'open-device: Android display preparation failed.\nNext: wake and unlock the selected device, then retry.\n' >&2
+    return 1
+  fi
+  for _attempt in {1..12}; do
+    if ! power_state="$("$ADB_BIN" "${ADB_ARGS[@]}" shell dumpsys power)"; then
+      break
+    fi
+    wake_state="$(printf '%s\n' "$power_state" | tr -d '\r' | sed -nE 's/^[[:space:]]*mWakefulness=([^[:space:]]+).*/\1/p' | head -1)"
+    case "$wake_state" in
+      Awake|1) break ;;
+      Asleep|Dozing|Dreaming|0|2|3) sleep 0.25 ;;
+      *) break ;;
+    esac
+  done
+  if [ "$wake_state" != Awake ] && [ "$wake_state" != 1 ]; then
+    printf 'open-device: Android display preparation failed.\nNext: wake the selected device and check adb access, then retry.\n' >&2
+    return 1
+  fi
+  if ! "$ADB_BIN" "${ADB_ARGS[@]}" shell wm dismiss-keyguard >&2; then
+    printf 'open-device: Android display preparation failed.\nNext: unlock the selected device, then retry.\n' >&2
+    return 1
+  fi
+  # OS dismissal can finish asynchronously, and cannot unlock a secure keyguard.
+  for _attempt in {1..12}; do
+    if ! trust_state="$("$ADB_BIN" "${ADB_ARGS[@]}" shell dumpsys trust)"; then
+      printf 'open-device: Android lock state unavailable.\nNext: check adb access and the selected device screen, then retry.\n' >&2
+      return 1
+    fi
+    lock_state="$(printf '%s\n' "$trust_state" | tr -d '\r' | sed -nE '/\(current\):/s/.*deviceLocked=([01]|true|false)(,.*)?$/\1/p')"
+    case "$lock_state" in
+      0|false) return 0 ;;
+      1|true) sleep 0.25 ;;
+      *)
+        printf 'open-device: Android lock state unavailable.\nNext: check adb access and the selected device screen, then retry.\n' >&2
+        return 1
+        ;;
+    esac
+  done
+  printf 'open-device: Android device is locked.\nNext: unlock the selected device, then retry; credentials are never entered automatically.\n' >&2
+  return 1
+}
+
 android_app_installed() {
   local pkg="$1"
   shift
@@ -597,6 +639,10 @@ if [ "$PLATFORM" = "ios" ]; then
 else
   ADB_ARGS=()
   [ -n "$ADB_SERIAL_ARG" ] && ADB_ARGS+=("-s" "$ADB_SERIAL_ARG")
+  if $UI_ONLY; then
+    prepare_android_display
+    exit $?
+  fi
 
   LAUNCHED=false
   for PKG in "${ANDROID_PKGS[@]}"; do
@@ -621,6 +667,8 @@ else
       || printf 'http%%3A%%2F%%2Flocalhost%%3A%s%%3FdisableOnboarding%%3D1' "$PORT")"
     DEEP_LINK="expo-metamask://expo-development-client/?url=${ENCODED_URL}"
 
+    prepare_android_display || exit 1
+
     printf 'Launching Android dev client %s\n' "$PKG" >&2
     if "$ADB_BIN" "${ADB_ARGS[@]}" shell am start \
         -a android.intent.action.VIEW \

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

@@ -22,8 +22,6 @@ const {
 const DEFAULT_MAX_POLLS = 90;
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_PROBE_TIMEOUT_MS = 1_500;
-const DEFAULT_AGENTIC_GRACE_MS = 15_000;
-const DEFAULT_UNRESPONSIVE_GRACE_MS = 12_000;
 const PROGRESS_INTERVAL_MS = 10_000;
 const MAX_HTTP_BODY_BYTES = 2 * 1024 * 1024;
 
@@ -76,15 +74,6 @@ function parseArgs(argv, env = process.env) {
     env.MOBILE_BRIDGE_PROBE_TIMEOUT_MS || String(DEFAULT_PROBE_TIMEOUT_MS),
     'MOBILE_BRIDGE_PROBE_TIMEOUT_MS',
   );
-  const agenticGraceMs = parsePositiveInteger(
-    env.MOBILE_BRIDGE_AGENTIC_GRACE_MS || String(DEFAULT_AGENTIC_GRACE_MS),
-    'MOBILE_BRIDGE_AGENTIC_GRACE_MS',
-  );
-  const unresponsiveGraceMs = parsePositiveInteger(
-    env.MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS ||
-      String(DEFAULT_UNRESPONSIVE_GRACE_MS),
-    'MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS',
-  );
 
   return {
     ...options,
@@ -93,8 +82,6 @@ function parseArgs(argv, env = process.env) {
     timeoutMs,
     pollIntervalMs,
     probeTimeoutMs,
-    agenticGraceMs,
-    unresponsiveGraceMs,
   };
 }
 
@@ -128,15 +115,17 @@ function fetchJson(port, pathname, timeoutMs) {
 }
 
 function runBridgeStatus({ bridgePath, target, timeoutMs, env }) {
+  // performance.now() leaves fractional milliseconds near the deadline.
+  const budgetMs = Math.max(1, Math.floor(timeoutMs));
   const result = spawnSync(process.execPath, [bridgePath, 'status'], {
     cwd: target,
     env: {
       ...env,
       APP_ROOT: target,
-      CDP_TIMEOUT: String(timeoutMs),
+      CDP_TIMEOUT: String(budgetMs),
     },
     encoding: 'utf8',
-    timeout: timeoutMs,
+    timeout: budgetMs,
     killSignal: 'SIGTERM',
     maxBuffer: MAX_HTTP_BODY_BYTES,
   });
@@ -154,7 +143,7 @@ function runBridgeStatus({ bridgePath, target, timeoutMs, env }) {
       stdout || stderr
         ? `${stdout}${stderr}`.trimEnd()
         : result.error?.code === 'ETIMEDOUT'
-          ? `bridge status probe exceeded ${timeoutMs}ms`
+          ? `bridge status probe exceeded ${budgetMs}ms`
           : '',
     timedOut: result.error?.code === 'ETIMEDOUT',
   };
@@ -270,26 +259,15 @@ function waitReason(observation, state, config) {
   if (observation.metro === 'no-target') {
     return 'Metro running; no React Native debug target yet';
   }
-  if (state.agenticMissingSince !== null) {
+  if (state.agenticMissing) {
     return 'React Native target answered; in-app bridge not installed yet';
   }
-  if (state.unresponsiveSince !== null) {
+  if (state.unresponsive) {
     return 'React Native target visible; CDP is not answering';
   }
   return 'React Native target answered; waiting for an in-app route';
 }
 
-function failure(kind, startedAt, deadline, now, attempts, lastObservation) {
-  return {
-    ok: false,
-    kind,
-    attempts,
-    elapsedMs: Math.max(0, now - startedAt),
-    remainingMs: Math.max(0, deadline - now),
-    lastObservation,
-  };
-}
-
 async function waitForBridge(config, dependencies = {}) {
   const now = dependencies.now || (() => performance.now());
   const sleep =
@@ -299,11 +277,13 @@ async function waitForBridge(config, dependencies = {}) {
   const progress = dependencies.progress || (() => undefined);
   const status = dependencies.status || (() => undefined);
   const startedAt = now();
+  // Native inspector discovery can precede JavaScript and bridge installation.
+  // Only the caller's startup deadline bounds those intermediate states.
   const deadline = startedAt + config.timeoutMs;
   const state = {
     readyStreak: 0,
-    unresponsiveSince: null,
-    agenticMissingSince: null,
+    unresponsive: false,
+    agenticMissing: false,
   };
   let attempts = 0;
   let nextProgressAt = startedAt;
@@ -328,8 +308,8 @@ async function waitForBridge(config, dependencies = {}) {
 
     if (hasMatchingRoute(lastObservation.statusValue, config.env)) {
       state.readyStreak += 1;
-      state.unresponsiveSince = null;
-      state.agenticMissingSince = null;
+      state.unresponsive = false;
+      state.agenticMissing = false;
       if (state.readyStreak >= 2) {
         return {
           ok: true,
@@ -345,37 +325,13 @@ async function waitForBridge(config, dependencies = {}) {
         (snapshot) => snapshot.agenticPresent === false,
       );
       if (agenticMissing) {
-        state.agenticMissingSince ??= afterProbe;
-        state.unresponsiveSince = null;
-        if (afterProbe - state.agenticMissingSince >= config.agenticGraceMs) {
-          return failure(
-            'agentic-missing',
-            startedAt,
-            deadline,
-            afterProbe,
-            attempts,
-            lastObservation,
-          );
-        }
+        state.agenticMissing = true;
+        state.unresponsive = false;
       } else {
-        state.agenticMissingSince = null;
+        state.agenticMissing = false;
         const targetUnresponsive =
           lastObservation.metro === 'target-visible' && snapshots.length === 0;
-        if (targetUnresponsive) state.unresponsiveSince ??= afterProbe;
-        else state.unresponsiveSince = null;
-        if (
-          state.unresponsiveSince !== null &&
-          afterProbe - state.unresponsiveSince >= config.unresponsiveGraceMs
-        ) {
-          return failure(
-            'target-unresponsive',
-            startedAt,
-            deadline,
-            afterProbe,
-            attempts,
-            lastObservation,
-          );
-        }
+        state.unresponsive = targetUnresponsive;
       }
     }
 
@@ -394,14 +350,15 @@ async function waitForBridge(config, dependencies = {}) {
   }
 
   const endedAt = now();
-  return failure(
-    'deadline',
-    startedAt,
-    deadline,
-    endedAt,
+  return {
+    ok: false,
+    kind: 'deadline',
     attempts,
+    elapsedMs: Math.max(0, endedAt - startedAt),
+    remainingMs: Math.max(0, deadline - endedAt),
+    reason: waitReason(lastObservation, state, config),
     lastObservation,
-  );
+  };
 }
 
 function bundleProgress(logPath) {
@@ -507,21 +464,11 @@ async function main() {
     process.stderr.write(fs.readFileSync(statusLog, 'utf8'));
   } catch {}
   const requested = describeRequested(env);
-  if (result.kind === 'target-unresponsive') {
-    process.stderr.write(
-      `wait-for-bridge: React Native target for ${requested} was visible but CDP did not answer for ${formatSeconds(parsed.unresponsiveGraceMs)} (${formatSeconds(result.elapsedMs)} elapsed, ${formatSeconds(result.remainingMs)} remaining).\n`,
-    );
-  } else if (result.kind === 'agentic-missing') {
-    process.stderr.write(
-      `wait-for-bridge: React Native target for ${requested} answered without __AGENTIC__ for ${formatSeconds(parsed.agenticGraceMs)}.\n`,
-    );
-  } else {
-    process.stderr.write(
-      `wait-for-bridge: readiness deadline expired after ${formatSeconds(result.elapsedMs)} on port ${parsed.port}.\n`,
-    );
-  }
   process.stderr.write(
-    `wait-for-bridge: no bridge target matched the requested ${requested} on port ${parsed.port}.\n`,
+    `wait-for-bridge: readiness deadline expired after ${formatSeconds(result.elapsedMs)} on port ${parsed.port}: ${result.reason}.\n`,
+  );
+  process.stderr.write(
+    `wait-for-bridge: no bridge target matched the requested ${requested} on port ${parsed.port}: ${result.reason}.\n`,
   );
   process.stderr.write(`  requested: ${requested}\n`);
   process.stderr.write(

package/dist/adapters/mobile/prepare.js

@@ -242,7 +242,6 @@ function startMobileConsoleForwarder(target, platform, json, watcherPort) {
   );
 }
 function ensureMobileHumanSurface(target, platform, json, watcherPort) {
-  if (platform !== "ios") return Promise.resolve({ status: 0, output: "" });
   return dispatchAction(
     { id: "ensure-device-ui", cwd: target },
     target,

package/dist/adapters/mobile/verify.js

@@ -435,8 +435,7 @@ async function runMobileVerify(argv, io = defaultIo) {
           {
             env: {
               ...process.env,
-              MOBILE_BRIDGE_READY_TIMEOUT_MS: process.env.MOBILE_BRIDGE_READY_TIMEOUT_MS || "90000",
-              MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS: process.env.MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS || "90000"
+              MOBILE_BRIDGE_READY_TIMEOUT_MS: process.env.MOBILE_BRIDGE_READY_TIMEOUT_MS || "90000"
             }
           }
         );

package/dist/commands/fixtures.js

@@ -12,6 +12,7 @@ import { FeatureFlagSpecError, fixtureFeatureFlags, parseRemoteFlagSpec, sameFea
 import { readExtensionPinnedFlags } from "../adapters/extension/feature-flags.js";
 const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["dev", "force", "json"]);
 const FIXTURE_STREAM_TIMEOUT_MS = 12e4;
+const FIXTURE_BRIDGE_READY_TIMEOUT_MS = 18e4;
 const MOBILE_SETUP_WALLET_TIMEOUT_MS = 36e4;
 async function handleFixtures(argv) {
   const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
@@ -251,9 +252,9 @@ async function handleFixturesLocked(argv) {
             const waitForBridge = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
             const waitResult = await spawnScriptStreaming(
               waitForBridge,
-              ["--target", target, "--port", port, "--platform", platform],
+              ["--target", target, "--port", port, "--platform", platform, "--timeout-ms", String(FIXTURE_BRIDGE_READY_TIMEOUT_MS)],
               target,
-              { timeoutMs: FIXTURE_STREAM_TIMEOUT_MS }
+              { timeoutMs: FIXTURE_BRIDGE_READY_TIMEOUT_MS + 1e4 }
             );
             if (waitResult.status !== 0) {
               resetError = new Error("Mobile bridge did not return after app data reset.");

package/dist/commands/launch/index.js

@@ -381,6 +381,26 @@ async function handleLaunchLocked(argv, stream) {
       originalError: attempt.output.trim() || void 0
     });
   }
+  if (adapter === "mobile" && attempt.output.includes("open-device: Android device is locked.")) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "MOBILE_DEVICE_LOCKED",
+      message: "the selected Android device is locked.",
+      recoverable: false,
+      userAction: "Unlock the selected Android device, then retry the launch.",
+      exitCode: EXIT.runtime,
+      originalError: attempt.output.trim()
+    });
+  }
+  if (adapter === "mobile" && /open-device: Android (?:lock state unavailable|display preparation failed)\./u.test(attempt.output)) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "MOBILE_DEVICE_UI_UNAVAILABLE",
+      message: "the selected Android display could not be prepared.",
+      recoverable: false,
+      userAction: "Check adb access and the selected device screen, then retry the launch.",
+      exitCode: EXIT.runtime,
+      originalError: attempt.output.trim()
+    });
+  }
   if (heal === "off") {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "LAUNCH_FAILED",

package/docs/QA.md

@@ -105,6 +105,18 @@ mm-harness debug
 
 ## Mobile
 
+Physical Android devices must be awake and unlocked. Launch wakes the selected
+device, requests keyguard dismissal and checks the current user's lock state.
+`MOBILE_DEVICE_LOCKED` requires a human unlock; `MOBILE_DEVICE_UI_UNAVAILABLE`
+means the display or lock-state check failed. These prerequisites stop launch
+without an automatic recovery restart.
+
+For dedicated powered QA devices, configure stay-awake for the power sources
+actually reported by Android. An ADB-connected phone can report AC power, so a
+USB-only setting may still allow sleep. `adb -s <serial> shell svc power stayon true`
+enables stay-awake on external power. Record the previous setting before changing
+it, and restore it when returning a device to ordinary use.
+
 ```bash
 cd /path/to/metamask-mobile
 mm-harness provision runway ios

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.67.0",
+  "version": "0.67.1",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"