@deeeed/metamask-harness 0.86.2 → 0.88.0

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

@@ -0,0 +1,274 @@
+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 { 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,
+          // The runner keeps the files finished before the failure and fails the run as CAPTURE_INTERRUPTED.
+          ...interruption ? {
+            interruption: {
+              frames: timing.timing?.framesMs.length ?? 0,
+              mediaTimeMs: timing.timing?.framesMs.at(-1) ?? 0,
+              cause: interruption
+            }
+          } : {}
+        };
+      } 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,54 @@
+import { errorMessage, 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 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) {
+            throw coded(error) ?? recordingFailure("RECORDING_FAILED", errorMessage(error));
+          }
+        }
+      };
+    }
+  };
+}
+function coded(error) {
+  return error instanceof RecipeExecutionError && typeof error.code === "string" ? error : void 0;
+}
+export {
+  recordingFailure,
+  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";
@@ -60,11 +61,17 @@ const mobileRun = {
   // An installed release artifact is opaque: it has no dev bridge and no
   // AgentStepHud, so there is nothing to draw the HUD with.
   autoHud: () => process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME !== "1",
-  // Always clear a HUD step the engine left on-device (a failed run strands
-  // the FAIL banner). Best-effort — never masks the run's real outcome.
+  // Cancel the mainnet limit orders the run opened (a failure fails the run),
+  // and always clear a HUD step the engine left on-device (a failed run strands
+  // the FAIL banner; best-effort, never masks the run's real outcome).
   async teardown(projectRoot, env) {
-    const { hideMobileHudOnTeardown } = await import("./ui.js");
-    await hideMobileHudOnTeardown(projectRoot, env);
+    try {
+      const { cancelRunMainnetOrders } = await import("../perps-mainnet-cleanup.js");
+      await cancelRunMainnetOrders(projectRoot, env, "teardown");
+    } finally {
+      const { hideMobileHudOnTeardown } = await import("./ui.js");
+      await hideMobileHudOnTeardown(projectRoot, env);
+    }
   },
   // A release artifact is checked before the overlay install; the loaded
   // source only matters for a development build the caller did not restart.
@@ -94,20 +101,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 +218,7 @@ export {
   ensureMobileProofRuntime,
   mobileDiagnostics,
   mobileObservation,
+  mobileRecorderCheck,
   mobileRecording,
   mobileRun
 };

package/dist/adapters/mobile/ui.js

@@ -109,6 +109,85 @@ function isRetryableMobileWaitError(error) {
     isRecord(error) && typeof error.code === "string" && RETRYABLE_MOBILE_WAIT_CODES.has(error.code)
   );
 }
+function hiddenRouteExpression(testId) {
+  return `(function(){
+    const hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    if (!hook || !hook.getFiberRoots) return null;
+    const hiddenAt = (props, routeKey) => {
+      const state = props.state;
+      const index = state.routes.findIndex((route) => route && route.key === routeKey);
+      if (index < 0 || typeof state.index !== 'number') return false;
+      if (state.type === 'tab') return index !== state.index;
+      if (state.type !== 'stack') return false;
+      // Mirror native-stack's getModalRouteKeys: an unset presentation after
+      // any modal-family screen is a modal too. On iOS a card pushed after a
+      // modal goes under it, so nothing hides a modal target.
+      const modal = [];
+      for (let position = 0; position <= state.index; position += 1) {
+        const descriptor = props.descriptors[state.routes[position].key];
+        if (!descriptor || !descriptor.options) return false;
+        const presentation = descriptor.options.presentation;
+        modal.push(presentation === undefined || presentation === null
+          ? modal.includes(true)
+          : !['card', 'push'].includes(presentation));
+      }
+      if (modal[index]) return false;
+      for (let above = index + 1; above <= state.index; above += 1) {
+        if (!modal[above]) return true;
+      }
+      return false;
+    };
+    const onHiddenRoute = (fiber) => {
+      let routeKey;
+      for (let owner = fiber.return; owner; owner = owner.return) {
+        const props = owner.memoizedProps;
+        if (!props) continue;
+        if (props.route && typeof props.route.key === 'string') routeKey = props.route.key;
+        if (routeKey && props.descriptors && props.state && Array.isArray(props.state.routes)
+          && hiddenAt(props, routeKey)) return true;
+      }
+      return false;
+    };
+    let matches = 0;
+    let hidden = 0;
+    const visit = (fiber) => {
+      for (; fiber; fiber = fiber.sibling) {
+        if (fiber.memoizedProps && fiber.memoizedProps.testID === ${JSON.stringify(testId)}) {
+          matches += 1;
+          try {
+            if (onHiddenRoute(fiber)) hidden += 1;
+          } catch (error) {
+            // An unreadable navigator counts as visible: never a false absent.
+          }
+        }
+        visit(fiber.child);
+      }
+    };
+    const roots = new Set();
+    for (const id of hook.renderers.keys()) (hook.getFiberRoots(id) || []).forEach((root) => roots.add(root));
+    roots.forEach((root) => visit(root.current));
+    return { matches, hidden };
+  })()`;
+}
+const NATIVE_READ_BUDGET_MS = 2500;
+async function hiddenRouteOnly(input, probeInput, payload, testId, deadline) {
+  const routes = await evalSync(probeInput, hiddenRouteExpression(testId));
+  if (!isRecord(routes) || Number(routes.matches) < 1 || routes.hidden !== routes.matches) return null;
+  const remainingMs = deadline - Date.now();
+  if (remainingMs < NATIVE_READ_BUDGET_MS) return null;
+  let timer;
+  const observed = await Promise.race([
+    observeNativeUi({ refs: ["ui.visible"], node: payload }, input.context),
+    new Promise((resolve) => {
+      timer = setTimeout(() => resolve(null), remainingMs);
+    })
+  ]).finally(() => clearTimeout(timer));
+  if (!isRecord(observed) || Array.isArray(observed.warnings) && observed.warnings.length > 0) return null;
+  const visible = isRecord(observed.observations) ? observed.observations["ui.visible"] : void 0;
+  if (!isRecord(visible) || !Array.isArray(visible.items) || visible.truncated === true) return null;
+  const nativeVisible = visible.items.some((item) => isRecord(item) && item.test_id === testId && item.visible !== false);
+  return nativeVisible ? null : { hiddenRoute: true, nativeVisible: false };
+}
 async function waitForMobileTarget(input, payload) {
   const timeoutMs = Number(payload.timeout_ms ?? payload.timeoutMs ?? 1e4);
   const deadline = Date.now() + timeoutMs;
@@ -162,8 +241,22 @@ async function waitForMobileTarget(input, payload) {
       );
     }
     lastResult = result;
-    const present = result.present === true;
-    const visible = result.visible === true;
+    let present = result.present === true;
+    let visible = result.visible === true;
+    let cachedRoute = null;
+    if (expectsAbsent && present && testId && visibility === "tree") {
+      try {
+        cachedRoute = await hiddenRouteOnly(input, probeInput, payload, testId, deadline);
+      } catch (error) {
+        if (!isRetryableMobileWaitError(error)) throw error;
+        lastBridgeError = error;
+      }
+      if (cachedRoute) {
+        present = false;
+        visible = false;
+        lastResult = { ...result, ...cachedRoute };
+      }
+    }
     let textMatched = !expectedText || textMatch === "contains";
     if (expectedText && textMatch === "exact" && textExpression) {
       try {
@@ -186,6 +279,7 @@ async function waitForMobileTarget(input, payload) {
         present,
         visible,
         visibility,
+        ...cachedRoute ?? {},
         ...isRecord(result.rect) ? { rect: result.rect } : {}
       };
     }