@deeeed/metamask-harness 0.40.1 → 0.41.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.41.0 - 2026-08-19
+
+### Added
+
+- Add one parameterized, platform-neutral Mobile Perps performance recipe covering cold, cached, resume, reconnect, account-switch, and network-switch lifecycles with native visible-content proof and production loading/WebSocket evidence.
+
+### Changed
+
+- Replace the duplicated Android, iOS, cold, warm, and background Perps performance recipes with the single lifecycle recipe.
+
+### Fixed
+
+- Keep explicitly pinned iOS and Android bridge targets isolated when both platforms are active, and classify bounded CDP target failures as infrastructure failures.
+- Make Mobile wallet unlock and account selection deterministic across app restarts, propagate recipe timeouts through Perps state setup, and preserve missing performance counts and offsets as unknown instead of zero.
+- Keep the entire checkout-local `temp` tree outside Metro watching during canonical `yarn watch` launches, and leave the Mobile recipe HUD visible by default for performance lifecycles.
+
 ## 0.40.1 - 2026-08-16
 
 ### Fixed

package/adapters/manifest.json

@@ -42,6 +42,14 @@
       "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 the checkout-local temp tree owned by harness evidence and runtime state.",
+      "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,12 +30,13 @@ const {
 const { cdpEval, cdpEvalAsync } = require('./lib/cdp-eval.cjs');
 const { buildArmSnippet, buildCollectSnippet } = require('./lib/issue-capture.cjs');
 
-function parseHomepagePerformanceConsoleEvent(params) {
-  const marker = '[HomepagePerf] ';
+function parsePerformanceConsoleEvent(params) {
+  const markers = ['[PerpsPerf] ', '[HomepagePerf] '];
   for (const arg of params?.args || []) {
     const text = typeof arg?.value === 'string' ? arg.value : '';
+    const marker = markers.find((candidate) => text.includes(candidate));
+    if (!marker) continue;
     const markerIndex = text.indexOf(marker);
-    if (markerIndex < 0) continue;
     try {
       return JSON.parse(text.slice(markerIndex + marker.length));
     } catch {}
@@ -490,7 +491,7 @@ const COMMANDS = {
     let removeConsoleListener = null;
     if (visibleEventStage) {
       removeConsoleListener = client.on('Runtime.consoleAPICalled', (params) => {
-        const payload = parseHomepagePerformanceConsoleEvent(params);
+        const payload = parsePerformanceConsoleEvent(params);
         if (payload?.stage === visibleEventStage) visibleEvents.push(payload);
       });
       await client.send('Runtime.enable');

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -145,6 +145,9 @@ async function discoverTarget(port) {
   const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
   const androidPinned = Boolean(androidTargetName || androidDevice);
   const simName = loadSimulatorName();
+  const iosPinned =
+    process.env.MM_HARNESS_EXPLICIT_PLATFORM === 'ios' ||
+    Boolean(process.env.SIM_UDID);
   const matchesAndroidPin = (target) => androidTargetName
     ? target.deviceName !== simName &&
       (target.deviceName === androidTargetName ||
@@ -166,6 +169,18 @@ async function discoverTarget(port) {
         }
         return false;
       }
+      if (iosPinned && simName) {
+        const pinnedCandidates = runtimeCandidates.filter(
+          (candidate) => candidate.deviceName === simName,
+        );
+        for (const candidate of pinnedCandidates) {
+          if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+            acceptedPinnedCandidate = candidate;
+            return true;
+          }
+        }
+        return false;
+      }
       return true;
     });
   } catch (e) {
@@ -193,12 +208,16 @@ async function discoverTarget(port) {
   // context, and letting it win here sends a pinned android action to the iOS
   // target. No-match keeps the full candidate set (ambient sim configs tolerate a
   // sim that is not currently attached).
-  if (simName && !androidPinned && candidates.length > 1) {
+  if (simName && !androidPinned) {
     const deviceFiltered = candidates.filter(
       (t) => t.deviceName === simName,
     );
     if (deviceFiltered.length > 0) {
       candidates = deviceFiltered;
+    } else if (iosPinned) {
+      throw coded(new Error(
+        `Pinned iOS simulator '${simName}' did not match any Metro target.`,
+      ), BRIDGE_ERROR_CODES.NO_TARGET);
     }
   }
 
@@ -306,15 +325,15 @@ async function discoverTarget(port) {
     }
   }
 
-  if (androidPinned) {
+  if (androidPinned || iosPinned) {
     const candidateList = candidates
       .map((target) => `  deviceName=${JSON.stringify(target.deviceName || '')} ws=${target.webSocketDebuggerUrl || ''}`)
       .join('\n');
     throw coded(new Error(
-      `Pinned Android device has no responding __AGENTIC__ JS runtime after ${FETCH_RETRIES} discovery attempt(s).\n` +
-      `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
+      `Pinned ${androidPinned ? 'Android device' : `iOS simulator '${simName || process.env.SIM_UDID || '(unknown)'}'`} has no responding __AGENTIC__ JS runtime after ${FETCH_RETRIES} discovery attempt(s).\n` +
+      (androidPinned ? `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` : '') +
       `  Matching non-agentic targets:\n${candidateList}\n` +
-      `  The native C++ page is not a valid recipe target; wait for Android Hermes to re-register or relaunch the Android app.`,
+      `  The native C++ page is not a valid recipe target; wait for Hermes to re-register or relaunch the pinned app.`,
     ), BRIDGE_ERROR_CODES.NO_TARGET);
   }
 

package/adapters/mobile/metro-config.cjs

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs = require('node:fs');
+const { createRequire } = require('node:module');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function appendBlockList(blockList, pattern) {
+  if (Array.isArray(blockList)) return [...blockList, pattern];
+  return blockList instanceof RegExp ? [blockList, pattern] : [pattern];
+}
+
+function blockListFlags(blockList) {
+  const first = Array.isArray(blockList) ? blockList[0] : blockList;
+  return first instanceof RegExp && first.ignoreCase ? 'i' : '';
+}
+
+function resolveExpoConfigLoader(projectRoot) {
+  const requireFromProject = createRequire(path.join(projectRoot, 'package.json'));
+  let requireUtilsPath;
+  try {
+    requireUtilsPath = requireFromProject.resolve('@expo/require-utils');
+  } catch (error) {
+    if (error?.code !== 'MODULE_NOT_FOUND') throw error;
+    return null;
+  }
+  const { loadModuleSync } = requireFromProject(requireUtilsPath);
+  return typeof loadModuleSync === 'function' ? loadModuleSync : null;
+}
+
+async function loadProductConfig(configPath, baseConfig, projectRoot) {
+  let loaded;
+  const expoConfigLoader = resolveExpoConfigLoader(projectRoot);
+  if (expoConfigLoader) {
+    loaded = expoConfigLoader(configPath);
+  } else {
+    try {
+      loaded = require(configPath);
+    } catch (error) {
+      if (error?.code !== 'ERR_REQUIRE_ESM') throw error;
+      loaded = await import(pathToFileURL(configPath).href);
+    }
+  }
+
+  const moduleValue = await loaded;
+  const exported =
+    moduleValue?.__esModule || moduleValue?.[Symbol.toStringTag] === 'Module'
+      ? moduleValue.default
+      : moduleValue;
+  const config = await exported;
+  return typeof config === 'function' ? config(baseConfig) : config;
+}
+
+module.exports = async function harnessMetroConfig(baseConfig) {
+  const projectRoot = path.resolve(
+    process.env.MM_HARNESS_METRO_PROJECT_ROOT || process.cwd(),
+  );
+  const productConfigPath = path.resolve(
+    process.env.MM_HARNESS_METRO_BASE_CONFIG ||
+      path.join(projectRoot, 'metro.config.js'),
+  );
+  if (productConfigPath === __filename) {
+    throw new Error(
+      'MM_HARNESS_METRO_BASE_CONFIG must reference the product Metro config, not the harness wrapper.',
+    );
+  }
+  let productConfig = baseConfig;
+  if (fs.existsSync(productConfigPath)) {
+    productConfig = await loadProductConfig(
+      productConfigPath,
+      baseConfig,
+      projectRoot,
+    );
+  }
+
+  const tempRoot = path.join(projectRoot, 'temp');
+  const existingBlockList =
+    productConfig.resolver?.blockList ?? baseConfig.resolver?.blockList;
+  const tempPattern = new RegExp(
+    `^${escapeRegExp(tempRoot)}(?:${escapeRegExp(path.sep)}|$)`,
+    blockListFlags(existingBlockList),
+  );
+  return {
+    ...productConfig,
+    resolver: {
+      ...productConfig.resolver,
+      blockList: appendBlockList(existingBlockList, tempPattern),
+    },
+  };
+};

package/adapters/mobile/start-metro.sh

@@ -50,7 +50,16 @@ fi
 # only ever inspect or signal a Metro listening on $PORT.
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/metro-listener.sh"
-MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID METAMASK_BUILD_TYPE METAMASK_ENVIRONMENT}"
+HARNESS_METRO_CONFIG="$SCRIPT_DIR/metro-config.cjs"
+if [ "${EXPO_OVERRIDE_METRO_CONFIG:-}" = "$HARNESS_METRO_CONFIG" ]; then
+  PRODUCT_METRO_CONFIG="${MM_HARNESS_METRO_BASE_CONFIG:-$TARGET/metro.config.js}"
+else
+  PRODUCT_METRO_CONFIG="${EXPO_OVERRIDE_METRO_CONFIG:-$TARGET/metro.config.js}"
+fi
+export MM_HARNESS_METRO_PROJECT_ROOT="$TARGET"
+export MM_HARNESS_METRO_BASE_CONFIG="$PRODUCT_METRO_CONFIG"
+export EXPO_OVERRIDE_METRO_CONFIG="$HARNESS_METRO_CONFIG"
+MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID METAMASK_BUILD_TYPE METAMASK_ENVIRONMENT} MM_HARNESS_METRO_PROJECT_ROOT MM_HARNESS_METRO_BASE_CONFIG EXPO_OVERRIDE_METRO_CONFIG"
 
 # RECIPE_RUNTIME_DIR (relative, validated) makes runtime state per-run so jobs
 # sharing one checkout do not collide on metro.log / metro.pid / metro.tmux.
@@ -88,6 +97,9 @@ write_metro_build_env() {
     done
   )" || { rm -f "$temporary"; return 1; }
   eval "$product_values"
+  required_MM_HARNESS_METRO_PROJECT_ROOT="$MM_HARNESS_METRO_PROJECT_ROOT"
+  required_MM_HARNESS_METRO_BASE_CONFIG="$MM_HARNESS_METRO_BASE_CONFIG"
+  required_EXPO_OVERRIDE_METRO_CONFIG="$EXPO_OVERRIDE_METRO_CONFIG"
   [ "$CLEAR" = true ] && clear_value=1
   {
     printf 'export MM_HARNESS_METRO_WATCHER_PORT=%q\n' "$PORT"

package/dist/commands/device-target.js

@@ -26,6 +26,7 @@ function resolveAndroidModel(serial) {
 }
 function setAndroidDeviceEnv(id, fallbackName) {
   process.env.PLATFORM = "android";
+  process.env.MM_HARNESS_EXPLICIT_PLATFORM = "android";
   process.env.ADB_SERIAL = id;
   process.env.ANDROID_SERIAL = id;
   process.env.ANDROID_DEVICE = id;
@@ -33,9 +34,11 @@ function setAndroidDeviceEnv(id, fallbackName) {
   if (model) process.env.ANDROID_TARGET_DEVICE_NAME = model;
   else delete process.env.ANDROID_TARGET_DEVICE_NAME;
   process.env.IOS_SIMULATOR = "";
+  process.env.SIM_UDID = "";
 }
 function setIosDeviceEnv(id, fallbackName) {
   process.env.PLATFORM = "ios";
+  process.env.MM_HARNESS_EXPLICIT_PLATFORM = "ios";
   process.env.IOS_SIMULATOR = fallbackName?.trim() || id;
   process.env.SIM_UDID = id;
   process.env.ADB_SERIAL = "";

package/dist/commands/run-engine.js

@@ -155,12 +155,11 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
     projectRoot,
     rootRecipe: recipeDocument
   });
-  const suppressHudForLifecycleTiming = adapter === "mobile" && mobileRecipeRequiresUninterruptedLifecycleTiming(recipeDocument);
   const suppressHudForOpaqueMobile = adapter === "mobile" && process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
   const runnerOptions = {
     quietStdout: runtimeOptions.stdoutIsMachineContract === true,
     suppressLibraryResolutionLogs: runtimeOptions.suppressLibraryResolutionLogs,
-    autoHud: suppressHudForLifecycleTiming || suppressHudForOpaqueMobile ? false : trust.source && trust.source.trust !== "trusted" ? false : runtimeOptions.autoHud,
+    autoHud: suppressHudForOpaqueMobile ? false : trust.source && trust.source.trust !== "trusted" ? false : runtimeOptions.autoHud,
     onActionEvent: runtimeOptions.onActionEvent,
     actionSources,
     // A direct engineer invocation is the explicit trust boundary for a
@@ -213,16 +212,6 @@ function runtimeRecipeDocument(recipe, absoluteRecipePath) {
     return void 0;
   }
 }
-function mobileRecipeRequiresUninterruptedLifecycleTiming(recipe) {
-  if (!isRecord(recipe)) return false;
-  const workflow = isRecord(recipe.workflow) ? recipe.workflow : void 0;
-  const nodes = workflow && isRecord(workflow.nodes) ? workflow.nodes : void 0;
-  if (!nodes) return false;
-  const actions = new Set(
-    Object.values(nodes).filter(isRecord).map((node) => node.action).filter((action) => typeof action === "string")
-  );
-  return actions.has("app.lifecycle") && actions.has("metamask.perps.capture_performance");
-}
 function recipeProcessEnvironment() {
   const env = { ...process.env };
   delete env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
@@ -314,7 +303,8 @@ function recipeRunEnv(adapter, runtimeOptions = {}) {
     RECIPE_CDP_PORT: runtimeOptions.cdpPort ?? process.env.RECIPE_CDP_PORT,
     FARMSLOT_SLOT_ID: runtimeOptions.slot ?? process.env.FARMSLOT_SLOT_ID,
     SLOT_ID: runtimeOptions.slot ?? process.env.SLOT_ID,
-    PLATFORM: process.env.PLATFORM
+    PLATFORM: process.env.PLATFORM,
+    MM_HARNESS_EXPLICIT_PLATFORM: process.env.MM_HARNESS_EXPLICIT_PLATFORM
   };
   if (adapter !== "mobile") return base;
   return {
@@ -322,6 +312,7 @@ function recipeRunEnv(adapter, runtimeOptions = {}) {
     WATCHER_PORT: process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
     METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
     IOS_SIMULATOR: process.env.IOS_SIMULATOR,
+    SIM_UDID: process.env.SIM_UDID,
     ANDROID_DEVICE: process.env.ANDROID_DEVICE,
     ANDROID_TARGET_DEVICE_NAME: process.env.ANDROID_TARGET_DEVICE_NAME,
     ADB_SERIAL: process.env.ADB_SERIAL,
@@ -1378,7 +1369,6 @@ export {
   ensureMobileProofRuntime,
   executeWithHealBounds,
   listRunnableRecipes,
-  mobileRecipeRequiresUninterruptedLifecycleTiming,
   preflightRecipe,
   prepareHeal,
   prepareRuntimeIfNeeded,

package/dist/heal-bounds.js

@@ -62,6 +62,7 @@ async function ensureOverlay(adapter, target, heal, state, json) {
 }
 function classifyFailure(output) {
   if (/SCREENSHOT_PROTECTED|screenshot is protected by FLAG_SECURE/iu.test(output)) return "screenshot-protected";
+  if (/CDP_TIMEOUT|Mobile CDP bridge command timed out|NO_TARGET|WS_CLOSED/iu.test(output)) return "infra";
   if (/wallet|fixture|keyring|not seeded|\bsrp\b|password|onboard/iu.test(output)) return "wallet";
   if (/metro|cdp|chrome|bridge|bundle|packager|port\b|econnrefused|not reachable|watcher|dev client|websocket/iu.test(output)) {
     return "infra";

package/dist/live-adapter-contract.js

@@ -359,7 +359,8 @@ function liveAdapterProcessTimeoutMs(node) {
   const actionTimeouts = [
     node.target_timeout_ms,
     node.unlock_timeout_ms,
-    node.timeout_ms
+    node.timeout_ms,
+    node.wait_timeout_ms
   ].map(Number).filter((value) => Number.isFinite(value) && value > 0);
   if (actionTimeouts.length > 0) {
     return Math.max(

package/dist/mm-harness-cli.js

@@ -243,7 +243,7 @@ Common overrides:
   --json                             Machine-readable output
   --json-stream                      Line-flushed JSONL progress + terminal event
   --record-video=full-run            Record a video of the run
-  --hud <auto|show|hide>             Recipe HUD policy (default: auto)
+  --hud <auto|show|hide>             Recipe HUD policy (auto shows normal Mobile recipes; hide is explicit)
 
 Advanced integrations:
   runtime: --cdp-port, --watcher-port/--metro-port, --runtime-dir, --slot,

package/docs/RECIPES.md

@@ -176,30 +176,36 @@ For visual PR proof, prefer a short simulator recording or GIF over still
 screenshots when the claim is a UI flow (timing / transitions). Use screenshots
 as supporting stills.
 
-### Perps Homepage visible performance
+### Perps loading lifecycle validation
 
-The bundled `perps.performance.homepage.*` family preserves the device-proven
-Homepage TTC/DFD journeys. Run every recipe with an explicit device pin,
-healing disabled, and full-run video:
+One platform-neutral recipe owns the reusable Perps lifecycle proof. The
+harness adapter supplies Android or iOS behavior; the graph and lifecycle
+parameters remain identical. Run it with an explicit device pin:
 
 ```bash
-mm-harness run perps.performance.homepage.android-background-short --device <serial> --heal off --record-video=full-run
-mm-harness run perps.performance.homepage.android-background-reconnect --device <serial> --heal off --record-video=full-run
-mm-harness run perps.performance.homepage.android-cold-no-cache --device <serial> --heal off --record-video=full-run
-mm-harness run perps.performance.homepage.android-cold-disk-cache --device <serial> --heal off --record-video=full-run
-mm-harness run perps.performance.homepage.android-network-recovery --device <serial> --heal off --record-video=full-run
-mm-harness run perps.performance.homepage.ios-background-short --device <udid> --heal off --record-video=full-run
-mm-harness run perps.performance.homepage.ios-background-reconnect --device <udid> --heal off --record-video=full-run
-mm-harness run perps.performance.homepage.ios-cold-no-cache --device <udid> --heal off --record-video=full-run
-mm-harness run perps.performance.homepage.ios-cold-disk-cache --device <udid> --heal off --record-video=full-run
+mm-harness run perps.performance \
+  --device <android-serial-or-ios-udid> \
+  account=<fixture-account-name> \
+  content_variant=trending \
+  market=BTC \
+  lifecycle=cold_no_cache \
+  --heal off --record-video=full-run
 ```
 
-The Android variants use a deterministic Hyperliquid testnet order and cancel
-it after capture. The iOS variants use the existing fixture wallet and validate
-trending content without fabricating position/order state. `app.network` is
-Android-only because host-wide iOS network mutation cannot isolate one
-simulator safely. These recipes validate viewport-demand-to-visible TTC/DFD;
-they do not relabel process-start duration as TTC.
+The Mobile recipe HUD is shown by default, including during performance
+validation. Use `--hud hide` only when a specific opaque/release proof requires
+an unobstructed product surface; do not hide it merely to collect timings.
+
+Supported lifecycle values are `navigate_return`, `cold_disk_cache`,
+`cold_no_cache`, `background_short`, `background_reconnect`, `account_switch`,
+and `network_switch`. The shared graph uses an existing fixture position and
+never fabricates exchange state inside the measurement. It proves native
+visible content with `ui.wait_for`, captures production `[PerpsLoadProof]` and
+WebSocket milestones, and leaves detailed TTC/DFD to the app's Sentry traces.
+It never relabels Metro, fixture, or process-start duration as TTC.
+The recipe does not label a checkout as main or candidate; pin and record the
+exact checkout commit externally, then use captured source milestones to verify
+which data path actually ran.
 
 Rules:
 

package/library/actions/mobile/perps/capture_performance.mjs

@@ -1,4 +1,4 @@
 import { runAdapter } from '../platform/bridge.mjs';
-import { captureHomepagePerformance } from './performance-capture.mjs';
+import { capturePerpsPerformance } from './performance-capture.mjs';
 
-runAdapter(captureHomepagePerformance);
+runAdapter(capturePerpsPerformance);