@deeeed/metamask-harness 0.86.1 → 0.87.0

package/library/actions/mobile/platform/bridge.mjs

@@ -29,6 +29,13 @@ const { resolvePort } = configModule;
 // second import path into the cjs bridge-runtime.
 export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
 export const MOBILE_BRIDGE_RESULT_ERROR_CODES = BRIDGE_RESULT_ERROR_CODES;
+// Budget exhaustion, kept apart from the bridge's CDP_TIMEOUT: ACTION_DEADLINE
+// is a bridge command its caller's deadline refused or cut short;
+// DOMAIN_SETUP_DEADLINE is a setup phase that ran out of its slice.
+export const MOBILE_BUDGET_ERROR_CODES = Object.freeze({
+  ACTION_DEADLINE: 'ACTION_DEADLINE',
+  DOMAIN_SETUP_DEADLINE: 'DOMAIN_SETUP_DEADLINE',
+});
 
 const execFileAsync = promisify(execFile);
 const ACTION_DEADLINE_FIELD = '_action_deadline_epoch_ms';
@@ -256,7 +263,11 @@ export function resolveMobileTarget(input) {
   const iosSimulator = input.node?.simulator ?? input.node?.ios_simulator ?? contextEnv.IOS_SIMULATOR ?? process.env.IOS_SIMULATOR;
   const androidDevice = input.node?.android_device ?? contextEnv.ANDROID_DEVICE ?? process.env.ANDROID_DEVICE;
   const androidTargetDeviceName = input.node?.android_target_device_name ?? input.node?.androidTargetDeviceName ?? contextEnv.ANDROID_TARGET_DEVICE_NAME ?? process.env.ANDROID_TARGET_DEVICE_NAME;
-  const adbSerial = input.node?.adb_serial ?? contextEnv.ADB_SERIAL ?? contextEnv.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL ?? androidDevice;
+  const explicitAdbSerial = input.node?.adb_serial ?? contextEnv.ADB_SERIAL ?? contextEnv.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
+  const adbSerial = explicitAdbSerial ?? androidDevice;
+  // Only an explicit adb serial says which device class answers: ANDROID_DEVICE
+  // alone can be an AVD or Metro device name.
+  const physicalAndroid = Boolean(explicitAdbSerial) && !isAndroidEmulatorSerial(explicitAdbSerial);
   if (requestedPlatform === 'ios') {
     return {
       watcherPort,
@@ -264,6 +275,7 @@ export function resolveMobileTarget(input) {
       androidDevice: undefined,
       androidTargetDeviceName: undefined,
       adbSerial: undefined,
+      physicalAndroid: false,
       requestedPlatform,
     };
   }
@@ -274,6 +286,7 @@ export function resolveMobileTarget(input) {
       androidDevice,
       androidTargetDeviceName,
       adbSerial,
+      physicalAndroid,
       requestedPlatform,
     };
   }
@@ -283,10 +296,15 @@ export function resolveMobileTarget(input) {
     androidDevice,
     androidTargetDeviceName,
     adbSerial,
+    physicalAndroid,
     requestedPlatform,
   };
 }
 
+export function isAndroidEmulatorSerial(serial) {
+  return String(serial ?? '').startsWith('emulator-');
+}
+
 export async function openExternalDeeplink(input, url, timeout = 15000) {
   const target = resolveMobileTarget(input);
   const requestedPlatform = String(
@@ -470,17 +488,17 @@ export async function bridgeCommand(input, args) {
     ? actionDeadline - Date.now()
     : configuredTimeoutMs;
   if (remainingActionMs <= 0) {
-    throw coded(
-      new Error(
-        `Mobile CDP bridge command did not start before its action deadline: ${String(args[0] ?? 'unknown')}`,
-      ),
-      BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+    const error = new Error(
+      `ACTION_DEADLINE: bridge command ${String(args[0] ?? 'unknown')} was not started; its action deadline passed ${Math.round(-remainingActionMs)}ms ago (per-command limit ${configuredTimeoutMs}ms).`,
     );
+    error.deadlineEpochMs = actionDeadline;
+    throw coded(error, MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE);
   }
   const timeoutMs = Math.max(
     1,
     Math.min(configuredTimeoutMs, remainingActionMs),
   );
+  const cutByActionDeadline = timeoutMs < configuredTimeoutMs;
   const result = await new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [script, ...args], {
       cwd: input.context.projectRoot,
@@ -521,8 +539,20 @@ export async function bridgeCommand(input, args) {
   });
   if (result.timedOut) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
+    // A timer the action deadline shortened means the caller's budget ran out,
+    // not the bridge: say so, and keep it out of the target-transition codes
+    // so route waits stop instead of retrying refused commands.
+    if (cutByActionDeadline) {
+      const error = new Error(
+        `ACTION_DEADLINE: bridge command ${String(args[0] ?? 'unknown')} was stopped after ${result.timeoutMs}ms when its action deadline ended (per-command limit ${configuredTimeoutMs}ms): ${command}`,
+      );
+      error.deadlineEpochMs = actionDeadline;
+      throw coded(error, MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE);
+    }
     throw coded(
-      new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`),
+      new Error(
+        `Mobile CDP bridge command timed out after ${result.timeoutMs}ms (CDP_COMMAND_TIMEOUT: per-command limit ${configuredTimeoutMs}ms${Number.isFinite(actionDeadline) ? `, action budget had ${Math.max(0, Math.round(actionDeadline - Date.now()))}ms left` : ''}): ${command}`,
+      ),
       BRIDGE_ERROR_CODES.CDP_TIMEOUT,
     );
   }
@@ -628,6 +658,13 @@ export function isTargetTransition(error) {
   return TARGET_TRANSITION_CODES.has(error?.code);
 }
 
+// A read a target transition interrupted, or the action deadline cut short,
+// has no answer yet. Polling callers treat it as "not yet" so their own loop
+// ends at the deadline with its own timeout message.
+export function isUnansweredRead(error) {
+  return isTargetTransition(error) || error?.code === MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE;
+}
+
 function valueContains(actual, expected) {
   if (Array.isArray(expected)) {
     return Array.isArray(actual) &&
@@ -663,13 +700,152 @@ function routeTransitionProven(previousRoute, currentRoute, expectedRoute, expec
   );
 }
 
+export function inheritedDeadline(input) {
+  const deadline = Number(input.node?.[ACTION_DEADLINE_FIELD]);
+  return Number.isFinite(deadline) ? deadline : null;
+}
+
+export function earliestDeadline(input, deadline) {
+  const inherited = inheritedDeadline(input);
+  return inherited === null ? deadline : Math.min(deadline, inherited);
+}
+
+// The earlier of now + timeoutMs and the calling action's deadline. Route waits
+// use it because past the action deadline bridgeCommand refuses to start
+// get-route (ACTION_DEADLINE): polling on would only retry that refusal and
+// could never see a route that did arrive.
+export function deadlineFromTimeout(input, timeoutMs) {
+  return earliestDeadline(input, Date.now() + Math.max(0, Number(timeoutMs)));
+}
+
+// Default budgets by device class. A physical Android device over USB answers
+// bridge calls in 0.1-0.5 s when idle and slower while the app is busy; a Perps
+// market-details -> home navigation on a Pixel 6a took ~18 s. Emulators and
+// simulators keep the shorter budgets so a real hang there still fails fast.
+const MOBILE_BUDGET_DEFAULTS = Object.freeze({
+  virtual: { setupMs: 30_000, navigationMs: 15_000 },
+  physical: { setupMs: 60_000, navigationMs: 30_000 },
+});
+// Per bridge command inside a domain setup, so one hung command cannot spend
+// the whole setup budget. Recipes override it with cdp_timeout_ms.
+export const SETUP_COMMAND_TIMEOUT_MS = 15_000;
+
+function positiveMs(value) {
+  const ms = Number(value);
+  return value !== null && value !== '' && Number.isFinite(ms) && ms > 0 ? ms : null;
+}
+
+// Env overrides (MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS,
+// MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS) replace the device-class defaults;
+// a node's own timeout_ms / navigation_timeout_ms still wins over both.
+export function mobileBudgetDefaults(input) {
+  const env = { ...process.env, ...(input.context?.env || {}) };
+  const deviceClass = resolveMobileTarget(input).physicalAndroid ? 'physical' : 'virtual';
+  const defaults = MOBILE_BUDGET_DEFAULTS[deviceClass];
+  return {
+    deviceClass,
+    setupMs: positiveMs(env.MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS) ?? defaults.setupMs,
+    navigationMs:
+      positiveMs(env.MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS) ?? defaults.navigationMs,
+  };
+}
+
+export function mobileNavigationTimeoutMs(input) {
+  return positiveMs(input.node?.navigation_timeout_ms) ?? mobileBudgetDefaults(input).navigationMs;
+}
+
+export function mobileSetupTimeoutMs(input) {
+  return positiveMs(input.node?.timeout_ms) ?? mobileBudgetDefaults(input).setupMs;
+}
+
+// One overall budget for a multi-step domain setup (unlock, navigation, state
+// convergence). Each phase runs on its own deadline: the rest of the setup
+// budget, or less when sliceMs bounds it. Each bridge command inside a phase
+// gets the per-command limit, capped by that phase deadline. A phase that runs
+// out of time fails as DOMAIN_SETUP_DEADLINE naming the phase and both limits,
+// not as a CDP timeout of whichever command happened to be running.
+export function createSetupBudget(input, action) {
+  const { deviceClass } = mobileBudgetDefaults(input);
+  const navigationMs = mobileNavigationTimeoutMs(input);
+  const commandMs =
+    positiveMs(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms) ??
+    SETUP_COMMAND_TIMEOUT_MS;
+  const startedAt = Date.now();
+  const deadline = deadlineFromTimeout(input, mobileSetupTimeoutMs(input));
+  const limitMs = deadline - startedAt;
+
+  function deadlineError(phase, phaseStartedAt, phaseLimitMs, sliced, cause) {
+    const now = Date.now();
+    const budget = {
+      action,
+      phase,
+      deviceClass,
+      phaseElapsedMs: now - phaseStartedAt,
+      phaseLimitMs,
+      setupElapsedMs: now - startedAt,
+      setupLimitMs: limitMs,
+    };
+    const phaseText = cause === null
+      ? `phase '${phase}' could not start`
+      : `phase '${phase}' ran ${budget.phaseElapsedMs}ms of its ${phaseLimitMs}ms ${sliced ? 'slice' : 'share of the setup budget'}`;
+    const error = new Error(
+      `DOMAIN_SETUP_DEADLINE: ${action} ${phaseText}; setup ran ${budget.setupElapsedMs}ms of ${limitMs}ms (${deviceClass} device). ` +
+        `Raise timeout_ms (setup) or navigation_timeout_ms (navigation slice) on the node, or MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS / MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS.` +
+        (cause === null ? '' : `\n  Cause: ${String(cause?.message ?? cause)}`),
+      cause === null ? undefined : { cause },
+    );
+    error.budget = budget;
+    return coded(error, MOBILE_BUDGET_ERROR_CODES.DOMAIN_SETUP_DEADLINE);
+  }
+
+  return {
+    deadline,
+    limitMs,
+    navigationMs,
+    async phase(name, run, { sliceMs } = {}) {
+      const phaseStartedAt = Date.now();
+      const sliced = sliceMs !== undefined && phaseStartedAt + sliceMs < deadline;
+      const phaseDeadline = sliced ? phaseStartedAt + sliceMs : deadline;
+      const phaseLimitMs = phaseDeadline - phaseStartedAt;
+      if (phaseLimitMs <= 0) {
+        throw deadlineError(name, phaseStartedAt, phaseLimitMs, false, null);
+      }
+      const commandLimitMs = Math.min(commandMs, phaseLimitMs);
+      const phaseInput = {
+        ...input,
+        node: {
+          ...input.node,
+          [ACTION_DEADLINE_FIELD]: phaseDeadline,
+          timeout_ms: phaseLimitMs,
+          bridge_timeout_ms: commandLimitMs,
+          cdp_timeout_ms: commandLimitMs,
+          controller_ready_timeout_ms: phaseLimitMs,
+          navigation_timeout_ms: Math.min(navigationMs, phaseLimitMs),
+        },
+      };
+      try {
+        return await run(phaseInput);
+      } catch (error) {
+        if (error?.code === MOBILE_BUDGET_ERROR_CODES.DOMAIN_SETUP_DEADLINE) throw error;
+        // A nested wait with its own shorter deadline is not this phase running out.
+        const phaseRanOut =
+          Date.now() >= phaseDeadline ||
+          (error?.code === MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE &&
+            error.deadlineEpochMs >= phaseDeadline);
+        if (!phaseRanOut) throw error;
+        throw deadlineError(name, phaseStartedAt, phaseLimitMs, sliced, error);
+      }
+    },
+  };
+}
+
 async function waitForNextRouteProbe(deadline) {
   const remaining = deadline - Date.now();
   if (remaining > 0) await sleep(Math.min(250, remaining));
 }
 
 export async function navigate(input, route, params = {}, expectedRoute) {
-  const timeoutMs = Number(input.node?.navigation_timeout_ms ?? 15000);
+  const timeoutMs = mobileNavigationTimeoutMs(input);
   let requestedRoute = String(expectedRoute ?? route);
   let requestedParams = requestedRoute === String(route) ? params : undefined;
   const nestedTarget = expectedRoute == null && typeof params?.screen === 'string';
@@ -712,7 +888,7 @@ export async function navigate(input, route, params = {}, expectedRoute) {
 
   while (navigateAttempts < 2 || recoveryPending) {
     if (recoveryPending) {
-      const deadline = recoveryDeadline ?? Date.now() + timeoutMs;
+      const deadline = recoveryDeadline ?? deadlineFromTimeout(input, timeoutMs);
       let currentRoute = null;
       while (Date.now() < deadline) {
         try {
@@ -798,7 +974,7 @@ export async function navigate(input, route, params = {}, expectedRoute) {
       if (!isTargetTransition(error)) throw error;
       lastTransitionError = error;
       transitionCodes.push(error.code);
-      recoveryDeadline = Date.now() + timeoutMs;
+      recoveryDeadline = deadlineFromTimeout(input, timeoutMs);
       recoveryPending = true;
       await waitForNextRouteProbe(recoveryDeadline);
     }
@@ -820,7 +996,8 @@ export async function waitForRoute(
   expectedParams,
 ) {
   const expected = String(expectedRoute);
-  const deadline = Date.now() + timeoutMs;
+  const startedAt = Date.now();
+  const deadline = deadlineFromTimeout(input, timeoutMs);
   // lastRoute is null when bridgeCommand returns null (transient: route not yet
   // settled mid-navigation). Null means "not ready yet" — keep polling.
   let lastRoute = null;
@@ -831,6 +1008,9 @@ export async function waitForRoute(
     try {
       lastRoute = await bridgeCommand(input, ['get-route']);
     } catch (error) {
+      // The action deadline cut the last poll short: report the route wait
+      // (expected and last route) rather than that one poll.
+      if (error?.code === MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE) break;
       if (!isTargetTransition(error)) throw error;
       lastTransitionError = error;
       transitionCodes.push(error.code);
@@ -857,7 +1037,7 @@ export async function waitForRoute(
     ? 'empty/undefined (route transiently unavailable — bridge not yet settled)'
     : JSON.stringify(lastRoute);
   const timeoutError = new Error(
-    `Timed out waiting for Mobile route '${expected}' after ${timeoutMs}ms (${pollCount} polls).\n` +
+    `Timed out waiting for Mobile route '${expected}' after ${Date.now() - startedAt}ms (${pollCount} polls; limit ${deadline - startedAt}ms of ${timeoutMs}ms requested).\n` +
     `  Expected route: ${expected}\n` +
     `  Expected params: ${expectedParams === undefined ? 'any' : JSON.stringify(expectedParams)}\n` +
     `  Last parsed route: ${JSON.stringify(lastRoute)}\n` +

package/library/actions/mobile/wallet/home.mjs

@@ -1,5 +1,10 @@
 // Open wallet home through WalletView, with a verified HomeNav fallback for older navigators.
-import { bridgeCommand, navigate, waitForRoute } from '../platform/bridge.mjs';
+import {
+  bridgeCommand,
+  mobileNavigationTimeoutMs,
+  navigate,
+  waitForRoute,
+} from '../platform/bridge.mjs';
 
 /**
  * Navigate to the wallet home across MetaMask Mobile navigation generations.
@@ -19,7 +24,7 @@ export async function navigateWalletHome(input) {
     const currentRoute = await waitForRoute(
       input,
       'WalletView',
-      Number(input.node?.navigation_timeout_ms ?? 15000),
+      mobileNavigationTimeoutMs(input),
     );
     return {
       navigation: {

package/library/actions/mobile/wallet/select_account.mjs

@@ -5,14 +5,18 @@ import { pathToFileURL } from 'node:url';
 import {
   bridgeCommand,
   MOBILE_BRIDGE_ERROR_CODES,
+  MOBILE_BUDGET_ERROR_CODES,
   runAdapter,
 } from '../platform/bridge.mjs';
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// A switch-account write cut short by the deadline may still have landed, so
+// ACTION_DEADLINE leaves the outcome as unknown as a transport failure does.
 const TRANSIENT_READ_CODES = new Set([
   MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
   MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
   MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
+  MOBILE_BUDGET_ERROR_CODES.ACTION_DEADLINE,
 ]);
 const READ_ATTEMPT_TIMEOUT_MS = 10_000;
 

package/library/actions/shared/app/live-adapter-deadline.mjs

@@ -0,0 +1,8 @@
+// The epoch ms by which a live adapter action must finish. The runner kills a
+// live adapter process liveAdapterProcessTimeoutMs(node) after starting it.
+
+import { liveAdapterProcessTimeoutMs } from '@farmslot/recipe-cli/harness';
+
+export function liveAdapterDeadline(node, reserveMs = 5_000) {
+  return performance.timeOrigin + liveAdapterProcessTimeoutMs(node ?? {}) - reserveMs;
+}

package/library/actions/shared/perps/order-policy.mjs

@@ -123,6 +123,25 @@ export function worstCaseNotionalUsd({ amount, leverage, price, szDecimals, maxS
   return (usd + step * Number(price)) * (1 + Number(maxSlippageBps) / 10_000);
 }
 
+// The lot the controller submits for a market order of `amount` USDC margin (the
+// same rounding as above), in whole size steps, its notional, and the margin one
+// step adds at `price`. Null when the size decimals or price are unknown.
+export function marketOrderLot({ amount, leverage, price, szDecimals }) {
+  const decimals = szDecimals == null || szDecimals === '' ? Number.NaN : Number(szDecimals);
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 8 || !(Number(price) > 0)) return null;
+  const multiplier = 10 ** decimals;
+  const usd = Number(amount) * Number(leverage);
+  let lots = Math.round((usd / Number(price)) * multiplier);
+  if ((lots / multiplier) * Number(price) < usd) lots += 1;
+  if (!Number.isSafeInteger(lots) || lots <= 0) return null;
+  return {
+    sizeDecimals: decimals,
+    lots,
+    notionalBaseUnits: `${Math.ceil((lots / multiplier) * Number(price) * 1_000_000)}`,
+    stepMarginBaseUnits: `${Math.ceil((Number(price) / multiplier / Number(leverage)) * 1_000_000)}`,
+  };
+}
+
 // Mainnet only: refuse before dispatch when the size the controller would submit
 // could fill above the house notional limit. Testnet needs no bound.
 export function requireHouseNotional({ network, symbol, amount, leverage, price, szDecimals, maxSlippageBps }) {

package/library/actions/shared/perps/rate-limit.mjs

@@ -0,0 +1,93 @@
+// Classify a Hyperliquid HTTP 429 (Too Many Requests) as RATE_LIMITED and retry
+// Perps reads a bounded number of times with exponential backoff and jitter.
+// Farm runs share one testnet account and egress IP, so a 429 is load on the
+// venue, not a product result. Placements never retry here: see
+// runGuardedExternalMutation, which retries only once the venue proves nothing
+// was placed.
+
+export const RATE_LIMITED = 'RATE_LIMITED';
+export const RATE_LIMIT_RETRIES = 3;
+const BASE_BACKOFF_MS = 1_000;
+
+const TOO_MANY_REQUESTS = /too many requests|\b(?:http|status(?:\s*code)?)\s*:?\s*429\b/iu;
+
+export function isRateLimited(error) {
+  if (error?.code === RATE_LIMITED) return true;
+  return TOO_MANY_REQUESTS.test(error instanceof Error ? error.message : String(error ?? ''));
+}
+
+// Retry n (1-based) waits between half and all of 1 s, 2 s, 4 s: at most 7 s over
+// the three retries.
+export function rateLimitBackoffMs(retry, random = Math.random) {
+  const ceiling = BASE_BACKOFF_MS * 2 ** (retry - 1);
+  return Math.round(ceiling / 2 + random() * (ceiling / 2));
+}
+
+// The sentence naming the call, its attempts and the backoff it used.
+export function describeRateLimit({ call, attempts, waitedMs }) {
+  return `Hyperliquid answered 429 Too Many Requests to ${call} on ${attempts} attempt${attempts === 1 ? '' : 's'} `
+    + `after ${waitedMs} ms of backoff (exponential from ${BASE_BACKOFF_MS} ms with jitter, at most ${RATE_LIMIT_RETRIES} retries)`;
+}
+
+export function rateLimitedError({ call, attempts, waitedMs, reason = null, next = 'wait a minute and rerun' }) {
+  return Object.assign(
+    new Error(`${RATE_LIMITED}: ${describeRateLimit({ call, attempts, waitedMs })}${reason ? `; ${reason}` : ''}. Next: ${next}.`),
+    { code: RATE_LIMITED, call, attempts, waitedMs },
+  );
+}
+
+export function backoffSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// A retry that has not answered by the deadline fails there; the read itself
+// keeps running, but the action no longer waits for it.
+async function beforeDeadline(promise, deadline, timedOut) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(timedOut()), Math.max(0, deadline - Date.now()));
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Run a read, retrying it after a 429 up to RATE_LIMIT_RETRIES times.
+ * @param call - The request named in the error, e.g. perpsGetPositions.
+ * @param read - The read to run; any other error is rethrown at once.
+ * @param options.deadline - Epoch ms the action must finish by. A retry starts only if its backoff
+ *   and another attempt as long as the last one end before it, and fails RATE_LIMITED at it.
+ * @returns The read's result, or throws RATE_LIMITED once the retries or the deadline are spent.
+ */
+export async function withRateLimitRetry(call, read, { deadline = null, sleep = backoffSleep, random = Math.random } = {}) {
+  let waitedMs = 0;
+  for (let attempt = 1; ; attempt += 1) {
+    const startedAt = Date.now();
+    try {
+      if (attempt === 1 || !Number.isFinite(deadline)) return await read();
+      return await beforeDeadline(read(), deadline, () => rateLimitedError({
+        call, attempts: attempt, waitedMs, reason: 'the last retry did not answer before the action deadline',
+      }));
+    } catch (error) {
+      // A nested read already spent its retries.
+      if (error?.code === RATE_LIMITED || !isRateLimited(error)) throw error;
+      if (attempt > RATE_LIMIT_RETRIES) {
+        throw rateLimitedError({ call, attempts: attempt, waitedMs });
+      }
+      const backoffMs = rateLimitBackoffMs(attempt, random);
+      if (Number.isFinite(deadline) && Date.now() + backoffMs + (Date.now() - startedAt) >= deadline) {
+        throw rateLimitedError({
+          call, attempts: attempt, waitedMs,
+          reason: `the next ${backoffMs} ms backoff and another attempt would pass the action deadline`,
+        });
+      }
+      await sleep(backoffMs);
+      waitedMs += backoffMs;
+    }
+  }
+}

package/library/actions/shared/perps/visible-state.mjs

@@ -191,7 +191,7 @@ function visibleFeatures(items) {
   const long = has(/(?:long-cta-button|direction-long|market-details-long-button)$/u);
   const short = has(/(?:short-cta-button|direction-short|market-details-short-button)$/u);
   return {
-    activity: has(/^(?:transaction-card-|perps-(?:recent-activity|activity))/u),
+    activity: has(/^(?:transaction-card-|perps-(?:recent-activity|activity|market-trades-row-))/u),
     balance: has(/^(?:perps-balance-dropdown|perps-balance-actions-available-value|perps-market-(?:balance-value|available-balance-text))/u),
     chart: has(/^(?:chart_surface|tv_chart_container)$/u) ||
       has(/perps-(?:candlestick-chart|market-detail-chart|market-details-fullscreen-chart|pro-market-chart)/u),
@@ -283,7 +283,8 @@ export function normalizeVisiblePerpsState(raw, options, platform) {
       options.maxItems,
     ),
     activity: compactEntries(
-      selected(unique, (item) => /^(?:transaction-card-|transaction-item(?:-|$)|perps-activity-row-)/u.test(item.testId), options.maxItems),
+      // Mobile previews: Perps home Recent activity and the market's recent trades.
+      selected(unique, (item) => /^(?:transaction-card-|transaction-item(?:-|$)|perps-activity-row-|perps-(?:recent-activity|market-trades)-row-\d+$)/u.test(item.testId), options.maxItems),
       options.maxItems,
     ),
     orderEntry: raw.orderEntry && typeof raw.orderEntry === 'object' ? {

package/library/manifests/extension.action-manifest.json

@@ -3788,7 +3788,7 @@
       ]
     },
     "metamask.perps.read_snapshot": {
-      "description": "Read a bounded, redacted source-dev snapshot of Extension Perps state through the optional product background hook.",
+      "description": "Read a bounded, redacted source-dev snapshot of Extension Perps state through the optional product background hook. The history section is the funds ledger from perpsGetUserHistory (deposits, withdrawals and transfers): it holds no trades or orders, so zero history items does not mean no trading history. Read trade and order rows with metamask.perps.read_visible_state activity.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3830,6 +3830,7 @@
           },
           "history": {
             "type": "object",
+            "description": "Funds-ledger window (deposits, withdrawals and transfers) passed to perpsGetUserHistory; trades and orders are not part of it.",
             "properties": {
               "start_time_ms": {
                 "type": "integer",
@@ -4465,7 +4466,7 @@
           "identity_rounding_tolerance_base_units": {
             "type": "string",
             "default": "10000",
-            "description": "Maximum visible amount/price rounding delta in six-decimal USDC base units; default 10000 and capped at 1000000."
+            "description": "Maximum visible amount/price rounding delta in six-decimal USDC base units; default 10000 and capped at 1000000. A background market order's margin check adds one venue size step at the current price."
           }
         },
         "additionalProperties": false

package/library/manifests/mobile.action-manifest.json

@@ -930,7 +930,7 @@
       ]
     },
     "ui.wait_for": {
-      "description": "Wait for a React Native testID/test_id or text target. expected=visible requires a measured viewport intersection; expected=present only requires the mounted tree.",
+      "description": "Wait for a React Native testID/test_id or text target. expected=visible requires a measured viewport intersection; expected=present only requires the mounted tree. expected=absent also passes when every mounted match is on a screen the navigator hides (an inactive tab, or a non-modal stack screen under a non-modal screen) and a native observation does not show the test ID.",
       "schema": {
         "type": "object",
         "properties": {
@@ -960,7 +960,8 @@
             "type": "boolean"
           },
           "timeout_ms": {
-            "type": "number"
+            "type": "number",
+            "description": "Total wait in milliseconds (default 10000). The hidden-screen check for expected=absent needs about 3 s of it left for its native read."
           }
         },
         "additionalProperties": false
@@ -3544,7 +3545,7 @@
           "trading_state": {
             "type": "string",
             "enum": ["preserve", "clean_selected_testnet_market"],
-            "description": "High-level state policy. The clean policy removes matching positions, ordinary orders, TWAPs, and Chase sessions only on testnet and preserves them on mainnet."
+            "description": "High-level state policy that sets positions, orders and strategies itself: preserve leaves them untouched, and the clean policy removes matching positions, ordinary orders, TWAPs, and Chase sessions only on testnet and preserves them on mainnet. Cannot be combined with an explicit positions, orders or strategies request other than false; omit it to apply such a request."
           },
           "positions": {
             "description": "Requested position state. Omit it or pass false to preserve current positions.",
@@ -3768,7 +3769,19 @@
             "additionalProperties": false
           },
           "timeout_ms": {
-            "type": "number"
+            "type": "number",
+            "minimum": 1,
+            "description": "Overall budget for the whole start state setup: every phase runs inside it. Default 30000 on emulators and simulators, 60000 on a physical Android device (explicit non-emulator adb serial), or MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS. A phase that runs out fails as DOMAIN_SETUP_DEADLINE naming the phase."
+          },
+          "navigation_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Slice of the setup budget for each navigation phase. Default 15000 on emulators and simulators, 30000 on a physical Android device, or MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS."
+          },
+          "cdp_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Limit for each bridge command inside the setup, capped by the phase deadline. Default 15000. A command that hits it fails as CDP_TIMEOUT (CDP_COMMAND_TIMEOUT in the message)."
           },
           "side": {
             "type": "string",
@@ -4104,7 +4117,19 @@
             "additionalProperties": false
           },
           "timeout_ms": {
-            "type": "number"
+            "type": "number",
+            "minimum": 1,
+            "description": "Overall budget for the whole teardown: every phase runs inside it. Default 30000 on emulators and simulators, 60000 on a physical Android device (explicit non-emulator adb serial), or MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS. A phase that runs out fails as DOMAIN_SETUP_DEADLINE naming the phase."
+          },
+          "navigation_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Slice of the setup budget for each navigation phase. Default 15000 on emulators and simulators, 30000 on a physical Android device, or MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS."
+          },
+          "cdp_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Limit for each bridge command inside the setup, capped by the phase deadline. Default 15000. A command that hits it fails as CDP_TIMEOUT (CDP_COMMAND_TIMEOUT in the message)."
           },
           "side": {
             "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.86.1",
+  "version": "0.87.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"

package/site/assets/help-recipes.json

@@ -202,6 +202,7 @@
         "Flake risk: wait on observable state instead of sleeping, keep device and runtime identity explicit, and never overwrite a prior run's artifacts.",
         "Mutation: require an independent state assertion and identity-bound receipt. Bind activity to that operation's accepted ID; an old row or nonzero count is insufficient. Opening and closing orders have different IDs. Schedule authorized cleanup in teardown, verify its result, and report any residue. Testnet cleanup closes what the task opened and never silently undoes another task's live proof on a reserved account or market.",
         "Testnet account state: on a testnet account or market the task owns for its run (the slot's fixture account, or one reserved with exclusive_testnet_market=true), converging is an explicit, ownership-scoped setup choice, not a violation. Use the team library's perps.ensure-market-state or perps.clean-market-testnet, or on Mobile and Core metamask.perps.ensure_positions / metamask.perps.ensure_orders (mode=all for strays), record what was closed in the trace, then prove. A pre-existing position or order on an account the task owns is never a reason to block, skip, or refuse, and a fixture that demands an empty account must converge rather than refuse. Extension ensure_* and teardown_state only assert; converge there through an explicitly funded leaf action. Never broaden cleanup onto an account or market the task does not own; obtain an owned one instead of blocking. On mainnet, orders follow the shared Perps order rule (PERPS_MAINNET_ORDER_REFUSED), Core needs CORE_PERPS_ALLOW_MAINNET_WRITES=1 for any write, Mobile cleanup acts on whatever network the app is on, and Extension refuses mainnet writes other than orders and `close_visible_position` in the fixture-policy lane.",
+        "Rate limits: RATE_LIMITED means Hyperliquid answered 429 Too Many Requests and bounded retries did not get through; it says nothing about the product. Wait a minute and rerun a read. A placement left outcome-unknown is never rerun before the market's positions, orders and fills are checked.",
         {
           "text": "An accepted order can fill before the UI updates. Preserve its receipt even when the expected resting-order assertion fails; one empty read does not prove cleanup. Check the read API's cache and freshness options before adding polling. Reconcile returned margin against the pre-placement balance. A successful close does not turn the original failed proof into a pass.",
           "adapters": [