@deeeed/metamask-harness 0.74.0 → 0.76.0

package/dist/commands/launch/mobile.js

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import { prepareMobile } from "../../adapters/mobile/prepare.js";
 import {
   mobileSourceCheck,
@@ -8,11 +7,7 @@ import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
 import { pinMobileFeatureFlags } from "../../adapters/mobile/feature-flags.js";
 import { toRemoteFlagSpec } from "../../feature-flags.js";
 import { clearMobileReleaseArtifactState } from "../../adapters/mobile/release-artifact-state.js";
-import { EXIT, str, writeInteractiveProgress } from "../shared.js";
-import { applyDeviceTargeting } from "../device-target.js";
-import { RECOVERY_CODE } from "../../heal-bounds.js";
-import { recipeRuntimePath } from "../../paths.js";
-import { shellQuote } from "./device.js";
+import { EXIT } from "../shared.js";
 async function launchMobile(target, mobileTarget, tier, json, restartApp = false, clearMetro = false, remoteFlags) {
   clearMobileReleaseArtifactState(target);
   await ensureHarnessFresh(target, "mobile");
@@ -59,189 +54,6 @@ async function launchMobile(target, mobileTarget, tier, json, restartApp = false
   }
   return { ...result, remoteFeatureFlags: provenFlags };
 }
-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 {
-  launchMobile,
-  mobileLaunchProfile
+  launchMobile
 };

package/dist/commands/launch/quote.js

@@ -0,0 +1,7 @@
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(value)) return value;
+  return `'${value.replace(/'/gu, `'"'"'`)}'`;
+}
+export {
+  shellQuote
+};

package/dist/commands/logs.js

@@ -68,7 +68,7 @@ async function handleLogs(argv) {
   if (flag(options, "window")) {
     surface.resolveSlotPorts(target);
     const port = process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "default";
-    const windowName = adapter === "mobile" ? `metro-${port}` : `webpack-${port}`;
+    const windowName = `${surface.devServer.label}-${port}`;
     const devLog = logSources[0].path;
     const leaf = path.join(runnerDir, "adapters/shared/open-log-window.sh");
     const result = spawnScript(

package/dist/commands/parse-args.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { detectAdapter } from "../harness.js";
-import { assertAdapter, manifestPath } from "../paths.js";
+import { adapterRegistry } from "../adapters/registry.js";
+import { assertAdapter } from "../paths.js";
 import { explicitRecipeTrustOptions } from "../recipe-security.js";
 import { ADAPTER_DETECT_NEXT } from "./shared.js";
 import { EXIT } from "./shared.js";
@@ -179,12 +180,16 @@ function requiredOption(options, key, message) {
   if (!value) throw usageError(message);
   return value;
 }
+function adapterUsageError(error) {
+  if (error instanceof Error && error.message.startsWith("internal:")) return error;
+  return usageError(error instanceof Error ? error.message : String(error));
+}
 function adapterOption(options) {
   const adapter = optionString(options, "adapter");
   try {
     assertAdapter(adapter);
   } catch (error) {
-    throw usageError(error instanceof Error ? error.message : String(error));
+    throw adapterUsageError(error);
   }
   return adapter;
 }
@@ -193,7 +198,7 @@ function targetPath(options) {
 }
 function actionManifestPathOption(options, adapter) {
   const configured = optionString(options, "actionManifest");
-  return configured ? path.resolve(configured) : manifestPath(adapter);
+  return configured ? path.resolve(configured) : adapterRegistry.get(adapter).actions.manifestPath();
 }
 function parsePort(value, errorMessage) {
   const port = Number(value);
@@ -238,7 +243,7 @@ function resolveAdapter(options) {
   try {
     assertAdapter(adapter);
   } catch (error) {
-    throw usageError(error instanceof Error ? error.message : String(error));
+    throw adapterUsageError(error);
   }
   return { adapter, target };
 }

package/dist/commands/pin.js

@@ -0,0 +1,226 @@
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { isPin, PIN_MARKER } from "../harness-pin.js";
+import { runnerDir } from "../paths.js";
+import { EXIT } from "./shared.js";
+const PACKAGE_NAME = "@deeeed/metamask-harness";
+const STALE_STAGING_MS = 30 * 60 * 1e3;
+const RUNNER_STATE = /* @__PURE__ */ new Set([".omc", ".omx"]);
+function pinRoot(env = process.env, home = os.homedir()) {
+  return path.resolve(env.MM_HARNESS_PIN_ROOT || path.join(home, ".local/share/mm-harness/pins"));
+}
+function readManifest(root) {
+  return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+}
+function contentDigest(root) {
+  const hash = crypto.createHash("sha256");
+  const walk = (directory, relative) => {
+    hash.update(`d\0${relative}\0`);
+    const entries = fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const entry of entries) {
+      if (RUNNER_STATE.has(entry.name) || !relative && entry.name === PIN_MARKER) continue;
+      const absolute = path.join(directory, entry.name);
+      const child = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(absolute, child);
+      } else if (entry.isSymbolicLink()) {
+        hash.update(`l\0${child}\0${fs.readlinkSync(absolute)}\0`);
+      } else if (entry.isFile()) {
+        const fd = fs.openSync(absolute, "r");
+        try {
+          const opened = fs.fstatSync(fd);
+          hash.update(`f\0${child}\0${opened.mode & 73 ? "x" : "-"}\0${opened.size}\0`);
+          hash.update(fs.readFileSync(fd));
+          hash.update("\0");
+        } finally {
+          fs.closeSync(fd);
+        }
+      }
+    }
+  };
+  walk(root, "");
+  return hash.digest("hex");
+}
+function relinkIntoCopy(copy, sourceAliases) {
+  const walk = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolute);
+        continue;
+      }
+      if (!entry.isSymbolicLink()) continue;
+      const raw = fs.readlinkSync(absolute);
+      if (!path.isAbsolute(raw)) continue;
+      const targets = [path.resolve(raw)];
+      try {
+        targets.push(fs.realpathSync(raw));
+      } catch {
+      }
+      let match;
+      for (const target of targets) {
+        const alias = sourceAliases.find((prefix) => target === prefix || target.startsWith(`${prefix}${path.sep}`));
+        if (alias) {
+          match = { alias, target };
+          break;
+        }
+      }
+      if (!match) continue;
+      fs.unlinkSync(absolute);
+      fs.symlinkSync(path.relative(directory, path.join(copy, path.relative(match.alias, match.target))) || ".", absolute);
+    }
+  };
+  walk(copy);
+}
+function assertSelfContained(root) {
+  const manifest = readManifest(root);
+  const lookup = createRequire(path.join(root, "package.json")).resolve.paths("") ?? [];
+  const realRoot = fs.realpathSync(root);
+  const inside = (candidate) => candidate === realRoot || candidate.startsWith(`${realRoot}${path.sep}`);
+  for (const dependency of Object.keys(manifest.dependencies ?? {})) {
+    const found = lookup.map((directory) => path.join(directory, dependency)).find((candidate) => fs.existsSync(path.join(candidate, "package.json")));
+    if (!found) throw new Error(`dependency ${dependency} is not installed for ${root}`);
+    const resolved = fs.realpathSync(found);
+    if (!inside(resolved)) {
+      throw new Error(`dependency ${dependency} resolves outside the install (${resolved}); only a self-contained install (npm i -g) can be pinned`);
+    }
+  }
+  const walk = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) walk(absolute);
+      else if (entry.isSymbolicLink() && path.isAbsolute(fs.readlinkSync(absolute))) {
+        let resolved;
+        try {
+          resolved = fs.realpathSync(absolute);
+        } catch {
+          continue;
+        }
+        if (!inside(resolved)) throw new Error(`link ${path.relative(root, absolute)} leads outside the install (${resolved})`);
+      }
+    }
+  };
+  walk(root);
+}
+function readPinMarker(pin) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(pin, PIN_MARKER), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    return {};
+  }
+}
+function assertPinUnchanged(pin, marker) {
+  if (typeof marker.contentSha256 !== "string" || marker.contentSha256 !== contentDigest(pin)) {
+    throw new Error(`pin ${pin} changed after it was created; remove it, then re-run: mm-harness pin`);
+  }
+}
+function sweepStaleStaging(store, now = Date.now()) {
+  let names;
+  try {
+    names = fs.readdirSync(store);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const created = /^\.staging-.+-(\d{13})-[^-]+$/u.exec(name)?.[1];
+    if (created && now - Number(created) > STALE_STAGING_MS) {
+      fs.rmSync(path.join(store, name), { recursive: true, force: true });
+    }
+  }
+}
+function pinHarness(options = {}) {
+  const sourceAlias = path.resolve(options.sourceRoot ?? runnerDir);
+  const source = fs.realpathSync(sourceAlias);
+  const store = options.root ?? pinRoot();
+  const manifest = readManifest(source);
+  if (manifest.name !== PACKAGE_NAME || typeof manifest.version !== "string" || !manifest.version) {
+    throw new Error(`not an ${PACKAGE_NAME} package: ${source}`);
+  }
+  const version = manifest.version;
+  const ownExecutable = path.join(source, "bin/mm-harness");
+  if (isPin(source)) {
+    return { version, source, executable: ownExecutable, pinned: true, created: false, reason: "already-pinned" };
+  }
+  if (!source.includes(`${path.sep}node_modules${path.sep}`)) {
+    return { version, source, executable: ownExecutable, pinned: false, created: false, reason: "source-checkout" };
+  }
+  const key = `${version}-${contentDigest(source).slice(0, 12)}`;
+  const target = path.join(store, key);
+  const executable = path.join(target, "bin/mm-harness");
+  const existing = readPinMarker(target);
+  if (existing) {
+    assertPinUnchanged(target, existing);
+    return { version, source, executable, pinned: true, created: false };
+  }
+  assertSelfContained(source);
+  fs.mkdirSync(store, { recursive: true });
+  sweepStaleStaging(store);
+  const staging = fs.mkdtempSync(path.join(store, `.staging-${key}-${Date.now()}-`));
+  const copy = path.join(staging, "package");
+  try {
+    fs.cpSync(source, copy, {
+      recursive: true,
+      preserveTimestamps: true,
+      verbatimSymlinks: true,
+      mode: fs.constants.COPYFILE_FICLONE,
+      filter: (from) => !RUNNER_STATE.has(path.basename(from))
+    });
+    relinkIntoCopy(copy, [.../* @__PURE__ */ new Set([source, sourceAlias])]);
+    assertSelfContained(copy);
+    const check = spawnSync(path.join(copy, "bin/mm-harness"), ["--version"], {
+      encoding: "utf8",
+      env: { ...process.env, MM_HARNESS_BIN: "", MM_HARNESS_NO_UPDATE_CHECK: "1" },
+      timeout: 6e4
+    });
+    if (check.status !== 0 || check.stdout.trim() !== version) {
+      throw new Error(`the copied harness did not run (exit ${check.status}): ${(check.stderr || check.stdout || "").trim()}`);
+    }
+    const marker = { schemaVersion: 1, key, version, source, contentSha256: contentDigest(copy), createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+    fs.writeFileSync(path.join(copy, PIN_MARKER), `${JSON.stringify(marker, null, 2)}
+`);
+    try {
+      fs.renameSync(copy, target);
+    } catch (error) {
+      if (!isPin(target)) throw error;
+      return { version, source, executable, pinned: true, created: false };
+    }
+    return { version, source, executable, pinned: true, created: true };
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+}
+function handlePin(argv) {
+  const json = argv.includes("--json");
+  try {
+    const result = pinHarness();
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "pin", status: "pass", ...result }, null, 2));
+    } else {
+      console.log(result.executable);
+      if (result.reason === "source-checkout") {
+        console.error("mm-harness pin: a source checkout is not copied; record it by its working-tree hash.");
+      }
+    }
+    return EXIT.ok;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const userAction = "install the harness globally (npm i -g @deeeed/metamask-harness), then re-run: mm-harness pin";
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "pin", status: "fail", error: { code: "PIN_FAILED", message, userAction } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness pin: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.runtime;
+  }
+}
+export {
+  handlePin,
+  pinHarness,
+  pinRoot
+};

package/dist/commands/prepare.js

@@ -10,7 +10,9 @@ import {
 import { color, stripAnsi } from "../cli-color.js";
 import { runnerProvenance } from "../doctor.js";
 import { detectAdapter } from "../harness.js";
-import { harnessExecutable, manifestPath, PREPARE_PROGRESS_ARTIFACT, recipeRuntimeDir } from "../paths.js";
+import { adapterRegistry } from "../adapters/registry.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import { harnessExecutable, PREPARE_PROGRESS_ARTIFACT, recipeRuntimeDir } from "../paths.js";
 import { optionFlag, optionString, parseArgs, targetPath, usageError } from "./parse-args.js";
 import { EXIT } from "./shared.js";
 import { formatDuration } from "./status-watch.js";
@@ -52,8 +54,8 @@ const STEP_HINT = {
   launch: "can take minutes on Mobile: Metro bundle and app start",
   fixtures: "under a minute"
 };
-function stepChain(platform) {
-  return platform === "core" ? ["doctor", "status", "verify"] : ["doctor", "status", "launch", "fixtures", "verify"];
+function stepChain(surface) {
+  return surface.headless ? ["doctor", "status", "verify"] : ["doctor", "status", "launch", "fixtures", "verify"];
 }
 function lastRunDurations(recordPath) {
   let parsed;
@@ -225,36 +227,6 @@ function readDevices(artifactsDir) {
   const devices = parsed?.devices;
   return Array.isArray(devices) ? devices : [];
 }
-function readRuntimeContextTarget(target) {
-  const file = path.join(target, recipeRuntimeDir(), "agentic-runtime.json");
-  let parsed;
-  try {
-    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-  } catch {
-    return {};
-  }
-  const record = parsed ?? {};
-  const str = (key) => typeof record[key] === "string" ? record[key] : void 0;
-  return { simulator: str("simulator"), simulatorUdid: str("simulatorUdid"), adbSerial: str("adbSerial") };
-}
-function mobilePlatformFromConfiguredTarget(env, context) {
-  const ios = Boolean(env.IOS_SIMULATOR || env.SIM_UDID || context.simulator || context.simulatorUdid);
-  const android = Boolean(
-    env.ADB_SERIAL || env.ANDROID_SERIAL || env.ANDROID_TARGET_DEVICE_NAME || env.ANDROID_DEVICE || context.adbSerial
-  );
-  if (ios === android) return void 0;
-  return ios ? "ios" : "android";
-}
-function mobilePlatformFromDevices(devices) {
-  const selected = devices.filter((device) => device?.selected === true);
-  const candidates = selected.length > 0 ? selected : devices;
-  const platforms = [
-    ...new Set(
-      candidates.map((device) => device?.platform).filter((value) => value === "ios" || value === "android")
-    )
-  ];
-  return platforms.length === 1 ? platforms[0] : void 0;
-}
 function mobileTargetAmbiguityError() {
   const choices = [
     "1. iOS     mm-harness prepare --platform mobile --mobile-platform ios",
@@ -300,8 +272,9 @@ function mobilePlatformOption(value) {
 }
 function resolvePlatform(requested, target) {
   const platform = requested ?? detectAdapter(target);
-  if (platform === "mobile" || platform === "extension" || platform === "core") {
-    return platform;
+  const surface = platform && adapterRegistry.has(platform) ? getAdapterSurface(platform) : void 0;
+  if (surface?.prepare) {
+    return surface;
   }
   throw usageError(
     `could not detect the platform of ${target}
@@ -328,21 +301,22 @@ async function handlePrepareLocked(argv) {
   const { options } = parseArgs(argv, "prepare");
   const json = optionFlag(options, "json");
   const target = targetPath(options);
-  const platform = resolvePlatform(optionString(options, "platform"), target);
+  const surface = resolvePlatform(optionString(options, "platform"), target);
+  const platform = surface.adapter;
   const artifactsDir = path.resolve(
     optionString(options, "artifactsDir") ?? path.join(target, recipeRuntimeDir())
   );
   const executable = harnessExecutable();
   const targetArgs = ["--target", target];
   const clearMetro = optionFlag(options, "clearMetro");
-  if (clearMetro && platform !== "mobile") {
+  if (clearMetro && !surface.prepare.clearMetro) {
     throw usageError(`--clear-metro is mobile only; this checkout is ${platform}
   Next: ${USAGE}`);
   }
   const remoteFlag = optionString(options, "remoteFlag");
   if (remoteFlag !== void 0) {
-    if (platform === "core") {
-      throw usageError(`--remote-flag needs an app runtime; this checkout is core
+    if (surface.headless) {
+      throw usageError(`--remote-flag needs an app runtime; this checkout is ${platform}
   Next: ${USAGE}`);
     }
     try {
@@ -357,7 +331,7 @@ async function handlePrepareLocked(argv) {
   let mobilePlatform = mobilePlatformOption(optionString(options, "mobilePlatform"));
   const recordPath = path.join(artifactsDir, READINESS_RECORD);
   const progressPath = path.join(artifactsDir, PREPARE_PROGRESS_ARTIFACT);
-  const chain = stepChain(platform);
+  const chain = stepChain(surface);
   const view = json ? void 0 : createStepView(chain, stepHints(chain, lastRunDurations(recordPath)));
   view?.begin();
   const steps = [];
@@ -406,35 +380,33 @@ async function handlePrepareLocked(argv) {
   try {
     await run("doctor", ["doctor", "--fix", "--json", "--adapter", platform, ...targetArgs]);
     await run("status", ["status", "--json", ...targetArgs]);
-    if (platform === "mobile" && !mobilePlatform && !failed()) {
-      mobilePlatform = mobilePlatformFromConfiguredTarget(process.env, readRuntimeContextTarget(target)) ?? mobilePlatformFromDevices(readDevices(artifactsDir));
+    const { devicePlatform } = surface.prepare;
+    if (devicePlatform && !mobilePlatform && !failed()) {
+      mobilePlatform = devicePlatform(target, readDevices(artifactsDir));
       if (!mobilePlatform) return ambiguousMobileTarget(json);
     }
-    if (platform === "core") {
-      const reason = "core is headless: no app surface to launch or seed";
+    if (surface.headless) {
+      const reason = `${platform} is headless: no app surface to launch or seed`;
       addStep(skippedStep("launch", `${executable} launch`, reason));
       addStep(skippedStep("fixtures", `${executable} fixtures set`, reason));
-    } else if (platform === "mobile") {
-      const device = mobilePlatform ? [mobilePlatform] : [];
+    } else {
+      const device = devicePlatform && mobilePlatform ? [mobilePlatform] : [];
       await run("launch", ["launch", ...device, ...clearMetro ? ["--clear-metro"] : [], ...remoteFlagArgs, "--verify", "--json", ...targetArgs]);
       await run("fixtures", [
         "fixtures",
         "set",
-        ...mobilePlatform ? ["--platform", mobilePlatform] : [],
+        ...device.flatMap((platformName) => ["--platform", platformName]),
         ...remoteFlagArgs,
         "--json",
         ...targetArgs
       ]);
-    } else {
-      await run("launch", ["launch", ...remoteFlagArgs, "--verify", "--json", ...targetArgs]);
-      await run("fixtures", ["fixtures", "set", ...remoteFlagArgs, "--json", ...targetArgs]);
     }
     await run("verify", ["verify", "--json", "--adapter", platform, ...targetArgs]);
   } finally {
     clearInterval(heartbeat);
     view?.end();
   }
-  const provenance = runnerProvenance(manifestPath(platform));
+  const provenance = runnerProvenance(surface.actions.manifestPath());
   const record = {
     schemaVersion: 1,
     harness: {
@@ -462,7 +434,5 @@ async function handlePrepareLocked(argv) {
 }
 export {
   handlePrepare,
-  mobilePlatformFromConfiguredTarget,
-  mobilePlatformFromDevices,
   mobileTargetAmbiguityError
 };