@deeeed/metamask-harness 0.86.2 → 0.87.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.87.0 - 2026-10-10
+
+### Changed
+
+- `--record-video=full-run` on a physical Android device records on the device with `adb shell screenrecord`, not a scrcpy window captured through capture-helper. macOS stopped the capture-helper stream whenever another capture-helper process exited (Farmslot's browser liveness check, `mm-harness doctor`, another slot's recording), so a Pixel 6a release run lost its full-run video with ScreenCaptureKit error -3805. screenrecord ends each file at 180 s: the recorder starts the next file as soon as one ends and joins them with ffmpeg, so a physical Android recording now needs ffmpeg at start (`FFMPEG_PATH` overrides). The roughly half-second gap at each restart is kept as a held frame, so video time stays on wall-clock time and the recording timeline stays tight; `videos/recipe-run.mp4.capture.json` lists each file's start, stop and offset. If the file being stopped at the end of the run fails (stopped while screenrecord was still starting), the earlier files are kept. Device files and pulled host files are removed and the device and host recorder processes stopped when the run ends, fails, or the harness gets SIGINT, SIGTERM or SIGHUP. The recipe HUD is drawn in the app, so it is in the video. Screens the app marks secure (FLAG_SECURE) record black, as with any capture of the device screen. Emulators keep the mirror. `METAMASK_RECIPE_MOBILE_ANDROID_RECORDER=screenrecord|mirror` forces either recorder (`mirror` keeps its single-file screenrecord fallback when the mirror is unavailable); any other value fails the run.
+- A Mobile recording that fails, or whose recorder cannot record when the run starts, now fails the run with a code. The `record.video` trace entry reads `RECORDING_FAILED: <cause>. The run has no video.` or, when capture stopped mid-run with nothing kept, `RECORDER_INTERRUPTED: <cause>. The run has no video.`, with `cause_class: "environment"`. Before, it carried the recorder's raw message (for capture-helper 0.3.0 an empty `capture-helper record failed (exit 1):`). A recording that stopped mid-run but kept a finalized partial file is published, and its manifest entry gains `recorder.interrupted` (`code: "RECORDER_INTERRUPTED"`, `cause`, and `coveredMs`, the video time up to the last captured frame, or `coverageUnavailableReason` when that cannot be measured); the run also prints a `WARN: RECORDER_INTERRUPTED` line. This covers capture-helper 0.3.1's `stream_interrupted` event on the emulator mirror (the MP4 and timing sidecar it finalized are kept; `cause` names the ScreenCaptureKit error, such as `SCStreamErrorDomain -3805`) and an on-device screenrecord that fails mid-run (the files finished before it are kept).
+- `mm-harness doctor`, `doctor --expect-live`, `--print-ready` and `doctor --fix` on Mobile check the recorder `run --record-video` would use for the selected device once the runtime is ready, and show it (`recorder` in `--json`, a `recorder:` line otherwise). A recorder that cannot record (no ffmpeg for on-device recording, capture-helper or scrcpy unusable with no fallback, simulator not booted) makes doctor report `ready: false` with that recorder's next step: `DOCTOR_CHECKS_FAILED` from `doctor`, `RECORDER_UNAVAILABLE` from `--expect-live --json`, `not-ready` from `--print-ready`, and `recorder` in `failed` from `--fix`. Before, doctor reported ready while every recording failed.
+
+### Fixed
+
+- `mm-harness run --plan` now rejects a `metamask.perps.start_state` node that combines a Mobile `trading_state` with a `positions`, `orders` or `strategies` request other than `false`, or whose `positions` or `orders` block opens a position or order without a market and side (on the node or in the block) and an `amount` or `notional` in the block. Unresolved templates are still checked at run time.
+- Extension `metamask.analytics.set_consent` reads marketing consent from `optedInToMarketing` when the state has no `dataCollectionForMarketing` (Extension 13.51+), so its readback no longer fails with "Extension consent state did not contain boolean consent fields before the deadline".
+- Extension `ui.navigate page=perps` names a Perps home still loading at the deadline, with loading markers listed first in its visible test IDs: "Perps home stayed on its loading view (perps-view-loading visible) within the <n>ms budget" and "Next: check the Perps stream/provider, or raise timeout_ms".
+- Mobile Perps `start_state` and `teardown_state` keep the setup budget apart from bridge command limits. Before, one deadline covered unlock, account, navigation and cleanup, and every nested bridge command could use all of what was left. On a physical Pixel 6a, a market-details to home navigation took about 18 s of a 30 s clean-market setup. Later commands were cut to slivers (`press-test-id` after 1258 ms, `eval-async` after 315 ms) or refused, and every one was reported as `CDP_TIMEOUT`, which reads as a bridge failure. Now each phase runs on its own deadline inside the setup budget. Navigation phases get a slice (`navigation_timeout_ms`), and each bridge command gets its own limit (`cdp_timeout_ms`, default 15 s) capped by the phase deadline. A phase that runs out fails as `DOMAIN_SETUP_DEADLINE`, with the phase, its elapsed time and limit, and the setup's elapsed time and limit. A bridge command its action deadline refused or stopped fails as `ACTION_DEADLINE`, not `CDP_TIMEOUT`. Route waits, `ensure_mode` and account switching treat it as no answer yet: a route or mode wait still ends with its own timeout message, and an account switch the deadline cut short is reported as ambiguous. A command that hits its own limit keeps `CDP_TIMEOUT`, and its message now says `CDP_COMMAND_TIMEOUT` and gives the limit.
+- Mobile setup and navigation budgets depend on the device class. Emulators and simulators keep 30 s for setup and 15 s per navigation. A physical Android device (explicit non-`emulator-*` adb serial) gets 60 s and 30 s. `MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS` and `MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS` override the defaults, and node `timeout_ms` and `navigation_timeout_ms` override both. The setups' live process timeout is raised to the setup budget plus 5 s, so the process timeout no longer races a 60 s setup. `start_state` and `teardown_state` schemas accept `navigation_timeout_ms` and `cdp_timeout_ms`.
+- A Hyperliquid `429 Too Many Requests` in a Perps action is now the typed error `RATE_LIMITED`, naming the call, the attempts and the backoff used. Farm runs share the testnet account and egress IP, so the venue rate-limits them; on Extension 13.52.0 QA (testnet run 46848-1009-223034) the $12 SOL setup order failed with `429 Too Many Requests - null` and Recipe Cook stopped the case, though nothing was placed.
+  - Reads retry up to 3 times with exponential backoff and jitter (between half and all of 1 s, 2 s, 4 s), then fail `RATE_LIMITED` with `Next: wait a minute and rerun`. No retry starts unless its backoff and another attempt as long as the last one end before the action deadline, and a retry still unanswered at the deadline fails there. The deadline is the inherited deadline on Mobile, and 5 s before the runner kills the live adapter process (`liveAdapterProcessTimeoutMs`) on Extension and Core. This covers Extension position, order, account, market, size-step and snapshot reads and the `compare_provider_market` venue read, Mobile controller position, order and strategy-order reads, and Core `read_positions`, `read_orders` and `read_account`.
+  - Extension background `metamask.perps.place_order` retries a 429 only when the dispatch itself got it (no accepted order) and, after the backoff, Hyperliquid's own info API (read from the harness, not the extension) shows no open order and no fill in that market since the first dispatch (open orders read first, so an order filling between the reads still shows), and for a market order no position on its side. Up to 3 retries, and only while the backoff and those reads (5 s at most) leave the postcondition its `timeout_ms` and 5 s before the process limit. The retry's own pre-dispatch checks are bounded by that deadline too; a retry that would reach the venue after it is not sent, the receipt becomes `not-dispatched`, and the error is still `RATE_LIMITED`. Every retry reruns the pre-dispatch checks (unchanged funding balance, provider and network, CDP target, bound account); the budget cap and the order rule are the first dispatch's.
+  - Every 429 on a dispatch goes into the receipt under `rateLimitedDispatches`, with its backoff and venue verification or the reason it was not retried. Without a retry the receipt stays `outcome-unknown` and the error is `RATE_LIMITED` with that reason and still `Next: do not rerun this mutation`: a venue read that fails or shows activity, a HIP-3 market, spent retries, the deadline, a 429 on the postcondition read after dispatch (never redispatched), and every other Extension mutation. Mobile placements keep no receipt and are not retried.
+- Mobile `metamask.perps.read_visible_state` counts the Perps home Recent activity rows (`perps-recent-activity-row-<n>`) and a market's recent trades rows (`perps-market-trades-row-<n>`) as activity. A populated home preview reported `activity: []` and failed `minimum_activity_count`.
+- Mobile `ui.wait_for expected=absent` no longer times out on a control that only a screen hidden in the navigation stack still mounts. The app's tree query also finds test IDs in screens a navigator keeps behind the focused one (the Activity screen's `activity-screen-aggregated-checkbox` under Perps home). A tree hit now counts as absent only when every match is on a provably hidden route (an inactive tab, or a stack screen that is neither modal-presented nor inheriting a modal presentation, with a screen above it that is not modal either) and a complete native observation, read within the wait's remaining time, does not show the test ID. The result then carries `hiddenRoute: true` and `nativeVisible: false`. A modal-family screen, and any screen under a sheet or transparent modal, is never treated as hidden, even when native accessibility omits its controls; a truncated or warned native observation, or a navigator the walk cannot read, keeps the control present. Present-waits are unchanged.
+- Extension `metamask.perps.read_snapshot` states that its `history` section is the funds ledger from `perpsGetUserHistory` (deposits, withdrawals and transfers), not trades or orders. Zero history items with trade rows on screen is expected; read those rows with `read_visible_state` activity.
+
 ## 0.86.2 - 2026-10-09
 
 ### Fixed
@@ -15,6 +38,7 @@
 
 ### Fixed
 
+- Mobile `metamask.perps.start_state` refuses `trading_state` combined with an explicit `positions`, `orders` or `strategies` request (anything but `false`). The policy sets all three itself, so the request was dropped without a word: `trading_state=preserve` with `positions: { state: "open", notional: 11, leverage: 2 }` passed with `positions: { skipped: true }` and opened nothing. A later isolated-margin prerequisite then read zero positions. The action now fails before unlock, naming the ignored keys. Omit `trading_state` to apply the request, or put the request in its own `start_state` node. Profile defaults are still replaced by the policy, and `false` is still accepted.
 - Mobile route waits (`navigate` and `waitForRoute` in the action library) now end at the calling action's deadline. Before, once a Perps `start_state` or `teardown_state` ran out of budget, the bridge refused each new `get-route` with `CDP_TIMEOUT`. The waits took that refusal for a target transition and kept polling for up to 30 s more on their own 15 s windows. They could not see a route that did arrive, and failed with "did not start before its action deadline: get-route". On a physical Pixel 6a this showed up as `CDP_TIMEOUT` in clean-market setup and teardown, while one `get-route` took 0.1 to 0.5 s. Both now stop at the deadline. A route that never matched fails with the expected route, the last route read and the limit applied; a recovery cut short by the deadline fails with its last bridge error.
 
 ## 0.86.1 - 2026-10-09
@@ -24,6 +48,8 @@
 - Extension `metamask.perps.close_visible_position cleanup_only=true` reconciles the final balance against the margin the close releases. With no placement receipt, the baseline is the available balance read while the position is still open. That baseline excludes the position's margin, so a clean full close went over the $1 tolerance and left an `outcome-unknown` receipt. A 0.11 SOL testnet close moved $524.42 to $536.45 and failed this way. The action now reads the close modal's "You'll receive" amount before dispatch and records it in the receipt as `closeReleaseBaseUnits`. It then checks the final balance against baseline + receive, with the same tolerance. If the amount is not visible, the action refuses before publishing a receipt or clicking. Closes backed by a placement receipt still reconcile against the pre-order balance. Cleanup output adds `releaseBaseUnits` and `expectedBalanceAfterBaseUnits`.
 - Mobile `metamask.perps.read_visible_state` on iOS sees Perps Text test IDs. iOS accessibility lists React Native Text as a StaticText with no identifier, so a visible Lite market price (`perps-market-header-price`) failed `require_features: ["price"]`. On a non-opaque iOS run, `ui.visible` now reads each mounted `perps-` Text's test ID, string and size over the dev bridge. It gives that test ID to the on-screen StaticText with the same label and size, when exactly one test ID matches. Offscreen StaticText stays unbound, and so does a same-text twin of another size (the collapsed header price). Other Text, such as a revealed Secret Recovery Phrase word, is not read. This reaches every iOS `ui.visible` consumer: `ui.locators`, native-navigation test-ID waits, `readVisiblePerpsTestIds`, `configure_order`, and the assets and swap-bridge `read_visible_state`. Opaque runtimes and Android are unchanged. A non-opaque run with Metro down pays one bridge attempt (at most 2 s) per observation and gets a `ui.visible` warning; a read over 500 Texts is truncated with a warning.
 - An empty `METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT` means the bundled `cdp-bridge.cjs` everywhere the TypeScript side spawns the Mobile bridge, as `run` and the action library already treated it. `launch`'s feature-flag reads and pins (and `doctor`'s) and the `status` live probe read the variable with `??`. An empty value made them check for a script named `""`, so they reported no runtime and never spawned a bridge. All TypeScript callers now share one `mobileBridgeScript()`; the action library keeps the same rule in its own `bridgeScript()` because it cannot import `src/`.
+- Contributors: `tests/contract/run.sh` stopped by SIGTERM signals every running test at once, from one process listing, and its main loop no longer delays the trap by a `sleep`. A runner SIGKILLed 0.3 s after its SIGTERM used to leave most running tests (and their `timeout` parents) going until their own time limit, and `/tmp/contract-run.*` behind; now each test gets its SIGTERM and cleans up, and the directory goes once they have.
+- Contributors: a unit run's teardown also stops what the processes naming its TMPDIR started (a wrapper's child need not name it), so it no longer orphans them. The `feature-guard-run-capture` timeout test times out only once bash has set its EXIT trap, instead of hoping bash starts within 3 s; it no longer fails on a loaded machine and runs in under a second.
 
 ## 0.86.0 - 2026-10-09
 

package/dist/adapters/mobile/action-inputs.js

@@ -0,0 +1,20 @@
+const POLICY_KEYS = ["positions", "orders", "strategies"];
+function isTemplate(value) {
+  return typeof value === "string" && value.includes("{{");
+}
+function mobileActionInputFindings(nodeId, node) {
+  const policy = node.trading_state;
+  if (node.action !== "metamask.perps.start_state" || typeof policy !== "string" || isTemplate(policy)) return [];
+  const dropped = POLICY_KEYS.filter((key) => node[key] !== void 0 && node[key] !== false && !isTemplate(node[key]));
+  if (dropped.length === 0) return [];
+  const keys = dropped.join(", ");
+  return [{
+    severity: "error",
+    code: "recipe.invalid_param",
+    path: `workflow.nodes.${nodeId}.trading_state`,
+    message: `metamask.perps.start_state trading_state=${policy} sets positions, orders and strategies itself, so the requested ${keys} would be ignored. Omit trading_state to apply ${keys}, or request ${keys} in a separate metamask.perps.start_state node.`
+  }];
+}
+export {
+  mobileActionInputFindings
+};

package/dist/adapters/mobile/actions.js

@@ -1,5 +1,7 @@
+import { liveAdapterProcessTimeoutMs } from "@farmslot/recipe-cli/harness";
 import { manifestPath } from "../../paths.js";
 import { perpsOrderInputFindings } from "../perps-order-inputs.js";
+import { mobileActionInputFindings } from "./action-inputs.js";
 const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
   "ui.press",
   "ui.key_press",
@@ -13,6 +15,8 @@ const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
   "ui.screenshot",
   "ui.capture_surface"
 ]);
+const MOBILE_SETUP_ACTIONS = /* @__PURE__ */ new Set(["metamask.perps.start_state", "metamask.perps.teardown_state"]);
+const SETUP_EXIT_ALLOWANCE_MS = 5e3;
 const mobileActions = {
   manifestPath: () => manifestPath("mobile"),
   semantic: [
@@ -49,9 +53,22 @@ const mobileActions = {
   }),
   wrap: async (adapters) => (await import("./runtime-identity.js")).withMobileNativeRuntimeIdentity(adapters),
   lifecycle: async (adapters) => (await import("./lifecycle.js")).mobileSourceAwareLifecycleAdapters(adapters),
+  // A Perps setup resolves its own budget (device-class default unless the node
+  // sets timeout_ms). Its process must outlive that budget so the setup, not the
+  // process timeout, reports which phase ran out.
+  liveProcessNode: async (action, node, env) => {
+    if (!MOBILE_SETUP_ACTIONS.has(action) || node.live_adapter_timeout_ms != null) return node;
+    const { mobileSetupTimeoutMs } = await import("../../../library/actions/mobile/platform/bridge.mjs");
+    const needed = mobileSetupTimeoutMs({ node, context: { env } }) + SETUP_EXIT_ALLOWANCE_MS;
+    return needed > liveAdapterProcessTimeoutMs(node) ? { ...node, live_adapter_timeout_ms: needed } : node;
+  },
   // ensure_positions and ensure_orders with an open or present state place an order.
-  inputFindings: (nodeId, node) => perpsOrderInputFindings(nodeId, node, { ensureChecksOnly: false })
+  inputFindings: (nodeId, node) => [
+    ...mobileActionInputFindings(nodeId, node),
+    ...perpsOrderInputFindings(nodeId, node, { ensureChecksOnly: false })
+  ]
 };
 export {
+  SETUP_EXIT_ALLOWANCE_MS,
   mobileActions
 };

package/dist/adapters/mobile/android-screenrecord.js

@@ -0,0 +1,270 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { createAndroidVideoRecorder } from "@farmslot/adapter-rn";
+import { optionalVideoTiming } from "@farmslot/recipe-runner";
+import { interruptedRecorder, recordingFailure } from "./recording-outcome.js";
+const SEGMENT_SECONDS = 180;
+const START_TIMEOUT_MS = 5e3;
+const STOP_TIMEOUT_MS = 1e4;
+const START_GRACE_MS = 1e3;
+const HOST_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+function createAndroidScreenrecordRecorder(serial, options = {}) {
+  const adb = (args) => spawnSync("adb", ["-s", serial, ...args], { encoding: "utf8", timeout: 6e4 });
+  return {
+    name: "adb-screenrecord",
+    platform: "android",
+    async doctor() {
+      const device = await createAndroidVideoRecorder(serial).doctor();
+      if (!device.ok) return device;
+      const ffmpeg = spawnSync(ffmpegPath(), ["-version"], { encoding: "utf8", timeout: 1e4 });
+      if (ffmpeg.status !== 0) {
+        return {
+          ok: false,
+          code: "ffmpeg_unavailable",
+          message: `ffmpeg, which joins Android screenrecord files, is unavailable: ${failure(ffmpeg)}`,
+          suggestedFix: "Install ffmpeg (brew install ffmpeg) or set FFMPEG_PATH."
+        };
+      }
+      return { ok: true, code: "ok", message: `Android on-device screen recording is ready on ${serial}.` };
+    },
+    start: (request) => startRecording(serial, request, adb, options)
+  };
+}
+async function startRecording(serial, request, adb, options) {
+  if (request.target.kind !== "android-device" || request.target.serial !== serial) {
+    throw new Error("Android recording target does not match the selected device.");
+  }
+  const pollMs = options.pollMs ?? 100;
+  const host = options.host ?? process;
+  const running = screenrecordPids(adb);
+  if (running.length > 0) {
+    throw new Error(`Android screenrecord is already running on ${serial} (pid ${running.join(", ")}). Stop that recording before retrying.`);
+  }
+  const prefix = `${options.remoteDir ?? "/sdcard/Download"}/mm-harness-recording-${Date.now()}-${process.pid}`;
+  const segments = [];
+  let stopping = false;
+  let interruption;
+  let chain = Promise.resolve();
+  const localFiles = /* @__PURE__ */ new Set();
+  const segmentFailure = (segment) => `screenrecord on ${serial} stopped with exit ${segment.exitCode ?? "error"}: ${segment.output.trim() || "no recorder output"}`;
+  const startSegment = async () => {
+    const remotePath = `${prefix}-${segments.length}.mp4`;
+    const startedAtUnixMs = Date.now();
+    const child = spawn(
+      "adb",
+      ["-s", serial, "shell", "screenrecord", "--time-limit", String(options.segmentSeconds ?? SEGMENT_SECONDS), remotePath],
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    const exited = new Promise((resolve) => {
+      child.once("error", () => resolve(null));
+      child.once("exit", (code) => resolve(code));
+    });
+    const segment = { remotePath, child, output: "", startedAtUnixMs, exited };
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      segment.output = (segment.output + chunk).slice(-2e3);
+    });
+    segments.push(segment);
+    void exited.then((code) => {
+      segment.stoppedAtUnixMs = Date.now();
+      segment.exitCode = code;
+      if (!segment.pid || segment.killed || interruption || stopping) return;
+      if (code !== 0) {
+        interruption = segmentFailure(segment);
+        return;
+      }
+      chain = startSegment().catch((error) => {
+        interruption ??= error instanceof Error ? error.message : String(error);
+      });
+    });
+    const deadline = Date.now() + (options.startTimeoutMs ?? START_TIMEOUT_MS);
+    while (Date.now() < deadline) {
+      if (segment.stoppedAtUnixMs !== void 0) {
+        throw new Error(`Android screenrecord exited before capture started on ${serial}: ${segment.output.trim() || "no recorder output"}`);
+      }
+      const pid = screenrecordPids(adb)[0];
+      if (pid) {
+        segment.pid = pid;
+        return;
+      }
+      await delay(pollMs);
+    }
+    child.kill("SIGTERM");
+    throw new Error(`Android screenrecord did not start on ${serial} within ${options.startTimeoutMs ?? START_TIMEOUT_MS}ms.`);
+  };
+  const abandon = () => {
+    const live = segments.filter((segment) => segment.stoppedAtUnixMs === void 0);
+    for (const segment of live) segment.killed = true;
+    if (live.length > 0) {
+      const starting = live.some((segment) => !segment.pid);
+      const graceUntil = Date.now() + (starting ? START_GRACE_MS : 0);
+      const giveUpAt = Date.now() + (options.stopTimeoutMs ?? STOP_TIMEOUT_MS);
+      const signaled = /* @__PURE__ */ new Set();
+      while (Date.now() < giveUpAt) {
+        const pids = screenrecordPids(adb).filter((pid) => starting || live.some((segment) => segment.pid === pid));
+        if (pids.length === 0 && Date.now() >= graceUntil) break;
+        for (const pid of pids) {
+          if (!signaled.has(pid)) adb(["shell", "kill", "-2", pid]);
+          signaled.add(pid);
+        }
+        sleepSync(pollMs);
+      }
+      for (const segment of live) segment.child.kill("SIGTERM");
+    }
+    if (segments.length > 0) adb(["shell", "rm", "-f", ...segments.map((segment) => segment.remotePath)]);
+    for (const localPath of localFiles) fs.rmSync(localPath, { force: true });
+  };
+  const onExit = () => abandon();
+  const signalHandlers = Object.fromEntries(
+    HOST_SIGNALS.map((signal) => [
+      signal,
+      () => {
+        stopping = true;
+        abandon();
+        removeGuards();
+        if (host.listenerCount(signal) === 0) host.kill(host.pid, signal);
+      }
+    ])
+  );
+  const removeGuards = () => {
+    host.removeListener("exit", onExit);
+    for (const signal of HOST_SIGNALS) host.removeListener(signal, signalHandlers[signal]);
+  };
+  host.once("exit", onExit);
+  for (const signal of HOST_SIGNALS) host.once(signal, signalHandlers[signal]);
+  try {
+    await startSegment();
+  } catch (error) {
+    stopping = true;
+    abandon();
+    removeGuards();
+    throw error;
+  }
+  let stopped = false;
+  return {
+    async stop() {
+      if (stopped) throw new Error(`Android screen recording on ${serial} was already stopped.`);
+      stopped = true;
+      stopping = true;
+      const stagingDir = path.dirname(request.outputPath);
+      try {
+        await chain;
+        const tail = segments.at(-1);
+        if (tail.stoppedAtUnixMs === void 0 && tail.pid) adb(["shell", "kill", "-2", tail.pid]);
+        if (!await settles(tail.exited, options.stopTimeoutMs ?? STOP_TIMEOUT_MS)) {
+          tail.killed = true;
+          tail.child.kill("SIGKILL");
+          throw new Error(`Android screenrecord on ${serial} did not stop within ${options.stopTimeoutMs ?? STOP_TIMEOUT_MS}ms.`);
+        }
+        const kept = interruption ? segments.filter((segment) => segment.exitCode === 0) : tail.exitCode === 0 ? segments : segments.slice(0, -1);
+        if (kept.length === 0) {
+          throw recordingFailure(interruption ? "RECORDER_INTERRUPTED" : "RECORDING_FAILED", interruption ?? segmentFailure(tail));
+        }
+        fs.mkdirSync(stagingDir, { recursive: true });
+        const recorded = [];
+        for (const [index, segment] of kept.entries()) {
+          const localPath = path.join(stagingDir, `${path.basename(request.outputPath)}.segment-${index}.mp4`);
+          localFiles.add(localPath);
+          const pull = adb(["pull", segment.remotePath, localPath]);
+          if (pull.status !== 0) throw new Error(`Could not pull Android recording from ${serial}: ${failure(pull)}`);
+          const bytes = fs.statSync(localPath).size;
+          if (bytes > 0) recorded.push({ ...segment, localPath, bytes });
+        }
+        if (recorded.length === 0) throw recordingFailure("RECORDING_FAILED", `Android recording output is empty: ${request.outputPath}`);
+        const startedAtUnixMs = recorded[0].startedAtUnixMs;
+        const stoppedAtUnixMs = recorded.at(-1).stoppedAtUnixMs;
+        const placed = recorded.map((segment) => ({ ...segment, offsetMs: segment.startedAtUnixMs - startedAtUnixMs }));
+        joinSegments(placed, request.outputPath);
+        const timingEvidencePath = `${path.basename(request.outputPath)}.segments.json`;
+        fs.writeFileSync(
+          path.join(stagingDir, timingEvidencePath),
+          `${JSON.stringify({
+            recorder: "adb-screenrecord",
+            serial,
+            segments: placed.map((segment) => ({
+              offsetMs: segment.offsetMs,
+              startedAtUnixMs: segment.startedAtUnixMs,
+              stoppedAtUnixMs: segment.stoppedAtUnixMs,
+              bytes: segment.bytes
+            }))
+          })}
+`
+        );
+        const timing = await optionalVideoTiming(request.outputPath, { startedAtUnixMs, stoppedAtUnixMs });
+        const recorder = { name: "adb-screenrecord", platform: "android", target: { selector: "adb-serial", value: serial } };
+        return {
+          ...timing.timing ? { timing: { ...timing.timing, clock: { ...timing.timing.clock, latestZeroUnixMs: latestVideoZero(timing.timing, placed) } } } : timing,
+          timingEvidencePath,
+          recorder: interruption ? interruptedRecorder(
+            recorder,
+            interruption,
+            timing.timing ? { coveredMs: [0, timing.timing.framesMs.at(-1)] } : { coverageUnavailableReason: timing.timingUnavailableReason ?? "video timing unavailable" }
+          ) : recorder
+        };
+      } finally {
+        abandon();
+        removeGuards();
+      }
+    }
+  };
+}
+function latestVideoZero(timing, segments) {
+  return segments.reduce((latest, segment, index) => {
+    const to = segments[index + 1]?.offsetMs ?? Infinity;
+    const last = timing.framesMs.filter((time) => time >= segment.offsetMs && time < to).at(-1);
+    return last === void 0 ? latest : Math.max(latest, segment.stoppedAtUnixMs - last);
+  }, timing.clock.latestZeroUnixMs);
+}
+function joinSegments(segments, outputPath) {
+  if (segments.length === 1) {
+    fs.renameSync(segments[0].localPath, outputPath);
+    return;
+  }
+  const listPath = `${outputPath}.segments.txt`;
+  const list = segments.map((segment, index) => {
+    const entry = `file '${segment.localPath.replaceAll("'", "'\\''")}'`;
+    const next = segments[index + 1];
+    return next ? `${entry}
+duration ${((next.offsetMs - segment.offsetMs) / 1e3).toFixed(3)}` : entry;
+  });
+  fs.writeFileSync(listPath, `${list.join("\n")}
+`);
+  try {
+    const join = spawnSync(ffmpegPath(), ["-v", "error", "-y", "-f", "concat", "-safe", "0", "-i", listPath, "-c", "copy", outputPath], {
+      encoding: "utf8"
+    });
+    if (join.status !== 0) throw new Error(`Could not join Android recording segments: ${failure(join)}`);
+  } finally {
+    fs.rmSync(listPath, { force: true });
+  }
+}
+function ffmpegPath() {
+  return process.env.FFMPEG_PATH || "ffmpeg";
+}
+function screenrecordPids(adb) {
+  const result = adb(["shell", "pidof", "screenrecord"]);
+  if (result.status !== 0) return [];
+  return result.stdout.trim().split(/\s+/u).filter(Boolean);
+}
+function settles(promise, ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), ms);
+    void promise.then(() => {
+      clearTimeout(timer);
+      resolve(true);
+    });
+  });
+}
+function failure(result) {
+  return result.error?.message || result.stderr?.trim() || result.stdout?.trim() || `exit ${result.status ?? "unknown"}`;
+}
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export {
+  createAndroidScreenrecordRecorder
+};

package/dist/adapters/mobile/readiness.js

@@ -18,7 +18,8 @@ const mobileReadiness = {
   orphanDevServers: detectOrphanMetros,
   captureProviders: ["simctl", "adb"],
   fixes: [{ id: "mobile-perps-env", apply: (target) => ensureMobilePerpsEnvironment(target).length > 0 }],
-  devices: async () => (await import("./devices.js")).mobileDevices
+  devices: async () => (await import("./devices.js")).mobileDevices,
+  recorder: async () => (await import("./run.js")).mobileRecorderCheck()
 };
 async function mobileRuntimeDecision(target, options) {
   const watcherPortRaw = optionString(options, "watcherPort") ?? process.env.WATCHER_PORT ?? process.env.METRO_PORT;

package/dist/adapters/mobile/recording-outcome.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import { errorMessage, manifestTarget, readCaptureHelperTiming, RecipeExecutionError } from "@farmslot/recipe-runner";
+function recordingFailure(code, cause) {
+  const reason = cause.trim().replace(/[\s.:]+$/u, "");
+  return new RecipeExecutionError("environment", `${code}: ${reason}. The run has no video.`, { code, details: { cause: reason } });
+}
+function interruptedRecorder(recorder, cause, coverage) {
+  const kept = "coveredMs" in coverage ? `${(coverage.coveredMs[0] / 1e3).toFixed(1)}-${(coverage.coveredMs[1] / 1e3).toFixed(1)} s` : `coverage unknown: ${coverage.coverageUnavailableReason}`;
+  process.stderr.write(`WARN: RECORDER_INTERRUPTED (${cause}): kept the partial video, ${kept}.
+`);
+  const entry = { ...recorder, interrupted: { code: "RECORDER_INTERRUPTED", cause, ...coverage } };
+  return entry;
+}
+function streamInterruption(text) {
+  for (const line of text.split("\n")) {
+    if (!line.includes("stream_interrupted")) continue;
+    try {
+      const event = JSON.parse(line.slice(line.indexOf("{"), line.lastIndexOf("}") + 1));
+      if (event.type !== "error" || event.code !== "stream_interrupted") continue;
+      const mediaTimeMs = typeof event.media_time_ms === "number" && event.media_time_ms >= 0 ? event.media_time_ms : void 0;
+      return {
+        cause: `stream_interrupted: ${typeof event.cause === "string" ? event.cause : "capture stream stopped"}`,
+        ...mediaTimeMs !== void 0 ? { mediaTimeMs } : {}
+      };
+    } catch {
+      continue;
+    }
+  }
+  return void 0;
+}
+function withRecordingOutcomes(recorder) {
+  return {
+    name: recorder.name,
+    get version() {
+      return recorder.version;
+    },
+    platform: recorder.platform,
+    // The runner asks this before start; a recorder that cannot record fails
+    // the run with a code, as a failed start does.
+    async doctor() {
+      let result;
+      try {
+        result = await recorder.doctor?.();
+      } catch (error) {
+        throw recordingFailure("RECORDING_FAILED", `${recorder.name} readiness check failed: ${errorMessage(error)}`);
+      }
+      if (result && !result.ok) {
+        const next = result.suggestedFix ? ` Next: ${result.suggestedFix}` : "";
+        throw recordingFailure("RECORDING_FAILED", `${recorder.name} ${result.code}: ${result.message}${next}`);
+      }
+      return result ?? { ok: true, code: "ok", message: `${recorder.name} has no readiness check.` };
+    },
+    async start(request) {
+      let active;
+      try {
+        active = await recorder.start(request);
+      } catch (error) {
+        throw coded(error) ?? recordingFailure("RECORDING_FAILED", errorMessage(error));
+      }
+      return {
+        ...active.snapshot ? { snapshot: (outputPath) => active.snapshot(outputPath) } : {},
+        async stop() {
+          try {
+            return await active.stop();
+          } catch (error) {
+            const known = coded(error);
+            if (known) throw known;
+            const interruption = streamInterruption(errorMessage(error));
+            if (!interruption) throw recordingFailure("RECORDING_FAILED", errorMessage(error));
+            if (!hasBytes(request.outputPath)) throw recordingFailure("RECORDER_INTERRUPTED", interruption.cause);
+            const timing = await readCaptureHelperTiming(request.outputPath);
+            return {
+              ...timing,
+              ...timing.timing ? { timingEvidencePath: `${path.basename(request.outputPath)}.timing.json` } : {},
+              recorder: interruptedRecorder(
+                { name: "capture-helper", platform: recorder.platform, target: manifestTarget(request.target) },
+                interruption.cause,
+                interruption.mediaTimeMs !== void 0 ? { coveredMs: [0, interruption.mediaTimeMs] } : { coverageUnavailableReason: "capture-helper reported no media time" }
+              )
+            };
+          }
+        }
+      };
+    }
+  };
+}
+function coded(error) {
+  return error instanceof RecipeExecutionError && typeof error.code === "string" ? error : void 0;
+}
+function hasBytes(file) {
+  try {
+    return fs.statSync(file).size > 0;
+  } catch {
+    return false;
+  }
+}
+export {
+  interruptedRecorder,
+  recordingFailure,
+  streamInterruption,
+  withRecordingOutcomes
+};

package/dist/adapters/mobile/recording-target.js

@@ -9,7 +9,18 @@ function resolveMobileIosSimulatorName(env = process.env) {
   const suffix = slot.includes("-") ? slot.slice(slot.lastIndexOf("-") + 1) : slot;
   return suffix || void 0;
 }
+function resolveAndroidRecorderKind(serial, env = process.env) {
+  const forced = env.METAMASK_RECIPE_MOBILE_ANDROID_RECORDER?.trim().toLowerCase();
+  if (forced === "screenrecord" || forced === "mirror") return forced;
+  if (forced) {
+    throw new Error(
+      `METAMASK_RECIPE_MOBILE_ANDROID_RECORDER must be screenrecord or mirror, not "${forced}". Next: unset METAMASK_RECIPE_MOBILE_ANDROID_RECORDER`
+    );
+  }
+  return /^emulator-\d+$/u.test(serial) ? "mirror" : "screenrecord";
+}
 export {
   resolveAndroidDeviceSerial,
+  resolveAndroidRecorderKind,
   resolveMobileIosSimulatorName
 };

package/dist/adapters/mobile/run.js

@@ -5,6 +5,7 @@ import { IOS_SIMULATOR_RECORDING_TARGET_PREFIX } from "@farmslot/adapter-rn";
 import { devicePlatformFromEnv } from "../performance/device-platform.js";
 import {
   resolveAndroidDeviceSerial,
+  resolveAndroidRecorderKind,
   resolveMobileIosSimulatorName
 } from "./recording-target.js";
 import { emitProofFailure } from "../proof-failure.js";
@@ -94,20 +95,55 @@ async function ensureMobileProofRuntime(target, _heal, state, json, deps = {}) {
 }
 const mobileRecording = {
   target: (context) => resolveMobileRecordingTarget(context),
-  // An Android device records through the mirror, with screenrecord as the
-  // fallback; otherwise the selected iOS simulator records.
   async videoRecorder() {
-    const androidSerial = resolveAndroidDeviceSerial();
-    const iosSimulator = androidSerial ? void 0 : resolveMobileIosSimulatorName();
-    if (!androidSerial && !iosSimulator) return void 0;
-    const { createAndroidVideoRecorder, createIosSimulatorVideoRecorder } = await import("@farmslot/adapter-rn");
-    if (androidSerial) {
-      const { createAndroidMirrorVideoRecorder } = await import("@farmslot/recipe-runner");
-      return createAndroidMirrorVideoRecorder({ serial: androidSerial, fallback: createAndroidVideoRecorder(androidSerial) });
-    }
-    return createIosSimulatorVideoRecorder(iosSimulator);
+    const selected = await selectMobileRecorder();
+    if (!selected) return void 0;
+    const { withRecordingOutcomes } = await import("./recording-outcome.js");
+    return withRecordingOutcomes(selected.recorder);
   }
 };
+async function selectMobileRecorder() {
+  const androidSerial = resolveAndroidDeviceSerial();
+  const iosSimulator = androidSerial ? void 0 : resolveMobileIosSimulatorName();
+  if (!androidSerial && !iosSimulator) return void 0;
+  if (androidSerial && resolveAndroidRecorderKind(androidSerial) === "screenrecord") {
+    const { createAndroidScreenrecordRecorder } = await import("./android-screenrecord.js");
+    return { recorder: createAndroidScreenrecordRecorder(androidSerial), device: androidSerial };
+  }
+  const { createAndroidVideoRecorder, createIosSimulatorVideoRecorder } = await import("@farmslot/adapter-rn");
+  if (androidSerial) {
+    const { createAndroidMirrorVideoRecorder } = await import("@farmslot/recipe-runner");
+    const mirror = createAndroidMirrorVideoRecorder({ serial: androidSerial, fallback: createAndroidVideoRecorder(androidSerial) });
+    return { recorder: mirror, device: androidSerial };
+  }
+  return { recorder: createIosSimulatorVideoRecorder(iosSimulator), device: iosSimulator };
+}
+async function mobileRecorderCheck() {
+  let selected;
+  try {
+    selected = await selectMobileRecorder();
+  } catch (error) {
+    return {
+      id: "recorder",
+      status: "fail",
+      required: true,
+      message: "No recorder can be selected for this device.",
+      detail: error instanceof Error ? error.message : String(error),
+      userAction: "unset METAMASK_RECIPE_MOBILE_ANDROID_RECORDER, then rerun mm-harness doctor"
+    };
+  }
+  if (!selected) return void 0;
+  const { recorder, device } = selected;
+  const doctor = await recorder.doctor?.() ?? { ok: true, code: "ok", message: `${recorder.name} has no readiness check.` };
+  return {
+    id: "recorder",
+    status: doctor.ok ? "pass" : "fail",
+    required: true,
+    message: doctor.ok ? `Recording on ${device} uses ${recorder.name}.` : `Recording on ${device} uses ${recorder.name}, which cannot record (${doctor.code}).`,
+    detail: doctor.message,
+    ...doctor.ok ? {} : { userAction: doctor.suggestedFix ?? "fix the recorder named above, then rerun mm-harness doctor" }
+  };
+}
 async function resolveMobileRecordingTarget(context) {
   const platform = (context.env.PLATFORM ?? process.env.PLATFORM ?? "ios").trim().toLowerCase();
   const androidSerial = resolveAndroidDeviceSerial(context.env);
@@ -176,6 +212,7 @@ export {
   ensureMobileProofRuntime,
   mobileDiagnostics,
   mobileObservation,
+  mobileRecorderCheck,
   mobileRecording,
   mobileRun
 };