@deeeed/metamask-harness 0.79.0 → 0.81.0

package/adapters/terminal/wallet-host.mjs

@@ -27,19 +27,20 @@
 import { appendFileSync, chmodSync, existsSync, unwatchFile, watchFile, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { createStrictWallet, createWalletRequestBinding, pageReadyExpression, pageScriptSource } from '@farmslot/adapter-web/dapp';
+import { isAppUrl as isExactAppUrl, shortUrl } from '@farmslot/adapter-web/origin';
 
 import { CdpClient, browserWebSocketUrl } from './lib/cdp-client.mjs';
 import { hudFile, hudRenderExpression, readHudState } from './lib/hud.mjs';
-import { LINK_HOSTS, hostOf, isMainnetVenueUrl, mainnetTypedDataReason } from './lib/mainnet-guard.mjs';
+import { hostOf, isMainnetVenueUrl } from './lib/mainnet-guard.mjs';
 import { ownedBrowserPids } from './lib/processes.mjs';
-import { isAppTopFrameContext, isAppUrl as isExactAppUrl } from './lib/origin.mjs';
-import { LOG_BINDING, REQUEST_BINDING, RESOLVE_FN, pageScriptSource } from './lib/page-script.mjs';
-import { createStrictWallet } from './lib/strict-wallet.mjs';
 
 const { captureMacFrontmost, macFocusDisabled } = createRequire(import.meta.url)('@farmslot/adapter-web/macos-focus');
 
 function usage() {
-  return 'Usage: wallet-host.mjs --cdp-port <port> --runtime-dir <dir> --signer <extension|injected> --app-origin <url> [--network testnet|mainnet] [--mainnet-hosts <h1,h2>] [--testnet-hosts <h1,h2>] [--extension-id <id>] [--target <checkout> --account <name> --start-chain <id>] [--observe-focus 1] [--window x,y,w,h] [--start-path <path>] [--mm-harness-owner=<marker>]';
+  return 'Usage: wallet-host.mjs --cdp-port <port> --runtime-dir <dir> --signer <extension|injected> --app-origin <url> --policy-module <venue policy module> [--network testnet|mainnet] [--mainnet-hosts <h1,h2>] [--testnet-hosts <h1,h2>] [--extension-id <id>] [--target <checkout> --account <name> --start-chain <id>] [--observe-focus 1] [--window x,y,w,h] [--start-path <path>] [--mm-harness-owner=<marker>]';
 }
 
 function parseArgs(argv) {
@@ -58,13 +59,17 @@ function parseArgs(argv) {
     args[flag.slice(2)] = argv[index + 1];
     index += 1;
   }
-  for (const key of ['cdp-port', 'runtime-dir', 'signer', 'app-origin']) {
+  for (const key of ['cdp-port', 'runtime-dir', 'signer', 'app-origin', 'policy-module']) {
     if (!args[key]) throw new Error(`Missing --${key}\n${usage()}`);
   }
   return args;
 }
 
 const args = parseArgs(process.argv.slice(2));
+// The venue policy (the Terminal's adapters/terminal/policy.mjs): link hosts,
+// the probe host, the typed-data refusal and the start page.
+const { policy } = await import(pathToFileURL(path.resolve(args['policy-module'])).href);
+const LINK_HOSTS = new Set(policy.linkHosts);
 const runtimeDir = path.resolve(args['runtime-dir']);
 const logFile = path.join(runtimeDir, 'wallet-requests.jsonl');
 const signer = args.signer;
@@ -79,6 +84,19 @@ if (network === 'testnet' && mainnetHosts.length === 0) throw new Error('testnet
 // only, never a link host (app.hyperliquid-testnet.xyz serves pages and icons).
 const testnetHosts = String(args['testnet-hosts'] ?? '').split(',').filter((host) => host && !LINK_HOSTS.has(host));
 const PROBE_MARK = 'mm-harness-probe=1';
+// A testnet run never lets the typed data the policy refuses reach the signer.
+const refuseTypedData = network === 'testnet' ? policy.refuseTypedData : null;
+// The injected strict wallet presents as MetaMask, so the app connects to it
+// the way it connects to the extension.
+const INJECTED_WALLET = {
+  info: {
+    uuid: '5d1e5b4e-e2e0-4c3f-9a1d-000000000001',
+    name: 'MetaMask (strict test wallet)',
+    icon: "data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'/>",
+    rdns: 'io.metamask',
+  },
+  isMetaMask: true,
+};
 
 // The request log is evidence; keep it owner-only even when it already exists.
 if (existsSync(logFile)) chmodSync(logFile, 0o600);
@@ -96,29 +114,23 @@ if (signer === 'injected') {
   const { fixtureAccount } = await import('../../library/actions/terminal/platform/runtime.mjs');
   if (!args.target || !args.account) throw new Error('injected mode requires --target and --account');
   const account = await fixtureAccount(path.resolve(args.target), args.account);
-  wallet = createStrictWallet({ account, chainId: Number(args['start-chain'] ?? 42161) });
+  wallet = createStrictWallet({ account, chainId: Number(args['start-chain'] ?? policy.startChain) });
   say(`injected strict wallet ready for ${args.account} (${account.address}) on chain ${wallet.chainId}`);
 }
 
-const source = pageScriptSource({ signer, appOrigin, network });
+const source = pageScriptSource({ signer, appOrigin, refuseTypedData, injectedWallet: INJECTED_WALLET });
 const client = await CdpClient.connect(await browserWebSocketUrl(Number(args['cdp-port'])));
+// Judges each binding call against the frame and document that made it, logs
+// it and, in injected mode, answers it with the strict wallet.
+const binding = createWalletRequestBinding({ client, appOrigin, signer, wallet, refuseTypedData, record: appendEntry, say });
 // Hooks are installed once per target: a second session for the same tab
 // (auto-attach plus a restored tab) would log every request twice.
 const hookedTargets = new Map();
 const appSessions = new Set();
-// Per app session: its target id (= main frame id), the URL its top frame has
-// committed, and live execution contexts, so a binding call can be traced to
-// the frame, document and origin that made it.
+// Per app session: its target id (= main frame id) and the URL its top frame
+// has committed.
 const sessionTargets = new Map();
 const sessionCommittedUrls = new Map();
-const sessionContexts = new Map();
-// Binding calls whose execution context, or that context's document, is not
-// known yet.
-const pendingCalls = new Map();
-// Per app session: the URL of a top-frame commit no execution context has
-// been tied to yet.
-const awaitingDocuments = new Map();
-const PENDING_CALL_TTL_MS = 5000;
 // App sessions whose target runs with domains enabled; the HUD is drawn only
 // there so no evaluate ever waits on a tab paused for setup.
 const hudSessions = new Set();
@@ -129,41 +141,6 @@ function isAppUrl(url) {
   return url === 'about:blank' || url === '' || isExactAppUrl(url, appOrigin);
 }
 
-function isTopDefaultContext(sessionId, context) {
-  return context?.auxData?.isDefault === true && context.auxData.frameId === sessionTargets.get(sessionId);
-}
-
-// A top-frame commit is tied to the top frame's default context of its
-// document: one created before the commit and still untied, or else the next
-// one created.
-// A commit is applied once: Page.getFrameTree and Page.frameNavigated can
-// both report the same document (its loaderId); a second report would leave a
-// stale commit waiting for the next document's context.
-const appliedCommits = new Map();
-function assignDocumentUrl(sessionId, url, loaderId) {
-  if (loaderId) {
-    if (appliedCommits.get(sessionId) === loaderId) return;
-    appliedCommits.set(sessionId, loaderId);
-  }
-  const untied = [...(sessionContexts.get(sessionId)?.values() ?? [])]
-    .filter((context) => isTopDefaultContext(sessionId, context) && context.documentUrl === null);
-  if (untied.length === 0) {
-    awaitingDocuments.set(sessionId, url);
-    return;
-  }
-  for (const context of untied) context.documentUrl = url;
-}
-
-// Judged against the caller's own document, not the tab's latest commit.
-function callerIsAppTopFrame(sessionId, executionContextId) {
-  const context = sessionContexts.get(sessionId)?.get(executionContextId);
-  return isAppTopFrameContext(context, {
-    targetId: sessionTargets.get(sessionId),
-    appOrigin,
-    committedUrl: context?.documentUrl ?? null,
-  });
-}
-
 // MetaMask shows dapp requests in its side panel (the fixture default) or a
 // notification/popup window; only request routes count as confirmations.
 const WALLET_SURFACES = ['sidepanel.html', 'notification.html', 'popup.html'];
@@ -233,9 +210,7 @@ function bounded(promise, label, ms = 10000) {
 async function installAppHooks(sessionId, targetId) {
   appSessions.add(sessionId);
   sessionTargets.set(sessionId, targetId);
-  sessionContexts.set(sessionId, new Map());
-  await bounded(client.send('Runtime.addBinding', { name: LOG_BINDING }, sessionId), 'Runtime.addBinding');
-  if (signer === 'injected') await bounded(client.send('Runtime.addBinding', { name: REQUEST_BINDING }, sessionId), 'Runtime.addBinding');
+  await bounded(binding.install(sessionId, targetId), 'Runtime.addBinding');
   await bounded(client.send('Page.addScriptToEvaluateOnNewDocument', { source, runImmediately: true }, sessionId), 'Page.addScriptToEvaluateOnNewDocument');
   if (network === 'testnet') {
     await bounded(client.send('Fetch.enable', {
@@ -244,16 +219,6 @@ async function installAppHooks(sessionId, targetId) {
   }
 }
 
-// Where a request went, without its query string or body.
-function shortUrl(url) {
-  try {
-    const parsed = new URL(url);
-    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
-  } catch {
-    return String(url).slice(0, 120);
-  }
-}
-
 // Venue traffic per app session: the served-network check. Only venue
 // endpoints count (the block list and the testnet endpoints); other hosts on a
 // venue domain, such as the coin icons on app.hyperliquid.xyz, are ignored.
@@ -288,10 +253,10 @@ async function enableAppDomains(sessionId) {
   const { frameTree } = await bounded(client.send('Page.getFrameTree', {}, sessionId), 'Page.getFrameTree');
   if (frameTree?.frame?.url !== undefined) {
     sessionCommittedUrls.set(sessionId, frameTree.frame.url);
-    assignDocumentUrl(sessionId, frameTree.frame.url, frameTree.frame.loaderId);
+    binding.commit(sessionId, frameTree.frame.url, frameTree.frame.loaderId);
   }
   if (appSessions.has(sessionId)) hudSessions.add(sessionId);
-  drainPendingCalls(sessionId);
+  binding.drain(sessionId);
 }
 
 // Redraw the HUD on app pages. The expression is a no-op when the same state
@@ -344,18 +309,13 @@ client.on('Target.targetCreated', ({ targetInfo }) => {
   if (targetInfo.type === 'page') observeWalletSurface(targetInfo.targetId, targetInfo.url);
 });
 client.on('Target.detachedFromTarget', ({ sessionId }) => {
-  // Calls still waiting for their document can no longer be judged.
-  for (const call of pendingCalls.get(sessionId) ?? []) recordUnattributed(call, 'its tab detached first');
-  awaitingDocuments.delete(sessionId);
-  appliedCommits.delete(sessionId);
+  binding.detach(sessionId);
   const targetId = sessionTargets.get(sessionId);
   if (targetId && hookedTargets.get(targetId)?.sessionId === sessionId) hookedTargets.delete(targetId);
   appSessions.delete(sessionId);
   hudSessions.delete(sessionId);
   sessionTargets.delete(sessionId);
   sessionCommittedUrls.delete(sessionId);
-  sessionContexts.delete(sessionId);
-  pendingCalls.delete(sessionId);
 });
 // What the app tab's first navigation did, for the diagnostic when it never
 // commits: main-frame commits, and the document's response or failure.
@@ -370,8 +330,7 @@ client.on('Page.frameNavigated', ({ frame }, sessionId) => {
   if (sessionId === appNavigation.session && !frame.parentId) appNavigation.commits.push(pathOf(frame.url));
   if (appSessions.has(sessionId) && !frame.parentId) {
     sessionCommittedUrls.set(sessionId, frame.url);
-    assignDocumentUrl(sessionId, frame.url, frame.loaderId);
-    drainPendingCalls(sessionId);
+    binding.commit(sessionId, frame.url, frame.loaderId);
   }
 });
 client.on('Fetch.requestPaused', ({ requestId, request, resourceType }, sessionId) => {
@@ -407,25 +366,6 @@ client.on('Network.webSocketCreated', ({ requestId, url }, sessionId) => {
     say(`blocked a mainnet WebSocket to ${shortUrl(url)}`);
   }
 });
-client.on('Runtime.executionContextCreated', ({ context }, sessionId) => {
-  const contexts = sessionContexts.get(sessionId);
-  if (!contexts) return;
-  contexts.set(context.id, context);
-  if (isTopDefaultContext(sessionId, context)) {
-    // The navigation this document belongs to may already have committed
-    // (frameNavigated first) or not yet (the context first).
-    const awaiting = awaitingDocuments.get(sessionId);
-    context.documentUrl = awaiting ?? null;
-    awaitingDocuments.delete(sessionId);
-  }
-  drainPendingCalls(sessionId);
-});
-client.on('Runtime.executionContextDestroyed', ({ executionContextId }, sessionId) => {
-  sessionContexts.get(sessionId)?.delete(executionContextId);
-});
-client.on('Runtime.executionContextsCleared', (_params, sessionId) => {
-  sessionContexts.get(sessionId)?.clear();
-});
 for (const event of ['Page.domContentEventFired', 'Page.loadEventFired', 'Page.navigatedWithinDocument']) {
   client.on(event, (_params, sessionId) => {
     if (hudSessions.has(sessionId)) drawHud([sessionId]);
@@ -436,123 +376,6 @@ for (const event of ['Page.domContentEventFired', 'Page.loadEventFired', 'Page.n
 watchFile(hudFile(runtimeDir), { interval: 500 }, () => drawHud());
 const hudRepeat = setInterval(() => drawHud(), 2000);
 
-// Answer a request the host refuses, so the page's promise settles instead of
-// hanging; harmless where the preload (and its resolver) is absent.
-function refuse(sessionId, executionContextId, id, message) {
-  const outcome = { error: { message, code: 4100 } };
-  const expression = `typeof window.${RESOLVE_FN} === 'function' && window.${RESOLVE_FN}(${JSON.stringify(id)}, ${JSON.stringify(outcome)})`;
-  return client.send('Runtime.evaluate', { expression, contextId: executionContextId }, sessionId).catch(() => {});
-}
-
-function requestId(name, payload) {
-  if (name !== REQUEST_BINDING) return null;
-  try {
-    return JSON.parse(payload).id ?? null;
-  } catch {
-    return null;
-  }
-}
-
-async function handleBindingCall({ name, payload, executionContextId }, sessionId) {
-  // Only the app's own top frame may log or ask the injected wallet to sign;
-  // anything else (an iframe, a blank popup, a page the tab navigated to) is
-  // dropped, and a refused request is answered with 4100.
-  if (!callerIsAppTopFrame(sessionId, executionContextId)) {
-    const context = sessionContexts.get(sessionId)?.get(executionContextId);
-    appendEntry({ kind: 'outside-app-frame', t: Date.now(), binding: name === REQUEST_BINDING ? 'request' : 'log', origin: context?.origin ?? null, document: context?.documentUrl ? shortUrl(context.documentUrl) : null });
-    say(`ignored ${name === REQUEST_BINDING ? 'wallet request' : 'log entry'} from outside the app top frame`);
-    const id = requestId(name, payload);
-    if (id !== null) await refuse(sessionId, executionContextId, id, 'Wallet requests are accepted only from the app top frame.');
-    return;
-  }
-  if (name === LOG_BINDING) {
-    try {
-      appendEntry(JSON.parse(payload));
-    } catch (error) {
-      say(`unparseable log payload: ${error.message}`);
-    }
-    return;
-  }
-  if (name !== REQUEST_BINDING || !wallet) return;
-  const { id, method, params } = JSON.parse(payload);
-  if (network === 'testnet' && /^eth_signTypedData/u.test(String(method))) {
-    let reason = null;
-    try {
-      reason = mainnetTypedDataReason(typeof params?.[1] === 'string' ? JSON.parse(params[1]) : params?.[1]);
-    } catch {
-      reason = null;
-    }
-    if (reason) {
-      appendEntry({ kind: 'refused-mainnet', t: Date.now(), method, reason, layer: 'wallet-host' });
-      await refuse(sessionId, executionContextId, id, 'Refused: this test run is held to Hyperliquid testnet and the request signs a mainnet action.');
-      return;
-    }
-  }
-  let outcome;
-  try {
-    outcome = { result: await wallet.request({ method, params }) };
-  } catch (error) {
-    outcome = { error: { message: String(error.message), code: error.code ?? -32603 } };
-  }
-  await client.send(
-    'Runtime.evaluate',
-    { expression: `window.${RESOLVE_FN}(${JSON.stringify(id)}, ${JSON.stringify(outcome)})`, contextId: executionContextId },
-    sessionId,
-  ).catch((error) => say(`resolve ${method} failed: ${error.message}`));
-}
-
-// A binding call can arrive before its execution context is reported (the
-// domains are enabled after the tab resumes), or before its document's commit.
-// Hold it until both are known; after a short wait it cannot be judged: it is
-// logged as unattributed (and a request is refused).
-function drainPendingCalls(sessionId) {
-  const queue = pendingCalls.get(sessionId);
-  if (!queue) return;
-  for (const call of [...queue]) {
-    const known = callAttributable(sessionId, call.executionContextId);
-    if (!known && Date.now() - call.at < PENDING_CALL_TTL_MS) continue;
-    queue.splice(queue.indexOf(call), 1);
-    if (known) {
-      handleBindingCall(call, sessionId);
-      continue;
-    }
-    recordUnattributed(call, 'its document was never attributed');
-    const id = requestId(call.name, call.payload);
-    if (id !== null) refuse(sessionId, call.executionContextId, id, 'Wallet request from a document the harness could not attribute.');
-  }
-}
-
-function recordUnattributed(call, why) {
-  let entry = {};
-  try {
-    entry = JSON.parse(call.payload);
-  } catch {
-    entry = {};
-  }
-  const binding = call.name === REQUEST_BINDING ? 'request' : 'log';
-  appendEntry({ kind: 'unattributed', t: Date.now(), binding, method: typeof entry.method === 'string' ? entry.method : null, loggedKind: typeof entry.kind === 'string' ? entry.kind : null, reason: why });
-  say(`a wallet ${binding === 'request' ? 'request' : 'log entry'} could not be judged (${why}); recorded as unattributed`);
-}
-
-// A binding call can be judged once its execution context is known and, for
-// the top frame's default context, the URL of that context's own document.
-function callAttributable(sessionId, executionContextId) {
-  const context = sessionContexts.get(sessionId)?.get(executionContextId);
-  if (!context) return false;
-  return !isTopDefaultContext(sessionId, context) || context.documentUrl !== null;
-}
-
-client.on('Runtime.bindingCalled', (call, sessionId) => {
-  if (callAttributable(sessionId, call.executionContextId)) {
-    handleBindingCall(call, sessionId);
-    return;
-  }
-  const queue = pendingCalls.get(sessionId) ?? [];
-  queue.push({ ...call, at: Date.now() });
-  pendingCalls.set(sessionId, queue);
-  setTimeout(() => drainPendingCalls(sessionId), PENDING_CALL_TTL_MS + 50);
-});
-
 client.on('close', () => {
   clearInterval(hudRepeat);
   unwatchFile(hudFile(runtimeDir));
@@ -632,7 +455,7 @@ for (const info of startupTabs) {
 // The first app document is a market page: it streams from the venue in the
 // browser, which the served-network check below observes (the home page's
 // data comes from the server render).
-const startUrl = new URL(args['start-path'] || '/order/BTC', `${appOrigin}/`).href;
+const startUrl = new URL(args['start-path'] || policy.startPath, `${appOrigin}/`).href;
 appNavigation.session = appSession;
 const navigation = await bounded(client.send('Page.navigate', { url: startUrl }, appSession), 'Page.navigate', 60000).catch((error) => fail(error.message));
 const navigateStart = Date.now();
@@ -652,13 +475,7 @@ const evaluate = (expression, timeoutMs = 5000) => bounded(
 // The first app document must carry the log binding and the installed
 // preload (its marker), with the page's provider wrapped, or requests on it
 // would go unrecorded.
-const readyExpression = [
-  `typeof window.${LOG_BINDING} === 'function'`,
-  ...(signer === 'injected' ? [`typeof window.${REQUEST_BINDING} === 'function'`] : []),
-  `Boolean(window.__mmTerminalHarness && window.__mmTerminalHarness.signer === ${JSON.stringify(signer)} && window.__mmTerminalHarness.network === ${JSON.stringify(network)})`,
-  // The provider the app sees is the wrapped one, and no wrap failed.
-  'window.__mmTerminalHarness.wrapFailures.length === 0 && window.__mmTerminalHarness.covers(window.ethereum)',
-].join(' && ');
+const readyExpression = pageReadyExpression({ signer, refusesTypedData: refuseTypedData !== null });
 let hooksReady = false;
 for (let attempt = 0; attempt < 50 && !hooksReady; attempt += 1) {
   hooksReady = (await evaluate(readyExpression)) === true;
@@ -670,10 +487,11 @@ if (network === 'testnet') {
   // The block must hold before anything runs: a probe to the mainnet venue
   // from the app page has to fail (HTTP through the request block and the
   // resolver rule, WebSocket through the resolver rule).
-  const host = mainnetHosts.includes('api.hyperliquid.xyz') ? 'api.hyperliquid.xyz' : mainnetHosts[0];
-  const httpProbe = await evaluate(`fetch('https://${host}/info?${PROBE_MARK}', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{"type":"meta"}' }).then(() => 'reached', () => 'blocked')`, 20000);
-  const resolverProbe = await evaluate(`fetch('https://${host}:${RESOLVER_PROBE_PORT}/info?${PROBE_MARK}', { method: 'POST' }).then(() => 'reached', () => 'blocked')`, 20000);
-  const wsProbe = await evaluate(`new Promise((resolve) => { const socket = new WebSocket('wss://${host}/ws?${PROBE_MARK}'); const done = (value) => { try { socket.close(); } catch {} resolve(value); }; socket.onopen = () => done('reached'); socket.onerror = () => done('blocked'); setTimeout(() => done('timeout'), 10000); })`, 20000);
+  const { probe } = policy;
+  const host = mainnetHosts.includes(probe.host) ? probe.host : mainnetHosts[0];
+  const httpProbe = await evaluate(`fetch('https://${host}${probe.httpPath}?${PROBE_MARK}', { method: 'POST', headers: { 'content-type': 'application/json' }, body: ${JSON.stringify(probe.httpBody)} }).then(() => 'reached', () => 'blocked')`, 20000);
+  const resolverProbe = await evaluate(`fetch('https://${host}:${RESOLVER_PROBE_PORT}${probe.httpPath}?${PROBE_MARK}', { method: 'POST' }).then(() => 'reached', () => 'blocked')`, 20000);
+  const wsProbe = await evaluate(`new Promise((resolve) => { const socket = new WebSocket('wss://${host}${probe.wsPath}?${PROBE_MARK}'); const done = (value) => { try { socket.close(); } catch {} resolve(value); }; socket.onopen = () => done('reached'); socket.onerror = () => done('blocked'); setTimeout(() => done('timeout'), 10000); })`, 20000);
   if (httpProbe !== 'blocked' || resolverProbe !== 'blocked' || wsProbe !== 'blocked') {
     fail(`the mainnet venue is reachable from the app (http ${httpProbe}, resolver ${resolverProbe}, websocket ${wsProbe})`);
   }

package/bin/mm-harness

@@ -90,24 +90,6 @@ if [ -f "$ENSURE_DEPS" ]; then
   bash "$ENSURE_DEPS" "$RUNNER_DIR"
 fi
 
-find_protocol_root() {
-  local start="$1"
-  local dir
-  dir="$(cd "$start" && pwd -P)"
-  while [ "$dir" != "/" ]; do
-    if [ -f "$dir/packages/recipe-runner/package.json" ] && [ -f "$dir/packages/protocol/package.json" ]; then
-      printf '%s\n' "$dir"
-      return 0
-    fi
-    if [ -f "$dir/farmslot/packages/recipe-runner/package.json" ] && [ -f "$dir/farmslot/packages/protocol/package.json" ]; then
-      printf '%s\n' "$dir/farmslot"
-      return 0
-    fi
-    dir="$(dirname "$dir")"
-  done
-  return 1
-}
-
 node_can_run_source_typescript() {
   # Node refuses type-stripping for files under node_modules (ERR_UNSUPPORTED_NODE_
   # MODULES_TYPE_STRIPPING). When this runner is installed as a dependency, the
@@ -183,20 +165,19 @@ if [ ! -f "$ENTRY_TS" ]; then
   exit 1
 fi
 
-TSX_BIN="${TSX_BIN:-$RUNNER_DIR/node_modules/.bin/tsx}"
-if [ ! -x "$TSX_BIN" ] && [ -x "$RUNNER_DIR/../../.bin/tsx" ]; then
-  TSX_BIN="$RUNNER_DIR/../../.bin/tsx"
+# ENTRY_TSX, not TSX_BIN: TSX_BIN is the caller's choice of runner for live
+# adapter scripts too, so this fallback must not overwrite the exported value.
+ENTRY_TSX="${TSX_BIN:-$RUNNER_DIR/node_modules/.bin/tsx}"
+if [ ! -x "$ENTRY_TSX" ] && [ -x "$RUNNER_DIR/../../.bin/tsx" ]; then
+  ENTRY_TSX="$RUNNER_DIR/../../.bin/tsx"
 fi
-if [ ! -x "$TSX_BIN" ]; then
+if [ ! -x "$ENTRY_TSX" ]; then
   if [ -z "${FARMSLOT_ROOT:-}" ] && [ -f "$RUNNER_DIR/.farmslot-root" ]; then
     FARMSLOT_ROOT="$(cat "$RUNNER_DIR/.farmslot-root")"
   fi
-  if [ -z "${FARMSLOT_ROOT:-}" ]; then
-    FARMSLOT_ROOT="$(find_protocol_root "$RUNNER_DIR" || find_protocol_root "$PWD" || true)"
-  fi
   if [ -n "${FARMSLOT_ROOT:-}" ]; then
     FARMSLOT_ROOT="$(cd "$FARMSLOT_ROOT" && pwd -P)"
-    TSX_BIN="$FARMSLOT_ROOT/node_modules/.bin/tsx"
+    ENTRY_TSX="$FARMSLOT_ROOT/node_modules/.bin/tsx"
   fi
 fi
 
@@ -204,8 +185,8 @@ if node_can_run_source_typescript; then
   exec node --no-warnings "$ENTRY_TS" "$@"
 fi
 
-if [ -x "$TSX_BIN" ]; then
-  exec "$TSX_BIN" "$ENTRY_TS" "$@"
+if [ -x "$ENTRY_TSX" ]; then
+  exec "$ENTRY_TSX" "$ENTRY_TS" "$@"
 fi
 
 echo "mm-harness: source checkout requires dist/mm-harness-cli.js, Node.js TypeScript type stripping, or a local tsx binary." >&2

package/dist/adapters/checkout-files.js

@@ -0,0 +1,16 @@
+import fs from "node:fs";
+import path from "node:path";
+function checkoutHas(target, relative) {
+  return fs.existsSync(path.join(target, relative));
+}
+function checkoutHasDir(target, relative) {
+  try {
+    return fs.statSync(path.join(target, relative)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+export {
+  checkoutHas,
+  checkoutHasDir
+};

package/dist/adapters/console-capture.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import {
   collectorMatches,
   collectorOwnerMarker,
+  collectorStatus,
   isLegacyCollector,
   isOwnedCollector,
   isPriorInstallCollector,
@@ -80,6 +81,17 @@ async function stopProcess(pid) {
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
 }
+async function verifyOwnedCollectorControl(capture, control) {
+  const status = collectorStatus({
+    pidFile: capture.pidFile,
+    extensionLog: capture.extensionLog,
+    marker: collectorOwnerMarker(path.dirname(capture.pidFile)),
+    cdpPort: capture.cdpPort
+  });
+  if (!status.ok) return { ok: false, detail: status.detail };
+  const result = await control();
+  return { ok: result.ok, detail: result.ok ? `${status.detail}; ${result.detail}` : result.detail };
+}
 const ROTATE_LOG_BYTES = 32 * 1024 * 1024;
 function rotateLargeLog(file) {
   if (fileSize(file) < ROTATE_LOG_BYTES) return;
@@ -118,5 +130,6 @@ function containsAttachment(from) {
 export {
   COLLECTOR_SCRIPT,
   ROTATE_LOG_BYTES,
-  ensureConsoleCollector
+  ensureConsoleCollector,
+  verifyOwnedCollectorControl
 };

package/dist/adapters/core/actions.js

@@ -1,19 +1,23 @@
 import { manifestPath } from "../../paths.js";
+import { perpsOrderInputFindings } from "../perps-order-inputs.js";
 const coreActions = {
   manifestPath: () => manifestPath("core"),
   semantic: [
     "metamask.perps.close_positions",
     "metamask.perps.start_state",
     "metamask.perps.read_snapshot",
-    "metamask.perps.read_account"
+    "metamask.perps.read_account",
+    "metamask.perps.quote_fees"
   ],
-  // read_account is Core's alone, and only its live adapter implements it.
-  liveOnly: ["metamask.perps.read_account"],
+  // 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" }
+  cdpTarget: { transport: "chrome-extension-cdp", probePath: "json/version" },
+  // ensure_positions and ensure_orders with an open or present state place an order.
+  inputFindings: (nodeId, node) => perpsOrderInputFindings(nodeId, node, { ensureChecksOnly: false })
 };
 export {
   coreActions

package/dist/adapters/core/overlay.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { recipeHarnessPath } from "../../paths.js";
+import { recipeHarnessPath } from "@farmslot/recipe-cli/harness";
 function isExecutable(file) {
   try {
     const stat = fs.statSync(file);

package/dist/adapters/core/readiness.js

@@ -1,8 +1,35 @@
 import fs from "node:fs";
 import path from "node:path";
+import { coreDependencyBlock } from "../../commands/core-readiness.js";
+import { resolveLiveTsx } from "../../live-tsx.js";
 const coreReadiness = {
-  compatibilityMode: (target) => fs.existsSync(path.join(target, "packages/perps-controller/src/index.ts")) ? "headless controller (no bridge)" : "unsupported/no bridge"
+  compatibilityMode: (target) => fs.existsSync(path.join(target, "packages/perps-controller/src/index.ts")) ? "headless controller (no bridge)" : "unsupported/no bridge",
+  checks: (target) => [coreControllerActionsCheck(target)]
 };
+function coreControllerActionsCheck(target) {
+  const block = coreDependencyBlock(target);
+  if (block) {
+    return {
+      id: "core-controller-actions",
+      status: "fail",
+      // A checkout with no dependencies installed is reported, not failed: the
+      // runtime check already says it is not ready and how to install. Once
+      // dependencies are installed, an action that still cannot run fails doctor.
+      required: block.code !== "CORE_DEPS_MISSING",
+      message: `metamask.perps.* actions cannot run: ${block.message}`,
+      detail: block.code,
+      userAction: block.userAction
+    };
+  }
+  const runner = resolveLiveTsx(target);
+  return {
+    id: "core-controller-actions",
+    status: "pass",
+    required: true,
+    message: "metamask.perps.* actions can run.",
+    detail: runner ? `tsx (${runner.source}): ${runner.bin}` : void 0
+  };
+}
 export {
   coreReadiness
 };

package/dist/adapters/core/run.js

@@ -1,11 +1,11 @@
+import { isRecord } from "@farmslot/recipe-cli/harness";
 import { coreDependencyBlock } from "../../commands/core-readiness.js";
-import { isRecord } from "../../commands/parse-args.js";
 const coreRun = {
   async dependencyBlock(target, { recipe, librarySources, action }) {
     const usesController = action !== void 0 ? actionUsesCoreController(action) : await recipeUsesCoreController(recipe, librarySources);
     return usesController ? coreDependencyBlock(target) : null;
   },
-  violationUserAction: (violation) => violation.code === "WALLET_STATE_REQUIRED" ? "for signing, configure a reserved wallet-fixture.json account and pass its non-empty name; an explicit 0x address is supported only by read-only actions" : void 0
+  violationUserAction: (violation) => violation.code === "WALLET_STATE_REQUIRED" ? "for signing, select a wallet-fixture.json account by name or by its address; an address outside the fixture works only for read-only actions" : void 0
 };
 async function recipeUsesCoreController(recipe, librarySources) {
   if (objectUsesCoreController(recipe)) return true;

package/dist/adapters/core/surface.js

@@ -1,12 +1,14 @@
+import { shellQuote } from "@farmslot/recipe-cli/harness";
 import path from "node:path";
 import { depsCheck } from "@farmslot/recipe-runner/runtime/deps-readiness";
 import { defineAdapter } from "@farmslot/adapter-sdk";
-import { shellQuote } from "../../commands/parse-args.js";
 import { adapterRegistry } from "../registry.js";
 import { coreActions } from "./actions.js";
 import { coreHarness, corePrepare, coreRuntimeContext } from "./overlay.js";
 import { coreReadiness } 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,
@@ -15,6 +17,16 @@ const coreSurface = defineAdapter({
   },
   async runtimeStatus(target) {
     const deps = depsCheck(path.resolve(target));
+    const block = deps.status === "current" ? coreDependencyBlock(target) : null;
+    if (block) {
+      return {
+        decision: "blocked",
+        reasonCode: block.code,
+        reasons: [`Core is headless; controller actions cannot run: ${block.message}`],
+        nextAction: block.userAction,
+        deps: deps.status
+      };
+    }
     const ready = deps.status === "current";
     return {
       decision: ready ? "ready" : "install",
@@ -56,6 +68,9 @@ const coreSurface = defineAdapter({
   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",