@deeeed/metamask-harness 0.47.4 → 0.48.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## 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

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/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",

package/dist/commands/run-engine.js

@@ -582,6 +582,11 @@ async function validateRecipeAdapterAware(adapter, recipe, manifest, librarySour
   );
   const findings = [
     ...withManifest.findings,
+    ...withManifest.status === "valid" && params ? protocol.validateRecipeWithManifest(
+      resolveMetaMaskParameterValue(recipe, params),
+      manifest,
+      validationOptions
+    ).findings : [],
     ...validateMetaMaskActionInputs(recipe, adapter, params)
   ];
   if (withManifest.status === "valid" && isRecord(recipe) && libraryResolution) {
@@ -626,6 +631,11 @@ async function validateRecipeAdapterAware(adapter, recipe, manifest, librarySour
             supplied,
             isRecord(dependency.document) ? dependency.document.paramsSchema : void 0
           );
+          findings.push(...protocol.validateRecipeWithManifest(
+            resolveMetaMaskParameterValue(dependency.document, childParams),
+            manifest,
+            validationOptions
+          ).findings);
           findings.push(...validateMetaMaskActionInputs(dependency.document, adapter, childParams));
           validateDependencyInstances(dependency.document, childParams);
         }
@@ -690,9 +700,24 @@ async function listRunnableRecipes(adapter, librarySources) {
   const protocol = await importRecipeProtocol();
   const { manifest } = await resolveActionManifest(adapter, void 0, sources);
   const externalRecipeIds = new Set(resolution.recipes.keys());
-  return [...resolution.recipes.values()].filter((recipe) => protocol.validateRecipeWithManifest(recipe.document, manifest, {
+  const validRefs = new Set([...resolution.recipes.values()].filter((recipe) => protocol.validateRecipeWithManifest(recipe.document, manifest, {
     externalRecipeIds
-  }).status === "valid").map(
+  }).status === "valid").map((recipe) => recipe.ref));
+  return [...resolution.recipes.values()].filter((recipe) => {
+    if (!validRefs.has(recipe.ref)) return false;
+    try {
+      const dependencies = harness.resolveRecipeDependencies({
+        rootRef: recipe.ref,
+        root: recipe.document,
+        rootSource: recipe.provenance,
+        recipes: resolution.recipes
+      });
+      return [...dependencies.recipes.keys()].every((ref) => validRefs.has(ref));
+    } catch (error) {
+      if (error instanceof harness.RecipeResolutionError) return false;
+      throw error;
+    }
+  }).map(
     (recipe) => recipeSummary(recipe.ref, adapter, recipe.document, recipe)
   ).sort((left, right) => left.name.localeCompare(right.name));
 }
@@ -1371,14 +1396,14 @@ function readRunFailureText(result) {
 }
 async function executeWithHealBounds(exec, target, state) {
   const result = await exec();
-  if (result.status === "pass") return { result, violation: null };
+  if (result.status === "pass" || result.status === "unknown") return { result, violation: null };
   return {
     result,
     violation: checkHealBounds(target, readRunFailureText(result), state)
   };
 }
 function emitHealViolation(json, command, result, violation, state, adapter) {
-  const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? 'create temp/recipe/runtime/wallet-fixture.json, or add "account": "<0x\u2026>" to the node block in the recipe' : violation.userAction ?? `inspect ${shellQuoteArg(result.summaryPath)} and ${shellQuoteArg(result.tracePath)}; fix the application or recipe failure before retrying`;
+  const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? "for signing, configure a reserved wallet-fixture.json account and pass its non-empty name; an explicit 0x address is supported only by read-only actions" : violation.userAction ?? `inspect ${shellQuoteArg(result.summaryPath)} and ${shellQuoteArg(result.tracePath)}; fix the application or recipe failure before retrying`;
   if (json) {
     console.log(
       JSON.stringify(

package/dist/commands/run.js

@@ -396,7 +396,7 @@ async function handleRunInner({ positional, options }, stream) {
           userAction: failureUserAction
         });
       }
-      stream.complete(result.status === "pass" ? "pass" : "fail", exitCode, {
+      stream.complete(result.status, exitCode, {
         adapter,
         reportPath: report.path,
         summaryPath: result.summaryPath,

package/dist/commands/runtime-launch.js

@@ -34,15 +34,20 @@ async function handleRuntimeLaunch({ options }) {
   --device <serial>          Explicit Android device serial
   --cdp-port <port>          Extension CDP port
   --chrome-user-data-dir     Isolated Chrome profile path
+  --reset-profile            Explicitly clear the selected Extension profile
   --artifacts-dir <dir>      Validation evidence directory
   --json                     Machine-readable terminal report
 
   The harness verifies and runs a local artifact but never downloads one. Extension
-  launch resets an isolated profile. Android install requires an explicit serial.`);
+  launch preserves the selected profile unless --reset-profile is requested.
+  Android install requires an explicit serial.`);
     return 0;
   }
   const adapter = adapterOption(options);
   const target = targetPath(options);
+  if (adapter !== "extension" && (optionFlag(options, "resetProfile") || optionFlag(options, "preserveProfile"))) {
+    throw usageError("Profile options apply only to Extension.\nNext: mm-harness runtime-launch --help");
+  }
   const artifactFile = optionString(options, "artifactFile");
   const artifactVersion = optionString(options, "artifactVersion");
   const artifactSha256 = optionString(options, "artifactSha256");
@@ -68,6 +73,9 @@ async function handleRuntimeLaunch({ options }) {
     });
   }
   if (adapter !== "extension") throw new Error("runtime-launch currently applies to the extension adapter.");
+  if (optionFlag(options, "resetProfile") && optionFlag(options, "preserveProfile")) {
+    throw usageError("Choose either --reset-profile or --preserve-profile, not both.\nNext: mm-harness runtime-launch --help");
+  }
   if (artifactBuildId || artifactPackageId || optionString(options, "platform") || optionString(options, "device")) {
     throw usageError("Extension runtime-launch does not accept Android artifact options.");
   }
@@ -119,6 +127,7 @@ async function handleRuntimeLaunch({ options }) {
     );
   }
   if (chromeUserDataDir) command.push("--chrome-user-data-dir", chromeUserDataDir);
+  command.push(optionFlag(options, "resetProfile") ? "--reset-profile" : "--preserve-profile");
   const remoteFlag = optionString(options, "remoteFlag");
   if (remoteFlag) command.push("--remote-flag", remoteFlag);
   if (!fs.existsSync(liveScript)) {

package/dist/commands/status.js

@@ -37,6 +37,8 @@ async function handleStatus({ options }) {
   const next = surface.hints.relaunch;
   const deviceView = adapter === "mobile" ? mobileDeviceView(allDevices) : null;
   const devices = deviceView?.devices ?? [];
+  const discovery = deviceView?.deviceDiscoveryErrors.length ? { deviceDiscoveryErrors: deviceView.deviceDiscoveryErrors } : {};
+  const discoveryNext = discovery.deviceDiscoveryErrors?.[0]?.userAction;
   if (json) {
     const doProbe = !fast && adapter === "mobile" && deviceView !== null && deviceView.allConnectedDevices.length > 0;
     if (doProbe) {
@@ -49,9 +51,10 @@ async function handleStatus({ options }) {
             adapter,
             target,
             devices: liveView.devicesWithLive,
+            ...discovery,
             ...liveView.additionalReachableDevices.length > 0 ? { additionalReachableDevices: liveView.additionalReachableDevices } : {},
             ...liveView.androidPortHints.length > 0 ? { androidPortHints: liveView.androidPortHints } : {},
-            next: nextForLive(next, liveView.liveMap)
+            next: discoveryNext ?? nextForLive(next, liveView.liveMap)
           },
           null,
           2
@@ -67,8 +70,9 @@ async function handleStatus({ options }) {
             adapter,
             target,
             devices,
+            ...discovery,
             ...runtime ? { runtime } : {},
-            next: runtime ? nextForRuntime(surface.hints.launch, surface.hints.relaunch, runtime) : next
+            next: discoveryNext ?? (runtime ? nextForRuntime(surface.hints.launch, surface.hints.relaunch, runtime) : next)
           },
           null,
           2
@@ -85,13 +89,13 @@ async function handleStatus({ options }) {
     if (liveView.additionalReachableDevices.length > 0) renderAdditionalReachableDevices(liveView.additionalReachableDevices, out);
     renderMobileLiveBlock(devices, liveView.liveMap, out);
     renderAndroidPortHints(liveView.androidPortHints, out);
-    console.log(`${out("label", "Next:")} ${out("cmd", nextForLive(next, liveView.liveMap))}`);
+    console.log(`${out("label", "Next:")} ${out("cmd", discoveryNext ?? nextForLive(next, liveView.liveMap))}`);
   } else if (!fast && adapter === "extension") {
     const runtime = await surface.runtimeStatus(target);
     renderRuntimeStatus(runtime, out);
     console.log(`${out("label", "Next:")} ${out("cmd", nextForRuntime(surface.hints.launch, surface.hints.relaunch, runtime))}`);
   } else {
-    console.log(`${out("label", "Next:")} ${out("cmd", next)}`);
+    console.log(`${out("label", "Next:")} ${out("cmd", discoveryNext ?? next)}`);
   }
   return EXIT.ok;
 }