@deeeed/metamask-harness 0.86.2 → 0.87.0

package/library/actions/extension/perps/mutation-receipt.mjs

@@ -19,6 +19,14 @@ import path from 'node:path';
 
 import { isFixtureAccount } from '../../shared/wallet/fixture-accounts.mjs';
 import { MAINNET_HOUSE_LIMITS, orderNetwork, requirePerpsOrderAllowed } from '../../shared/perps/order-policy.mjs';
+import {
+  RATE_LIMIT_RETRIES,
+  RATE_LIMITED,
+  backoffSleep,
+  describeRateLimit,
+  isRateLimited,
+  rateLimitBackoffMs,
+} from '../../shared/perps/rate-limit.mjs';
 import { readWalletStateExpression } from '../wallet/state.mjs';
 import { readPerpsRuntimeStateExpression } from './state.mjs';
 
@@ -43,6 +51,14 @@ function recoveryError(receipt, detail) {
   );
 }
 
+// The outcome stays unknown, so the Next is still the receipt's, never a plain rerun.
+function rateLimitedRecoveryError(receipt, rateLimit, reason) {
+  return Object.assign(
+    new Error(`${RATE_LIMITED}: ${recoveryError(receipt, `${describeRateLimit(rateLimit)}; ${reason}`).message}`),
+    { code: RATE_LIMITED },
+  );
+}
+
 class ExternalMutationNotDispatchedError extends Error {}
 
 export function externalMutationNotDispatched(message) {
@@ -848,9 +864,9 @@ async function recordSubmissionAcceptance(input, receipt, acceptance) {
       || !validFilledOrder(filledSize, averagePrice)) {
       throw recoveryError(receipt, 'background market acceptance has invalid filled order identity');
     }
-    return writeSubmissionAcceptance(input, receipt, {
+    return amendOutcomeUnknownReceipt(input, receipt, { acceptance: {
       source: BACKGROUND_ACCEPTANCE_SOURCE, venueOrderId, status, size, filledSize, averagePrice,
-    });
+    } }, 'submission acceptance');
   }
   const closing = receipt.record.identity.operation === 'perps-close-position';
   const market = closing || receipt.record.identity.operation === 'perps-market-order';
@@ -871,19 +887,25 @@ async function recordSubmissionAcceptance(input, receipt, acceptance) {
   if (market && status === 'filled' && (!validFilledOrder(filledSize, averagePrice) || Number(filledSize) > Number(size))) {
     throw recoveryError(receipt, 'market acceptance has invalid filled size or price');
   }
-  return writeSubmissionAcceptance(input, receipt, {
+  return amendOutcomeUnknownReceipt(input, receipt, { acceptance: {
     venueOrderId, status, requestId, serviceWorkerTargetId, asset, size, limitPriceBaseUnits,
     ...(market && status === 'filled' ? { filledSize, averagePrice } : {}),
-  });
+  } }, 'submission acceptance');
 }
 
-async function writeSubmissionAcceptance(input, receipt, acceptance) {
+// Adds fields to a still outcome-unknown receipt: the accepted order, or a 429
+// and the venue read that followed it.
+async function amendOutcomeUnknownReceipt(input, receipt, fields, label) {
   const destination = await receiptDestination(input);
   const current = await readPublished(destination);
   if (!current || current.sha256 !== receipt.sha256 || current.record?.state !== 'outcome-unknown') {
-    throw recoveryError(receipt, 'the receipt changed before submission acceptance was recorded');
+    throw recoveryError(receipt, `the receipt changed before ${label} was recorded`);
+  }
+  const record = { ...current.record, ...fields };
+  const bytes = canonical(record);
+  if (bytes.length > 12_288 || /secret|password|srp|mnemonic|private.?key/iu.test(bytes)) {
+    throw recoveryError(receipt, `the ${label} receipt is unsafe`);
   }
-  const record = { ...current.record, acceptance };
   const staged = await stagedRecord(destination.directory, record);
   try {
     await rename(staged.stagedPath, destination.absolute);
@@ -893,12 +915,21 @@ async function writeSubmissionAcceptance(input, receipt, acceptance) {
   }
   const published = await readPublished(destination);
   if (!published || canonical(published.record) !== canonical(record)) {
-    throw recoveryError(receipt, 'submission acceptance could not be reread');
+    throw recoveryError(receipt, `${label} could not be reread`);
   }
   return { ...published, resumed: receipt.resumed };
 }
 
-export async function runGuardedExternalMutation({ input, identity, dispatch, observe, publicationFacts, receiptIo }) {
+/**
+ * Publish the receipt, dispatch once, observe the postcondition and complete the receipt.
+ * @param rateLimit - Optional retry of a dispatch the venue refused with a 429:
+ *   { call, deadline, verifyBudgetMs, verifyNotPlaced({ sinceMs }) -> { proven, reason?, facts? }, sleep?, random? }.
+ *   A retry runs only when the dispatch itself threw the 429 (nothing accepted), the backoff and
+ *   the venue read fit before the deadline, and verifyNotPlaced then proves from the venue that
+ *   nothing was placed since the first dispatch. Every 429 is recorded in the receipt with its
+ *   verification or the reason it was not retried.
+ */
+export async function runGuardedExternalMutation({ input, identity, dispatch, observe, publicationFacts, receiptIo, rateLimit = null }) {
   let receipt = await beginExternalMutation(input, identity, receiptIo, publicationFacts);
   if (receipt.record?.state === 'observed-policy-violation') {
     throw new Error('External mutation receipt records an observed policy violation and is cleanup-only.');
@@ -907,27 +938,93 @@ export async function runGuardedExternalMutation({ input, identity, dispatch, ob
     throw new Error('External mutation receipt state is unsafe.');
   }
   if (!receipt.resumed) {
-    try {
-      const acceptance = await dispatch();
-      if (acceptance?.venueOrderId) receipt = await recordSubmissionAcceptance(input, receipt, acceptance);
-    } catch (error) {
-      if (error instanceof ExternalMutationNotDispatchedError) {
-        await markExternalMutationNotDispatched(input, receipt, error, receiptIo);
-        throw Object.assign(
-          new Error(
-            `External mutation was safely not dispatched (${error.message}). ` +
-            'Next: correct the observed state and create a fresh consent request, claim, and artifact root.',
-          ),
-          { knownNotDispatched: true },
-        );
+    const call = rateLimit?.call ?? `${identity.action} dispatch`;
+    const sinceMs = Date.now();
+    let waitedMs = 0;
+    for (let attempt = 1; ; attempt += 1) {
+      let returned = false;
+      try {
+        // A retry must reach the venue before the deadline, its pre-dispatch checks included.
+        const acceptance = await dispatch(attempt > 1 ? { deadline: rateLimit.deadline } : {});
+        returned = true;
+        if (acceptance?.venueOrderId) receipt = await recordSubmissionAcceptance(input, receipt, acceptance);
+        break;
+      } catch (error) {
+        if (error instanceof ExternalMutationNotDispatchedError) {
+          await markExternalMutationNotDispatched(input, receipt, error, receiptIo);
+          // A retry that was not sent still ends the action on the 429 that called for it.
+          const retried = attempt > 1;
+          throw Object.assign(
+            new Error(
+              `${retried ? `${RATE_LIMITED}: ` : ''}External mutation was safely not dispatched (` +
+              `${retried ? `${describeRateLimit({ call, attempts: attempt - 1, waitedMs })}; the retry was not sent: ` : ''}` +
+              `${error.message}). ` +
+              'Next: correct the observed state and create a fresh consent request, claim, and artifact root.',
+            ),
+            { knownNotDispatched: true, ...(retried ? { code: RATE_LIMITED } : {}) },
+          );
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        if (returned || !isRateLimited(error)) {
+          throw recoveryError(receipt, `pointer dispatch may have occurred (${message})`);
+        }
+        const deadline = rateLimit?.deadline;
+        const passesDeadline = (ms) => Number.isFinite(deadline) && Date.now() + ms >= deadline;
+        const backoffMs = attempt > RATE_LIMIT_RETRIES ? 0 : rateLimitBackoffMs(attempt, rateLimit?.random);
+        let refusal = !rateLimit?.verifyNotPlaced ? 'this mutation has no venue read that can prove nothing was placed'
+          : receipt.record.acceptance ? 'the receipt already records an accepted order'
+            : attempt > RATE_LIMIT_RETRIES ? 'its retries are spent'
+              : passesDeadline(backoffMs + (rateLimit.verifyBudgetMs ?? 0))
+                ? `the next ${backoffMs} ms backoff and the venue read would pass the action deadline` : null;
+        let verification = null;
+        if (!refusal) {
+          await (rateLimit.sleep ?? backoffSleep)(backoffMs);
+          waitedMs += backoffMs;
+          try {
+            verification = await rateLimit.verifyNotPlaced({ sinceMs });
+          } catch (verifyError) {
+            verification = {
+              proven: false,
+              reason: `the venue read failed (${verifyError instanceof Error ? verifyError.message : String(verifyError)})`,
+            };
+          }
+          if (verification?.proven !== true) {
+            refusal = verification?.reason ?? 'the venue read did not prove that nothing was placed';
+          } else if (passesDeadline(0)) {
+            refusal = 'the venue read ended past the action deadline';
+          }
+        }
+        receipt = await amendOutcomeUnknownReceipt(input, receipt, {
+          rateLimitedDispatches: [...(receipt.record.rateLimitedDispatches ?? []), {
+            attempt,
+            error: message.slice(0, 200),
+            ...(verification ? {
+              backoffMs,
+              verification: {
+                proven: verification.proven === true,
+                ...(verification.facts ? { facts: verification.facts } : {}),
+              },
+            } : {}),
+            ...(refusal ? { refusal: String(refusal).slice(0, 500) } : {}),
+          }],
+        }, 'the rate-limited dispatch');
+        if (refusal) {
+          throw rateLimitedRecoveryError(receipt, { call, attempts: attempt, waitedMs }, receipt.record.rateLimitedDispatches.at(-1).refusal);
+        }
       }
-      throw recoveryError(receipt, `pointer dispatch may have occurred (${error instanceof Error ? error.message : String(error)})`);
     }
   }
   let observation;
   try {
     observation = await observe({ resumed: receipt.resumed, receipt: receipt.record });
   } catch (error) {
+    if (isRateLimited(error)) {
+      throw rateLimitedRecoveryError(receipt, {
+        call: error.call ?? 'the postcondition read',
+        attempts: error.attempts ?? 1,
+        waitedMs: error.waitedMs ?? 0,
+      }, 'the postcondition read could not run, so the dispatched order is not proven');
+    }
     throw recoveryError(receipt, error instanceof Error ? error.message : String(error));
   }
   if (!observation || observation.success !== true) {

package/library/actions/extension/perps/perps.mjs

@@ -31,6 +31,8 @@ import {
   marketOrderLot,
   requireHouseNotional,
 } from '../../shared/perps/order-policy.mjs';
+import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 import {
   orderIdentityMatches,
   parseOrderCard,
@@ -345,23 +347,36 @@ async function closeOrderThroughBackground(input, page, timeoutMs) {
   };
 }
 
-async function readAcceptedFilledOrder(input, page, placement, requireTerminal = false) {
-  const accepted = placement.record?.acceptance;
-  if (!accepted?.venueOrderId) return null;
+function hyperliquidOrigin(network) {
+  return network === 'testnet' ? 'https://api.hyperliquid-testnet.xyz' : 'https://api.hyperliquid.xyz';
+}
+
+function postHyperliquidInfo(network, body, signal = AbortSignal.timeout(10_000)) {
+  return fetch(`${hyperliquidOrigin(network)}/info`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body), signal,
+  });
+}
+
+// The Hyperliquid network and user a receipt's order went to, read from the live
+// app and bound to the receipt's selected-account hash.
+async function receiptVenueUser(input, page, identity, purpose) {
   const { provider, network } = await requirePerpsTradingContext(input, page);
-  if (provider !== 'hyperliquid') throw new Error('Accepted-order status requires the original Hyperliquid provider.\nNext: mm-harness last --json');
+  if (provider !== 'hyperliquid') throw new Error(`${purpose} requires the original Hyperliquid provider.\nNext: mm-harness last --json`);
   const wallet = await page.evaluate(readWalletStateExpression());
   const user = String(wallet.selectedAccount?.address ?? '').toLowerCase();
   if (!/^0x[a-f0-9]{40}$/u.test(user)
-    || createHash('sha256').update(user).digest('hex') !== placement.record.identity.selectedIdentitySha256) {
-    throw new Error('Accepted-order status wallet differs from the placement receipt.\nNext: mm-harness last --json');
+    || createHash('sha256').update(user).digest('hex') !== identity.selectedIdentitySha256) {
+    throw new Error(`${purpose} wallet differs from the placement receipt.\nNext: mm-harness last --json`);
   }
-  const origin = network === 'testnet' ? 'https://api.hyperliquid-testnet.xyz' : 'https://api.hyperliquid.xyz';
-  const response = await fetch(`${origin}/info`, {
-    method: 'POST', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ type: 'orderStatus', user, oid: Number(accepted.venueOrderId) }),
-    signal: AbortSignal.timeout(10_000),
-  });
+  return { network, user };
+}
+
+async function readAcceptedFilledOrder(input, page, placement, requireTerminal = false) {
+  const accepted = placement.record?.acceptance;
+  if (!accepted?.venueOrderId) return null;
+  const { network, user } = await receiptVenueUser(input, page, placement.record.identity, 'Accepted-order status');
+  const response = await postHyperliquidInfo(network, { type: 'orderStatus', user, oid: Number(accepted.venueOrderId) });
   if (!response.ok) throw new Error('Accepted-order status request failed.\nNext: mm-harness last --json');
   const result = await response.json();
   if (result.status === 'unknownOid') throw new Error('Accepted venue order status is unavailable.\nNext: mm-harness last --json');
@@ -671,7 +686,7 @@ async function readCurrentMarketPrice(page, symbol, explicitPrice) {
     if (Number.isFinite(parsed) && parsed > 0) return parsed;
     throw new Error(`Invalid explicit current price for ${symbol}: ${String(explicitPrice)}`);
   }
-  const price = await page.evaluate(String.raw`(async () => {
+  const price = await withRateLimitRetry('perpsGetMarketDataWithPrices', () => page.evaluate(String.raw`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
     const symbol = ${JSON.stringify(symbol)};
@@ -709,7 +724,7 @@ async function readCurrentMarketPrice(page, symbol, explicitPrice) {
     const line = body.split('\n').find((text) => /\$[0-9][0-9,]*(?:\.[0-9]+)?/.test(text));
     const fromBody = parsePrice(line);
     return fromBody ? { price: fromBody, source: 'document-body-price-line' } : null;
-  })()`);
+  })()`), { deadline: page.actionDeadline });
   const numericPrice = Number(price?.price ?? price);
   if (!Number.isFinite(numericPrice) || numericPrice <= 0) throw new Error(`Unable to determine current Perps price for ${symbol}.`);
   return numericPrice;
@@ -915,7 +930,7 @@ async function dispatchBackgroundPlace(page, {
 }
 
 async function readOpenOrdersState(page) {
-  const state = await page.evaluate(`(async () => {
+  const state = await withRateLimitRetry('perpsGetOpenOrders', () => page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
     const cached = manager?.orders?.cache;
@@ -933,13 +948,13 @@ async function readOpenOrdersState(page) {
       connected: Boolean(manager?.orders?.isConnected),
       orders: Array.isArray(cached) ? cached : [],
     };
-  })()`);
+  })()`), { deadline: page.actionDeadline });
   if (!state.available) throw new Error('Perps orders are unavailable from both background and stream manager cache.');
   return state;
 }
 
 async function readAccountState(page) {
-  const state = await page.evaluate(`(async () => {
+  const state = await withRateLimitRetry('perpsGetAccountState', () => page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
     const cached = manager?.account?.cache;
@@ -957,7 +972,7 @@ async function readAccountState(page) {
       connected: Boolean(manager?.account?.isConnected),
       account: cached && typeof cached === 'object' ? cached : null,
     };
-  })()`);
+  })()`), { deadline: page.actionDeadline });
   if (!state.available) throw new Error('Perps account state is unavailable from both background and stream manager cache.');
   return state.account;
 }
@@ -1242,6 +1257,52 @@ async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs
   throw new Error(`matching ${expected.orderType} ${identity} identity was not stably visible before timeout; last observed: ${JSON.stringify(lastObserved)}`);
 }
 
+// Fills and open orders up to this long before the first dispatch count as this
+// order's, so a local clock behind the venue's cannot hide one.
+const VENUE_CLOCK_SKEW_MS = 30_000;
+// All three venue reads together; a retry starts only if they fit before its deadline.
+const VENUE_VERIFY_TIMEOUT_MS = 5_000;
+
+// After a 429 on a background placement: Hyperliquid's own account state, not the
+// extension's cache, shows no open order and no fill in the market since the first
+// dispatch, and for a market order no position on its side (the pre-order baseline
+// had none). Open orders are read before fills, so an order of ours that fills
+// between the two reads still shows in one of them. Anything else, or a failed
+// read, leaves the outcome unproven.
+async function verifyNothingPlacedOnVenue(input, page, identity, sinceMs) {
+  const coin = identity.market;
+  if (coin.includes(':')) {
+    return { proven: false, reason: `the venue read covers only the main Hyperliquid dex, not ${coin}` };
+  }
+  const { network, user } = await receiptVenueUser(input, page, identity, 'Rate-limit verification');
+  const startTime = sinceMs - VENUE_CLOCK_SKEW_MS;
+  const signal = AbortSignal.timeout(VENUE_VERIFY_TIMEOUT_MS);
+  const read = async (body) => {
+    const response = await postHyperliquidInfo(network, body, signal);
+    if (!response.ok) throw new Error(`Hyperliquid ${body.type} answered HTTP ${response.status}`);
+    return response.json();
+  };
+  const orders = await read({ type: 'openOrders', user });
+  const fills = await read({ type: 'userFillsByTime', user, startTime });
+  const account = await read({ type: 'clearinghouseState', user });
+  if (!Array.isArray(fills) || !Array.isArray(orders) || !Array.isArray(account?.assetPositions)) {
+    return { proven: false, reason: 'the Hyperliquid account reads returned an unexpected shape' };
+  }
+  const size = Number(account.assetPositions.find((entry) => entry?.position?.coin === coin)?.position?.szi ?? 0);
+  if (!Number.isFinite(size)) return { proven: false, reason: `the Hyperliquid ${coin} position size is unreadable` };
+  const facts = {
+    source: 'hyperliquid-info',
+    startTime,
+    openOrders: orders.filter((order) => order?.coin === coin && !(Number(order?.timestamp) < startTime)).length,
+    fills: fills.filter((fill) => fill?.coin === coin && !(Number(fill?.time) < startTime)).length,
+    sameSidePosition: identity.orderType === 'market' && (identity.side === 'long' ? size > 0 : size < 0),
+  };
+  if (facts.openOrders > 0 || facts.fills > 0 || facts.sameSidePosition) {
+    return { proven: false, reason: `Hyperliquid shows ${coin} activity since the first dispatch`, facts };
+  }
+  return { proven: true, facts };
+}
+
 async function placeOrderThroughBackground(input, page, {
   amount,
   bound = null,
@@ -1296,6 +1357,13 @@ async function placeOrderThroughBackground(input, page, {
   const mutation = await runGuardedExternalMutation({
     input,
     identity,
+    rateLimit: {
+      call: 'perpsPlaceOrder',
+      // A retry leaves the postcondition its timeout_ms and 5 s before the runner's process limit.
+      deadline: liveAdapterDeadline(input.node, Number(input.node?.timeout_ms ?? 30_000) + 5_000),
+      verifyBudgetMs: VENUE_VERIFY_TIMEOUT_MS,
+      verifyNotPlaced: ({ sinceMs }) => verifyNothingPlacedOnVenue(input, page, identity, sinceMs),
+    },
     // The pre-order balance lets a receipt-bound close reconcile its final balance.
     publicationFacts: {
       balanceBeforeBaseUnits: fundingBalance.observedBaseUnits,
@@ -1303,16 +1371,20 @@ async function placeOrderThroughBackground(input, page, {
       fundingBalance,
       ...(expected.marketLot ? { marketLot: expected.marketLot } : {}),
     },
-    dispatch: async () => {
+    dispatch: async ({ deadline = null } = {}) => {
       try {
+        const timeoutMs = Number(input.node?.timeout_ms ?? 30_000);
         await requireCurrentVisibleFundingBalance(
           input,
           page,
-          Number(input.node?.timeout_ms ?? 30_000),
+          deadline == null ? timeoutMs : Math.max(0, Math.min(timeoutMs, deadline - Date.now())),
           fundingBalance.observedBaseUnits,
         );
         await requirePerpsTradingContext(input, page);
         assertTrustedExternalMutationTarget(input, page, identity);
+        if (deadline != null && Date.now() >= deadline) {
+          throw new Error('it reached the action deadline before dispatch');
+        }
       } catch (error) {
         throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
       }
@@ -1567,12 +1639,8 @@ export async function observeHyperliquidSubmission(page, expected) {
   if (expected.provider !== 'hyperliquid' || !['market', 'limit'].includes(expected.orderType)) {
     throw new Error('Exact visible submission observation requires a Hyperliquid market or limit order.');
   }
-  const origin = expected.network === 'testnet'
-    ? 'https://api.hyperliquid-testnet.xyz' : 'https://api.hyperliquid.xyz';
-  const metadataResponse = await fetch(`${origin}/info`, {
-    method: 'POST', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ type: 'meta' }), signal: AbortSignal.timeout(10_000),
-  });
+  const origin = hyperliquidOrigin(expected.network);
+  const metadataResponse = await postHyperliquidInfo(expected.network, { type: 'meta' });
   if (!metadataResponse.ok) throw new Error('Hyperliquid market metadata is unavailable before submission.');
   const metadata = await metadataResponse.json();
   const asset = metadata.universe?.findIndex((market) => market.name === expected.market);
@@ -2178,7 +2246,7 @@ export async function placeOrder(input) {
 // read in one evaluation with the context guard before, between and after the
 // reads, so a switch to another account's book and back can't pass as flat.
 async function readBoundBook(page, bound) {
-  const book = await page.evaluate(`(async () => {
+  const book = await withRateLimitRetry('perpsGetPositions/perpsGetOpenOrders', () => page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     if (typeof request !== 'function') return { unavailable: true };
     const guard = async () => { ${boundContextGuard(bound)} return null; };
@@ -2188,7 +2256,7 @@ async function readBoundBook(page, bound) {
     const orders = await request('perpsGetOpenOrders', []);
     if (await guard()) return { changed: true };
     return { positions, orders };
-  })()`);
+  })()`), { deadline: page.actionDeadline });
   if (book?.changed) {
     throw Object.assign(
       new Error('Perps order not dispatched: the selected account or network changed while the market was checked flat.'),
@@ -2202,9 +2270,9 @@ async function readBoundBook(page, bound) {
 }
 
 async function readSizeDecimals(page, symbol) {
-  const markets = await page.evaluate(
+  const markets = await withRateLimitRetry('perpsGetMarkets', () => page.evaluate(
     `globalThis.stateHooks.submitRequestToBackground('perpsGetMarkets', [{ symbols: [${JSON.stringify(symbol)}] }])`,
-  );
+  ), { deadline: page.actionDeadline });
   const market = (Array.isArray(markets) ? markets : []).find((item) => normalizeMarketSymbol(item?.name ?? '') === symbol);
   return market?.szDecimals ?? null;
 }

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

@@ -3,6 +3,7 @@
 import { pathToFileURL } from 'node:url';
 
 import { normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 const ALL_SECTIONS = ['account', 'markets', 'positions', 'orders', 'history', 'watchlist'];
 const DEFAULT_HISTORY_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
@@ -533,8 +534,11 @@ export async function readSnapshot(input, testOptions = {}) {
     const pause = testOptions.pause ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const samples = [];
     for (let index = 0; index < options.sampling.count; index += 1) {
-      const raw = await page.evaluate(snapshotRequestExpression(options));
-      samples.push(normalizeSnapshotResult(raw, options));
+      // A section a 429 left unavailable fails normalization; the sample reruns.
+      samples.push(await withRateLimitRetry('Perps snapshot', async () => normalizeSnapshotResult(
+        await page.evaluate(snapshotRequestExpression(options)),
+        options,
+      ), { sleep: pause, deadline: page.actionDeadline }));
       if (index + 1 < options.sampling.count) await pause(options.sampling.intervalMs);
     }
     const sections = samples.at(-1);

package/library/actions/extension/platform/cdp.mjs

@@ -22,6 +22,8 @@ import path from 'node:path';
 
 import { captureActiveRecipeRecordingSnapshot, recipeHarnessPath } from '@farmslot/recipe-cli/harness';
 import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, extensionIdPath, walletFixturePath } from '../../harness-exports.mjs';
+import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 // Resolve the Farmslot harness through normal package dependencies by default.
 // Local Farmslot source is only a dev override handled by the harness paths module.
@@ -843,6 +845,8 @@ export async function withExtensionPage(input, callback) {
     const origin = `chrome-extension://${extensionId}`;
     const runtimeIdentity = extensionRuntimeIdentity({ port, target, browserVersion });
     const page = new ExtensionPage(session, origin, target, port, runtimeIdentity);
+    // Rate-limit retries on this page's reads stop before the runner's process limit.
+    page.actionDeadline = liveAdapterDeadline(input.node);
     const recoverVisibleWallet = input.action === 'metamask.wallet.import' && input.node?.method === 'ui';
     if (recoverVisibleWallet) {
       try {
@@ -1030,7 +1034,7 @@ export class ExtensionPage extends CdpWebPage {
   }
 
   async readPositions() {
-    return this.evaluate(`(async () => {
+    return withRateLimitRetry('perpsGetPositions', () => this.evaluate(`(async () => {
       const request = globalThis.stateHooks?.submitRequestToBackground;
       const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
       const cached = manager?.positions?.cache;
@@ -1050,7 +1054,7 @@ export class ExtensionPage extends CdpWebPage {
         connected: Boolean(manager?.positions?.isConnected),
         positions: Array.isArray(cached) ? cached : [],
       };
-    })()`);
+    })()`), { deadline: this.actionDeadline });
   }
 
   async screenshot(contextOrInput, relPath, metadata = {}) {

package/library/actions/extension/ui/navigate.mjs

@@ -280,6 +280,8 @@ export async function openPerpsHome(page, timeoutMs) {
     await pauseForUi(page);
   }
 
+  // The sample is capped at 30 and the header and tabs come first in the DOM, so loading
+  // markers are listed first; otherwise a Perps view still loading reads as a wrong route.
   const state = await page.evaluate(`({
     href: location.href,
     title: document.title,
@@ -291,8 +293,14 @@ export async function openPerpsHome(page, timeoutMs) {
       })
       .map((element) => element.getAttribute('data-testid'))
       .filter(Boolean)
+      .sort((a, b) => Number(b.endsWith('-loading')) - Number(a.endsWith('-loading')))
       .slice(0, 30),
   })`);
+  if (await hasVisibleSelector(page, perpsLoading)) {
+    throw new Error(
+      `extension ui.navigate page=perps: Perps home stayed on its loading view (perps-view-loading visible) within the ${timeoutMs}ms budget; observed ${JSON.stringify(state)}.\nNext: check the Perps stream/provider, or raise timeout_ms; a raw hash route does not wait for Perps readiness.`,
+    );
+  }
   throw new Error(
     `extension ui.navigate page=perps could not resolve the Perps home through visible UI; observed ${JSON.stringify(state)}. Capture the current UI with mm-harness call ui.screenshot, then use a verified visible control or raw hash/path.`,
   );