@deeeed/metamask-harness 0.37.0 → 0.38.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+## 0.38.1 - 2026-08-14
+
+### Fixed
+
+- Read release evidence through verified regular-file descriptors, escape generated Markdown safely, and keep UI waits out of dynamically constructed page expressions.
+
+## 0.38.0 - 2026-08-14
+
+### Added
+
+- Add visible Perps release actions and recipes for market details, search, filters, watchlists, order entry, position management, funds confirmations, and activity on untouched Extension builds, plus native Android market-state evidence without a development bridge.
+- Add shared Assets release actions and recipes for token lists, details, sorting, import, visibility, persistence, send review, custom gas, and network scope on Extension, plus native Android holdings evidence.
+- Add shared Swap and Bridge actions and recipes for exact asset selection, quote amounts, Max, slippage, and guarded submission on Extension, with native Android selection and quote evidence.
+- Add Extension custom-network lifecycle and visible-state actions plus bounded balance-stability validation, and native Android multi-network holdings evidence.
+- Add a canonical release-report gate that rejects missing case IDs, incomplete evidence, non-terminal verdicts, and unfinished case inventories before writing report metadata and quality output.
+
+### Fixed
+
+- Recover Runway provisioning from an unresponsive iOS simulator by restarting the selected device once, waiting for a confirmed boot, and retrying the bounded installed-app probe.
+- Consume Protocol 0.21.0, Recipe Harness 0.15.0, Agent Runtime 0.8.1, and Expo Recipe 0.8.1 as one compatible QA runtime set.
+- Stop every Chrome process using an Extension validation profile before replacing its runtime snapshot, preventing stale pages from loading chunks from a different build.
+- Prefer an unlocked Extension Home page over stale onboarding and Side Panel pages when multiple CDP targets remain open.
+- Fixed opaque Android navigation completing the same native session twice after reaching its destination.
+- Keep Android release actions on one device-and-app-scoped accessibility session so sequential recipe nodes do not conflict over stale leases.
+- Navigate Android Swap through semantic accessibility identifiers, dismiss the keyboard before selecting exact chain-qualified assets, and scroll the token list until the requested row is visible.
+- Unlock an opaque Android release with the wallet password instead of entering biometric authentication, and omit Metro launch data from native release lifecycle actions.
+- Bind send and limit-order evidence to the newly submitted operation, reject selectors that native UI cannot disambiguate, and fail when Perps navigation or partial TP/SL reconciliation is not proven.
+- Classify live Swap submission as an external mutation, reject ID-less release-report cases, and probe competing Extension tabs before selecting the runtime health target.
+- Require explicit approval for live Perps submissions and reject release evidence that escapes its declared root or lacks regular trace leaves.
+- Bind custom-token reuse to its chain and contract, reject vacuous asset sorting proof, and report capped Perps observations as truncated.
+- Bind Swap confirmation to a newly created transaction, reconcile exact TP/SL values, assert disabled zero-withdraw submission, and require structured run evidence.
+- Dismiss the first-run Perps tutorial through its visible Skip control before release recipes act on the Perps home screen.
+
 ## 0.37.0 - 2026-08-13
 
 ### Added

package/adapters/extension/artifact-runtime-state.cjs

@@ -5,7 +5,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
-  console.log('Usage: artifact-runtime-state.cjs <set|clear> --target <absolute-dir> --runtime-dir <relative-dir> [--source-dir <absolute-dir> --runtime-dist <absolute-dir> --provenance <absolute-file>]');
+  console.log('Usage: artifact-runtime-state.cjs <set|clear> --target <absolute-dir> --runtime-dir <relative-dir> [--source-dir <absolute-dir> --runtime-dist <absolute-dir> --provenance <absolute-file> --chrome-user-data-dir <absolute-dir>]');
   process.exit(0);
 }
 
@@ -29,6 +29,16 @@ if (action !== 'set') throw new Error('Usage: artifact-runtime-state.cjs <set|cl
 const sourceDir = requiredPath(args, 'source-dir');
 const runtimeDist = requiredPath(args, 'runtime-dist');
 const provenancePath = requiredPath(args, 'provenance');
+const chromeUserDataDir = requiredPath(args, 'chrome-user-data-dir');
+const directory = safeRuntimeDirectory(target, runtimeDir, true);
+const runtimeRoot = path.resolve(target, runtimeDir);
+if (!chromeUserDataDir.startsWith(`${runtimeRoot}${path.sep}`)) {
+  throw new Error('Release artifact Chrome profile must be a dedicated child of the runtime directory.');
+}
+const profileStat = fs.lstatSync(chromeUserDataDir, { throwIfNoEntry: false });
+if (!profileStat?.isDirectory() || profileStat.isSymbolicLink()) {
+  throw new Error('Release artifact Chrome profile must be an existing non-symlink directory.');
+}
 const provenance = readRegularJson(provenancePath);
 const relativeExtensionDir = provenance.extensionDir;
 if (
@@ -48,17 +58,17 @@ if (!fs.existsSync(path.join(sourceDir, 'manifest.json'))) throw new Error('Rele
 if (!fs.existsSync(path.join(runtimeDist, 'manifest.json'))) throw new Error('Release artifact runtime manifest is missing.');
 
 const state = {
-  schemaVersion: 1,
+  schemaVersion: 2,
   sourceDir,
   runtimeDist,
   provenancePath,
+  chromeUserDataDir,
   sha256: provenance.sha256,
   treeSha256: provenance.treeSha256,
   expectedVersion: provenance.expectedVersion,
   manifestVersion: provenance.manifestVersion,
   recordedAt: new Date().toISOString(),
 };
-const directory = safeRuntimeDirectory(target, runtimeDir, true);
 const statePath = path.join(directory, 'extension-release-artifact.json');
 const existing = fs.lstatSync(statePath, { throwIfNoEntry: false });
 if (existing && (!existing.isFile() || existing.isSymbolicLink())) throw invalidRuntimeState(statePath);

package/adapters/extension/inject.mjs

@@ -132,6 +132,7 @@ copyFile(path.join(runnerDir, 'adapters/extension/lib/slot-title.cjs'), path.joi
 copyFile(path.join(runnerDir, 'adapters/extension/lib/chrome-args.cjs'), path.join(harnessDir, 'scripts/lib/chrome-args.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/macos-focus.cjs'), path.join(harnessDir, 'scripts/lib/macos-focus.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/product-config.cjs'), path.join(harnessDir, 'scripts/lib/product-config.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/lib/validation-process-ownership.cjs'), path.join(harnessDir, 'scripts/lib/validation-process-ownership.cjs'));
 makeExecutableTree(path.join(harnessDir, 'scripts'));
 fs.writeFileSync(path.join(harnessDir, 'installed-scripts.sha256'), `${dirContentHash(path.join(harnessDir, 'scripts'))}\n`);
 

package/adapters/extension/launch-browser.cjs

@@ -24,6 +24,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { execFileSync, spawn, spawnSync } = require('node:child_process');
 const { extensionIdFromExtensionDir } = require('./lib/extension-id.cjs');
+const { profileProcessPids } = require('./lib/validation-process-ownership.cjs');
 const {
   automationRuntimeArgs,
   clearDetachedLaunchUnproven,
@@ -91,6 +92,7 @@ if (foreignPids.length > 0) {
   );
 }
 const ownedPids = new Set(listenerPids);
+for (const pid of profileProcessPids(args.profile)) ownedPids.add(pid);
 const previousPid = readPidFile(args['chrome-pid']);
 if (previousPid !== null && processIsOwnedHarnessBrowser(previousPid, args.profile, args['extension-dir'])) ownedPids.add(previousPid);
 try {

package/adapters/extension/live.sh

@@ -324,7 +324,7 @@ NODE
     prepare_parts+=("bash ${quoted_snapshot_dist} --dist ${quoted_dist} --target ${quoted_target} --runtime-root ${quoted_runtime_root} --runtime-dist ${quoted_runtime_dist}")
   fi
   if $EXTERNAL_ARTIFACT; then
-    prepare_parts+=("node ${quoted_artifact_state} set --target ${quoted_target} --runtime-dir ${quoted_runtime_dir} --source-dir ${quoted_dist} --runtime-dist ${quoted_runtime_dist} --provenance ${quoted_artifact_provenance}")
+    prepare_parts+=("node ${quoted_artifact_state} set --target ${quoted_target} --runtime-dir ${quoted_runtime_dir} --source-dir ${quoted_dist} --runtime-dist ${quoted_runtime_dist} --provenance ${quoted_artifact_provenance} --chrome-user-data-dir ${quoted_profile}")
   fi
   if ! $EXTERNAL_ARTIFACT; then
     prepare_parts+=("node ${quoted_configure_manifest} --target ${quoted_target} --manifest ${quoted_runtime_dist}/manifest.json")

package/adapters/extension/readiness.mjs

@@ -75,7 +75,7 @@ function extensionBuildRoot(target) {
     }
     const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
     const expected = path.join(runtimeRoot, process.env.RECIPE_RUNTIME_DIST_DIR || 'runtime-dist');
-    if (state.schemaVersion === 1 && path.resolve(state.runtimeDist || '') === expected) return expected;
+    if (state.schemaVersion === 2 && path.resolve(state.runtimeDist || '') === expected) return expected;
   } catch (error) {
     throw new Error(`Loaded release artifact identity is invalid: ${error instanceof Error ? error.message : String(error)}`);
   }

package/adapters/manifest.json

@@ -234,6 +234,14 @@
       "inputs": "--cdp-port --chrome-bin --profile --extension-dir --chrome-log --chrome-pid",
       "outputs": "pid file + append-log; exit 0 / non-zero"
     },
+    {
+      "id": "extension/validation-process-ownership",
+      "entry": "adapters/extension/lib/validation-process-ownership.cjs",
+      "kind": "lib",
+      "purpose": "Resolve browser processes owned by one isolated Extension validation profile.",
+      "inputs": "profile path",
+      "outputs": "owned process identifiers"
+    },
     {
       "id": "extension/refresh-build",
       "entry": "adapters/extension/refresh-build.sh",

package/dist/adapters/extension/runtime-decision.js

@@ -165,11 +165,13 @@ function releaseArtifactState(target) {
     const sourceDir = typeof state.sourceDir === "string" ? path.resolve(state.sourceDir) : "";
     const runtimeDist = typeof state.runtimeDist === "string" ? path.resolve(state.runtimeDist) : "";
     const provenancePath = typeof state.provenancePath === "string" ? path.resolve(state.provenancePath) : "";
+    const chromeUserDataDir = typeof state.chromeUserDataDir === "string" ? path.resolve(state.chromeUserDataDir) : "";
     const expectedRuntimeDist = path.join(
       runtimeRoot,
       process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist"
     );
-    if (state.schemaVersion !== 1 || !sourceDir || runtimeDist !== expectedRuntimeDist || !provenancePath) {
+    const profileStat = chromeUserDataDir ? fs.lstatSync(chromeUserDataDir, { throwIfNoEntry: false }) : void 0;
+    if (state.schemaVersion !== 2 || !sourceDir || runtimeDist !== expectedRuntimeDist || !provenancePath || !chromeUserDataDir.startsWith(`${runtimeRoot}${path.sep}`) || !profileStat?.isDirectory() || profileStat.isSymbolicLink()) {
       return { status: "invalid", reason: "artifact runtime identity has invalid paths or schema" };
     }
     const provenanceStat = fs.lstatSync(provenancePath);
@@ -199,6 +201,7 @@ function releaseArtifactState(target) {
       sourceDir,
       runtimeDist,
       provenancePath,
+      chromeUserDataDir,
       sha256,
       treeSha256,
       expectedVersion,

package/dist/adapters/extension/runtime.js

@@ -83,11 +83,15 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     (target2) => target2.type === "page" && String(target2.url ?? "").startsWith("chrome-extension://") && String(target2.url ?? "").includes("/sidepanel.html") && Boolean(target2.webSocketDebuggerUrl)
   );
   const extensionTargets = pageMode === "home-or-sidepanel" && homeTargets.length === 0 ? sidepanelTargets : homeTargets;
-  if (extensionTargets.length !== 1) {
-    const expected = pageMode === "home-or-sidepanel" ? "exactly one MetaMask extension home page target, or one sidepanel target when home is intentionally closed" : "exactly one MetaMask extension home page target";
+  if (extensionTargets.length === 0) {
+    const expected = pageMode === "home-or-sidepanel" ? "a MetaMask extension home page target, or one sidepanel target when home is intentionally closed" : "a MetaMask extension home page target";
     findings.push(`Expected ${expected}, found ${extensionTargets.length}.`);
   }
-  const target = extensionTargets[0];
+  const targetSelection = await selectResponsiveExtensionTarget(extensionTargets, cdpCallTimeoutMs);
+  const target = targetSelection.target;
+  if (extensionTargets.length > 1) {
+    warnings.push(`Found ${extensionTargets.length} MetaMask Extension page targets; health selected ${target?.url ?? "none"} after probing each candidate.`);
+  }
   if (!target?.webSocketDebuggerUrl) {
     return failReport(cdpPort, findings, {
       targetUrls: targets.map((entry) => entry.url).filter(Boolean)
@@ -205,6 +209,41 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     session?.close();
   }
 }
+async function selectResponsiveExtensionTarget(targets, timeoutMs) {
+  if (targets.length <= 1) return { target: targets[0] };
+  const probeTimeoutMs = Math.min(1e3, timeoutMs);
+  const ranked = [];
+  for (const [index, target] of targets.entries()) {
+    let session;
+    try {
+      session = await CdpSession.connect(target.webSocketDebuggerUrl, { timeoutMs: probeTimeoutMs });
+      await boundedCdpCall(session, "Runtime.enable", {}, probeTimeoutMs);
+      await boundedCdpCall(session, "Page.enable", {}, probeTimeoutMs);
+      const compositor = await probeCdpCompositorInteractivity(session, probeTimeoutMs);
+      const result = await boundedCdpCall(session, "Runtime.evaluate", {
+        expression: `(() => ({
+          readyState: String(document.readyState || ''),
+          href: String(location.href || ''),
+          text: String(document.body?.innerText || '').slice(0, 5000),
+        }))()`,
+        returnByValue: true
+      }, probeTimeoutMs);
+      const value = result.result?.value ?? {};
+      const text = String(value.text ?? "");
+      const href = String(value.href ?? target.url ?? "");
+      const blocked = text.includes("Background connection unresponsive") || text.includes("MetaMask had trouble starting") || text.includes("Unable to connect to Ethereum");
+      const onboarding = href.includes("/onboarding/");
+      const score = (compositor.status === "ready" ? 100 : compositor.status === "not-interactive" ? 10 : 0) + (value.readyState === "complete" ? 10 : 0) + (blocked ? 0 : 5) + (onboarding ? 0 : 2);
+      ranked.push({ target, score, index });
+    } catch {
+      ranked.push({ target, score: -1, index });
+    } finally {
+      session?.close();
+    }
+  }
+  ranked.sort((left, right) => right.score - left.score || left.index - right.index);
+  return { target: ranked[0]?.target };
+}
 function failReport(cdpPort, findings, details, extensionPageTargets = 0) {
   return {
     status: "FAIL",

package/dist/adapters/mobile/provision.js

@@ -14,6 +14,8 @@ const RUNWAY_IOS_METADATA = {
 };
 class SimulatorTargetError extends Error {
 }
+class SimulatorUnresponsiveError extends Error {
+}
 function resolvePoolIdentity(target) {
   const out = resolveSlotPortsByRepo(target);
   const id = {};
@@ -75,7 +77,7 @@ async function provisionRunwayMobile(target, options) {
     const sim = ensureSimulator(simulator, runtime, deviceType);
     let resolved;
     let reason = options.force ? "forced" : "fresh-install";
-    if (!options.force && appInstalled(sim.udid ?? sim.name)) {
+    if (!options.force && appInstalledWithRecovery(sim.udid ?? sim.name, options)) {
       const installed = readInstalledBaselineArtifact(resolvedTarget, sim, options.runtimeDir);
       let requestedRunId = options.run;
       if (installed && !requestedRunId) {
@@ -445,6 +447,24 @@ function bootSimulator(device, options) {
     log(options, `runway: bootstatus wait for ${device} did not confirm; continuing to install`);
   }
 }
+function restartSimulator(device, options) {
+  log(options, `runway: simulator ${device} did not answer the app probe; restarting it once`);
+  execFileSync("xcrun", ["simctl", "shutdown", device], {
+    stdio: ["ignore", "ignore", "ignore"],
+    timeout: 3e4
+  });
+  try {
+    execFileSync("xcrun", ["simctl", "boot", device], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: 3e4
+    });
+  } catch {
+  }
+  execFileSync("xcrun", ["simctl", "bootstatus", device, "-b"], {
+    stdio: ["ignore", "ignore", "ignore"],
+    timeout: 12e4
+  });
+}
 function preapproveDeepLinkScheme(device, bundleId, options) {
   const scheme = process.env.IOS_DEV_CLIENT_SCHEME ?? "expo-metamask";
   try {
@@ -572,12 +592,27 @@ function readInstalledBaselineArtifact(target, sim, runtimeDir) {
 }
 function appInstalled(device) {
   try {
-    execFileSync("xcrun", ["simctl", "get_app_container", device, RUNWAY_IOS_METADATA.bundleId, "app"], { stdio: ["ignore", "ignore", "ignore"] });
+    execFileSync("xcrun", ["simctl", "get_app_container", device, RUNWAY_IOS_METADATA.bundleId, "app"], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: 15e3
+    });
     return true;
-  } catch {
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ETIMEDOUT") {
+      throw new SimulatorUnresponsiveError(`simulator ${device} timed out while checking the installed app`);
+    }
     return false;
   }
 }
+function appInstalledWithRecovery(device, options) {
+  try {
+    return appInstalled(device);
+  } catch (error) {
+    if (!(error instanceof SimulatorUnresponsiveError)) throw error;
+    restartSimulator(device, options);
+    return appInstalled(device);
+  }
+}
 function writeRunwayBaseline(target, slot, platform, resolved, artifact, simulator, alreadyInstalled, runtimeDir, preservedArtifact) {
   const file = runwayBaselinePath(target, runtimeDir);
   fs.mkdirSync(path.dirname(file), { recursive: true });

package/dist/adapters.js

@@ -13,6 +13,7 @@ import { resolveWalletImportCredentials, validateWalletImportOptions } from "../
 const execFileAsync = promisify(execFile);
 const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
   "ui.press",
+  "ui.key_press",
   "ui.set_input",
   "ui.scroll",
   "ui.swipe",
@@ -34,7 +35,41 @@ function simpleAdapter(action, executor) {
     }
   };
 }
-const LIVE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
+const LIVE_ONLY_ACTIONS = /* @__PURE__ */ new Set([
+  "metamask.assets.read_visible_state",
+  "metamask.assets.read_details",
+  "metamask.assets.verify_sorting",
+  "metamask.assets.set_token_visibility",
+  "metamask.assets.import_custom_token",
+  "metamask.assets.prepare_send",
+  "metamask.assets.review_send",
+  "metamask.assets.finish_send",
+  "metamask.assets.set_custom_gas",
+  "metamask.assets.select_network_scope",
+  "metamask.wallet.lock",
+  "metamask.networks.read_visible_state",
+  "metamask.networks.add_custom",
+  "metamask.networks.add_chainlist",
+  "metamask.networks.remove_custom",
+  "metamask.perps.read_visible_state",
+  "metamask.perps.compare_provider_market",
+  "metamask.perps.read_eligibility",
+  "metamask.perps.select_market_filter",
+  "metamask.perps.close_visible_position",
+  "metamask.perps.set_market_favorite",
+  "metamask.perps.select_activity_filter",
+  "metamask.perps.open_balance_action",
+  "metamask.perps.open_position_action",
+  "metamask.perps.edit_margin",
+  "metamask.perps.update_position_tpsl",
+  "metamask.perps.read_funds_confirmation",
+  "metamask.swap_bridge.read_visible_state",
+  "metamask.swap_bridge.select_assets",
+  "metamask.swap_bridge.set_amount",
+  "metamask.swap_bridge.set_max_amount",
+  "metamask.swap_bridge.set_slippage",
+  "metamask.swap_bridge.submit_transaction",
+  "metamask.settings.set_basic_functionality",
   "metamask.perps.read_snapshot",
   "metamask.perps.read_positions",
   "metamask.perps.ensure_positions",
@@ -66,7 +101,7 @@ const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
 ]);
 const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set(["ui.navigate"]);
 function requiresLiveAdapter(platform, action) {
-  return LIVE_ONLY_PERPS_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
+  return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
 }
 function liveRuntimeConfigured(platform, node) {
   if (platform === "mobile" || platform === "core") return true;
@@ -214,6 +249,36 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
   ];
   const bundledActions = [
     ...walletActions,
+    "metamask.assets.read_visible_state",
+    ...platform === "extension" ? ["metamask.assets.read_details"] : [],
+    ...platform === "extension" ? ["metamask.assets.verify_sorting"] : [],
+    ...platform === "extension" ? ["metamask.assets.set_token_visibility"] : [],
+    ...platform === "extension" ? ["metamask.assets.import_custom_token"] : [],
+    ...platform === "extension" ? [
+      "metamask.assets.prepare_send",
+      "metamask.assets.review_send",
+      "metamask.assets.finish_send",
+      "metamask.assets.set_custom_gas",
+      "metamask.assets.select_network_scope"
+    ] : [],
+    ...platform === "extension" ? ["metamask.wallet.lock"] : [],
+    ...platform === "extension" ? ["metamask.networks.read_visible_state"] : [],
+    ...platform === "extension" ? ["metamask.networks.add_custom", "metamask.networks.add_chainlist", "metamask.networks.remove_custom"] : [],
+    "metamask.perps.read_visible_state",
+    ...platform === "extension" ? ["metamask.perps.compare_provider_market"] : [],
+    ...platform === "extension" ? ["metamask.perps.read_eligibility"] : [],
+    ...platform === "extension" ? [
+      "metamask.perps.open_position_action",
+      "metamask.perps.edit_margin",
+      "metamask.perps.update_position_tpsl"
+    ] : [],
+    "metamask.swap_bridge.read_visible_state",
+    "metamask.swap_bridge.select_assets",
+    "metamask.swap_bridge.set_amount",
+    ...platform === "extension" ? ["metamask.swap_bridge.set_max_amount"] : [],
+    ...platform === "extension" ? ["metamask.swap_bridge.set_slippage"] : [],
+    ...platform === "extension" ? ["metamask.swap_bridge.submit_transaction"] : [],
+    ...platform === "extension" ? ["metamask.settings.set_basic_functionality"] : [],
     "metamask.perps.read_positions",
     "metamask.perps.ensure_positions",
     "metamask.perps.assert_positions",
@@ -810,7 +875,7 @@ function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters) {
         if (live) return live.output;
         throw new Error(`ui.navigate requires library/actions/${platform}/ui/navigate.mjs.`);
       }
-      if (platform === "mobile" && NATIVE_PROVIDER_UI_ACTIONS.has(action) && (context.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || ["ui.swipe", "ui.pan", "ui.drag", "ui.long_press", "ui.capture_surface"].includes(action))) {
+      if (platform === "mobile" && NATIVE_PROVIDER_UI_ACTIONS.has(action) && (context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || ["ui.swipe", "ui.pan", "ui.drag", "ui.long_press", "ui.capture_surface"].includes(action))) {
         return executeNativeProviderAction(action, node, context, harness.createNativeUiTransport);
       }
       return base.execute(action, action === "ui.wait_for" ? normalizeUiWaitNode(node) : node, context);

package/dist/app-lifecycle.js

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

package/dist/commands/call.js

@@ -290,7 +290,10 @@ async function handleCall(argv) {
       target,
       heal,
       state,
-      () => recoverRunInfra(adapter, target, json)
+      () => recoverRunInfra(adapter, target, json, {
+        cdpPort: optionString(options, "cdpPort"),
+        watcherPort: optionString(options, "watcherPort") ?? optionString(options, "metroPort")
+      })
     );
     if (violation !== null) {
       const conciseFailure = violation.originalError ? conciseFailureForHuman(violation.originalError) : "";

package/dist/commands/launch/extension.js

@@ -56,6 +56,12 @@ async function installExtensionDeps(target) {
   return result;
 }
 async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
+  const requestedCdpPort = process.env.CDP_PORT;
+  const requestedRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+  const restoreRequestedPorts = () => {
+    if (requestedCdpPort) process.env.CDP_PORT = requestedCdpPort;
+    if (requestedRecipeCdpPort) process.env.RECIPE_CDP_PORT = requestedRecipeCdpPort;
+  };
   if (process.env.CHROME_USER_DATA_DIR) {
     process.env.CHROME_USER_DATA_DIR = path.resolve(process.env.CHROME_USER_DATA_DIR);
   }
@@ -63,6 +69,7 @@ async function launchExtension(target, tier, wantWatch, displayMode = "fullscree
   const artifactSnapshot = runtimeDistCheck(target, artifact);
   const artifactLaunchable = !wantWatch && tier !== "build" && artifact.status === "valid" && artifactSnapshot.status === "fresh";
   const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target, artifact);
+  restoreRequestedPorts();
   if (artifact.status !== "none" && !reusable && !artifactLaunchable) {
     const detail = artifact.status === "invalid" ? `identity is invalid: ${artifact.reason ?? "unknown reason"}` : "runtime is not healthy and reusable";
     return {
@@ -82,6 +89,7 @@ Next: ${block.userAction}`
     }
   }
   await ensureHarnessFresh(target, "extension");
+  restoreRequestedPorts();
   if (wantWatch) {
     const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
     const watchArgs = ["--target", target];
@@ -93,6 +101,12 @@ Next: ${block.userAction}`
     return extensionRebuild(target);
   }
   if (reusable) {
+    if (artifact.status === "valid") {
+      console.error(colorHumanMessage(
+        `\u2192 extension release reuse \u2014 verified artifact ${artifact.manifestVersion ?? artifact.expectedVersion ?? ""} \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no snapshot mutation)`
+      ));
+      return { status: EXIT.ok, output: "Verified release artifact runtime is already healthy." };
+    }
     return extensionReattach(target, displayMode);
   }
   if (artifactLaunchable) {
@@ -115,7 +129,7 @@ async function extensionRuntimeReusable(target, artifact = releaseArtifactState(
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const reachable = await cdpVersionReachable(cdpPort);
     const nonceOwned = reachable && await cdpOwnedByRuntimeNonce(cdpPort, target);
-    const owned = nonceOwned || reachable && cdpOwnedByExpectedRuntime(cdpPort, target);
+    const owned = nonceOwned || reachable && cdpOwnedByExpectedRuntime(cdpPort, target, releaseArtifact ? artifact.chromeUserDataDir : void 0);
     const targetPresent = owned && await cdpHasExpectedExtensionTarget(cdpPort, target);
     const healthy = targetPresent && await cdpRuntimeHealthy(cdpPort, target);
     if (healthy) return true;
@@ -142,9 +156,9 @@ function commandHasExactFlagValue(command, flag, value) {
   }
   return false;
 }
-function cdpOwnedByExpectedRuntime(port, target) {
+function cdpOwnedByExpectedRuntime(port, target, profileOverride) {
   const pids = cdpListenerPids(port);
-  const profile = expectedChromeProfile(target);
+  const profile = profileOverride ?? expectedChromeProfile(target);
   const runtimeDist = expectedRuntimeDist(target);
   for (const pid of pids) {
     try {
@@ -369,7 +383,7 @@ async function extensionLaunchDevelopment(target) {
   return spawnScriptStreaming(liveScript, liveArgs, target);
 }
 async function extensionLaunchReleaseArtifact(target, artifact) {
-  if (!artifact.sourceDir || !artifact.provenancePath) {
+  if (!artifact.sourceDir || !artifact.provenancePath || !artifact.chromeUserDataDir) {
     return {
       status: EXIT.infra,
       output: "RELEASE_ARTIFACT_NOT_REUSABLE: The loaded release artifact identity is incomplete.\nNext: rerun runtime-launch with the same artifact source."
@@ -384,7 +398,9 @@ async function extensionLaunchReleaseArtifact(target, artifact) {
     artifact.sourceDir,
     "--artifact-provenance",
     artifact.provenancePath,
-    "--preserve-profile"
+    "--preserve-profile",
+    "--chrome-user-data-dir",
+    artifact.chromeUserDataDir
   ];
   if (process.env.CDP_PORT) liveArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.EXTENSION_START_URL) liveArgs.push("--start-url", process.env.EXTENSION_START_URL);

package/dist/commands/launch/index.js

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

package/dist/commands/run-engine.js

@@ -1197,43 +1197,54 @@ const RUN_RECOVERY_CODE = {
   extension: "extension.runtime_recovered",
   core: "run.retried"
 };
-async function recoverRunInfra(adapter, target, json) {
+async function recoverRunInfra(adapter, target, json, runtimeOptions = {}) {
   getAdapterSurface(adapter).resolveSlotPorts(target);
-  if (adapter === "extension") {
-    const { 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);
+  const previousCdpPort = process.env.CDP_PORT;
+  const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+  if (runtimeOptions.cdpPort) {
+    process.env.CDP_PORT = runtimeOptions.cdpPort;
+    process.env.RECIPE_CDP_PORT = runtimeOptions.cdpPort;
   }
-  if (adapter === "mobile") {
-    try {
-      const artifact = requireCurrentMobileReleaseArtifactState(target);
-      if (artifact) {
-        const { relaunchAndroidReleaseArtifactRuntime } = await import("../adapters/mobile/release-artifact.js");
-        await relaunchAndroidReleaseArtifactRuntime(artifact);
+  try {
+    if (adapter === "extension") {
+      const { releaseArtifactState } = await import("../adapters/extension/runtime-decision.js");
+      const artifact = releaseArtifactState(target);
+      if (artifact.status !== "none" && artifact.status !== "valid") {
         return {
-          status: 0,
-          output: `Relaunched ${artifact.packageId} ${artifact.versionName} (${artifact.versionCode}) on ${artifact.deviceSerial}.`
+          status: 1,
+          output: "Release artifact recovery cannot trust the recorded runtime identity.\nNext: rerun runtime-launch with the same artifact source."
         };
       }
-    } 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)}
+      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);
     }
-    const { launchMobile } = await import("./launch/mobile.js");
-    const platform = resolveMobileRecoveryPlatform();
-    return launchMobile(target, platform, "quick", json);
+    return { status: 0, output: "headless run retry" };
+  } finally {
+    restoreEnv("CDP_PORT", previousCdpPort);
+    restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
   }
-  return { status: 0, output: "headless run retry" };
 }
 function resolveMobileRecoveryPlatform(env = process.env) {
   if (env.PLATFORM === "android" || env.PLATFORM === "ios") return env.PLATFORM;

package/dist/commands/run.js

@@ -284,7 +284,7 @@ async function handleRunInner({ positional, options }, stream) {
       target,
       heal,
       state,
-      () => recoverRunInfra(adapter, target, machine),
+      () => recoverRunInfra(adapter, target, machine, runtimeOptions),
       (code) => stream.phase("recover", { code })
     );
     for (const mutation of state.mutations) stream.mutation(mutation);