@deeeed/metamask-harness 0.70.1 → 0.71.0

package/library/actions/terminal/perps/_venue.mjs

@@ -0,0 +1,242 @@
+// Read and clean up Hyperliquid venue state for a terminal fixture account.
+// Reads use the public info API. Writes (cleanup, agent revoke) are testnet-only,
+// signed in this process by the fixture account through the target checkout's
+// own @nktkas/hyperliquid, and never pass through the browser wallet.
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const INFO_URLS = Object.freeze({
+  testnet: 'https://api.hyperliquid-testnet.xyz/info',
+  mainnet: 'https://api.hyperliquid.xyz/info',
+});
+
+// Agents the Web Terminal approves are named "mm-terminal" plus an optional
+// " valid_until <ms>" expiry suffix.
+export const TERMINAL_AGENT_PREFIX = 'mm-terminal';
+
+export function resolveNetwork(node = {}) {
+  const network = node.network == null ? 'testnet' : String(node.network);
+  if (network !== 'testnet' && network !== 'mainnet') {
+    throw new Error(`network must be testnet or mainnet, got ${JSON.stringify(node.network)}.`);
+  }
+  return network;
+}
+
+export const MAINNET_CONFIRMATION = 'REAL_FUNDS';
+
+// Venue mutations default to testnet. Mainnet needs the explicit
+// mainnet_confirmation=REAL_FUNDS on the node, as every library mutation does.
+export function requireTestnet(node = {}, action = 'this action') {
+  const network = resolveNetwork(node);
+  if (network === 'mainnet' && node.mainnet_confirmation === MAINNET_CONFIRMATION) return network;
+  if (network !== 'testnet') {
+    throw new Error(
+      `${action} mutates venue state; refusing network=${network} without mainnet_confirmation=${MAINNET_CONFIRMATION}.`,
+    );
+  }
+  return network;
+}
+
+export async function info(network, body, fetchImpl = globalThis.fetch) {
+  const response = await fetchImpl(INFO_URLS[network], {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    throw new Error(`Hyperliquid ${network} info ${body.type} returned HTTP ${response.status}.`);
+  }
+  return response.json();
+}
+
+export function normalizePosition(entry) {
+  const position = entry?.position ?? entry;
+  const size = Number(position.szi);
+  return {
+    market: String(position.coin).toUpperCase(),
+    side: size >= 0 ? 'long' : 'short',
+    size: String(Math.abs(size)),
+    entryPrice: position.entryPx ?? null,
+    // Numeric entry notional in USD, for cap assertions.
+    notional: position.entryPx == null ? null : Number((Math.abs(size) * Number(position.entryPx)).toFixed(2)),
+    leverage: position.leverage?.value ?? null,
+    marginMode: position.leverage?.type ?? null,
+    liquidationPrice: position.liquidationPx ?? null,
+  };
+}
+
+const TRIGGER_TYPES = {
+  'Stop Market': 'stop_market',
+  'Stop Limit': 'stop_limit',
+  'Take Profit Market': 'take_profit_market',
+  'Take Profit Limit': 'take_profit_limit',
+};
+
+export function normalizeOrder(order) {
+  return {
+    orderId: String(order.oid),
+    market: String(order.coin).toUpperCase(),
+    side: order.side === 'B' ? 'buy' : 'sell',
+    price: order.limitPx ?? null,
+    size: order.sz ?? null,
+    orderType: order.orderType ?? null,
+    triggerType: TRIGGER_TYPES[order.orderType] ?? null,
+    isTrigger: Boolean(order.isTrigger),
+    triggerPrice: order.isTrigger ? order.triggerPx ?? null : null,
+    reduceOnly: Boolean(order.reduceOnly),
+    isPositionTpsl: Boolean(order.isPositionTpsl),
+    timestamp: order.timestamp ?? null,
+  };
+}
+
+// Only a public EVM address ever leaves this process for the info API.
+export function venueUser(address) {
+  const value = String(address ?? '');
+  if (!/^0x[0-9a-fA-F]{40}$/u.test(value)) throw new Error('venue reads need a 0x-prefixed 20-byte account address.');
+  return `0x${value.slice(2).toLowerCase()}`;
+}
+
+export async function readVenueState({ network, user: rawUser, fetchImpl }) {
+  const user = venueUser(rawUser);
+  const [clearinghouse, openOrders, agents] = await Promise.all([
+    info(network, { type: 'clearinghouseState', user }, fetchImpl),
+    info(network, { type: 'frontendOpenOrders', user }, fetchImpl),
+    info(network, { type: 'extraAgents', user }, fetchImpl),
+  ]);
+  return {
+    network,
+    user,
+    positions: (clearinghouse.assetPositions ?? []).map(normalizePosition),
+    orders: (openOrders ?? []).map(normalizeOrder),
+    agents: (agents ?? []).map((agent) => ({
+      name: agent.name,
+      address: agent.address,
+      validUntil: agent.validUntil ?? null,
+    })),
+    accountValue: clearinghouse.marginSummary?.accountValue ?? null,
+    withdrawable: clearinghouse.withdrawable ?? null,
+  };
+}
+
+// Market selection mirrors the core adapter: market/symbol or markets/symbols,
+// with mode=all selecting every item. Positions match side long|short, orders
+// match the side they would open (buy=long, sell=short).
+export function requestedMarkets(node = {}) {
+  const selector = node.selector && typeof node.selector === 'object' ? node.selector : {};
+  if ((node.mode ?? selector.mode) === 'all') return null;
+  const list = [
+    node.market,
+    node.symbol,
+    selector.market,
+    selector.symbol,
+    ...(Array.isArray(node.markets) ? node.markets : []),
+    ...(Array.isArray(node.symbols) ? node.symbols : []),
+    ...(Array.isArray(selector.markets) ? selector.markets : []),
+    ...(Array.isArray(selector.symbols) ? selector.symbols : []),
+  ]
+    .filter((value) => typeof value === 'string' && value.trim())
+    .map((value) => value.trim().toUpperCase());
+  if (list.length === 0) {
+    throw new Error('Select a market (market, markets) or pass mode=all; refusing an implicit account-wide selection.');
+  }
+  return new Set(list);
+}
+
+export function selectItems(node, items, kind) {
+  const markets = requestedMarkets(node);
+  const rawSide = node.side ?? node.selector?.side;
+  const side = rawSide == null ? null : String(rawSide).toLowerCase();
+  return items.filter((item) => {
+    if (markets && !markets.has(item.market)) return false;
+    if (!side) return true;
+    if (kind === 'position') return item.side === side;
+    return (item.side === 'buy' ? 'long' : 'short') === side;
+  });
+}
+
+export function expectedOpen(node, action) {
+  if (node.state == null) throw new Error(`${action} requires state=open or state=none.`);
+  const state = String(node.state).toLowerCase();
+  if (state === 'open' || state === 'present') return true;
+  if (state === 'none' || state === 'closed' || state === 'absent') return false;
+  throw new Error(`${action} received unsupported state: ${state}`);
+}
+
+function sameNumber(actual, expected, tolerancePct = 0) {
+  const a = Number(actual);
+  const e = Number(expected);
+  if (!Number.isFinite(a) || !Number.isFinite(e)) return false;
+  if (tolerancePct <= 0) return a === e;
+  return Math.abs(a - e) <= Math.abs(e) * (tolerancePct / 100);
+}
+
+// Order expectations beyond presence; each failing order is reported.
+export function orderExpectationFailures(node, orders) {
+  const failures = [];
+  const tolerance = Number(node.price_tolerance_pct ?? 0);
+  for (const order of orders) {
+    if (node.expect_limit_price != null && !sameNumber(order.price, node.expect_limit_price, tolerance)) {
+      failures.push(`order ${order.orderId} limit price ${order.price} != ${node.expect_limit_price}`);
+    }
+    if (node.expect_trigger_price != null && !sameNumber(order.triggerPrice, node.expect_trigger_price, tolerance)) {
+      failures.push(`order ${order.orderId} trigger price ${order.triggerPrice} != ${node.expect_trigger_price}`);
+    }
+    if (node.expect_trigger_order_type != null && order.triggerType !== node.expect_trigger_order_type) {
+      failures.push(`order ${order.orderId} trigger type ${order.triggerType} != ${node.expect_trigger_order_type}`);
+    }
+    if (node.expect_reduce_only != null && order.reduceOnly !== Boolean(node.expect_reduce_only)) {
+      failures.push(`order ${order.orderId} reduceOnly ${order.reduceOnly} != ${node.expect_reduce_only}`);
+    }
+    if (node.expect_size != null && !sameNumber(order.size, node.expect_size)) {
+      failures.push(`order ${order.orderId} size ${order.size} != ${node.expect_size}`);
+    }
+  }
+  return failures;
+}
+
+export function filterOrderKind(node, orders) {
+  let selected = orders;
+  if (node.only_trigger_orders === true || node.order_kind === 'trigger') selected = selected.filter((order) => order.isTrigger);
+  if (node.order_kind === 'limit') selected = selected.filter((order) => !order.isTrigger);
+  if (node.trigger_kind === 'take_profit') selected = selected.filter((order) => order.triggerType?.startsWith('take_profit'));
+  if (node.trigger_kind === 'stop_loss') selected = selected.filter((order) => order.triggerType?.startsWith('stop'));
+  if (Array.isArray(node.order_ids) && node.order_ids.length > 0) {
+    const ids = new Set(node.order_ids.map(String));
+    selected = selected.filter((order) => ids.has(order.orderId));
+  }
+  return selected;
+}
+
+export async function pollUntil(read, done, timeoutMs, intervalMs = 750) {
+  const deadline = Date.now() + Math.max(0, Number(timeoutMs) || 0);
+  let value = await read();
+  while (!done(value) && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, Math.max(1, deadline - Date.now()))));
+    value = await read();
+  }
+  return value;
+}
+
+// The terminal checkout ships the SDK it trades with; use that exact copy.
+export async function loadTargetHyperliquid(projectRoot) {
+  const require = createRequire(path.join(projectRoot, 'package.json'));
+  let entry;
+  try {
+    entry = require.resolve('@nktkas/hyperliquid');
+  } catch {
+    throw new Error(
+      `@nktkas/hyperliquid is not installed in ${projectRoot}.\nNext: npm ci in the terminal checkout.`,
+    );
+  }
+  return import(pathToFileURL(entry).href);
+}
+
+// Hyperliquid prices: at most 5 significant figures and (6 - szDecimals)
+// decimals for perps.
+export function venuePrice(raw, szDecimals) {
+  const decimals = Math.max(0, 6 - szDecimals);
+  const significant = Number(Number(raw).toPrecision(5));
+  return String(Number(significant.toFixed(decimals)));
+}

package/library/actions/terminal/perps/assert_orders.mjs

@@ -0,0 +1,54 @@
+// Assert presence, absence, count and field expectations (limit/trigger price,
+// trigger type, reduce-only, size) of the selected venue open orders.
+
+import { isDirectRun, resolveAccountAddress, runAdapter } from '../platform/runtime.mjs';
+import {
+  expectedOpen,
+  filterOrderKind,
+  orderExpectationFailures,
+  pollUntil,
+  readVenueState,
+  resolveNetwork,
+  selectItems,
+} from './_venue.mjs';
+
+export async function assertOrders(input, deps = {}) {
+  const node = input.node ?? {};
+  const expectOpen = expectedOpen(node, 'metamask.perps.assert_orders');
+  const network = resolveNetwork(node);
+  const { name, address } = await resolveAccountAddress(input);
+  const expectCount = node.expect_count ?? node.expectCount;
+  const reached = (matching) => {
+    if (!expectOpen) return matching.length === 0;
+    const countOk = expectCount == null ? matching.length > 0 : matching.length === Number(expectCount);
+    return countOk && orderExpectationFailures(node, matching).length === 0;
+  };
+  const matching = await pollUntil(
+    async () => filterOrderKind(node, selectItems(node, (await readVenueState({ network, user: address, fetchImpl: deps.fetchImpl })).orders, 'order')),
+    reached,
+    node.timeout_ms,
+  );
+  if (!reached(matching)) {
+    const failures = expectOpen ? orderExpectationFailures(node, matching) : [];
+    const wanted = !expectOpen ? 'no' : expectCount == null ? 'at least one' : `exactly ${expectCount}`;
+    throw new Error(
+      `Expected ${wanted} matching venue order(s), found ${matching.length}` +
+      `${failures.length ? `; ${failures.join('; ')}` : ''}: ${JSON.stringify(matching)}`,
+    );
+  }
+  return {
+    action: input.action,
+    source: 'hyperliquid-info-frontendOpenOrders',
+    network,
+    account: address,
+    accountName: name,
+    expectedOpen: expectOpen,
+    matchingCount: matching.length,
+    expectedCount: expectCount == null ? null : Number(expectCount),
+    orders: matching,
+    orderIds: matching.map((order) => order.orderId),
+    proofPath: 'venue-frontendOpenOrders',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => assertOrders(input));

package/library/actions/terminal/perps/assert_positions.mjs

@@ -0,0 +1,40 @@
+// Assert presence, absence or exact count of the selected venue positions,
+// polling up to timeout_ms for the expected state.
+
+import { isDirectRun, resolveAccountAddress, runAdapter } from '../platform/runtime.mjs';
+import { expectedOpen, pollUntil, readVenueState, resolveNetwork, selectItems } from './_venue.mjs';
+
+export async function assertPositions(input, deps = {}) {
+  const node = input.node ?? {};
+  const expectOpen = expectedOpen(node, 'metamask.perps.assert_positions');
+  const network = resolveNetwork(node);
+  const { name, address } = await resolveAccountAddress(input);
+  const expectCount = node.expect_count ?? node.expectCount;
+  const reached = (matching) => {
+    if (!expectOpen) return matching.length === 0;
+    return expectCount == null ? matching.length > 0 : matching.length === Number(expectCount);
+  };
+  const matching = await pollUntil(
+    async () => selectItems(node, (await readVenueState({ network, user: address, fetchImpl: deps.fetchImpl })).positions, 'position'),
+    reached,
+    node.timeout_ms,
+  );
+  if (!reached(matching)) {
+    const wanted = !expectOpen ? 'no' : expectCount == null ? 'at least one' : `exactly ${expectCount}`;
+    throw new Error(`Expected ${wanted} matching venue position(s), found ${matching.length}: ${JSON.stringify(matching)}`);
+  }
+  return {
+    action: input.action,
+    source: 'hyperliquid-info-clearinghouseState',
+    network,
+    account: address,
+    accountName: name,
+    expectedOpen: expectOpen,
+    matchingCount: matching.length,
+    expectedCount: expectCount == null ? null : Number(expectCount),
+    positions: matching,
+    proofPath: 'venue-clearinghouseState',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => assertPositions(input));

package/library/actions/terminal/perps/read_orders.mjs

@@ -0,0 +1,26 @@
+// Read the fixture account's Hyperliquid open orders for the selected markets.
+
+import { isDirectRun, resolveAccountAddress, runAdapter } from '../platform/runtime.mjs';
+import { filterOrderKind, readVenueState, resolveNetwork, selectItems } from './_venue.mjs';
+
+export async function readOrders(input, deps = {}) {
+  const node = input.node ?? {};
+  const network = resolveNetwork(node);
+  const { name, address } = await resolveAccountAddress(input);
+  const state = await readVenueState({ network, user: address, fetchImpl: deps.fetchImpl });
+  const matching = filterOrderKind(node, selectItems(node, state.orders, 'order'));
+  return {
+    action: input.action,
+    source: 'hyperliquid-info-frontendOpenOrders',
+    network,
+    account: address,
+    accountName: name,
+    count: state.orders.length,
+    matchingCount: matching.length,
+    orders: matching,
+    orderIds: matching.map((order) => order.orderId),
+    proofPath: 'venue-frontendOpenOrders',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => readOrders(input));

package/library/actions/terminal/perps/read_positions.mjs

@@ -0,0 +1,25 @@
+// Read the fixture account's Hyperliquid positions for the selected markets.
+
+import { isDirectRun, resolveAccountAddress, runAdapter } from '../platform/runtime.mjs';
+import { readVenueState, resolveNetwork, selectItems } from './_venue.mjs';
+
+export async function readPositions(input, deps = {}) {
+  const node = input.node ?? {};
+  const network = resolveNetwork(node);
+  const { name, address } = await resolveAccountAddress(input);
+  const state = await readVenueState({ network, user: address, fetchImpl: deps.fetchImpl });
+  const matching = selectItems(node, state.positions, 'position');
+  return {
+    action: input.action,
+    source: 'hyperliquid-info-clearinghouseState',
+    network,
+    account: address,
+    accountName: name,
+    count: state.positions.length,
+    matchingCount: matching.length,
+    positions: matching,
+    proofPath: 'venue-clearinghouseState',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => readPositions(input));

package/library/actions/terminal/perps/read_snapshot.mjs

@@ -0,0 +1,40 @@
+// Snapshot the fixture account's venue state: positions, open orders, agents and
+// balances, optionally scoped to markets. Used for before/after comparison.
+
+import { isDirectRun, resolveAccountAddress, runAdapter } from '../platform/runtime.mjs';
+import { readVenueState, resolveNetwork, selectItems } from './_venue.mjs';
+
+const MARKET_KEYS = ['market', 'markets', 'symbol', 'symbols'];
+
+// The snapshot covers every market unless the node names some, through any of
+// the selector spellings selectItems accepts.
+export function snapshotSelector(raw = {}) {
+  const node = { ...raw };
+  const selector = node.selector && typeof node.selector === 'object' ? node.selector : {};
+  const named = MARKET_KEYS.some((key) => node[key] != null || selector[key] != null);
+  if (node.mode == null && selector.mode == null && !named) node.mode = 'all';
+  return node;
+}
+
+export async function readSnapshot(input, deps = {}) {
+  const node = snapshotSelector(input.node ?? {});
+  const network = resolveNetwork(node);
+  const { name, address } = await resolveAccountAddress(input);
+  const state = await readVenueState({ network, user: address, fetchImpl: deps.fetchImpl });
+  return {
+    action: input.action,
+    source: 'hyperliquid-info',
+    network,
+    account: address,
+    accountName: name,
+    at: new Date().toISOString(),
+    positions: selectItems(node, state.positions, 'position'),
+    orders: selectItems(node, state.orders, 'order'),
+    agents: state.agents,
+    accountValue: state.accountValue,
+    withdrawable: state.withdrawable,
+    proofPath: 'venue-snapshot',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => readSnapshot(input));

package/library/actions/terminal/perps/revoke_agent.mjs

@@ -0,0 +1,58 @@
+// Lifecycle step (testnet; mainnet only with mainnet_confirmation=REAL_FUNDS): revoke the Web Terminal's Hyperliquid agent(s) for the
+// fixture account outside the UI (approveAgent to the zero address under the
+// same name, user-signed in Node), then assert none is left. The next UI write
+// must therefore ask the wallet for a fresh ApproveAgent.
+
+import { accountName, fixtureAccount, isDirectRun, readBrowserState, runAdapter } from '../platform/runtime.mjs';
+import { TERMINAL_AGENT_PREFIX, loadTargetHyperliquid, pollUntil, readVenueState, requireTestnet } from './_venue.mjs';
+
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+export function agentBaseName(name) {
+  return String(name).replace(/\s+valid_until\s+\d+$/u, '');
+}
+
+export function terminalAgents(agents, prefix = TERMINAL_AGENT_PREFIX) {
+  return agents.filter((agent) => agentBaseName(agent.name) === prefix);
+}
+
+export async function revokeAgent(input, deps = {}) {
+  const node = input.node ?? {};
+  const network = requireTestnet(node, 'metamask.perps.revoke_agent');
+  const prefix = node.agent_name ?? TERMINAL_AGENT_PREFIX;
+  const projectRoot = input.context?.projectRoot;
+  const name = accountName(input, await readBrowserState(projectRoot));
+  const account = deps.account ?? (await fixtureAccount(projectRoot, name));
+  const read = () => readVenueState({ network, user: account.address, fetchImpl: deps.fetchImpl });
+  const before = terminalAgents((await read()).agents, prefix);
+  const responses = [];
+  if (before.length > 0) {
+    const hl = deps.hl ?? (await loadTargetHyperliquid(projectRoot));
+    const exchange = new hl.ExchangeClient({ wallet: account, transport: new hl.HttpTransport({ isTestnet: network === 'testnet' }) });
+    for (const agentName of new Set(before.map((agent) => agentBaseName(agent.name)))) {
+      const response = await exchange.approveAgent({ agentAddress: ZERO_ADDRESS, agentName });
+      responses.push({ agentName, status: response?.status ?? null });
+    }
+  }
+  const after = await pollUntil(
+    async () => terminalAgents((await read()).agents, prefix),
+    (agents) => agents.length === 0,
+    node.timeout_ms ?? 20000,
+  );
+  if (after.length > 0) {
+    throw new Error(`terminal agent still approved after revoke: ${JSON.stringify(after.map((agent) => agent.address))}`);
+  }
+  return {
+    action: input.action,
+    source: 'hyperliquid-exchange-fixture-signer',
+    network,
+    account: account.address,
+    accountName: name,
+    revokedAgents: before.map((agent) => ({ name: agent.name, address: agent.address })),
+    responses,
+    remainingAgents: after.length,
+    proofPath: 'venue-extraAgents',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => revokeAgent(input));

package/library/actions/terminal/perps/teardown_state.mjs

@@ -0,0 +1,104 @@
+// Testnet cleanup for one reserved market: cancel its open orders (or only the
+// listed order_ids) and close its position with a reduce-only IOC order, signed
+// in Node by the fixture account, then assert the requested end state. Testnet by
+// default; mainnet only with mainnet_confirmation=REAL_FUNDS. Refuses
+// account-wide selection.
+
+import { fixtureAccount, isDirectRun, readBrowserState, accountName, runAdapter } from '../platform/runtime.mjs';
+import {
+  filterOrderKind,
+  info,
+  loadTargetHyperliquid,
+  pollUntil,
+  readVenueState,
+  requireTestnet,
+  requestedMarkets,
+  selectItems,
+  venuePrice,
+} from './_venue.mjs';
+
+const CLOSE_SLIPPAGE = 0.05;
+
+function wantsNone(spec, label) {
+  if (spec == null) return false;
+  const state = String(spec.state ?? spec).toLowerCase();
+  if (state === 'none' || state === 'closed' || state === 'absent') return true;
+  throw new Error(`metamask.perps.teardown_state only converges ${label} to state=none, got ${state}.`);
+}
+
+export async function teardownState(input, deps = {}) {
+  const node = input.node ?? {};
+  const network = requireTestnet(node, 'metamask.perps.teardown_state');
+  const markets = requestedMarkets(node);
+  if (!markets) throw new Error('metamask.perps.teardown_state requires an explicit market; mode=all is refused.');
+  const closePositions = wantsNone(node.positions ?? { state: 'none' }, 'positions');
+  const cancelOrders = wantsNone(node.orders ?? { state: 'none' }, 'orders');
+  const projectRoot = input.context?.projectRoot;
+  const name = accountName(input, await readBrowserState(projectRoot));
+  const account = deps.account ?? (await fixtureAccount(projectRoot, name));
+  const user = account.address;
+  const read = () => readVenueState({ network, user, fetchImpl: deps.fetchImpl });
+  const before = await read();
+  const orders = cancelOrders ? filterOrderKind(node, selectItems(node, before.orders, 'order')) : [];
+  const positions = closePositions ? selectItems(node, before.positions, 'position') : [];
+  const actions = { canceledOrderIds: [], closedPositions: [], responses: [] };
+
+  if (orders.length > 0 || positions.length > 0) {
+    const hl = deps.hl ?? (await loadTargetHyperliquid(projectRoot));
+    const exchange = new hl.ExchangeClient({ wallet: account, transport: new hl.HttpTransport({ isTestnet: network === 'testnet' }) });
+    const [meta, mids] = await Promise.all([
+      info(network, { type: 'meta' }, deps.fetchImpl),
+      info(network, { type: 'allMids' }, deps.fetchImpl),
+    ]);
+    const assetOf = (market) => {
+      const index = meta.universe.findIndex((asset) => asset.name.toUpperCase() === market);
+      if (index < 0) throw new Error(`market ${market} is not in the ${network} perps universe.`);
+      return { index, szDecimals: meta.universe[index].szDecimals };
+    };
+    if (orders.length > 0) {
+      const response = await exchange.cancel({
+        cancels: orders.map((order) => ({ a: assetOf(order.market).index, o: Number(order.orderId) })),
+      });
+      actions.responses.push({ cancel: response?.response?.data ?? response });
+      actions.canceledOrderIds.push(...orders.map((order) => order.orderId));
+    }
+    for (const position of positions) {
+      const { index, szDecimals } = assetOf(position.market);
+      const mid = Number(mids[position.market]);
+      if (!Number.isFinite(mid)) throw new Error(`no ${network} mid price for ${position.market}.`);
+      const isBuy = position.side === 'short';
+      const price = venuePrice(mid * (isBuy ? 1 + CLOSE_SLIPPAGE : 1 - CLOSE_SLIPPAGE), szDecimals);
+      const response = await exchange.order({
+        orders: [{ a: index, b: isBuy, p: price, s: position.size, r: true, t: { limit: { tif: 'Ioc' } } }],
+        grouping: 'na',
+      });
+      actions.responses.push({ close: response?.response?.data ?? response });
+      actions.closedPositions.push({ market: position.market, side: position.side, size: position.size });
+    }
+  }
+
+  const done = (state) =>
+    (!cancelOrders || filterOrderKind(node, selectItems(node, state.orders, 'order')).length === 0) &&
+    (!closePositions || selectItems(node, state.positions, 'position').length === 0);
+  const after = await pollUntil(read, done, node.timeout_ms ?? 30000);
+  const remaining = {
+    orders: cancelOrders ? filterOrderKind(node, selectItems(node, after.orders, 'order')) : [],
+    positions: closePositions ? selectItems(node, after.positions, 'position') : [],
+  };
+  if (!done(after)) {
+    throw new Error(`testnet cleanup left state behind for ${[...markets].join(',')}: ${JSON.stringify(remaining)}`);
+  }
+  return {
+    action: input.action,
+    source: 'hyperliquid-exchange-fixture-signer',
+    network,
+    account: user,
+    accountName: name,
+    markets: [...markets],
+    ...actions,
+    remaining,
+    proofPath: 'venue-cleanup',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter((input) => teardownState(input));

package/library/actions/terminal/platform/hud.mjs

@@ -0,0 +1,71 @@
+// app.hud for the terminal: fold the runner's progress update into
+// <runtime>/hud.json and draw it on the app tab now. The wallet host redraws
+// the same state after every navigation. The HUD is advisory: a missing
+// browser or a busy tab skips the update instead of failing the recipe.
+
+import { clearHudState, hudRenderExpression, nextHudState, readHudState, writeHudState } from '../../../../adapters/terminal/lib/hud.mjs';
+import { isAppUrl } from '../../../../adapters/terminal/lib/origin.mjs';
+import { appOrigin, cdpPort, readBrowserState, terminalRuntimeDir } from './runtime.mjs';
+import { importRecipeHarnessRuntimeCdp } from '../../harness-exports.mjs';
+
+// --hud show draws in any mode; --hud auto (the default) only for a visible
+// browser. --hud hide never reaches this handler.
+export function hudVisible(policy, browserState) {
+  if (policy === 'show') return true;
+  return browserState?.browser?.headless !== true;
+}
+
+// Every CDP step is bounded: a busy tab must never stall the recipe.
+export function withDeadline(promise, timeoutMs, label) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+async function drawOnAppTabs(input, expression, timeoutMs = 3000) {
+  const { CdpSession, listCdpTargets } = await importRecipeHarnessRuntimeCdp();
+  const origin = appOrigin(input);
+  const targets = (await withDeadline(listCdpTargets('127.0.0.1', cdpPort(input)), timeoutMs, 'HUD target list'))
+    .filter((target) => target.type === 'page' && isAppUrl(target.url, origin));
+  const results = [];
+  for (const target of targets) {
+    const connecting = CdpSession.connect(target.webSocketDebuggerUrl, { timeoutMs });
+    let session;
+    try {
+      session = await withDeadline(connecting, timeoutMs, 'HUD connect');
+      const response = await withDeadline(session.call('Runtime.evaluate', { expression, returnByValue: true }), timeoutMs, 'HUD draw');
+      results.push(response?.result?.value ?? null);
+    } finally {
+      if (session) session.close();
+      // A connect that lands after its deadline is closed as soon as it opens.
+      else connecting.then((late) => late.close(), () => {});
+    }
+  }
+  return results;
+}
+
+export async function showTerminalHud(input, { hudPolicy = 'auto' } = {}) {
+  const node = input.node ?? {};
+  const projectRoot = input.context?.projectRoot;
+  const nodeId = input.context?.nodeId ?? '';
+  const browserState = projectRoot ? await readBrowserState(projectRoot) : null;
+  if (!browserState) return { hud: false, skipped: true, reason: 'no slot browser yet' };
+  if (!hudVisible(hudPolicy, browserState)) return { hud: false, skipped: true, reason: 'headless browser (--hud show draws anyway)' };
+  const runtimeDir = terminalRuntimeDir(projectRoot);
+  let state = null;
+  if (node.clear === true) {
+    clearHudState(runtimeDir);
+  } else {
+    state = nextHudState(readHudState(runtimeDir), node, nodeId);
+    writeHudState(runtimeDir, state);
+  }
+  try {
+    const drawn = await drawOnAppTabs(input, hudRenderExpression(state, appOrigin(input)));
+    return { hud: Boolean(state), seq: state?.seq ?? null, status: node.status ?? 'running', tabs: drawn.length };
+  } catch (error) {
+    process.stderr.write(`app.hud skipped (slot browser busy or gone): ${error?.message ?? error}\n`);
+    return { hud: false, skipped: true, seq: state?.seq ?? null, reason: String(error?.message ?? error) };
+  }
+}