@deeeed/metamask-harness 0.35.0 → 0.37.0

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(),
@@ -270,7 +286,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--extension-id-file": value(),
       "--action-manifest": value()
     }),
-    positionals: [{ label: "action", choices: ["init", "sync", "set", "generate", "finalize"] }],
+    positionals: [{ label: "action", choices: ["init", "sync", "set", "reset", "generate", "finalize"] }],
     minimumPositionals: 0
   }
 };

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;

package/dist/commands/device-target.js

@@ -256,6 +256,11 @@ ${formatConnectedDevices(connected)}
       userAction: deviceRecovery(options, opts.rerun)
     };
   }
+  if (targetable.length === 1) {
+    const selected = targetable[0];
+    if (selected.platform === "android") setAndroidDeviceEnv(selected.id, selected.name);
+    else setIosDeviceEnv(selected.id, selected.name);
+  }
   return { ok: true };
 }
 function scopedDevices(devices, allDevices = false) {

package/dist/commands/fixtures.js

@@ -48,7 +48,7 @@ function fixturesStatus(options) {
   const fixture = { ...summary, path: canonical };
   const ready = summary.status === "ready";
   const nextCommand = ready ? "mm-harness fixtures set" : "mm-harness fixtures init --from <path>   # or: mm-harness fixtures init --dev";
-  const operations = adapter === "extension" ? ["init", "sync", "set", "generate", "finalize"] : ["init", "sync", "set"];
+  const operations = adapter === "extension" ? ["init", "sync", "set", "reset", "generate", "finalize"] : adapter === "mobile" ? ["init", "sync", "set", "reset"] : ["init", "sync", "set"];
   if (json) {
     console.log(JSON.stringify({
       schemaVersion: 1,
@@ -103,8 +103,8 @@ async function handleFixturesLocked(argv) {
   const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
   const sub = positional[0];
-  if (sub !== "init" && sub !== "sync" && sub !== "set" && sub !== "generate" && sub !== "finalize") {
-    return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <init|sync|set|generate|finalize>", "mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
+  if (sub !== "init" && sub !== "sync" && sub !== "set" && sub !== "reset" && sub !== "generate" && sub !== "finalize") {
+    return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <init|sync|set|reset|generate|finalize>", "mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
   }
   if (sub !== "init" && (flag(options, "dev") || flag(options, "force") || str(options, "from"))) {
     return usageOut(
@@ -121,7 +121,7 @@ async function handleFixturesLocked(argv) {
   }
   const surface = getAdapterSurface(adapter);
   surface.resolveSlotPorts(target);
-  const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: false, rerun: "" });
+  const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: sub === "reset", rerun: "" });
   if ("code" in dtResult) {
     return usageOut(json, "fixtures", dtResult.message, dtResult.userAction);
   }
@@ -129,6 +129,9 @@ async function handleFixturesLocked(argv) {
   if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);
   const canonicalFixture = walletFixturePath(target);
   if (sub === "init") return fixturesInit(adapter, target, options, json);
+  if (sub === "reset" && surface.headless) {
+    return usageOut(json, "fixtures", "fixtures reset requires a Mobile or Extension client.", "use fixtures set for the core adapter");
+  }
   if (surface.headless && sub === "set") {
     const fixture = fixtureSummary(target, adapter);
     if (fixture.status !== "ready") {
@@ -139,7 +142,7 @@ async function handleFixturesLocked(argv) {
     else console.error(message);
     return EXIT.ok;
   }
-  const retryHint = `${surface.hints.relaunch}   # relaunch, then retry: mm-harness fixtures set`;
+  const retryHint = `${surface.hints.relaunch}   # relaunch, then retry: mm-harness fixtures ${sub}`;
   if (sub === "sync") {
     const exitCode = fixturesSync(adapter, target, json);
     if (json) {
@@ -162,34 +165,105 @@ async function handleFixturesLocked(argv) {
       "mm-harness fixtures init --dev && mm-harness fixtures set"
     );
   }
+  if (sub === "reset") {
+    const selectedFixture = fixtureFileSummary(fixturePath, adapter, fixturePath);
+    if (selectedFixture.status !== "ready") {
+      return usageOut(
+        json,
+        "fixtures",
+        `wallet fixture is ${String(selectedFixture.status)} at ${fixturePath}; reset was not started.`,
+        `mm-harness fixtures init --from <path> --target ${target}`
+      );
+    }
+  }
   if (adapter === "extension") {
-    return applyExtensionFixture(target, fixturePath, canonicalFixture, json);
+    return applyExtensionFixture(target, fixturePath, canonicalFixture, json, sub);
   }
-  process.stderr.write(`\u2192 fixtures set ${adapter} \u2014 connecting bridge + applying wallet fixture (can take ~30s)\u2026
+  const reset = sub === "reset";
+  process.stderr.write(`\u2192 fixtures ${sub} ${adapter} \u2014 ${reset ? "resetting selected app data, relaunching, then applying" : "connecting bridge + applying"} wallet fixture (can take ~30s)\u2026
 `);
   let status;
   let mobileSetupResult;
+  let resetError;
   if (adapter === "mobile") {
     const setupWalletSh = path.join(runnerDir, "adapters/mobile/bridge-runtime/setup-wallet.sh");
     const previousAppRoot = process.env.APP_ROOT;
     process.env.APP_ROOT = target;
     try {
+      if (reset) {
+        const platform = process.env.PLATFORM === "android" || process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
+        const port = process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "8081";
+        const resetAppData = path.join(runnerDir, "adapters/mobile/reset-app-data.sh");
+        const resetArgs = ["--platform", platform, "--target", target];
+        if (platform === "ios") {
+          resetArgs.push("--simulator", process.env.SIM_UDID || process.env.IOS_SIMULATOR || "booted");
+        } else if (process.env.ADB_SERIAL || process.env.ANDROID_SERIAL) {
+          resetArgs.push("--adb-serial", process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || "");
+        }
+        const resetResult = await spawnScriptStreaming(resetAppData, resetArgs, target, {
+          timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+        });
+        if (resetResult.status !== 0) {
+          resetError = new Error("Mobile app data reset failed.");
+        } else {
+          const prewarmBundle = path.join(runnerDir, "adapters/mobile/prewarm-bundle.sh");
+          const prewarmResult = await spawnScriptStreaming(
+            prewarmBundle,
+            ["--platform", platform, "--target", target, "--port", port],
+            target,
+            {
+              timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+            }
+          );
+          if (prewarmResult.status !== 0) {
+            resetError = new Error("Mobile bundle prewarm failed after app data reset.");
+          }
+        }
+        if (!resetError) {
+          const openDevice = path.join(runnerDir, "adapters/mobile/open-device.sh");
+          const openArgs = ["--platform", platform, "--target", target, "--port", port, "--preflight-mode", "fast", "--restart"];
+          if (platform === "ios") {
+            openArgs.push("--simulator", process.env.SIM_UDID || process.env.IOS_SIMULATOR || "booted");
+          } else if (process.env.ADB_SERIAL || process.env.ANDROID_SERIAL) {
+            openArgs.push("--adb-serial", process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || "");
+          }
+          const openResult = await spawnScriptStreaming(openDevice, openArgs, target, {
+            timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+          });
+          if (openResult.status !== 0) {
+            resetError = new Error("Mobile app relaunch after data reset failed.");
+          } else {
+            const waitForBridge = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
+            const waitResult = await spawnScriptStreaming(
+              waitForBridge,
+              ["--target", target, "--port", port, "--platform", platform],
+              target,
+              { timeoutMs: FIXTURE_STREAM_TIMEOUT_MS }
+            );
+            if (waitResult.status !== 0) {
+              resetError = new Error("Mobile bridge did not return after app data reset.");
+            }
+          }
+        }
+      }
       const configuredTimeout = Number(process.env.MM_HARNESS_FIXTURES_SET_TIMEOUT_MS ?? FIXTURE_STREAM_TIMEOUT_MS);
       const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : FIXTURE_STREAM_TIMEOUT_MS;
-      mobileSetupResult = await spawnScriptStreaming(
-        setupWalletSh,
-        ["--fixture", fixturePath],
-        target,
-        {
-          env: {
-            APP_ROOT: target,
-            WATCHER_PORT: process.env.WATCHER_PORT ?? "8081",
-            METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? "8081"
-          },
-          timeoutMs
-        }
-      );
-      status = mobileSetupResult.status === 0 ? "pass" : "fail";
+      if (!resetError) {
+        mobileSetupResult = await spawnScriptStreaming(
+          setupWalletSh,
+          ["--fixture", fixturePath],
+          target,
+          {
+            env: {
+              APP_ROOT: target,
+              WATCHER_PORT: process.env.WATCHER_PORT ?? "8081",
+              METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? "8081"
+            },
+            timeoutMs
+          }
+        );
+      }
+      status = !resetError && mobileSetupResult?.status === 0 ? "pass" : "fail";
     } finally {
       if (previousAppRoot === void 0) delete process.env.APP_ROOT;
       else process.env.APP_ROOT = previousAppRoot;
@@ -205,16 +279,17 @@ async function handleFixturesLocked(argv) {
         {
           schemaVersion: 1,
           command: "fixtures",
-          action: "set",
+          action: sub,
           adapter,
           fixture: fixturePath,
           canonicalFixture,
           status,
           exitCode: status === "pass" ? EXIT.ok : EXIT.runtime,
+          walletReset: reset && status === "pass",
           message: teaching,
           error: status === "fail" ? {
-            code: mobileSetupResult?.timedOut ? "SETUP_WALLET_TIMEOUT" : "SETUP_WALLET_FAILED",
-            message: mobileSetupResult?.timedOut ? `wallet fixture setup exceeded its ${String(mobileSetupResult.timeoutMs)}ms bound on Metro port ${process.env.WATCHER_PORT ?? "8081"}` : `wallet fixture setup failed on ${process.env.WATCHER_PORT ?? "8081"}`,
+            code: resetError ? "MOBILE_WALLET_RESET_FAILED" : mobileSetupResult?.timedOut ? "SETUP_WALLET_TIMEOUT" : "SETUP_WALLET_FAILED",
+            message: resetError ? `wallet reset failed: ${resetError instanceof Error ? resetError.message : String(resetError)}` : mobileSetupResult?.timedOut ? `wallet fixture setup exceeded its ${String(mobileSetupResult.timeoutMs)}ms bound on Metro port ${process.env.WATCHER_PORT ?? "8081"}` : `wallet fixture setup failed on ${process.env.WATCHER_PORT ?? "8081"}`,
             userAction: retryHint
           } : null
         },
@@ -227,7 +302,7 @@ async function handleFixturesLocked(argv) {
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;
 }
-async function applyExtensionFixture(target, fixturePath, canonicalFixture, json) {
+async function applyExtensionFixture(target, fixturePath, canonicalFixture, json, action) {
   const distManifest = path.join(target, "dist/chrome/manifest.json");
   const userAction = `mm-harness launch --build --verify --target ${JSON.stringify(target)}`;
   if (!fs.existsSync(distManifest)) {
@@ -236,7 +311,7 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
       console.log(JSON.stringify({
         schemaVersion: 1,
         command: "fixtures",
-        action: "set",
+        action,
         adapter: "extension",
         fixture: fixturePath,
         canonicalFixture,
@@ -245,15 +320,15 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
         error: { code: "EXTENSION_FIXTURE_BUILD_REQUIRED", message: message2, userAction }
       }, null, 2));
     } else {
-      console.error(`\u2717 mm-harness fixtures set: ${message2}
+      console.error(`\u2717 mm-harness fixtures ${action}: ${message2}
   Next: ${userAction}`);
     }
     return EXIT.runtime;
   }
-  process.stderr.write(`${colorHumanMessage("\u2192 fixtures set extension \u2014 resetting and seeding the slot-owned profile from the existing build\u2026")}
+  process.stderr.write(`${colorHumanMessage(`\u2192 fixtures ${action} extension \u2014 resetting and seeding the slot-owned profile from the existing build\u2026`)}
 `);
   const liveScript = path.join(runnerDir, "adapters/extension/live.sh");
-  const args = ["--target", target, "--launch-existing-dist"];
+  const args = ["--target", target, "--launch-existing-dist", "--launch-only"];
   if (process.env.CDP_PORT) args.push("--cdp-port", process.env.CDP_PORT);
   const result = await spawnScriptStreaming(liveScript, args, target, {
     env: { RECIPE_WALLET_FIXTURE: fixturePath },
@@ -266,7 +341,7 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
     console.log(JSON.stringify({
       schemaVersion: 1,
       command: "fixtures",
-      action: "set",
+      action,
       adapter: "extension",
       fixture: fixturePath,
       canonicalFixture,
@@ -279,7 +354,7 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
   } else if (status === "pass") {
     console.error(message);
   } else {
-    console.error(`\u2717 mm-harness fixtures set: ${message}
+    console.error(`\u2717 mm-harness fixtures ${action}: ${message}
   Next: ${userAction}`);
   }
   return exitCode;

package/dist/commands/launch/extension.js

@@ -15,11 +15,20 @@ import {
   runnerDir
 } from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
-import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
-import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
+import {
+  EXTENSION_PRODUCT_CONFIG_FINGERPRINT_FILENAME,
+  extensionCompiledScriptsMatchProductConfig,
+  extensionProductConfigBlock,
+  extensionProductConfigFingerprint
+} from "../../adapters/extension/product-config.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 { stopExtensionWatcher } from "../../adapters/slot-ports.js";
+import { isExtensionWatcherLive, stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { EXIT, spawnScriptStreaming } from "../shared.js";
 const { CdpSession } = await importRecipeHarnessRuntimeCdp();
 const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = createRequire(import.meta.url)(
@@ -50,7 +59,18 @@ async function launchExtension(target, tier, wantWatch, displayMode = "fullscree
   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);
+  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) {
@@ -75,12 +95,23 @@ Next: ${block.userAction}`
   if (reusable) {
     return extensionReattach(target, displayMode);
   }
-  return extensionRebuild(target);
+  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;
+  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);
@@ -325,6 +356,59 @@ async function extensionReattach(target, displayMode = "fullscreen") {
   console.error(colorHumanMessage(`\u2192 extension quick reattach \u2014 reload in place \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no rebuild, no relaunch)`));
   return spawnScriptStreaming(reattachScript, reattachArgs, target);
 }
+async function extensionLaunchDevelopment(target) {
+  const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
+  const liveArgs = ["--target", target];
+  const existingBuild = isExtensionWatcherLive(target) && harnessWatcherMatchesProductConfig(target) && extensionCompiledScriptsMatchProductConfig(target, path.join(target, "dist/chrome")) && fs.existsSync(path.join(target, "dist/chrome/manifest.json")) && !isExtensionDistStale(target);
+  liveArgs.push(existingBuild ? "--launch-existing-dist" : "--start-watch");
+  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(
+    existingBuild ? `\u2192 extension quick launch \u2014 existing yarn start build \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)` : `\u2192 extension quick launch \u2014 yarn start development build \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`
+  ));
+  return spawnScriptStreaming(liveScript, liveArgs, target);
+}
+async function extensionLaunchReleaseArtifact(target, artifact) {
+  if (!artifact.sourceDir || !artifact.provenancePath) {
+    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"
+  ];
+  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");
+  if (!fs.existsSync(harnessPidFile)) return true;
+  const expected = extensionProductConfigFingerprint(target);
+  if (!expected) return true;
+  try {
+    const actual = fs.readFileSync(
+      path.join(runtimeDir, EXTENSION_PRODUCT_CONFIG_FINGERPRINT_FILENAME),
+      "utf8"
+    ).trim();
+    return actual === expected;
+  } catch {
+    return false;
+  }
+}
 async function extensionRebuild(target) {
   const runtimeDirRel = recipeRuntimeDir();
   const runtimeAbs = path.join(target, runtimeDirRel);
@@ -348,6 +432,7 @@ async function extensionRebuild(target) {
 }
 export {
   extensionDepsBlock,
+  extensionLaunchDevelopment,
   extensionReattach,
   extensionRebuild,
   extensionRuntimeReusable,

package/dist/commands/launch/index.js

@@ -259,6 +259,16 @@ async function handleLaunchLocked(argv, stream) {
       exitCode: EXIT.infra
     });
   }
+  if (adapter === "extension" && extensionEvmRpcUnreachable(attempt.output)) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "EVM_RPC_UNREACHABLE",
+      message: "EVM RPC readiness failed; Infura configured does not mean RPC reachable.",
+      recoverable: false,
+      userAction: `Check the effective INFURA_PROJECT_ID from the environment, .metamaskprodrc, or ${shellQuote(path.join(target, ".metamaskrc"))}, then rerun: mm-harness launch --verify --target ${shellQuote(target)}`,
+      exitCode: EXIT.runtime,
+      originalError: attempt.output.trim() || void 0
+    });
+  }
   if (heal === "off") {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "LAUNCH_FAILED",
@@ -374,6 +384,9 @@ function extensionBrowserMissing(output) {
 function extensionProductConfigMissing(output) {
   return /EXTENSION_PRODUCT_CONFIG_REQUIRED:/u.test(output);
 }
+function extensionEvmRpcUnreachable(output) {
+  return /EVM_RPC_UNREACHABLE|EVM RPC readiness probe failed|Infura configured ≠ RPC reachable/u.test(output);
+}
 function mobileProvisioningBlocked(output) {
   return /open-device: configured iOS simulator '.+' does not exist|open-device: no MetaMask bundle found|fast mode requires an installed (?:iOS dev client|Android dev client)/u.test(output);
 }

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,