@deeeed/metamask-harness 0.72.0 → 0.74.0

package/dist/commands/launch/index.js

@@ -1,9 +1,4 @@
-import { execFileSync } from "node:child_process";
 import fs from "node:fs";
-import path from "node:path";
-import { color, colorHumanMessage } from "../../cli-color.js";
-import { handleHarness } from "../../harness.js";
-import { recipeRuntimePath, runnerDir, walletFixturePath } from "../../paths.js";
 import { getAdapterSurface } from "../../adapters/surface.js";
 import {
   ADAPTER_DETECT_NEXT,
@@ -12,44 +7,14 @@ import {
   flag,
   parseFlags,
   resolveAdapter,
-  spawnScript,
   str,
   targetOf,
-  usageOut,
-  writeInteractiveProgress
+  usageOut
 } from "../shared.js";
-import {
-  RECOVERY_CODE,
-  checkHealBounds,
-  ensureOverlay,
-  newHealState,
-  parseHeal
-} from "../../heal-bounds.js";
-import {
-  extensionDepsBlock,
-  extensionRuntimeReusable,
-  installExtensionDeps,
-  launchExtension
-} from "./extension.js";
-import { launchMobile } from "./mobile.js";
-import { applyDeviceTargeting } from "../device-target.js";
+import { parseHeal } from "../../heal-bounds.js";
 import { acquireCheckoutLock } from "../../checkout-lock.js";
 import { JsonStreamWriter } from "../../json-stream.js";
-import {
-  FeatureFlagSpecError,
-  fixtureFeatureFlags,
-  parseRemoteFlagSpec,
-  remoteFlagRequestFor,
-  sameFeatureFlags,
-  toRemoteFlagSpec
-} from "../../feature-flags.js";
-import { readExtensionPinnedFlags } from "../../adapters/extension/feature-flags.js";
-import { ensureExtensionConsoleCapture } from "../../adapters/extension/console-capture.js";
-import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
-import {
-  releaseArtifactState,
-  runtimeDistCheck
-} from "../../adapters/extension/runtime-decision.js";
+import { shellQuote } from "./device.js";
 const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "build",
   "watch",
@@ -64,22 +29,6 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "headless",
   "headful"
 ]);
-const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
-function metroLaunchEvidence(adapter, target) {
-  if (adapter !== "mobile") return void 0;
-  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);
-  }
-}
 async function handleLaunch(argv) {
   const { options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
@@ -120,83 +69,6 @@ async function handleLaunch(argv) {
     restoreStdout();
   }
 }
-const TERMINAL_ONLY_LAUNCH_OPTIONS = Object.freeze({
-  signer: "--signer",
-  account: "--account",
-  freshProfile: "--fresh-profile",
-  headless: "--headless",
-  headful: "--headful",
-  slowMo: "--slow-mo",
-  network: "--network",
-  mainnetConfirmation: "--mainnet-confirmation"
-});
-function terminalOnlyLaunchFlags(options) {
-  return Object.entries(TERMINAL_ONLY_LAUNCH_OPTIONS).filter(([key]) => options[key] !== void 0 && options[key] !== false).map(([, name]) => name);
-}
-function parseTerminalLauncherOutput(output) {
-  const text = output.trim();
-  if (!text) return { status: "fail", error: "the terminal launcher printed no summary" };
-  try {
-    return JSON.parse(text);
-  } catch {
-    const last = text.split("\n").filter((line) => line.trim()).pop() ?? "";
-    try {
-      return JSON.parse(last);
-    } catch {
-      return { status: "fail", error: `the terminal launcher printed no JSON summary: ${last.slice(0, 200)}` };
-    }
-  }
-}
-function launchTerminal(options, target, jsonOutput, stream) {
-  const cdpPort = str(options, "cdpPort") ?? process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
-  const appPort = str(options, "watcherPort") ?? process.env.TERMINAL_APP_PORT ?? process.env.RECIPE_WATCHER_PORT ?? process.env.WATCHER_PORT;
-  if (!cdpPort || !appPort) {
-    return launchUsage(
-      jsonOutput,
-      stream,
-      "terminal launch needs the slot browser CDP port and the slot dev-server port.",
-      "mm-harness launch --adapter terminal --cdp-port <port> --watcher-port <app port>"
-    );
-  }
-  const args = [
-    path.join(runnerDir, "adapters", "terminal", "launch.mjs"),
-    "--target",
-    target,
-    "--cdp-port",
-    cdpPort,
-    "--app-port",
-    appPort,
-    "--signer",
-    str(options, "signer") ?? process.env.TERMINAL_SIGNER ?? "extension",
-    "--account",
-    str(options, "account") ?? process.env.TERMINAL_ACCOUNT ?? "dev1",
-    "--json"
-  ];
-  if (flag(options, "freshProfile")) args.push("--fresh-profile");
-  if (flag(options, "headless")) args.push("--headless");
-  if (flag(options, "headful")) args.push("--headful");
-  const slowMo = str(options, "slowMo");
-  if (slowMo) args.push("--slow-mo", slowMo);
-  const network = str(options, "network");
-  if (network) args.push("--network", network);
-  const mainnetConfirmation = str(options, "mainnetConfirmation");
-  if (mainnetConfirmation) args.push("--mainnet-confirmation", mainnetConfirmation);
-  stream.phase("launch", { adapter: "terminal", cdpPort, appPort });
-  let output = "";
-  let status = 0;
-  try {
-    output = execFileSync(process.execPath, args, { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
-  } catch (error) {
-    status = 1;
-    output = String(error.stdout ?? "");
-  }
-  const result = parseTerminalLauncherOutput(output);
-  if (jsonOutput) console.log(JSON.stringify({ schemaVersion: 1, command: "launch", adapter: "terminal", target, ...result }, null, 2));
-  else if (result.status === "pass") console.log(`\u2713 terminal browser ${result.reused ? "reused" : "started"} on CDP ${result.cdpPort} (${result.signer}, ${result.account?.name})`);
-  else console.error(`\u2717 terminal launch failed: ${result.error ?? "unknown error"}`);
-  stream.complete(result.status === "pass" ? "pass" : "fail", status);
-  return result.status === "pass" ? 0 : 1;
-}
 async function handleLaunchLocked(argv, stream) {
   const { positional, options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
@@ -216,827 +88,22 @@ async function handleLaunchLocked(argv, stream) {
     return launchUsage(jsonOutput, stream, `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   stream.phase("resolve", { target, adapter, platform: mobileTarget ?? null });
-  if (adapter === "core") {
-    return launchUsage(jsonOutput, stream, "core is headless; there is nothing to launch.", "mm-harness verify");
-  }
-  if (adapter === "terminal") {
-    return launchTerminal(options, target, jsonOutput, stream);
-  }
-  const terminalOnly = terminalOnlyLaunchFlags(options);
-  if (terminalOnly.length > 0) {
-    return launchUsage(
-      jsonOutput,
-      stream,
-      `${terminalOnly.join(", ")} apply only to --adapter terminal; ${adapter} does not read them.`,
-      "drop the terminal flags, or pass --adapter terminal"
-    );
-  }
-  if (adapter === "mobile" && !mobileTarget) {
-    return launchUsage(
-      jsonOutput,
-      stream,
-      "target is required for mobile.",
-      "mm-harness launch ios   or   mm-harness launch android"
-    );
-  }
-  const wantBuild = flag(options, "build");
-  const wantVerify = flag(options, "verify");
-  const wantWatch = flag(options, "watch");
-  const wantRunway = flag(options, "runway");
-  const wantClearMetro = flag(options, "clearMetro");
-  const requestedSurface = str(options, "surface");
-  const legacySidepanel = flag(options, "sidepanel");
-  const legacyFullscreen = flag(options, "fullscreen");
-  if (wantRunway && adapter !== "mobile") {
-    return launchUsage(jsonOutput, stream, "runway is mobile-only.", "drop --runway for the extension");
-  }
-  if (wantClearMetro && adapter !== "mobile") {
-    return launchUsage(jsonOutput, stream, "--clear-metro is mobile-only.", "drop --clear-metro for the extension");
-  }
-  if (requestedSurface !== void 0 && requestedSurface !== "fullscreen" && requestedSurface !== "sidepanel") {
-    return launchUsage(
-      jsonOutput,
-      stream,
-      `--surface must be fullscreen or sidepanel (got: ${requestedSurface}).`,
-      "pass --surface fullscreen or --surface sidepanel"
-    );
-  }
-  if (legacySidepanel && legacyFullscreen) {
-    return launchUsage(
-      jsonOutput,
-      stream,
-      "--sidepanel and --fullscreen conflict.",
-      "pass exactly one Extension surface"
-    );
-  }
-  const legacySurface = legacySidepanel ? "sidepanel" : legacyFullscreen ? "fullscreen" : void 0;
-  if (requestedSurface && legacySurface && requestedSurface !== legacySurface) {
-    return launchUsage(
-      jsonOutput,
-      stream,
-      `--surface ${requestedSurface} conflicts with --${legacySurface}.`,
-      "pass one consistent Extension surface"
-    );
-  }
-  const displayMode = requestedSurface ?? legacySurface ?? "fullscreen";
-  const remoteFlagSpec = str(options, "remoteFlag");
-  if (remoteFlagSpec !== void 0 && adapter === "extension" && wantWatch) {
-    return launchUsage(
-      jsonOutput,
-      stream,
-      "--remote-flag cannot be applied with --watch: the watcher never re-creates the dist snapshot that carries the pin.",
-      `mm-harness launch --adapter extension --remote-flag ${remoteFlagSpec} --target ${shellQuote(target)}`
-    );
-  }
-  let remoteFlagRequest;
-  try {
-    remoteFlagRequest = remoteFlagRequestFor({
-      ...fixtureFeatureFlags(walletFixturePath(target)),
-      ...remoteFlagSpec === void 0 ? {} : parseRemoteFlagSpec(remoteFlagSpec)
-    });
-  } catch (error) {
-    if (!(error instanceof FeatureFlagSpecError)) throw error;
-    return launchUsage(jsonOutput, stream, error.message, error.userAction);
-  }
-  for (const portFlag of ["cdpPort", "watcherPort"]) {
-    const value = str(options, portFlag);
-    if (value !== void 0 && !/^\d+$/u.test(value)) {
-      return launchUsage(
-        jsonOutput,
-        stream,
-        `--${portFlag === "cdpPort" ? "cdp-port" : "watcher-port"} must be numeric (got: ${value}).`,
-        `pass a numeric port, e.g. --${portFlag === "cdpPort" ? "cdp-port 6663" : "watcher-port 8081"}`
-      );
-    }
-  }
-  const envResult = applyLaunchEnvOverrides(options, adapter, mobileTarget, target);
-  if (envResult && "code" in envResult) {
-    return launchUsage(jsonOutput, stream, envResult.message, envResult.userAction);
-  }
-  const tier = wantBuild ? "build" : "quick";
-  if (adapter === "extension") {
-    const requestedUrl = typeof options["url"] === "string" && options["url"] ? options["url"] : "";
-    if (requestedUrl || displayMode === "sidepanel") {
-      process.env.EXTENSION_START_URL = requestedUrl || DEFAULT_EXTENSION_DAPP_URL;
-    }
-  }
-  if (!machine && adapter === "extension") {
-    const modeNote = displayMode === "sidepanel" ? `sidepanel \xB7 dapp ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}` : "fullscreen";
-    const workNote = wantWatch ? "watch only" : tier === "build" ? "clean build" : "quick reuse probe";
-    console.error(colorHumanMessage(
-      `\u2192 extension launch \u2014 ${modeNote} \xB7 CDP :${process.env.CDP_PORT ?? "default"} \xB7 ${workNote}`
-    ));
-  }
-  if (adapter === "mobile") {
-    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" : ""}`
-    );
-  }
-  const state = newHealState();
-  if (tier === "quick" && nativeInputsChanged(target, adapter)) {
-    return launchUsage(
-      jsonOutput,
-      stream,
-      "native build inputs changed since last build.",
-      `mm-harness launch ${adapter === "mobile" ? `${mobileTarget} ` : ""}--build`
-    );
-  }
-  stream.phase("install");
-  const ensured = await ensureOverlay(adapter, target, heal, state, machine);
-  if (!ensured.ok) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: "OVERLAY_INSTALL_FAILED",
-      message: ensured.error ?? "overlay install failed",
-      recoverable: false,
-      exitCode: EXIT.infra
-    });
-  }
-  stream.phase("healthcheck");
-  if (adapter === "extension") {
-    const artifact = releaseArtifactState(target);
-    const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target, artifact);
-    const verifiedReleaseReuse = artifact.status === "valid" && reusable;
-    const verifiedReleaseLaunch = !wantWatch && tier !== "build" && artifact.status === "valid" && runtimeDistCheck(target, artifact).status === "fresh";
-    const willBuild = !reusable;
-    if (willBuild) {
-      const productConfigBlock = extensionProductConfigBlock(target);
-      if (productConfigBlock) {
-        return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-          code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
-          message: productConfigBlock.message,
-          recoverable: false,
-          userAction: productConfigBlock.userAction,
-          exitCode: EXIT.infra
-        });
-      }
-    }
-    const depsBlock = verifiedReleaseReuse || verifiedReleaseLaunch ? null : extensionDepsBlock(target);
-    if (depsBlock) {
-      if (heal === "off") {
-        return launchUsage(jsonOutput, stream, depsBlock.message, depsBlock.userAction);
-      }
-      const recoveryCode2 = "deps.installed";
-      state.attemptedRecoveries.push(recoveryCode2);
-      stream.phase("recover");
-      const repaired = await installExtensionDeps(target);
-      if (repaired.status !== 0 || extensionDepsBlock(target)) {
-        return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-          code: "DEPENDENCY_INSTALL_FAILED",
-          message: depsBlock.message,
-          recoverable: false,
-          userAction: "install the checkout-pinned Node version, then re-run mm-harness launch",
-          originalError: repaired.output,
-          exitCode: EXIT.infra
-        });
-      }
-      state.recovered.push(recoveryCode2);
-      state.mutations.push({ type: "dependencies", action: "installed", path: target });
-    }
-  }
-  stream.phase("launch");
-  let attempt = await executeComposition(
+  return getAdapterSurface(adapter).launch({
     adapter,
-    mobileTarget,
-    tier,
-    wantWatch,
     target,
-    machine,
-    displayMode,
-    false,
-    wantClearMetro,
-    remoteFlagRequest
-  );
-  if (attempt.status === 0) {
-    return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, attempt.remoteFeatureFlags);
-  }
-  const readinessFailure = mobileReadinessFailure(attempt);
-  if (readinessFailure) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, readinessFailure);
-  }
-  if (adapter === "extension" && attempt.output.includes("REMOTE_FLAG_NOT_PINNABLE:")) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: "REMOTE_FLAG_NOT_PINNABLE",
-      message: `a verified release artifact cannot carry a remote feature-flag pin (${remoteFlagRequest?.spec ?? ""}); its manifest is signed evidence and is never rewritten. Validate the artifact as shipped (drop --remote-flag and the fixture's remoteFeatureFlags) or validate the variant on a source build.`,
-      recoverable: false,
-      // The next step must leave the artifact alone: a --build here would replace
-      // the artifact under validation with a source build.
-      userAction: Object.keys(fixtureFeatureFlags(walletFixturePath(target))).length > 0 ? `remove remoteFeatureFlags from ${shellQuote(walletFixturePath(target))}, then: mm-harness launch --adapter extension --target ${shellQuote(target)}` : `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
-      exitCode: EXIT.infra,
-      originalError: attempt.output.trim() || void 0
-    });
-  }
-  if (adapter === "extension" && extensionProductConfigMissing(attempt.output)) {
-    const block = extensionProductConfigBlock(target);
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
-      message: block?.message ?? "Extension product configuration was not ready when the build started.",
-      recoverable: false,
-      userAction: block?.userAction ?? `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
-      exitCode: EXIT.infra
-    });
-  }
-  if (adapter === "extension" && extensionBrowserMissing(attempt.output)) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: "EXTENSION_BROWSER_REQUIRED",
-      message: "the checkout Playwright browser is not installed; system Chrome is not a compatible unpacked-extension fallback. Installing the browser cache requires user approval.",
-      recoverable: false,
-      userAction: `ask the user for approval, then run: cd ${shellQuote(target)} && yarn playwright install chromium`,
-      exitCode: EXIT.infra
-    });
-  }
-  if (adapter === "extension" && (attempt.output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") || attempt.output.includes("EXTENSION_STARTUP_UNVERIFIED:"))) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: attempt.output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") ? "EXTENSION_BACKGROUND_UNRESPONSIVE" : "EXTENSION_STARTUP_UNVERIFIED",
-      message: "Extension startup is not healthy; inspect the background error before restarting or resetting wallet state.",
-      recoverable: false,
-      userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
-      exitCode: EXIT.runtime,
-      originalError: attempt.output.trim() || void 0
-    });
-  }
-  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",
-      message: "EVM RPC readiness failed; Infura configured does not mean RPC reachable.",
-      recoverable: false,
-      userAction: `Check the effective INFURA_PROJECT_ID from the environment, .metamaskprodrc, or ${shellQuote(path.join(target, ".metamaskrc"))}, then rerun: mm-harness launch --verify --target ${shellQuote(target)}`,
-      exitCode: EXIT.runtime,
-      originalError: attempt.output.trim() || void 0
-    });
-  }
-  if (adapter === "mobile" && attempt.output.includes("open-device: Android device is locked.")) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      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: attempt.output.trim()
-    });
-  }
-  if (adapter === "mobile" && /open-device: Android (?:lock state unavailable|display preparation failed)\./u.test(attempt.output)) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      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: attempt.output.trim()
-    });
-  }
-  if (heal === "off") {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: "LAUNCH_FAILED",
-      message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed (healing off)`,
-      recoverable: false,
-      exitCode: EXIT.infra
-    });
-  }
-  if (adapter === "extension" && tier === "quick" && extensionQuickReattachFailed(attempt.output)) {
-    const recoveryCode2 = "chrome.relaunched";
-    state.attemptedRecoveries.push(recoveryCode2);
-    stream.phase("recover");
-    const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode, false, false, remoteFlagRequest);
-    if (rebuildAttempt.status === 0) {
-      state.recovered.push(recoveryCode2);
-      return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, rebuildAttempt.remoteFeatureFlags);
-    }
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: "EXTENSION_RELAUNCH_FAILED",
-      message: "quick reattach failed, and clean relaunch failed too.",
-      recoverable: false,
-      exitCode: EXIT.infra,
-      originalError: rebuildAttempt.output.trim() || void 0
-    });
-  }
-  const missingIosSimulator = adapter === "mobile" ? missingConfiguredIosSimulator(attempt.output) : void 0;
-  const ambiguousIosSimulator = adapter === "mobile" ? ambiguousConfiguredIosSimulator(attempt.output) : void 0;
-  if (ambiguousIosSimulator) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      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: attempt.output.trim() || void 0
-    });
-  }
-  if (missingIosSimulator && isIosSimulatorUdid(missingIosSimulator)) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      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: attempt.output.trim() || void 0
-    });
-  }
-  if (adapter === "mobile" && mobileProvisioningBlocked(attempt.output)) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: "MOBILE_PROVISION_REQUIRED",
-      message: `mobile ${mobileTarget ?? "runtime"} is not provisioned for this slot.`,
-      recoverable: false,
-      userAction: mobileProvisionCommand(target, mobileTarget),
-      exitCode: EXIT.runtime,
-      originalError: attempt.output.trim() || void 0
-    });
-  }
-  if (adapter === "mobile" && tier === "build" && /open-device: (?:Android|iOS) native build failed/u.test(attempt.output)) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      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: attempt.output.trim() || void 0
-    });
-  }
-  const bound = checkHealBounds(target, attempt.output, state);
-  if (bound !== null) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: bound.code,
-      message: bound.message,
-      recoverable: false,
-      userAction: bound.userAction,
-      exitCode: bound.exitCode,
-      originalError: bound.originalError
-    });
-  }
-  const restartMobileApp = adapter === "mobile" && mobileBridgeTargetMissing(attempt.output);
-  const recoveryCode = restartMobileApp ? "mobile.app-restarted" : RECOVERY_CODE[adapter];
-  state.attemptedRecoveries.push(recoveryCode);
-  stream.phase("recover");
-  const recoveryTier = restartMobileApp && tier === "build" ? "quick" : tier;
-  if (!jsonOutput) {
-    process.stderr.write(`launch: recovering (${recoveryCode}) with the ${recoveryTier} tier
-`);
-  }
-  attempt = await executeComposition(
-    adapter,
+    options,
     mobileTarget,
-    recoveryTier,
-    wantWatch,
-    target,
-    machine,
-    displayMode,
-    restartMobileApp,
-    false,
-    remoteFlagRequest
-  );
-  if (attempt.status === 0) {
-    state.recovered.push(recoveryCode);
-    return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, attempt.remoteFeatureFlags);
-  }
-  const retryReadinessFailure = mobileReadinessFailure(attempt);
-  if (retryReadinessFailure) {
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, retryReadinessFailure);
-  }
-  return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-    code: "SAME_RECOVERY_TWICE",
-    message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed again after ${recoveryCode} recovery \u2014 refusing to loop.`,
-    recoverable: false,
-    exitCode: EXIT.bounded,
-    originalError: attempt.output.trim() || void 0
-  });
-}
-function mobileReadinessFailure(result) {
-  const block = result.readinessBlock;
-  if (!block) return void 0;
-  return {
-    code: block.reasonCode === "deps-not-ready" ? "MOBILE_DEPENDENCIES_NOT_READY" : "MOBILE_READINESS_BLOCKED",
-    message: block.message,
-    userAction: block.userAction,
-    recoverable: false,
-    exitCode: result.status
-  };
-}
-function extensionQuickReattachFailed(output) {
-  return /\[reattach\]|extension quick reattach|mm-harness launch --build/u.test(output);
-}
-function extensionRuntimeBlocked(output) {
-  return /ERR_BLOCKED_BY_CLIENT|has been blocked by Chromium/u.test(output);
-}
-function extensionBrowserMissing(output) {
-  return /Playwright Chromium is not installed|No compatible Chromium binary selected/u.test(output);
-}
-function extensionProductConfigMissing(output) {
-  return /EXTENSION_PRODUCT_CONFIG_REQUIRED:/u.test(output);
-}
-function extensionEvmRpcUnreachable(output) {
-  return /EVM_RPC_UNREACHABLE|EVM RPC readiness probe failed|Infura configured ≠ RPC reachable/u.test(output);
-}
-function mobileProvisioningBlocked(output) {
-  return /open-device: configured iOS simulator '.+' does not exist|open-device: no MetaMask bundle found|fast mode requires an installed (?:iOS dev client|Android dev client)/u.test(output);
-}
-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 shellQuote(value) {
-  if (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(value)) return value;
-  return `'${value.replace(/'/gu, `'"'"'`)}'`;
-}
-function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
-  getAdapterSurface(adapter).resolveSlotPorts(target);
-  const device = str(options, "device");
-  if (adapter === "mobile" && (device || mobileTarget === "ios" || mobileTarget === "android")) {
-    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`
-      };
-    }
-  }
-  const cdpPort = str(options, "cdpPort");
-  if (cdpPort) {
-    process.env.CDP_PORT = cdpPort;
-    process.env.RECIPE_CDP_PORT = cdpPort;
-  }
-  const watcherPort = str(options, "watcherPort");
-  if (watcherPort) {
-    process.env.WATCHER_PORT = watcherPort;
-    process.env.RECIPE_WATCHER_PORT = watcherPort;
-    process.env.METRO_PORT = watcherPort;
-  }
-  return { ok: true };
-}
-function isIosSimulatorUdid(value) {
-  return /^[0-9A-Fa-f-]{36}$/u.test(value);
-}
-function nativeInputsChanged(target, adapter) {
-  const baselineFile = recipeRuntimePath(target, ".last-build-ref");
-  let baseline;
-  try {
-    baseline = fs.readFileSync(baselineFile, "utf8").trim();
-  } catch {
-    return false;
-  }
-  if (!baseline) return false;
-  const paths = adapter === "mobile" ? ["ios", "android", "package.json", "yarn.lock"] : ["package.json", "yarn.lock", "webpack.config.js"];
-  try {
-    const diff = execFileSync("git", ["-C", target, "diff", "--name-only", baseline, "--", ...paths], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
-    }).trim();
-    return diff.length > 0;
-  } catch {
-    return false;
-  }
-}
-function verifyExtensionPin(target, requested) {
-  const pinned = readExtensionPinnedFlags(target);
-  if (pinned.error) {
-    return {
-      ok: false,
-      flags: {},
-      code: "RUNTIME_MANIFEST_UNREADABLE",
-      message: `the launched dist snapshot manifest could not be read (${pinned.sourcePath ?? "unknown path"}): ${pinned.error}`
-    };
-  }
-  if (pinned.overrides !== null && pinned.pinned === null) {
-    return {
-      ok: false,
-      flags: {},
-      code: "REMOTE_FLAG_NOT_APPLIED",
-      message: `the launched dist snapshot manifest (${pinned.sourcePath ?? "unknown path"}) carries no harness pin record; it was not written by this launch.`
-    };
-  }
-  const actual = pinned.pinned ?? {};
-  if (!sameFeatureFlags(actual, requested)) {
-    const mismatched = [.../* @__PURE__ */ new Set([...Object.keys(requested), ...Object.keys(actual)])].filter(
-      (key) => JSON.stringify(actual[key]) !== JSON.stringify(requested[key])
-    );
-    return {
-      ok: false,
-      flags: {},
-      code: "REMOTE_FLAG_NOT_APPLIED",
-      message: `the remote feature-flag pin ${toRemoteFlagSpec(requested) || "(none)"} does not match the launched snapshot manifest: ` + mismatched.map((key) => `${key} expected ${JSON.stringify(requested[key])}, got ${JSON.stringify(actual[key])}`).join("; ")
-    };
-  }
-  return { ok: true, flags: actual, message: "" };
-}
-async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode = "fullscreen", restartMobileApp = false, clearMobileMetro = false, remoteFlagRequest) {
-  if (adapter === "mobile") {
-    return launchMobile(
-      target,
-      mobileTarget,
-      tier,
-      json,
-      restartMobileApp,
-      clearMobileMetro,
-      remoteFlagRequest?.flags
-    );
-  }
-  return launchExtension(target, tier, wantWatch, displayMode, remoteFlagRequest);
-}
-async function settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, sidepanelRecoveryAllowed = true, mobileProvenFlags) {
-  const requested = remoteFlagRequest?.flags ?? {};
-  const pinned = adapter !== "extension" ? { ok: true, flags: mobileProvenFlags === void 0 ? requested : mobileProvenFlags, message: "" } : wantWatch ? { ok: true, flags: readExtensionPinnedFlags(target).pinned, message: "" } : verifyExtensionPin(target, requested);
-  if (!pinned.ok) {
-    const spec = remoteFlagRequest?.spec;
-    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: pinned.code ?? "REMOTE_FLAG_NOT_APPLIED",
-      message: pinned.message,
-      recoverable: false,
-      // A rebuild re-creates the snapshot; the flag is repeated only when one was asked for.
-      userAction: `mm-harness launch --adapter extension --build${spec ? ` --remote-flag ${spec}` : ""} --target ${shellQuote(target)}`,
-      exitCode: EXIT.runtime
-    });
-  }
-  return finishLaunch(
+    heal,
     jsonOutput,
     machine,
     stream,
-    adapter,
-    mobileTarget,
-    tier,
-    displayMode,
-    target,
-    state,
-    wantWatch,
-    wantVerify,
-    sidepanelRecoveryAllowed,
-    remoteFlagRequest,
-    pinned.flags
-  );
-}
-async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, sidepanelRecoveryAllowed = true, remoteFlagRequest, remoteFlags = {}) {
-  if (adapter === "extension" && displayMode === "fullscreen") {
-    const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
-    const sidepanelArgs = ["close"];
-    if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
-    const fullscreen = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
-    if (fullscreen.status !== 0) {
-      return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-        code: "FULLSCREEN_OPEN_FAILED",
-        message: "app launched but restoring the fullscreen Extension surface failed.",
-        recoverable: false,
-        userAction: `bash adapters/extension/sidepanel-toggle.sh close --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
-        exitCode: EXIT.runtime,
-        originalError: fullscreen.output.trim() || void 0
-      });
-    }
-  }
-  if (adapter === "extension" && displayMode === "sidepanel") {
-    const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
-    const sidepanelArgs = ["open"];
-    if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
-    if (!machine) {
-      console.error(
-        `[sidepanel] opening panel beside ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}`
-      );
-    }
-    const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
-    if (sidepanel.status !== 0) {
-      const recoveryCode = "chrome.relaunched";
-      if (sidepanelRecoveryAllowed && tier === "quick" && extensionRuntimeBlocked(sidepanel.output) && !state.attemptedRecoveries.includes(recoveryCode)) {
-        state.attemptedRecoveries.push(recoveryCode);
-        stream.phase("recover");
-        const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode, false, false, remoteFlagRequest);
-        if (rebuildAttempt.status === 0) {
-          state.recovered.push(recoveryCode);
-          return await settleLaunch(
-            jsonOutput,
-            machine,
-            stream,
-            adapter,
-            mobileTarget,
-            tier,
-            displayMode,
-            target,
-            state,
-            wantWatch,
-            wantVerify,
-            remoteFlagRequest,
-            false
-          );
-        }
-        return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-          code: "EXTENSION_RELAUNCH_FAILED",
-          message: "sidepanel open found a blocked extension runtime, and clean relaunch failed too.",
-          recoverable: false,
-          exitCode: EXIT.infra,
-          originalError: rebuildAttempt.output.trim() || void 0
-        });
-      }
-      return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-        code: "SIDEPANEL_OPEN_FAILED",
-        message: "app launched but opening the side panel failed.",
-        recoverable: false,
-        userAction: `bash adapters/extension/sidepanel-toggle.sh open --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
-        exitCode: EXIT.runtime,
-        originalError: sidepanel.output.trim() || void 0
-      });
-    }
-  }
-  if (adapter === "extension") {
-    try {
-      await ensureExtensionConsoleCapture(target);
-    } catch (error) {
-      if (!machine) {
-        console.error(`WARN: Extension console capture unavailable: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    }
-  }
-  if (wantVerify) {
-    stream.phase("verify");
-    const verifyArgs = ["verify", "--adapter", adapter, "--target", target];
-    if (adapter === "mobile" && mobileTarget) verifyArgs.push("--platform", mobileTarget);
-    if (adapter === "extension" && process.env.CDP_PORT) {
-      verifyArgs.push("--cdp-port", process.env.CDP_PORT);
-    }
-    if (machine) verifyArgs.push("--json");
-    const exitCode = await handleHarness(verifyArgs);
-    if (stream.enabled) {
-      for (const mutation of state.mutations) stream.mutation(mutation);
-      for (const recovery of state.recovered) stream.recovery(recovery);
-      stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode, {
-        adapter,
-        platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
-        tier,
-        recovered: state.recovered,
-        mutations: state.mutations,
-        metro: metroLaunchEvidence(adapter, target),
-        remoteFeatureFlags: remoteFlags
-      });
-    }
-    return exitCode;
-  }
-  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, target, state, remoteFlags);
-}
-function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, target, state, remoteFlags = {}) {
-  if (stream.enabled) {
-    for (const mutation of state.mutations) stream.mutation(mutation);
-    for (const recovery of state.recovered) stream.recovery(recovery);
-    stream.complete("pass", EXIT.ok, {
-      adapter,
-      platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
-      tier,
-      recovered: state.recovered,
-      mutations: state.mutations,
-      metro: metroLaunchEvidence(adapter, target),
-      remoteFeatureFlags: remoteFlags
-    });
-  } else if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: "launch",
-          adapter,
-          platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
-          tier,
-          status: "pass",
-          phase: "launch",
-          recovered: state.recovered,
-          mutations: state.mutations,
-          metro: metroLaunchEvidence(adapter, target),
-          remoteFeatureFlags: remoteFlags,
-          exitCode: EXIT.ok
-        },
-        null,
-        2
-      )
-    );
-  } else {
-    const device = adapter === "mobile" ? launchDeviceLabel(mobileTarget) : displayMode;
-    const tierNote = tier === "quick" ? "quick relaunch, no native build" : tier;
-    const devNote = process.env.MM_HARNESS_BIN ? ` ${color("dim", "[dev: MM_HARNESS_BIN]")}` : "";
-    console.error(
-      `${color("ok", "\u2713")} launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} \u2014 ${color("ok", String(device))} \xB7 ${tierNote} \xB7 app + bridge ready${devNote}`
-    );
-  }
-  return EXIT.ok;
-}
-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";
+    usage: (message, userAction) => launchUsage(jsonOutput, stream, message, userAction)
+  });
 }
 function launchUsage(json, stream, message, userAction) {
   stream.error({ code: "USAGE", message, userAction });
   return usageOut(json, "launch", message, userAction);
 }
-function launchFail(json, stream, adapter, mobileTarget, tier, state, target, failure) {
-  const userAction = failure.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
-  if (stream.enabled) {
-    for (const mutation of state.mutations) stream.mutation(mutation);
-    for (const recovery of state.recovered) stream.recovery(recovery);
-    stream.error({
-      code: failure.code,
-      message: failure.message,
-      retryable: failure.recoverable,
-      userAction,
-      originalError: failure.originalError ?? null
-    });
-    stream.complete("fail", failure.exitCode, {
-      adapter,
-      platform: mobileTarget ?? null,
-      tier,
-      recovered: state.recovered,
-      mutations: state.mutations,
-      recoverable: failure.recoverable,
-      attemptedRecoveries: state.attemptedRecoveries,
-      metro: metroLaunchEvidence(adapter, target)
-    });
-  } else if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: "launch",
-          adapter,
-          platform: mobileTarget ?? null,
-          tier,
-          status: "fail",
-          phase: state.attemptedRecoveries.length ? "recover" : "launch",
-          recovered: state.recovered,
-          mutations: state.mutations,
-          recoverable: failure.recoverable,
-          attemptedRecoveries: state.attemptedRecoveries,
-          metro: metroLaunchEvidence(adapter, target),
-          exitCode: failure.exitCode,
-          error: {
-            code: failure.code,
-            message: failure.message,
-            retryable: failure.recoverable,
-            userAction,
-            originalError: failure.originalError ?? null
-          }
-        },
-        null,
-        2
-      )
-    );
-  } else {
-    console.error(colorHumanMessage(
-      `\u2717 launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed
-  ${failure.message}` + (failure.originalError ? `
-  --- original failure ---
-${failure.originalError}` : "") + `
-  Next: ${userAction}`
-    ));
-  }
-  return failure.exitCode;
-}
 export {
-  TERMINAL_ONLY_LAUNCH_OPTIONS,
-  handleLaunch,
-  parseTerminalLauncherOutput,
-  terminalOnlyLaunchFlags
+  handleLaunch
 };