@deeeed/metamask-harness 0.74.0 → 0.75.0

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/run-engine.js

@@ -14,9 +14,6 @@ import {
 import { resolveActionManifest, validateManifest } from "../manifest.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { extensionProductConfigBlock } from "../adapters/extension/product-config.js";
-import {
-  requireCurrentMobileReleaseArtifactState
-} from "../adapters/mobile/release-artifact-state.js";
 import {
   importRecipeHarness,
   importRecipeProtocol,
@@ -121,13 +118,8 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
         );
       }
     } finally {
-      if (adapter === "mobile") {
-        const { hideMobileHudOnTeardown } = await import("../adapters.js");
-        await hideMobileHudOnTeardown(
-          projectRoot,
-          recipeRunEnv(adapter, runtimeOptions)
-        );
-      }
+      const teardown = getAdapterSurface(adapter).run?.teardown;
+      if (teardown) await teardown(projectRoot, recipeRunEnv(adapter, runtimeOptions));
     }
     let recordingError;
     if (executionError === void 0 && result) {
@@ -240,11 +232,12 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
     projectRoot,
     rootRecipe: recipeDocument
   });
-  const suppressHudForOpaqueMobile = adapter === "mobile" && process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
+  const surface = getAdapterSurface(adapter);
+  const suppressAutoHud = surface.run?.autoHud?.() === false;
   const runnerOptions = {
     quietStdout: runtimeOptions.stdoutIsMachineContract === true,
     suppressLibraryResolutionLogs: runtimeOptions.suppressLibraryResolutionLogs,
-    autoHud: suppressHudForOpaqueMobile ? false : trust.source && trust.source.trust !== "trusted" ? false : runtimeOptions.autoHud,
+    autoHud: suppressAutoHud ? false : trust.source && trust.source.trust !== "trusted" ? false : runtimeOptions.autoHud,
     onActionEvent: runtimeOptions.onActionEvent,
     actionSources,
     // A direct engineer invocation is the explicit trust boundary for a
@@ -256,7 +249,7 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
     ...runnerOptions,
     trustedMutation
   });
-  const useFramedExtensionRecording = adapter === "extension" && recordVideo === "full-run" && trust.source?.trust !== "untrusted" && trust.source?.trust !== "unknown" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
+  const useFramedExtensionRecording = surface.recording?.framed !== void 0 && recordVideo === "full-run" && trust.source?.trust !== "untrusted" && trust.source?.trust !== "unknown" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
   const runRequest = {
     ...recipeDocument !== void 0 ? { recipeDocument } : absoluteRecipePath ? { recipePath: absoluteRecipePath } : { recipeDocument: recipe },
     artifactsDir: absoluteArtifactsDir,
@@ -447,31 +440,22 @@ function executionLibrarySources(sources, invocationTrust) {
     };
   });
 }
+const RUN_ENV_KEYS = [
+  "CDP_PORT",
+  "RECIPE_CDP_PORT",
+  "WATCHER_PORT",
+  "METRO_PORT",
+  "METAMASK_RECIPE_EXTENSION_AUTOLAUNCH"
+];
 function activateRecipeRuntimeEnvironment(adapter, projectRoot, runtimeOptions) {
-  const previousCdpPort = process.env.CDP_PORT;
-  const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
-  const previousWatcherPort = process.env.WATCHER_PORT;
-  const previousMetroPort = process.env.METRO_PORT;
-  const previousExtensionAutolaunch = process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH;
-  const previousMobileOpaqueRuntime = process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME;
-  const previousAndroidPackageId = process.env.ANDROID_PACKAGE_ID;
-  const previousAdbSerial = process.env.ADB_SERIAL;
-  const previousAndroidSerial = process.env.ANDROID_SERIAL;
-  const explicitMobileDeviceEnv = adapter === "mobile" && process.env.MM_HARNESS_EXPLICIT_PLATFORM ? Object.fromEntries(
-    [
-      "PLATFORM",
-      "MM_HARNESS_EXPLICIT_PLATFORM",
-      "IOS_SIMULATOR",
-      "SIM_UDID",
-      "ADB_SERIAL",
-      "ANDROID_SERIAL",
-      "ANDROID_DEVICE",
-      "ANDROID_TARGET_DEVICE_NAME"
-    ].map((key) => [key, process.env[key]])
-  ) : void 0;
-  getAdapterSurface(adapter).resolveSlotPorts(projectRoot);
-  if (explicitMobileDeviceEnv) {
-    for (const [key, value] of Object.entries(explicitMobileDeviceEnv)) {
+  const surface = getAdapterSurface(adapter);
+  const previousEnv = Object.fromEntries(
+    [...RUN_ENV_KEYS, ...surface.run?.envKeys ?? []].map((key) => [key, process.env[key]])
+  );
+  const pinnedEnv = surface.run?.pinnedEnv?.();
+  surface.resolveSlotPorts(projectRoot);
+  if (pinnedEnv) {
+    for (const [key, value] of Object.entries(pinnedEnv)) {
       restoreEnv(key, value);
     }
   }
@@ -486,37 +470,9 @@ function activateRecipeRuntimeEnvironment(adapter, projectRoot, runtimeOptions)
   if (runtimeOptions.launchExistingDist) {
     process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH = "1";
   }
-  if (adapter === "mobile") {
-    const state = requireCurrentMobileReleaseArtifactState(projectRoot);
-    if (state) {
-      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;
-    }
-  }
+  surface.run?.activateEnv?.(projectRoot);
   return () => {
-    restoreEnv("CDP_PORT", previousCdpPort);
-    restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
-    restoreEnv("WATCHER_PORT", previousWatcherPort);
-    restoreEnv("METRO_PORT", previousMetroPort);
-    restoreEnv(
-      "METAMASK_RECIPE_EXTENSION_AUTOLAUNCH",
-      previousExtensionAutolaunch
-    );
-    restoreEnv(
-      "METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME",
-      previousMobileOpaqueRuntime
-    );
-    restoreEnv("ANDROID_PACKAGE_ID", previousAndroidPackageId);
-    restoreEnv("ADB_SERIAL", previousAdbSerial);
-    restoreEnv("ANDROID_SERIAL", previousAndroidSerial);
+    for (const [key, value] of Object.entries(previousEnv)) restoreEnv(key, value);
   };
 }
 function actionSourceMap(sources) {
@@ -539,42 +495,11 @@ function recipeRunEnv(adapter, runtimeOptions = {}) {
     PLATFORM: process.env.PLATFORM,
     MM_HARNESS_EXPLICIT_PLATFORM: process.env.MM_HARNESS_EXPLICIT_PLATFORM
   };
-  if (adapter !== "mobile") return base;
-  return {
-    ...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
-  };
+  const childEnv = getAdapterSurface(adapter).run?.childEnv;
+  return childEnv ? childEnv(base) : base;
 }
 async function prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions) {
-  if (adapter !== "extension" || runtimeOptions.skipExtensionRuntimePrepare === true)
-    return;
-  const { releaseArtifactState, runtimeDistCheck } = await import("../adapters/extension/runtime-decision.js");
-  const artifact = releaseArtifactState(projectRoot);
-  const runtimeSnapshot = runtimeDistCheck(projectRoot, artifact);
-  if (artifact.status !== "none") {
-    if (artifact.status === "valid" && runtimeSnapshot.status === "fresh") return;
-    throw new Error(
-      "The loaded release artifact identity is invalid or stale. Next: rerun runtime-launch with the same artifact source."
-    );
-  }
-  const { prepareExtensionRuntime } = await import("../adapters/extension/runtime.js");
-  await prepareExtensionRuntime({
-    projectRoot,
-    cdpPort: runtimeOptions.cdpPort,
-    slot: runtimeOptions.slot,
-    launchExistingDist: runtimeOptions.launchExistingDist === true,
-    validationRuntimeDir: runtimeOptions.validationRuntimeDir,
-    pageMode: "home-or-sidepanel"
-  });
+  await getAdapterSurface(adapter).run?.prepareRuntime?.(projectRoot, runtimeOptions);
 }
 function restoreEnv(key, value) {
   if (value === void 0) delete process.env[key];
@@ -1051,7 +976,15 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     return EXIT.usage;
   }
   const state = newHealState();
-  const mobileArtifact = adapter === "mobile" ? requireCurrentMobileReleaseArtifactState(target) : null;
+  const runtimeCheck = getAdapterSurface(adapter).run?.runtimeCheck?.({
+    target,
+    options,
+    heal,
+    state,
+    json,
+    appRestartAuthored: prepareOptions.appRestartAuthored,
+    onRecovery: (code) => prepareOptions.onPhase?.("recover", { code })
+  });
   prepareOptions.onPhase?.("install");
   const ensured = await ensureOverlay(
     adapter,
@@ -1089,41 +1022,8 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     return EXIT.infra;
   }
   prepareOptions.onPhase?.("healthcheck");
-  if (adapter === "extension") {
-    const previousCdpPort = process.env.CDP_PORT;
-    const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
-    const previousWatcherPort = process.env.WATCHER_PORT;
-    const explicitCdpPort = optionString(options, "cdpPort");
-    const explicitWatcherPort = optionString(options, "watcherPort") ?? optionString(options, "metroPort");
-    if (explicitCdpPort) {
-      process.env.CDP_PORT = explicitCdpPort;
-      process.env.RECIPE_CDP_PORT = explicitCdpPort;
-    }
-    if (explicitWatcherPort) process.env.WATCHER_PORT = explicitWatcherPort;
-    try {
-      const current = await ensureExtensionProofRuntime(
-        target,
-        heal,
-        state,
-        json,
-        {
-          onRecovery: (code) => prepareOptions.onPhase?.("recover", { code })
-        }
-      );
-      if (current !== null) return current;
-    } finally {
-      restoreEnv("CDP_PORT", previousCdpPort);
-      restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
-      restoreEnv("WATCHER_PORT", previousWatcherPort);
-    }
-  }
-  if (adapter === "mobile" && mobileArtifact === null && prepareOptions.skipMobileSourceFreshness !== true) {
-    const current = await ensureMobileProofRuntime(
-      target,
-      heal,
-      state,
-      json
-    );
+  if (runtimeCheck) {
+    const current = await runtimeCheck();
     if (current !== null) return current;
   }
   return { state, heal };
@@ -1372,7 +1272,7 @@ async function executeWithHealBounds(exec, target, state) {
   };
 }
 function emitHealViolation(json, command, result, violation, state, adapter) {
-  const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? "for signing, configure a reserved wallet-fixture.json account and pass its non-empty name; an explicit 0x address is supported only by read-only actions" : violation.userAction ?? `inspect ${shellQuoteArg(result.summaryPath)} and ${shellQuoteArg(result.tracePath)}; fix the application or recipe failure before retrying`;
+  const userAction = (adapter ? getAdapterSurface(adapter).run?.violationUserAction?.(violation) : void 0) ?? violation.userAction ?? `inspect ${shellQuoteArg(result.summaryPath)} and ${shellQuoteArg(result.tracePath)}; fix the application or recipe failure before retrying`;
   if (json) {
     console.log(
       JSON.stringify(

package/dist/commands/run-report.js

@@ -1,8 +1,7 @@
 import fs from "node:fs";
-import { createRequire } from "node:module";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
-import { recipeRuntimeDir } from "../paths.js";
+import { getAdapterSurface } from "../adapters/surface.js";
 import { isRecord } from "./parse-args.js";
 function writeRunReport(result) {
   const summaryPath = String(result.summaryPath);
@@ -95,33 +94,6 @@ function indexProductProvenanceArtifact(artifactManifestPath, target, adapter, b
 `
   );
 }
-function readRecord(file) {
-  try {
-    const recorded = JSON.parse(fs.readFileSync(file, "utf8"));
-    return isRecord(recorded) ? recorded : null;
-  } catch {
-    return null;
-  }
-}
-const browserCdp = createRequire(import.meta.url)("../../adapters/shared/browser-cdp.cjs");
-function verifyLaunch(record, cdpPort) {
-  const launch = isRecord(record.launch) ? record.launch : {};
-  const pid = Number(launch.pid);
-  const port = Number(launch.cdpPort);
-  if (!Number.isInteger(pid) || !Number.isInteger(port) || typeof launch.profile !== "string" || typeof launch.processStartedAt !== "string") {
-    return "the browser record has no process identity (pid, start time, profile, CDP port)";
-  }
-  if (cdpPort && port !== Number(cdpPort)) return `the browser record is for CDP port ${port}, not ${cdpPort}`;
-  try {
-    const owner = browserCdp.cdpOwner(port, launch.profile);
-    if (owner.pid !== pid || owner.startedAt !== launch.processStartedAt) {
-      return `CDP port ${port} is now held by another browser process than the recorded pid ${pid}`;
-    }
-  } catch (error) {
-    return error instanceof Error ? error.message : String(error);
-  }
-  return null;
-}
 function resolveTemplatedPort(value, params, recipe) {
   let resolved = value;
   const template = /^\{\{\s*params\.([\w-]+)\s*\}\}$/u.exec(String(value).trim());
@@ -155,26 +127,11 @@ function recipeCdpPorts(request) {
   return [...ports];
 }
 function executedBrowser(adapter, target, artifactManifestPath, ports) {
-  if (adapter !== "extension") return null;
+  const launched = getAdapterSurface(adapter).run?.launchedBrowser;
+  if (!launched) return null;
   if (ports.length === 0) return { boundTo: "none", reason: "the run had no known CDP port" };
   if (ports.length > 1) return { boundTo: "none", reason: `the run drove several CDP ports (${ports.join(", ")})` };
-  return launchedBrowser(target, path.dirname(artifactManifestPath), ports[0]);
-}
-function launchedBrowser(target, artifactsDir, cdpPort) {
-  const runtime = readRecord(path.join(artifactsDir, "extension-runtime", "runtime.json"));
-  const autolaunched = runtime && isRecord(runtime.browser) ? runtime.browser : null;
-  const candidates = [];
-  if (autolaunched) candidates.push([autolaunched, "run-autolaunch"]);
-  const slot = readRecord(path.join(path.resolve(target), recipeRuntimeDir(), "browser-resolution.json"));
-  if (slot) candidates.push([slot, "slot-runtime"]);
-  if (candidates.length === 0) return null;
-  const reasons = [];
-  for (const [record, boundTo] of candidates) {
-    const problem = verifyLaunch(record, cdpPort);
-    if (problem === null) return { ...record, boundTo };
-    reasons.push(`${boundTo}: ${problem}`);
-  }
-  return { boundTo: "none", reason: reasons.join("; ") };
+  return launched(target, path.dirname(artifactManifestPath), ports[0]);
 }
 function renderRunReport(summary, entries) {
   const lines = [
@@ -279,7 +236,6 @@ function indexRunReportArtifact(artifactManifestPath) {
 export {
   executedBrowser,
   indexProductProvenanceArtifact,
-  launchedBrowser,
   recipeCdpPorts,
   writeRunReport
 };

package/dist/commands/run.js

@@ -28,8 +28,6 @@ import {
 import { handleDescribeRecipe, handleListExecutables } from "./list-executables.js";
 import { applyDeviceTargeting } from "./device-target.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { coreDependencyBlock } from "./core-readiness.js";
-import { readMobileReleaseArtifactState } from "../adapters/mobile/release-artifact-state.js";
 import {
   indexProductProvenanceArtifact,
   writeRunReport
@@ -244,7 +242,10 @@ async function handleRunInner({ positional, options }, stream) {
       actionLibraryContextArgs(validated.librarySources)
     );
   }
-  const depsBlock = adapter === "core" && await recipeUsesCoreController(validated.recipe, validated.librarySources) ? coreDependencyBlock(target) : null;
+  const depsBlock = await getAdapterSurface(adapter).run?.dependencyBlock?.(target, {
+    recipe: validated.recipe,
+    librarySources: validated.librarySources
+  }) ?? null;
   if (depsBlock) {
     return emitRunUsageError(jsonOutput, stream, adapter, validated.recipeFile, depsBlock.code, depsBlock.message, depsBlock.userAction);
   }
@@ -295,8 +296,7 @@ async function handleRunInner({ positional, options }, stream) {
   }
   try {
     const prepared = await prepareHeal(adapter, target, options, machine, {
-      onPhase: (phase, fields) => stream.phase(phase, fields),
-      skipMobileSourceFreshness: adapter === "mobile" && readMobileReleaseArtifactState(target) !== null
+      onPhase: (phase, fields) => stream.phase(phase, fields)
     });
     if (typeof prepared === "number") {
       stream.error({
@@ -511,48 +511,6 @@ function formatPreviewLine(line, out) {
   const rest = match[2];
   return `${out(status === "PASS" ? "ok" : "err", status)} ${rest}`;
 }
-async function recipeUsesCoreController(recipe, librarySources) {
-  if (objectUsesCoreController(recipe)) return true;
-  const refs = collectCallRefs(recipe);
-  if (refs.length === 0) return false;
-  const sources = librarySources ?? [];
-  if (sources.length === 0) return false;
-  const { loadRecipeLibraries } = await import("@farmslot/recipe-harness");
-  const recipes = (await loadRecipeLibraries(sources, { adapter: "core" })).recipes;
-  const visited = /* @__PURE__ */ new Set();
-  const visit = (ref) => {
-    if (visited.has(ref)) return false;
-    visited.add(ref);
-    const dependency = recipes.get(ref);
-    if (!dependency) return false;
-    if (objectUsesCoreController(dependency.document)) return true;
-    return collectCallRefs(dependency.document).some(visit);
-  };
-  return refs.some(visit);
-}
-function objectUsesCoreController(value) {
-  if (Array.isArray(value)) return value.some(objectUsesCoreController);
-  if (!isRecord(value)) return false;
-  if (actionUsesCoreController(value.action)) return true;
-  return Object.values(value).some(objectUsesCoreController);
-}
-function collectCallRefs(value) {
-  const refs = [];
-  const visit = (node) => {
-    if (Array.isArray(node)) {
-      for (const item of node) visit(item);
-      return;
-    }
-    if (!isRecord(node)) return;
-    if (node.action === "call" && typeof node.ref === "string" && node.ref) refs.push(node.ref);
-    for (const child of Object.values(node)) visit(child);
-  };
-  visit(value);
-  return [...new Set(refs)];
-}
-function actionUsesCoreController(action) {
-  return typeof action === "string" && action.startsWith("metamask.perps.");
-}
 async function handleRunPlan(recipeArg, params, options, stream) {
   const json = optionFlag(options, "json");
   const jsonOutput = json && !stream.enabled;
@@ -635,7 +593,7 @@ async function handleRunPlan(recipeArg, params, options, stream) {
       status: "planned",
       detail: "would auto-ensure the runtime overlay if missing (install phase)"
     },
-    ...adapter === "core" ? [] : [
+    ...getAdapterSurface(adapter).headless ? [] : [
       {
         step: "launch.app",
         confidence: "conditional",

package/dist/doctor.js

@@ -10,6 +10,7 @@ import {
 } from "../library/actions/mobile/platform/tool-paths.mjs";
 import { mobilePerpsEnvironment } from "./adapters/mobile/perps-env.js";
 import { readRuntimeContextField, resolveRuntimeContextPath } from "./harness.js";
+import { isPin } from "./harness-pin.js";
 import { harnessExecutable, manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "./paths.js";
 function requiredDoctorCheckSummary(checks) {
   const required = checks.filter((check) => check.required);
@@ -281,6 +282,7 @@ function mobileToolDoctorChecks(platform) {
   });
 }
 function runnerInstallKind(runnerRoot, invokedPath, executablePath) {
+  if (isPin(runnerRoot)) return "pinned-install";
   const normalizedRoot = path.normalize(runnerRoot);
   const nodeModulesSegment = `${path.sep}node_modules${path.sep}`;
   const globalNodeModulesSegment = `${path.sep}lib${path.sep}node_modules${path.sep}`;
@@ -315,7 +317,7 @@ function runnerProvenance(actionManifestPath) {
   const executablePath = harnessExecutable();
   const invokedPath = path.resolve(process.env.MM_HARNESS_INVOKED_AS ?? executablePath);
   const installKind = runnerInstallKind(runnerDir, invokedPath, executablePath);
-  const packageSource = runnerDir.includes(`${path.sep}node_modules${path.sep}`) ? "node_modules" : "source-checkout";
+  const packageSource = isPin(runnerDir) ? "pin" : runnerDir.includes(`${path.sep}node_modules${path.sep}`) ? "node_modules" : "source-checkout";
   return {
     name: "@metamask/recipe-runner",
     packageName,