@deeeed/metamask-harness 0.82.0 → 0.83.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.83.0 - 2026-10-07
+
+### Added
+
+- Site: a zoomable platform map (`site/platform.html`) of the recipe platform layers, from the Farmslot runner and adapter packages to mm-harness, recipe libraries and plugins and the Farmslot pieces that call it, with packages, versions and four request flows; linked from the front page, Architecture and Repositories.
+
+### Changed
+
+- The Core adapter is a MetaMask preset over `@farmslot/adapter-node` 0.1.2. The headless lifecycle, the runtime context and the overlay cleanup leaf come from the package (`adapters/core/cleanup.sh` runs its `scripts/cleanup.sh --adapter core`). Live scripts import every workspace package the checkout declares from source, through the package's tsconfig paths; that replaces four listed packages, so a stale `dist/` or a package that moved into the monorepo no longer breaks `metamask.perps.*`. mm-harness keeps Core's detection, wording, actions, install leaf, fixtures, and its dependency gate (`run`, `call`, `doctor` and `verify` still agree on `core-controller-actions`). Messages and codes are unchanged.
+- Depend on `@farmslot/recipe-cli` 0.8.0 and `@farmslot/adapter-sdk` 0.6.0 (were 0.6.0 and 0.5.0), which classify an adapter's declared environment failures and forward a parent signal that arrives while a script's leaf starts, on `@farmslot/recipe-runner` 0.26.0, `@farmslot/adapter-rn` 0.18.0 and `@farmslot/adapter-web` 0.4.1 (were 0.25.0, 0.17.1 and 0.3.1), and on `@farmslot/adapter-node` 0.1.2 (new). The frame-metric helpers now come from `@farmslot/recipe-runner/runtime/cdp-trace`, where adapter-rn 0.18.0 moved them. `@farmslot/agent-runtime` 0.17.0 and `@farmslot/protocol` 0.34.0 are unchanged, and the install still holds one `@farmslot/recipe-runner`.
+- Performance and network observation run on Farmslot (Farmslot #830, #834): the CDP trace collector and parser and the JavaScript-task and frame summaries come from `@farmslot/recipe-runner/runtime/cdp-trace`, and the Extension performance and network observers from `@farmslot/adapter-web/performance-observer` and `/network-observer`. `src/adapters/extension/{browser-cdp,performance-observer}.ts`, `src/adapters/performance/{cdp-trace,js-task-metrics}.ts` and `src/async.ts` are gone. mm-harness keeps the MetaMask parts: `TRACE_KINDS` per platform (`src/adapters/performance/trace-kinds.ts`), the `mmh-clock-` marker prefix, the traced UI pages (`/home.html`, then `/sidepanel.html`), `CDP_PORT` and the extension id. The network observer now gets that id too (on `web-dapp`, from the manifest key of the dist the browser loaded), so a component extension that Chrome lists first is never captured instead of MetaMask. Artifacts are unchanged. Two Extension performance errors now say "extension UI target" instead of "MetaMask UI target", and a CDP port that does not answer fails with adapter-web's connection error after retrying for 10 seconds.
+
+### Fixed
+
+- A plugin that extends `web-dapp` can no longer bind a venue policy outside its own code. The policy module and every file it imports must be files the plugin digest covers (the loader's file list for the plugin, by real path: the module's directory and the library's `actions/`), imported by literal relative path or as node built-ins. Anything else refuses the plugin with `ADAPTER_PLUGIN_INVALID` before any policy code runs. The digest of those files goes in `RECIPE_WEB_DAPP_POLICY_DIGEST`, and every process that loads the policy refuses files that changed since the command bound it. A refusal from a plugin's own checks is no longer mistaken for one from a built-in.
+- `--adapter terminal` (or `--platform terminal`) without the Terminal recipe library is no longer reported as a typo. It fails with `CLI_ADAPTER_LIBRARY_MISSING`, names `MetaMask/experimental-metamask-recipe-terminal` (at a revision whose `recipe-library.json` declares `adapters.terminal`) and gives the command again with the library on `RECIPE_LIBRARY_PATH`. When `RECIPE_LIBRARY_PATH` already holds an older checkout of that library (named `terminal`, or holding `recipes/terminal`), it says to update that checkout. Other unknown ids are still `CLI_INVALID_OPTION_VALUE`.
+- Core `doctor` and `verify` import the Perps controller the way `metamask.perps.*` actions do (a new required `core-controller-import` check, bounded to 60 s, run once the dependency gate passes). A partial workspace build (a package whose `dist/` is missing) used to pass readiness and then fail the first action; it now fails readiness, naming the missing module, with `cd <core> && yarn build`, and Core's runtime status reports `blocked` (`CORE_CONTROLLER_IMPORT_FAILED`) so `--print-ready`, `--expect-live` and `--fix` agree. The probe runs once per command, in its own process group, and a timeout, or a signal that ends the command, kills the whole tree. When an action still hits a missing module, Core's live adapter prints `[core/perps] environment: cannot resolve …` with the same build step, and `run`/`call` classify it `ENVIRONMENT_NOT_READY` (exit 4) instead of `APP_LOGIC_FAILURE`.
+- The Extension validation browser that `run --launch-existing-dist` opens now seeds the slot's wallet fixture (it launches its fresh profile with `--reset-profile`); it used to open on onboarding with no wallet. A seeded launch still on onboarding after a 5-second re-check fails with `FIXTURE_SEED_NOT_APPLIED` instead of running on an empty wallet. Runs that attach to an existing runtime, and `fixtures set`, are not gated; under `--launch-existing-dist` an onboarding recipe now starts from the seeded wallet.
+- Extension `fixtures set|reset` no longer swaps a selected release artifact for the checkout build. It used to report pass after relaunching `dist/chrome`, and the next action failed with `EXTENSION_RUNTIME_NOT_CURRENT` and a checkout-rebuild hint. While an artifact is recorded, valid or not, it now refuses before touching the browser with `FIXTURES_ARTIFACT_ACTIVE`, exit 1. For a valid artifact, `Next:` re-selects it (archive, version, SHA-256, cache, profile) with `--reset-profile`, then runs `wallet.import method=ui credential_source=fixture`, so exported `MM_HARNESS_WALLET_*` values can't import another wallet. A `--fixture`/`RECIPE_WALLET_FIXTURE` that isn't the canonical fixture is published first with `fixtures init --from <path> --force`, and the message names the slot's canonical fixture that it replaces. When the recorded archive no longer exists, `Next:` asks for it (`--artifact-file <path-to-the-artifact-zip>`) instead of printing a command that would fail. `userAction` and `Next:` are each one runnable command line. For a valid artifact, the checkout route (`runtime-launch` without an artifact, which drops the artifact record, then `fixtures set`) is offered separately, as `error.alternatives` in JSON and an `Or:` line in human output; for an invalid record it is the `Next:` itself. Commands are shell-quoted. Checkout launches are unchanged. Extension `wallet.import method=ui` also recovers the wallet locking right after onboarding (seen on a fresh 13.51.0 artifact profile while the sidepanel attaches). It used to fail the account search with `could not enter the derived release identity (route "#/unlock")`. After the usual unlock of a profile that starts locked, a relock during the account proof is unlocked once more with the fixture password and reported as `relockRecovered: true`; a further lock still fails with that route error. The visible account search also re-enters a search value that the account list drops right after onboarding (it failed with `could not enter the alternate-address control (route "#/account-list")`), in place and within the same deadline. It stops at once if the page leaves the list, and the error now names the last input failure, with addresses redacted. The no-match control and the exact match are still required.
+
+## 0.82.1 - 2026-10-07
+
+### Fixed
+
+- Extension `check diff [--fix]` no longer fails when every changed file is one the repo's oxfmt config ignores (for example `package.json`, `yarn.lock` and regenerated LavaMoat policy JSON): oxfmt runs with `--no-error-on-unmatched-pattern`, so it checks nothing instead of exiting 2 with "Expected at least one target file". A real formatting problem in a file oxfmt does check still fails the gate.
+
 ## 0.82.0 - 2026-10-07
 
 ### Added

package/adapters/core/cleanup.sh

@@ -3,35 +3,11 @@
 #
 # Inputs: --target <metamask-core> (default $PWD); env RECIPE_HARNESS_ROOT.
 # Outputs: removes <harness>/core. Exit 0 — cleaned (idempotent); 2 — bad args.
-# Never touches: product files (core install patches nothing).
-#
-# Core injects nothing into the product checkout, so cleanup only removes the
-# ignored overlay directory temp/recipe/harness/core. There are no backups to
-# restore and no patched product files. Idempotent: a missing overlay is a
-# success, not an error.
+# Binding: runs @farmslot/adapter-node's scripts/cleanup.sh --adapter core.
 set -euo pipefail
-
-TARGET="$PWD"
-while [ "$#" -gt 0 ]; do
-  case "$1" in
-    --target) TARGET="$2"; shift 2 ;;
-    -h|--help) echo "Usage: cleanup.sh (core) [--target <metamask-core>]"; exit 0 ;;
-    *) echo "Unknown arg: $1" >&2; exit 2 ;;
-  esac
-done
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TARGET="$(cd "$TARGET" && pwd)"
-# shellcheck disable=SC1091
-for _hp in "$SCRIPT_DIR/../shared/harness-path.sh"; do
-  [ -f "$_hp" ] && { . "$_hp"; break; }
-done
-unset _hp
-if ! command -v harness_root >/dev/null 2>&1; then
-  echo "mm-harness: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
+NODE_CLEANUP="$(cd "$SCRIPT_DIR" && node -p "require.resolve('@farmslot/adapter-node/scripts/cleanup.sh')")" || {
+  echo "cleanup.sh: @farmslot/adapter-node is not installed next to the runner; reinstall the runner." >&2
   exit 1
-fi
-HARNESS_DIR="$(harness_dir "$TARGET" core)"
-
-rm -rf "$HARNESS_DIR"
-echo "Cleaned core recipe harness from $TARGET"
+}
+exec bash "$NODE_CLEANUP" --adapter core "$@"

package/adapters/core/controller-import-probe.mjs

@@ -0,0 +1,26 @@
+// controller-import-probe — import what Core's metamask.perps.* live scripts
+// import (the checkout's perps-controller and messenger sources), under the same
+// tsx environment, and report the outcome as one JSON line on stdout.
+//
+// Inputs:  argv[2] = the core checkout. Run by `doctor` (readiness), never by a recipe.
+// Outputs: {"ok":true} or {"ok":false,"code":…,"url":…,"message":…}; exit 0 either way (2: no checkout).
+// Never touches: the checkout (import only, no controller is constructed).
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const root = process.argv[2];
+if (!root || root === '--help' || root === '-h') {
+  console.log('Usage: controller-import-probe.mjs <core-checkout>   (run under the actions\' tsx env by doctor)');
+  process.exit(root ? 0 : 2);
+}
+try {
+  await Promise.all([
+    import(pathToFileURL(path.join(root, 'packages/perps-controller/src/index.ts')).href),
+    import(pathToFileURL(path.join(root, 'packages/messenger/src/index.ts')).href),
+  ]);
+  process.stdout.write(`${JSON.stringify({ ok: true })}\n`);
+} catch (error) {
+  process.stdout.write(
+    `${JSON.stringify({ ok: false, code: error?.code ?? null, url: error?.url ?? null, message: String(error?.message ?? error) })}\n`,
+  );
+}

package/adapters/manifest.json

@@ -386,6 +386,14 @@
       "inputs": "--target; env RECIPE_HARNESS_ROOT",
       "outputs": "removes <harness>/core; exit 0/2"
     },
+    {
+      "id": "core/controller-import-probe",
+      "entry": "adapters/core/controller-import-probe.mjs",
+      "kind": "node",
+      "purpose": "Import the checkout's Perps controller and messenger sources the way metamask.perps.* actions do; run by doctor's core-controller-import check under the actions' tsx env.",
+      "inputs": "<core-checkout>",
+      "outputs": "one JSON line {ok,code,url,message} on stdout; exit 0 (2: no checkout)"
+    },
     {
       "id": "lib/harness-path",
       "entry": "adapters/shared/harness-path.sh",
@@ -687,6 +695,14 @@
       "inputs": "env RECIPE_WEB_DAPP_POLICY",
       "outputs": "webDappPolicy(), webDappAdapterId()"
     },
+    {
+      "id": "web-dapp/lib-policy-fence",
+      "entry": "adapters/web-dapp/lib/policy-fence.mjs",
+      "kind": "lib",
+      "purpose": "Checks the venue policy a plugin binds: the policy and every file it imports must be files the plugin digest covers (its module's directory or the library's actions/), imported by literal relative path or as node built-ins. Records their digest in RECIPE_WEB_DAPP_POLICY_DIGEST; a process loading the policy refuses files that changed since.",
+      "inputs": "policy path, plugin library root and module; env RECIPE_WEB_DAPP_POLICY_DIGEST",
+      "outputs": "fencePolicy(), assertPolicyDigest(), PolicyFenceError"
+    },
     {
       "id": "web-dapp/surface",
       "entry": "src/adapters/web-dapp/surface.ts",

package/adapters/web-dapp/lib/policy-fence.mjs

@@ -0,0 +1,119 @@
+// The venue policy module runs outside the plugin loader's import fence: the
+// host and every web-dapp leaf process require it by path. So mm-harness checks
+// it itself when it binds the adapter: the policy file and everything it
+// imports must be files the plugin digest covers (the loader's
+// libraryAdapterFiles, by real path), and imports must be literal relative
+// paths or node built-ins. The digest of those files goes in
+// RECIPE_WEB_DAPP_POLICY_DIGEST, and a process that loads the policy with it
+// set refuses files that changed since.
+
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { isBuiltin } from 'node:module';
+import path from 'node:path';
+
+export const POLICY_DIGEST_ENV = 'RECIPE_WEB_DAPP_POLICY_DIGEST';
+
+export class PolicyFenceError extends Error {
+  constructor(message) {
+    super(message);
+    this.code = 'ADAPTER_PLUGIN_INVALID';
+    this.userAction =
+      'keep the venue policy and every file it imports in the plugin module\'s directory (or the library\'s actions/), importing node built-ins and literal relative paths only';
+  }
+}
+
+const STATIC_IMPORT = /(?:^|[\s;])(?:import|export)\b[^'"`;]*?\bfrom\s*(['"])([^'"]+)\1/gu;
+const BARE_IMPORT = /(?:^|[\s;])import\s*(['"])([^'"]+)\1/gu;
+const LITERAL_CALL = /(?<![.\w$])(?:import|require)\s*\(\s*(['"])([^'"]+)\1\s*\)/gu;
+const ANY_CALL = /(?<![.\w$])(?:import|require)\s*\(/gu;
+
+// Whole-line comments may mention imports and are dropped. Nothing else is: a
+// block or trailing comment that mentions an import is read as one and refused,
+// so the scan errs on the side of refusing, never of missing an import.
+function stripComments(source) {
+  return source.replace(/^\s*\/\/.*$/gmu, '');
+}
+
+function specifiers(source, file) {
+  const code = stripComments(source);
+  const found = [];
+  for (const pattern of [STATIC_IMPORT, BARE_IMPORT, LITERAL_CALL]) {
+    for (const match of code.matchAll(pattern)) found.push(match[2]);
+  }
+  const literalCalls = [...code.matchAll(LITERAL_CALL)].length;
+  if ([...code.matchAll(ANY_CALL)].length > literalCalls) {
+    throw new PolicyFenceError(`web-dapp venue policy file ${file} imports or requires a computed specifier, which mm-harness can't check.`);
+  }
+  return found;
+}
+
+function realFile(file) {
+  try {
+    const real = fs.realpathSync(file);
+    if (fs.statSync(real).isFile()) return real;
+  } catch {
+    // reported below
+  }
+  return undefined;
+}
+
+/**
+ * The real paths of the policy module and every file it imports, in import
+ * order. `allowed(real)` decides each file; relative specifiers resolve
+ * against the importer's real path, as Node does.
+ */
+function policyClosure(file, allowed) {
+  const start = realFile(path.resolve(file));
+  if (!start) throw new PolicyFenceError(`web-dapp venue policy file ${file} does not exist.`);
+  const seen = new Set();
+  const visit = (real) => {
+    if (seen.has(real)) return;
+    allowed(real);
+    seen.add(real);
+    for (const specifier of specifiers(fs.readFileSync(real, 'utf8'), real)) {
+      if (specifier.startsWith('node:') || isBuiltin(specifier)) continue;
+      if (!specifier.startsWith('./') && !specifier.startsWith('../')) {
+        throw new PolicyFenceError(`web-dapp venue policy file ${real} imports '${specifier}', which is neither a node built-in nor a relative path the plugin digest covers.`);
+      }
+      const target = realFile(path.resolve(path.dirname(real), specifier));
+      if (!target) throw new PolicyFenceError(`web-dapp venue policy file ${real} imports '${specifier}', which does not resolve to a file.`);
+      visit(target);
+    }
+  };
+  visit(start);
+  return [...seen];
+}
+
+function digestFiles(files) {
+  const hash = createHash('sha256');
+  for (const file of [...files].sort()) {
+    hash.update(file).update('\0').update(fs.readFileSync(file)).update('\0');
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * Check a policy module against `covered`, the real paths of the files the
+ * plugin digest covers, and return the digest of the policy's files. Throws
+ * PolicyFenceError when one of them is not covered.
+ */
+export function fencePolicy({ file, covered, scope }) {
+  const allowed = (real) => {
+    if (!covered.has(real)) {
+      throw new PolicyFenceError(`web-dapp venue policy file ${real} is outside the files the plugin digest covers (${scope}).`);
+    }
+  };
+  return digestFiles(policyClosure(file, allowed));
+}
+
+/** Refuse a policy whose files changed since mm-harness bound it (`digest`). */
+export function assertPolicyDigest(file, digest) {
+  const now = digestFiles(policyClosure(file, () => {}));
+  if (now !== digest) {
+    throw new Error(
+      `web-dapp venue policy ${file} or a file it imports changed since mm-harness bound it.\n` +
+      'Next: rerun the command, so it binds and checks the policy again.',
+    );
+  }
+}

package/adapters/web-dapp/lib/policy.mjs

@@ -7,6 +7,8 @@
 import { createRequire } from 'node:module';
 import path from 'node:path';
 
+import { POLICY_DIGEST_ENV, assertPolicyDigest } from './policy-fence.mjs';
+
 export const POLICY_ENV = 'RECIPE_WEB_DAPP_POLICY';
 // The policy contract this web-dapp reads; a policy declares the version it was written for.
 export const POLICY_VERSION = 1;
@@ -66,9 +68,12 @@ export function webDappPolicy(env = process.env) {
       'Next: put the library that declares it on RECIPE_LIBRARY_PATH and pass its id, e.g. --adapter terminal.',
     );
   }
-  if (loaded?.file !== file) {
+  const digest = env[POLICY_DIGEST_ENV];
+  if (loaded?.file !== file || loaded.digest !== digest) {
+    // The digest mm-harness took when it bound the policy: refuse files that changed since.
+    if (digest) assertPolicyDigest(file, digest);
     // The policy module uses node built-ins only and has no top-level await, so it loads synchronously.
-    loaded = { file, policy: checkPolicy(createRequire(import.meta.url)(path.resolve(file)).policy, file) };
+    loaded = { file, digest, policy: checkPolicy(createRequire(import.meta.url)(path.resolve(file)).policy, file) };
   }
   return loaded.policy;
 }

package/dist/adapters/core/actions.js

@@ -11,9 +11,6 @@ const coreActions = {
   ],
   // read_account and quote_fees are Core's alone, and only its live adapter implements them.
   liveOnly: ["metamask.perps.read_account", "metamask.perps.quote_fees"],
-  tsxLiveScripts: {
-    env: async (projectRoot, tempDir) => (await import("./live-script-env.js")).coreLiveScriptEnv(projectRoot, tempDir)
-  },
   // Core declares no cdp.target; the probe matches the Extension's.
   cdpTarget: { transport: "chrome-extension-cdp", probePath: "json/version" },
   // ensure_positions and ensure_orders with an open or present state place an order.

package/dist/adapters/core/overlay.js

@@ -23,12 +23,8 @@ Next: mm-harness install --platform core --target ${target}`
     return { command: delegate, prefixArgs: ["doctor", "--adapter", "core"] };
   }
 };
-const coreRuntimeContext = {
-  forbiddenFields: ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"]
-};
 const corePrepare = {};
 export {
   coreHarness,
-  corePrepare,
-  coreRuntimeContext
+  corePrepare
 };

package/dist/adapters/core/readiness.js

@@ -1,11 +1,140 @@
+import { spawn } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { coreDependencyBlock } from "../../commands/core-readiness.js";
+import { shellQuote } from "@farmslot/recipe-cli/harness";
 import { resolveLiveTsx } from "../../live-tsx.js";
+import { runnerDir } from "../../paths.js";
 const coreReadiness = {
   compatibilityMode: (target) => fs.existsSync(path.join(target, "packages/perps-controller/src/index.ts")) ? "headless controller (no bridge)" : "unsupported/no bridge",
-  checks: (target) => [coreControllerActionsCheck(target)]
+  checks: (target) => [coreControllerActionsCheck(target)],
+  // Installed dependencies and a tsx are not enough: a partial workspace build
+  // can still leave the controller unimportable. Import it the way the actions
+  // do, once the cheaper gate passes. runtimeStatus asks the same question, so
+  // --print-ready, --expect-live and verify agree.
+  liveChecks: async (target) => coreDependencyBlock(target) ? [] : [coreControllerImportCheck(await coreControllerImport(target))],
+  // doctor --fix cannot build the workspace: an unimportable controller stays failed.
+  runtimeBlock: (_target, runtime) => runtime?.reasonCode === "CORE_CONTROLLER_IMPORT_FAILED" ? { id: "core-controller-import", userAction: runtime.nextAction } : void 0
 };
+const CONTROLLER_IMPORT_TIMEOUT_MS = 6e4;
+const PARENT_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+function isProbeReport(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const report = value;
+  const optionalString = (field) => field === void 0 || field === null || typeof field === "string";
+  return typeof report.ok === "boolean" && optionalString(report.code) && optionalString(report.url) && (report.message === void 0 || typeof report.message === "string");
+}
+function coreRebuildAction(target) {
+  return `cd ${shellQuote(path.resolve(target))} && yarn build`;
+}
+const controllerImports = /* @__PURE__ */ new Map();
+function coreControllerImport(target) {
+  const key = path.resolve(target);
+  let result = controllerImports.get(key);
+  if (!result) {
+    result = probeControllerImport(key);
+    controllerImports.set(key, result);
+  }
+  return result;
+}
+async function probeControllerImport(target) {
+  const runner = resolveLiveTsx(target);
+  if (!runner) return { ok: false, reason: "no tsx runtime found" };
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "mm-harness-core-probe-"));
+  let cancelledBy;
+  try {
+    const { coreSurface } = await import("./surface.js");
+    const env = { ...process.env, ...await coreSurface.actions.tsxLiveScripts?.env(target, tempDir) };
+    const probe = path.join(runnerDir, "adapters/core/controller-import-probe.mjs");
+    const run = await runBounded(runner.bin, [probe, target], target, env);
+    cancelledBy = run.cancelledBy;
+    if (run.spawnError) {
+      return { ok: false, reason: `tsx (${runner.source}) ${runner.bin} could not start: ${run.spawnError.code ?? run.spawnError.message}`, code: run.spawnError.code };
+    }
+    if (run.timedOut) {
+      return {
+        ok: false,
+        reason: `importing the Perps controller took over ${CONTROLLER_IMPORT_TIMEOUT_MS / 1e3}s`,
+        userAction: coreRebuildAction(target)
+      };
+    }
+    const line = run.stdout.trim().split("\n").at(-1) ?? "";
+    let parsed;
+    if (line.startsWith("{")) {
+      try {
+        parsed = JSON.parse(line);
+      } catch (error) {
+        if (!(error instanceof SyntaxError)) throw error;
+      }
+    }
+    const report = isProbeReport(parsed) ? parsed : void 0;
+    if (!report || run.exitCode !== 0) {
+      return { ok: false, reason: `tsx (${runner.source}) ${runner.bin} did not run the controller import probe (exit ${run.exitCode ?? "signal"})` };
+    }
+    if (report.ok) return { ok: true };
+    const missingModule = report.code === "ERR_MODULE_NOT_FOUND" || report.code === "MODULE_NOT_FOUND";
+    const detail = report.url ?? report.message?.split("\n")[0];
+    return {
+      ok: false,
+      reason: missingModule ? `a module is missing (${detail})` : String(detail),
+      code: report.code ?? void 0,
+      userAction: coreRebuildAction(target)
+    };
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    if (cancelledBy) process.kill(process.pid, cancelledBy);
+  }
+}
+function coreControllerImportCheck(result) {
+  const id = "core-controller-import";
+  if (result.ok) {
+    return { id, status: "pass", required: true, message: "the Perps controller imports under the action runtime." };
+  }
+  return {
+    id,
+    status: "fail",
+    required: true,
+    message: `metamask.perps.* actions cannot import the Perps controller: ${result.reason}.`,
+    ...result.code ? { detail: result.code } : {},
+    ...result.userAction ? { userAction: result.userAction } : {}
+  };
+}
+function runBounded(bin, args, cwd, env) {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { cwd, env, stdio: ["ignore", "pipe", "ignore"], detached: true });
+    let stdout = "";
+    let timedOut = false;
+    let cancelledBy;
+    const killGroup = () => {
+      if (child.pid === void 0) return;
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch (error) {
+        if (error.code !== "ESRCH") throw error;
+      }
+    };
+    const onSignal = (signal) => {
+      cancelledBy ??= signal;
+      killGroup();
+    };
+    for (const signal of PARENT_SIGNALS) process.on(signal, onSignal);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup();
+    }, CONTROLLER_IMPORT_TIMEOUT_MS);
+    const settle = (run) => {
+      clearTimeout(timer);
+      for (const signal of PARENT_SIGNALS) process.off(signal, onSignal);
+      resolve({ ...run, ...cancelledBy ? { cancelledBy } : {} });
+    };
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.on("error", (error) => settle({ stdout, exitCode: null, timedOut: false, spawnError: error }));
+    child.on("close", (code) => settle({ stdout, exitCode: code, timedOut }));
+  });
+}
 function coreControllerActionsCheck(target) {
   const block = coreDependencyBlock(target);
   if (block) {
@@ -31,5 +160,7 @@ function coreControllerActionsCheck(target) {
   };
 }
 export {
-  coreReadiness
+  coreControllerImport,
+  coreReadiness,
+  coreRebuildAction
 };

package/dist/adapters/core/surface.js

@@ -1,20 +1,50 @@
-import { shellQuote } from "@farmslot/recipe-cli/harness";
 import path from "node:path";
-import { depsCheck } from "@farmslot/recipe-runner/runtime/deps-readiness";
+import { checkoutWorkspacePackages, createNodeAdapter } from "@farmslot/adapter-node";
 import { defineAdapter } from "@farmslot/adapter-sdk";
+import { shellQuote } from "@farmslot/recipe-cli/harness";
+import { depsCheck } from "@farmslot/recipe-runner/runtime/deps-readiness";
+import { coreDependencyBlock } from "../../commands/core-readiness.js";
+import { checkoutHas, checkoutHasDir } from "../checkout-files.js";
 import { adapterRegistry } from "../registry.js";
 import { coreActions } from "./actions.js";
-import { coreHarness, corePrepare, coreRuntimeContext } from "./overlay.js";
-import { coreReadiness } from "./readiness.js";
+import { coreHarness, corePrepare } from "./overlay.js";
+import { coreControllerImport, coreReadiness, coreRebuildAction } from "./readiness.js";
 import { coreRun } from "./run.js";
-import { coreDependencyBlock } from "../../commands/core-readiness.js";
-import { checkoutHas, checkoutHasDir } from "../checkout-files.js";
 const coreSurface = defineAdapter({
-  id: "core",
-  sdkVersion: 1,
-  headless: true,
-  resolveSlotPorts() {
+  ...createNodeAdapter({
+    id: "core",
+    detect: {
+      files: (target) => checkoutHasDir(target, "packages/perps-controller") && checkoutHas(target, "yarn.lock")
+    },
+    hints: {
+      launch: "mm-harness run <recipe>   # run recipes against the headless core",
+      relaunch: "mm-harness verify",
+      runtimeProbeRecovery: (target) => `mm-harness verify --adapter core --target ${shellQuote(path.resolve(target))}`
+    },
+    wording: {
+      devServerStop: {
+        message: "core is headless \u2014 no dev server runs for a core checkout",
+        userAction: "use mm-harness verify (readiness) or mm-harness run (execute a recipe)"
+      }
+    },
+    // Live scripts import the checkout's workspace packages from source: an
+    // unbuilt or stale checkout has no usable dist/ for them.
+    workspacePackages: checkoutWorkspacePackages,
+    actions: coreActions,
+    harness: coreHarness,
+    // coreRun's dependencyBlock (the Core gate) replaces adapter-node's check.
+    run: coreRun
+  }),
+  // Core's live adapter marks a module the checkout cannot resolve (a partial
+  // workspace build) on its own line: the environment, not app logic.
+  failurePatterns: {
+    environment: {
+      pattern: /\[core\/perps\] environment: cannot resolve /u,
+      message: "the Core checkout cannot resolve a module the action imports (a partial workspace build).",
+      userAction: "run yarn build in the Core checkout, then retry"
+    }
   },
+  // The Core gate decides readiness too, so doctor, verify, run and call agree.
   async runtimeStatus(target) {
     const deps = depsCheck(path.resolve(target));
     const block = deps.status === "current" ? coreDependencyBlock(target) : null;
@@ -27,6 +57,18 @@ const coreSurface = defineAdapter({
         deps: deps.status
       };
     }
+    if (deps.status === "current") {
+      const imported = await coreControllerImport(target);
+      if (!imported.ok) {
+        return {
+          decision: "blocked",
+          reasonCode: "CORE_CONTROLLER_IMPORT_FAILED",
+          reasons: [`Core is headless; controller actions cannot import the Perps controller: ${imported.reason}`],
+          nextAction: imported.userAction ?? coreRebuildAction(target),
+          deps: deps.status
+        };
+      }
+    }
     const ready = deps.status === "current";
     return {
       decision: ready ? "ready" : "install",
@@ -51,39 +93,9 @@ const coreSurface = defineAdapter({
       };
     }
   },
-  devServer: {
-    label: "dev-server",
-    describe: () => "no dev server (headless)",
-    stop() {
-      return {
-        kind: "headless",
-        message: "core is headless \u2014 no dev server runs for a core checkout",
-        userAction: "use mm-harness verify (readiness) or mm-harness run (execute a recipe)"
-      };
-    }
-  },
-  logSources() {
-    return [];
-  },
-  appLogSource() {
-    return null;
-  },
-  detect: {
-    files: (target) => checkoutHasDir(target, "packages/perps-controller") && checkoutHas(target, "yarn.lock")
-  },
-  hints: {
-    launch: "mm-harness run <recipe>   # run recipes against the headless core",
-    relaunch: "mm-harness verify",
-    runtimeProbeRecovery: (target) => `mm-harness verify --adapter core --target ${shellQuote(path.resolve(target))}`
-  },
-  launch: async ({ usage }) => usage("core is headless; there is nothing to launch.", "mm-harness verify"),
-  actions: coreActions,
-  harness: coreHarness,
-  runtimeContext: coreRuntimeContext,
   readiness: coreReadiness,
   fixtures: { operations: ["init", "sync", "set"] },
-  prepare: corePrepare,
-  run: coreRun
+  prepare: corePrepare
 });
 adapterRegistry.register(coreSurface);
 export {

package/dist/adapters/extension/extension-id.js

@@ -77,5 +77,6 @@ async function resolveExtensionId(target, options = {}) {
 }
 export {
   extensionIdFromKey,
+  idFromManifest,
   resolveExtensionId
 };