@deeeed/metamask-harness 0.86.2 → 0.88.0

package/docs/RECIPES.md

@@ -261,12 +261,34 @@ Perps orders follow one rule on Mobile, Extension and Core
 (`library/actions/shared/perps/order-policy.mjs`), checked before dispatch:
 
 - Testnet: allowed with no funding proof.
-- Mainnet: only from a synced fixture account (`wallet-fixture.json`), as a 1x
-  isolated market order with `close_immediately: true`, and the node must
-  declare `network: mainnet`. The $15 limit bounds the size the controller would
-  submit: (amount + one size step × price) × (1 + max slippage). Anything else
-  is refused with `PERPS_MAINNET_ORDER_REFUSED`, naming each broken limit, and
-  no order is sent.
+- Mainnet: only from a synced fixture account (`wallet-fixture.json`), 1x
+  isolated, and the node must declare `network: mainnet`. Either a market order
+  with `close_immediately: true`, where the $15 limit bounds the size the
+  controller would submit: (amount + one size step × price) × (1 + max
+  slippage); or, on Mobile and Extension `place_order`, a `dev1` Hyperliquid
+  limit order away from the live market price, sent post-only and bounded at its limit
+  price: amount + one size step × limit price. Mainnet orders take no
+  `current_price`. Anything else is refused with `PERPS_MAINNET_ORDER_REFUSED`,
+  naming each broken limit, and no order is sent: more than 1x or $15, a limit
+  that would fill now, another account, Core, and `ensure_orders` or
+  `ensure_positions` opening state.
+- A mainnet limit order lasts one run. It is tracked before dispatch in
+  `temp/recipe/runtime/perps-mainnet-orders.json`, and the run cancels whatever
+  is still open when it ends (success, failure, or abort by signal; after a
+  kill, the next run on the checkout). The order counts as gone only when the
+  Hyperliquid API, read for the placing address, no longer lists it. Each
+  order's ID, cancel result and both reads (app and venue) land in
+  `<artifacts>/perps-mainnet-orders.json`. An order
+  that cannot be proven cancelled, or that filled (the market's position moved),
+  fails the run with `PERPS_MAINNET_ORDER_LEFT_OPEN`; a fill is reported, never
+  closed for you. On mainnet, `close_orders` cancels only orders the run placed,
+  and leaving mainnet while the run holds one is refused
+  (`PERPS_MAINNET_ORDER_OPEN`).
+- Switching to mainnet: Mobile `metamask.perps.start_state network=mainnet`;
+  Extension `metamask.perps.set_network network=mainnet`, which the run switches
+  back to testnet at its end (the fixture loads testnet). Mobile stays on
+  mainnet after the run: switch back with `start_state network=testnet` once
+  the run's orders are settled.
 - `close_immediately: true` needs a market order from a flat market: no
   position and no resting order in it. Positions are netted per market, so the
   close takes the market's whole position; don't share a fixture account's
@@ -279,6 +301,18 @@ Perps orders follow one rule on Mobile, Extension and Core
   sent or closed.
 - Core still needs `CORE_PERPS_ALLOW_MAINNET_WRITES=1` for any mainnet write.
 
+A Hyperliquid `429 Too Many Requests` fails as `RATE_LIMITED`, naming the call,
+the attempts and the backoff (`library/actions/shared/perps/rate-limit.mjs`).
+Reads retry up to 3 times with exponential backoff and jitter inside the action
+deadline; then wait a minute and rerun. Extension background placement retries
+only when the dispatch itself got the 429 and Hyperliquid's info API then shows
+no open order, no fill and (market orders) no position on the order's side in
+that market since the first dispatch. The receipt records every dispatch 429
+under `rateLimitedDispatches`, with that check or the reason it did not retry;
+without a retry it stays `outcome-unknown`: inspect the market before any rerun.
+A 429 after dispatch is never redispatched, and Mobile placements are not
+retried.
+
 On the Extension, a run without funding files gets that rule through the
 fixture-policy lane: the runner binds the run and a run-owned execution ledger
 (`<artifacts>/mutation-ledger`), and each mutation completes the context from
@@ -330,9 +364,11 @@ rather than refuse. Extension `ensure_*` and `teardown_state` only assert, so
 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 Perps order rule above, 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.
+`CORE_PERPS_ALLOW_MAINNET_WRITES=1` for any write, Mobile `close_positions`
+acts on whatever network the app is on, `close_orders` there cancels only the
+run's own orders, and Extension refuses mainnet writes other than orders,
+`close_visible_position` and cancelling the run's own orders in the
+fixture-policy lane.
 
 ### Mobile advanced-order setup
 
@@ -417,6 +453,57 @@ For visual PR proof, prefer a short simulator recording or GIF over still
 screenshots when the claim is a UI flow (timing / transitions). Use screenshots
 as supporting stills.
 
+`--record-video=full-run` on a physical Android device records on the device
+with `adb shell screenrecord`, so no other host screen-capture client can stop
+it. screenrecord ends each file at 180 s; the harness starts the next one at
+once and joins them with ffmpeg (required, or set `FFMPEG_PATH`). Each restart
+leaves a gap of about half a second, which the video holds on the last frame
+so video time keeps to wall-clock time. `videos/recipe-run.mp4.capture.json`
+lists the files and their offsets. Screens the app marks secure (FLAG_SECURE)
+record black. An emulator (`emulator-*`) still records its scrcpy window
+through capture-helper, falling back to one screenrecord file when the mirror
+is unavailable. Set `METAMASK_RECIPE_MOBILE_ANDROID_RECORDER` to
+`screenrecord` or `mirror` to force either.
+
+A recording that fails fails the run: the `record.video` trace entry starts
+with `RECORDING_FAILED` or `RECORDER_INTERRUPTED`, names the cause, and says the
+run has no video. When capture stopped mid-run but a finalized partial file was
+kept (capture-helper 0.3.1's `stream_interrupted`, or the screenrecord files
+finished before a failure), the video is published, its manifest entry's
+`interruption` gives the frames, the video time up to the last captured frame
+(`mediaTimeMs`) and the cause, and the run fails as `CAPTURE_INTERRUPTED`, a
+capture (environment) failure, not a product one. `mm-harness doctor` shows the
+recorder for the selected device and is not ready while it cannot record.
+
+### Mobile setup and command budgets
+
+`metamask.perps.start_state` and `teardown_state` have three budgets:
+
+| Budget | Node field | Emulator / simulator | Physical Android | Env override |
+|---|---|---|---|---|
+| Whole setup | `timeout_ms` | 30 s | 60 s | `MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS` |
+| Each navigation phase | `navigation_timeout_ms` | 15 s | 30 s | `MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS` |
+| Each bridge command | `cdp_timeout_ms` | 15 s | 15 s | none |
+
+A device counts as physical when the run has an explicit adb serial (`--device <serial>`
+or `ADB_SERIAL`) that is not `emulator-*`. Node fields win over the env overrides.
+Each phase (unlock, account, navigation, provider, network, cleanup) runs on the
+rest of the setup budget, or on its slice for navigation, and each bridge command
+inside it is capped by that phase deadline. `navigate` and Perps market/home
+navigation use the same navigation default outside setups.
+
+Errors say which budget ran out:
+
+- `DOMAIN_SETUP_DEADLINE`: a setup phase ran out. The message names the action and
+  phase, the time it ran against its limit, and the setup's elapsed time and
+  limit. Raise `timeout_ms` or `navigation_timeout_ms`.
+- `ACTION_DEADLINE`: the calling action's deadline refused or stopped a bridge
+  command. Route and mode waits treat it as "no answer yet" and end with their
+  own timeout message.
+- `CDP_TIMEOUT` with `CDP_COMMAND_TIMEOUT` in the message: one bridge command hit
+  its own limit while the action still had time. That points at the bridge or app,
+  not the budget.
+
 ### Perps loading lifecycle validation
 
 The Mobile loading recipe shares one graph across Android and iOS. It requires

package/docs/RELEASE-QA-CAPABILITY-MAP.md

@@ -63,7 +63,11 @@ outside the declared root, incomplete run directories, and any non-empty
 
 Supported verdicts are `PASS`, `FAIL`, `BLOCKED_FUNDS`, `BLOCKED_COST`, and
 `BLOCKED_ENVIRONMENT`. Product failures must remain failures; infrastructure,
-funding, and cost limits must not be reported as passes.
+funding, and cost limits must not be reported as passes. If every run cited by a
+case failed only on `CAPTURE_INTERRUPTED`, the gate requires `BLOCKED_ENVIRONMENT`
+with "evidence incomplete (capture interrupted)" in its summary and the partial
+video in its run directory. Retain interrupted attempts alongside the retry's
+evidence. A passing retry can be `PASS`; a product-failing retry remains `FAIL`.
 
 ## Capability matrix
 

package/docs/cli-contract.md

@@ -146,7 +146,7 @@ The goldens need the harness to be a git checkout: `execution-provenance.json` `
 2. UUIDs become `<UUID>`. Git object ids (40 hex, or a short hex value under a `*head`/`*gitRef`/`*commit` key) become `<GIT_REF>`. ISO-8601 timestamps become `<TIMESTAMP>`, and compact stamps in names `<STAMP>`. Path-derived slot ids `local-<adapter>-<8 hex>` become `local-<adapter>-<HASH>`.
 3. The package version becomes `<HARNESS_VERSION>`. Any other `x.y.z` under a key ending in `version` becomes `<VERSION>`.
 4. Numbers under volatile keys: `*pid` becomes `<PID>`, `inode` `<INODE>`, `*port` `<PORT>`, `*At`/`*Time`/`*timestamp`/`mtime*` `<TIMESTAMP>`, and `*Ms`/`duration*`/`elapsed*` `<DURATION>`. Values inside `schema` and `examples` subtrees (static manifest content) are never rewritten.
-5. `invocationDigest` becomes `<DIGEST>`: it hashes `recipe-invocation.json`, which carries sandbox paths and timestamps and is frozen itself in normalised form. `runner.sourceFingerprint` becomes `<FINGERPRINT>`: it hashes the harness source tree, so any harness edit changes it. A `status` holding `git status --porcelain` output (provenance `runner.status` and `libraries[].status`, empty when clean) becomes `<GIT_STATUS>`. A loaded adapter plugin's code digest in doctor's `adapter-plugin:<id>` message becomes `sha256:<PLUGIN_DIGEST>`: it hashes the recipe library's plugin files, so any library edit changes it. Content-only digests (recipe and dependency digests) stay frozen.
+5. `invocationDigest` becomes `<DIGEST>`: it hashes `recipe-invocation.json`, which carries sandbox paths and timestamps and is frozen itself in normalised form. `runner.sourceFingerprint` becomes `<FINGERPRINT>`: it hashes the harness source tree, so any harness edit changes it. A `status` holding `git status --porcelain` output (provenance `runner.status` and `libraries[].status`, empty when clean) becomes `<GIT_STATUS>`. A loaded adapter plugin's code digest in doctor's `adapter-plugin:<id>` message becomes `sha256:<PLUGIN_DIGEST>`: it hashes the recipe library's plugin files, so any library edit changes it. Within `executionPlan`, SHA-256 `digest` and `executionContextDigest` values become `sha256:<DIGEST>` because plans bind sandbox paths, environment and loaded source bytes. `schema` and `examples` remain exempt. Other content-only digests (recipe and dependency digests) stay frozen.
 6. Durations in text (`0.3s`, `123ms`) become `<DURATION>`.
 
 In tree listings, files whose names differ only by a volatile token collapse into one row: a count and the union of their key shapes, or the sorted list of their values in a value tree.

package/library/actions/core/perps/read_account.mjs

@@ -6,13 +6,15 @@ import {
   redactAccount,
   runAdapter,
 } from './_controller.mjs';
+import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 export async function readAccount(input) {
   const { controller, accountAddress, network } = await getCoreController(input);
-  const account = await controller.getAccountState({
+  const account = await withRateLimitRetry('PerpsController.getAccountState', () => controller.getAccountState({
     standalone: true,
     userAddress: accountAddress,
-  });
+  }), { deadline: liveAdapterDeadline(input.node) });
   return {
     action: input.action,
     source: 'perps-controller-standalone',

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

@@ -7,13 +7,15 @@ import {
   runAdapter,
   selectedItems,
 } from './_controller.mjs';
+import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 export async function readOrders(input) {
   const { controller, accountAddress, network } = await getCoreController(input);
-  const orders = await controller.getOpenOrders({
+  const orders = await withRateLimitRetry('PerpsController.getOpenOrders', () => controller.getOpenOrders({
     standalone: true,
     userAddress: accountAddress,
-  });
+  }), { deadline: liveAdapterDeadline(input.node) });
   const matching = selectedItems(input, orders);
   return {
     action: input.action,

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

@@ -7,13 +7,15 @@ import {
   runAdapter,
   selectedItems,
 } from './_controller.mjs';
+import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 export async function readPositions(input) {
   const { controller, accountAddress, network } = await getCoreController(input);
-  const positions = await controller.getPositions({
+  const positions = await withRateLimitRetry('PerpsController.getPositions', () => controller.getPositions({
     standalone: true,
     userAddress: accountAddress,
-  });
+  }), { deadline: liveAdapterDeadline(input.node) });
   const matching = selectedItems(input, positions, 'position');
   return {
     action: input.action,

package/library/actions/extension/analytics/consent.mjs

@@ -85,18 +85,23 @@ export function consentControllerExpression({
         throw new Error('Extension consent state is unavailable.');
       }
       const metamask = root?.metamask ?? root ?? {};
+      // Extension 13.51+ keeps marketing consent in AnalyticsController.optedInToMarketing
+      // (migration 228); older builds expose MetaMetricsController.dataCollectionForMarketing.
+      const dataCollectionForMarketing = typeof metamask.dataCollectionForMarketing === 'boolean'
+        ? metamask.dataCollectionForMarketing
+        : metamask.optedInToMarketing;
       // Debug UI state can lag an acknowledged setter until the next UI sync.
       // Background/snapshot reads have no such subscription to wait for.
       if ((capturedChrome || !storeState) && (
         typeof metamask.optedIn !== 'boolean' ||
-        typeof metamask.dataCollectionForMarketing !== 'boolean'
+        typeof dataCollectionForMarketing !== 'boolean'
       )) {
         throw new Error('Extension consent state did not contain boolean consent fields.');
       }
       return {
         state: {
           optedIn: metamask.optedIn,
-          dataCollectionForMarketing: metamask.dataCollectionForMarketing,
+          dataCollectionForMarketing,
           analyticsId: metamask.analyticsId ? 'set' : null
         },
         source: capturedChrome

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

@@ -1,6 +1,8 @@
 // Fetch production Hyperliquid data and compare it with the opened market's displayed values.
 // Also check the funding countdown and nonblank chart canvases.
 import { dataTestId, marketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 function numeric(value) {
   const match = String(value ?? '').replace(/[$,]/gu, '').match(/-?[0-9]+(?:\.[0-9]+)?/u);
@@ -63,14 +65,16 @@ runAdapter(async (input) => {
   if (endpoint !== 'https://api.hyperliquid.xyz/info') {
     throw new Error('metamask.perps.compare_provider_market endpoint must be the Hyperliquid production info API.');
   }
-  const response = await fetch(endpoint, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ type: 'metaAndAssetCtxs' }),
-    signal: AbortSignal.timeout(Number(input.node?.timeout_ms ?? 15_000)),
-  });
-  if (!response.ok) throw new Error(`Hyperliquid market request failed with HTTP ${response.status}.`);
-  const payload = await response.json();
+  const payload = await withRateLimitRetry('Hyperliquid metaAndAssetCtxs', async () => {
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ type: 'metaAndAssetCtxs' }),
+      signal: AbortSignal.timeout(Number(input.node?.timeout_ms ?? 15_000)),
+    });
+    if (!response.ok) throw new Error(`Hyperliquid market request failed with HTTP ${response.status}.`);
+    return response.json();
+  }, { deadline: liveAdapterDeadline(input.node) });
   const universe = payload?.[0]?.universe;
   const contexts = payload?.[1];
   const index = Array.isArray(universe) ? universe.findIndex((entry) => entry?.name === market) : -1;

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) {
@@ -212,8 +228,9 @@ export function inFixturePolicyLane(input) {
  *   non-order mutation (allowed on testnet; on mainnet only a close from a fixture account).
  * @returns {{ input, network, policy }} input with the completed context.
  */
-export async function withFixturePolicyContext(input, page, { operations, order = null, mainnetAllowed = false }) {
-  // mainnetAllowed: a non-order mutation (a close) a fixture account may run on mainnet.
+export async function withFixturePolicyContext(input, page, { operations, order = null, mainnetAllowed = false, mainnetRefusal = null }) {
+  // mainnetAllowed: a non-order mutation (a close, or a cancel of an order this
+  // run placed) a fixture account may run on mainnet; mainnetRefusal says why not.
   if (!inFixturePolicyLane(input)) return { input, network: null, policy: null };
   const state = await page.evaluate(readPerpsRuntimeStateExpression());
   if (!state?.available || !state?.networkKnown) {
@@ -230,7 +247,7 @@ export async function withFixturePolicyContext(input, page, { operations, order
   if (!order && network === 'mainnet'
     && (!mainnetAllowed || !(await isFixtureAccount(projectRoot, address)))) {
     throw Object.assign(
-      new Error(`PERPS_MAINNET_ORDER_REFUSED: ${input.action} on mainnet needs the funding-file release lane${mainnetAllowed ? ' or a synced test account' : ''}; refused before dispatch.`),
+      new Error(`PERPS_MAINNET_ORDER_REFUSED: ${input.action} on mainnet ${mainnetRefusal && !mainnetAllowed ? `${mainnetRefusal} without funding files` : `needs the funding-file release lane${mainnetAllowed ? ' or a synced test account' : ''}`}; refused before dispatch.`),
       { code: 'PERPS_MAINNET_ORDER_REFUSED' },
     );
   }
@@ -848,9 +865,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 +888,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 +916,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 +939,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) {