@deeeed/metamask-harness 0.78.0 → 0.80.0

package/dist/paths.js

@@ -1,43 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { recipeRuntimeDir, recipeRuntimePath } from "@farmslot/recipe-cli/harness";
 import { adapterRegistry } from "./adapters/registry.js";
 const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const pathDefaults = readPathDefaults();
-const DEFAULT_RECIPE_RUNTIME_DIR = pathDefaults.recipeRuntimeDir;
-const DEFAULT_RECIPE_HARNESS_ROOT = pathDefaults.recipeHarnessRoot;
 const PREPARE_PROGRESS_ARTIFACT = "prepare/progress.json";
-function recipeRuntimeDir() {
-  return validateRelativeRecipePath("RECIPE_RUNTIME_DIR", process.env.RECIPE_RUNTIME_DIR || DEFAULT_RECIPE_RUNTIME_DIR);
-}
-function recipeHarnessRoot() {
-  return validateRelativeRecipePath("RECIPE_HARNESS_ROOT", process.env.RECIPE_HARNESS_ROOT || DEFAULT_RECIPE_HARNESS_ROOT);
-}
-function harnessExecutable() {
-  return path.resolve(process.env.MM_HARNESS_EXECUTABLE ?? path.join(runnerDir, "bin/mm-harness"));
-}
-function readPathDefaults() {
-  const defaultsPath = path.join(runnerDir, "adapters/shared/path-defaults.json");
-  const parsed = JSON.parse(fs.readFileSync(defaultsPath, "utf8"));
-  return {
-    recipeRuntimeDir: validateRelativeRecipePath("recipeRuntimeDir", parsed.recipeRuntimeDir || ""),
-    recipeHarnessRoot: validateRelativeRecipePath("recipeHarnessRoot", parsed.recipeHarnessRoot || "")
-  };
-}
-function validateRelativeRecipePath(name, value) {
-  if (!value || path.isAbsolute(value)) throw new Error(`${name} must be a non-empty relative path: ${value}`);
-  if (!/^[A-Za-z0-9._/-]+$/u.test(value)) throw new Error(`${name} contains unsupported characters: ${value}`);
-  for (const part of value.split("/")) {
-    if (!part || part === "." || part === "..") throw new Error(`${name} contains unsafe path component: ${value}`);
-  }
-  return value;
-}
-function recipeRuntimePath(projectRoot, ...segments) {
-  return path.join(projectRoot, recipeRuntimeDir(), ...segments);
-}
-function recipeHarnessPath(projectRoot, ...segments) {
-  return path.join(projectRoot, recipeHarnessRoot(), ...segments);
-}
 function walletFixturePath(projectRoot) {
   return recipeRuntimePath(projectRoot, "wallet-fixture.json");
 }
@@ -51,42 +18,51 @@ function recipeWatchLogCandidates() {
   ];
 }
 function resolveLocalProtocolRoot() {
-  const candidates = [
-    process.env.METAMASK_RUNNER_PROTOCOL_ROOT,
-    readConfiguredProtocolRoot(),
-    findProtocolRoot(runnerDir),
-    findProtocolRoot(process.cwd())
-  ].filter(Boolean);
-  const root = candidates[0];
+  const root = process.env.METAMASK_RUNNER_PROTOCOL_ROOT || readConfiguredProtocolRoot();
   return root ? path.resolve(root) : void 0;
 }
-function resolveRequiredLocalProtocolRoot(reason) {
-  const root = resolveLocalProtocolRoot();
-  if (!root) {
-    throw new Error(
-      `${reason} requires a local protocol/runtime checkout. Set METAMASK_RUNNER_PROTOCOL_ROOT or create .farmslot-root for this dev-only path.`
-    );
+function resolveFarmslotPoolDir(starts = [runnerDir, process.cwd()]) {
+  const configured = resolveLocalProtocolRoot();
+  if (configured) return path.join(configured, "pool");
+  for (const start of starts) {
+    const pool = findPoolDir(start);
+    if (pool) return pool;
   }
-  return root;
+  return void 0;
 }
+const LIBRARY_ACTION_NAMESPACE = "metamask";
 function readConfiguredProtocolRoot() {
   const configPath = path.join(runnerDir, ".farmslot-root");
   if (!fs.existsSync(configPath)) return void 0;
   const value = fs.readFileSync(configPath, "utf8").trim();
   return value || void 0;
 }
-function findProtocolRoot(start) {
+function findPoolDir(start) {
   let dir = path.resolve(start);
   while (dir !== path.dirname(dir)) {
-    if (isProtocolRoot(dir)) return dir;
-    const sibling = path.join(dir, "farmslot");
-    if (isProtocolRoot(sibling)) return sibling;
+    for (const root of [dir, path.join(dir, "farmslot")]) {
+      const pool = path.join(root, "pool");
+      if (holdsSlotPool(pool)) return pool;
+    }
     dir = path.dirname(dir);
   }
   return void 0;
 }
-function isProtocolRoot(candidate) {
-  return fs.existsSync(path.join(candidate, "packages/recipe-harness/package.json")) && fs.existsSync(path.join(candidate, "packages/protocol/package.json"));
+function holdsSlotPool(candidate) {
+  let names;
+  try {
+    names = fs.readdirSync(candidate);
+  } catch {
+    return false;
+  }
+  return names.some((name) => {
+    if (!name.endsWith(".json") || name.includes(".bak")) return false;
+    try {
+      return Array.isArray(JSON.parse(fs.readFileSync(path.join(candidate, name), "utf8"))?.slots);
+    } catch {
+      return false;
+    }
+  });
 }
 function assertAdapter(adapter) {
   const ids = adapterRegistry.list();
@@ -110,44 +86,44 @@ function readJson(file) {
 }
 async function importRecipeHarness() {
   return importProtocolPackage(
-    "@farmslot/recipe-harness",
-    "packages/recipe-harness/src/index.ts"
+    "@farmslot/recipe-runner",
+    "packages/recipe-runner/src/index.ts"
   );
 }
 async function importRecipeHarnessRuntimeCdp() {
   return importProtocolPackage(
-    "@farmslot/recipe-harness/runtime/cdp",
-    "packages/recipe-harness/src/runtime/cdp.ts"
+    "@farmslot/recipe-runner/runtime/cdp",
+    "packages/recipe-runner/src/runtime/cdp.ts"
   );
 }
 async function importRecipeHarnessAppLifecycle() {
   return importProtocolPackage(
-    "@farmslot/recipe-harness/adapters/app-lifecycle",
-    "packages/recipe-harness/src/adapters/app-lifecycle.ts"
+    "@farmslot/recipe-runner/adapters/app-lifecycle",
+    "packages/recipe-runner/src/adapters/app-lifecycle.ts"
   );
 }
 async function importRecipeHarnessRuntimeBrowserExtension() {
   return importProtocolPackage(
-    "@farmslot/recipe-harness/runtime/browser-extension",
-    "packages/recipe-harness/src/runtime/browser-extension.ts"
+    "@farmslot/recipe-runner/runtime/browser-extension",
+    "packages/recipe-runner/src/runtime/browser-extension.ts"
   );
 }
 async function importRecipeHarnessRuntimeReactNativeBridge() {
   return importProtocolPackage(
-    "@farmslot/recipe-harness/runtime/react-native-bridge",
-    "packages/recipe-harness/src/runtime/react-native-bridge.ts"
+    "@farmslot/recipe-runner/runtime/react-native-bridge",
+    "packages/recipe-runner/src/runtime/react-native-bridge.ts"
   );
 }
 async function importMetaMaskNativeUiProvider() {
   return importProtocolPackage(
-    "@farmslot/expo-recipe",
-    "packages/expo-recipe/src/index.ts"
+    "@farmslot/adapter-rn",
+    "packages/adapter-rn/src/index.ts"
   );
 }
-async function importRecipeHarnessCli() {
+async function importRecipeRunnerCli() {
   return importProtocolPackage(
-    "@farmslot/recipe-harness/cli",
-    "packages/recipe-harness/src/cli/index.ts"
+    "@farmslot/recipe-runner/cli",
+    "packages/recipe-runner/src/cli/index.ts"
   );
 }
 async function importRecipeProtocol() {
@@ -176,30 +152,24 @@ function isMissingPackageError(error, packageName) {
   return (code === "ERR_MODULE_NOT_FOUND" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED") && error.message.includes(packageName);
 }
 export {
-  DEFAULT_RECIPE_HARNESS_ROOT,
-  DEFAULT_RECIPE_RUNTIME_DIR,
+  LIBRARY_ACTION_NAMESPACE,
   PREPARE_PROGRESS_ARTIFACT,
   assertAdapter,
   extensionIdPath,
-  harnessExecutable,
   importMetaMaskNativeUiProvider,
   importRecipeHarness,
   importRecipeHarnessAppLifecycle,
-  importRecipeHarnessCli,
   importRecipeHarnessRuntimeBrowserExtension,
   importRecipeHarnessRuntimeCdp,
   importRecipeHarnessRuntimeReactNativeBridge,
   importRecipeProtocol,
+  importRecipeRunnerCli,
   manifestPath,
   readJson,
-  recipeHarnessPath,
-  recipeHarnessRoot,
   recipePath,
-  recipeRuntimeDir,
-  recipeRuntimePath,
   recipeWatchLogCandidates,
+  resolveFarmslotPoolDir,
   resolveLocalProtocolRoot,
-  resolveRequiredLocalProtocolRoot,
   runnerDir,
   walletFixturePath
 };

package/dist/performance-observation.js

@@ -4,13 +4,13 @@ import { gzip } from "node:zlib";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { createExtensionPerformanceBackend } from "./adapters/extension/performance-observer.js";
 import { TRACE_KINDS } from "./adapters/performance/cdp-trace.js";
-import { summarizeFrames } from "./adapters/mobile/frame-metrics.js";
+import { summarizeFrames } from "@farmslot/adapter-rn";
 import { summarizeJavaScriptTasks } from "./adapters/performance/js-task-metrics.js";
 import {
   indexArtifactManifest,
   readContainedJsonArtifact,
   writeContainedArtifact
-} from "./artifact-files.js";
+} from "@farmslot/recipe-cli/harness";
 const sessions = /* @__PURE__ */ new Map();
 const DEFAULT_MAX_DURATION_MS = 5 * 60 * 1e3;
 const MAX_DURATION_MS = 60 * 60 * 1e3;

package/dist/progress.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { parseArgs } from "node:util";
-import { color } from "./cli-color.js";
+import { color } from "@farmslot/recipe-cli/harness";
 function shouldEmitJson(explicit) {
   if (explicit) return true;
   const env = process.env.RECIPE_PROGRESS_JSON;

package/dist/recipe-assistance-context.js

@@ -1,13 +1,11 @@
 import fs from "node:fs";
 import { createHash } from "node:crypto";
-import { loadRecipeLibraries, resolveRecipeDependencies, rootResolutionRef } from "@farmslot/recipe-harness";
-import { isSensitiveKey } from "./command-journal.js";
+import { loadRecipeLibraries, resolveRecipeDependencies, rootResolutionRef } from "@farmslot/recipe-runner";
+import { isSensitiveKey, CliError, isRecord, optionStrings, EXIT } from "@farmslot/recipe-cli/harness";
 import { resolveActionManifest } from "./manifest.js";
 import { describeManifestActions } from "./commands/manifest.js";
 import { recipeComposition } from "@farmslot/recipe-cli";
 import { resolveMetaMaskLibrarySources, validateRunRecipeStatic } from "./commands/run-engine.js";
-import { CliError, isRecord, optionStrings } from "./commands/parse-args.js";
-import { EXIT } from "./commands/shared.js";
 import { MAX_ADVICE_STATE_BYTES } from "./recipe-assistance-rubric.js";
 function digest(value) {
   return createHash("sha256").update(value).digest("hex");

package/dist/recipe-security.js

@@ -18,6 +18,7 @@ const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.read_positions",
   "metamask.perps.read_orders",
   "metamask.perps.read_account",
+  "metamask.perps.quote_fees",
   "metamask.perps.read_snapshot",
   "metamask.perps.assert_visible_consistency",
   "metamask.perps.assert_positions",
@@ -175,65 +176,7 @@ function isPathWithin(root, candidate) {
 function isMissing(error) {
   return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
 }
-function explicitRecipeTrustOptions(values) {
-  const { sourceTrust, sourceKind, sourceName, sourceDigest, approvalDigest } = values;
-  const source = sourceTrust || sourceKind || sourceName || sourceDigest ? {
-    trust: sourceTrust ?? "unknown",
-    kind: sourceKind ?? "recipe-file",
-    ...sourceName ? { name: sourceName } : {},
-    ...sourceDigest ? { digest: sourceDigest } : {}
-  } : void 0;
-  return {
-    ...source ? { source } : {},
-    ...approvalDigest ? { approval: { planDigest: approvalDigest } } : {}
-  };
-}
-function recipeTrustFailure(error) {
-  if (!error || typeof error !== "object") return void 0;
-  const value = error;
-  if (typeof value.code !== "string" || !value.code.startsWith("RECIPE_") || typeof value.message !== "string" || typeof value.userAction !== "string") return void 0;
-  const failure = value.failure && typeof value.failure === "object" ? value.failure : void 0;
-  const blocked = Array.isArray(failure?.blocked) ? failure.blocked.flatMap((entry) => {
-    if (!entry || typeof entry !== "object") return [];
-    const node = entry;
-    if (typeof node.nodeId !== "string" || typeof node.action !== "string" || !Array.isArray(node.capabilities)) return [];
-    const origin = node.origin && typeof node.origin === "object" ? node.origin : void 0;
-    const adapterOrigin = node.adapterOrigin && typeof node.adapterOrigin === "object" ? node.adapterOrigin : void 0;
-    const implementation = adapterOrigin ? {
-      ...typeof adapterOrigin.kind === "string" ? { kind: adapterOrigin.kind } : {},
-      ...typeof adapterOrigin.trust === "string" ? { trust: adapterOrigin.trust } : {},
-      ...typeof adapterOrigin.digest === "string" ? { digest: adapterOrigin.digest } : {}
-    } : void 0;
-    return [{
-      nodeId: node.nodeId,
-      action: node.action,
-      capabilities: node.capabilities.filter(
-        (item) => typeof item === "string"
-      ),
-      source: typeof origin?.kind === "string" ? origin.kind : "unknown",
-      ...implementation && Object.keys(implementation).length > 0 ? { implementation } : {}
-    }];
-  }) : void 0;
-  const recipeDigest = typeof failure?.recipeDigest === "string" ? failure.recipeDigest : void 0;
-  const userAction = recipeDigest && (value.code === "RECIPE_TRUST_REQUIRED" || value.code === "RECIPE_APPROVAL_MISMATCH") && !value.userAction.includes("execution environment") ? `${value.userAction}; rerun with the same project root, artifact directory, and execution environment` : value.userAction;
-  return {
-    code: value.code,
-    message: value.message,
-    userAction,
-    ...failure ? {
-      details: {
-        // Farmslot reports the approved execution plan digest as
-        // recipeDigest in failures; approval input names it planDigest.
-        ...recipeDigest ? { recipeDigest } : {},
-        ...typeof failure.trust === "string" ? { trust: failure.trust } : {},
-        ...blocked?.length ? { blocked } : {}
-      }
-    } : {}
-  };
-}
 export {
   actionSourceIntegrity,
-  explicitRecipeTrustOptions,
-  metaMaskActionExecutionCapabilities,
-  recipeTrustFailure
+  metaMaskActionExecutionCapabilities
 };

package/dist/review/knowledge.js

@@ -1,9 +1,9 @@
+import { detectAdapter, usageError } from "@farmslot/recipe-cli/harness";
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { detectAdapter } from "../harness.js";
-import { usageError } from "../commands/parse-args.js";
+import "../adapters/surface.js";
 const REVIEW_ADAPTERS = ["mobile", "extension", "core", "terminal"];
 const ADVISOR_STAGES = ["plan", "draft", "evidence"];
 function parseAdvisorSettings(value) {
@@ -221,7 +221,7 @@ async function hydrateLibraryPathEnv(context) {
   if (discovered.length === 0) return;
   const entries = discovered.map((library) => `${library.name}=${library.root}`);
   if (!existing) {
-    const { personalRecipeLibraryRoot } = await import("@farmslot/recipe-harness");
+    const { personalRecipeLibraryRoot } = await import("@farmslot/recipe-runner");
     const personal = personalRecipeLibraryRoot(env);
     if (isDir(personal)) entries.push(`personal=${personal}`);
   }

package/dist/runner.js

@@ -10,10 +10,11 @@ import {
 import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from "./manifest.js";
 import { actionSourceIntegrity, metaMaskActionExecutionCapabilities } from "./recipe-security.js";
 import {
+  createRecordingTargetProvider,
   prepareLiveAdapterScript
-} from "./live-adapter-contract.js";
-import { createMetaMaskRecordingTargetProvider } from "./recording-target.js";
+} from "@farmslot/recipe-cli/harness";
 import {
+  LIBRARY_ACTION_NAMESPACE,
   importMetaMaskNativeUiProvider,
   importRecipeHarness,
   importRecipeHarnessAppLifecycle,
@@ -109,7 +110,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     ),
     logger,
     recording: {
-      targetProvider: createMetaMaskRecordingTargetProvider(adapter),
+      targetProvider: createRecordingTargetProvider(adapter),
       ...videoRecorder ? { videoRecorder } : {}
     },
     runner: runnerProvenance(),
@@ -204,6 +205,7 @@ async function prepareLiveAdapterImplementations(platform, actions, sources, tru
     const executable = await prepareLiveAdapterScript({
       platform,
       action,
+      namespace: LIBRARY_ACTION_NAMESPACE,
       implementationRoot: source.implementationRoot,
       allowRuntimeImports: source.tier === "canonical" || source.trust === "trusted" || source.tier === "task" && trustTaskActions
     });

package/dist/runtime-context.js

@@ -1,10 +1,10 @@
+import { recipeRuntimeDir } from "@farmslot/recipe-cli/harness";
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { getAdapterSurface } from "./adapters/surface.js";
-import { recipeRuntimeDir } from "./paths.js";
 function ensureRuntimeContext(target, adapter) {
   const repoRoot = fs.realpathSync(target);
   const runtimeDir = recipeRuntimeDir();

package/dist/task-view.js

@@ -1,4 +1,4 @@
-import { readOperations, processIdentity } from "@farmslot/recipe-harness/runtime/operation";
+import { readOperations, processIdentity } from "@farmslot/recipe-runner/runtime/operation";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -22,9 +22,8 @@ import {
   subtaskPaths,
   WORKER_SIGNAL_FILE
 } from "@farmslot/protocol";
-import { readCommandJournal } from "./command-journal.js";
-import { resolveRuntimeContextPath } from "./harness.js";
-import { PREPARE_PROGRESS_ARTIFACT, recipeRuntimeDir } from "./paths.js";
+import { readCommandJournal, recipeRuntimeDir, resolveRuntimeContextPath } from "@farmslot/recipe-cli/harness";
+import { PREPARE_PROGRESS_ARTIFACT } from "./paths.js";
 import { parseLibraryPathEnv } from "./review/knowledge.js";
 const CHECKLIST_LABEL_LIMIT = 70;
 const TASK_SILENT_AFTER_MS = 10 * 60 * 1e3;

package/docs/CONTRIBUTING.md

@@ -13,7 +13,7 @@ bin/mm-harness
   -> @farmslot/agent-runtime     checklist state
   -> @farmslot/handoff           scrubbed learning capture/share
   -> @farmslot/recipe-cli        recipe discovery: libraries, runnable checks, composition
-  -> @farmslot/recipe-harness    generic execution, UI transports, evidence
+  -> @farmslot/recipe-runner     generic execution, UI transports, evidence
   -> @farmslot/protocol          schemas
   -> adapters/                   focused host/browser/device leaves
   -> library/                    MetaMask actions and recipes
@@ -26,7 +26,7 @@ bin/mm-harness
 | `@farmslot/agent-runtime` | task-local checklist state and terminal contracts |
 | `@farmslot/handoff` | learning assembly, scrubbing, validation, approval, and publication |
 | `@farmslot/recipe-cli` | recipe discovery: library resolution, runnable checks, composition |
-| `@farmslot/recipe-harness` | generic execution, recovery, traces, artifacts, `ui.*` |
+| `@farmslot/recipe-runner` | generic execution, recovery, traces, artifacts, `ui.*` |
 | `mm-harness` | MetaMask runtime control, diagnostics, durable domain actions |
 | skills/checklists | task workflow and proof expectations |
 | product checkout | app behavior and explicit debug hooks |
@@ -180,7 +180,7 @@ test. Update `CHANGELOG.md` under `Unreleased` for user-visible behavior.
 
 When upgrading the protocol or runtime, align their transitive consumers before
 pinning them here. Farmslot's `workspace:*` dependencies become exact versions
-when packed, so `agent-runtime` and `expo-recipe` can retain older copies until
+when packed, so `agent-runtime` and `adapter-rn` can retain older copies until
 republished. Verify the complete install with
 `bash tests/contract/packaging-dist-install.test.sh` before releasing the harness.
 

package/docs/cli-contract.md

@@ -109,11 +109,11 @@ Every family checks its own golden directory: a golden no case writes fails the
 Each case runs under a safety cap, `GOLDENS_CASE_TIMEOUT` (default 600 s). A case that hits it reports `TIMEOUT <case>` and fails without being compared or written, so `--update` can never accept a truncated capture.
 
 Each family is a normal contract test (`tests/contract/goldens-<family>.test.sh`). `gd_init` (`tests/contract/goldens/lib.sh`) builds a sandbox on `ct_init`, and every case runs under `env -i`:
-- `gd_init` first unsets every inherited `MM_HARNESS_*`, `RECIPE_*`, `METAMASK_*` and `FARMSLOT_*` variable, plus device and port pins (`IOS_SIMULATOR`, `ADB_SERIAL`, `WATCHER_PORT`, `METRO_PORT`, `CDP_PORT`, `IDB_PATH`, `ANDROID_HOME`, …). A developer's `MM_HARNESS_BIN` or `MM_HARNESS_IDB_PATH` export therefore cannot redirect a case;
+- `gd_init` first unsets every inherited `MM_HARNESS_*`, `RECIPE_*`, `METAMASK_*` and `FARMSLOT_*` variable, plus device and port pins (`IOS_SIMULATOR`, `ADB_SERIAL`, `WATCHER_PORT`, `METRO_PORT`, `CDP_PORT`, `IDB_PATH`, `ANDROID_HOME`, …). A developer's `MM_HARNESS_BIN` or `RECIPE_RN_IDB_PATH` export therefore cannot redirect a case;
 - the environment is an allowlist: sandbox `HOME`, caches, config, `FARMSLOT_HOME`, `TZ=UTC`, no update probe, and only the variables the family sets itself;
 - every interpreter and tool the goldens launch is resolved to its real binary before `HOME` moves into the sandbox: `node` (`process.execPath`), `git` (`git --exec-path`), `bash` (`$BASH`) and `timeout`. The goldens need no Python. A tool that resolves to a script, the shape of an asdf/mise/volta/pyenv shim, fails the family up front with a message naming it. Each is checked to run with a sandboxed `HOME`;
 - `PATH` is pinned to the case stubs, the sandbox stubs, those real binaries, and `/usr/bin:/bin:/usr/sbin:/sbin`. Host tools (`idb`, `capture-helper`, a developer's Chrome) cannot change a golden;
-- device-tool discovery is pinned: `MM_HARNESS_IDB_PATH` and `MM_HARNESS_ADB_PATH` point at sandbox stubs, which discovery checks before any absolute Homebrew or pipx path;
+- device-tool discovery is pinned: `RECIPE_RN_IDB_PATH` and `RECIPE_RN_ADB_PATH` point at sandbox stubs, which discovery checks before any absolute Homebrew or pipx path;
 - localhost probes cannot reach a real server. `gd_reserve_ports` runs a Node port holder (`tests/contract/goldens/port-holder.mjs`) that holds ephemeral ports on `127.0.0.1` and `::1` and resets every connection it accepts, so Metro `/status` and CDP probes never get a response and nothing real can take the port mid-run. Each family exports the farm's slot port variables (`RECIPE_CDP_PORT`, `WATCHER_PORT`, `METRO_PORT`) set to those ports, so commands without an explicit port use them too. Goldens show them as `<PORT:NAME>`, rewritten only in port positions (`*port` keys, `:<port>`, `port <n>`/`PORT=<n>`, or a string that is exactly the port), so an unrelated equal number such as a 60000 ms timeout is never rewritten;
 - `tmux`, `xcrun` and `adb` are stubbed (`ct_init`, plus one booted simulator and one Android device for Mobile);
 - forbidden stubs record any call to `open`, `osascript`, `lsappinfo`, `screencapture`, `yarn`, `npx`, `npm`, `corepack`, `gh` and Chrome/Chromium, and the family fails if one is called. A browser stub answers only `--version`, and `npm` only `root -g` (install-source detection), with a sandbox path;

package/docs/feature-guard.md

@@ -0,0 +1,90 @@
+# Feature-loss guard
+
+While the platform phases move mm-harness code into Farmslot packages, nothing the frozen 0.76.0 release could do may get lost. Unit tests don't prove that. The guard has three parts, all run against real builds:
+
+| Part | Script | Proves | When |
+|---|---|---|---|
+| Inventory | `scripts/feature-inventory.mjs --check` | every 0.76.0 capability still exists, or is mapped in `tests/feature-inventory/changes.json` | every PR review, every release |
+| Live differential | `scripts/differential.mjs` | the same commands on the same real slots behave the same on 0.76.0 and on the PR build | every migration PR (report attached to the PR) |
+| Release smoke | `scripts/release-smoke.mjs` | the fixed real recipes pass on the canary Mac, recorded, and match the previous release | every release |
+
+The baseline is `@deeeed/metamask-harness@0.76.0` (da656404, before phase 2). The repo declares no dependency on it: `scripts/feature-guard/builds.mjs` installs it on first use, on each host, into `~/.cache/mm-harness-baseline/0.76.0` with npm's `--before` set just after 0.76.0's publish time, so every host resolves the dependency tree that release shipped with (the differential report prints each host's tree digest); it is never upgraded. The candidate is `npm pack` of the checkout, installed in `~/.cache/mm-harness-builds/<sha>`, so both sides are installed packages in sibling directories. Commands run as argv arrays, locally without a shell and remotely through one fixed ssh launcher with quoted arguments.
+
+## 1. Inventory
+
+```bash
+node scripts/feature-inventory.mjs --check            # this checkout, packed and installed, vs tests/feature-inventory/baseline-0.76.0.json
+node scripts/feature-inventory.mjs --check --bin <installed mm-harness>   # a published build
+```
+
+The inventory asks the build itself, so it stays valid while code moves between packages:
+
+- **CLI**: a public command refuses `<cmd> --feature-inventory-probe` as an unknown option, a removed one is refused as an unknown command. A flag exists when `<cmd> <flags…> --feature-inventory-canary --help` is refused only at the trailing canary (a lost flag is refused first; the canary proves the validator walked every flag before it, and `--help` keeps an accepted probe from running anything). An option value exists when `<cmd> <flag>=<value> --feature-inventory-canary --help` is refused only at the canary. Positional choices come from the "Valid values" an invalid positional is refused with. Candidates to probe are the union of the build's own command contract and the baseline's grammar, so moving `command-contract.ts` cannot hide a lost flag.
+- **Oracle check**: every probe reads presence from a refusal, so the run first proves the refusals are seen (a bogus command, flag and option value must each be refused, `--help` must succeed), and any probe result that is neither an acceptance nor a known refusal stops the run. A build that does not start, or a CLI whose wording changed (the contract moving into `@farmslot/recipe-cli`), fails loudly; update the patterns in `feature-inventory.mjs` in that PR.
+- **Hidden commands** (`self-test`, `ensure-ready`, `runtime-*`, `resolve-extension`, `completion-candidates`, `completions`) bypass the preflight validator. They are probed with a flag that has no value, which their own parsers reject before doing any work; a different result stops the run. If that parse ever changed, the probe would reach the command, inside the sandbox.
+- **Per adapter** (the `--adapter` choices): action ids, their schema fields and enum values, and observers (`actions --raw --json`); call short names (`call --list --json`); bundled recipes and their parameters (`run --list --json`); doctor check ids (`doctor --json`) against an empty target, plus a real checkout per `--checkout <adapter>=<dir>`.
+- **Environment variables**: a source scan of the package and every `@farmslot` package it depends on (a direct JS read, a name passed to a helper that reads env by parameter or listed next to an `env[<variable>]` access, or a shell expansion the script never assigns), the env inputs `adapters/manifest.json` documents, and every unset variable a Node process looked up while the probes ran (including a read-only `help review` per adapter) (`scripts/feature-guard/env-trace.mjs`, which sees names built at runtime). This is a floor: a name that is still present somewhere does not prove the same code path reads it; the differential covers behaviour.
+- **Package surface**: bins, exports, the package entry's export names, `files` entries that exist in the package, `adapters/manifest.json` features, every shipped script and module path under `adapters/` and `library/`, and the export subpaths and bins of the `@farmslot` dependencies (where moved code lands).
+
+Probes run in `scripts/feature-guard/sandbox.mjs`: a sandbox HOME and config, no inherited recipe libraries, inert device and process listings, and stubs that fail the inventory if a probe reaches a browser, launcher, package manager or `gh`.
+
+`--check` fails on a baseline key that is missing from the build unless `changes.json` covers it. Doctor contexts the run did not record (no `--checkout`) are reported as skipped. The baseline file is regenerated only when the probe logic changes, and always from the frozen 0.76.0 bin:
+
+```bash
+node scripts/feature-inventory.mjs --bin ~/.cache/mm-harness-baseline/0.76.0/node_modules/.bin/mm-harness \
+  --out tests/feature-inventory/baseline-0.76.0.json
+```
+
+### `changes.json`: consolidation is welcome
+
+The guard protects capabilities, not names. Merging or simplifying actions, commands or flags is fine when the capability survives. Each entry has an `id`, a `reason` and a `pr`:
+
+- `consolidated`: `from` (old keys, `*` allowed) → `to` (keys that must exist in the build), the `argumentMapping`, and a `differential` the differential's consolidated lane runs:
+  - `{ "kind": "cli", "where": "sandbox" | "slot", "adapter": …, "old": { "argv", "env" }, "new": { "argv", "env" } }`: the old invocation on 0.76.0 vs the mapped one on the PR build; equivalent normalized outcome passes.
+  - `{ "kind": "env", …same…, "names": [[old, new], …] }`: as `cli`, and the baseline must read each old variable and the build the new one (env trace; leave them unset).
+  - `{ "kind": "module", "old": [paths or specifiers], "new": [specifiers], "renamed": { old: new }, "names": [old names] }`: each new home exports every name the old module did (or, with `names`, the listed names when only part of the old module moved).
+  - `{ "kind": "script", "old": { "script", "args" }, "new": { "script", "args" } }`: a moved CLI script, run on both sides.
+- `dropped`: `keys` proven dead, with `evidence` (no caller in farms, skills, recipe libraries, docs).
+
+No shims: the PR that consolidates renames every caller (farm hooks, skills, recipes, docs) in the same change.
+
+## 2. Live differential
+
+```bash
+node scripts/differential.mjs \
+  --slot core=~/dev/metamask/core-6 \
+  --slot terminal=~/dev/metamask/va-mmcx-terminal-1 --slot-var terminal:cdpPort=9541 --slot-var terminal:appPort=9341 \
+  --slot-env terminal:TERMINAL_EXTENSION_CHECKOUT=<extension checkout with a dist> \
+  --slot-env terminal:RECIPE_WALLET_FIXTURE=<farm wallet fixture> \
+  --slot-env terminal:RECIPE_LIBRARY_PATH=perps=<dir>:terminal=<dir> \
+  --slot extension=macpro.local:/Users/deeeed/dev/metamask/metamask-extension-1 \
+  --slot-var extension:cdpPort=7661 --slot-var extension:watcherPort=9011 --slot-var extension:slot=macpro-mme-1 \
+  --slot mobile=macpro.local:/Users/deeeed/dev/metamask/metamask-mobile-5 \
+  --slot-var mobile:watcherPort=8065 --slot-var mobile:device=mm-5
+```
+
+Lanes (`--lanes`, default all):
+
+- `help`: `--help`, `--version` and `<cmd> --help` for every baseline command, sandboxed.
+- `slots`: per `--slot`, discovery (`actions --raw`, `call --list`, `run --list`, `doctor --json`) and the adapter's cases in `tests/differential/matrix.json`: the farm hook argv the goldens freeze, run on the real slot, plus real runs and calls (`live`), including a probe that requires the live transport (`cdp.target`), not only checkout metadata. The prelude gives both sides the same start; the whole baseline sequence runs before the candidate's. A slot on another host runs over ssh, with both builds installed there.
+- `consolidated`: the `changes.json` differentials.
+- `goldens`: the contract golden families run against each build from a copy of `tests/`, compared golden by golden.
+
+Captures are normalized (paths, versions, pids, timestamps, durations, epoch numbers, encrypted vaults) and compared per facet: exit code, stdout (JSON paths or text), stderr when stdout is empty, artifact files and tree. `volatile` paths in the matrix (product console warnings that arrive on the product's own timing) are masked but their keys still compared. Every remaining difference must match an entry in `tests/differential/intended.json` (`case` glob, optional `facet`, `paths` or `text`, `reason`, `pr`). The report lands in `evidence/differential/<sha>/report.md`, with `results.json` and every raw capture beside it; attach the report to the PR. Verdicts: PASS (exit 0), FAIL (exit 1: an unexplained difference or a lane error), INCOMPLETE (exit 3: a case was skipped, e.g. a consolidated proof without its `--slot`).
+
+What the normaliser deliberately masks, and so cannot catch: any semver under a key ending in `version` other than the harness's own, numbers under keys ending in `Ms`/`Seconds`/`duration`/`elapsed` (so a changed timeout value), epoch-millisecond numbers, and the `volatile` paths (a new product warning during a live run). Each varies run to run on real slots; the goldens freeze the static values.
+
+Machine rules: on macwork, headless only and no focus stealing (`TERMINAL_HEADLESS=1` is in the matrix). Headful runs and the Extension wallet popup fail while macwork's screen is locked (`Page.captureScreenshot` timeout). Mobile and the Extension run on free macpro or mini slots, never mini-mm-3. The differential stops and cleans the slot runtime it used; reinstall the farm's overlay afterwards if the slot is handed back to the farm.
+
+## 3. Release smoke
+
+```bash
+node scripts/release-smoke.mjs --version 0.79.0 <the same --slot flags>   # a published release -> ~/dev/metamask/mm-harness-smoke/0.79.0
+node scripts/release-smoke.mjs <the same --slot flags>                   # this checkout, packed -> .../0.79.0+<package digest>, compared with 0.79.0
+```
+
+`tests/release-smoke/*.json` is the fixed set: Mobile Perps smoke, Extension Perps smoke, Terminal wallet connect (`terminal.perps.ensure-session`), and a core `call`. All are read-only; the canary slots must hold the farm's testnet wallet fixture (the Terminal enforces testnet itself). Each runs its prelude (install or fixture sync, launch, wallet fixture), the recipe with `--record-video=full-run` (the Terminal adapter has no video; its trace is the record), then its after steps (stop). Runs are kept per build on the host in `~/dev/metamask/mm-harness-smoke/<version>` (published) , `<version>+<package digest>` (a packed checkout; commits that only touch repo tooling are the same build) or `<version>+local` (`--bin`), with the full artifact directory (summary, trace, video) per smoke; an `--only` run updates its smokes and keeps the others recorded for the same packed or published build (a `--bin` build keeps nothing: it can change in place). The run compares with the published run at the highest version not above its own. Verdicts: FAIL (exit 1) on a non-pass status, a missing trace or expected video, or a regression (status, or the node/action sequence of a passing run); INCOMPLETE (exit 3) when a smoke has not run for this build or has nothing to compare with (`--no-compare` marks the first recorded run).
+
+## CI
+
+Not wired yet. The inventory `--check` needs no slot and can run in CI on the packed build; the differential and the smoke set need real slots and stay in the review and release flow. The workflow change is proposed separately.

package/library/README.md

@@ -10,7 +10,9 @@
   That is the engine contract (the recipe engine spawns/imports them with the
   input env set) — a bare `import` outside the engine throws
   "Missing live adapter input path", which is expected, not a bug.
-- Actions load harness helpers ONLY through `actions/harness-exports.mjs` (the
+- Actions import the generic harness helpers (runtime paths, recording
+  snapshots) directly from `@farmslot/recipe-cli/harness`, and load the
+  MetaMask helpers ONLY through `actions/harness-exports.mjs` (the
   dist-preferring bridge) — never deep-import `src/` (published installs have no
   src/, and the entrypoint would close an import cycle through adapters.ts).
 - `recipes/` — runnable recipes (`mm-harness run <name-or-file>`).