@deeeed/metamask-harness 0.73.0 → 0.75.0

package/dist/adapters/mobile/launch.js

@@ -0,0 +1,192 @@
+import fs from "node:fs";
+import { applyDeviceTargeting } from "../../commands/device-target.js";
+import { launchMobile } from "../../commands/launch/mobile.js";
+import { shellQuote } from "../../commands/launch/quote.js";
+import { EXIT, str, writeInteractiveProgress } from "../../commands/shared.js";
+import { RECOVERY_CODE } from "../../heal-bounds.js";
+import { recipeRuntimePath } from "../../paths.js";
+function mobileProvisioningBlocked(output) {
+  return /open-device: configured iOS simulator '.+' does not exist|open-device: no MetaMask bundle found|fast mode requires an installed (?:iOS dev client|Android dev client)/u.test(output);
+}
+function missingConfiguredIosSimulator(output) {
+  return /open-device: configured iOS simulator '([^']+)' does not exist/u.exec(output)?.[1];
+}
+function ambiguousConfiguredIosSimulator(output) {
+  return /open-device: iOS simulator target ("[^"]+") is ambiguous/u.exec(output)?.[1];
+}
+function mobileBridgeTargetMissing(output) {
+  return /no bridge target matched|wait-for-bridge: readiness deadline expired/iu.test(output);
+}
+function mobileProvisionCommand(target, mobileTarget) {
+  const platform = mobileTarget === "android" ? "android" : "ios";
+  const device = platform === "ios" ? process.env.SIM_UDID || process.env.IOS_SIMULATOR : process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || process.env.ANDROID_DEVICE;
+  const parts = ["mm-harness", "provision", "runway", platform, "--adapter", "mobile", "--target", shellQuote(target)];
+  if (device) parts.push("--device", shellQuote(device));
+  return parts.join(" ");
+}
+function isIosSimulatorUdid(value) {
+  return /^[0-9A-Fa-f-]{36}$/u.test(value);
+}
+function launchDeviceLabel(mobileTarget) {
+  if (mobileTarget === "android") {
+    return process.env.ANDROID_TARGET_DEVICE_NAME || process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || process.env.ANDROID_DEVICE || "android device";
+  }
+  if (mobileTarget === "ios") {
+    return process.env.IOS_SIMULATOR || process.env.SIM_UDID || "iOS simulator";
+  }
+  return process.env.IOS_SIMULATOR || process.env.ADB_SERIAL || "booted device";
+}
+function metroLaunchEvidence(target) {
+  const evidencePath = recipeRuntimePath(target, "metro-generation.json");
+  let descriptor;
+  try {
+    descriptor = fs.openSync(evidencePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > 256 * 1024) return void 0;
+    return JSON.parse(fs.readFileSync(descriptor, "utf8"));
+  } catch {
+    return void 0;
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+  }
+}
+const mobileLaunchProfile = {
+  refuseFlags({ mobileTarget }) {
+    if (!mobileTarget) {
+      return { message: "target is required for mobile.", userAction: "mm-harness launch ios   or   mm-harness launch android" };
+    }
+    return void 0;
+  },
+  applyEnv({ adapter, options, mobileTarget, target }) {
+    const device = str(options, "device");
+    if (!device && mobileTarget !== "ios" && mobileTarget !== "android") return void 0;
+    const targetingOptions = {
+      ...options,
+      ...mobileTarget ? { platform: mobileTarget } : {}
+    };
+    const result = applyDeviceTargeting("launch", adapter, targetingOptions, { gate: false, rerun: "" });
+    if ("code" in result) {
+      if (mobileTarget === "ios" && result.code === "DEVICE_NOT_FOUND") {
+        process.env.IOS_SIMULATOR = device;
+        process.env.SIM_UDID = isIosSimulatorUdid(device) ? device : "";
+        process.env.ADB_SERIAL = "";
+        process.env.ANDROID_SERIAL = "";
+        process.env.ANDROID_DEVICE = "";
+        process.env.ANDROID_TARGET_DEVICE_NAME = "";
+      } else {
+        return result;
+      }
+    }
+    if (mobileTarget === "android" && device && !process.env.ADB_SERIAL && !process.env.ANDROID_SERIAL) {
+      return {
+        ok: false,
+        code: "DEVICE_WRONG_PLATFORM",
+        message: `--device ${device} did not resolve to an Android device for launch android.`,
+        userAction: `mm-harness status --target ${shellQuote(target)} --all-devices --json`
+      };
+    }
+    if (mobileTarget === "ios" && device && !process.env.IOS_SIMULATOR) {
+      return {
+        ok: false,
+        code: "DEVICE_WRONG_PLATFORM",
+        message: `--device ${device} did not resolve to an iOS simulator for launch ios.`,
+        userAction: `mm-harness status --target ${shellQuote(target)} --all-devices --json`
+      };
+    }
+    return void 0;
+  },
+  start({ options, mobileTarget, machine, tier, wantClearMetro }) {
+    const device = str(options, "device") ?? (mobileTarget === "android" ? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL : process.env.IOS_SIMULATOR ?? process.env.SIM_UDID) ?? "configured device";
+    const watcherPort = str(options, "watcherPort") ?? process.env.WATCHER_PORT ?? "auto";
+    writeInteractiveProgress(
+      machine,
+      `\u2192 mobile launch \u2014 ${mobileTarget} \xB7 ${tier === "build" ? "native build" : "quick readiness"} \xB7 ${device} \xB7 Metro ${watcherPort === "auto" ? "auto" : `:${watcherPort}`}${wantClearMetro ? " \xB7 clear cache" : ""}`
+    );
+  },
+  nativeInputs: ["ios", "android", "package.json", "yarn.lock"],
+  rebuildCommand: ({ mobileTarget }) => `mm-harness launch ${mobileTarget} --build`,
+  compose: ({ target, mobileTarget, machine, remoteFlagRequest }, tier, restartApp, clearMetro) => launchMobile(target, mobileTarget, tier, machine, restartApp, clearMetro, remoteFlagRequest?.flags),
+  classify(_launch, output) {
+    if (output.includes("open-device: Android device is locked.")) {
+      return {
+        code: "MOBILE_DEVICE_LOCKED",
+        message: "the selected Android device is locked.",
+        recoverable: false,
+        userAction: "Unlock the selected Android device, then retry the launch.",
+        exitCode: EXIT.runtime,
+        originalError: output.trim()
+      };
+    }
+    if (/open-device: Android (?:lock state unavailable|display preparation failed)\./u.test(output)) {
+      return {
+        code: "MOBILE_DEVICE_UI_UNAVAILABLE",
+        message: "the selected Android display could not be prepared.",
+        recoverable: false,
+        userAction: "Check adb access and the selected device screen, then retry the launch.",
+        exitCode: EXIT.runtime,
+        originalError: output.trim()
+      };
+    }
+    return void 0;
+  },
+  async beforeHeal(launch, attempt, state) {
+    const { target, mobileTarget, tier } = launch;
+    const output = attempt.output;
+    const missingIosSimulator = missingConfiguredIosSimulator(output);
+    const ambiguousIosSimulator = ambiguousConfiguredIosSimulator(output);
+    if (ambiguousIosSimulator) {
+      return launch.fail(state, {
+        code: "MOBILE_DEVICE_AMBIGUOUS",
+        message: `more than one iOS simulator matches ${ambiguousIosSimulator}.`,
+        recoverable: false,
+        userAction: `mm-harness status --adapter mobile --target ${shellQuote(target)} --all-devices --json`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      });
+    }
+    if (missingIosSimulator && isIosSimulatorUdid(missingIosSimulator)) {
+      return launch.fail(state, {
+        code: "MOBILE_DEVICE_NOT_FOUND",
+        message: `the configured iOS simulator ${missingIosSimulator} no longer exists.`,
+        recoverable: false,
+        userAction: `mm-harness status --adapter mobile --target ${shellQuote(target)} --all-devices --json`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      });
+    }
+    if (mobileProvisioningBlocked(output)) {
+      return launch.fail(state, {
+        code: "MOBILE_PROVISION_REQUIRED",
+        message: `mobile ${mobileTarget ?? "runtime"} is not provisioned for this slot.`,
+        recoverable: false,
+        userAction: mobileProvisionCommand(target, mobileTarget),
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      });
+    }
+    if (tier === "build" && /open-device: (?:Android|iOS) native build failed/u.test(output)) {
+      return launch.fail(state, {
+        code: "MOBILE_NATIVE_BUILD_FAILED",
+        message: "the selected Mobile native build failed; refusing to repeat the expensive build as a Metro recovery.",
+        recoverable: false,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      });
+    }
+    return void 0;
+  },
+  recovery(_launch, output) {
+    const restartApp = mobileBridgeTargetMissing(output);
+    return { code: restartApp ? "mobile.app-restarted" : RECOVERY_CODE.mobile, restartApp };
+  },
+  // Mobile proved its set inside launchMobile (null: nothing requested and no
+  // runtime answered).
+  provenFlags: (_launch, requested, proven) => ({ flags: proven === void 0 ? requested : proven }),
+  verifyArgs: ({ mobileTarget }) => mobileTarget ? ["--platform", mobileTarget] : [],
+  platformLabel: ({ mobileTarget }) => mobileTarget ?? null,
+  deviceLabel: ({ mobileTarget }) => launchDeviceLabel(mobileTarget),
+  evidence: metroLaunchEvidence
+};
+export {
+  mobileLaunchProfile
+};

package/dist/adapters/mobile/lifecycle.js

@@ -0,0 +1,300 @@
+import { execFileSync } from "node:child_process";
+import {
+  bridgeCommand,
+  MOBILE_BRIDGE_ERROR_CODES
+} from "../../../library/actions/mobile/platform/bridge.mjs";
+import { resolveMobileToolPath } from "../../../library/actions/mobile/platform/tool-paths.mjs";
+import {
+  MOBILE_LIFECYCLE_DEADLINE_FIELD,
+  MOBILE_LIFECYCLE_PREPARED
+} from "../../app-lifecycle.js";
+import {
+  mobileSourceFingerprint,
+  recordMobileSourceBaseline
+} from "./source-freshness.js";
+function mobileSourceAwareLifecycleAdapters(lifecycle, readinessProbe = probeMobileLifecycleRuntime, sourceFreshness = {
+  fingerprint: mobileSourceFingerprint,
+  record: recordMobileSourceBaseline
+}, processIdentity = {
+  readIosPid: readIosAppPid,
+  readAndroidPid: readAndroidAppPid
+}, runtimeMarker = readMobileLifecycleRuntimeIdentity) {
+  return lifecycle.map((entry) => ({
+    ...entry,
+    async execute(node, context) {
+      const command = node.command ?? node.event ?? node.state;
+      const opaqueRuntime = context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
+      const requiresProcessContinuity = command !== "restart" && node.require_process_continuity === true;
+      if (opaqueRuntime && !requiresProcessContinuity) {
+        return entry.execute(node, context);
+      }
+      const reloadsSource = !opaqueRuntime && (command === "launch" || command === "foreground" || command === "restart");
+      const recordsSource = !opaqueRuntime && command === "restart";
+      const androidLifecycle = isAndroidLifecycle(node, context.env ?? {});
+      const checksIosContinuity = command === "foreground" && !androidLifecycle;
+      const checksRequiredContinuity = requiresProcessContinuity;
+      const recordsProcessIdentity = checksIosContinuity || checksRequiredContinuity;
+      const readProcessId = androidLifecycle ? processIdentity.readAndroidPid ?? readAndroidAppPid : processIdentity.readIosPid;
+      const processBefore = recordsProcessIdentity ? readProcessId(node, context) : void 0;
+      const fingerprint = recordsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
+      const previousRuntimeIdentity = recordsSource ? await runtimeMarker(node, context) : void 0;
+      const androidRestart = command === "restart" && androidLifecycle;
+      const initialResult = await entry.execute(node, context);
+      const readinessDeadline = reloadsSource ? mobileLifecycleReadinessDeadline(command, node) : void 0;
+      let result = initialResult;
+      let runtimeReady = false;
+      if (androidRestart) {
+        try {
+          const remainingMs = Math.max(
+            1,
+            (readinessDeadline ?? Date.now()) - Date.now()
+          );
+          const handoffDeadline = Math.min(
+            readinessDeadline ?? Number.POSITIVE_INFINITY,
+            Date.now() + Math.min(1e4, Math.max(1, remainingMs / 2))
+          );
+          await readinessProbe(
+            node,
+            context,
+            previousRuntimeIdentity,
+            handoffDeadline
+          );
+          runtimeReady = true;
+        } catch (error) {
+          if (readinessDeadline !== void 0 && Date.now() >= readinessDeadline) {
+            throw error;
+          }
+          const foregroundTimeoutMs = Math.max(
+            1,
+            (readinessDeadline ?? Date.now() + 1) - Date.now()
+          );
+          const foregroundResult = await entry.execute(
+            {
+              ...node,
+              command: "foreground",
+              settle_ms: 0,
+              timeout_ms: foregroundTimeoutMs,
+              [MOBILE_LIFECYCLE_DEADLINE_FIELD]: readinessDeadline,
+              [MOBILE_LIFECYCLE_PREPARED]: true
+            },
+            context
+          );
+          result = mergeAndroidRestartResults(initialResult, foregroundResult);
+        }
+      }
+      if (reloadsSource && !runtimeReady) {
+        if (readinessDeadline !== void 0 && Date.now() >= readinessDeadline) {
+          throw new Error(
+            `Mobile lifecycle ${String(command)} exhausted its runtime readiness deadline before recovery completed.`
+          );
+        }
+        await readinessProbe(
+          node,
+          context,
+          previousRuntimeIdentity,
+          readinessDeadline
+        );
+      }
+      if (recordsProcessIdentity) {
+        const processAfter = readProcessId(node, context);
+        const processPreserved = processBefore !== null && processBefore === processAfter;
+        const actualTransition = processPreserved ? command === "background" ? "background_same_process" : "foreground_resume" : processAfter !== null ? "cold_relaunch" : "unknown";
+        const processContinuity = processPreserved ? "preserved" : processAfter === null ? "unknown" : "changed";
+        const resultRecord = asRecord(result);
+        result = {
+          ...resultRecord,
+          output: {
+            ...asRecord(resultRecord.output),
+            actualTransition,
+            processContinuity,
+            processBefore,
+            processAfter
+          }
+        };
+        if (checksRequiredContinuity && !processPreserved) {
+          const platform = androidLifecycle ? "Android" : "iOS";
+          throw new Error(
+            `${platform} ${String(command)} did not prove app-process continuity (actualTransition=${actualTransition}, before=${String(processBefore)}, after=${String(processAfter)}); this lifecycle sample cannot be classified as a same-process reconnect.`
+          );
+        }
+      }
+      if (fingerprint !== void 0 && !sourceFreshness.record(context.projectRoot, fingerprint)) {
+        throw new Error(
+          "Mobile source changed while the app was reloading; the loaded-source baseline was not recorded. Next: retry app.lifecycle restart."
+        );
+      }
+      return result;
+    }
+  }));
+}
+function readAndroidAppPid(node, context) {
+  const env = context.env ?? {};
+  const device = node.adb_serial ?? node.android_device ?? node.device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
+  const packageId = node.package_id ?? node.packageName ?? node.app_id ?? env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask";
+  if (typeof device !== "string" || typeof packageId !== "string") return null;
+  try {
+    const adb = resolveMobileToolPath("adb", { required: true });
+    const output = execFileSync(
+      adb,
+      ["-s", device, "shell", "pidof", packageId],
+      { encoding: "utf8", timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }
+    );
+    const pid = Number.parseInt(output.trim().split(/\s+/u)[0] ?? "", 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function readIosAppPid(node, context) {
+  const env = context.env ?? {};
+  const device = node.simulator ?? node.ios_simulator ?? env.SIM_UDID ?? env.IOS_SIMULATOR ?? process.env.SIM_UDID ?? process.env.IOS_SIMULATOR;
+  const bundleId = node.bundle_id ?? node.bundleId ?? env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID ?? "io.metamask.MetaMask";
+  if (typeof device !== "string" || typeof bundleId !== "string") return null;
+  try {
+    const output = execFileSync(
+      "xcrun",
+      ["simctl", "spawn", device, "launchctl", "list"],
+      { encoding: "utf8", timeout: 5e3 }
+    );
+    const labelPrefix = `UIKitApplication:${bundleId}[`;
+    const line = output.split("\n").find((candidate) => candidate.includes(labelPrefix));
+    if (!line) return null;
+    const pid = Number.parseInt(line.trim().split(/\s+/u)[0] ?? "", 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function isAndroidLifecycle(node, env) {
+  const platform = node.platform ?? env.PLATFORM ?? process.env.PLATFORM;
+  if (platform === "android") return true;
+  if (platform === "ios") return false;
+  return Boolean(
+    node.adb_serial ?? node.android_device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL
+  );
+}
+function mergeAndroidRestartResults(initialResult, foregroundResult) {
+  const initial = asRecord(initialResult);
+  const foreground = asRecord(foregroundResult);
+  const initialOutput = asRecord(initial.output);
+  const foregroundOutput = asRecord(foreground.output);
+  return {
+    ...initial,
+    output: {
+      ...initialOutput,
+      command: "restart",
+      calls: [
+        ...Array.isArray(initialOutput.calls) ? initialOutput.calls : [],
+        ...Array.isArray(foregroundOutput.calls) ? foregroundOutput.calls : []
+      ],
+      settleMs: foregroundOutput.settleMs ?? initialOutput.settleMs ?? 0,
+      foregroundEnsured: true
+    }
+  };
+}
+async function probeMobileLifecycleRuntime(node, context, previousRuntimeIdentity, deadlineMs) {
+  const command = node.command ?? node.event ?? node.state;
+  const timeoutMs = resolveMobileLifecycleReadinessTimeout(
+    command,
+    node.runtime_ready_timeout_ms
+  );
+  const startedAt = Date.now();
+  const deadline = deadlineMs ?? startedAt + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const status = await bridgeCommand(
+        {
+          action: "app.lifecycle",
+          node: {
+            ...node,
+            cdp_timeout_ms: Math.min(8e3, Math.max(1, deadline - Date.now()))
+          },
+          context
+        },
+        ["status-selected"]
+      );
+      if (status?.agenticPresent === true && status.route && (!previousRuntimeIdentity || status.runtimeIdentity !== previousRuntimeIdentity)) {
+        return status;
+      }
+      lastError = new Error(
+        previousRuntimeIdentity && status?.runtimeIdentity === previousRuntimeIdentity ? "retiring Mobile runtime is still selected" : "selected Mobile runtime is not ready"
+      );
+    } catch (error) {
+      lastError = error;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs > 0) {
+      await new Promise(
+        (resolve) => setTimeout(resolve, Math.min(1e3, remainingMs))
+      );
+    }
+  }
+  throw new Error(
+    `Mobile lifecycle ${String(command)} did not expose a usable pinned __AGENTIC__ runtime within ${Math.max(0, deadline - startedAt)}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+  );
+}
+async function readMobileLifecycleRuntimeIdentity(node, context) {
+  const deadline = Date.now() + 5e3;
+  let lastError;
+  do {
+    try {
+      const status = await bridgeCommand(
+        {
+          action: "app.lifecycle",
+          node: {
+            ...node,
+            cdp_timeout_ms: Math.min(1e3, Math.max(1, deadline - Date.now()))
+          },
+          context
+        },
+        ["target-identity-selected"]
+      );
+      if (typeof status?.runtimeIdentity === "string") {
+        return status.runtimeIdentity;
+      }
+      lastError = new Error("selected Mobile runtime has no stable identity");
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === MOBILE_BRIDGE_ERROR_CODES.NO_TARGET) {
+        return void 0;
+      }
+      lastError = error;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      break;
+    }
+    await new Promise(
+      (resolve) => setTimeout(resolve, Math.min(250, remainingMs))
+    );
+  } while (Date.now() < deadline);
+  throw new Error(
+    `Mobile lifecycle restart could not identify the retiring runtime: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+  );
+}
+function mobileLifecycleReadinessDeadline(command, node) {
+  const timeoutMs = resolveMobileLifecycleReadinessTimeout(
+    command,
+    node.runtime_ready_timeout_ms
+  );
+  return Date.now() + timeoutMs;
+}
+function resolveMobileLifecycleReadinessTimeout(command, value) {
+  if (value === void 0) {
+    return command === "launch" || command === "restart" || command === "foreground" ? 6e4 : 3e4;
+  }
+  const timeout = Number(value);
+  if (!Number.isInteger(timeout) || timeout < 1e3 || timeout > 12e4) {
+    throw new Error(
+      "app.lifecycle.runtime_ready_timeout_ms must be an integer from 1000 through 120000."
+    );
+  }
+  return timeout;
+}
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  mobileSourceAwareLifecycleAdapters,
+  resolveMobileLifecycleReadinessTimeout
+};

package/dist/adapters/mobile/run.js

@@ -0,0 +1,156 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { isRecord } from "../../commands/parse-args.js";
+import { runnerDir } from "../../paths.js";
+import { devicePlatformFromEnv } from "../performance/device-platform.js";
+import {
+  IOS_SIMULATOR_RECORDING_TARGET_PREFIX,
+  resolveAndroidDeviceSerial,
+  resolveMobileIosSimulatorName
+} from "../../recording-target.js";
+import { requireCurrentMobileReleaseArtifactState } from "./release-artifact-state.js";
+const EXPLICIT_DEVICE_KEYS = [
+  "PLATFORM",
+  "MM_HARNESS_EXPLICIT_PLATFORM",
+  "IOS_SIMULATOR",
+  "SIM_UDID",
+  "ADB_SERIAL",
+  "ANDROID_SERIAL",
+  "ANDROID_DEVICE",
+  "ANDROID_TARGET_DEVICE_NAME"
+];
+const mobileRun = {
+  pinnedEnv() {
+    if (!process.env.MM_HARNESS_EXPLICIT_PLATFORM) return void 0;
+    return Object.fromEntries(EXPLICIT_DEVICE_KEYS.map((key) => [key, process.env[key]]));
+  },
+  envKeys: ["METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME", "ANDROID_PACKAGE_ID", "ADB_SERIAL", "ANDROID_SERIAL"],
+  activateEnv(projectRoot) {
+    const state = requireCurrentMobileReleaseArtifactState(projectRoot);
+    if (!state) return;
+    const selected = process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
+    if (selected && selected !== state.deviceSerial) {
+      throw new Error(
+        `The Mobile release artifact is installed on ${state.deviceSerial}, not ${selected}. Next: rerun runtime-launch for ${selected}.`
+      );
+    }
+    process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME = "1";
+    process.env.ANDROID_PACKAGE_ID = state.packageId;
+    process.env.ADB_SERIAL = state.deviceSerial;
+    process.env.ANDROID_SERIAL = state.deviceSerial;
+  },
+  childEnv: (base) => ({
+    ...base,
+    WATCHER_PORT: process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
+    METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
+    IOS_SIMULATOR: process.env.IOS_SIMULATOR,
+    SIM_UDID: process.env.SIM_UDID,
+    ANDROID_DEVICE: process.env.ANDROID_DEVICE,
+    ANDROID_TARGET_DEVICE_NAME: process.env.ANDROID_TARGET_DEVICE_NAME,
+    ADB_SERIAL: process.env.ADB_SERIAL,
+    ANDROID_SERIAL: process.env.ANDROID_SERIAL,
+    ANDROID_PACKAGE_ID: process.env.ANDROID_PACKAGE_ID,
+    METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME: process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME
+  }),
+  // An installed release artifact is opaque: no harness HUD inside it.
+  autoHud: () => process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME !== "1",
+  // Always clear a HUD step the engine left on-device (a failed run strands
+  // the FAIL banner). Best-effort — never masks the run's real outcome.
+  async teardown(projectRoot, env) {
+    const { hideMobileHudOnTeardown } = await import("./ui.js");
+    await hideMobileHudOnTeardown(projectRoot, env);
+  },
+  // A release artifact is checked before the overlay install; the loaded
+  // source only matters for a development build the caller did not restart.
+  runtimeCheck({ target, heal, state, json, appRestartAuthored }) {
+    if (requireCurrentMobileReleaseArtifactState(target) !== null || appRestartAuthored) return void 0;
+    return async () => {
+      const { ensureMobileProofRuntime } = await import("../../commands/run-engine.js");
+      return ensureMobileProofRuntime(target, heal, state, json);
+    };
+  }
+};
+const mobileRecording = {
+  target: (context) => resolveMobileRecordingTarget(context),
+  // An Android device records through the mirror, with screenrecord as the
+  // fallback; otherwise the selected iOS simulator records.
+  async videoRecorder() {
+    const androidSerial = resolveAndroidDeviceSerial();
+    const iosSimulator = androidSerial ? void 0 : resolveMobileIosSimulatorName();
+    if (!androidSerial && !iosSimulator) return void 0;
+    const { createAndroidVideoRecorder, createIosSimulatorVideoRecorder } = await import("./video-recorder.js");
+    if (androidSerial) {
+      const { createAndroidMirrorVideoRecorder } = await import("@farmslot/recipe-harness");
+      return createAndroidMirrorVideoRecorder({ serial: androidSerial, fallback: createAndroidVideoRecorder(androidSerial) });
+    }
+    return createIosSimulatorVideoRecorder(iosSimulator);
+  }
+};
+async function resolveMobileRecordingTarget(context) {
+  const platform = (context.env.PLATFORM ?? process.env.PLATFORM ?? "ios").trim().toLowerCase();
+  const androidSerial = resolveAndroidDeviceSerial(context.env);
+  if (platform === "android" || androidSerial) {
+    if (!androidSerial) {
+      throw new Error(
+        "Could not resolve an Android device for --record-video. Set ADB_SERIAL or pass --device to mm-harness run."
+      );
+    }
+    return {
+      kind: "android-device",
+      serial: androidSerial
+    };
+  }
+  const simulator = resolveMobileIosSimulatorName(context.env);
+  if (!simulator) {
+    throw new Error(
+      "Could not resolve an iOS simulator name for --record-video. Set IOS_SIMULATOR or pass --simulator to the recipe hook."
+    );
+  }
+  return {
+    kind: "window-id",
+    windowId: `${IOS_SIMULATOR_RECORDING_TARGET_PREFIX}${simulator}`
+  };
+}
+const mobileDiagnostics = {
+  issueBuffer: {
+    arm(projectRoot) {
+      if (process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") return false;
+      if (!runMobileIssueCommand(projectRoot, "issues-arm")) return false;
+      return runMobileIssueCommand(projectRoot, "issues-collect") !== null;
+    },
+    collect(projectRoot) {
+      const result = runMobileIssueCommand(projectRoot, "issues-collect");
+      return isRecord(result) && Array.isArray(result.entries) ? result.entries : null;
+    }
+  }
+};
+const mobileObservation = {
+  network: {
+    backend: async (target, env) => (await import("../../network-observation.js")).createMobileNetworkBackend(target, env)
+  },
+  performance: {
+    backend: async (target, env) => (await import("./performance-observer.js")).createMobilePerformanceBackend(target, env),
+    platform: (env) => devicePlatformFromEnv(env)
+  }
+};
+function runMobileIssueCommand(projectRoot, command) {
+  const bridge = path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+  const result = spawnSync(process.execPath, [bridge, command], {
+    cwd: projectRoot,
+    env: { ...process.env, APP_ROOT: projectRoot, CDP_TIMEOUT: "5000" },
+    encoding: "utf8",
+    timeout: 1e4
+  });
+  if (result.status !== 0) return null;
+  try {
+    return JSON.parse(result.stdout.trim());
+  } catch {
+    return null;
+  }
+}
+export {
+  mobileDiagnostics,
+  mobileObservation,
+  mobileRecording,
+  mobileRun
+};

package/dist/adapters/mobile/runtime-identity.js

@@ -0,0 +1,34 @@
+import { readAndroidNativeRuntimeIdentity } from "./release-artifact.js";
+import { readMobileReleaseArtifactState } from "./release-artifact-state.js";
+function withMobileNativeRuntimeIdentity(adapters, identity = {
+  state: readMobileReleaseArtifactState,
+  read: readAndroidNativeRuntimeIdentity
+}) {
+  return adapters.map((entry) => ({
+    ...entry,
+    async execute(node, context) {
+      const state = identity.state(context.projectRoot);
+      if (!state) {
+        if (context.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") {
+          throw new Error("Mobile release-artifact actions require current trusted runtime state. Next: rerun runtime-launch with the exact artifact.");
+        }
+        return entry.execute(node, context);
+      }
+      identity.read(state);
+      const result = await entry.execute(node, context);
+      const nativeRuntimeIdentity = identity.read(state);
+      const output = result.output && typeof result.output === "object" && !Array.isArray(result.output) ? result.output : { result: result.output };
+      return {
+        ...result,
+        output: {
+          ...output,
+          nativeRuntimeIdentity,
+          runtimeSessionId: nativeRuntimeIdentity.runtimeSessionId
+        }
+      };
+    }
+  }));
+}
+export {
+  withMobileNativeRuntimeIdentity
+};