@deeeed/metamask-harness 0.35.0 → 0.37.0

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))}`;
@@ -1142,10 +1200,35 @@ const RUN_RECOVERY_CODE = {
 async function recoverRunInfra(adapter, target, json) {
   getAdapterSurface(adapter).resolveSlotPorts(target);
   if (adapter === "extension") {
+    const { releaseArtifactState } = await import("../adapters/extension/runtime-decision.js");
+    const artifact = releaseArtifactState(target);
+    if (artifact.status !== "none") {
+      return {
+        status: 1,
+        output: "Release artifact recovery cannot switch to a checkout build.\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);
@@ -1251,6 +1334,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({

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)
@@ -452,7 +453,7 @@ Example:
   Extension quick launch REUSES a healthy live runtime (reload in place, no rebuild);
   --build is the escape hatch that always clean-builds + relaunches a fresh runtime.
 
-  --build                            Full clean build + relaunch (escape hatch; skips extension reuse)
+  --build                            Full production-like build + relaunch (escape hatch; skips extension reuse)
   --clear-metro                      Mobile only: clear Metro's transform cache before launch
   --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
   --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
@@ -537,11 +538,41 @@ 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 / generate / finalize.",
+    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / reset / generate / finalize.",
     example: "mm-harness fixtures set",
-    helpText: `mm-harness fixtures [<init|sync|set|generate|finalize>] [flags]
+    helpText: `mm-harness fixtures [<init|sync|set|reset|generate|finalize>] [flags]
 
   Manage the ONE canonical wallet fixture per checkout \u2014 wallet DATA only.
   With no action, show the current fixture status and safe next command.
@@ -550,6 +581,8 @@ Example:
   sync       Refresh the wallet fixture files on the target.
   set        Apply the canonical fixture (SRP/password/accounts); the password is
              read FROM the fixture, never typed.
+  reset      Delete the current Mobile/Extension wallet, then apply and validate
+             the canonical fixture from a clean state.
   generate   Render the extension fixture-state.json from a wallet fixture, for
              pre-launch profile prefill (extension-only). Requires --fixture and --out.
   finalize   Seed account labels/selection into the LIVE extension over CDP and
@@ -578,6 +611,7 @@ Example:
   mm-harness fixtures init --dev
   mm-harness fixtures sync
   mm-harness fixtures set
+  mm-harness fixtures reset
   mm-harness fixtures generate --fixture wallet-fixture.json --out fixture-state.json
   mm-harness fixtures finalize --fixture wallet-fixture.json --state fixture-state.json --cdp-port 6661 --extension-dir dist/chrome`
   }
@@ -742,7 +776,6 @@ const HIDDEN = [
   "completion-candidates",
   "runtime-health",
   "runtime-decision",
-  "runtime-launch",
   "resolve-extension",
   "ensure-ready",
   "self-test"

package/dist/recipe-security.js

@@ -4,6 +4,7 @@ import path from "node:path";
 const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "ui.locators",
   "metamask.wallet.fixture_status",
+  "metamask.wallet.validate_import",
   "metamask.wallet.list_accounts",
   "metamask.wallet.read_state",
   "metamask.perps.read_positions",
@@ -19,6 +20,8 @@ const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
 ]);
 const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
+  "metamask.wallet.import",
+  "metamask.wallet.reset",
   "metamask.wallet.ensure_unlocked",
   "metamask.wallet.select_account",
   "metamask.deeplink.open",