@deeeed/metamask-harness 0.66.3 → 0.67.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## 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
+
+- Wait for asynchronous debug-page consent state updates without accepting missing values; retain immediate validation of authoritative background state.
+- Clarify fixture lifetime and consistent evidence-package handling in the version-matched recipe guide.
+
+### Added
+
+- Prefer capture-helper recording and concurrent screenshots for physical Android through an owned mirror; retain native frame/proof timing for Android and framed Extension, with explicit fallback provenance. Keep finalized footage when optional timing is unavailable, and reject unsafe timing sidecars.
+
+### Changed
+
+- Pin protocol 0.32.0, recipe-harness 0.20.0, agent-runtime 0.15.0 and expo-recipe 0.12.1 from npm for recording timelines and one HTML QA report.
+
 ## 0.66.3 - 2026-09-27
 
 ### Changed

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/adapters/mobile/video-recorder.js

@@ -1,6 +1,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { optionalVideoTiming } from "@farmslot/recipe-harness";
 import {
   ANDROID_RECORDING_TARGET_PREFIX,
   IOS_SIMULATOR_RECORDING_TARGET_PREFIX
@@ -146,6 +147,7 @@ async function startAndroidRecording(serial, request) {
     );
   }
   const remotePath = `/sdcard/Download/mm-harness-recipe-${Date.now()}-${process.pid}.mp4`;
+  const startedAtUnixMs = Date.now();
   const child = spawn(
     "adb",
     ["-s", serial, ...androidScreenrecordArgs(remotePath)],
@@ -170,6 +172,7 @@ async function startAndroidRecording(serial, request) {
           RECORDING_STOP_TIMEOUT_MS,
           "Android screenrecord"
         );
+        const stoppedAtUnixMs = Date.now();
         fs.mkdirSync(path.dirname(request.outputPath), { recursive: true });
         const pull = runAdb(serial, ["pull", remotePath, request.outputPath]);
         if (pull.status !== 0) {
@@ -182,6 +185,7 @@ async function startAndroidRecording(serial, request) {
           throw new Error(`Android recording output is empty: ${request.outputPath}`);
         }
         return {
+          ...await optionalVideoTiming(request.outputPath, { startedAtUnixMs, stoppedAtUnixMs }),
           recorder: {
             name: "adb-screenrecord",
             platform: "android",
@@ -195,6 +199,7 @@ async function startAndroidRecording(serial, request) {
   };
 }
 function androidTargetSerial(request) {
+  if (request.target.kind === "android-device") return request.target.serial;
   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;

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/dist/recording-target.js

@@ -29,8 +29,8 @@ function createMetaMaskRecordingTargetProvider(adapter) {
             );
           }
           return {
-            kind: "window-id",
-            windowId: `${ANDROID_RECORDING_TARGET_PREFIX}${androidSerial}`
+            kind: "android-device",
+            serial: androidSerial
           };
         }
         const simulator = resolveMobileIosSimulatorName(context.env);
@@ -52,6 +52,9 @@ function resolveAndroidDeviceSerial(env = process.env) {
   return env.ADB_SERIAL?.trim() || process.env.ADB_SERIAL?.trim() || void 0;
 }
 function captureHelperSupportsRecordSessionSnapshots(projectRoot) {
+  return captureHelperSupportsCapability(projectRoot, "record_session_snapshot");
+}
+function captureHelperSupportsCapability(projectRoot, capability) {
   const result = spawnSync(captureHelperPath(), ["version", "--json"], {
     cwd: projectRoot,
     encoding: "utf8"
@@ -59,7 +62,7 @@ function captureHelperSupportsRecordSessionSnapshots(projectRoot) {
   if (result.status !== 0) return false;
   try {
     const parsed = JSON.parse(result.stdout);
-    return Array.isArray(parsed.capabilities) && parsed.capabilities.includes("record_session_snapshot");
+    return Array.isArray(parsed.capabilities) && parsed.capabilities.includes(capability);
   } catch {
     return false;
   }
@@ -142,6 +145,7 @@ function readTextFile(file) {
 export {
   ANDROID_RECORDING_TARGET_PREFIX,
   IOS_SIMULATOR_RECORDING_TARGET_PREFIX,
+  captureHelperSupportsCapability,
   captureHelperSupportsRecordSessionSnapshots,
   createMetaMaskRecordingTargetProvider,
   resolveAndroidDeviceSerial,

package/dist/run-recording.js

@@ -1,8 +1,10 @@
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { optionalVideoTiming, readCaptureHelperTiming, writeRecordingTimeline } from "@farmslot/recipe-harness";
 import {
   captureHelperSupportsRecordSessionSnapshots,
+  captureHelperSupportsCapability,
   resolveExtensionBrowserPid
 } from "./recording-target.js";
 const activeRecordingsByPid = /* @__PURE__ */ new Map();
@@ -38,6 +40,7 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     outputPath
   );
   let child;
+  const startedAtUnixMs = Date.now();
   try {
     child = spawn(captureHelperPath(), [...recordArgs, "--output", stagedPath], {
       cwd: projectRoot,
@@ -50,6 +53,8 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
   }
   const recording = {
     child,
+    startedAtUnixMs,
+    nativeTiming: captureHelperSupportsCapability(projectRoot, "record_session_timing_v1"),
     outputPath,
     stagingDir,
     stagedPath,
@@ -78,6 +83,7 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     recording.exited = true;
   });
   child.on("close", (exitCode) => {
+    recording.stoppedAtUnixMs = Date.now();
     recording.exited = true;
     recording.exitCode = exitCode;
     activeRecordingsByPid.delete(recording.pid);
@@ -131,14 +137,14 @@ async function stopRecipeRecording(recording, result) {
   recording.finalized = true;
   try {
     await stopRecordingProcess(recording);
-    const validation = validateRecordingArtifact(recording);
+    const validation = await validateRecordingArtifact(recording);
     if (validation.ok === false) {
       throw new Error(
         `capture-helper recording did not produce a usable video artifact: ${validation.reason}`
       );
     }
     publishRecordingArtifact(recording);
-    if (result) addRecordingArtifactToManifest(result, recording);
+    if (result) await addRecordingArtifactToManifest(result, recording);
   } catch (error) {
     if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
     throw error;
@@ -210,6 +216,10 @@ function handleRecordingEventLine(recording, line) {
   if (event.type === "info" && typeof event.msg === "string" && /^record frames=[1-9]\d*$/.test(event.msg)) {
     recording.frameReady = true;
   }
+  if (event.type === "record_complete" && event.output === recording.stagedPath) {
+    recording.completedVideo = typeof event.frames === "number" && event.frames > 0;
+    if (typeof event.recording_id === "string") recording.completedRecordingId = event.recording_id;
+  }
   const output = typeof event.output === "string" ? event.output : void 0;
   if (!output) return;
   const pending = recording.pendingSnapshots.get(output);
@@ -233,7 +243,7 @@ function rejectPendingSnapshots(recording, error) {
   }
   recording.pendingSnapshots.clear();
 }
-function validateRecordingArtifact(recording) {
+async function validateRecordingArtifact(recording) {
   if (!fs.existsSync(recording.stagedPath)) {
     return { ok: false, reason: `missing output ${recording.stagedPath}` };
   }
@@ -247,6 +257,11 @@ function validateRecordingArtifact(recording) {
   }
   const recorderOutput = `${recording.stdout}
 ${recording.stderr}`;
+  if (recording.nativeTiming) {
+    if (!recording.completedVideo) return { ok: false, reason: "Missing finalized video completion" };
+    recording.nativeTimingEvidence = await readNativeRecordingTiming(recording);
+    return { ok: true };
+  }
   if (!recorderOutput.includes("record_complete")) {
     return {
       ok: false,
@@ -276,6 +291,19 @@ ${recording.stderr}`;
   }
   return { ok: true };
 }
+async function readNativeRecordingTiming(recording) {
+  try {
+    if (!recording.completedRecordingId) throw new Error("Missing native recording completion identity");
+    const sidecar = recording.stagedPath + ".timing.json";
+    const entry = fs.lstatSync(sidecar);
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Native timing must be a regular file");
+    const native = JSON.parse(fs.readFileSync(sidecar, "utf8"));
+    if (native.recording_id !== recording.completedRecordingId) throw new Error("Native recording identity mismatch");
+    return await readCaptureHelperTiming(recording.stagedPath);
+  } catch (error) {
+    return { timingUnavailableReason: error instanceof Error ? error.message : String(error) };
+  }
+}
 function preparePrivateRecordingDestination(artifactsDir, outputPath) {
   const outputDir = path.dirname(outputPath);
   ensureRecordingDirectory(path.resolve(artifactsDir), outputDir);
@@ -311,26 +339,36 @@ Next: replace ${JSON.stringify(directory)} with a regular directory and retry th
   );
 }
 function publishRecordingArtifact(recording) {
+  publishPrivateRecordingFile(recording.stagedPath, recording.outputPath);
+  if (recording.nativeTimingEvidence?.timing) {
+    try {
+      publishPrivateRecordingFile(recording.stagedPath + ".timing.json", recording.outputPath + ".timing.json");
+    } catch (error) {
+      recording.nativeTimingEvidence = { timingUnavailableReason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+}
+function publishPrivateRecordingFile(sourcePath, outputPath) {
   const noFollow = fs.constants.O_NOFOLLOW ?? 0;
   let descriptor;
   try {
-    descriptor = fs.openSync(recording.stagedPath, fs.constants.O_RDONLY | noFollow);
+    descriptor = fs.openSync(sourcePath, fs.constants.O_RDONLY | noFollow);
     const stagedStat = fs.fstatSync(descriptor);
     if (!stagedStat.isFile()) {
-      throw unsafeRecordingArtifactError(recording.stagedPath);
+      throw unsafeRecordingArtifactError(sourcePath);
     }
     fs.fchmodSync(descriptor, 384);
   } catch (error) {
     if (error instanceof Error && error.message.includes("Next:")) throw error;
     throw unsafeRecordingArtifactError(
-      recording.stagedPath,
+      sourcePath,
       error instanceof Error ? error.message : String(error)
     );
   } finally {
     if (descriptor !== void 0) fs.closeSync(descriptor);
   }
-  refuseRecordingDestinationSymlink(recording.outputPath);
-  fs.renameSync(recording.stagedPath, recording.outputPath);
+  refuseRecordingDestinationSymlink(outputPath);
+  fs.renameSync(sourcePath, outputPath);
 }
 function refuseRecordingDestinationSymlink(outputPath) {
   try {
@@ -375,7 +413,7 @@ function restoreActiveRecordingEnvironment(recording) {
   }
   process.env[ACTIVE_EXTENSION_RECORDING_PID] = recording.previousActiveRecordingPid;
 }
-function addRecordingArtifactToManifest(result, recording) {
+async function addRecordingArtifactToManifest(result, recording) {
   const manifestPath = result.artifactManifestPath;
   if (!manifestPath || !fs.existsSync(manifestPath)) {
     console.error(`WARN: cannot add video artifact to missing artifact manifest: ${manifestPath ?? "<unset>"}`);
@@ -384,6 +422,23 @@ function addRecordingArtifactToManifest(result, recording) {
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
   if (!Array.isArray(manifest.artifacts)) manifest.artifacts = [];
   manifest.artifacts = manifest.artifacts.filter((artifact) => artifact.path !== recording.relativePath);
+  const timing = recording.nativeTiming ? recording.nativeTimingEvidence ?? { timingUnavailableReason: "Native recording timing unavailable" } : await optionalVideoTiming(recording.outputPath, {
+    startedAtUnixMs: recording.startedAtUnixMs,
+    stoppedAtUnixMs: recording.stoppedAtUnixMs ?? Date.now()
+  });
+  if (recording.nativeTimingEvidence?.timing) manifest.artifacts.push({ path: recording.relativePath + ".timing.json", type: "json", category: "system", label: "Native recording and screenshot timing" });
+  let timelinePath;
+  let timelineUnavailableReason = timing.timingUnavailableReason;
+  if (timing.timing) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(result.tracePath, "utf8"));
+      const trace = Array.isArray(raw) ? raw : raw.entries;
+      timelinePath = await writeRecordingTimeline(path.dirname(manifestPath), recording.relativePath, timing.timing, trace);
+      manifest.artifacts.push({ path: timelinePath, type: "json", label: "Recording frames and action markers", category: "system" });
+    } catch (error) {
+      timelineUnavailableReason = error instanceof Error ? error.message : String(error);
+    }
+  }
   manifest.artifacts.push({
     path: recording.relativePath,
     type: "video",
@@ -391,6 +446,7 @@ function addRecordingArtifactToManifest(result, recording) {
     category: "evidence",
     mimeType: "video/mp4",
     record: "full_run",
+    ...timelinePath ? { timelinePath } : { timelineUnavailableReason },
     metadata: {
       provider: "capture-helper",
       mode: "full_run",

package/dist/runner.js

@@ -1,5 +1,6 @@
 import { execFileSync, execSync } from "node:child_process";
 import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
+import { createAndroidMirrorVideoRecorder } from "@farmslot/recipe-harness";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
 import {
   bridgeCommand,
@@ -138,7 +139,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter),
-      ...androidRecordingSerial ? { videoRecorder: createAndroidVideoRecorder(androidRecordingSerial) } : iosRecordingSimulator ? {
+      ...androidRecordingSerial ? { videoRecorder: createAndroidMirrorVideoRecorder({ serial: androidRecordingSerial, fallback: createAndroidVideoRecorder(androidRecordingSerial) }) } : iosRecordingSimulator ? {
         videoRecorder: createIosSimulatorVideoRecorder(iosRecordingSimulator)
       } : {}
     },

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/library/actions/extension/analytics/consent.mjs

@@ -85,10 +85,12 @@ export function consentControllerExpression({
         throw new Error('Extension consent state is unavailable.');
       }
       const metamask = root?.metamask ?? root ?? {};
-      if (
+      // Debug UI state can lag an acknowledged setter until the next UI sync.
+      // Background/snapshot reads have no such subscription to wait for.
+      if ((capturedChrome || !storeState) && (
         typeof metamask.optedIn !== 'boolean' ||
         typeof metamask.dataCollectionForMarketing !== 'boolean'
-      ) {
+      )) {
         throw new Error('Extension consent state did not contain boolean consent fields.');
       }
       return {
@@ -118,6 +120,10 @@ export function consentControllerExpression({
         }
         await new Promise((resolve) => setTimeout(resolve, 100));
       } while (Date.now() < deadline);
+      if (typeof result?.state.optedIn !== 'boolean' ||
+          typeof result?.state.dataCollectionForMarketing !== 'boolean') {
+        throw new Error('Extension consent state did not contain boolean consent fields before the deadline.');
+      }
       throw new Error(
         'Consent state did not settle to ' + JSON.stringify(expected) +
         '; got ' + JSON.stringify(result?.state) + '.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.66.3",
+  "version": "0.67.1",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -20,11 +20,11 @@
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
   },
   "dependencies": {
-    "@farmslot/agent-runtime": "0.14.0",
-    "@farmslot/expo-recipe": "0.12.0",
+    "@farmslot/agent-runtime": "0.15.0",
+    "@farmslot/expo-recipe": "0.12.1",
     "@farmslot/handoff": "^0.3.1",
-    "@farmslot/protocol": "0.31.0",
-    "@farmslot/recipe-harness": "0.19.0",
+    "@farmslot/protocol": "0.32.0",
+    "@farmslot/recipe-harness": "0.20.0",
     "agent-device": "0.19.3",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",

package/site/assets/help-recipes.json

@@ -95,7 +95,7 @@
       "details": [
         "Starting conditions are ordinary nodes at the beginning of workflow, not a preconditions field. Use idempotent ensure actions and independently assert their postconditions.",
         "Do not invoke mm-harness run/call from a command node on the same checkout: the outer run owns its sandbox. Compose actions or call child recipes instead. External measurement wrappers may invoke one root run, with preparation outside it; never bypass the lock.",
-        "Inspect existing state before creating or cleaning fixtures. Establish only prerequisites required by the claim; a history or display check may already have usable records and need no trade or cleanup. Record the selected records and verify they still satisfy the proof boundary.",
+        "Inspect existing state before creating or cleaning fixtures. Establish only prerequisites required by the claim; a history or display check may already have usable records and need no trade or cleanup. Record the selected records and verify they still satisfy the proof boundary. Record fixture identity and lifetime: terminal records cannot prove active behavior, and restarting can erase in-memory history. Re-establish expired prerequisites explicitly before the proof window.",
         "Match history-query ranges to the dates of existing visible records before declaring fixtures missing. Sample only sections needed for change detection; fetch one-time corroborating history once, and count background calls as well as graph nodes.",
         "Actions translate UI, CDP, or controller operations. Recipes compose them. Product code owns business rules. Teams own specialized journeys in their libraries; the harness retains shared capabilities and a small set of composable examples.",
         "Put identical cross-adapter graphs in recipes/shared/<domain>/ and platform variants in recipes/<adapter>/<domain>/. Both keep the same domain.recipe name; an adapter variant takes precedence. Keep platform differences in actions when the journey is identical. Verify discovery, execution, and callers before removing duplicates.",
@@ -232,7 +232,8 @@
           "adapters": [
             "core"
           ]
-        }
+        },
+        "Use fixtures that make the intended and incorrect outcomes differ. For changing geometry or values, declare the observation window and compare the same entity and inputs; do not select only favorable samples. Promote trace, screenshots, video and provenance as one immutable package, and inspect replacement image bytes again."
       ],
       "commands": [
         "mm-harness run ./proof.recipe.json --artifacts-dir temp/recipe-proof --json",