@deeeed/metamask-harness 0.86.2 → 0.88.0

package/dist/adapters/perps-mainnet-cleanup.js

@@ -0,0 +1,122 @@
+import {
+  VENUE_ORDER_FIELDS,
+  cleanupOwns,
+  clearMainnetSwitch,
+  ledgerOrderTargets,
+  mainnetOrderLeftOpenError,
+  markRunAborting,
+  readHyperliquidVenue,
+  readMainnetOrderLedger,
+  settleMainnetOrder
+} from "../../library/actions/shared/perps/mainnet-order-ledger.mjs";
+const PENDING_SETTLE_MS = 1e4;
+async function platformPerps(platform) {
+  if (platform === "mobile") return import("../../library/actions/mobile/perps/perps.mjs");
+  if (platform === "extension") return import("../../library/actions/extension/perps/perps.mjs");
+  throw new Error(`no mainnet order cleanup for platform ${platform}`);
+}
+async function currentEntry(projectRoot, id) {
+  return (await readMainnetOrderLedger(projectRoot)).entries.find((entry) => entry.id === id);
+}
+async function venueRead(entry) {
+  const venue = await readHyperliquidVenue(entry.address, entry.symbol);
+  const open = ledgerOrderTargets(entry, venue.openOrders, VENUE_ORDER_FIELDS);
+  return { source: venue.source, open: open.map((order) => order.orderId), positionSize: venue.positionSize };
+}
+async function closeOut(projectRoot, env, via, id) {
+  const deadline = Date.now() + PENDING_SETTLE_MS;
+  for (; ; ) {
+    const entry = await currentEntry(projectRoot, id);
+    if (!entry) return;
+    const cancelInApp = async () => (await platformPerps(entry.platform)).cancelMainnetLedgerOrder(entry, { projectRoot, env });
+    let proof = entry.state === "cancelled" ? { canceled: entry.cancelProof.canceled, read: null } : await cancelInApp();
+    let venue = await venueRead(entry);
+    if (entry.state === "cancelled" && venue.open.length > 0) {
+      proof = await cancelInApp();
+      venue = await venueRead(entry);
+    }
+    for (let wait = 0; venue.open.length > 0 && proof.canceled.length > 0 && wait < 5; wait += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+      venue = await venueRead(entry);
+    }
+    if (venue.open.length > 0) {
+      throw new Error(`the venue still lists order(s) ${venue.open.join(", ")} after the app ${proof.read?.notOpen ? "reported none open" : "cancelled"}`);
+    }
+    if (proof.read?.notOpen && entry.state === "pending" && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+      continue;
+    }
+    const recorded = { via: entry.cancelProof?.via ?? via, canceled: proof.canceled, app: proof.read, venue };
+    const evidencePath = await settleMainnetOrder(projectRoot, entry, recorded);
+    process.stderr.write(
+      `mainnet ${entry.symbol} order ${entry.orderId ?? "(pending)"}: ${proof.canceled.length > 0 ? "cancelled" : "not open"} at run ${via}, gone at the venue; proof in ${evidencePath}
+`
+    );
+    if (venue.positionSize !== Number(entry.baselinePositionSize ?? 0)) {
+      throw new Error(`the ${entry.symbol} position is ${venue.positionSize}, was ${entry.baselinePositionSize ?? 0} before the order: it filled; close that position now`);
+    }
+    return;
+  }
+}
+async function cleanup(projectRoot, env, via) {
+  const ledger = await readMainnetOrderLedger(projectRoot);
+  const failures = [];
+  for (const entry of ledger.entries.filter((record) => cleanupOwns(record, process.pid))) {
+    try {
+      await closeOut(projectRoot, env, via, entry.id);
+    } catch (error) {
+      failures.push({ entry, error });
+    }
+  }
+  if (failures.length > 0) throw mainnetOrderLeftOpenError(failures);
+  if (ledger.networkSwitch && cleanupOwns(ledger.networkSwitch, process.pid)) {
+    const { restoreTestnetAfterRun } = await import("../../library/actions/extension/perps/perps.mjs");
+    await restoreTestnetAfterRun(ledger.networkSwitch, { projectRoot });
+    await clearMainnetSwitch(projectRoot);
+    process.stderr.write(`Perps network switched back to testnet at run ${via}.
+`);
+  }
+}
+let inFlight;
+function cancelRunMainnetOrders(projectRoot, env, via) {
+  inFlight ??= cleanup(projectRoot, env, via).finally(() => {
+    inFlight = void 0;
+  });
+  return inFlight;
+}
+const ABORT_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+async function abortRunMainnetOrders(projectRoot) {
+  await markRunAborting(projectRoot, process.pid);
+  await cancelRunMainnetOrders(projectRoot, process.env, "abort");
+}
+async function withMainnetOrderAbort(projectRoot, run) {
+  let aborting;
+  const remove = () => {
+    for (const signal of ABORT_SIGNALS) process.off(signal, onSignal);
+  };
+  function onSignal(signal) {
+    if (aborting) return;
+    aborting = abortRunMainnetOrders(projectRoot).then(
+      () => void 0,
+      (error) => {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      }
+    ).then(() => {
+      remove();
+      process.kill(process.pid, signal);
+    });
+  }
+  for (const signal of ABORT_SIGNALS) process.on(signal, onSignal);
+  try {
+    return await run();
+  } finally {
+    if (aborting) await aborting;
+    else remove();
+  }
+}
+export {
+  abortRunMainnetOrders,
+  cancelRunMainnetOrders,
+  withMainnetOrderAbort
+};

package/dist/adapters/perps-order-inputs.js

@@ -1,35 +1,50 @@
+const ORDER_INPUTS = [
+  [["market", "symbol"], "market=<symbol> (or symbol=<symbol>)"],
+  [["side"], "side=long or side=short"],
+  [["amount", "notional"], "amount=<usd> or notional=<usd>"]
+];
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function opensState(value) {
+  const state = typeof value === "string" ? value.toLowerCase() : void 0;
+  return state === "open" || state === "present";
+}
+function hasValue(source, names) {
+  return names.some((name) => {
+    const value = source[name];
+    return value !== void 0 && value !== null && value !== "";
+  });
+}
+function missingOrderInputs(label, has, pathFor) {
+  return ORDER_INPUTS.filter(([names]) => !has(names)).map(([names, wanted]) => ({
+    severity: "error",
+    code: "recipe.missing_param",
+    path: pathFor(names[0]),
+    message: `${label} requires ${wanted} before it may create an order`
+  }));
+}
 function perpsOrderInputFindings(nodeId, node, { ensureChecksOnly }) {
   const action = node.action;
-  const state = typeof node.state === "string" ? node.state.toLowerCase() : void 0;
-  const createsOrder = action === "metamask.perps.place_order" || !ensureChecksOnly && (action === "metamask.perps.ensure_positions" || action === "metamask.perps.ensure_orders") && (state === "open" || state === "present");
-  if (!createsOrder) return [];
-  const findings = [];
-  const requireOneOf = (names, message) => {
-    const present = names.some((name) => {
-      const value = node[name];
-      return value !== void 0 && value !== null && value !== "";
+  if (action === "metamask.perps.start_state") {
+    if (ensureChecksOnly) return [];
+    return ["positions", "orders"].flatMap((key) => {
+      const block = node[key];
+      if (!isRecord(block) || !opensState(block.state)) return [];
+      return missingOrderInputs(
+        `${action} ${key}.state=${String(block.state)}`,
+        (names) => hasValue(block, names) || names[0] !== "amount" && hasValue(node, names),
+        (name) => `workflow.nodes.${nodeId}.${key}.${name}`
+      );
     });
-    if (present) return;
-    findings.push({
-      severity: "error",
-      code: "recipe.missing_param",
-      path: `workflow.nodes.${nodeId}.${names[0]}`,
-      message
-    });
-  };
-  requireOneOf(
-    ["market", "symbol"],
-    `${action} requires market=<symbol> (or symbol=<symbol>) before it may create an order`
-  );
-  requireOneOf(
-    ["side"],
-    `${action} requires side=long or side=short before it may create an order`
-  );
-  requireOneOf(
-    ["amount", "notional"],
-    `${action} requires amount=<usd> or notional=<usd> before it may create an order`
+  }
+  const createsOrder = action === "metamask.perps.place_order" || !ensureChecksOnly && (action === "metamask.perps.ensure_positions" || action === "metamask.perps.ensure_orders") && opensState(node.state);
+  if (!createsOrder) return [];
+  return missingOrderInputs(
+    String(action),
+    (names) => hasValue(node, names),
+    (name) => `workflow.nodes.${nodeId}.${name}`
   );
-  return findings;
 }
 export {
   perpsOrderInputFindings

package/dist/adapters.js

@@ -118,7 +118,10 @@ async function runLiveFirst(platform, action, node, context, forceLive = false,
     platform,
     action,
     namespace: LIBRARY_ACTION_NAMESPACE,
-    node: withImmediateCloseBudget(action, node),
+    node: withImmediateCloseBudget(
+      action,
+      await getAdapterSurface(platform).actions.liveProcessNode?.(action, node, { ...process.env, ...context.env }) ?? node
+    ),
     context,
     prepared: preparedLiveAdapters?.get(action),
     contextExtras: trustedMutationContextExtras(context),

package/dist/commands/doctor.js

@@ -85,11 +85,14 @@ async function handleDoctor({ options }) {
     } catch (error2) {
       runtimeProbeError2 = error2 instanceof Error ? error2.message : String(error2);
     }
-    const ready = runtime2?.decision === "ready";
+    const recorder2 = runtime2?.decision === "ready" ? await readiness.recorder?.() : void 0;
+    const ready2 = doctorReady(runtime2, recorder2);
     const block = readiness.runtimeBlock?.(target, runtime2);
     if (block) failed.push(block.id);
+    if (recorder2?.status === "fail") failed.push(recorder2.id);
     const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target, block);
-    if (failed.length === 0 && !ready && runtime2?.nextAction) nextActions.push(runtime2.nextAction);
+    if (recorder2?.status === "fail" && recorder2.userAction) nextActions.push(recorder2.userAction);
+    if (failed.length === 0 && runtime2?.decision !== "ready" && runtime2?.nextAction) nextActions.push(runtime2.nextAction);
     const status = result2.status === "pass" && failed.length === 0 ? "pass" : "fail";
     const retryDoctor = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
     const fixUserAction = failed.includes("wallet-fixture") ? `choose one wallet fixture source from nextActions, run it, then retry: ${retryDoctor}` : nextActions[0] ?? retryDoctor;
@@ -98,15 +101,16 @@ async function handleDoctor({ options }) {
       message: "doctor --fix could not make every required check pass",
       userAction: fixUserAction
     } : void 0;
-    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, ready, runtime: runtime2, ...runtimeProbeError2 ? { runtimeProbeError: runtimeProbeError2 } : {}, nextActions, ...error ? { error } : {} }, null, 2));
+    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, ready: ready2, runtime: runtime2, ...recorder2 ? { recorder: recorder2 } : {}, ...runtimeProbeError2 ? { runtimeProbeError: runtimeProbeError2 } : {}, nextActions, ...error ? { error } : {} }, null, 2));
     else {
-      console.log(`${status} ${adapter} ${result2.compatibilityMode} ready=${ready} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
+      console.log(`${status} ${adapter} ${result2.compatibilityMode} ready=${ready2} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
       if (runtime2) {
         console.log(`runtime: decision=${runtime2.decision}${runtime2.reasonCode ? ` (${runtime2.reasonCode})` : ""}`);
         for (const reason of runtime2.reasons) console.log(`  ${reason}`);
       } else if (runtimeProbeError2) {
         console.log(`runtime probe failed: ${runtimeProbeError2}`);
       }
+      if (recorder2) console.log(`recorder: ${recorder2.status} ${recorder2.message}`);
       for (const action of nextActions) console.error(`  Next: ${action}`);
     }
     return status === "pass" ? 0 : 1;
@@ -154,10 +158,12 @@ async function handleDoctor({ options }) {
     runtimeProbeError = error instanceof Error ? error.message : String(error);
   }
   const runtimeCheck = doctorRuntimeCheck(runtime, runtimeProbeError, expectLive);
+  const recorder = runtime?.decision === "ready" ? await readiness.recorder?.() : void 0;
   const checks = [
     ...result.checks,
     runtimeCheck,
     ...await readiness.liveChecks?.(target) ?? [],
+    ...recorder ? [recorder] : [],
     ...await platformDoctorChecks(adapter, target),
     // Which library plugin code this process loaded: library, module and digest.
     ...adapterPluginChecks()
@@ -182,6 +188,7 @@ async function handleDoctor({ options }) {
       adapter,
       target,
       runtime,
+      recorder,
       doctorResult,
       orphanMetros,
       capture,
@@ -201,7 +208,8 @@ async function handleDoctor({ options }) {
   )?.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
   const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
   const next = doctorError?.userAction ?? discovery.deviceDiscoveryErrors?.[0]?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
-  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, view, orphanMetros, capture, skills, update, featureFlags, devices, additionalReachableDevices, ...discovery, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
+  const ready = doctorReady(runtime, recorder);
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready, runtime, ...recorder ? { recorder } : {}, view, orphanMetros, capture, skills, update, featureFlags, devices, additionalReachableDevices, ...discovery, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -222,6 +230,7 @@ async function handleDoctor({ options }) {
     } else if (runtimeProbeError) {
       console.log(`${out("err", "runtime probe failed:")} ${out("dim", runtimeProbeError)}`);
     }
+    if (recorder) console.log(`${out("label", "recorder:")} ${out(recorder.status === "pass" ? "ok" : "err", recorder.status)} ${recorder.message}`);
     console.log(renderCheckoutView(view));
     console.log(`${out("label", "feature flags:")} ${out(
       featureFlags.error || (featureFlags.overrideCount ?? 0) > 0 ? "warn" : "dim",
@@ -246,6 +255,9 @@ async function handleDoctor({ options }) {
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
+function doctorReady(runtime, recorder) {
+  return runtime?.decision === "ready" && recorder?.status !== "fail";
+}
 async function platformDoctorChecks(adapter, target) {
   try {
     return await getAdapterSurface(adapter).doctor?.(target) ?? [];
@@ -297,17 +309,23 @@ function doctorFixNextActions(failed, fixture, adapter, target, block) {
   if (block?.userAction && failed.includes(block.id)) actions.push(block.userAction);
   return actions;
 }
-function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
+function emitExpectLiveVerdict(adapter, target, runtime, verdict, recorder) {
   const out = (style, text) => color(style, text, { stream: process.stderr });
   const detail = runtime ? `${runtime.decision}${runtime.reasonCode ? ` (${runtime.reasonCode})` : ""}` : "runtime probe unavailable";
   console.error(`${out("err", verdict)} ${out("bold", adapter)} ${detail} ${out("dim", target)}`);
   for (const reason of runtime?.reasons ?? []) console.error(`  ${out("dim", reason)}`);
+  if (recorder?.status === "fail") {
+    console.error(`  ${out("err", "recorder:")} ${recorder.message}${recorder.detail ? ` ${out("dim", recorder.detail)}` : ""}`);
+    console.error(`  Next: ${recorder.userAction}`);
+    return;
+  }
   console.error(`  Next: ${runtime?.nextAction ?? getAdapterSurface(adapter).hints.runtimeProbeRecovery(target)}`);
 }
-function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json, printReady, discovery) {
+function emitExpectLive(adapter, target, runtime, recorder, result, orphanMetros, capture, devices, additionalReachableDevices, json, printReady, discovery) {
   const live = runtime?.decision === "ready";
+  const ready = doctorReady(runtime, recorder);
   if (printReady) {
-    if (live) {
+    if (ready) {
       const indicator = farmslotReadyIndicator(adapter, devices);
       if (indicator) {
         console.log(indicator);
@@ -316,21 +334,21 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
       emitExpectLiveVerdict(adapter, target, runtime, "not-ready");
       return EXIT.runtime;
     }
-    emitExpectLiveVerdict(adapter, target, runtime, "not-live");
+    emitExpectLiveVerdict(adapter, target, runtime, live ? "not-ready" : "not-live", recorder);
     return EXIT.runtime;
   }
   if (json) {
     const userAction = runtime?.nextAction ?? getAdapterSurface(adapter).hints.runtimeProbeRecovery(target);
-    const error = live ? void 0 : { code: "RUNTIME_NOT_LIVE", message: `${adapter} runtime is not live`, userAction };
-    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices, ...discovery, ...error ? { error } : {} }, null, 2));
-    return live ? EXIT.ok : EXIT.runtime;
+    const error = !live ? { code: "RUNTIME_NOT_LIVE", message: `${adapter} runtime is not live`, userAction } : !ready ? { code: "RECORDER_UNAVAILABLE", message: recorder.message, userAction: recorder.userAction } : void 0;
+    console.log(JSON.stringify({ ...result, ready, runtime, ...recorder ? { recorder } : {}, orphanMetros, capture, devices, additionalReachableDevices, ...discovery, ...error ? { error } : {} }, null, 2));
+    return ready ? EXIT.ok : EXIT.runtime;
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });
-  if (live) {
+  if (ready) {
     console.log(`${out("ok", "live")} ${out("bold", adapter)} runtime ready`);
     return EXIT.ok;
   }
-  emitExpectLiveVerdict(adapter, target, runtime, "not-live");
+  emitExpectLiveVerdict(adapter, target, runtime, live ? "not-ready" : "not-live", recorder);
   return EXIT.runtime;
 }
 function captureHealth(providers) {
@@ -457,6 +475,7 @@ async function runDoctorFix(adapter, target, manifestValidation, json) {
 }
 export {
   doctorFixNextActions,
+  doctorReady,
   handleDoctor,
   skillsView
 };

package/dist/commands/status-probe.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { fixtureSummary } from "../doctor.js";
 import { normalizeFeatureFlagRecord } from "../feature-flags.js";
 import { mobileBridgeScript } from "../adapters/mobile/bridge-script.js";
+import { isAndroidEmulatorSerial } from "../../library/actions/mobile/platform/bridge.mjs";
 const PROBE_TIMEOUT_MS = 2e3;
 function truncateAddress(address) {
   if (!address || address.length <= 10) return address;
@@ -51,7 +52,7 @@ function parseBridgeEntries(raw) {
 function androidModelMatches(deviceName, model, device, devices) {
   if (deviceName === model || deviceName.startsWith(`${model} -`)) return true;
   if (!deviceName.endsWith(` ${model}`) && !deviceName.includes(` ${model} -`)) return false;
-  const physical = (d) => d.platform === "android" && !d.id.startsWith("emulator-");
+  const physical = (d) => d.platform === "android" && !isAndroidEmulatorSerial(d.id);
   if (!physical(device)) return false;
   return devices.filter((d) => physical(d) && d.name === device.name).length === 1;
 }

package/dist/engine.js

@@ -6,11 +6,15 @@ import {
   fixturePolicyMutationBase,
   fundingOptionsFromCli,
   isFixturePolicyBase,
-  loadTrustedMutationBase
+  loadTrustedMutationBase,
+  validateTrustedMutationPlan
 } from "./funding-execution-context.js";
 import { resolveActionManifest, validateManifest } from "./manifest.js";
 import { LIBRARY_ACTION_NAMESPACE, runnerDir } from "./paths.js";
 import { metaMaskActionExecutionCapabilities } from "./recipe-security.js";
+async function loadEngineMutation({ cli, adapter, ...run }) {
+  return await loadTrustedMutationBase({ ...fundingOptionsFromCli(cli), ...run }) ?? (getAdapterSurface(adapter).actions.trustedMutation === true ? fixturePolicyMutationBase({ artifactsDir: run.artifactsDir, rootRecipe: run.rootRecipe }) : void 0);
+}
 const metaMaskEngine = {
   bundledLibrary: {
     name: "metamask",
@@ -24,12 +28,17 @@ const metaMaskEngine = {
     const { createMetaMaskRunner } = await import("./runner.js");
     return createMetaMaskRunner(adapter, manifest, options);
   },
+  // Preflight checks policy; execution also claims the plan and checks claim conflicts.
   // Funding files from the run's command line, bound to the run's plan. Without
   // them, a platform whose actions take a trusted mutation (the Extension) runs a
   // plan with external mutations in the fixture-policy lane, where each action
   // applies the shared order policy; any other plan runs without one.
   trustedMutation: {
-    load: async ({ cli, adapter, ...run }) => await loadTrustedMutationBase({ ...fundingOptionsFromCli(cli), ...run }) ?? (getAdapterSurface(adapter).actions.trustedMutation === true ? fixturePolicyMutationBase({ artifactsDir: run.artifactsDir, rootRecipe: run.rootRecipe }) : void 0),
+    preflight: async (input, plan) => {
+      const base = await loadEngineMutation(input);
+      if (base) validateTrustedMutationPlan(base, plan);
+    },
+    load: loadEngineMutation,
     // Nothing to bind (undefined): recipe-cli keeps the runner it planned with.
     authorize: async (base, plan) => {
       if (!base) return void 0;

package/dist/funding-execution-context.js

@@ -181,10 +181,9 @@ function fixturePolicyMutationBase(options) {
 function isFixturePolicyBase(base) {
   return base?.proofLane === FIXTURE_POLICY_LANE;
 }
-async function authorizeFixturePolicyPlan(base, plan) {
+async function authorizeFixturePolicyPlan(base, executionPlanSha256) {
   const source = fixturePolicySources.get(base);
   if (!source) throw new Error("Fixture-policy plan authorization requires the runner-created context.");
-  const executionPlanSha256 = normalizeRecipeDigest(plan.digest);
   await mkdir(source.artifactsDir, { recursive: true, mode: 448 });
   const artifactsDir = await realpath(source.artifactsDir);
   const artifactsIdentitySha256 = await directoryIdentity(artifactsDir);
@@ -204,11 +203,9 @@ async function authorizeFixturePolicyPlan(base, plan) {
   });
   return authorized;
 }
-async function authorizeTrustedMutationPlan(base, plan, testIo = {}) {
-  if (isFixturePolicyBase(base)) return authorizeFixturePolicyPlan(base, plan);
-  const source = fundingSources.get(base);
-  if (!source) throw new Error("Funding plan authorization requires the original runner-verified context.");
+function validateTrustedMutationPlan(base, plan) {
   const executionPlanSha256 = normalizeRecipeDigest(plan.digest);
+  if (isFixturePolicyBase(base)) return { executionPlanSha256, operationCounts: [] };
   const nodes = Array.isArray(plan.nodes) ? plan.nodes : [];
   const actual = /* @__PURE__ */ new Map();
   for (const node of nodes) {
@@ -235,9 +232,16 @@ async function authorizeTrustedMutationPlan(base, plan, testIo = {}) {
     }
   }
   if (actual.size === 0) throw new Error("Funding documents require a resolved external-mutation plan.");
+  const operationCounts = [...expected.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([action, count]) => ({ action, count }));
+  return { executionPlanSha256, operationCounts };
+}
+async function authorizeTrustedMutationPlan(base, plan, testIo = {}) {
+  const { executionPlanSha256, operationCounts } = validateTrustedMutationPlan(base, plan);
+  if (isFixturePolicyBase(base)) return authorizeFixturePolicyPlan(base, executionPlanSha256);
+  const source = fundingSources.get(base);
+  if (!source) throw new Error("Funding plan authorization requires the original runner-verified context.");
   await mkdir(source.artifactsDir, { recursive: true, mode: 448 });
   const artifactsIdentitySha256 = await directoryIdentity(source.artifactsDir);
-  const operationCounts = [...expected.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([action, count]) => ({ action, count }));
   const runId = sha256(canonical({
     requestSha256: base.requestSha256,
     preflightSha256: base.preflightSha256,
@@ -1529,5 +1533,6 @@ export {
   selectedIdentityFromWalletImport,
   serializeTrustedMutationContext,
   trustedMutationContextExtras,
-  trustedMutationForAction
+  trustedMutationForAction,
+  validateTrustedMutationPlan
 };

package/dist/host.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { configureHarnessAdapters, configureHarnessHost } from "@farmslot/recipe-cli/harness";
 import { adapterRegistry } from "./adapters/registry.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-configureHarnessHost({
+const providerHost = {
   name: "mm-harness",
   product: "MetaMask",
   envPrefix: "MM_HARNESS",
@@ -28,5 +28,9 @@ configureHarnessHost({
     "stop",
     "verify"
   ]
-});
+};
+configureHarnessHost(providerHost);
 configureHarnessAdapters(adapterRegistry);
+export {
+  providerHost
+};

package/dist/index.js

@@ -1,4 +1,5 @@
 import "./host.js";
+import { createProvider, providerHost } from "./provider.js";
 import { createDoctorReport } from "./doctor.js";
 import { loadActionManifest, validateManifest } from "./manifest.js";
 import { createMetaMaskExtensionRunner, createMetaMaskMobileRunner, createMetaMaskRunner } from "./runner.js";
@@ -13,10 +14,12 @@ export {
   createMetaMaskExtensionRunner,
   createMetaMaskMobileRunner,
   createMetaMaskRunner,
+  createProvider,
   extensionIdPath,
   importRecipeHarnessRuntimeBrowserExtension,
   importRecipeHarnessRuntimeCdp,
   loadActionManifest,
+  providerHost,
   validateManifest,
   walletFixturePath
 };

package/dist/mm-harness-cli.js

@@ -22,6 +22,7 @@ import {
 } from "@farmslot/recipe-cli/harness";
 import { stopProjectCollector } from "../library/actions/shared/analytics/collector.mjs";
 import { adoptPluginAdapter, afterAdapterLoad, configuredLibrarySources } from "./adapters/plugin-surface.js";
+import { withMainnetOrderAbort } from "./adapters/perps-mainnet-cleanup.js";
 import { adapterRegistry } from "./adapters/registry.js";
 import {
   explainMissingAdapterLibrary,
@@ -155,8 +156,9 @@ const PUBLIC_RUN = {
   "execution-template": { run: handleExecutionTemplate },
   actions: { run: (args) => handleActions(parseArgs(args), { catalog: metaMaskEngine }) },
   stop: { run: (args) => handleStop(args, stopOptions) },
-  call: { run: (args) => handleCall(args, callOptions) },
-  run: { run: (args) => handleRun(args, runOptions) },
+  // A signal during run or call still cancels the run's mainnet orders.
+  call: { run: (args) => withMainnetOrderAbort(targetPath(parseArgs(args).options), () => handleCall(args, callOptions)) },
+  run: { run: (args) => withMainnetOrderAbort(targetPath(parseArgs(args).options), () => handleRun(args, runOptions)) },
   last: { run: (args) => handleLast(parseArgs(args)) },
   doctor: { run: (args) => handleDoctor(parseArgs(args)) },
   check: { run: handleCheck },

package/dist/provider.js

@@ -0,0 +1,72 @@
+import "./adapters/surface.js";
+import {
+  configureHarnessAdapters,
+  adapterForPlatform,
+  applyRuntimeDirOption,
+  configureHarnessHost,
+  ensureAdapterLoaded,
+  optionFlag,
+  optionStrings,
+  usageError
+} from "@farmslot/recipe-cli/harness";
+import { MAINNET_RUN_OWNER_ENV } from "../library/actions/shared/perps/mainnet-order-ledger.mjs";
+import { adoptPluginAdapter, afterAdapterLoad, configuredLibrarySources, operatorLibraryEnv } from "./adapters/plugin-surface.js";
+import { abortRunMainnetOrders, cancelRunMainnetOrders } from "./adapters/perps-mainnet-cleanup.js";
+import { adapterRegistry } from "./adapters/registry.js";
+import { getAdapterSurface } from "./adapters/surface.js";
+import { applyDeviceTargeting } from "./commands/device-target.js";
+import { metaMaskEngine } from "./engine.js";
+import { providerHost } from "./host.js";
+import { providerHost as providerHost2 } from "./host.js";
+async function createProvider(context) {
+  configureHarnessHost(context.host ?? providerHost);
+  configureHarnessAdapters(adapterRegistry);
+  const selection = context.adapter?.value;
+  if (!selection) throw usageError("The MetaMask provider requires a resolved adapter.");
+  const adapter = adapterForPlatform(selection) ?? selection;
+  const options = {
+    ...context.options,
+    ...!context.options?.platform && (selection === "ios" || selection === "android") ? { platform: selection } : {}
+  };
+  await ensureAdapterLoaded(adapter, {
+    libraries: optionStrings(options, "library"),
+    configured: context.libraries ?? configuredLibrarySources(),
+    env: operatorLibraryEnv(),
+    adopt: adoptPluginAdapter
+  });
+  await afterAdapterLoad();
+  const runtime = getAdapterSurface(adapter);
+  const executes = (context.command === "run" || context.command === "call") && !["plan", "list", "describe", "help"].some((flag) => optionFlag(options, flag));
+  if (executes) {
+    applyRuntimeDirOption(options);
+    runtime.resolveSlotPorts(context.target.value);
+    const selected = applyDeviceTargeting(context.command, adapter, {
+      ...options,
+      target: context.target.value
+    }, { gate: true, rerun: "" });
+    if (selected.ok === false) throw Object.assign(usageError(selected.message), { code: selected.code, userAction: selected.userAction });
+  }
+  const previousOwner = process.env[MAINNET_RUN_OWNER_ENV];
+  if (executes) process.env[MAINNET_RUN_OWNER_ENV] = String(process.pid);
+  return {
+    runtime,
+    engine: metaMaskEngine,
+    ...executes ? {
+      async cancel() {
+        await abortRunMainnetOrders(context.target.value);
+      },
+      async finalize() {
+        try {
+          await cancelRunMainnetOrders(context.target.value, process.env, "teardown");
+        } finally {
+          if (previousOwner === void 0) delete process.env[MAINNET_RUN_OWNER_ENV];
+          else process.env[MAINNET_RUN_OWNER_ENV] = previousOwner;
+        }
+      }
+    } : {}
+  };
+}
+export {
+  createProvider,
+  providerHost2 as providerHost
+};

package/dist/recipe-security.js

@@ -76,6 +76,7 @@ const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.open_balance_action",
   "metamask.perps.assert_visible_consistency",
   "metamask.perps.start_state",
+  "metamask.perps.set_network",
   "metamask.perps.teardown_state",
   // Consent changes wallet state and is therefore an app mutation.
   "metamask.analytics.set_consent",

package/docs/CONTRIBUTING.md

@@ -199,6 +199,13 @@ 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.
 
+`yarn install` hardlinks every `node_modules` file to Yarn's store
+(`~/.yarn/berry/store`), shared by all worktrees. Never edit an installed
+dependency in place: a write into an existing file reaches the store and every
+other worktree, and a reinstall does not undo it. Use `yarn dev:link-farmslot`
+for local Farmslot builds. To repair a package, remove `node_modules/<package>`
+in one worktree and run `yarn install`.
+
 Docs describe only current behavior. History belongs in the changelog and Git;
 do not add handovers, audits, speculative roadmaps, or duplicate command guides
 under `docs/`.