@deeeed/metamask-harness 0.34.0 → 0.34.2

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 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
+
+- Launch Mobile Metro through the product's canonical watcher while preserving slot, build, Sentry, and Segment environment settings, applying cache clears only to the selected Metro instance, and removing the config override that could corrupt cold bundles.
+- Pin native Mobile builds to the exact supported Main or Flask app identity and Android device, rejecting ambiguous physical-device names instead of building or launching on the wrong target.
+- Clean up timed-out Metro process groups safely and require the cold-disk-cache Perps freshness gate to report the expected lifecycle.
+- Allow performance recipes to enforce a first-fresh socket-to-subscriber latency budget for a stream and subscriber throttle, optionally scoped to a lifecycle while always reporting the observed lifecycle.
+- Allow Mobile wallet unlock actions to use their declared target and unlock timeouts without the live-adapter process ending first.
+- Remove Android's 180-second `screenrecord` cap so `--record-video=full-run` covers long recipe runs.
+- Retry empty Metro target lists, derive the Android model pin from `ADB_SERIAL`, and use pin-aware wallet status while Hermes re-registers between recipe actions.
+- Keep compound Mobile actions under one debugger lease so nested bridge calls cannot race another recipe action.
+- Let Android `scroll_into_view` fall back to a scrollable ancestor when the target itself is not a scroll container.
+- Leave Metro's worker count at its native default unless `METRO_MAX_WORKERS` is explicitly configured.
+- Bound each Mobile wallet-status probe by its polling deadline, raise the default unlock verification window to 30 seconds, and give the Android cold-no-cache recipe an explicit cold-start allowance, preventing a successful physical-device unlock from being reported as a timeout.
+
 ## 0.34.0 - 2026-08-07
 
 ### Fixed

package/adapters/manifest.json

@@ -42,14 +42,6 @@
       "inputs": "--target --port --log --pid-file [--workers] [--clear]",
       "outputs": "Metro PID/launch metadata and redirected log; exit 0/1/2"
     },
-    {
-      "id": "mobile/metro-config",
-      "entry": "adapters/mobile/metro-config.cjs",
-      "kind": "module",
-      "purpose": "Preserve the product Metro config while excluding harness-owned checkout temp artifacts.",
-      "inputs": "base Metro config; env MM_HARNESS_METRO_PROJECT_ROOT, MM_HARNESS_METRO_BASE_CONFIG",
-      "outputs": "merged Metro config with resolver.blockList for <projectRoot>/temp"
-    },
     {
       "id": "mobile/stop-metro",
       "entry": "adapters/mobile/stop-metro.sh",

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
 // ---------------------------------------------------------------------------
@@ -322,7 +335,11 @@ const COMMANDS = {
     const optsJson = JSON.stringify({ testId, offset, animated, intoView });
     // Try __AGENTIC__ bridge first, fall back to inline fiber walking
     const expr = `(function() {
-      if (globalThis.__AGENTIC__?.scrollView) return globalThis.__AGENTIC__.scrollView(${optsJson});
+      // The app helper implements generic scrolling by searching inside the
+      // selector fiber. For into-view requests the scroll container is commonly
+      // an ancestor (for example, a Wallet Home section row), so use the
+      // ancestor-aware bridge fallback below instead.
+      if (!${intoView} && globalThis.__AGENTIC__?.scrollView) return globalThis.__AGENTIC__.scrollView(${optsJson});
       var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
       if (!hook) return { ok: false, error: 'No React DevTools hook' };
       var renderers = hook.renderers;
@@ -383,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(' ');
@@ -681,6 +906,11 @@ const BRIDGE_LOCK_FILE = path.join(
   process.env.RECIPE_RUNTIME_DIR || path.join('temp', 'recipe', 'runtime'),
   'cdp-bridge.lock',
 );
+const BRIDGE_LOCK_OWNER_PID = /^\d+$/.test(
+  process.env.CDP_BRIDGE_LOCK_OWNER_PID || '',
+)
+  ? process.env.CDP_BRIDGE_LOCK_OWNER_PID
+  : String(process.pid);
 
 // Ownership semantics: last writer wins. Each bridge stamps its own pid; the
 // forwarder honors the lock while the pid IN THE FILE is alive. Overlapping
@@ -691,7 +921,7 @@ let bridgeLockHeld = false;
 
 function acquireBridgeLock() {
   try {
-    fs.writeFileSync(BRIDGE_LOCK_FILE, String(process.pid));
+    fs.writeFileSync(BRIDGE_LOCK_FILE, BRIDGE_LOCK_OWNER_PID);
     bridgeLockHeld = true;
   } catch {
     // Lock is best-effort: a missing runtime dir must not break bridge commands.
@@ -745,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)
@@ -765,7 +996,7 @@ Environment:
     process.exit(0);
   }
 
-  const handler = COMMANDS[command];
+  const handler = COMMANDS[command === 'status-selected' ? 'status' : command];
   if (!handler) {
     console.error(`Unknown command: ${command}`);
     console.error(`Available: ${Object.keys(COMMANDS).join(', ')}`);
@@ -780,6 +1011,8 @@ Environment:
   const timeout = Number.parseInt(process.env.CDP_TIMEOUT || '5000', 10);
 
   // `status` probes ALL connected targets so both platforms are visible.
+  // `status-selected` falls through to the normal pinned discovery path for
+  // action code that must survive one device's Hermes runtime rotation.
   if (command === 'status') {
     const { discoverAllTargets } = require('./lib/target-discovery.cjs');
     const allTargets = await discoverAllTargets(port);

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/target-discovery.cjs

@@ -6,7 +6,12 @@ const { createWSClient } = require('./ws-client.cjs');
 const { BRIDGE_ERROR_CODES, coded } = require('./bridge-errors.cjs');
 
 const FETCH_TIMEOUT_MS = Number.parseInt(process.env.CDP_TIMEOUT || '30000', 10);
-const FETCH_RETRIES = Number.parseInt(process.env.CDP_DISCOVERY_RETRIES || '3', 10);
+const DISCOVERY_RETRY_DELAY_MS = 500;
+const FETCH_RETRIES = Number.parseInt(
+  process.env.CDP_DISCOVERY_RETRIES ||
+    String(Math.max(3, Math.ceil(FETCH_TIMEOUT_MS / DISCOVERY_RETRY_DELAY_MS))),
+  10,
+);
 
 /** Fetch JSON from a URL (http only, no external deps) */
 function fetchJSONOnce(url) {
@@ -43,7 +48,9 @@ async function fetchJSON(url, acceptResponse) {
       lastError = error;
     }
     if (attempt === FETCH_RETRIES) break;
-    await new Promise((resolve) => setTimeout(resolve, attempt * 1000));
+    await new Promise((resolve) =>
+      setTimeout(resolve, DISCOVERY_RETRY_DELAY_MS),
+    );
   }
   if (lastError !== undefined) throw lastError;
   if (lastResponse !== undefined) return lastResponse;
@@ -146,21 +153,21 @@ async function discoverTarget(port) {
   let acceptedPinnedCandidate;
   let targets;
   try {
-    targets = await fetchJSON(
-      listUrl,
-      androidPinned
-        ? async (response) => {
-          const pinnedCandidates = rankRuntimeCandidates(response).filter(matchesAndroidPin);
-          for (const candidate of pinnedCandidates) {
-            if (await probeTarget(candidate.webSocketDebuggerUrl)) {
-              acceptedPinnedCandidate = candidate;
-              return true;
-            }
+    targets = await fetchJSON(listUrl, async (response) => {
+      const runtimeCandidates = rankRuntimeCandidates(response);
+      if (runtimeCandidates.length === 0) return false;
+      if (androidPinned) {
+        const pinnedCandidates = runtimeCandidates.filter(matchesAndroidPin);
+        for (const candidate of pinnedCandidates) {
+          if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+            acceptedPinnedCandidate = candidate;
+            return true;
           }
-          return false;
         }
-        : undefined,
-    );
+        return false;
+      }
+      return true;
+    });
   } catch (e) {
     throw coded(
       new Error(`Cannot reach Metro at ${listUrl}. Is Metro running?\n  ${e.message}`),

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/launch-metro.cjs

@@ -26,10 +26,10 @@ function parseArgs(argv) {
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
-    console.log('Usage: launch-metro.cjs --target <path> --port <port> --log <path> --pid-file <path> [--workers <n>] [--clear]');
+    console.log('Usage: launch-metro.cjs --target <path> --port <port> --log <path> --pid-file <path> --build-env <path> [--workers <n>] [--clear]');
     return;
   }
-  for (const required of ['target', 'port', 'log', 'pid-file']) {
+  for (const required of ['target', 'port', 'log', 'pid-file', 'build-env']) {
     if (!args[required]) throw new Error(`--${required} is required`);
   }
   const target = path.resolve(args.target);
@@ -38,9 +38,9 @@ async function main() {
   fs.mkdirSync(path.dirname(log), { recursive: true });
   fs.mkdirSync(path.dirname(pidFile), { recursive: true });
   const logFd = fs.openSync(log, 'a');
-  const childArgs = ['expo', 'start', '--port', String(args.port)];
-  if (args.clear) childArgs.push('--clear');
+  const childArgs = ['watch'];
   const env = { ...process.env };
+  env.BASH_ENV = args['build-env'];
   if (args.workers) env.METRO_MAX_WORKERS = String(args.workers);
   const child = spawn('yarn', childArgs, {
     cwd: target,
@@ -59,10 +59,12 @@ async function main() {
     `${JSON.stringify({
       schemaVersion: 1,
       pid: child.pid,
+      pgid: child.pid,
       startedAt: new Date().toISOString(),
       target,
       port: Number(args.port),
       clear: Boolean(args.clear),
+      command: `yarn ${childArgs[0]}`,
     }, null, 2)}\n`,
   );
   child.unref();