@deeeed/metamask-harness 0.36.0 → 0.38.0

package/dist/adapters.js

@@ -12,10 +12,16 @@ import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-p
 import { resolveWalletImportCredentials, validateWalletImportOptions } from "../library/actions/shared/wallet/import-source.mjs";
 const execFileAsync = promisify(execFile);
 const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
+  "ui.press",
+  "ui.key_press",
+  "ui.set_input",
+  "ui.scroll",
   "ui.swipe",
   "ui.pan",
   "ui.drag",
   "ui.long_press",
+  "ui.wait_for",
+  "ui.screenshot",
   "ui.capture_surface"
 ]);
 function sleep(ms) {
@@ -29,7 +35,42 @@ function simpleAdapter(action, executor) {
     }
   };
 }
-const LIVE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
+const LIVE_ONLY_ACTIONS = /* @__PURE__ */ new Set([
+  "metamask.assets.read_visible_state",
+  "metamask.assets.read_details",
+  "metamask.assets.verify_sorting",
+  "metamask.assets.set_token_visibility",
+  "metamask.assets.import_custom_token",
+  "metamask.assets.prepare_send",
+  "metamask.assets.review_send",
+  "metamask.assets.finish_send",
+  "metamask.assets.set_custom_gas",
+  "metamask.assets.select_network_scope",
+  "metamask.wallet.lock",
+  "metamask.networks.read_visible_state",
+  "metamask.networks.add_custom",
+  "metamask.networks.add_chainlist",
+  "metamask.networks.remove_custom",
+  "metamask.perps.read_visible_state",
+  "metamask.perps.compare_provider_market",
+  "metamask.perps.read_eligibility",
+  "metamask.perps.select_market_filter",
+  "metamask.perps.close_visible_position",
+  "metamask.perps.set_market_favorite",
+  "metamask.perps.select_activity_filter",
+  "metamask.perps.open_balance_action",
+  "metamask.perps.open_position_action",
+  "metamask.perps.edit_margin",
+  "metamask.perps.update_position_tpsl",
+  "metamask.perps.read_funds_confirmation",
+  "metamask.swap_bridge.read_visible_state",
+  "metamask.swap_bridge.select_assets",
+  "metamask.swap_bridge.set_amount",
+  "metamask.swap_bridge.set_max_amount",
+  "metamask.swap_bridge.set_slippage",
+  "metamask.swap_bridge.submit_transaction",
+  "metamask.settings.set_basic_functionality",
+  "metamask.perps.read_snapshot",
   "metamask.perps.read_positions",
   "metamask.perps.ensure_positions",
   "metamask.perps.assert_positions",
@@ -47,8 +88,7 @@ const LIVE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.capture_performance"
 ]);
 const CORE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
-  "metamask.perps.read_account",
-  "metamask.perps.read_snapshot"
+  "metamask.perps.read_account"
 ]);
 const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
@@ -61,7 +101,7 @@ const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
 ]);
 const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set(["ui.navigate"]);
 function requiresLiveAdapter(platform, action) {
-  return LIVE_ONLY_PERPS_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
+  return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
 }
 function liveRuntimeConfigured(platform, node) {
   if (platform === "mobile" || platform === "core") return true;
@@ -209,6 +249,36 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
   ];
   const bundledActions = [
     ...walletActions,
+    "metamask.assets.read_visible_state",
+    ...platform === "extension" ? ["metamask.assets.read_details"] : [],
+    ...platform === "extension" ? ["metamask.assets.verify_sorting"] : [],
+    ...platform === "extension" ? ["metamask.assets.set_token_visibility"] : [],
+    ...platform === "extension" ? ["metamask.assets.import_custom_token"] : [],
+    ...platform === "extension" ? [
+      "metamask.assets.prepare_send",
+      "metamask.assets.review_send",
+      "metamask.assets.finish_send",
+      "metamask.assets.set_custom_gas",
+      "metamask.assets.select_network_scope"
+    ] : [],
+    ...platform === "extension" ? ["metamask.wallet.lock"] : [],
+    ...platform === "extension" ? ["metamask.networks.read_visible_state"] : [],
+    ...platform === "extension" ? ["metamask.networks.add_custom", "metamask.networks.add_chainlist", "metamask.networks.remove_custom"] : [],
+    "metamask.perps.read_visible_state",
+    ...platform === "extension" ? ["metamask.perps.compare_provider_market"] : [],
+    ...platform === "extension" ? ["metamask.perps.read_eligibility"] : [],
+    ...platform === "extension" ? [
+      "metamask.perps.open_position_action",
+      "metamask.perps.edit_margin",
+      "metamask.perps.update_position_tpsl"
+    ] : [],
+    "metamask.swap_bridge.read_visible_state",
+    "metamask.swap_bridge.select_assets",
+    "metamask.swap_bridge.set_amount",
+    ...platform === "extension" ? ["metamask.swap_bridge.set_max_amount"] : [],
+    ...platform === "extension" ? ["metamask.swap_bridge.set_slippage"] : [],
+    ...platform === "extension" ? ["metamask.swap_bridge.submit_transaction"] : [],
+    ...platform === "extension" ? ["metamask.settings.set_basic_functionality"] : [],
     "metamask.perps.read_positions",
     "metamask.perps.ensure_positions",
     "metamask.perps.assert_positions",
@@ -221,13 +291,14 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
     "metamask.perps.start_state",
     "metamask.perps.teardown_state",
     "metamask.perps.capture_performance",
+    ...platform === "extension" || platform === "core" ? ["metamask.perps.read_snapshot"] : [],
     ...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", "metamask.perps.read_snapshot"] : []
+    ...platform === "core" ? ["metamask.perps.read_account"] : []
   ];
   const bundled = new Set(bundledActions);
   const actions = [.../* @__PURE__ */ new Set([...bundledActions, ...declaredCustomActions])];
@@ -662,6 +733,7 @@ async function handleMobileHud(payload, context) {
   }
 }
 async function hideMobileHudOnTeardown(projectRoot, env = {}) {
+  if (env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") return;
   if (process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false") return;
   const input = {
     node: { bridge_timeout_ms: 8e3, cdp_timeout_ms: 5e3 },
@@ -803,7 +875,7 @@ function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters) {
         if (live) return live.output;
         throw new Error(`ui.navigate requires library/actions/${platform}/ui/navigate.mjs.`);
       }
-      if (platform === "mobile" && NATIVE_PROVIDER_UI_ACTIONS.has(action)) {
+      if (platform === "mobile" && NATIVE_PROVIDER_UI_ACTIONS.has(action) && (context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || ["ui.swipe", "ui.pan", "ui.drag", "ui.long_press", "ui.capture_surface"].includes(action))) {
         return executeNativeProviderAction(action, node, context, harness.createNativeUiTransport);
       }
       return base.execute(action, action === "ui.wait_for" ? normalizeUiWaitNode(node) : node, context);

package/dist/app-lifecycle.js

@@ -1,6 +1,7 @@
 function resolveMetaMaskMobileLifecycleTarget(node, rawContext) {
   const context = rawContext;
   const platform = resolveMobilePlatform(node, context);
+  const opaqueRuntime = context.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
   const port = scalar(node.watcher_port ?? node.metro_port, "app.lifecycle.metro_port") ?? context.env.WATCHER_PORT ?? context.env.METRO_PORT ?? process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "8081";
   const launchUrl = scalar(node.launch_url ?? node.launchUrl ?? node.url, "app.lifecycle.launch_url") ?? expoDevClientUrl(port, platform);
   if (platform === "android") {
@@ -8,9 +9,9 @@ function resolveMetaMaskMobileLifecycleTarget(node, rawContext) {
       platform,
       deviceId: scalar(node.adb_serial ?? node.android_device ?? node.device, "app.lifecycle.device") ?? context.env.ADB_SERIAL ?? context.env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL,
       appId: scalar(node.package_id ?? node.packageName ?? node.app_id, "app.lifecycle.package_id") ?? context.env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask",
-      launchUrl,
-      metroPort: port,
-      prelaunchCalls: expoBundlePrewarmCalls(port, "android")
+      launchUrl: opaqueRuntime ? void 0 : launchUrl,
+      metroPort: opaqueRuntime ? void 0 : port,
+      prelaunchCalls: opaqueRuntime ? [] : expoBundlePrewarmCalls(port, "android")
     };
   }
   return {

package/dist/command-contract.js

@@ -239,6 +239,22 @@ const PUBLIC_COMMAND_CONTRACTS = {
     }),
     positionals: [{ label: "platform", choices: ["ios", "android"] }]
   },
+  "runtime-launch": {
+    options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, MOBILE_PLATFORM, {
+      "--cdp-port": value(),
+      "--chrome-user-data-dir": value(),
+      "--artifacts-dir": value(),
+      "--start-watch": bool(),
+      "--build-lavamoat": bool(),
+      "--remote-flag": value(),
+      "--artifact-file": value(),
+      "--artifact-version": value(),
+      "--artifact-build-id": value(),
+      "--artifact-package-id": value(),
+      "--artifact-sha256": value(),
+      "--artifact-cache": value()
+    })
+  },
   logs: {
     options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
       "--full": bool(),

package/dist/commands/call.js

@@ -40,6 +40,7 @@ import {
   synthesizeOneNodeRecipe,
   validateRecipeAdapterAware
 } from "./run-engine.js";
+import { readMobileReleaseArtifactState } from "../adapters/mobile/release-artifact-state.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
 import { recipeTrustFailure } from "../recipe-security.js";
@@ -267,7 +268,7 @@ async function handleCall(argv) {
   }
   try {
     const prepared = await prepareHeal(adapter, target, options, json, {
-      skipMobileSourceFreshness: adapter === "mobile" && resolvedAction === "app.lifecycle"
+      skipMobileSourceFreshness: adapter === "mobile" && (resolvedAction === "app.lifecycle" || readMobileReleaseArtifactState(target) !== null)
     });
     if (typeof prepared === "number") return prepared;
     const { state, heal } = prepared;
@@ -289,7 +290,10 @@ async function handleCall(argv) {
       target,
       heal,
       state,
-      () => recoverRunInfra(adapter, target, json)
+      () => recoverRunInfra(adapter, target, json, {
+        cdpPort: optionString(options, "cdpPort"),
+        watcherPort: optionString(options, "watcherPort") ?? optionString(options, "metroPort")
+      })
     );
     if (violation !== null) {
       const conciseFailure = violation.originalError ? conciseFailureForHuman(violation.originalError) : "";

package/dist/commands/launch/extension.js

@@ -21,7 +21,11 @@ import {
   extensionProductConfigBlock,
   extensionProductConfigFingerprint
 } from "../../adapters/extension/product-config.js";
-import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
+import {
+  isExtensionDistStale,
+  releaseArtifactState,
+  runtimeDistCheck
+} from "../../adapters/extension/runtime-decision.js";
 import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js";
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
 import { isExtensionWatcherLive, stopExtensionWatcher } from "../../adapters/slot-ports.js";
@@ -52,10 +56,28 @@ async function installExtensionDeps(target) {
   return result;
 }
 async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
+  const requestedCdpPort = process.env.CDP_PORT;
+  const requestedRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+  const restoreRequestedPorts = () => {
+    if (requestedCdpPort) process.env.CDP_PORT = requestedCdpPort;
+    if (requestedRecipeCdpPort) process.env.RECIPE_CDP_PORT = requestedRecipeCdpPort;
+  };
   if (process.env.CHROME_USER_DATA_DIR) {
     process.env.CHROME_USER_DATA_DIR = path.resolve(process.env.CHROME_USER_DATA_DIR);
   }
-  const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target);
+  const artifact = releaseArtifactState(target);
+  const artifactSnapshot = runtimeDistCheck(target, artifact);
+  const artifactLaunchable = !wantWatch && tier !== "build" && artifact.status === "valid" && artifactSnapshot.status === "fresh";
+  const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target, artifact);
+  restoreRequestedPorts();
+  if (artifact.status !== "none" && !reusable && !artifactLaunchable) {
+    const detail = artifact.status === "invalid" ? `identity is invalid: ${artifact.reason ?? "unknown reason"}` : "runtime is not healthy and reusable";
+    return {
+      status: EXIT.infra,
+      output: `RELEASE_ARTIFACT_NOT_REUSABLE: The loaded release artifact ${detail}.
+Next: rerun runtime-launch with the same artifact source.`
+    };
+  }
   if (!reusable) {
     const block = extensionProductConfigBlock(target);
     if (block) {
@@ -67,6 +89,7 @@ Next: ${block.userAction}`
     }
   }
   await ensureHarnessFresh(target, "extension");
+  restoreRequestedPorts();
   if (wantWatch) {
     const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
     const watchArgs = ["--target", target];
@@ -78,20 +101,35 @@ Next: ${block.userAction}`
     return extensionRebuild(target);
   }
   if (reusable) {
+    if (artifact.status === "valid") {
+      console.error(colorHumanMessage(
+        `\u2192 extension release reuse \u2014 verified artifact ${artifact.manifestVersion ?? artifact.expectedVersion ?? ""} \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no snapshot mutation)`
+      ));
+      return { status: EXIT.ok, output: "Verified release artifact runtime is already healthy." };
+    }
     return extensionReattach(target, displayMode);
   }
+  if (artifactLaunchable) {
+    return extensionLaunchReleaseArtifact(target, artifact);
+  }
   return extensionLaunchDevelopment(target);
 }
-async function extensionRuntimeReusable(target) {
+async function extensionRuntimeReusable(target, artifact = releaseArtifactState(target)) {
   const cdpPort = process.env.CDP_PORT;
   if (!cdpPort) return false;
-  if (isExtensionDistStale(target)) return false;
-  if (isExtensionWatcherLive(target) && !harnessWatcherMatchesProductConfig(target)) return false;
-  if (!extensionCompiledScriptsMatchProductConfig(target, expectedRuntimeDist(target))) return false;
+  const runtimeSnapshot = runtimeDistCheck(target, artifact);
+  const releaseArtifact = runtimeSnapshot.source === "release-artifact";
+  if (releaseArtifact) {
+    if (runtimeSnapshot.status !== "fresh") return false;
+  } else {
+    if (isExtensionDistStale(target)) return false;
+    if (isExtensionWatcherLive(target) && !harnessWatcherMatchesProductConfig(target)) return false;
+    if (!extensionCompiledScriptsMatchProductConfig(target, expectedRuntimeDist(target))) return false;
+  }
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const reachable = await cdpVersionReachable(cdpPort);
     const nonceOwned = reachable && await cdpOwnedByRuntimeNonce(cdpPort, target);
-    const owned = nonceOwned || reachable && cdpOwnedByExpectedRuntime(cdpPort, target);
+    const owned = nonceOwned || reachable && cdpOwnedByExpectedRuntime(cdpPort, target, releaseArtifact ? artifact.chromeUserDataDir : void 0);
     const targetPresent = owned && await cdpHasExpectedExtensionTarget(cdpPort, target);
     const healthy = targetPresent && await cdpRuntimeHealthy(cdpPort, target);
     if (healthy) return true;
@@ -118,9 +156,9 @@ function commandHasExactFlagValue(command, flag, value) {
   }
   return false;
 }
-function cdpOwnedByExpectedRuntime(port, target) {
+function cdpOwnedByExpectedRuntime(port, target, profileOverride) {
   const pids = cdpListenerPids(port);
-  const profile = expectedChromeProfile(target);
+  const profile = profileOverride ?? expectedChromeProfile(target);
   const runtimeDist = expectedRuntimeDist(target);
   for (const pid of pids) {
     try {
@@ -344,6 +382,33 @@ async function extensionLaunchDevelopment(target) {
   ));
   return spawnScriptStreaming(liveScript, liveArgs, target);
 }
+async function extensionLaunchReleaseArtifact(target, artifact) {
+  if (!artifact.sourceDir || !artifact.provenancePath || !artifact.chromeUserDataDir) {
+    return {
+      status: EXIT.infra,
+      output: "RELEASE_ARTIFACT_NOT_REUSABLE: The loaded release artifact identity is incomplete.\nNext: rerun runtime-launch with the same artifact source."
+    };
+  }
+  const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
+  const liveArgs = [
+    "--target",
+    target,
+    "--external-artifact",
+    "--dist-dir",
+    artifact.sourceDir,
+    "--artifact-provenance",
+    artifact.provenancePath,
+    "--preserve-profile",
+    "--chrome-user-data-dir",
+    artifact.chromeUserDataDir
+  ];
+  if (process.env.CDP_PORT) liveArgs.push("--cdp-port", process.env.CDP_PORT);
+  if (process.env.EXTENSION_START_URL) liveArgs.push("--start-url", process.env.EXTENSION_START_URL);
+  console.error(colorHumanMessage(
+    `\u2192 extension release relaunch \u2014 verified artifact ${artifact.manifestVersion ?? artifact.expectedVersion ?? ""} \xB7 CDP :${process.env.CDP_PORT ?? "default"}`
+  ));
+  return spawnScriptStreaming(liveScript, liveArgs, target);
+}
 function harnessWatcherMatchesProductConfig(target) {
   const runtimeDir = path.join(target, recipeRuntimeDir());
   const harnessPidFile = path.join(runtimeDir, "recipe-harness-webpack.pid");

package/dist/commands/launch/index.js

@@ -562,6 +562,9 @@ async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget,
     stream.phase("verify");
     const verifyArgs = ["verify", "--adapter", adapter, "--target", target];
     if (adapter === "mobile" && mobileTarget) verifyArgs.push("--platform", mobileTarget);
+    if (adapter === "extension" && process.env.CDP_PORT) {
+      verifyArgs.push("--cdp-port", process.env.CDP_PORT);
+    }
     if (machine) verifyArgs.push("--json");
     const exitCode = await handleHarness(verifyArgs);
     if (stream.enabled) {

package/dist/commands/launch/mobile.js

@@ -4,8 +4,10 @@ import {
   recordMobileSourceBaseline
 } from "../../adapters/mobile/source-freshness.js";
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
+import { clearMobileReleaseArtifactState } from "../../adapters/mobile/release-artifact-state.js";
 import { EXIT } from "../shared.js";
 async function launchMobile(target, mobileTarget, tier, json, restartApp = false, clearMetro = false) {
+  clearMobileReleaseArtifactState(target);
   await ensureHarnessFresh(target, "mobile");
   const platform = mobileTarget ?? "ios";
   const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : void 0;

package/dist/commands/provision.js

@@ -1,6 +1,7 @@
 import { detectAdapter } from "../harness.js";
 import { assertAdapter } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
+import { clearMobileReleaseArtifactState } from "../adapters/mobile/release-artifact-state.js";
 import { ADAPTER_DETECT_NEXT, usageOut, writeInteractiveProgress } from "./shared.js";
 import {
   applyWatcherPortOption,
@@ -28,6 +29,7 @@ async function handleProvision({ positional, options, rawArgv }) {
   const platform = optionString(options, "platform") ?? optionString(options, "devicePlatform") ?? (positional[0] === "runway" ? positional[1] : positional[0]) ?? "ios";
   if (adapter === "mobile") {
     writeInteractiveProgress(json, `\u2192 provision mobile ${platform} \u2014 resolving simulator and Runway artifact`);
+    if (!optionFlag(options, "resolveOnly")) clearMobileReleaseArtifactState(target);
   }
   const result = await surface.runwayProvision.run(target, {
     json,

package/dist/commands/run-engine.js

@@ -13,6 +13,9 @@ import {
 import { resolveActionManifest, validateManifest } from "../manifest.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { extensionProductConfigBlock } from "../adapters/extension/product-config.js";
+import {
+  requireCurrentMobileReleaseArtifactState
+} from "../adapters/mobile/release-artifact-state.js";
 import {
   importRecipeHarness,
   importRecipeProtocol,
@@ -137,10 +140,11 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
   const { createMetaMaskRunner } = await import("../runner.js");
   const recipeDocument = runtimeRecipeDocument(recipe, absoluteRecipePath);
   const suppressHudForLifecycleTiming = adapter === "mobile" && mobileRecipeRequiresUninterruptedLifecycleTiming(recipeDocument);
+  const suppressHudForOpaqueMobile = adapter === "mobile" && process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
   const runner = await createMetaMaskRunner(adapter, manifest, {
     quietStdout: runtimeOptions.stdoutIsMachineContract === true,
     suppressLibraryResolutionLogs: runtimeOptions.suppressLibraryResolutionLogs,
-    autoHud: suppressHudForLifecycleTiming ? false : trust.source && trust.source.trust !== "trusted" ? false : runtimeOptions.autoHud,
+    autoHud: suppressHudForLifecycleTiming || 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
@@ -216,6 +220,10 @@ function activateRecipeRuntimeEnvironment(adapter, projectRoot, runtimeOptions)
   const previousWatcherPort = process.env.WATCHER_PORT;
   const previousMetroPort = process.env.METRO_PORT;
   const previousExtensionAutolaunch = process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH;
+  const previousMobileOpaqueRuntime = process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME;
+  const previousAndroidPackageId = process.env.ANDROID_PACKAGE_ID;
+  const previousAdbSerial = process.env.ADB_SERIAL;
+  const previousAndroidSerial = process.env.ANDROID_SERIAL;
   getAdapterSurface(adapter).resolveSlotPorts(projectRoot);
   if (runtimeOptions.cdpPort) {
     process.env.CDP_PORT = runtimeOptions.cdpPort;
@@ -228,6 +236,21 @@ function activateRecipeRuntimeEnvironment(adapter, projectRoot, runtimeOptions)
   if (runtimeOptions.launchExistingDist) {
     process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH = "1";
   }
+  if (adapter === "mobile") {
+    const state = requireCurrentMobileReleaseArtifactState(projectRoot);
+    if (state) {
+      const selected = process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
+      if (selected && selected !== state.deviceSerial) {
+        throw new Error(
+          `The Mobile release artifact is installed on ${state.deviceSerial}, not ${selected}. Next: rerun runtime-launch for ${selected}.`
+        );
+      }
+      process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME = "1";
+      process.env.ANDROID_PACKAGE_ID = state.packageId;
+      process.env.ADB_SERIAL = state.deviceSerial;
+      process.env.ANDROID_SERIAL = state.deviceSerial;
+    }
+  }
   return () => {
     restoreEnv("CDP_PORT", previousCdpPort);
     restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
@@ -237,6 +260,13 @@ function activateRecipeRuntimeEnvironment(adapter, projectRoot, runtimeOptions)
       "METAMASK_RECIPE_EXTENSION_AUTOLAUNCH",
       previousExtensionAutolaunch
     );
+    restoreEnv(
+      "METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME",
+      previousMobileOpaqueRuntime
+    );
+    restoreEnv("ANDROID_PACKAGE_ID", previousAndroidPackageId);
+    restoreEnv("ADB_SERIAL", previousAdbSerial);
+    restoreEnv("ANDROID_SERIAL", previousAndroidSerial);
   };
 }
 function actionSourceMap(sources) {
@@ -267,12 +297,23 @@ function recipeRunEnv(adapter, runtimeOptions = {}) {
     ANDROID_DEVICE: process.env.ANDROID_DEVICE,
     ANDROID_TARGET_DEVICE_NAME: process.env.ANDROID_TARGET_DEVICE_NAME,
     ADB_SERIAL: process.env.ADB_SERIAL,
-    ANDROID_SERIAL: process.env.ANDROID_SERIAL
+    ANDROID_SERIAL: process.env.ANDROID_SERIAL,
+    ANDROID_PACKAGE_ID: process.env.ANDROID_PACKAGE_ID,
+    METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME: process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME
   };
 }
 async function prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions) {
   if (adapter !== "extension" || runtimeOptions.skipExtensionRuntimePrepare === true)
     return;
+  const { releaseArtifactState, runtimeDistCheck } = await import("../adapters/extension/runtime-decision.js");
+  const artifact = releaseArtifactState(projectRoot);
+  const runtimeSnapshot = runtimeDistCheck(projectRoot, artifact);
+  if (artifact.status !== "none") {
+    if (artifact.status === "valid" && runtimeSnapshot.status === "fresh") return;
+    throw new Error(
+      "The loaded release artifact identity is invalid or stale. Next: rerun runtime-launch with the same artifact source."
+    );
+  }
   const { prepareExtensionRuntime } = await import("../adapters/extension/runtime.js");
   await prepareExtensionRuntime({
     projectRoot,
@@ -306,7 +347,7 @@ async function validateRecipeAdapterAware(adapter, recipe, manifest, librarySour
   );
   const findings = [
     ...withManifest.findings,
-    ...validateMetaMaskActionInputs(recipe)
+    ...validateMetaMaskActionInputs(recipe, adapter)
   ];
   if (withManifest.status === "valid" && isRecord(recipe) && libraryResolution) {
     try {
@@ -336,7 +377,7 @@ async function validateRecipeAdapterAware(adapter, recipe, manifest, librarySour
             manifest,
             validationOptions
           ).findings,
-          ...validateMetaMaskActionInputs(dependency.document)
+          ...validateMetaMaskActionInputs(dependency.document, adapter)
         );
       }
     } catch (error) {
@@ -782,6 +823,7 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     return EXIT.usage;
   }
   const state = newHealState();
+  const mobileArtifact = adapter === "mobile" ? requireCurrentMobileReleaseArtifactState(target) : null;
   prepareOptions.onPhase?.("install");
   const ensured = await ensureOverlay(
     adapter,
@@ -847,7 +889,7 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
       restoreEnv("WATCHER_PORT", previousWatcherPort);
     }
   }
-  if (adapter === "mobile" && prepareOptions.skipMobileSourceFreshness !== true) {
+  if (adapter === "mobile" && mobileArtifact === null && prepareOptions.skipMobileSourceFreshness !== true) {
     const current = await ensureMobileProofRuntime(
       target,
       heal,
@@ -994,6 +1036,22 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
   });
   const initial = await decide();
   if (initial.decision === "ready") return null;
+  if (initial.reasonCode === "release-artifact-identity-invalid" || initial.reasonCode === "release-artifact-runtime-missing" || initial.reasonCode === "release-artifact-runtime-stale") {
+    const message = initial.reasons[0] ?? "The loaded release artifact identity is invalid.";
+    const userAction2 = "rerun runtime-launch with the same artifact source";
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        status: "fail",
+        recoverable: false,
+        error: { code: "RELEASE_ARTIFACT_NOT_CURRENT", message, userAction: userAction2 }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 ${message}`);
+      console.error(`  Next: ${userAction2}`);
+    }
+    return EXIT.infra;
+  }
   if (initial.reasonCode === "runtime-dist-check-failed") {
     const message = `Extension proof runtime freshness could not be checked: ${initial.reasons[0] ?? initial.decision}`;
     const userAction2 = `mm-harness doctor --adapter extension --target ${JSON.stringify(path.resolve(target))}`;
@@ -1139,18 +1197,54 @@ const RUN_RECOVERY_CODE = {
   extension: "extension.runtime_recovered",
   core: "run.retried"
 };
-async function recoverRunInfra(adapter, target, json) {
+async function recoverRunInfra(adapter, target, json, runtimeOptions = {}) {
   getAdapterSurface(adapter).resolveSlotPorts(target);
-  if (adapter === "extension") {
-    const { launchExtension } = await import("./launch/extension.js");
-    return launchExtension(target, "quick", false);
+  const previousCdpPort = process.env.CDP_PORT;
+  const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+  if (runtimeOptions.cdpPort) {
+    process.env.CDP_PORT = runtimeOptions.cdpPort;
+    process.env.RECIPE_CDP_PORT = runtimeOptions.cdpPort;
   }
-  if (adapter === "mobile") {
-    const { launchMobile } = await import("./launch/mobile.js");
-    const platform = resolveMobileRecoveryPlatform();
-    return launchMobile(target, platform, "quick", json);
+  try {
+    if (adapter === "extension") {
+      const { releaseArtifactState } = await import("../adapters/extension/runtime-decision.js");
+      const artifact = releaseArtifactState(target);
+      if (artifact.status !== "none" && artifact.status !== "valid") {
+        return {
+          status: 1,
+          output: "Release artifact recovery cannot trust the recorded runtime identity.\nNext: rerun runtime-launch with the same artifact source."
+        };
+      }
+      const { launchExtension } = await import("./launch/extension.js");
+      return launchExtension(target, "quick", false);
+    }
+    if (adapter === "mobile") {
+      try {
+        const artifact = requireCurrentMobileReleaseArtifactState(target);
+        if (artifact) {
+          const { relaunchAndroidReleaseArtifactRuntime } = await import("../adapters/mobile/release-artifact.js");
+          await relaunchAndroidReleaseArtifactRuntime(artifact);
+          return {
+            status: 0,
+            output: `Relaunched ${artifact.packageId} ${artifact.versionName} (${artifact.versionCode}) on ${artifact.deviceSerial}.`
+          };
+        }
+      } catch (error) {
+        return {
+          status: 1,
+          output: `Release artifact recovery could not revalidate and relaunch the pinned Android package: ${error instanceof Error ? error.message : String(error)}
+Next: rerun runtime-launch with the same artifact source.`
+        };
+      }
+      const { launchMobile } = await import("./launch/mobile.js");
+      const platform = resolveMobileRecoveryPlatform();
+      return launchMobile(target, platform, "quick", json);
+    }
+    return { status: 0, output: "headless run retry" };
+  } finally {
+    restoreEnv("CDP_PORT", previousCdpPort);
+    restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
   }
-  return { status: 0, output: "headless run retry" };
 }
 function resolveMobileRecoveryPlatform(env = process.env) {
   if (env.PLATFORM === "android" || env.PLATFORM === "ios") return env.PLATFORM;
@@ -1251,6 +1345,7 @@ export {
   mobileRecipeRequiresUninterruptedLifecycleTiming,
   preflightRecipe,
   prepareHeal,
+  prepareRuntimeIfNeeded,
   recoverRunInfra,
   resolveMetaMaskLibrarySources,
   resolveMobileRecoveryPlatform,

package/dist/commands/run.js

@@ -29,6 +29,7 @@ import { handleDescribeRecipe, handleListExecutables } from "./list-executables.
 import { applyDeviceTargeting } from "./device-target.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { coreDependencyBlock } from "./core-readiness.js";
+import { readMobileReleaseArtifactState } from "../adapters/mobile/release-artifact-state.js";
 import { writeRunReport } from "./run-report.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
 import { JsonStreamWriter } from "../json-stream.js";
@@ -250,7 +251,8 @@ async function handleRunInner({ positional, options }, stream) {
   }
   try {
     const prepared = await prepareHeal(adapter, target, options, machine, {
-      onPhase: (phase, fields) => stream.phase(phase, fields)
+      onPhase: (phase, fields) => stream.phase(phase, fields),
+      skipMobileSourceFreshness: adapter === "mobile" && readMobileReleaseArtifactState(target) !== null
     });
     if (typeof prepared === "number") {
       stream.error({
@@ -282,7 +284,7 @@ async function handleRunInner({ positional, options }, stream) {
       target,
       heal,
       state,
-      () => recoverRunInfra(adapter, target, machine),
+      () => recoverRunInfra(adapter, target, machine, runtimeOptions),
       (code) => stream.phase("recover", { code })
     );
     for (const mutation of state.mutations) stream.mutation(mutation);