@deeeed/metamask-harness 0.44.3 → 0.45.1

package/docs/PERFORMANCE-CAPTURE.md

@@ -1,6 +1,6 @@
 # UI smoothness capture
 
-`app.performance_capture` attributes CDP trace samples to the exact Recipe Protocol v1 nodes that run inside an explicit window. Mobile and Extension use the same action contract.
+`app.performance_capture` attributes native frame samples to the exact Recipe Protocol v1 nodes that run inside an explicit window. Mobile and Extension use the same action contract.
 
 ```json
 {
@@ -13,21 +13,50 @@
 }
 ```
 
-End the same ID with `phase: "end"`. The action writes bounded JSON and a self-contained HTML report. `app.performance_assert` can require a status, minimum frame count, and specific node intervals.
+End the same ID with `phase: "end"`. The action writes a machine-readable schema-v2 summary, a self-contained HTML report, and a bounded gzip-compressed Chrome Trace Event file named `*-trace.json.gz`. Chrome DevTools and Perfetto can consume the trace format. `app.performance_assert` can require a status, minimum frame count, and specific node intervals.
+
+## How it works
+
+1. `app.performance_capture` with `phase: "start"` selects the platform source and starts a bounded capture window.
+2. The recipe runner records each node's start and end on the host clock while the interaction runs.
+3. `phase: "end"` maps native frame timestamps onto those node intervals and closes the source before building artifacts.
+4. The harness writes summary JSON for tools, self-contained HTML for people, and a gzip-compressed Chrome trace for DevTools or Perfetto.
+5. `app.performance_assert` checks source status, frame count, and required node attribution. Missing coverage fails or remains `N/A`; it never becomes zero.
+
+## Host prerequisites
+
+Run `mm-harness doctor --json` from the target checkout before performance work on a new machine.
+
+| Target | Required host tools | Notes |
+| --- | --- | --- |
+| Android | `adb` from Android Platform Tools | `gfxinfo framestats` is built into Android; there is no separate `gfxinfo` package to install. |
+| iOS Simulator | Xcode command-line tools (`xcrun`) | Native frames require a debug client with `unstable_frameRecordingEnabled: true`. Visible UI assertions and `ui.navigate page=perps-market mode=...` also require `idb`. |
+| Extension | Chrome or Chromium with an isolated CDP profile | The harness uses Chromium's Tracing domain. |
+| Trace viewing | Chrome DevTools or Perfetto | Optional for recipe execution; required only to inspect the raw `*-trace.json.gz` file visually. |
+
+`Flashlight`, Instruments, and an in-app FPS overlay are not harness dependencies. Keep the recipe HUD visible; it is separate from the performance source.
 
 ## Sources and status
 
-- Mobile uses React Native's `Tracing.start`, `Tracing.dataCollected`, and `Tracing.end` implementation. iOS frame timings come from its built-in `CADisplayLink` observer. Android frame timings come from `Window.FrameMetrics`. The app build must report `unstable_frameRecordingEnabled: true`; otherwise native UI coverage is partial or unavailable.
+- Android polls `adb shell dumpsys gfxinfo <package> framestats` from the host. It maps Android uptime to recipe timestamps, merges frame snapshots, and measures `FrameCompleted - IntendedVsync` against the device's refresh-rate budget. It does not need a Mobile patch.
+- iOS uses React Native's `Tracing.start`, `Tracing.dataCollected`, and `Tracing.end` implementation. Frame timings come from its native `CADisplayLink` observer. The debug app must report `unstable_frameRecordingEnabled: true`; otherwise native UI coverage is unavailable. Instruments `Animation Hitches` and `Core Animation FPS` do not support iOS Simulator.
+- React Native rejects iOS Tracing after more than one RN host has been registered during the app process lifetime. Its counter is cumulative: removing the old host does not decrement it. Unlocking does not create or remove a host; the MetaMask unlock path only unlocks the wallet and navigates. The observed second host came from reopening an already-running Expo dev-client process against Metro.
+- Establish the iOS measurement cohort explicitly: run `app.lifecycle` with `command: "restart"` outside every capture window, unlock the keyring after the process restart, prove the wallet reached Home, then start `app.performance_capture`. Unlocking does not register another host; restart → unlock → trace passed in one process. This terminates only the app process. It must not restart Metro or the simulator, and capture failure must never trigger it as automatic recovery.
 - Extension uses Chromium's implementation of the same CDP Tracing domain. Frame and JavaScript data count only after the harness proves they belong to the MetaMask renderer. Unresolved browser-wide events produce partial or unavailable coverage.
-- The harness records a CDP clock marker and maps trace timestamps onto recipe-node timestamps. It waits for `Tracing.tracingComplete` before writing evidence.
+- CDP sources record a clock marker and map trace timestamps onto recipe-node timestamps. They wait for `Tracing.tracingComplete` before writing evidence. Android uses the uptime value emitted by `gfxinfo`; the report exposes the measured clock-mapping uncertainty because it bounds node attribution.
 - The JSON report includes bounded trace evidence counts for `BeginFrame`, `DrawFrame`, `RunTask`, and `ProfileChunk`, plus data-loss and retention-overflow flags.
-- UI frames and JavaScript work remain separate sources. `RunTask` events produce JavaScript task summaries. Sampling `ProfileChunk` events prove profiler data exists but are not converted to task timing or FPS. JavaScript work is never labelled as UI or JS FPS.
+- UI frames and JavaScript work remain separate sources. Chromium `RunTask` events produce JavaScript task summaries on Extension. React Native Mobile does not emit `RunTask`, so Mobile reports those fields as not applicable and judges coverage from native UI frames. Sampling `ProfileChunk` events prove Hermes profiler data exists but are not converted to task timing or FPS.
+- Active UI FPS uses consecutive native vsync intervals only while frames are being produced. Fewer than five usable intervals or an unclassified long cadence gap reports `N/A`. Sampling jitter can never raise active FPS above the detected refresh rate.
+- The trace cadence determines the refresh rate and fallback per-frame budget. Android over-budget percentage uses `FrameDeadline` when present; frame percentiles use `FrameCompleted - IntendedVsync`. iOS percentiles describe continuous `CADisplayLink` cadence rather than render work duration. An unclassified long gap forces partial coverage and `N/A` FPS. It stays visible as a gap and can be the worst observed sample, but it is not classified as an over-budget frame.
 - `complete`, `partial`, and `unavailable` describe source coverage. Missing data is never converted to zero.
+- Raw trace timestamps use host epoch microseconds. Standard complete events on the `MetaMask Harness / Recipe nodes` track preserve the node boundaries used by the HTML and JSON reports.
 
 `app.performance_assert.minimum_frame_count` applies only to native UI or Chromium renderer frames. JavaScript task count cannot satisfy it.
 
+Node duration includes automation, native state checks, and wait time inside the node. It is not screen time-to-content. Use product lifecycle milestones for section visibility and data readiness.
+
 Capture is explicit only. Use the action for comparisons on the same runtime and build. Automatic capture remains disabled until its overhead passes a matched benchmark.
 
 ## Sentry promotion boundary
 
-This action does not send data to Sentry. A future product integration may promote only bounded aggregates after release-build overhead is independently accepted: source status, stable node/action name, frame count, p50/p95/p99, jank percentage, and longest frame. Do not send raw frame samples, recipe parameters, wallet/account identity, URLs, or artifact contents.
+This action does not send data to Sentry. A future product integration may promote only bounded aggregates after release-build overhead is independently accepted: source status, stable node/action name, frame count, p50/p95/p99, over-budget percentage, and longest frame. Do not send raw frame samples, recipe parameters, wallet/account identity, URLs, or artifact contents.

package/docs/RECIPES.md

@@ -211,6 +211,17 @@ Rules:
 
 - Validate with `--plan` before side effects.
 - Use real product paths; never mutate hidden state to fabricate proof.
+- Never repair the product while proving it. A normal action must not restart,
+  reload, foreground, reconnect, clear caches, reset state, or rerun the
+  journey after failure. Observe the product's natural result and fail with the
+  last observed state when it does not arrive.
+- Put intended setup and lifecycle transitions in their own recipe nodes. Use
+  an explicit lifecycle node when restart, reload, reconnect, background, or
+  foreground behavior is the claim. A persistence proof must show the
+  transition as a node between the immediate and persisted assertions.
+- Keep setup outside the proof window. Setup may converge fixture-backed state
+  when the node names the mutation and the trace records it, but setup evidence
+  cannot prove the behavior under test.
 - Prove preparation with an independent read/assert or visible UI postcondition.
 - Keep ticket-specific claims in task-local recipes.
 - Compose, repair, or parameterize repeated behavior instead of multiplying names.
@@ -248,7 +259,8 @@ Keep responsibilities narrow:
 - **Recipes** compose actions and own journey order, safe defaults, invariants,
   and proof.
 - **Actions** translate one stable operation to existing UI, CDP, or controller
-  capabilities; they do not reimplement product business logic.
+  capabilities; they do not reimplement product business logic or hide
+  lifecycle recovery.
 - **Product/controllers** remain the source of truth for state transitions,
   validation, transactions, and domain behavior.
 

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

@@ -92,12 +92,8 @@ async function waitForExactPrices(page, identity, facts, timeoutMs) {
   throw new Error(`exact TP/SL postcondition was not visible: ${JSON.stringify(after)}.`);
 }
 
-async function observePersistedPrices(page, identity, facts, timeoutMs) {
+async function observeUpdatedPrices(page, identity, facts, timeoutMs) {
   const immediate = await waitForExactPrices(page, identity, facts, timeoutMs);
-  await page.session.call('Page.reload', { ignoreCache: true });
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  await page.waitForSelector(dataTestId('perps-position-size-value'), { timeoutMs: 20_000 });
-  const persisted = await waitForExactPrices(page, identity, facts, timeoutMs);
   return {
     success: true,
     positionBefore: facts.positionBefore,
@@ -107,7 +103,6 @@ async function observePersistedPrices(page, identity, facts, timeoutMs) {
       stopLossPrice: facts.stopLossPrice,
     },
     immediate,
-    persistedAfterReload: persisted,
   };
 }
 
@@ -191,7 +186,7 @@ export async function updatePositionTpsl(input) {
         input,
         identity,
         dispatch: async () => { throw new Error('resumed TP/SL mutation must not dispatch'); },
-        observe: async ({ receipt }) => observePersistedPrices(
+        observe: async ({ receipt }) => observeUpdatedPrices(
           page,
           identity,
           receipt.facts,
@@ -264,7 +259,7 @@ export async function updatePositionTpsl(input) {
         button: 'left', buttons: 0, clickCount: 1,
       });
     },
-    observe: async ({ receipt }) => observePersistedPrices(
+    observe: async ({ receipt }) => observeUpdatedPrices(
       page,
       identity,
       receipt.facts,

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

@@ -822,16 +822,12 @@ export async function placeOrder(input) {
   if (result?.success === false || result == null) {
     throw new Error(`Failed to place ${symbol} ${side}: ${result?.error || JSON.stringify(result)}`);
   }
-  const refresh = await evalAsync(
-    input,
-    'globalThis.__AGENTIC__ && globalThis.__AGENTIC__.refreshPerpsStreams ? globalThis.__AGENTIC__.refreshPerpsStreams().then(function(r){return JSON.stringify(r)}) : Promise.resolve(JSON.stringify({ ok: false, reason: "refreshPerpsStreams unavailable" }))',
-  );
   if (orderType === 'limit') {
     await waitForSelectedState(input, readOpenOrders, true, Number(input.node?.timeout_ms ?? 30000));
   } else {
     await waitForPositionPresent(input, symbol, Number(input.node?.timeout_ms ?? 30000));
   }
-  return { action: input.action, market: symbol, side, orderType, amount, size, leverage, limitPrice, submitted: true, result, refresh, proofPath: 'mobile-perps-controller-place-order' };
+  return { action: input.action, market: symbol, side, orderType, amount, size, leverage, limitPrice, submitted: true, result, proofPath: 'mobile-perps-controller-place-order' };
 }
 
 export async function ensurePositions(input) {

package/library/actions/mobile/perps/read-visible-state-loop.mjs

@@ -0,0 +1,73 @@
+import { observeNativeUi } from '../platform/observe-ui.mjs';
+import {
+  normalizeVisiblePerpsState,
+  resolveVisibleStateOptions,
+} from '../../shared/perps/visible-state.mjs';
+
+export async function readVisiblePerpsState(
+  input,
+  observe = observeNativeUi,
+) {
+  const options = resolveVisibleStateOptions(input.node);
+  const deadline = Date.now() + Number(input.node?.timeout_ms ?? 30_000);
+  let observed;
+  let screen;
+  let visible;
+  let lastAssertionError;
+  let lastObservationError;
+  do {
+    try {
+      observed = await observe(
+        { refs: ['ui.screen', 'ui.visible'], node: input.node },
+        input.context,
+      );
+      lastObservationError = undefined;
+    } catch (error) {
+      if (
+        /requires the idb client|requires adb|Android SDK Platform Tools/iu.test(
+          String(error?.message ?? error),
+        )
+      ) {
+        throw error;
+      }
+      lastObservationError = error;
+      observed = undefined;
+    }
+    screen = observed?.observations?.['ui.screen'];
+    visible = observed?.observations?.['ui.visible'];
+    if (screen && visible) {
+      try {
+        return {
+          action: input.action,
+          ...normalizeVisiblePerpsState({
+            route: screen.route,
+            title: screen.title,
+            items: visible.items,
+            offscreenItems: visible.hidden_or_offscreen,
+            truncated: visible.truncated,
+          }, options, 'mobile'),
+          proofPath: 'native-accessibility',
+        };
+      } catch (error) {
+        lastAssertionError = error;
+      }
+    }
+    if (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  } while (Date.now() < deadline);
+  if (lastAssertionError) throw lastAssertionError;
+  const warning = observed?.warnings
+    ?.map((entry) => entry.message)
+    .filter(Boolean)
+    .join('; ');
+  const observationError = lastObservationError instanceof Error
+    ? lastObservationError.message
+    : lastObservationError === undefined
+      ? undefined
+      : String(lastObservationError);
+  const detail = warning ?? observationError;
+  throw new Error(
+    `Mobile visible Perps state is unavailable${detail ? `: ${detail}` : '.'}`,
+  );
+}

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

@@ -1,31 +1,4 @@
 import { runAdapter } from '../platform/bridge.mjs';
-import { observeNativeUi } from '../platform/observe-ui.mjs';
-import {
-  normalizeVisiblePerpsState,
-  resolveVisibleStateOptions,
-} from '../../shared/perps/visible-state.mjs';
+import { readVisiblePerpsState } from './read-visible-state-loop.mjs';
 
-runAdapter(async (input) => {
-  const options = resolveVisibleStateOptions(input.node);
-  const observed = await observeNativeUi(
-    { refs: ['ui.screen', 'ui.visible'], node: input.node },
-    input.context,
-  );
-  const screen = observed.observations?.['ui.screen'];
-  const visible = observed.observations?.['ui.visible'];
-  if (!screen || !visible) {
-    const warning = observed.warnings?.map((entry) => entry.message).filter(Boolean).join('; ');
-    throw new Error(`Mobile visible Perps state is unavailable${warning ? `: ${warning}` : '.'}`);
-  }
-  return {
-    action: input.action,
-    ...normalizeVisiblePerpsState({
-      route: screen.route,
-      title: screen.title,
-      items: visible.items,
-      offscreenItems: visible.hidden_or_offscreen,
-      truncated: visible.truncated,
-    }, options, 'mobile'),
-    proofPath: 'native-accessibility',
-  };
-});
+runAdapter(readVisiblePerpsState);

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

@@ -227,7 +227,7 @@ export function shouldResolveAndroidTargetModel(
   return Boolean(serial && !targetName && (!device || device === serial));
 }
 
-function resolveMobileTarget(input) {
+export function resolveMobileTarget(input) {
   const contextEnv = input.context?.env || {};
   const explicitSimulatorUdid =
     input.node?.sim_udid ?? contextEnv.SIM_UDID ?? process.env.SIM_UDID;

package/library/actions/mobile/platform/observe-ui.mjs

@@ -134,7 +134,7 @@ async function readAndroidHierarchy(node, env) {
   );
   const hierarchy = parseAndroidHierarchy(stdout);
   if (hierarchy.nodeCount === 0) {
-    throw new Error('adb returned an empty UIAutomator hierarchy.');
+    return readAndroidAgentDeviceHierarchy(serial, env);
   }
   return normalizedHierarchy(
     'adb-uiautomator',
@@ -364,7 +364,7 @@ function flattenIosHierarchy(value) {
       screenName ??= label;
       screenBounds ??= bounds;
     }
-    if (isActionableRole(role)) {
+    if (isActionableRole(role) || testId) {
       const normalized = compactItem({
         role,
         label,

package/library/actions/mobile/ui/native-navigation.mjs

@@ -4,6 +4,10 @@ import {
   nativeAgentDeviceStateDir,
   nativeSessionName,
 } from '../platform/native-session-name.mjs';
+import { bridgeCommand } from '../platform/bridge.mjs';
+import {
+  observeNativeUi,
+} from '../platform/observe-ui.mjs';
 
 const IDS = {
   wallet: ['wallet-safe-area', 'homepage-container'],
@@ -151,6 +155,215 @@ export async function navigateOpaqueMobile(input, destination) {
   }
 }
 
+export async function ensureVisibleAndroidPerpsMode(input, perpsMode) {
+  if (!['lite', 'pro'].includes(perpsMode)) {
+    throw new Error('Opaque Mobile Perps mode must be lite or pro.');
+  }
+  const env = { ...process.env, ...(input.context?.env ?? {}) };
+  const device = String(
+    env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? env.ANDROID_DEVICE ?? '',
+  ).trim();
+  if (!device) {
+    throw new Error(
+      'Android Perps mode requires one explicit device serial.',
+    );
+  }
+  const app = String(env.ANDROID_PACKAGE_ID ?? 'io.metamask');
+  const session = nativeSessionName(env, device, app);
+  const stateDir = nativeAgentDeviceStateDir(env, input.context.projectRoot, device);
+  const client = createAgentDeviceClient({
+    session,
+    stateDir,
+    lockPolicy: 'reject',
+    lockPlatform: 'android',
+  });
+  const selection = { platform: 'android', target: 'mobile', serial: device, session };
+  const transport = createAgentDeviceUiTransport({
+    platform: 'android',
+    device,
+    app,
+    session,
+    stateDir,
+    client,
+  });
+  const context = {
+    nodeId: String(input.context?.nodeId ?? 'navigate'),
+    projectRoot: input.context.projectRoot,
+    artifactsDir: input.context.artifactsDir,
+    env,
+  };
+  const press = (testId) => transport.execute('ui.press', {
+    test_id: testId,
+    timeout_ms: Number(input.node?.timeout_ms ?? 30_000),
+    settle: false,
+  }, context);
+  const snapshot = () => client.capture.snapshot({
+    platform: 'android',
+    target: 'mobile',
+    serial: device,
+    session,
+    app,
+    interactiveOnly: false,
+    forceFull: true,
+  });
+  const identifiers = async () => new Set(
+    (await snapshot()).nodes
+      .filter((node) => node.visibleToUser !== false)
+      .map((node) => String(node.identifier ?? '')),
+  );
+
+  try {
+    const deadline = Date.now() + Number(input.node?.timeout_ms ?? 30_000);
+    const expectedToggle = perpsMode === 'pro' ? IDS.modeTogglePro : IDS.modeToggleLite;
+    const currentToggle = perpsMode === 'pro' ? IDS.modeToggleLite : IDS.modeTogglePro;
+    const option = perpsMode === 'pro' ? IDS.modePro : IDS.modeLite;
+    let expectedStreak = 0;
+    let currentStreak = 0;
+    let optionStreak = 0;
+    let currentAttempts = 0;
+    let optionAttempts = 0;
+    let lastObservationError;
+    while (Date.now() <= deadline) {
+      let ids;
+      try {
+        ids = await identifiers();
+        lastObservationError = undefined;
+      } catch (error) {
+        lastObservationError = String(error?.message ?? error);
+        expectedStreak = 0;
+        currentStreak = 0;
+        optionStreak = 0;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        continue;
+      }
+      if (ids.has(expectedToggle)) {
+        expectedStreak += 1;
+        if (expectedStreak >= 2) {
+          return {
+            mode: perpsMode,
+            observedScreen: expectedToggle,
+            provider: 'android-native-accessibility',
+            proofPath: 'visible-native-navigation',
+          };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        continue;
+      }
+      expectedStreak = 0;
+      if (ids.has(option)) {
+        optionStreak += 1;
+        if (optionAttempts === 0 || (optionStreak >= 2 && optionAttempts < 2)) {
+          optionAttempts += 1;
+          optionStreak = 0;
+          await pressCurrent(press, option);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        continue;
+      }
+      optionStreak = 0;
+      if (
+        (ids.has(IDS.market) || ids.has(IDS.proMarket)) &&
+        ids.has(currentToggle)
+      ) {
+        currentStreak += 1;
+        if (currentAttempts === 0 || (currentStreak >= 2 && currentAttempts < 2)) {
+          currentAttempts += 1;
+          currentStreak = 0;
+          await pressCurrent(press, currentToggle);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        continue;
+      }
+      currentStreak = 0;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    throw new Error(
+      `Android navigation did not visibly switch Perps to ${perpsMode} mode` +
+      `${lastObservationError ? `: ${lastObservationError}` : '.'}`,
+    );
+  } finally {
+    await closeNativeSession(client, selection);
+  }
+}
+
+export async function ensureVisibleIosPerpsMode(input, perpsMode) {
+  if (!['lite', 'pro'].includes(perpsMode)) {
+    throw new Error('iOS Perps mode must be lite or pro.');
+  }
+  const expectedToggle = perpsMode === 'pro' ? IDS.modeTogglePro : IDS.modeToggleLite;
+  const currentToggle = perpsMode === 'pro' ? IDS.modeToggleLite : IDS.modeTogglePro;
+  const option = perpsMode === 'pro' ? IDS.modePro : IDS.modeLite;
+  const deadline = Date.now() + Number(input.node?.timeout_ms ?? 30_000);
+  let lastObserved = [];
+  let lastWarning;
+  let expectedStreak = 0;
+  let currentStreak = 0;
+  let optionStreak = 0;
+  let currentAttempts = 0;
+  let optionAttempts = 0;
+  while (Date.now() <= deadline) {
+    let observed;
+    try {
+      observed = await observeNativeUi(
+        { refs: ['ui.visible'], node: input.node },
+        input.context,
+      );
+    } catch (error) {
+      lastWarning = String(error?.message ?? error);
+      expectedStreak = 0;
+      currentStreak = 0;
+      optionStreak = 0;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+      continue;
+    }
+    lastWarning = observed.warnings?.map((warning) => warning.message).filter(Boolean).join('; ');
+    const items = observed.observations?.['ui.visible']?.items ?? [];
+    const ids = new Set(items.map((item) => String(item.test_id ?? '')));
+    lastObserved = [...ids].filter(Boolean).slice(0, 20);
+    if (ids.has(expectedToggle)) {
+      expectedStreak += 1;
+      if (expectedStreak >= 2) {
+        return {
+          mode: perpsMode,
+          observedScreen: expectedToggle,
+          provider: 'ios-native-accessibility',
+          proofPath: 'visible-native-navigation',
+        };
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250));
+      continue;
+    }
+    expectedStreak = 0;
+    if (ids.has(option)) {
+      optionStreak += 1;
+      if (optionAttempts === 0 || (optionStreak >= 2 && optionAttempts < 2)) {
+        optionAttempts += 1;
+        optionStreak = 0;
+        await bridgeCommand(input, ['press-test-id', option]);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250));
+      continue;
+    }
+    optionStreak = 0;
+    if (ids.has(currentToggle)) {
+      currentStreak += 1;
+      if (currentAttempts === 0 || (currentStreak >= 2 && currentAttempts < 2)) {
+        currentAttempts += 1;
+        currentStreak = 0;
+        await bridgeCommand(input, ['press-test-id', currentToggle]);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250));
+      continue;
+    }
+    currentStreak = 0;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(
+    `iOS navigation did not visibly switch Perps to ${perpsMode} mode. ` +
+    `Observed: ${lastObserved.join(', ') || 'none'}${lastWarning ? `. ${lastWarning}` : ''}`,
+  );
+}
+
 async function navigateSwap({ identifiers, press, wait, back }) {
   let ids = await identifiers();
   if (ids.has(IDS.swapSourceInput)) return IDS.swapSourceInput;

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

@@ -1,5 +1,13 @@
-import { navigate, runAdapter } from '../platform/bridge.mjs';
-import { navigateOpaqueMobile } from './native-navigation.mjs';
+import {
+  navigate,
+  resolveMobileTarget,
+  runAdapter,
+} from '../platform/bridge.mjs';
+import {
+  ensureVisibleAndroidPerpsMode,
+  ensureVisibleIosPerpsMode,
+  navigateOpaqueMobile,
+} from './native-navigation.mjs';
 
 const PAGE_ROUTES = {
   home: { route: 'WalletView', params: {} },
@@ -44,8 +52,33 @@ runAdapter(async (input) => {
     ) {
       return navigateOpaqueMobile(input, alias);
     }
-    const navigation = await navigate(input, alias.route, alias.params);
-    return { action: input.action, ...alias, navigation, proofPath: 'agentic-navigation' };
+    const navigationParams = alias.page === 'perps-market'
+      ? { market: alias.params.market }
+      : alias.params;
+    const navigation = await navigate(input, alias.route, navigationParams);
+    const requestedPlatform = resolveMobileTarget(input).requestedPlatform;
+    const env = { ...process.env, ...(input.context?.env ?? {}) };
+    const platform =
+      requestedPlatform ||
+      (env.ADB_SERIAL || env.ANDROID_SERIAL || env.ANDROID_DEVICE
+        ? 'android'
+        : 'ios');
+    const visibleMode =
+      alias.page === 'perps-market' && text(input.node?.mode)
+      ? platform === 'android'
+        ? await ensureVisibleAndroidPerpsMode(input, alias.params.mode)
+        : await ensureVisibleIosPerpsMode(input, alias.params.mode)
+      : undefined;
+    return {
+      action: input.action,
+      ...alias,
+      params: navigationParams,
+      navigation,
+      ...(visibleMode ? { visibleMode } : {}),
+      proofPath: visibleMode
+        ? 'agentic-navigation+visible-native-navigation'
+        : 'agentic-navigation',
+    };
   }
 
   const route = input.node?.route ?? input.node?.screen;

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

@@ -56,8 +56,7 @@ async function statusBeforeDeadline(input, deadline) {
       30000,
   );
   const probeTimeoutMs = Math.min(
-    15000,
-    Math.max(5000, Math.floor(remainingMs / 3)),
+    Math.max(750, Math.floor(remainingMs / 3)),
     remainingMs,
     Number.isFinite(configuredMs) && configuredMs > 0 ? configuredMs : 30000,
   );
@@ -141,32 +140,41 @@ function isUnlockedStatus(status, input) {
   );
 }
 
-async function waitForStableUnlocked(input, initialStatus, stableMs = 750) {
+async function waitForStableUnlocked(
+  input,
+  initialStatus,
+  stableMs = 750,
+  recoveryTimeoutMs = 30000,
+) {
   if (!isUnlockedStatus(initialStatus, input)) return null;
-  const deadline = Date.now() + stableMs;
+  if (stableMs <= 0) return initialStatus;
+  const deadline =
+    Date.now() + Math.max(stableMs + 250, recoveryTimeoutMs);
+  let stableSince = Date.now();
   let last = initialStatus;
-  let transientDrops = 0;
   while (Date.now() < deadline) {
+    if (stableSince !== null && Date.now() - stableSince >= stableMs) {
+      return last;
+    }
     await new Promise((resolve) => setTimeout(resolve, 250));
     try {
       last = await statusBeforeDeadline(input, deadline);
       if (!isUnlockedStatus(last, input)) {
         if (routeName(last, input) === 'Login') return null;
-        transientDrops += 1;
-        if (transientDrops > 2) return null;
+        stableSince = null;
         continue;
       }
-      transientDrops = 0;
+      stableSince ??= Date.now();
     } catch {
-      // Recovery is correct: a bridge error during the stability window is the
-      // same signal as an unlocked-state drop — count it toward the transient
-      // threshold; exceeding it returns null so the caller runs the real
-      // password unlock instead of reporting a false alreadyUnlocked.
-      transientDrops += 1;
-      if (transientDrops > 2) return null;
+      // The Hermes page can rotate after Login -> Home. Keep waiting for the
+      // same pinned runtime to become observable again; do not restart Metro or
+      // the app, and restart the stability window when it returns.
+      stableSince = null;
     }
   }
-  return isUnlockedStatus(last, input) ? last : null;
+  return stableSince !== null && Date.now() - stableSince >= stableMs
+    ? last
+    : null;
 }
 
 export async function ensureUnlocked(input) {
@@ -194,7 +202,12 @@ export async function ensureUnlocked(input) {
     targetStatus,
     Math.max(0, targetDeadline - Date.now()),
   );
-  const stableBefore = await waitForStableUnlocked(input, before, Number(input.node?.stable_unlocked_ms ?? 750));
+  const stableBefore = await waitForStableUnlocked(
+    input,
+    before,
+    Number(input.node?.stable_unlocked_ms ?? 750),
+    Math.max(0, targetDeadline - Date.now()),
+  );
   if (stableBefore) {
     return {
       action: input.action,
@@ -251,10 +264,12 @@ export async function ensureUnlocked(input) {
   }
   const remainingUnlockMs = Math.max(1, unlockDeadline - Date.now());
   const after = await waitForUnlocked(input, remainingUnlockMs);
+  const remainingStabilityMs = Math.max(1, unlockDeadline - Date.now());
   const stableAfter = await waitForStableUnlocked(
     input,
     after,
     Number(input.node?.stable_unlocked_ms ?? 750),
+    remainingStabilityMs,
   );
   if (!stableAfter) {
     throw new Error('Mobile wallet did not remain unlocked for the required stability window.');