@deeeed/metamask-harness 0.47.3 → 0.48.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.48.0 - 2026-09-07
+
+- Consolidate parameterized recipes, move specialized Perps journeys into the team library, and separate short performance checks from full coverage suites.
+- Correct wallet, token, quote and Perps validation; honor network-addition opt-in and preserve identity-bound cleanup and failure evidence. Bound macOS focus calls, avoid duplicate Android preparation and native-session ownership, and refuse dependency repairs through shared directory links.
+- Add compact, searchable tutorials and version-matched recipe guidance for branching, composition, performance, and diagnosing drift.
+
+## 0.47.4 - 2026-09-05
+
+### Fixed
+
+- Verify Mobile reloads through execution-context replacement when React Native retains its Hermes target ID, and advance broker runtime identity on context reset for lifecycle readiness checks.
+
 ## 0.47.3 - 2026-09-05
 
 ### Fixed

package/README.md

@@ -129,7 +129,7 @@ mm-harness actions --action metamask.wallet.ensure_unlocked
 mm-harness call metamask.wallet.ensure_unlocked
 
 mm-harness run --list
-mm-harness run perps.clean-market-testnet --describe
+mm-harness run perps.smoke --describe
 mm-harness run wallet.smoke --describe
 mm-harness run wallet.import method=auto
 
@@ -145,7 +145,8 @@ absolute paths to the report, trace, executed recipe, and artifact manifest.
 Use `mm-harness last --json` to resume without repeating the last operation.
 
 For automation, `--json` emits one stable document. `run --json-stream` emits
-line-buffered JSONL progress and a terminal event.
+line-buffered JSONL progress and a terminal event. Its status matches the recipe's
+`pass`, `fail`, or `unknown` verdict; `unknown` still exits nonzero.
 
 ## Team libraries
 

package/adapters/extension/lib/macos-focus.cjs

@@ -8,7 +8,7 @@ function captureMacFrontmostProcess() {
     const value = execFileSync('osascript', [
       '-e',
       'tell application "System Events" to get unix id of first application process whose frontmost is true',
-    ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1_000 }).trim();
     const pid = Number.parseInt(value, 10);
     return Number.isInteger(pid) && pid > 0 ? pid : null;
   } catch {
@@ -22,7 +22,7 @@ function restoreMacFrontmostProcess(pid) {
     execFileSync('osascript', [
       '-e',
       `tell application "System Events" to set frontmost of first application process whose unix id is ${pid} to true`,
-    ], { stdio: 'ignore' });
+    ], { stdio: 'ignore', timeout: 1_000 });
     return true;
   } catch {
     return false;

package/adapters/extension/live.sh

@@ -45,7 +45,7 @@ START_WATCH=false
 BUILD_LAVAMOAT=false
 EXTERNAL_ARTIFACT=false
 ARTIFACT_PROVENANCE=""
-RESET_PROFILE=true
+RESET_PROFILE=false
 DIST_DIR="dist/chrome"
 CHROME_USER_DATA_DIR="${CHROME_USER_DATA_DIR:-}"
 REMOTE_FLAGS=""
@@ -62,6 +62,7 @@ while [ "$#" -gt 0 ]; do
     --external-artifact) EXTERNAL_ARTIFACT=true; LAUNCH_EXISTING_DIST=true; shift ;;
     --artifact-provenance) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; ARTIFACT_PROVENANCE="$2"; shift 2 ;;
     --preserve-profile) RESET_PROFILE=false; shift ;;
+    --reset-profile) RESET_PROFILE=true; shift ;;
     --start-url) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; START_URL="$2"; shift 2 ;;
     --start-watch|--start-test-watch) START_WATCH=true; LAUNCH_EXISTING_DIST=true; shift ;;
     --build-lavamoat) BUILD_LAVAMOAT=true; LAUNCH_EXISTING_DIST=true; shift ;;
@@ -69,7 +70,7 @@ while [ "$#" -gt 0 ]; do
     --dist-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; DIST_DIR="$2"; shift 2 ;;
     --chrome-user-data-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; CHROME_USER_DATA_DIR="$2"; shift 2 ;;
     --remote-flag) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; REMOTE_FLAGS="$2"; shift 2 ;;
-    -h|--help) echo "Usage: live.sh [--target <metamask-extension>] [--out <recipes-dir>] [--cdp-port <port>] [--launch-existing-dist|--start-watch|--build-lavamoat|--external-artifact --dist-dir <absolute-dir> --artifact-provenance <absolute-file> [--preserve-profile]|--prepare-cmd <cmd>] [--launch-only] [--dist-dir dist/chrome] [--remote-flag KEY=VARIANT] [--artifacts-dir <dir>]"; exit 0 ;;
+    -h|--help) echo "Usage: live.sh [--target <metamask-extension>] [--out <recipes-dir>] [--cdp-port <port>] [--launch-existing-dist|--start-watch|--build-lavamoat|--external-artifact --dist-dir <absolute-dir> --artifact-provenance <absolute-file>|--prepare-cmd <cmd>] [--preserve-profile|--reset-profile] [--launch-only] [--dist-dir dist/chrome] [--remote-flag KEY=VARIANT] [--artifacts-dir <dir>]"; exit 0 ;;
     *) echo "Unknown arg: $1" >&2; exit 2 ;;
   esac
 done
@@ -86,10 +87,6 @@ if $EXTERNAL_ARTIFACT && [ ! -f "$ARTIFACT_PROVENANCE" ]; then
   echo "--external-artifact requires --artifact-provenance <file>" >&2
   exit 2
 fi
-if ! $RESET_PROFILE && ! $EXTERNAL_ARTIFACT; then
-  echo "--preserve-profile is only valid for a verified external artifact" >&2
-  exit 2
-fi
 if $EXTERNAL_ARTIFACT; then
   case "$ARTIFACT_PROVENANCE" in
     /*) ;;
@@ -200,11 +197,11 @@ if $LAUNCH_EXISTING_DIST && [ -z "$PREPARE_CMD" ]; then
   FIXTURE_STATE_ABS="$ARTIFACTS/fixture-state.json"
   FIXTURE_VALIDATION_ABS="$ARTIFACTS/logs/fixture-account-parity.json"
   WALLET_FIXTURE_ABS=""
-  if ! $EXTERNAL_ARTIFACT; then
+  if $RESET_PROFILE && ! $EXTERNAL_ARTIFACT; then
     # Wallet fixture resolution chain + provenance live in seed-fixture.sh.
     WALLET_FIXTURE_ABS="$(bash "$SCRIPT_DIR/seed-fixture.sh" resolve --target "$TARGET" --cdp-port "$CDP_PORT" --source-out "$ARTIFACTS/logs/fixture-source.json")"
   fi
-  if ! $EXTERNAL_ARTIFACT && [ ! -f "$ARTIFACTS/logs/fixture-source.json" ]; then
+  if $RESET_PROFILE && ! $EXTERNAL_ARTIFACT && [ ! -f "$ARTIFACTS/logs/fixture-source.json" ]; then
     # resolve failed before writing provenance (invalid RECIPE_WALLET_FIXTURE);
     # keep the documented missing-provenance artifact.
     node - "$ARTIFACTS/logs/fixture-source.json" "" <<'NODE'
@@ -370,6 +367,7 @@ display_args=(mm-harness runtime-launch --adapter extension --target "$TARGET" -
 $START_WATCH && display_args+=(--start-watch)
 $BUILD_LAVAMOAT && display_args+=(--build-lavamoat)
 $EXTERNAL_ARTIFACT && display_args+=(--external-artifact --dist-dir "$DIST_DIR" --artifact-provenance "$ARTIFACT_PROVENANCE")
+$RESET_PROFILE && display_args+=(--reset-profile)
 $RESET_PROFILE || display_args+=(--preserve-profile)
 [ -n "$REMOTE_FLAGS" ] && display_args+=(--remote-flag "$REMOTE_FLAGS")
 [ -n "$CHROME_USER_DATA_DIR" ] && display_args+=(--chrome-user-data-dir "$CHROME_USER_DATA_DIR")

package/adapters/mobile/bridge-runtime/lib/bridge-errors.cjs

@@ -64,6 +64,7 @@ const NEEDLE_CODES = [
   ['pinned android device', BRIDGE_ERROR_CODES.NO_TARGET],
   ['no react native bridge target', BRIDGE_ERROR_CODES.NO_TARGET],
   ['cdp broker target unavailable', BRIDGE_ERROR_CODES.NO_TARGET],
+  ['cdp broker never observed the requested target', BRIDGE_ERROR_CODES.NO_TARGET],
   ['websocket closed', BRIDGE_ERROR_CODES.WS_CLOSED],
   ['websocket error', BRIDGE_ERROR_CODES.WS_CLOSED],
   ['cdp connection timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],

package/adapters/mobile/bridge-runtime/lib/cdp-broker.cjs

@@ -862,6 +862,10 @@ function createCdpBroker({
       }
     },
     onCdpEvent(deviceId, method, params) {
+      if (method === 'Runtime.executionContextsCleared') {
+        const target = knownTargets.get(deviceId);
+        if (target) knownTargets.set(deviceId, { ...target, generation: target.generation + 1 });
+      }
       for (const socket of clients) {
         if (subscriptions.get(socket)?.has(`${deviceId}\u0000${method}`)) {
           writeMessage(socket, { type: 'event', deviceId, method, params });

package/adapters/mobile/reload-app.mjs

@@ -1,12 +1,54 @@
 #!/usr/bin/env node
 
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 import { createRequire } from 'node:module';
 import { resolveMobileToolPath } from '../../library/actions/mobile/platform/tool-paths.mjs';
 
 const require = createRequire(import.meta.url);
 const WebSocket = require('ws');
-const { discoverTarget } = require('./bridge-runtime/lib/target-discovery.cjs');
+const { discoverTarget, rankRuntimeCandidates } = require('./bridge-runtime/lib/target-discovery.cjs');
+const { brokerSocketPath, createBrokerClient, deviceIdFromUrl } = require('./bridge-runtime/lib/cdp-broker.cjs');
+const { createWSClient } = require('./bridge-runtime/lib/ws-client.cjs');
+
+async function observeRuntimeReset(port, target) {
+  const socketPath = brokerSocketPath(
+    process.env.RECIPE_RUNTIME_DIR || path.join(process.cwd(), 'temp/recipe/runtime'),
+    port,
+  );
+  const client = fs.existsSync(socketPath)
+    ? await createBrokerClient(socketPath, deviceIdFromUrl(target.wsUrl), 5000)
+    : await createWSClient(target.wsUrl, 5000);
+  let armed = false;
+  let cleared = false;
+  let recreated = false;
+  client.on('Runtime.executionContextsCleared', () => {
+    if (armed) cleared = true;
+  });
+  client.on('Runtime.executionContextCreated', () => {
+    if (armed && cleared) recreated = true;
+  });
+  try {
+    await client.send('Runtime.enable');
+    // Finish subscription/bootstrap before the reload request can generate events.
+    await client.send('Runtime.evaluate', { expression: 'true', returnByValue: true });
+    armed = true;
+  } catch (error) {
+    client.close();
+    throw error;
+  }
+  return {
+    get recreated() { return recreated; },
+    async responsive(timeoutMs) {
+      const result = await client.send('Runtime.evaluate', {
+        expression: 'true', returnByValue: true,
+      }, timeoutMs);
+      return result?.result?.value === true;
+    },
+    close() { client.close(); },
+  };
+}
 
 function parseArgs(argv) {
   const args = {
@@ -46,30 +88,38 @@ async function reload(port) {
       'The Android Hermes sampling profiler is active, so a runtime reload can abort the app. Use an explicit app.lifecycle restart.',
     );
   }
-  await new Promise((resolve, reject) => {
-    const socket = new WebSocket(`ws://127.0.0.1:${numericPort}/message`);
-    const timeout = setTimeout(() => {
-      socket.close();
-      reject(new Error(`Metro reload timed out on port ${numericPort}`));
-    }, 5000);
-    socket.on('open', () => {
-      socket.send(JSON.stringify({ method: 'reload', version: 2 }));
-      setTimeout(() => {
-        clearTimeout(timeout);
+  const observer = await observeRuntimeReset(numericPort, targetBefore);
+  let verification;
+  try {
+    await new Promise((resolve, reject) => {
+      const socket = new WebSocket(`ws://127.0.0.1:${numericPort}/message`);
+      const timeout = setTimeout(() => {
         socket.close();
-        resolve();
-      }, 50);
-    });
-    socket.on('error', () => {
-      clearTimeout(timeout);
-      reject(new Error(`Metro is not reachable on port ${numericPort}`));
+        reject(new Error(`Metro reload timed out on port ${numericPort}`));
+      }, 5000);
+      socket.on('open', () => {
+        socket.send(JSON.stringify({ method: 'reload', version: 2 }));
+        setTimeout(() => {
+          clearTimeout(timeout);
+          socket.close();
+          resolve();
+        }, 50);
+      });
+      socket.on('error', () => {
+        clearTimeout(timeout);
+        reject(new Error(`Metro is not reachable on port ${numericPort}`));
+      });
     });
-  });
-  const targetAfter = await waitForReload(
-    numericPort,
-    targetBefore.id,
-    processBefore,
-  );
+    verification = await waitForReload(
+      numericPort,
+      targetBefore,
+      processBefore,
+      observer,
+    );
+  } finally {
+    observer.close();
+  }
+  const { target: targetAfter, proof } = verification;
   const processAfter = processBefore ? readAndroidPid() : null;
   if (processBefore && processAfter !== processBefore) {
     throw new Error(
@@ -84,6 +134,7 @@ async function reload(port) {
     port: numericPort,
     targetBefore: targetBefore.id,
     targetAfter: targetAfter.id,
+    verification: proof,
     ...(processBefore
       ? {
           processBefore,
@@ -94,20 +145,33 @@ async function reload(port) {
   };
 }
 
-async function waitForReload(port, targetBefore, processBefore) {
+async function waitForReload(port, targetBefore, processBefore, observer) {
   const deadline = Date.now() + 30_000;
+  let lastError;
   while (Date.now() < deadline) {
     if (processBefore && readAndroidPid() !== processBefore) {
       throw new Error(
         `Android app process ${processBefore} exited during reload. Inspect the native crash before using an explicit app.lifecycle restart.`,
       );
     }
-    const target = await readHermesTarget(port).catch(() => null);
-    if (target && target.id !== targetBefore) return target;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/json/list`, {
+        signal: AbortSignal.timeout(Math.max(1, Math.min(1000, deadline - Date.now()))),
+      });
+      const targets = rankRuntimeCandidates(await response.json());
+      const target = targets.find((item) => item.deviceName === targetBefore.deviceName);
+      if (target && target.id !== targetBefore.id) return { target, proof: 'target-replaced' };
+      if (target && observer.recreated && await observer.responsive(Math.max(1, Math.min(1000, deadline - Date.now())))) {
+        return { target, proof: 'execution-context-recreated' };
+      }
+    } catch (error) {
+      // A reload temporarily removes the runtime; preserve the last failure if it never returns.
+      lastError = error;
+    }
     await new Promise((resolve) => setTimeout(resolve, 250));
   }
   throw new Error(
-    `React Native did not expose a new Hermes target after reload on port ${port}`,
+    `React Native reload was not verified on port ${port}: no target replacement or responsive new execution context${lastError ? ` (${lastError.message})` : ''}.\nNext: mm-harness status --json`,
   );
 }
 
@@ -155,7 +219,7 @@ const args = parseArgs(process.argv.slice(2));
 reload(args.port)
   .then((result) => {
     if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    else console.log(`Reload requested through Metro :${result.port}`);
+    else console.log(`Reload verified through Metro :${result.port} (${result.verification})`);
   })
   .catch((error) => {
     const result = { ok: false, adapter: 'mobile', error: String(error?.message || error) };

package/adapters/shared/ensure-runner-deps.sh

@@ -60,6 +60,12 @@ if [ ! -f "$RUNNER_DIR/package.json" ]; then
   exit 1
 fi
 
+if [ -L "$RUNNER_DIR/node_modules" ]; then
+  echo "mm-harness: cannot repair dependencies through a shared node_modules symlink." >&2
+  echo "  Next: readlink '$RUNNER_DIR/node_modules' # inspect the shared target, then prepare a private dependency directory" >&2
+  exit 1
+fi
+
 if [ -n "$PROTOCOL_ROOT" ] && [ -f "$RUNNER_DIR/scripts/link-local-farmslot.mjs" ]; then
   if [ -f "$PROTOCOL_ROOT/packages/recipe-harness/package.json" ]; then
     FARMSLOT_ROOT="$(cd "$PROTOCOL_ROOT" && pwd -P)" \

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

@@ -356,7 +356,7 @@ async function cdpCheck(target, cdpPort, pageMode) {
   try {
     const { checkExtensionRuntimeHealth } = await import("./runtime.js");
     const report = await checkExtensionRuntimeHealth(target, cdpPort, { pageMode });
-    return report.status === "PASS" ? { status: "pass" } : { status: "fail", findings: report.findings };
+    return report.status === "PASS" ? { status: "pass" } : { status: "fail", findings: report.findings, errorCode: report.errorCode };
   } catch (error) {
     return { status: "fail", findings: [error instanceof Error ? error.message : String(error)] };
   }
@@ -441,6 +441,16 @@ async function decideExtensionReadiness(target, options = {}) {
       reasons: ["Build is fresh and the extension runtime is healthy over CDP."],
       actions: []
     },
+    {
+      when: cdp.errorCode === "EVM_RPC_EXECUTION_FAILED",
+      decision: "blocked",
+      reasonCode: "rpc-execution-failed",
+      reasons: [
+        "Background RPC fetch failed before an HTTP response; inspect its JavaScript stack before relaunching.",
+        ...cdp.findings?.slice(0, 3) ?? []
+      ],
+      actions: []
+    },
     {
       when: cdp.status === "fail",
       decision: "relaunch",
@@ -482,6 +492,13 @@ async function decideExtensionReadiness(target, options = {}) {
         reasons: [`Release artifact ${releaseArtifact.expectedVersion} is intact and healthy over CDP.`],
         actions: []
       },
+      {
+        when: cdp.errorCode === "EVM_RPC_EXECUTION_FAILED",
+        decision: "blocked",
+        reasonCode: "rpc-execution-failed",
+        reasons: ["Background RPC fetch failed before an HTTP response; inspect its JavaScript stack before relaunching.", ...cdp.findings?.slice(0, 3) ?? []],
+        actions: []
+      },
       {
         when: cdp.status === "fail",
         decision: "relaunch",

package/dist/adapters/extension/runtime.js

@@ -166,10 +166,11 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     if (runtime.ethereumConnectionUnavailable === true) {
       findings.push('Extension UI reports "Unable to connect to Ethereum".');
     }
+    const rpcExecutionFailed = runtime.evmRpcProbeOk !== true && /Failed to execute 'fetch' on 'WorkerGlobalScope': Illegal invocation/u.test(String(runtime.evmRpcProbeError));
     if (runtime.evmRpcProbeOk !== true) {
       const probeError = String(runtime.evmRpcProbeError ?? "unknown error").replace(/[.\s]+$/u, "");
       findings.push(
-        `EVM RPC readiness probe failed: ${probeError}. Infura configured \u2260 RPC reachable.`
+        rpcExecutionFailed ? `EVM_RPC_EXECUTION_FAILED: background RPC fetch threw before an HTTP response: ${probeError}.` : `EVM RPC readiness probe failed: ${probeError}. Infura configured \u2260 RPC reachable.`
       );
     }
     if (runtime.hasSubmitRequest === true && runtime.backgroundProbeOk !== true) {
@@ -180,8 +181,8 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     return {
       status: findings.length === 0 ? "PASS" : "FAIL",
       ...evmRpcUnreachable ? {
-        errorCode: "EVM_RPC_UNREACHABLE",
-        userAction: evmRpcRecoveryAction(projectRoot)
+        errorCode: rpcExecutionFailed ? "EVM_RPC_EXECUTION_FAILED" : "EVM_RPC_UNREACHABLE",
+        userAction: rpcExecutionFailed ? `mm-harness logs --target ${shellQuote(projectRoot)} --full  # inspect the background fetch stack; credential resync is not indicated by this error` : evmRpcRecoveryAction(projectRoot)
       } : {},
       warnings,
       cdpPort,
@@ -497,8 +498,7 @@ function formatHealthFailure(report, projectRoot) {
   ].join("\n");
 }
 function compositorRecoveryAction(projectRoot) {
-  const recovery = `mm-harness launch --verify --target ${JSON.stringify(projectRoot)}`;
-  return process.platform === "darwin" ? `Unlock the macOS session, then rerun: ${recovery}` : `Restore an active display compositor, then rerun: ${recovery}`;
+  return `Make the MetaMask tab visible in an unlocked desktop session, then rerun: mm-harness verify --adapter extension --target ${shellQuote(projectRoot)}`;
 }
 function evmRpcRecoveryAction(projectRoot) {
   return `Confirm ${shellQuote(path.join(projectRoot, ".metamaskrc"))} has a real INFURA_PROJECT_ID (not 00000000000), then rerun: mm-harness launch --verify --target ${shellQuote(projectRoot)}`;

package/dist/adapters/extension/surface.js

@@ -16,6 +16,7 @@ function watcherStatus(buildLog) {
 }
 function extensionRuntimeNextAction(reasonCode, target) {
   const resolved = shellQuote(path.resolve(target));
+  if (reasonCode === "rpc-execution-failed") return `mm-harness logs --target ${resolved} --full`;
   return reasonCode === "deps-missing" || reasonCode === "deps-stale" ? `cd ${resolved} && yarn install --immutable` : `mm-harness launch --adapter extension --target ${resolved}`;
 }
 const extensionSurface = {

package/dist/app-lifecycle.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { promisify } from "node:util";
+const MOBILE_LIFECYCLE_PREPARED = /* @__PURE__ */ Symbol("mobileLifecyclePrepared");
 const MOBILE_LIFECYCLE_DEADLINE_FIELD = "_mobile_lifecycle_deadline_epoch_ms";
 const lifecycleDeadline = new AsyncLocalStorage();
 const execFileAsync = promisify(execFile);
@@ -64,7 +65,7 @@ function resolveMetaMaskMobileLifecycleTarget(node, rawContext) {
       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: opaqueRuntime ? void 0 : launchUrl,
       metroPort: opaqueRuntime ? void 0 : port,
-      prelaunchCalls: opaqueRuntime ? [] : expoBundlePrewarmCalls(port, "android")
+      prelaunchCalls: opaqueRuntime || node[MOBILE_LIFECYCLE_PREPARED] ? [] : expoBundlePrewarmCalls(port, "android")
     };
   }
   return {
@@ -123,6 +124,7 @@ function scalar(value, label) {
 }
 export {
   MOBILE_LIFECYCLE_DEADLINE_FIELD,
+  MOBILE_LIFECYCLE_PREPARED,
   bindMetaMaskMobileLifecycleDeadline,
   createMetaMaskMobileLifecycleCommandRunner,
   resolveMetaMaskMobileLifecycleTarget

package/dist/command-contract.js

@@ -258,6 +258,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
     options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, MOBILE_PLATFORM, {
       "--cdp-port": value(),
       "--chrome-user-data-dir": value(),
+      "--reset-profile": bool(),
+      "--preserve-profile": bool(),
       "--artifacts-dir": value(),
       "--start-watch": bool(),
       "--build-lavamoat": bool(),

package/dist/commands/call.js

@@ -377,14 +377,7 @@ async function handleCall(argv) {
     persistRunEffects(result.summaryPath, result.artifactManifestPath, state);
     if (violation !== null) {
       const conciseFailure = violation.originalError ? conciseFailureForHuman(violation.originalError) : "";
-      const example = describedAction ? actionExampleCommand(
-        describedAction,
-        adapter,
-        target,
-        process.env.MM_HARNESS_INVOKED_AS ?? process.env.MM_HARNESS_EXECUTABLE ?? "mm-harness",
-        args
-      ) : void 0;
-      const taughtViolation = violation.code === "APP_LOGIC_FAILURE" && conciseFailure.includes(" requires ") && example ? { ...violation, userAction: example } : violation;
+      const taughtViolation = violation.code === "APP_LOGIC_FAILURE" && conciseFailure.includes(" requires ") && describedAction ? { ...violation, userAction: `mm-harness actions ${resolvedAction} --adapter ${adapter} --json` } : violation;
       return emitHealViolation(json, "call", result, taughtViolation, state, adapter);
     }
     const callOutput = readCallOutput(result.tracePath);

package/dist/commands/device-target.js

@@ -109,8 +109,13 @@ function applyDeviceTargeting(command, adapter, options, opts) {
     }
     return { ok: true };
   }
+  const discoveryErrors = [];
+  const discoveryFailure = () => {
+    const error = discoveryErrors.find((error2) => !platformPreference || error2.platform === platformPreference);
+    return error ? { ok: false, code: "DEVICE_DISCOVERY_FAILED", message: error.message, userAction: error.userAction } : void 0;
+  };
   if (device !== void 0) {
-    const connected2 = listConnectedDevices();
+    const connected2 = listConnectedDevices(void 0, discoveryErrors);
     const setResolvedDevice = (matched) => {
       if (platformPreference && matched.platform !== platformPreference) {
         return {
@@ -130,10 +135,12 @@ function applyDeviceTargeting(command, adapter, options, opts) {
     if (androidById) {
       return setResolvedDevice(androidById);
     }
-    const iosById = connected2.find((d) => d.platform === "ios" && d.id === device) ?? (command === "launch" && platformPreference === "ios" ? findAvailableIosSimulatorById(device) : void 0);
+    const iosById = connected2.find((d) => d.platform === "ios" && d.id === device) ?? (command === "launch" && platformPreference === "ios" ? findAvailableIosSimulatorById(device, discoveryErrors) : void 0);
     if (iosById) {
       return setResolvedDevice(iosById);
     }
+    const probeFailure2 = discoveryFailure();
+    if (probeFailure2) return probeFailure2;
     const normalizedDevice = normalizeDeviceName(device);
     const byName = connected2.filter((d) => {
       const name = d.name ?? "";
@@ -161,7 +168,9 @@ ${formatConnectedDevices(connected2)}` : `  No devices are currently connected (
       userAction: deviceRecovery(options, opts.rerun)
     };
   }
-  const connected = listConnectedDevices();
+  const connected = listConnectedDevices(void 0, discoveryErrors);
+  const probeFailure = discoveryFailure();
+  if (probeFailure) return opts.gate || command === "launch" ? probeFailure : { ok: true };
   const targetable = connected.filter(isTargetable);
   if (platformPreference) {
     const selectedTargetable2 = targetable.filter(deviceSelected);

package/dist/commands/doctor.js

@@ -188,6 +188,7 @@ async function handleDoctor({ options }) {
   const liveView = deviceView ? await mobileDeviceLiveView(target, deviceView) : null;
   const devices = liveView?.devicesWithLive ?? deviceView?.devices ?? [];
   const additionalReachableDevices = liveView?.additionalReachableDevices ?? [];
+  const discovery = deviceView?.deviceDiscoveryErrors.length ? { deviceDiscoveryErrors: deviceView.deviceDiscoveryErrors } : {};
   if (expectLive) {
     return emitExpectLive(
       adapter,
@@ -199,15 +200,16 @@ async function handleDoctor({ options }) {
       devices,
       additionalReachableDevices,
       json,
-      printReady
+      printReady,
+      discovery
     );
   }
   const doctorUserAction = doctorResult.checks.find(
     (check) => check.required && check.status === "fail" && check.userAction
   )?.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
   const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
-  const next = doctorError?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
-  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
+  const next = doctorError?.userAction ?? discovery.deviceDiscoveryErrors?.[0]?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...discovery, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -298,7 +300,7 @@ function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
   for (const reason of runtime?.reasons ?? []) console.error(`  ${out("dim", reason)}`);
   console.error(`  Next: ${runtime?.nextAction ?? getAdapterSurface(adapter).hints.runtimeProbeRecovery(target)}`);
 }
-function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json, printReady) {
+function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json, printReady, discovery) {
   const live = runtime?.decision === "ready";
   if (printReady) {
     if (live) {
@@ -316,7 +318,7 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
   if (json) {
     const userAction = runtime?.nextAction ?? getAdapterSurface(adapter).hints.runtimeProbeRecovery(target);
     const error = live ? void 0 : { code: "RUNTIME_NOT_LIVE", message: `${adapter} runtime is not live`, userAction };
-    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices, ...error ? { error } : {} }, null, 2));
+    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices, ...discovery, ...error ? { error } : {} }, null, 2));
     return live ? EXIT.ok : EXIT.runtime;
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });

package/dist/commands/fixtures.js

@@ -328,7 +328,7 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
   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", "--launch-only"];
+  const args = ["--target", target, "--launch-existing-dist", "--launch-only", "--reset-profile"];
   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 },

package/dist/commands/launch/index.js

@@ -310,6 +310,16 @@ async function handleLaunchLocked(argv, stream) {
       exitCode: EXIT.infra
     });
   }
+  if (adapter === "extension" && attempt.output.includes("EVM_RPC_EXECUTION_FAILED:")) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "EVM_RPC_EXECUTION_FAILED",
+      message: "Background RPC fetch failed during JavaScript execution; this does not establish an Infura authentication or connectivity failure.",
+      recoverable: false,
+      userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+      exitCode: EXIT.runtime,
+      originalError: attempt.output.trim() || void 0
+    });
+  }
   if (adapter === "extension" && extensionEvmRpcUnreachable(attempt.output)) {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "EVM_RPC_UNREACHABLE",

package/dist/commands/manifest.js

@@ -358,10 +358,11 @@ function renderHumanActionCatalog(actions, options) {
     for (const entry of entries) {
       const fieldNames = humanFieldNames(entry);
       const fields = fieldNames.length ? ` ${out("dim", `fields=${fieldNames.join(",")}`)}` : "";
+      const cases = entry.result_cases?.length ? ` ${out("dim", `cases=${entry.result_cases.join(",")}`)}` : "";
       const description = entry.description ? ` ${out("comment", `\u2014 ${entry.description}`)}` : "";
       const source = ` ${out("dim", `[${entry.source}]`)}`;
       const risk = entry.capabilities.length ? ` ${out("dim", `risk=${entry.capabilities.join(",")}`)}` : "";
-      lines.push(`  ${out("cmd", options.displayName?.(entry) ?? entry.name)}${source}${fields}${risk}${description}`);
+      lines.push(`  ${out("cmd", options.displayName?.(entry) ?? entry.name)}${source}${fields}${cases}${risk}${description}`);
     }
   }
   return lines.join("\n");
@@ -519,6 +520,7 @@ function describeManifestAction(name, kind, metadata, source) {
     fields: properties,
     schema,
     examples: record.examples,
+    ...Array.isArray(record.result_cases) ? { result_cases: record.result_cases.filter((value) => typeof value === "string") } : {},
     source: source?.name ?? (kind === "official" ? "official" : "metamask"),
     sourceTier: source?.tier ?? (kind === "official" ? "official" : "canonical"),
     sourceManifest: source?.manifestPath ?? "",

package/dist/commands/mobile-device-view.js

@@ -4,10 +4,12 @@ import { listConnectedDevices } from "../devices.js";
 import { renderDeviceList, scopedDevices } from "./device-target.js";
 import { probeMobileLiveState } from "./status-probe.js";
 function mobileDeviceView(allDevices) {
-  const allConnectedDevices = listConnectedDevices();
+  const deviceDiscoveryErrors = [];
+  const allConnectedDevices = listConnectedDevices(void 0, deviceDiscoveryErrors);
   return {
     allConnectedDevices,
-    devices: scopedDevices(allConnectedDevices, allDevices)
+    devices: scopedDevices(allConnectedDevices, allDevices),
+    deviceDiscoveryErrors
   };
 }
 async function mobileDeviceLiveView(target, view) {
@@ -39,7 +41,15 @@ function detectAdditionalReachableDevices(scoped, allConnected, liveMap) {
   }).filter((device) => device !== null);
 }
 function renderMobileDeviceList(view, out) {
-  renderDeviceList(view.devices, out);
+  if (view.devices.length === 0 && view.deviceDiscoveryErrors.length > 0) {
+    console.log(`${out("label", "devices:")} ${out("warn", "discovery incomplete")}`);
+  } else {
+    renderDeviceList(view.devices, out);
+  }
+  for (const error of view.deviceDiscoveryErrors) {
+    console.log(`${out("warn", error.message)}
+  Next: ${error.userAction}`);
+  }
 }
 function renderAdditionalReachableDevices(devices, out) {
   console.log(`${out("warn", "additional reachable target:")} ${devices.length} device(s) answered on this Metro but are not the active target for this command`);

package/dist/commands/parse-args.js

@@ -24,6 +24,8 @@ function parseArgs(argv, command) {
     "launchExistingDist",
     "startWatch",
     "buildLavamoat",
+    "resetProfile",
+    "preserveProfile",
     "record",
     "plan",
     "list",