@deeeed/metamask-harness 0.86.2 → 0.87.0

package/library/actions/mobile/perps/perps.mjs

@@ -4,11 +4,13 @@ import { pathToFileURL } from 'node:url';
 import {
   MOBILE_BRIDGE_RESULT_ERROR_CODES,
   bridgeCommand,
+  createSetupBudget,
   deadlineFromTimeout,
   earliestDeadline,
   evalAsync,
   inheritedDeadline,
-  isTargetTransition,
+  isUnansweredRead,
+  mobileNavigationTimeoutMs,
   navigate,
   routeSatisfiesNavigationTarget,
   runAdapter,
@@ -25,6 +27,7 @@ import {
   requireHouseNotional,
   requirePerpsOrderAllowed,
 } from '../../shared/perps/order-policy.mjs';
+import { isRateLimited, rateLimitedError, withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -169,7 +172,7 @@ async function readModeState(input, mode, deadline) {
   try {
     return await queryModeState(input, mode, deadline);
   } catch (error) {
-    if (!isTargetTransition(error)) throw error;
+    if (!isUnansweredRead(error)) throw error;
     return null;
   }
 }
@@ -237,6 +240,8 @@ export async function ensureMode(input) {
   throw new Error(`Perps did not reach ${requestedMode} mode before timeout.`);
 }
 
+// Retries the client-not-initialized race until the deadline, and a 429 with
+// the shared rate-limit backoff.
 export async function retryPerpsClientRead(
   read,
   {
@@ -244,6 +249,8 @@ export async function retryPerpsClientRead(
     intervalMs = 500,
     sleep: wait = sleep,
     deadlineEpochMs,
+    call = 'PerpsController read',
+    random,
   } = {},
 ) {
   const localDeadline = Date.now() + Math.max(0, timeoutMs);
@@ -254,7 +261,7 @@ export async function retryPerpsClientRead(
       : Math.min(localDeadline, configuredDeadline);
   while (true) {
     try {
-      return await read();
+      return await withRateLimitRetry(call, read, { deadline, sleep: wait, random });
     } catch (error) {
       if (!/CLIENT_NOT_INITIALIZED/u.test(String(error?.message ?? error))) {
         throw error;
@@ -386,7 +393,7 @@ async function readPositions(input) {
       }
       return positions;
     },
-    { deadlineEpochMs: inheritedDeadline(input) },
+    { deadlineEpochMs: inheritedDeadline(input), call: 'PerpsController.getPositions' },
   );
 }
 
@@ -413,7 +420,7 @@ async function readOpenOrders(input) {
       }
       return orders;
     },
-    { deadlineEpochMs: inheritedDeadline(input) },
+    { deadlineEpochMs: inheritedDeadline(input), call: 'PerpsController.getOpenOrders' },
   );
 }
 
@@ -445,7 +452,7 @@ async function readStrategyOrders(input) {
       }
       return orders;
     },
-    { deadlineEpochMs: inheritedDeadline(input) },
+    { deadlineEpochMs: inheritedDeadline(input), call: 'PerpsController.getTwapOrders/getChaseOrders' },
   );
 }
 
@@ -903,7 +910,7 @@ async function readCurrentRoute(input) {
   try {
     return await bridgeCommand(input, ['get-route']);
   } catch (error) {
-    if (!isTargetTransition(error)) throw error;
+    if (!isUnansweredRead(error)) throw error;
     return null;
   }
 }
@@ -961,8 +968,7 @@ async function waitForPerpsUiTarget(input, testId, deadline) {
 }
 
 async function selectPerpsMarketFromHome(input, symbol, previousRoute) {
-  const timeoutMs = Number(input.node?.navigation_timeout_ms ?? 15_000);
-  const deadline = deadlineFromTimeout(input, timeoutMs);
+  const deadline = deadlineFromTimeout(input, mobileNavigationTimeoutMs(input));
   const params = { market: { symbol } };
   const rowTestId = `perps-market-row-item-${symbol}`;
   const recentlyViewedTestId = `perps-recently-viewed-tile-${symbol}`;
@@ -1045,8 +1051,7 @@ async function waitForRouteChange(input, previousRoute, deadline) {
 }
 
 async function navigateFromMarketDetailsToHome(input, previousRoute) {
-  const timeoutMs = Number(input.node?.navigation_timeout_ms ?? 15_000);
-  const deadline = deadlineFromTimeout(input, timeoutMs);
+  const deadline = deadlineFromTimeout(input, mobileNavigationTimeoutMs(input));
   let visibleTestIds = await readVisiblePerpsTestIds(input, deadline);
   let backTestId = PERPS_MARKET_DETAILS_BACK_TEST_IDS.find((testId) =>
     visibleTestIds.has(testId),
@@ -1468,6 +1473,16 @@ export async function placeOrder(input) {
       );
     }
     if (result?.success === false || result == null) {
+      // Mobile keeps no placement receipt, so a 429 is never retried: nothing proves the venue saw no order.
+      if (isRateLimited(result?.error)) {
+        throw rateLimitedError({
+          call: 'PerpsController.placeOrder',
+          attempts: 1,
+          waitedMs: 0,
+          reason: `no retry, since nothing proves the ${symbol} order was not placed`,
+          next: `read the ${symbol} positions and orders, then wait a minute and rerun only if nothing was placed`,
+        });
+      }
       throw new Error(`Failed to place ${symbol} ${side}: ${result?.error || JSON.stringify(result)}`);
     }
     if (orderType === 'limit') {
@@ -1732,9 +1747,20 @@ function mergeStateConfig(defaults, params) {
   };
 }
 
-export function applyTradingStatePolicy(config) {
+// The policy owns positions, orders and strategies. An explicit request for one
+// of them would be dropped, so it fails before any phase runs.
+export function applyTradingStatePolicy(config, requested) {
   const policy = config.trading_state;
   if (policy === undefined) return config;
+  const dropped = ['positions', 'orders', 'strategies'].filter(
+    (key) => requested[key] !== undefined && requested[key] !== false,
+  );
+  if (dropped.length > 0) {
+    throw new Error(
+      `metamask.perps.start_state trading_state=${String(policy)} sets positions, orders and strategies itself, so the requested ${dropped.join(', ')} would be ignored. ` +
+        `Omit trading_state to apply ${dropped.join(', ')}, or request ${dropped.join(', ')} in a separate metamask.perps.start_state node.`,
+    );
+  }
   if (policy === 'preserve') {
     return { ...config, positions: false, orders: false, strategies: false };
   }
@@ -1969,16 +1995,15 @@ export async function startState(input) {
   const params = paramsForState(input);
   const config = applyTradingStatePolicy(
     mergeStateConfig(profileDefaults(params.profile), params),
+    params,
   );
-  const timeoutMs = Math.max(1, Number(input.node?.timeout_ms ?? 30_000));
-  const deadline = deadlineFromTimeout(input, timeoutMs);
-  const stateInput = () => {
-    const remainingMs = deadline - Date.now();
-    if (remainingMs <= 0) {
-      throw new Error(
-        'metamask.perps.start_state timed out before completing all phases.',
-      );
-    }
+  const budget = createSetupBudget(input, 'metamask.perps.start_state');
+  const navigationSlice = { sliceMs: budget.navigationMs };
+  // Product edits require an app restart before proof. Mobile relocks on restart,
+  // so a deterministic Perps start state must restore the fixture-backed wallet
+  // prerequisite before it navigates or converges controller state.
+  const wallet = await budget.phase('unlock', (phaseInput) => {
+    const remainingMs = phaseInput.node.timeout_ms;
     const configuredTargetMs = Number(input.node?.target_timeout_ms);
     const targetTimeoutMs = Math.min(
       remainingMs,
@@ -1993,75 +2018,78 @@ export async function startState(input) {
         ? configuredUnlockMs
         : remainingMs,
     );
-    return {
-      ...input,
+    return ensureUnlocked({
+      ...phaseInput,
+      action: 'metamask.wallet.ensure_unlocked',
       node: {
-        ...input.node,
-        _action_deadline_epoch_ms: deadline,
-        timeout_ms: remainingMs,
-        bridge_timeout_ms: remainingMs,
-        cdp_timeout_ms: remainingMs,
-        controller_ready_timeout_ms: remainingMs,
+        ...phaseInput.node,
+        action: 'metamask.wallet.ensure_unlocked',
         target_timeout_ms: targetTimeoutMs,
         unlock_timeout_ms: unlockTimeoutMs,
       },
-    };
-  };
-  // Product edits require an app restart before proof. Mobile relocks on restart,
-  // so a deterministic Perps start state must restore the fixture-backed wallet
-  // prerequisite before it navigates or converges controller state.
-  const walletInput = stateInput();
-  const wallet = await ensureUnlocked({
-    ...walletInput,
-    action: 'metamask.wallet.ensure_unlocked',
-    node: { ...walletInput.node, action: 'metamask.wallet.ensure_unlocked' },
+    });
   });
-  const accountInput = stateInput();
   const account = typeof config.account === 'string' && config.account.trim()
-    ? await selectAccount({
-      ...accountInput,
+    ? await budget.phase('account', (phaseInput) => selectAccount({
+      ...phaseInput,
       action: 'metamask.wallet.select_account',
       node: {
-        ...accountInput.node,
+        ...phaseInput.node,
         action: 'metamask.wallet.select_account',
         ...(/^0x[0-9a-f]{40}$/iu.test(config.account.trim())
           ? { address: config.account.trim() }
           : { name: config.account.trim() }),
       },
-    })
+    }))
     : { skipped: true };
   // Entering Perps initializes the provider client on a freshly launched app.
   // State reads before this navigation fail with CLIENT_NOT_INITIALIZED.
-  const navigation = await applyStateNavigation(stateInput(), config);
-  const provider = await ensureProvider(stateInput(), config);
-  const network = await ensureNetwork(stateInput(), config);
+  const navigation = await budget.phase(
+    'navigation',
+    (phaseInput) => applyStateNavigation(phaseInput, config),
+    navigationSlice,
+  );
+  const provider = await budget.phase('provider', (phaseInput) =>
+    ensureProvider(phaseInput, config));
+  const network = await budget.phase('network', (phaseInput) =>
+    ensureNetwork(phaseInput, config));
   let resolvedNavigation = provider.changed || network.changed
-    ? await applyStateNavigation(stateInput(), config)
+    ? await budget.phase(
+      'navigation after provider or network change',
+      (phaseInput) => applyStateNavigation(phaseInput, config),
+      navigationSlice,
+    )
     : navigation;
-  const modeInput = stateInput();
   const marketMode = config.market_mode
-    ? await ensureMode({
-        ...modeInput,
+    ? await budget.phase('market mode', (phaseInput) => ensureMode({
+        ...phaseInput,
         action: 'metamask.perps.ensure_mode',
         node: {
-          ...modeInput.node,
+          ...phaseInput.node,
           action: 'metamask.perps.ensure_mode',
           mode: config.market_mode,
         },
-      })
+      }))
     : { skipped: true };
   if (marketMode.alreadySelected === false) {
-    resolvedNavigation = await applyStateNavigation(stateInput(), config);
-  }
-  const tutorial = await applyTutorialState(stateInput(), config);
-  const readyToTrade = await assertReadyToTrade(stateInput(), config);
-  const balance = await assertBalance(stateInput(), config);
-  const strategies = await applyStrategiesState(
-    stateInput(),
-    config.strategies,
-  );
-  const orders = await applyOrdersState(stateInput(), config.orders);
-  const positions = await applyPositionsState(stateInput(), config.positions);
+    resolvedNavigation = await budget.phase(
+      'navigation after mode change',
+      (phaseInput) => applyStateNavigation(phaseInput, config),
+      navigationSlice,
+    );
+  }
+  const tutorial = await budget.phase('tutorial', (phaseInput) =>
+    applyTutorialState(phaseInput, config));
+  const readyToTrade = await budget.phase('ready to trade', (phaseInput) =>
+    assertReadyToTrade(phaseInput, config));
+  const balance = await budget.phase('balance', (phaseInput) =>
+    assertBalance(phaseInput, config));
+  const strategies = await budget.phase('strategies', (phaseInput) =>
+    applyStrategiesState(phaseInput, config.strategies));
+  const orders = await budget.phase('orders', (phaseInput) =>
+    applyOrdersState(phaseInput, config.orders));
+  const positions = await budget.phase('positions', (phaseInput) =>
+    applyPositionsState(phaseInput, config.positions));
   return {
     action: input.action,
     profile: config.profile ?? params.profile ?? null,
@@ -2090,16 +2118,7 @@ export async function startState(input) {
 }
 
 export async function teardownState(input) {
-  const timeoutMs = Math.max(1, Number(input.node?.timeout_ms ?? 30_000));
-  const deadline = deadlineFromTimeout(input, timeoutMs);
-  const stateInput = (phase) => {
-    if (Date.now() >= deadline) {
-      throw new Error(
-        `metamask.perps.teardown_state timed out before ${phase}.`,
-      );
-    }
-    return withRemainingDeadline(input, deadline);
-  };
+  const budget = createSetupBudget(input, 'metamask.perps.teardown_state');
   const params = paramsForState(input);
   const defaults = {
     provider: 'hyperliquid',
@@ -2110,28 +2129,23 @@ export async function teardownState(input) {
     strategies: params.market || params.symbol || params.markets || params.symbols ? { state: 'none', mode: 'matching' } : false,
   };
   const config = mergeStateConfig(defaults, params);
-  const environment = await assertRequestedRuntimeState(
-    stateInput('checking the requested environment'),
-    config,
-  );
-  const strategies = await applyStrategiesState(
-    stateInput('cleaning strategies'),
-    config.strategies,
-  );
-  const orders = await applyOrdersState(
-    stateInput('cleaning orders'),
-    config.orders,
-  );
-  const positions = await applyPositionsState(
-    stateInput('closing positions'),
-    config.positions,
+  const environment = await budget.phase(
+    'checking the requested environment',
+    (phaseInput) => assertRequestedRuntimeState(phaseInput, config),
   );
+  const strategies = await budget.phase('cleaning strategies', (phaseInput) =>
+    applyStrategiesState(phaseInput, config.strategies));
+  const orders = await budget.phase('cleaning orders', (phaseInput) =>
+    applyOrdersState(phaseInput, config.orders));
+  const positions = await budget.phase('closing positions', (phaseInput) =>
+    applyPositionsState(phaseInput, config.positions));
   const navigation =
     config.page === false
       ? { skipped: true }
-      : await applyStateNavigation(
-          stateInput('restoring the requested page'),
-          config,
+      : await budget.phase(
+          'restoring the requested page',
+          (phaseInput) => applyStateNavigation(phaseInput, config),
+          { sliceMs: budget.navigationMs },
         );
   return {
     action: input.action,

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) &&
@@ -675,19 +712,140 @@ export function earliestDeadline(input, deadline) {
 
 // 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 (CDP_TIMEOUT): polling on would only retry that refusal and could
-// never see a route that did arrive.
+// 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';
@@ -850,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);

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;
+}