@deeeed/metamask-harness 0.34.1 → 0.34.3

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.34.3 - 2026-08-12
+
+### Added
+
+- Add a composable headless Core Perps snapshot recipe that calls the public controller APIs with configurable Terminal endpoints.
+- Add route-agnostic Extension actions and a reusable recipe for post-GC navigation slopes, detached-DOM growth, and equal-duration idle-control memory measurement.
+
+### Fixed
+
+- Preserve an already-foregrounded Android app while recipes toggle network state, avoiding an unnecessary launcher intent during recovery validation.
+
+## 0.34.2 - 2026-08-11
+
+### Added
+
+- Add composable platform-neutral Homepage Perps position setup and background-lifecycle measurement recipes.
+
+### Fixed
+
+- Give Mobile foreground lifecycle actions the same bounded 60-second runtime-reacquisition window as launch and restart.
+- Classify iOS foreground as a same-process resume or cold relaunch, and let reconnect recipes reject process-evicted samples immediately.
+- Quiesce active Perps streams before direct-CDP performance cache removal and verify the disk keys remain absent.
+- Exclude queued pre-lifecycle socket frames from lifecycle-specific Fresh DFD measurements.
+
 ## 0.34.1 - 2026-08-09
 
 ### Fixed

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -30,6 +30,19 @@ const {
 const { cdpEval, cdpEvalAsync } = require('./lib/cdp-eval.cjs');
 const { buildArmSnippet, buildCollectSnippet } = require('./lib/issue-capture.cjs');
 
+function parseHomepagePerformanceConsoleEvent(params) {
+  const marker = '[HomepagePerf] ';
+  for (const arg of params?.args || []) {
+    const text = typeof arg?.value === 'string' ? arg.value : '';
+    const markerIndex = text.indexOf(marker);
+    if (markerIndex < 0) continue;
+    try {
+      return JSON.parse(text.slice(markerIndex + marker.length));
+    } catch {}
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -387,6 +400,214 @@ const COMMANDS = {
     return { ...result, deviceName };
   },
 
+  async 'measure-scroll-transition'(client, args, { deviceName } = {}) {
+    let options;
+    try {
+      options = JSON.parse(args[0] || '{}');
+    } catch (error) {
+      throw new Error(`Invalid measure-scroll-transition options: ${error.message}`);
+    }
+    const timeoutMs = Number(options.timeoutMs);
+    const pollIntervalMs = Number(options.pollIntervalMs ?? 100);
+    const visibleEventStage = options.visibleEventStage || null;
+    const visibleEventGraceMs = Number(options.visibleEventGraceMs ?? 0);
+    const targetCount = Number(Boolean(options.targetTestId)) + Number(Boolean(options.targetText));
+    if (
+      !options.fromTestId ||
+      targetCount !== 1 ||
+      !Number.isFinite(timeoutMs) ||
+      timeoutMs <= 0 ||
+      !Number.isFinite(pollIntervalMs) ||
+      pollIntervalMs < 16 ||
+      (visibleEventStage !== null && typeof visibleEventStage !== 'string') ||
+      !Number.isFinite(visibleEventGraceMs) ||
+      visibleEventGraceMs < 0
+    ) {
+      throw new Error(
+        'measure-scroll-transition requires fromTestId, exactly one targetTestId or targetText, a positive timeoutMs, pollIntervalMs >= 16, and a non-negative visibleEventGraceMs.',
+      );
+    }
+    const visibleEvents = [];
+    let removeConsoleListener = null;
+    if (visibleEventStage) {
+      removeConsoleListener = client.on('Runtime.consoleAPICalled', (params) => {
+        const payload = parseHomepagePerformanceConsoleEvent(params);
+        if (payload?.stage === visibleEventStage) visibleEvents.push(payload);
+      });
+      await client.send('Runtime.enable');
+    }
+    const targetQuery = options.targetTestId
+      ? { testId: options.targetTestId, visibility: 'viewport' }
+      : { textContains: options.targetText, visibility: 'viewport' };
+    const from = await cdpEvalAsync(
+      client,
+      `globalThis.__AGENTIC__?.queryUiTarget(${JSON.stringify({
+        testId: options.fromTestId,
+        visibility: 'viewport',
+      })})`,
+      timeoutMs,
+    );
+    if (from?.visible !== true) {
+      return {
+        ok: false,
+        error: 'measurement start target is not visible',
+        from,
+        deviceName,
+      };
+    }
+    let walletReady = null;
+    if (options.requireWalletReady === true) {
+      walletReady = await cdpEval(
+        client,
+        `(function(){
+          var route = globalThis.__AGENTIC__?.getRoute() || null;
+          var account = null;
+          try { account = globalThis.__AGENTIC__?.getSelectedAccount() || null; } catch(e) {}
+          var address = account && typeof account.address === 'string' ? account.address : '';
+          var id = account && typeof account.id === 'string' ? account.id : '';
+          return {
+            ready: Boolean(address || id) && String(route && route.name || '') !== 'Login',
+            route: route,
+            accountPresent: Boolean(address || id),
+            observedAtMs: performance.now(),
+          };
+        })()`,
+      );
+      if (walletReady?.ready !== true) {
+        return {
+          ok: false,
+          error: 'wallet is not ready at measurement start',
+          walletReady,
+          from,
+          deviceName,
+        };
+      }
+    }
+    const started = await cdpEvalAsync(
+      client,
+      `(function(){
+        const scrollStartedAtMs = performance.now();
+        const startedAtMs = ${
+          walletReady === null
+            ? 'scrollStartedAtMs'
+            : JSON.stringify(Number(walletReady.observedAtMs))
+        };
+        return Promise.resolve(globalThis.__AGENTIC__?.scrollView(${JSON.stringify({
+          testId: options.scrollTestId,
+          offset: options.offset,
+          animated: options.animated,
+          intoView: false,
+        })})).then(function(scroll){ return { startedAtMs, scrollStartedAtMs, scroll }; });
+      })()`,
+      timeoutMs,
+    );
+    if (started?.scroll?.ok === false) {
+      return {
+        ok: false,
+        error: 'scroll failed',
+        ...started,
+        from,
+        deviceName,
+      };
+    }
+    const hostDeadline = Date.now() + timeoutMs;
+    if (visibleEventStage && visibleEventGraceMs > 0) {
+      const eventDeadline = Math.min(hostDeadline, Date.now() + visibleEventGraceMs);
+      while (Date.now() <= eventDeadline) {
+        const event = visibleEvents.find(
+          (candidate) =>
+            Number(candidate.frame_checkpoint_monotonic_ms) >=
+            Number(started.scrollStartedAtMs),
+        );
+        if (event) {
+          removeConsoleListener?.();
+          const observedAtMs = Number(event.frame_checkpoint_monotonic_ms);
+          return {
+            ok: true,
+            clock: 'performance.now',
+            observationSource: 'runtime-console-event',
+            durationMs: observedAtMs - started.startedAtMs,
+            scrollDurationMs: observedAtMs - started.scrollStartedAtMs,
+            appVisibleDurationMs: Number(event.duration_ms),
+            pollIntervalMs,
+            preScrollDelayMs: started.scrollStartedAtMs - started.startedAtMs,
+            startedAtMs: started.startedAtMs,
+            scrollStartedAtMs: started.scrollStartedAtMs,
+            observedAtMs,
+            visibleEvent: event,
+            ...(walletReady ? { walletReady } : {}),
+            from,
+            scroll: started.scroll,
+            deviceName,
+          };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+    }
+    while (Date.now() <= hostDeadline) {
+      const remainingMs = hostDeadline - Date.now();
+      if (remainingMs <= 1_000) break;
+      const queryTimeoutMs = Math.min(5_000, remainingMs);
+      const observation = await cdpEvalAsync(
+        client,
+        `(function(){
+          return Promise.resolve(globalThis.__AGENTIC__?.queryUiTarget(${JSON.stringify(targetQuery)})).then(function(target){
+            return { target, observedAtMs: performance.now() };
+          });
+        })()`,
+        queryTimeoutMs,
+      );
+      const requiredPresent =
+        observation?.target?.visible === true && options.requiredPresentTestId
+        ? await cdpEvalAsync(
+            client,
+            `globalThis.__AGENTIC__?.queryUiTarget(${JSON.stringify({
+              testId: options.requiredPresentTestId,
+              visibility: 'tree',
+            })})`,
+            queryTimeoutMs,
+          )
+        : null;
+      if (
+        observation?.target?.visible === true &&
+        (!options.requiredPresentTestId || requiredPresent?.present === true)
+      ) {
+        return {
+          ok: true,
+          clock: 'performance.now',
+          durationMs: observation.observedAtMs - started.startedAtMs,
+          scrollDurationMs:
+            observation.observedAtMs - started.scrollStartedAtMs,
+          pollIntervalMs,
+          observationSource: visibleEventStage
+            ? 'fiber-poll-after-event-grace'
+            : 'fiber-poll',
+          preScrollDelayMs:
+            started.scrollStartedAtMs - started.startedAtMs,
+          startedAtMs: started.startedAtMs,
+          scrollStartedAtMs: started.scrollStartedAtMs,
+          observedAtMs: observation.observedAtMs,
+          ...(walletReady ? { walletReady } : {}),
+          from,
+          target: observation.target,
+          ...(requiredPresent ? { requiredPresent } : {}),
+          scroll: started.scroll,
+          deviceName,
+        };
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    removeConsoleListener?.();
+    return {
+      ok: false,
+      error: 'timed out waiting for visible transition target',
+      durationMs: await cdpEval(client, `performance.now() - ${Number(started.startedAtMs)}`),
+      startedAtMs: started.startedAtMs,
+      scrollStartedAtMs: started.scrollStartedAtMs,
+      deviceName,
+    };
+  },
+
   async 'set-input'(client, args, { deviceName } = {}) {
     const testId = args[0];
     const value = args.slice(1).join(' ');
@@ -754,6 +975,7 @@ Commands:
   press-text <text>                     Press a component containing visible text
   scroll-view [--test-id <id>] [--offset <n>] [--animated]
                                        Scroll a ScrollView/FlatList
+  measure-scroll-transition <json>    Scroll and measure a visible target using one CDP session
   set-input <testId> <value>           Set text input value by testID (calls onChangeText)
   sentry-debug [enable|disable]          Patch Sentry to log errors to console with [SENTRY-DEBUG] prefix
   unlock <password>                      Unlock wallet (inject password + press login button via fiber tree)

package/adapters/mobile/bridge-runtime/console-forwarder.cjs

@@ -61,6 +61,11 @@ const statePath = `${out}.forwarder-state.json`;
 // buffer replay backfills everything missed, so no lines are lost.
 const LOCK_FILE = path.join(path.dirname(out), 'cdp-bridge.lock');
 const LOCK_SETTLE_MS = 1500;
+// The inspector can deliver NEW_DEBUGGER_OPENED after a short bridge command
+// has already removed its lock. Keep a narrow release grace so that delayed
+// close event is not mistaken for a human DevTools takeover (which otherwise
+// suppresses device logs for five minutes).
+const BRIDGE_RELEASE_GRACE_MS = 3000;
 const LOCK_STALE_MS = 30000; // unreadable lock body: crashed bridge must not block logs forever
 // dev-middleware serves one debugger slot per device; when a debugger we do not
 // coordinate with (React Native DevTools) takes it, re-attaching would evict
@@ -105,9 +110,20 @@ function yieldSessions() {
 }
 
 let resumeTimer = null;
+let bridgeCoordinationUntil = 0;
+
+function noteBridgeCoordination() {
+  bridgeCoordinationUntil = Date.now() + BRIDGE_RELEASE_GRACE_MS;
+}
+
+function bridgeCoordinationRecent() {
+  return Date.now() < bridgeCoordinationUntil;
+}
+
 try {
   fs.watch(path.dirname(out), (_event, filename) => {
     if (filename !== path.basename(LOCK_FILE)) return;
+    noteBridgeCoordination();
     if (bridgeLockActive()) {
       if (resumeTimer) {
         clearTimeout(resumeTimer);
@@ -272,7 +288,11 @@ function connect(target) {
     // another one attaches. With no bridge lock present that debugger is a
     // human's DevTools session — back off long instead of evicting them back.
     const why = event && event.reason ? String(event.reason) : '';
-    if (why.includes('NEW_DEBUGGER_OPENED') && !bridgeLockActive()) {
+    if (
+      why.includes('NEW_DEBUGGER_OPENED') &&
+      !bridgeLockActive() &&
+      !bridgeCoordinationRecent()
+    ) {
       foreignDebuggerUntil.set(deviceId, Date.now() + FOREIGN_DEBUGGER_BACKOFF_MS);
       process.stderr.write(
         `console-forwarder: another debugger took ${name}; standing down for ${FOREIGN_DEBUGGER_BACKOFF_MS / 60000} min\n`,
@@ -285,6 +305,7 @@ function connect(target) {
 
 function discover() {
   if (bridgeLockActive()) {
+    noteBridgeCoordination();
     schedule(DISCOVER_ACTIVE_MS);
     return;
   }

package/adapters/mobile/bridge-runtime/lib/ws-client.cjs

@@ -31,6 +31,7 @@ function createWSClient(wsUrl, timeout) {
     const ws = new WebSocketImpl(wsUrl);
     let msgId = 0;
     const pending = new Map();
+    const eventHandlers = new Map();
 
     const timer = setTimeout(() => {
       ws.close();
@@ -69,6 +70,15 @@ function createWSClient(wsUrl, timeout) {
             ws.send(msg);
           });
         },
+        on(method, handler) {
+          const handlers = eventHandlers.get(method) || new Set();
+          handlers.add(handler);
+          eventHandlers.set(method, handlers);
+          return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0) eventHandlers.delete(method);
+          };
+        },
         close() {
           ws.close();
         },
@@ -92,6 +102,13 @@ function createWSClient(wsUrl, timeout) {
         } else {
           res(msg.result);
         }
+        return;
+      }
+      if (!msg.method) return;
+      for (const handler of eventHandlers.get(msg.method) || []) {
+        try {
+          handler(msg.params || {});
+        } catch {}
       }
     };
 
@@ -106,6 +123,7 @@ function createWSClient(wsUrl, timeout) {
         rej(coded(new Error('WebSocket closed'), BRIDGE_ERROR_CODES.WS_CLOSED));
       }
       pending.clear();
+      eventHandlers.clear();
     };
   });
 }

package/adapters/mobile/open-device.sh

@@ -522,10 +522,6 @@ else
   ADB_ARGS=()
   [ -n "$ADB_SERIAL_ARG" ] && ADB_ARGS+=("-s" "$ADB_SERIAL_ARG")
 
-  # Reverse-tunnel Metro port so the device can reach localhost:PORT.
-  "$ADB_BIN" "${ADB_ARGS[@]}" reverse "tcp:${PORT}" "tcp:${PORT}" >/dev/null 2>&1 || \
-    printf 'open-device: adb reverse failed (non-fatal — device may already be reachable)\n' >&2
-
   LAUNCHED=false
   for PKG in "${ANDROID_PKGS[@]}"; do
     if ! ensure_android_app_for_mode "$PKG" "$PREFLIGHT_MODE" "${ADB_ARGS[@]}"; then
@@ -539,6 +535,12 @@ else
       printf 'Restarting Android dev client %s\n' "$PKG" >&2
     fi
 
+    # Installing/rebuilding a dev client can invalidate adb reverse mappings.
+    # Restore Metro reachability only after the app is ensured, immediately
+    # before opening the development-client URL.
+    "$ADB_BIN" "${ADB_ARGS[@]}" reverse "tcp:${PORT}" "tcp:${PORT}" >/dev/null 2>&1 || \
+      printf 'open-device: adb reverse failed (non-fatal — device may already be reachable)\n' >&2
+
     ENCODED_URL="$(urlencode "http://localhost:${PORT}?disableOnboarding=1" 2>/dev/null \
       || printf 'http%%3A%%2F%%2Flocalhost%%3A%s%%3FdisableOnboarding%%3D1' "$PORT")"
     DEEP_LINK="expo-metamask://expo-development-client/?url=${ENCODED_URL}"

package/dist/adapters/mobile/prepare.js

@@ -116,10 +116,7 @@ async function prepareMobile(target, opts = {}) {
       );
     }
     const launch = await dispatchActionSequence(
-      withAppRestart(
-        launchActions(path.resolve(target)),
-        restartApp || iosAccessibilityChanged
-      ),
+      withAppRestart(launchActions(path.resolve(target)), true),
       target,
       platform,
       json,

package/dist/adapters.js

@@ -39,11 +39,16 @@ const LIVE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.ensure_orders",
   "metamask.perps.assert_orders",
   "metamask.perps.clear_performance_caches",
+  "metamask.perps.measure_homepage_visible",
+  "metamask.perps.prepare_local_snapshot_endpoint",
   "metamask.perps.start_state",
   "metamask.perps.teardown_state",
   "metamask.perps.capture_performance"
 ]);
-const CORE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set(["metamask.perps.read_account"]);
+const CORE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
+  "metamask.perps.read_account",
+  "metamask.perps.read_snapshot"
+]);
 const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
   "metamask.wallet.ensure_unlocked",
@@ -198,9 +203,13 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
     "metamask.perps.start_state",
     "metamask.perps.teardown_state",
     "metamask.perps.capture_performance",
-    ...platform === "mobile" ? ["metamask.perps.clear_performance_caches"] : [],
+    ...platform === "mobile" ? [
+      "metamask.perps.clear_performance_caches",
+      "metamask.perps.measure_homepage_visible",
+      "metamask.perps.prepare_local_snapshot_endpoint"
+    ] : [],
     // read_account is core-only: only the headless core adapter implements it.
-    ...platform === "core" ? ["metamask.perps.read_account"] : []
+    ...platform === "core" ? ["metamask.perps.read_account", "metamask.perps.read_snapshot"] : []
   ];
   const bundled = new Set(bundledActions);
   const actions = [.../* @__PURE__ */ new Set([...bundledActions, ...declaredCustomActions])];
@@ -283,6 +292,17 @@ function resolveMobileWaitTarget(payload) {
     visibility: expected === "visible" || expected === "hidden" ? "viewport" : "tree"
   };
 }
+const RETRYABLE_MOBILE_WAIT_CODES = /* @__PURE__ */ new Set([
+  MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
+  MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+  MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
+  MOBILE_BRIDGE_ERROR_CODES.METRO_UNREACHABLE
+]);
+function isRetryableMobileWaitError(error) {
+  return Boolean(
+    isRecord(error) && typeof error.code === "string" && RETRYABLE_MOBILE_WAIT_CODES.has(error.code)
+  );
+}
 async function waitForMobileTarget(input, payload) {
   const timeoutMs = Number(payload.timeout_ms ?? payload.timeoutMs ?? 1e4);
   const deadline = Date.now() + timeoutMs;
@@ -308,9 +328,28 @@ async function waitForMobileTarget(input, payload) {
       })()` : null;
   let lastResult = null;
   let lastText = null;
+  let lastBridgeError = null;
   const expectsAbsent = expected === "absent" || expected === "hidden" || expected === "not_present";
   while (Date.now() <= deadline) {
-    const result = await evalAsync(input, queryExpression);
+    const remainingMs = Math.max(1, deadline - Date.now());
+    const probeTimeoutMs = Math.min(5e3, remainingMs);
+    const probeInput = {
+      ...input,
+      node: {
+        ...input.node,
+        bridge_timeout_ms: probeTimeoutMs,
+        cdp_timeout_ms: probeTimeoutMs
+      }
+    };
+    let result;
+    try {
+      result = await evalAsync(probeInput, queryExpression);
+    } catch (error) {
+      if (!isRetryableMobileWaitError(error)) throw error;
+      lastBridgeError = error;
+      await sleep(250);
+      continue;
+    }
     if (!isRecord(result) || result.unsupported === true) {
       throw new Error(
         "Mobile ui.wait_for requires the current __AGENTIC__.queryUiTarget bridge for text-only or viewport-visible assertions."
@@ -321,7 +360,14 @@ async function waitForMobileTarget(input, payload) {
     const visible = result.visible === true;
     let textMatched = !expectedText || textMatch === "contains";
     if (expectedText && textMatch === "exact" && textExpression) {
-      lastText = await evalSync(input, textExpression);
+      try {
+        lastText = await evalSync(probeInput, textExpression);
+      } catch (error) {
+        if (!isRetryableMobileWaitError(error)) throw error;
+        lastBridgeError = error;
+        await sleep(250);
+        continue;
+      }
       textMatched = traceText(lastText) === expectedText;
     }
     const matched = expected === "visible" ? visible && textMatched : expected === "hidden" ? !visible : expectsAbsent ? !present : present && textMatched;
@@ -344,8 +390,9 @@ async function waitForMobileTarget(input, payload) {
     expectedText ? `text ${textMatch} ${JSON.stringify(expectedText)}` : ""
   ].filter(Boolean).join(" with ");
   const exactReason = textMatch === "exact" ? `; last text=${JSON.stringify(lastText)}` : "";
+  const bridgeReason = lastBridgeError ? `; last bridge error=${traceText(lastBridgeError)}` : "";
   throw new Error(
-    `Timed out waiting for mobile ${target} to be ${expected}; last result=${JSON.stringify(lastResult)}${exactReason}.`
+    `Timed out waiting for mobile ${target} to be ${expected}; last result=${JSON.stringify(lastResult)}${exactReason}${bridgeReason}.`
   );
 }
 const MOBILE_BRIDGE_HANDLERS = {
@@ -427,6 +474,48 @@ async function handleMobileScroll(payload, context) {
   const testId = optionalScalarText(payload.test_id ?? payload.testID, "ui.scroll.test_id");
   const offset = scalarText(payload.offset ?? payload.delta_y ?? payload.deltaY, "ui.scroll.offset", "600");
   const intoView = payload.scroll_into_view === true || payload.into_view === true;
+  const measureFromTestId = optionalScalarText(
+    payload.measure_from_test_id ?? payload.measureFromTestId,
+    "ui.scroll.measure_from_test_id"
+  );
+  const measureTargetTestId = optionalScalarText(
+    payload.measure_target_test_id ?? payload.measureTargetTestId,
+    "ui.scroll.measure_target_test_id"
+  );
+  const measureTargetText = optionalScalarText(
+    payload.measure_target_text ?? payload.measureTargetText,
+    "ui.scroll.measure_target_text"
+  );
+  const measureTargetCount = Number(Boolean(measureTargetTestId)) + Number(Boolean(measureTargetText));
+  const measureRequiredPresentTestId = optionalScalarText(
+    payload.measure_required_present_test_id ?? payload.measureRequiredPresentTestId,
+    "ui.scroll.measure_required_present_test_id"
+  );
+  if (Boolean(measureFromTestId) !== (measureTargetCount === 1)) {
+    throw new Error(
+      "ui.scroll visible-transition measurement requires measure_from_test_id and exactly one of measure_target_test_id or measure_target_text."
+    );
+  }
+  if (measureFromTestId && measureTargetCount === 1) {
+    if (intoView) {
+      throw new Error(
+        "ui.scroll visible-transition measurement uses an explicit offset and does not support scroll_into_view."
+      );
+    }
+    return measureMobileScrollTransition(input, {
+      animated: payload.animated === true,
+      fromTestId: measureFromTestId,
+      offset: Number(offset),
+      ...measureTargetTestId ? { targetTestId: measureTargetTestId } : {},
+      ...measureTargetText ? { targetText: measureTargetText } : {},
+      ...measureRequiredPresentTestId ? { requiredPresentTestId: measureRequiredPresentTestId } : {},
+      timeoutMs: Math.max(
+        1,
+        Number(payload.timeout_ms ?? payload.timeoutMs ?? 3e4)
+      ),
+      ...testId ? { scrollTestId: testId } : {}
+    });
+  }
   if (testId && intoView) {
     const before = await queryMobileViewportTarget(input, testId);
     if (before.visible === true) {
@@ -448,12 +537,23 @@ async function handleMobileScroll(payload, context) {
     ...intoView ? ["--into-view"] : [],
     animatedFlag(payload)
   ] : ["scroll-view", "--offset", offset, animatedFlag(payload)];
-  const result = await bridgeCommand(input, args);
+  const timeoutMs = Math.max(0, Number(payload.timeout_ms ?? payload.timeoutMs ?? 5e3));
+  const deadline = Date.now() + timeoutMs;
+  let result;
+  while (true) {
+    try {
+      result = await bridgeCommand(input, args);
+      break;
+    } catch (error) {
+      if (!testId || Date.now() >= deadline) throw error;
+      await sleep(100);
+    }
+  }
   if (testId && intoView) {
     const after = await waitForMobileViewportTarget(
       input,
       testId,
-      Number(payload.timeout_ms ?? payload.timeoutMs ?? 5e3)
+      timeoutMs
     );
     if (after.visible !== true) {
       throw new Error(
@@ -466,6 +566,36 @@ async function handleMobileScroll(payload, context) {
     intoView
   };
 }
+async function measureMobileScrollTransition(input, options) {
+  const result = await bridgeCommand(
+    {
+      ...input,
+      node: {
+        ...input.node,
+        bridge_timeout_ms: options.timeoutMs + 5e3,
+        cdp_timeout_ms: options.timeoutMs + 5e3
+      }
+    },
+    ["measure-scroll-transition", JSON.stringify(options)]
+  );
+  if (!isRecord(result) || result.unsupported === true) {
+    throw new Error(
+      "ui.scroll visible-transition measurement requires queryUiTarget and scrollView on the current mobile bridge."
+    );
+  }
+  if (result.ok !== true) {
+    throw new Error(
+      `ui.scroll visible-transition measurement failed: ${traceText(result.error ?? result)}.`
+    );
+  }
+  return {
+    ...result,
+    measureFromTestId: options.fromTestId,
+    ...options.targetTestId ? { measureTargetTestId: options.targetTestId } : {},
+    ...options.targetText ? { measureTargetText: options.targetText } : {},
+    ...options.requiredPresentTestId ? { measureRequiredPresentTestId: options.requiredPresentTestId } : {}
+  };
+}
 async function queryMobileViewportTarget(input, testId) {
   const expression = `(function(){
     const api = globalThis.__AGENTIC__;
@@ -851,6 +981,7 @@ export {
   createMetaMaskUiTransport,
   hideMobileHudOnTeardown,
   isMobileHudLifecycleSkip,
+  isRetryableMobileWaitError,
   normalizeUiWaitNode,
   resolveMobileWaitTarget
 };

package/dist/commands/launch/mobile.js

@@ -1,18 +1,32 @@
 import { prepareMobile } from "../../adapters/mobile/prepare.js";
+import {
+  mobileSourceCheck,
+  recordMobileSourceBaseline
+} from "../../adapters/mobile/source-freshness.js";
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
+import { EXIT } from "../shared.js";
 async function launchMobile(target, mobileTarget, tier, json, restartApp = false, clearMetro = false) {
   await ensureHarnessFresh(target, "mobile");
   const platform = mobileTarget ?? "ios";
   const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : void 0;
   const preflightMode = tier === "build" ? "rebuild-native" : "fast";
-  return prepareMobile(target, {
+  const source = mobileSourceCheck(target);
+  const result = await prepareMobile(target, {
     platform,
     json,
     watcherPort,
     preflightMode,
-    restartApp,
+    restartApp: restartApp || source.status !== "current",
     clearMetro
   });
+  if (result.status !== 0) return result;
+  if (!recordMobileSourceBaseline(target, source.fingerprint)) {
+    const message = "Mobile source changed while the app was launching; the loaded-source baseline was not recorded.\n  Next: re-run mm-harness launch.";
+    if (!json) process.stderr.write(`${message}
+`);
+    return { status: EXIT.runtime, output: message };
+  }
+  return result;
 }
 export {
   launchMobile