@deeeed/metamask-harness 0.33.2 → 0.34.0

package/dist/adapters.js

@@ -1,11 +1,15 @@
 import http from "node:http";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { compatibilityMode, fixtureSummary, repoShape } from "./doctor.js";
 import {
   runLiveAdapterScript
 } from "./live-adapter-contract.js";
 import { withExtensionPage } from "../library/actions/extension/platform/cdp.mjs";
-import { bridgeCommand, evalSync, MOBILE_BRIDGE_ERROR_CODES, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
+import { bridgeCommand, evalAsync, evalSync, MOBILE_BRIDGE_ERROR_CODES, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
 import { observeNativeUi } from "../library/actions/mobile/platform/observe-ui.mjs";
+import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
+const execFileAsync = promisify(execFile);
 const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
   "ui.swipe",
   "ui.pan",
@@ -34,8 +38,10 @@ const LIVE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.close_orders",
   "metamask.perps.ensure_orders",
   "metamask.perps.assert_orders",
+  "metamask.perps.clear_performance_caches",
   "metamask.perps.start_state",
-  "metamask.perps.teardown_state"
+  "metamask.perps.teardown_state",
+  "metamask.perps.capture_performance"
 ]);
 const CORE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set(["metamask.perps.read_account"]);
 const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
@@ -191,6 +197,8 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
     "metamask.perps.assert_orders",
     "metamask.perps.start_state",
     "metamask.perps.teardown_state",
+    "metamask.perps.capture_performance",
+    ...platform === "mobile" ? ["metamask.perps.clear_performance_caches"] : [],
     // read_account is core-only: only the headless core adapter implements it.
     ...platform === "core" ? ["metamask.perps.read_account"] : []
   ];
@@ -238,43 +246,107 @@ function mobileProbeOutput(status, input, projectRoot) {
 function mobileBridgePath(_projectRoot) {
   return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || "runner:adapters/mobile/bridge-runtime/cdp-bridge.cjs";
 }
+function resolveMobileWaitTarget(payload) {
+  const testId = optionalScalarText(
+    payload.test_id ?? payload.testID,
+    "Mobile ui.wait_for.test_id"
+  );
+  const expectedText = optionalScalarText(payload.text, "ui.wait_for.text");
+  if (!testId && !expectedText) {
+    throw new Error(
+      "Mobile ui.wait_for requires one of: test_id, testID, text."
+    );
+  }
+  const expected = scalarText(
+    payload.expected,
+    "ui.wait_for.expected",
+    "present"
+  ).toLowerCase();
+  const textMatch = scalarText(
+    payload.text_match ?? payload.textMatch,
+    "ui.wait_for.text_match",
+    "contains"
+  ).toLowerCase();
+  if (!["contains", "exact"].includes(textMatch)) {
+    throw new Error("ui.wait_for.text_match must be contains or exact.");
+  }
+  if (!testId && textMatch === "exact") {
+    throw new Error(
+      "Mobile text-only ui.wait_for supports text_match=contains; exact matching also requires test_id/testID."
+    );
+  }
+  return {
+    testId,
+    expectedText,
+    expected,
+    textMatch,
+    visibility: expected === "visible" || expected === "hidden" ? "viewport" : "tree"
+  };
+}
 async function waitForMobileTarget(input, payload) {
   const timeoutMs = Number(payload.timeout_ms ?? payload.timeoutMs ?? 1e4);
   const deadline = Date.now() + timeoutMs;
-  const testId = firstScalarText(payload, ["test_id", "testID"], "Mobile ui.wait_for");
-  const expected = scalarText(payload.expected, "ui.wait_for.expected", "present").toLowerCase();
-  const expectedText = optionalScalarText(payload.text, "ui.wait_for.text");
-  const textMatch = scalarText(payload.text_match ?? payload.textMatch, "ui.wait_for.text_match", "contains").toLowerCase();
-  const textExpression = `(function(){
+  const { testId, expectedText, expected, textMatch, visibility } = resolveMobileWaitTarget(payload);
+  const query = {
+    ...testId ? { testId } : {},
+    ...expectedText && textMatch === "contains" ? { textContains: expectedText } : {},
+    visibility
+  };
+  const queryExpression = `(function(){
     const api = globalThis.__AGENTIC__;
-    if (!api?.getTextByTestId) return null;
-    return api.getTextByTestId(${JSON.stringify(testId)});
+    if (!api || typeof api.queryUiTarget !== 'function') {
+      return Promise.resolve(JSON.stringify({ unsupported: true }));
+    }
+    return api.queryUiTarget(${JSON.stringify(query)}).then(function(result){
+      return JSON.stringify(result);
+    });
   })()`;
-  const expression = `Boolean(globalThis.__AGENTIC__?.findFiberByTestId?.(${JSON.stringify(testId)}))`;
-  let lastValue = null;
+  const textExpression = testId ? `(function(){
+        const api = globalThis.__AGENTIC__;
+        if (!api?.getTextByTestId) return null;
+        return api.getTextByTestId(${JSON.stringify(testId)});
+      })()` : null;
+  let lastResult = null;
   let lastText = null;
   const expectsAbsent = expected === "absent" || expected === "hidden" || expected === "not_present";
   while (Date.now() <= deadline) {
-    lastValue = await evalSync(input, expression);
-    const present = Boolean(lastValue);
-    if (expectsAbsent && !present) {
-      return { matched: true, testId, expected, present };
+    const result = await evalAsync(input, queryExpression);
+    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."
+      );
     }
-    if (!expectsAbsent && present) {
-      if (!expectedText) {
-        return { matched: true, testId, expected, present };
-      }
+    lastResult = result;
+    const present = result.present === true;
+    const visible = result.visible === true;
+    let textMatched = !expectedText || textMatch === "contains";
+    if (expectedText && textMatch === "exact" && textExpression) {
       lastText = await evalSync(input, textExpression);
-      const text = traceText(lastText);
-      const textMatched = textMatch === "exact" ? text === expectedText : text.includes(expectedText);
-      if (textMatched) {
-        return { matched: true, testId, expected, present, text, textMatch };
-      }
+      textMatched = traceText(lastText) === expectedText;
+    }
+    const matched = expected === "visible" ? visible && textMatched : expected === "hidden" ? !visible : expectsAbsent ? !present : present && textMatched;
+    if (matched) {
+      return {
+        matched: true,
+        ...testId ? { testId } : {},
+        ...expectedText ? { text: expectedText, textMatch } : {},
+        expected,
+        present,
+        visible,
+        visibility,
+        ...isRecord(result.rect) ? { rect: result.rect } : {}
+      };
     }
     await sleep(250);
   }
-  const textReason = expectedText ? ` and text ${textMatch} ${JSON.stringify(expectedText)}; last text=${JSON.stringify(lastText)}` : "";
-  throw new Error(`Timed out waiting for mobile testID ${testId} to be ${expected}${textReason}; last present=${Boolean(lastValue)}.`);
+  const target = [
+    testId ? `testID ${JSON.stringify(testId)}` : "",
+    expectedText ? `text ${textMatch} ${JSON.stringify(expectedText)}` : ""
+  ].filter(Boolean).join(" with ");
+  const exactReason = textMatch === "exact" ? `; last text=${JSON.stringify(lastText)}` : "";
+  throw new Error(
+    `Timed out waiting for mobile ${target} to be ${expected}; last result=${JSON.stringify(lastResult)}${exactReason}.`
+  );
 }
 const MOBILE_BRIDGE_HANDLERS = {
   screenshot: handleMobileScreenshot,
@@ -354,13 +426,73 @@ async function handleMobileScroll(payload, context) {
   const input = mobileUiInput(context, "scroll", payload);
   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 args = testId ? ["scroll-view", "--test-id", testId, "--offset", offset, animatedFlag(payload)] : ["scroll-view", "--offset", offset, animatedFlag(payload)];
+  const intoView = payload.scroll_into_view === true || payload.into_view === true;
+  if (testId && intoView) {
+    const before = await queryMobileViewportTarget(input, testId);
+    if (before.visible === true) {
+      return {
+        ok: true,
+        testId,
+        intoView: true,
+        alreadyVisible: true,
+        rect: before.rect
+      };
+    }
+  }
+  const args = testId ? [
+    "scroll-view",
+    "--test-id",
+    testId,
+    "--offset",
+    offset,
+    ...intoView ? ["--into-view"] : [],
+    animatedFlag(payload)
+  ] : ["scroll-view", "--offset", offset, animatedFlag(payload)];
   const result = await bridgeCommand(input, args);
+  if (testId && intoView) {
+    const after = await waitForMobileViewportTarget(
+      input,
+      testId,
+      Number(payload.timeout_ms ?? payload.timeoutMs ?? 5e3)
+    );
+    if (after.visible !== true) {
+      throw new Error(
+        `ui.scroll did not bring mobile testID ${JSON.stringify(testId)} into the viewport; last result=${JSON.stringify(after)}.`
+      );
+    }
+  }
   return {
     ...isRecord(result) ? result : { result },
-    intoView: payload.scroll_into_view === true || payload.into_view === true
+    intoView
   };
 }
+async function queryMobileViewportTarget(input, testId) {
+  const expression = `(function(){
+    const api = globalThis.__AGENTIC__;
+    if (!api || typeof api.queryUiTarget !== 'function') {
+      return Promise.resolve(JSON.stringify({ unsupported: true }));
+    }
+    return api.queryUiTarget(${JSON.stringify({ testId, visibility: "viewport" })}).then(function(result){
+      return JSON.stringify(result);
+    });
+  })()`;
+  const result = await evalAsync(input, expression);
+  if (!isRecord(result) || result.unsupported === true) {
+    throw new Error(
+      "Mobile ui.scroll scroll_into_view requires the current __AGENTIC__.queryUiTarget bridge."
+    );
+  }
+  return result;
+}
+async function waitForMobileViewportTarget(input, testId, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, Math.min(timeoutMs, 5e3));
+  let result = await queryMobileViewportTarget(input, testId);
+  while (result.visible !== true && Date.now() < deadline) {
+    await sleep(100);
+    result = await queryMobileViewportTarget(input, testId);
+  }
+  return result;
+}
 async function handleMobileWaitFor(payload, context) {
   return waitForMobileTarget(mobileUiInput(context, "waitFor", payload), payload);
 }
@@ -543,13 +675,10 @@ async function executeNativeProviderAction(action, node, context, createTranspor
       `${action} requires one selected ${platform} device. Next: mm-harness status --adapter mobile --all-devices --json`
     );
   }
-  const app = platform === "android" ? context.env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID : context.env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID;
-  if (!app) {
-    const variable = platform === "android" ? "ANDROID_PACKAGE_ID" : "IOS_BUNDLE_ID";
-    throw new Error(
-      `${action} requires the selected MetaMask app id. Next: export ${variable}=<installed-app-id>`
-    );
+  if (platform === "android" && action === "ui.swipe" && isCoordinateTarget(node.target)) {
+    return executeAndroidCoordinateSwipe(node, String(device));
   }
+  const app = platform === "android" ? context.env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask" : context.env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID ?? "io.metamask.MetaMask";
   const session = `mm-harness-${process.pid}-${context.nodeId}`.replace(/[^a-zA-Z0-9._-]/gu, "-");
   let transport;
   try {
@@ -585,6 +714,66 @@ async function executeNativeProviderAction(action, node, context, createTranspor
   if (closeError) throw closeError;
   return output;
 }
+function isCoordinateTarget(value) {
+  return isRecord(value) && typeof value.x === "number" && Number.isFinite(value.x) && typeof value.y === "number" && Number.isFinite(value.y);
+}
+async function executeAndroidCoordinateSwipe(node, device) {
+  const target = node.target;
+  const direction = String(node.direction ?? "").toLowerCase();
+  if (!["up", "down", "left", "right"].includes(direction)) {
+    throw new Error("ui.swipe.direction must be up, down, left, or right.");
+  }
+  const distance = Number(node.distance ?? 300);
+  const durationMs = Number(node.duration_ms ?? 300);
+  if (!Number.isFinite(distance) || distance <= 0) {
+    throw new Error("ui.swipe.distance must be a positive number.");
+  }
+  if (!Number.isFinite(durationMs) || durationMs <= 0) {
+    throw new Error("ui.swipe.duration_ms must be a positive number.");
+  }
+  const start = { x: Math.round(target.x), y: Math.round(target.y) };
+  const end = {
+    x: Math.round(start.x + (direction === "left" ? -distance : direction === "right" ? distance : 0)),
+    y: Math.round(start.y + (direction === "up" ? -distance : direction === "down" ? distance : 0))
+  };
+  const adbPath = resolveMobileToolPath("adb", { required: true });
+  try {
+    await execFileAsync(
+      adbPath,
+      [
+        "-s",
+        device,
+        "shell",
+        "input",
+        "swipe",
+        String(start.x),
+        String(start.y),
+        String(end.x),
+        String(end.y),
+        String(Math.round(durationMs))
+      ],
+      { encoding: "utf8", timeout: Math.round(durationMs) + 1e4 }
+    );
+  } catch (error) {
+    throw new Error(
+      `Android ui.swipe failed on ${device}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const settleMs = node.settle === false ? 0 : 300;
+  if (settleMs > 0) await sleep(settleMs);
+  return {
+    action: "ui.swipe",
+    resolvedStart: start,
+    resolvedEnd: end,
+    backend: "adb-input-swipe",
+    segments: 1,
+    settlement: {
+      method: "bounded-post-gesture",
+      waitedMs: settleMs,
+      lifecycleNeutral: true
+    }
+  };
+}
 function mobileNativePlatform(env) {
   if (env.PLATFORM === "android" || env.PLATFORM === "ios") return env.PLATFORM;
   if (env.ADB_SERIAL || env.ANDROID_SERIAL) return "android";
@@ -662,5 +851,6 @@ export {
   createMetaMaskUiTransport,
   hideMobileHudOnTeardown,
   isMobileHudLifecycleSkip,
-  normalizeUiWaitNode
+  normalizeUiWaitNode,
+  resolveMobileWaitTarget
 };

package/dist/command-contract.js

@@ -228,6 +228,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
   launch: {
     options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
       "--build": bool(),
+      "--clear-metro": bool(),
       "--verify": bool(),
       "--runway": bool(),
       "--watch": bool(),

package/dist/commands/device-target.js

@@ -1,7 +1,12 @@
 import { execFileSync } from "node:child_process";
 import { resolveMobileToolPath } from "../../library/actions/mobile/platform/tool-paths.mjs";
-import { listConnectedDevices } from "../devices.js";
+import {
+  findAvailableIosSimulatorById,
+  listConnectedDevices
+} from "../devices.js";
+import { persistExplicitDevicePin } from "../runtime-context.js";
 import { optionString, shellQuoteArg, targetPath } from "./parse-args.js";
+const DEVICE_SELECT_HINT = "Pass --device <name|udid|serial> to select one target. Do not shut down other connected devices to force selection.";
 function normalizeDeviceName(value) {
   return value.replace(/_/gu, " ").trim();
 }
@@ -20,6 +25,7 @@ function resolveAndroidModel(serial) {
   }
 }
 function setAndroidDeviceEnv(id, fallbackName) {
+  process.env.PLATFORM = "android";
   process.env.ADB_SERIAL = id;
   process.env.ANDROID_SERIAL = id;
   process.env.ANDROID_DEVICE = id;
@@ -29,7 +35,8 @@ function setAndroidDeviceEnv(id, fallbackName) {
   process.env.IOS_SIMULATOR = "";
 }
 function setIosDeviceEnv(id, fallbackName) {
-  process.env.IOS_SIMULATOR = fallbackName ? normalizeDeviceName(fallbackName) : id;
+  process.env.PLATFORM = "ios";
+  process.env.IOS_SIMULATOR = fallbackName?.trim() || id;
   process.env.SIM_UDID = id;
   process.env.ADB_SERIAL = "";
   process.env.ANDROID_SERIAL = "";
@@ -113,13 +120,14 @@ function applyDeviceTargeting(command, adapter, options, opts) {
       }
       if (matched.platform === "android") setAndroidDeviceEnv(matched.id, matched.name);
       else setIosDeviceEnv(matched.id, matched.name);
+      persistExplicitDevicePin(targetPath(options), matched);
       return { ok: true };
     };
     const androidById = connected2.find((d) => d.platform === "android" && d.id === device);
     if (androidById) {
       return setResolvedDevice(androidById);
     }
-    const iosById = connected2.find((d) => d.platform === "ios" && d.id === device);
+    const iosById = connected2.find((d) => d.platform === "ios" && d.id === device) ?? (command === "launch" && platformPreference === "ios" ? findAvailableIosSimulatorById(device) : void 0);
     if (iosById) {
       return setResolvedDevice(iosById);
     }
@@ -221,7 +229,8 @@ ${formatConnectedDevices(connected)}` : `  No devices are currently connected (a
   Connected devices:
 ${formatConnectedDevices(connected)}
   Add --device <id> to disambiguate, e.g.:${platformTargetable.map((d) => `
-    --device ${d.id}`).join("")}`,
+    --device ${d.name ?? d.id}`).join("")}
+  ${DEVICE_SELECT_HINT}`,
       userAction: deviceRecovery(options, opts.rerun)
     };
   }
@@ -240,8 +249,10 @@ ${formatConnectedDevices(connected)}
       message: `${targetable.length} mobile devices available \u2014 ${command} needs exactly one target.
   Connected devices:
 ${formatConnectedDevices(connected)}
-` + (selectedTargetable.length > 1 ? `  The current slot context selects more than one target; fix the slot device pins or add --device <id>.` : `  Add --device <id> to disambiguate, e.g.:${targetable.map((d) => `
-    --device ${d.id}`).join("")}`),
+` + (selectedTargetable.length > 1 ? `  The current slot context selects more than one target; fix the slot device pins or add --device <id>.
+  ${DEVICE_SELECT_HINT}` : `  Add --device <id> to disambiguate, e.g.:${targetable.map((d) => `
+    --device ${d.name ?? d.id}`).join("")}
+  ${DEVICE_SELECT_HINT}`),
       userAction: deviceRecovery(options, opts.rerun)
     };
   }

package/dist/commands/launch/index.js

@@ -44,6 +44,7 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "sidepanel",
   "fullscreen",
   "runway",
+  "clearMetro",
   "json",
   "jsonStream"
 ]);
@@ -122,9 +123,13 @@ async function handleLaunchLocked(argv, stream) {
   const wantVerify = flag(options, "verify");
   const wantWatch = flag(options, "watch");
   const wantRunway = flag(options, "runway");
+  const wantClearMetro = flag(options, "clearMetro");
   if (wantRunway && adapter !== "mobile") {
     return launchUsage(jsonOutput, stream, "runway is mobile-only.", "drop --runway for the extension");
   }
+  if (wantClearMetro && adapter !== "mobile") {
+    return launchUsage(jsonOutput, stream, "--clear-metro is mobile-only.", "drop --clear-metro for the extension");
+  }
   const displayMode = flag(options, "sidepanel") && !flag(options, "fullscreen") ? "sidepanel" : "fullscreen";
   for (const portFlag of ["cdpPort", "watcherPort"]) {
     const value = str(options, portFlag);
@@ -160,7 +165,7 @@ async function handleLaunchLocked(argv, stream) {
     const watcherPort = str(options, "watcherPort") ?? process.env.WATCHER_PORT ?? "auto";
     writeInteractiveProgress(
       machine,
-      `\u2192 mobile launch \u2014 ${mobileTarget} \xB7 ${tier === "build" ? "native build" : "quick readiness"} \xB7 ${device} \xB7 Metro ${watcherPort === "auto" ? "auto" : `:${watcherPort}`}`
+      `\u2192 mobile launch \u2014 ${mobileTarget} \xB7 ${tier === "build" ? "native build" : "quick readiness"} \xB7 ${device} \xB7 Metro ${watcherPort === "auto" ? "auto" : `:${watcherPort}`}${wantClearMetro ? " \xB7 clear cache" : ""}`
     );
   }
   const state = newHealState();
@@ -221,7 +226,17 @@ async function handleLaunchLocked(argv, stream) {
     }
   }
   stream.phase("launch");
-  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, machine, displayMode);
+  let attempt = await executeComposition(
+    adapter,
+    mobileTarget,
+    tier,
+    wantWatch,
+    target,
+    machine,
+    displayMode,
+    false,
+    wantClearMetro
+  );
   if (attempt.status === 0) {
     return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
   }
@@ -379,7 +394,7 @@ function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
   if (adapter === "mobile" && (device || mobileTarget === "ios" || mobileTarget === "android")) {
     const targetingOptions = {
       ...options,
-      ...mobileTarget && !device ? { platform: mobileTarget } : {}
+      ...mobileTarget ? { platform: mobileTarget } : {}
     };
     const result = applyDeviceTargeting("launch", adapter, targetingOptions, { gate: false, rerun: "" });
     if ("code" in result) {
@@ -447,9 +462,16 @@ function nativeInputsChanged(target, adapter) {
     return false;
   }
 }
-async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode = "fullscreen", restartMobileApp = false) {
+async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode = "fullscreen", restartMobileApp = false, clearMobileMetro = false) {
   if (adapter === "mobile") {
-    return launchMobile(target, mobileTarget, tier, json, restartMobileApp);
+    return launchMobile(
+      target,
+      mobileTarget,
+      tier,
+      json,
+      restartMobileApp,
+      clearMobileMetro
+    );
   }
   return launchExtension(target, tier, wantWatch, displayMode);
 }

package/dist/commands/launch/mobile.js

@@ -1,11 +1,18 @@
 import { prepareMobile } from "../../adapters/mobile/prepare.js";
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
-async function launchMobile(target, mobileTarget, tier, json, restartApp = false) {
+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" ? "auto" : "fast";
-  return prepareMobile(target, { platform, json, watcherPort, preflightMode, restartApp });
+  return prepareMobile(target, {
+    platform,
+    json,
+    watcherPort,
+    preflightMode,
+    restartApp,
+    clearMetro
+  });
 }
 export {
   launchMobile

package/dist/commands/run-engine.js

@@ -135,10 +135,12 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
     process.env.METAMASK_RECIPE_LIVE_ADAPTER_DIR
   );
   const { createMetaMaskRunner } = await import("../runner.js");
+  const recipeDocument = runtimeRecipeDocument(recipe, absoluteRecipePath);
+  const suppressHudForLifecycleTiming = adapter === "mobile" && mobileRecipeRequiresUninterruptedLifecycleTiming(recipeDocument);
   const runner = await createMetaMaskRunner(adapter, manifest, {
     quietStdout: runtimeOptions.stdoutIsMachineContract === true,
     suppressLibraryResolutionLogs: runtimeOptions.suppressLibraryResolutionLogs,
-    autoHud: trust.source && trust.source.trust !== "trusted" ? false : runtimeOptions.autoHud,
+    autoHud: suppressHudForLifecycleTiming ? 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
@@ -169,6 +171,25 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
     }
   };
 }
+function runtimeRecipeDocument(recipe, absoluteRecipePath) {
+  if (typeof recipe !== "string") return recipe;
+  if (!absoluteRecipePath || !fs.existsSync(absoluteRecipePath)) return void 0;
+  try {
+    return JSON.parse(fs.readFileSync(absoluteRecipePath, "utf8"));
+  } catch {
+    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;
@@ -1126,11 +1147,20 @@ async function recoverRunInfra(adapter, target, json) {
   }
   if (adapter === "mobile") {
     const { launchMobile } = await import("./launch/mobile.js");
-    const platform = process.env.PLATFORM === "android" ? "android" : "ios";
+    const platform = resolveMobileRecoveryPlatform();
     return launchMobile(target, platform, "quick", json);
   }
   return { status: 0, output: "headless run retry" };
 }
+function resolveMobileRecoveryPlatform(env = process.env) {
+  if (env.PLATFORM === "android" || env.PLATFORM === "ios") return env.PLATFORM;
+  const androidPinned = Boolean(
+    env.ADB_SERIAL || env.ANDROID_SERIAL || env.ANDROID_TARGET_DEVICE_NAME || env.ANDROID_DEVICE
+  );
+  const iosPinned = Boolean(env.IOS_SIMULATOR || env.SIM_UDID);
+  if (androidPinned && !iosPinned) return "android";
+  return "ios";
+}
 function readRunFailureText(result) {
   try {
     const trace = JSON.parse(fs.readFileSync(result.tracePath, "utf8"));
@@ -1218,10 +1248,12 @@ export {
   ensureMobileProofRuntime,
   executeWithHealBounds,
   listRunnableRecipes,
+  mobileRecipeRequiresUninterruptedLifecycleTiming,
   preflightRecipe,
   prepareHeal,
   recoverRunInfra,
   resolveMetaMaskLibrarySources,
+  resolveMobileRecoveryPlatform,
   resolveRunRecipeArg,
   runOneNode,
   runRecipe,

package/dist/devices.js

@@ -6,6 +6,12 @@ function listConnectedDevices(platform) {
   if (!platform || platform === "ios") devices.push(...listIosSimulators());
   return devices;
 }
+function findAvailableIosSimulatorById(id) {
+  for (const simulator of listIosSimulators("available")) {
+    if (simulator.id === id) return simulator;
+  }
+  return void 0;
+}
 function listAndroidDevices() {
   const adbPath = resolveMobileToolPath("adb");
   if (!adbPath) return [];
@@ -33,10 +39,10 @@ function listAndroidDevices() {
   }
   return devices;
 }
-function listIosSimulators() {
+function listIosSimulators(scope = "booted") {
   let output;
   try {
-    output = execFileSync("xcrun", ["simctl", "list", "devices", "booted", "-j"], {
+    output = execFileSync("xcrun", ["simctl", "list", "devices", scope, "-j"], {
       encoding: "utf8",
       timeout: 5e3,
       stdio: ["ignore", "pipe", "ignore"]
@@ -65,5 +71,6 @@ function listIosSimulators() {
   return devices;
 }
 export {
+  findAvailableIosSimulatorById,
   listConnectedDevices
 };

package/dist/heal-bounds.js

@@ -61,6 +61,7 @@ async function ensureOverlay(adapter, target, heal, state, json) {
   return { ok: true };
 }
 function classifyFailure(output) {
+  if (/SCREENSHOT_PROTECTED|screenshot is protected by FLAG_SECURE/iu.test(output)) return "screenshot-protected";
   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";
@@ -86,6 +87,15 @@ function checkHealBounds(target, output, state) {
     };
   }
   const failureClass = classifyFailure(output);
+  if (failureClass === "screenshot-protected") {
+    return {
+      code: "SCREENSHOT_PROTECTED",
+      exitCode: EXIT.runtime,
+      message: "the focused Android window intentionally blocks screenshots; a black capture cannot be used as evidence.",
+      userAction: "unlock or navigate to a non-protected screen, then rerun the screenshot action",
+      originalError
+    };
+  }
   if (failureClass === "wallet") {
     return {
       code: "WALLET_STATE_REQUIRED",