@deeeed/metamask-harness 0.36.0 → 0.38.0

package/dist/commands/runtime-launch.js

@@ -1,6 +1,14 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import {
+  acquireExtensionReleaseArtifact
+} from "../adapters/extension/release-artifact.js";
+import { installAndroidReleaseArtifact } from "../adapters/mobile/release-artifact.js";
+import {
+  clearMobileReleaseArtifactState,
+  writeMobileReleaseArtifactState
+} from "../adapters/mobile/release-artifact-state.js";
 import { recipeHarnessPath } from "../paths.js";
 import {
   adapterOption,
@@ -13,9 +21,56 @@ import {
   usageError
 } from "./parse-args.js";
 async function handleRuntimeLaunch({ options }) {
+  if (optionFlag(options, "help")) {
+    console.log(`mm-harness runtime-launch --adapter <extension|mobile> --target <checkout> [flags]
+
+  --artifact-file <path>     Artifact downloaded by the validation skill
+  --artifact-version <X.Y.Z> Expected manifest or Android version name
+  --artifact-sha256 <digest> Trusted SHA-256 from the acquisition step
+  --artifact-build-id <id>   Android version code
+  --artifact-package-id <id> Android application ID
+  --artifact-cache <dir>     Artifact cache root
+  --platform <android>       Mobile artifact platform (iOS is unsupported)
+  --device <serial>          Explicit Android device serial
+  --cdp-port <port>          Extension CDP port
+  --chrome-user-data-dir     Isolated Chrome profile path
+  --artifacts-dir <dir>      Validation evidence directory
+  --json                     Machine-readable terminal report
+
+  The harness verifies and runs a local artifact but never downloads one. Extension
+  launch resets an isolated profile. Android install requires an explicit serial.`);
+    return 0;
+  }
   const adapter = adapterOption(options);
   const target = targetPath(options);
+  const artifactFile = optionString(options, "artifactFile");
+  const artifactVersion = optionString(options, "artifactVersion");
+  const artifactSha256 = optionString(options, "artifactSha256");
+  const artifactBuildId = optionString(options, "artifactBuildId");
+  const artifactPackageId = optionString(options, "artifactPackageId");
+  const artifactCache = optionString(options, "artifactCache");
+  const artifactRequested = Boolean(
+    artifactFile || artifactVersion || artifactSha256 || artifactBuildId || artifactPackageId || artifactCache
+  );
+  if (artifactRequested && (!artifactFile || !artifactVersion || !artifactSha256)) {
+    throw usageError("artifact launch requires --artifact-file, --artifact-version, and --artifact-sha256 together.");
+  }
+  if (adapter === "mobile") {
+    return handleAndroidArtifactLaunch({
+      options,
+      target,
+      artifactFile,
+      artifactVersion,
+      artifactSha256,
+      artifactBuildId,
+      artifactPackageId,
+      artifactCache
+    });
+  }
   if (adapter !== "extension") throw new Error("runtime-launch currently applies to the extension adapter.");
+  if (artifactBuildId || artifactPackageId || optionString(options, "platform") || optionString(options, "device")) {
+    throw usageError("Extension runtime-launch does not accept Android artifact options.");
+  }
   const cdpPort = parsePort(
     optionString(options, "cdpPort") ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
     "runtime-launch requires --cdp-port <port>."
@@ -29,7 +84,19 @@ async function handleRuntimeLaunch({ options }) {
   if (startWatch && buildLavaMoat) {
     throw usageError("runtime-launch accepts only one of --start-watch or --build-lavamoat.");
   }
-  const mode = buildLavaMoat ? "build-lavamoat" : startWatch ? "start-watch" : "existing-dist";
+  if (artifactRequested && (startWatch || buildLavaMoat || optionString(options, "remoteFlag"))) {
+    throw usageError("artifact launch cannot be combined with build, watch, or remote-flag options.");
+  }
+  let artifact;
+  if (artifactRequested) {
+    artifact = await acquireExtensionReleaseArtifact({
+      file: artifactFile,
+      expectedVersion: artifactVersion,
+      expectedSha256: artifactSha256,
+      cacheRoot: artifactCache
+    });
+  }
+  const mode = artifact ? "release-artifact" : buildLavaMoat ? "build-lavamoat" : startWatch ? "start-watch" : "existing-dist";
   const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
   const command = [
     "bash",
@@ -42,6 +109,15 @@ async function handleRuntimeLaunch({ options }) {
     "--artifacts-dir",
     artifactsDir
   ];
+  if (artifact) {
+    command.push(
+      "--external-artifact",
+      "--dist-dir",
+      artifact.extensionDir,
+      "--artifact-provenance",
+      artifact.provenancePath
+    );
+  }
   if (chromeUserDataDir) command.push("--chrome-user-data-dir", chromeUserDataDir);
   const remoteFlag = optionString(options, "remoteFlag");
   if (remoteFlag) command.push("--remote-flag", remoteFlag);
@@ -52,7 +128,7 @@ async function handleRuntimeLaunch({ options }) {
       cdpPort,
       artifactsDir,
       reason: "harness_live_script_missing",
-      fix: `Run mm-harness install --adapter extension --target ${shellQuote(target)}, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, mode)}`,
+      fix: `Run mm-harness install --adapter extension --target ${shellQuote(target)}, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, mode, artifactInvocation(options))}`,
       command
     });
     printRuntimeLaunchReport(report2, optionFlag(options, "json"));
@@ -61,7 +137,7 @@ async function handleRuntimeLaunch({ options }) {
   fs.mkdirSync(artifactsDir, { recursive: true });
   const jsonMode = optionFlag(options, "json");
   if (!jsonMode) {
-    const detail = mode === "build-lavamoat" ? "production-like LavaMoat build" : mode === "start-watch" ? "test webpack watcher" : "existing dist";
+    const detail = mode === "release-artifact" ? `release artifact ${artifact?.manifestVersion}` : mode === "build-lavamoat" ? "production-like LavaMoat build" : mode === "start-watch" ? "test webpack watcher" : "existing dist";
     console.error(`recipe: runtime-launch starting (cdp=${cdpPort}, ${detail})`);
   } else {
     console.error(JSON.stringify({
@@ -69,7 +145,7 @@ async function handleRuntimeLaunch({ options }) {
       type: "progress",
       command: "rebuild",
       phase: "runtime-launch",
-      message: mode === "build-lavamoat" ? "production-like LavaMoat build starting" : mode === "start-watch" ? "test webpack watcher starting" : "launching existing dist",
+      message: mode === "release-artifact" ? `release artifact ${artifact?.manifestVersion} launch starting` : mode === "build-lavamoat" ? "production-like LavaMoat build starting" : mode === "start-watch" ? "test webpack watcher starting" : "launching existing dist",
       cdpPort
     }));
   }
@@ -90,7 +166,8 @@ async function handleRuntimeLaunch({ options }) {
       summaryPath,
       reason: "runtime_ready",
       fix: "",
-      command
+      command,
+      artifact
     });
     printRuntimeLaunchReport(report2, optionFlag(options, "json"));
     return 0;
@@ -109,20 +186,111 @@ async function handleRuntimeLaunch({ options }) {
     launchLogPath: fs.existsSync(launchLogPath) ? launchLogPath : void 0,
     verifySummaryPath: fs.existsSync(verifySummaryPath) ? verifySummaryPath : void 0,
     reason,
-    fix: `Read ${failurePath}, fix the first error, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, mode)}`,
+    fix: `Read ${failurePath}, fix the first error, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, mode, artifactInvocation(options))}`,
     command,
+    artifact,
     exitCode: result.status ?? 1
   });
   printRuntimeLaunchReport(report, optionFlag(options, "json"));
   return 1;
 }
+async function handleAndroidArtifactLaunch(input) {
+  const {
+    options,
+    target,
+    artifactFile,
+    artifactVersion,
+    artifactSha256,
+    artifactBuildId,
+    artifactPackageId,
+    artifactCache
+  } = input;
+  const platform = optionString(options, "platform") ?? "android";
+  if (platform === "ios") {
+    throw usageError("Downloaded iOS artifact launch is unsupported. Next: use --platform android with a local APK.");
+  }
+  if (platform !== "android") throw usageError("--platform must be android for Mobile artifact launch.");
+  if (!artifactFile || !artifactVersion || !artifactSha256 || !artifactBuildId || !artifactPackageId) {
+    throw usageError(
+      "Android artifact launch requires --artifact-file, --artifact-version, --artifact-build-id, --artifact-package-id, and --artifact-sha256 together."
+    );
+  }
+  const deviceSerial = optionString(options, "device");
+  if (!deviceSerial) {
+    throw usageError("Android artifact launch requires --device <serial>. Next: run adb devices -l and rerun with one serial.");
+  }
+  if (artifactCache || optionString(options, "cdpPort") || optionString(options, "chromeUserDataDir") || optionString(options, "remoteFlag") || optionFlag(options, "startWatch") || optionFlag(options, "buildLavamoat")) {
+    throw usageError("Android artifact launch cannot be combined with Extension build, profile, cache, or CDP options.");
+  }
+  const artifactsDir = path.resolve(
+    optionString(options, "artifactsDir") ?? recipeHarnessPath(target, "mobile", "runtime-launch", (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/gu, ""))
+  );
+  fs.mkdirSync(artifactsDir, { recursive: true });
+  const summaryPath = path.join(artifactsDir, "summary.json");
+  try {
+    clearMobileReleaseArtifactState(target);
+    const artifact = await installAndroidReleaseArtifact({
+      file: artifactFile,
+      expectedVersion: artifactVersion,
+      expectedBuildId: artifactBuildId,
+      expectedSha256: artifactSha256,
+      packageId: artifactPackageId,
+      deviceSerial
+    });
+    const runtimeState = writeMobileReleaseArtifactState(target, artifact);
+    const report = runtimeLaunchReport("pass", {
+      adapter: "mobile",
+      platform,
+      target,
+      artifactsDir,
+      summaryPath,
+      reason: "runtime_ready",
+      fix: "",
+      artifact,
+      runtimeState
+    });
+    fs.writeFileSync(summaryPath, `${JSON.stringify(report, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    printRuntimeLaunchReport(report, optionFlag(options, "json"));
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const report = runtimeLaunchReport("fail", {
+      adapter: "mobile",
+      platform,
+      target,
+      artifactsDir,
+      summaryPath,
+      reason: "android_artifact_launch_failed",
+      error: message,
+      fix: `Fix the first error, then rerun with --device ${shellQuote(deviceSerial)} and the same verified artifact identity.`
+    });
+    fs.writeFileSync(summaryPath, `${JSON.stringify(report, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    printRuntimeLaunchReport(report, optionFlag(options, "json"));
+    return 1;
+  }
+}
 function runtimeLaunchLiveFlag(mode) {
-  return mode === "existing-dist" ? "--launch-existing-dist" : `--${mode}`;
+  return mode === "existing-dist" || mode === "release-artifact" ? "--launch-existing-dist" : `--${mode}`;
 }
-function runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, mode = "existing-dist") {
+function runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, mode = "existing-dist", artifact) {
   const base = `mm-harness runtime-launch --adapter extension --target ${shellQuote(target)} --cdp-port ${cdpPort}`;
-  const withMode = mode === "existing-dist" ? base : `${base} --${mode}`;
-  return chromeUserDataDir ? `${withMode} --chrome-user-data-dir ${shellQuote(chromeUserDataDir)}` : withMode;
+  let command = mode === "existing-dist" || mode === "release-artifact" ? base : `${base} --${mode}`;
+  if (artifact?.file) command += ` --artifact-file ${shellQuote(artifact.file)}`;
+  if (artifact?.version) command += ` --artifact-version ${shellQuote(artifact.version)}`;
+  if (artifact?.sha256) command += ` --artifact-sha256 ${shellQuote(artifact.sha256)}`;
+  if (artifact?.cache) command += ` --artifact-cache ${shellQuote(artifact.cache)}`;
+  return chromeUserDataDir ? `${command} --chrome-user-data-dir ${shellQuote(chromeUserDataDir)}` : command;
+}
+function artifactInvocation(options) {
+  const artifact = {
+    file: optionString(options, "artifactFile"),
+    version: optionString(options, "artifactVersion"),
+    sha256: optionString(options, "artifactSha256"),
+    cache: optionString(options, "artifactCache")
+  };
+  return Object.values(artifact).some(Boolean) ? artifact : void 0;
 }
 function runtimeLaunchReport(status, fields) {
   return {

package/dist/heal-bounds.js

@@ -86,7 +86,7 @@ function checkHealBounds(target, output, state) {
       originalError
     };
   }
-  const failureClass = classifyFailure(output);
+  const failureClass = classifyFailure(conciseFailureForHuman(output));
   if (failureClass === "screenshot-protected") {
     return {
       code: "SCREENSHOT_PROTECTED",

package/dist/live-adapter-contract.js

@@ -158,7 +158,9 @@ async function prepareLiveAdapterScript({
     target: `node${process.versions.node.split(".")[0]}`,
     legalComments: "none",
     sourcemap: false,
-    banner: { js: `process.argv[1] = ${JSON.stringify(entryReal)};` },
+    banner: {
+      js: `import { createRequire as __mmCreateRequire } from 'node:module';const require = __mmCreateRequire(import.meta.url);process.argv[1] = ${JSON.stringify(entryReal)};`
+    },
     plugins: [bindImportMetaUrls()],
     logLevel: "silent"
   });

package/dist/metamask-action-validation.js

@@ -1,7 +1,7 @@
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function validateMetaMaskActionInputs(recipe) {
+function validateMetaMaskActionInputs(recipe, adapter) {
   if (!isRecord(recipe) || !isRecord(recipe.workflow)) return [];
   const nodes = isRecord(recipe.workflow.nodes) ? recipe.workflow.nodes : void 0;
   if (!nodes) return [];
@@ -9,6 +9,52 @@ function validateMetaMaskActionInputs(recipe) {
   for (const [nodeId, node] of Object.entries(nodes)) {
     if (!isRecord(node)) continue;
     const action = node.action;
+    if (action === "metamask.perps.read_snapshot" && adapter === "extension") {
+      if (node.market !== void 0 && node.markets !== void 0) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.markets`,
+          message: `${action} accepts market or markets, not both`
+        });
+      }
+      if (isRecord(node.history)) {
+        const start = node.history.start_time_ms;
+        const end = node.history.end_time_ms;
+        if (typeof start === "number" && typeof end === "number" && start > end) {
+          findings.push({
+            severity: "error",
+            code: "recipe.invalid_param",
+            path: `workflow.nodes.${nodeId}.history.start_time_ms`,
+            message: `${action} history.start_time_ms must not exceed history.end_time_ms`
+          });
+        }
+        if (typeof node.history.limit === "number" && node.history.limit > 500) {
+          findings.push({
+            severity: "error",
+            code: "recipe.invalid_param",
+            path: `workflow.nodes.${nodeId}.history.limit`,
+            message: `${action} history.limit must not exceed 500`
+          });
+        }
+      }
+      if (typeof node.max_items_per_section === "number" && node.max_items_per_section > 500) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.max_items_per_section`,
+          message: `${action} max_items_per_section must not exceed 500`
+        });
+      }
+      if (typeof node.timeout_ms === "number" && node.timeout_ms > 6e4) {
+        findings.push({
+          severity: "error",
+          code: "recipe.invalid_param",
+          path: `workflow.nodes.${nodeId}.timeout_ms`,
+          message: `${action} timeout_ms must not exceed 60000`
+        });
+      }
+    }
     const state = typeof node.state === "string" ? node.state.toLowerCase() : void 0;
     const createsOrder = action === "metamask.perps.place_order" || (action === "metamask.perps.ensure_positions" || action === "metamask.perps.ensure_orders") && (state === "open" || state === "present");
     if (!createsOrder) continue;

package/dist/mm-harness-cli.js

@@ -199,6 +199,7 @@ Example:
   --list                             List actions accepted by call for this adapter; no <action> needed
   --arg k=v                          Action field value (repeatable; equivalent to key=value shorthand)
   --device <udid|serial|name>        Mobile only: target this device (sets IOS_SIMULATOR / ADB_SERIAL and updates agentic-runtime.json). Without it, >1 connected mobile device fails fast and lists them. Do not shut down other devices to force selection.
+  --cdp-port <port>                  Extension only: bind the action to this live browser runtime.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Where to write evidence (default: temp dir)
@@ -537,6 +538,36 @@ Example:
   mm-harness update
   mm-harness update --check --json`
   },
+  {
+    name: "runtime-launch",
+    summary: "Launch and verify an Extension runtime or local Android release artifact.",
+    example: "mm-harness runtime-launch --adapter extension --target <checkout> --cdp-port 9222 --artifact-file <zip> --artifact-version <X.Y.Z> --artifact-sha256 <digest>",
+    helpText: `mm-harness runtime-launch --adapter <extension|mobile> --target <checkout> [flags]
+
+  Verify and run an artifact already downloaded by the validation skill. The
+  harness performs no network acquisition. Extension ZIPs run through the
+  packaged browser/CDP path; Android APKs install to one explicitly named device.
+
+  --artifact-file <path>             Artifact downloaded by the validation skill
+  --artifact-version <X.Y.Z>         Expected manifest or Android version name
+  --artifact-build-id <id>           Android version code
+  --artifact-package-id <id>         Android application ID
+  --artifact-sha256 <digest>         Trusted SHA-256 from the acquisition step
+  --artifact-cache <dir>             Extension artifact cache root
+  --platform <android>               Mobile platform (downloaded iOS is unsupported)
+  --device <serial>                  Explicit Android device serial
+  --cdp-port <port>                  Extension CDP port
+  --chrome-user-data-dir <dir>       Isolated Chrome profile path
+  --artifacts-dir <dir>              Validation evidence directory
+  --start-watch                      Build through the checkout watcher
+  --build-lavamoat                   Build through the production-like path
+  --remote-flag <KEY=VARIANT>        Pin checkout snapshot flags (not allowed for artifacts)
+  --json                             Machine-readable terminal report
+
+Example:
+  mm-harness runtime-launch --adapter extension --target /path/to/checkout --cdp-port 9222 --artifact-file /path/to/metamask-chrome-X.Y.Z.zip --artifact-version X.Y.Z --artifact-sha256 <digest>
+  mm-harness runtime-launch --adapter mobile --platform android --target /path/to/checkout --device <serial> --artifact-file /path/to/app.apk --artifact-version X.Y.Z --artifact-build-id <code> --artifact-package-id io.metamask --artifact-sha256 <digest>`
+  },
   {
     name: "fixtures",
     summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / reset / generate / finalize.",
@@ -745,7 +776,6 @@ const HIDDEN = [
   "completion-candidates",
   "runtime-health",
   "runtime-decision",
-  "runtime-launch",
   "resolve-extension",
   "ensure-ready",
   "self-test"

package/dist/recipe-security.js

@@ -3,10 +3,19 @@ import { lstat, readFile, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "ui.locators",
+  "ui.activate_and_observe",
   "metamask.wallet.fixture_status",
   "metamask.wallet.validate_import",
   "metamask.wallet.list_accounts",
   "metamask.wallet.read_state",
+  "metamask.assets.read_visible_state",
+  "metamask.assets.read_details",
+  "metamask.networks.read_visible_state",
+  "metamask.perps.read_visible_state",
+  "metamask.perps.compare_provider_market",
+  "metamask.perps.read_eligibility",
+  "metamask.perps.read_funds_confirmation",
+  "metamask.swap_bridge.read_visible_state",
   "metamask.perps.read_positions",
   "metamask.perps.read_orders",
   "metamask.perps.read_account",
@@ -19,15 +28,37 @@ const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.analytics.assert_events"
 ]);
 const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
+  "ui.activate_and_observe",
+  "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.add_custom",
+  "metamask.networks.add_chainlist",
+  "metamask.networks.remove_custom",
   "metamask.wallet.setup",
   "metamask.wallet.import",
   "metamask.wallet.reset",
   "metamask.wallet.ensure_unlocked",
   "metamask.wallet.select_account",
+  "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.deeplink.open",
   "metamask.perps.close_positions",
   "metamask.perps.close_orders",
   "metamask.perps.place_order",
+  "metamask.perps.close_visible_position",
+  "metamask.perps.open_position_action",
+  "metamask.perps.edit_margin",
   "metamask.perps.edit_order",
   "metamask.perps.update_position_tpsl",
   "metamask.perps.ensure_positions",
@@ -35,15 +66,24 @@ const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.clear_performance_caches",
   "metamask.perps.measure_homepage_visible",
   "metamask.perps.prepare_local_snapshot_endpoint",
+  "metamask.perps.set_market_favorite",
+  "metamask.perps.select_activity_filter",
+  "metamask.perps.select_market_filter",
+  "metamask.perps.open_balance_action",
   "metamask.perps.start_state",
   "metamask.perps.teardown_state",
   // Consent changes wallet state and is therefore an app mutation.
   "metamask.analytics.set_consent"
 ]);
 const EXTERNAL_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
+  "ui.activate_and_observe",
+  "metamask.assets.finish_send",
+  "metamask.swap_bridge.submit_transaction",
   "metamask.perps.close_positions",
   "metamask.perps.close_orders",
   "metamask.perps.place_order",
+  "metamask.perps.close_visible_position",
+  "metamask.perps.edit_margin",
   "metamask.perps.edit_order",
   "metamask.perps.update_position_tpsl",
   "metamask.perps.ensure_positions",

package/dist/run-diagnostics.js

@@ -32,7 +32,7 @@ function formatRunDiagnosticsForHuman(diagnostics, adapter) {
 async function beginRunDiagnostics(adapter, projectRoot) {
   const source = getAdapterSurface(adapter).appLogSource(projectRoot);
   if (!source) return null;
-  const mobileIssueBuffer = adapter === "mobile" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
+  const mobileIssueBuffer = adapter === "mobile" && process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME !== "1" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
   if (adapter === "extension") {
     await ensureExtensionConsoleCapture(projectRoot).catch(() => void 0);
   }

package/dist/runner.js

@@ -246,6 +246,9 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
   return lifecycle.map((entry) => ({
     ...entry,
     async execute(node, context) {
+      if (context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") {
+        return entry.execute(node, context);
+      }
       const command = node.command ?? node.event ?? node.state;
       const reloadsSource = command === "launch" || command === "foreground" || command === "restart";
       const checksIosContinuity = command === "foreground" && !isAndroidLifecycle(node, context.env ?? {});

package/docs/RELEASE-QA-CAPABILITY-MAP.md

@@ -0,0 +1,125 @@
+# Release QA capability map
+
+This document maps the current mm-harness release-validation surface to the
+MetaMask Extension QA checklists at commit
+[`77591c5`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/tree/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension).
+It describes reusable capabilities, not a release verdict. A release verdict
+must come from the case inventory, terminal traces, and completion gate for that
+specific artifact.
+
+The referenced plans contain 135 cases:
+
+- Perps: [64 cases](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/perps-rc/perps-rc-regression.md)
+- Assets: [22 cases](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/assets-rc-regression.md)
+- Swap and Bridge: [39 cases](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/swap-bridge-rc/swap-bridge-rc-regression.md)
+- Networks: [10 cases](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/networks-regression-rc/networks-regression-rc.md)
+
+## Artifact boundary
+
+Artifact discovery and download belong to the release-validation workflow. The
+workflow supplies mm-harness with a local artifact, expected product identity,
+and trusted SHA-256. mm-harness never discovers or downloads a release.
+
+For Extension, `runtime-launch` verifies the ZIP digest and manifest version,
+extracts it safely, records archive and tree provenance, copies the exact tree
+to an isolated runtime directory, resets only the selected Chrome profile, and
+launches without building or patching the checkout.
+
+For Android, `runtime-launch` requires one physical-device serial, verifies the
+local APK digest, package ID, version name, and version code, installs it, and
+binds subsequent recipes to the installed APK digest and selected device. The
+release path does not use Metro, a development bridge, or the HUD.
+
+```sh
+mm-harness runtime-launch \
+  --adapter extension \
+  --target /path/to/metamask-extension \
+  --cdp-port 9222 \
+  --artifact-file /path/to/metamask-chrome-X.Y.Z.zip \
+  --artifact-version X.Y.Z \
+  --artifact-sha256 <trusted-digest>
+
+mm-harness runtime-launch \
+  --adapter mobile \
+  --platform android \
+  --target /path/to/metamask-mobile \
+  --device <physical-device-serial> \
+  --artifact-file /path/to/app.apk \
+  --artifact-version X.Y.Z \
+  --artifact-build-id <version-code> \
+  --artifact-package-id io.metamask \
+  --artifact-sha256 <trusted-digest>
+```
+
+## Completion gate
+
+[`scripts/validate-release-report.mjs`](../scripts/validate-release-report.mjs)
+compares a canonical case inventory with terminal verdicts. It rejects missing
+or unknown IDs, duplicate IDs, non-terminal statuses, absent evidence, evidence
+outside the declared root, incomplete run directories, and any non-empty
+`remainingCases`. A passing gate writes `metadata.json`,
+`report-quality.json`, and `report.md`.
+
+Supported verdicts are `PASS`, `FAIL`, `BLOCKED_FUNDS`, `BLOCKED_COST`, and
+`BLOCKED_ENVIRONMENT`. Product failures must remain failures; infrastructure,
+funding, and cost limits must not be reported as passes.
+
+## Capability matrix
+
+`AVAILABLE` means a typed action or bundled recipe covers the reusable
+operation and produces machine-readable evidence. `PARTIAL` means the generic
+operation exists but the complete checklist family still depends on task-local
+composition, live funds, or deterministic external state. `MISSING` means the
+current manifests do not expose the required durable capability.
+
+### Perps
+
+| Case family | Required state and behavior | Current capability | Status |
+| --- | --- | --- | --- |
+| Navigation, home, markets, and details | Eligible account, live catalog, market summaries, chart, statistics, and route recovery | Visible-state reads, market navigation/search/filter, provider comparison, eligibility reads, and market-detail recipes | **AVAILABLE** for visible live flows |
+| Watchlist and activity | Existing favorites and typed activity rows | Favorite mutation, activity-filter selection, and release recipes | **AVAILABLE** |
+| Order entry | Funded Perps balance, market/limit inputs, validation, preview, fill, and duplicate protection | Parameterized order placement plus visible order-entry and validation recipes | **PARTIAL**: live state and provider outcomes remain release-dependent |
+| Position management | Open position, close, margin, and TP/SL changes | Visible position actions, close, edit-margin, and TP/SL actions | **PARTIAL**: exact outcome depends on live account state |
+| Deposit and withdrawal | Wallet funds, Perps balance, confirmations, and resulting activity | Balance actions and confirmation reads with a funds-flow recipe | **PARTIAL**: funds and provider availability are external |
+| Snapshot assertions | Positions, orders, markets, history, and watchlist | Bounded redacted snapshot when the background hook exists; visible-state reads on untouched releases | **AVAILABLE** with runtime-specific observation paths |
+| Deterministic seeded provider state | Balance, positions, limit orders, TP/SL, history, and controlled REST/stream behavior | Existing setup fixtures do not reproduce the complete QA provider model inside an untouched release artifact | **MISSING** |
+
+### Assets
+
+| Case family | Required state and behavior | Current capability | Status |
+| --- | --- | --- | --- |
+| Token list, prices, details, and sorting | Funded account with known holdings and price data | Visible token-list/details reads, network scope, sorting assertions, and bundled recipes | **AVAILABLE** for EVM token UI |
+| Token search/import/hide/persistence | Known contracts and a persistent profile | Custom-token import, visibility changes, restart-safe recipes, and custom-network composition | **AVAILABLE** for Extension EVM tokens |
+| Native/token send and gas | Funded owned accounts and live gas | Prepare, review, custom-gas, finish, and Max/cancel/send recipes | **PARTIAL**: terminal submission is gated by funds and cost policy |
+| Aggregate Android holdings | Imported wallet with multi-chain assets | Native-accessibility token-list read on an untouched physical-device release | **AVAILABLE** |
+| Balance streaming and aggregation arithmetic | Triggered inbound update and expected cross-network totals | Visible snapshots exist; deterministic inbound trigger and tolerance assertions are not bundled | **PARTIAL** |
+| NFTs, DeFi, Solana send, and Bitcoin details | Indexed owned positions/assets and chain-specific transaction flows | Generic visible UI only | **MISSING** |
+
+### Swap and Bridge
+
+| Case family | Required state and behavior | Current capability | Status |
+| --- | --- | --- | --- |
+| Surface, asset, network, and amount selection | Supported source/destination pair | Exact asset/network selection, amount/Max input, and visible-state reads on Extension; exact native selection and amount input on Android | **AVAILABLE** |
+| Quote and slippage | Live quote services and supported route | Surface, quote, Max-quote, and custom-slippage recipes | **AVAILABLE** |
+| Submit and confirmation | Sufficient source balance and gas | Typed submit action with explicit confirmation policy | **PARTIAL**: live funds and cost policy decide whether submission is allowed |
+| Sequential multi-network journey | Balances delivered by preceding swaps and bridges | Individual steps are composable, but the complete live-funds journey remains task-local and resumable by its case inventory | **PARTIAL** |
+| Activity, balance deltas, and completed bridge tracking | Confirmed transactions and indexed activity | Visible-state evidence exists; reusable terminal activity and arithmetic assertions are incomplete | **PARTIAL** |
+
+### Networks
+
+| Case family | Required state and behavior | Current capability | Status |
+| --- | --- | --- | --- |
+| Add, select, and remove custom networks | Known RPC configuration and chain identity | Typed custom-network and Chainlist add, visible-state read, select, and remove actions | **AVAILABLE** on Extension |
+| Custom-network tokens and persistence | Known token contract and persistent profile | Network actions compose with Assets import/visibility/persistence recipes | **AVAILABLE** on Extension |
+| Balance stability and fiat visibility | Funded custom network and live price APIs | Visible-state reads and a bounded balance-stability recipe | **PARTIAL**: external price availability remains uncontrolled |
+| Send Max and activity | Funded custom network and recipient | Assets send actions cover the transaction path | **PARTIAL**: exact activity and balance-delta assertions remain task-local |
+| Bridge tracking and details | Completed supported bridge route | Swap/Bridge composition exists; reusable terminal tracking assertions are incomplete | **PARTIAL** |
+| Android multi-network visibility | Imported wallet with holdings on multiple chains | Native Assets read reports aggregate visible holdings without Metro or a development bridge | **AVAILABLE** |
+
+## Platform scope
+
+The 135-case source inventory targets Extension. It must not be relabeled as an
+Android checklist. Android release validation uses a separate case inventory
+for the product behaviors exercised on a physical device, while reusing the
+same action vocabulary and report gate where the clients expose equivalent
+flows. Simulator-only evidence is not accepted for Android release claims.