@deeeed/metamask-harness 0.47.4 → 0.48.0

package/docs/RECIPES.md

@@ -32,7 +32,7 @@ task proof and may call other recipes.
   "paramsSchema": {
     "type": "object",
     "properties": {
-      "account": { "type": "string", "default": "Account 1" }
+      "timeout_ms": { "type": "integer", "minimum": 1, "default": 15000 }
     },
     "additionalProperties": false
   },
@@ -41,6 +41,7 @@ task proof and may call other recipes.
     "nodes": {
       "unlock": {
         "action": "metamask.wallet.ensure_unlocked",
+        "timeout_ms": "{{params.timeout_ms}}",
         "intent": "Make the fixture-backed wallet ready for use",
         "next": "done"
       },
@@ -54,8 +55,8 @@ Defaults are applied before validation. Root values use `key=value`; a nested
 recipe call uses `action: "call"`, `ref`, and `params`.
 
 ```bash
-mm-harness run recipe.json account="Account 2" --plan
-mm-harness run recipe.json account="Account 2"
+mm-harness run recipe.json timeout_ms=20000 --plan
+mm-harness run recipe.json timeout_ms=20000
 ```
 
 Use the shared wallet setup recipe on either Mobile or Extension. `auto`
@@ -76,11 +77,40 @@ fixture. Secret values are redacted from commands and evidence. Visible imports
 default to MetaMetrics off and skip Mobile's optional interests; password terms
 are required and always accepted by the action.
 
+### Retained-memory measurements
+
+Budget failures retain their samples and limits in a private JSON report linked
+from the failed node's error. Inspect that report before attributing growth or
+changing a budget; it is supporting evidence, not a passing measurement.
+
+Use `performance.navigation-memory` for one screen in an unlocked Extension.
+Choose its current route/marker, sample count, and growth bounds before running:
+
+```sh
+mm-harness run performance.navigation-memory \
+  'screen_hash=#/settings' screen_test_id=settings-tab-bar-grouped --hud hide
+```
+
+`performance.navigation-memory-suite` retains the full eight-screen audit,
+detached-DOM check, and idle-control comparison. A one-screen slope does not
+prove those broader claims. Check the suite's reference markers against the
+tested build before running it.
+
 ### Extension Perps release recipes
 
 Discover these identifiers with `run --list --adapter extension --json` and
 inspect the exact graph with `run <id> --describe --adapter extension --json`:
 
+Market/activity filters, visible consistency, funds previews, order-form cases,
+live order journeys, watchlist and source-dev snapshot consistency are owned by the
+[Perps team library](https://github.com/MetaMask/experimental-metamask-recipe-perps).
+Register the library checkout to discover and compose those unchanged names:
+
+```sh
+export RECIPE_LIBRARY_PATH="perps=/path/to/experimental-metamask-recipe-perps"
+mm-harness run perps.release-market-filters --describe --adapter extension --json
+```
+
 | Behavior | Canonical recipe |
 | --- | --- |
 | Activity filter routes | `perps.release-activity-filters` |
@@ -90,10 +120,10 @@ inspect the exact graph with `run <id> --describe --adapter extension --json`:
 | Market header and statistics | `perps.release-market-details` |
 | Market categories | `perps.release-market-filters` |
 | Market text search | `perps.release-market-search` |
-| Long/Short and Market/Limit entry controls | `perps.release-order-entry` |
-| Amount, leverage, keyboard, auto-close, and TP/SL validation | `perps.release-order-validation` |
+| Long/Short and Market/Limit entry controls | `perps.release-order-entry case=configuration` |
+| Amount, leverage, keyboard, auto-close, and TP/SL validation | `perps.release-order-entry case=validation` |
 | Official-build rendered market/activity consistency | `perps.release-visible-consistency` |
-| Favorite persistence and cleanup | `perps.release-watchlist` |
+| Favorite add/remove persistence and observed-baseline restoration | `perps.release-watchlist` |
 | Hook-backed controller snapshot consistency | `perps.source-dev-snapshot-consistency` |
 
 The source-development snapshot recipe is compatibility evidence only and must
@@ -102,11 +132,22 @@ Extension-scoped because their semantic actions are not shared release
 capabilities. Keep ticket-specific orchestration task-local and compose these
 identifiers with `call` instead of copying their graphs.
 
-Order-entry and order-validation callers must supply a market with no existing
+Watchlist proof requires a visible market-bound favorite baseline before any
+toggle. Unknown is not false. Restoration is verified on the audited Extension
+runtime; the audited Mobile reader cannot establish that baseline, so it must
+stop before mutation rather than infer identity from unrelated market text.
+
+The order-form recipe is in the registered Perps team library. Both cases require a market with no existing
 position; the product exposes Modify/Close instead of New Long/Short for an
-already-open market. Source-development snapshot callers may opt into a
+already-open market. Validation prices and leverage must match the selected
+market's current rules; the examples are not universal defaults. Give each
+composed case a distinct `capture_path`.
+Source-development snapshot callers may opt into a
 positive `minimum_changed_market_count`; the default does not require a price
 tick, while typed-history and visible-activity agreement remain strict.
+Use the snapshot recipe's `history` object to bound existing record dates and
+`capture_path` to separate evidence when composing calls. Market sampling does
+not repeatedly fetch history.
 
 The two live recipes require explicit `confirm_live=true`. The trusted runner
 must also verify the exact consented funding request, preflight, release proof,
@@ -126,15 +167,56 @@ using a generic UI press invalidates the cached identity proof; a fresh visible
 `ensure_positions`, `ensure_orders`, and `teardown_state` only observe and assert
 state that already exists; their schemas reject creation and cleanup inputs.
 Extension does not expose `start_state`, readiness claims, multi-position
-background closure, or the mutating `runner.action-validation` recipe. Financial
+background closure. The former `runner.action-validation` is now a repository-only
+maintainer exercise at `scripts/qa/mobile-action-validation.recipe.json`, outside
+the installed catalog. It requires explicit disposable setup and reserved testnet
+account/market inputs; it is not a full action audit or a normal task recipe. Financial
 transitions must use an explicitly funded leaf action.
-The shared `perps.clean-market-testnet` convergence recipe is therefore Mobile-
-only: Extension discovery omits it and a direct Extension plan fails statically.
+The Perps team library owns `perps.clean-market-testnet` for Mobile and Core,
+not Extension. Register that library before discovery or execution.
+They require explicit `account`, `market` and `exclusive_testnet_market=true`.
+That confirmation does not reserve the market or authorize deleting someone
+else's trades. Plan first and execute only with actual task ownership.
 Planning or calling a recipe never weakens those gates.
 
+### Mobile advanced-order setup
+
+These recipes belong to the Perps team library. Register it once:
+
+```sh
+export RECIPE_LIBRARY_PATH="perps=/path/to/experimental-metamask-recipe-perps"
+```
+
+`perps.pro-order-setup` preserves existing orders, positions, and strategies by
+default. Its Scale, Chase, and TWAP placement callers inherit that policy.
+When a proof requires a clean testnet market, reserve the account/market and
+compose explicit setup with `trading_state=clean_selected_testnet_market`.
+This parameter never authorizes cleanup of another task's trades.
+
+`perps.scale-assert-orders` checks the complete market order count before
+capturing three visible rows. The generic `assert_output` action compares a
+prior node's structured field, for example `$.matchingCount` with `eq` and
+`{{params.orders}}`; it is not limited to command output. Count and visibility
+still need task-owned submission IDs to prove a specific ladder.
+
+### Fixed and Max quotes
+
+`swap-bridge.release-quote` uses one graph for both amount modes. It defaults to
+a fixed 0.0001 ETH-to-WETH quote on Ethereum with a 60-second transition budget.
+Max ignores `amount` and uses the selected asset's available balance. Neither
+mode submits a transaction.
+
+```sh
+mm-harness run swap-bridge.release-quote amount=0.0001
+mm-harness run swap-bridge.release-quote amount_mode=max
+```
+
+Set `capture_path` to a distinct filename when composing multiple quotes in
+one run. Pair, chain, asset identity, and timeout inputs remain explicit options.
+
 ### Extension submission boundary
 
-Extension currently exposes read-only Assets and Swap/Bridge evidence plus send
+Extension currently exposes non-submitting Assets and Swap/Bridge evidence plus send
 preparation/review, quote, Max, and slippage actions. It does not expose
 `metamask.assets.finish_send`, `metamask.swap_bridge.submit_transaction`, or
 generic `ui.activate_and_observe`. Those operations remain unavailable until a
@@ -178,12 +260,13 @@ as supporting stills.
 
 ### Perps loading lifecycle validation
 
-One platform-neutral recipe owns the reusable Perps lifecycle proof. The
-harness adapter supplies Android or iOS behavior; the graph and lifecycle
-parameters remain identical. Run it with an explicit device pin:
+The Mobile loading recipe shares one graph across Android and iOS. It requires
+the product's source-dev instrumentation; platform parity still needs live
+validation. Register the Perps team library, then pin the device:
 
 ```bash
 mm-harness run perps.performance \
+  --library perps=/path/to/experimental-metamask-recipe-perps \
   --device <android-serial-or-ios-udid> \
   account=<fixture-account-name> \
   content_variant=trending \
@@ -196,10 +279,10 @@ The Mobile recipe HUD is shown by default, including during performance
 validation. Use `--hud hide` only when a specific opaque/release proof requires
 an unobstructed product surface; do not hide it merely to collect timings.
 
-Supported lifecycle values are `navigate_return`, `cold_disk_cache`,
-`cold_no_cache`, `background_short`, `background_reconnect`, `account_switch`,
-and `network_switch`. The shared graph uses an existing fixture position and
-never fabricates exchange state inside the measurement. It proves native
+Declared lifecycle values are `navigate_return`, `cold_no_cache`,
+`background_short`, `background_reconnect`, `account_switch`, and
+`network_switch`. The graph requires an existing position or an account with
+no positions or orders; it never trades to create either prerequisite. It checks native
 visible content with `ui.wait_for`, captures production `[PerpsLoadProof]` and
 WebSocket milestones, and leaves detailed TTC/DFD to the app's Sentry traces.
 It never relabels Metro, fixture, or process-start duration as TTC.
@@ -207,6 +290,12 @@ The recipe does not label a checkout as main or candidate; pin and record the
 exact checkout commit externally, then use captured source milestones to verify
 which data path actually ran.
 
+Warm return and short resume require resident-content milestones. The other
+lifecycles also require live positions, orders and account streams. Each group
+shares one capture ending, with the lifecycle and content identity preserved.
+Cold preparation clears Perps disk/controller caches and disconnects its
+channels before capture; an explicit process restart begins the proof.
+
 Rules:
 
 - Validate with `--plan` before side effects.
@@ -237,8 +326,9 @@ Locators, labels, routes, and screen structure can legitimately change, so a
 failed recipe is not by itself evidence of either recipe drift or a product
 regression.
 
-1. Reproduce the failing node and compare it with authoritative acceptance
-   criteria, product contracts, or known-good evidence.
+1. Preserve the first failure and compare it with authoritative acceptance
+   criteria, product contracts, or known-good evidence. Reproduce only after
+   confirming the action is safe to repeat.
 2. Inspect the current product surface and resolved recipe source, then classify
    the cause as product regression, recipe drift, fixture/runtime drift, or
    harness defect.
@@ -268,6 +358,23 @@ If changing a value would violate the recipe's postcondition, keep it as a
 documented recipe invariant rather than a parameter. Add a shared action only
 when repeated direct access has a stable cross-task contract.
 
+Core actions construct isolated controllers. Pass account and network into
+each action; a separate initialization node cannot prepare the next process.
+Skip setup that does no work, while retaining the independent read assertions.
+Signing requires a non-empty fixture account name. Address-only inputs support
+reads; they must not silently choose the default signing account.
+
+The Perps team library's `perps.trading-lifecycle` combines the Core long market
+and limit examples. The harness retains read-only `perps.smoke` and
+`perps.snapshot` examples; trading policy belongs to the team library.
+It requires an explicit fixture account, market, and confirmation of exclusive
+testnet ownership. Initial assertions refuse non-flat state rather than clearing
+it. Failure-path cleanup is guarded by completed initial assertions and remains
+market-scoped, so it cannot safely share that account/market with another task.
+The limit branch uses the original 30%-below-mid offset; it must prove the order
+rests rather than assume it cannot fill. These trading paths still require live
+validation with a reserved funded testnet account.
+
 The protocol is authoritative:
 <https://farmslot.io/docs/reference/recipe-protocol-v1>.
 
@@ -307,7 +414,11 @@ mm-harness run onboarding.smoke --plan
 Use `--library wallet=/path/to/library` for one command. The alias is the
 source name; without one, the directory name is used. Resolution follows the
 explicit library order, then bundled MetaMask. Adapter-specific variants are
-selected deterministically from `recipes/<adapter>/<domain>/`. Legacy
+selected deterministically from `recipes/<adapter>/<domain>/`. Identical
+cross-adapter graphs live once in `recipes/shared/<domain>/`; an adapter-specific
+variant takes precedence. Both resolve as `<domain>.<recipe>`, without a platform
+or `shared` prefix. Keep domains below `core`, `extension`, `mobile`, or `shared`.
+Legacy
 `*.<adapter>.recipe.json` paths remain readable during migration, but new and
 migrated libraries use the adapter-first layout. A file cannot declare its
 adapter through both forms. Every run records the root recipe, exact resolved

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

@@ -22,8 +22,9 @@ and trusted SHA-256. mm-harness never discovers or downloads a release.
 
 For Extension, `runtime-launch` verifies the ZIP digest and manifest version,
 extracts it safely, records archive and tree provenance, copies the exact tree
-to an isolated runtime directory, resets only the selected Chrome profile, and
-launches without building or patching the checkout.
+to an isolated runtime directory, preserves the selected Chrome profile, and
+launches without building or patching the checkout. A profile reset requires
+explicit `--reset-profile`; an ordinary launch does not apply a wallet fixture.
 
 For Android, `runtime-launch` requires one physical-device serial, verifies the
 local APK digest, package ID, version name, and version code, installs it, and

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

@@ -498,6 +498,16 @@ function registerSignerHandlers(rootMessenger, childMessenger, account) {
  * @returns { controller, projectRoot, network, accountAddress, signerAddress }.
  */
 export async function getCoreControllerWithSigner(input) {
+  const requestedName = input.node?.account_name ?? input.node?.account;
+  if (requestedName !== undefined && (
+    typeof requestedName !== 'string' || !requestedName.trim() ||
+    /^0x[0-9a-fA-F]{40}$/u.test(requestedName.trim())
+  )) {
+    throw new Error(
+      'Core signing requires a non-empty fixture account name, not an address.\n' +
+      'Next: pass account=<reserved-fixture-name>; use addresses only for read-only actions.',
+    );
+  }
   const base = await getCoreController(input);
   const { controller, messenger: childMessenger, rootMessenger, accountAddress } = base;
   if (!rootMessenger || !childMessenger) {

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

@@ -10,21 +10,14 @@ import {
   optionalParam,
 } from './_controller.mjs';
 
-// core Cancel selected live Perps open orders on HyperLiquid testnet by driving
-// the headless PerpsController.cancelOrders() through the full signing/provider
-// path (Slice 2). Mirrors close_positions.mjs: read open orders → cancel the
-// selected subset via the controller → verify the selected orders are gone.
-//
-// cancelOrders() resolves the concrete orders to cancel via the ACTIVE provider's
-// getOpenOrders() (PerpsController wires getOpenOrders: () => this.getOpenOrders()
-// into the cancel context) and then batch-cancels by symbol. We pass the selected
-// symbols; with mode=all (no explicit market) we cancel every open order.
+// Snapshot selection into exact IDs so dispatch and postcondition checks cannot
+// expand to opposite-side or newly created orders sharing a market symbol.
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function waitForOrdersAbsent(controller, accountAddress, symbols, timeoutMs) {
+async function waitForOrdersAbsent(controller, accountAddress, orderIds, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let orders = [];
   for (;;) {
@@ -32,7 +25,7 @@ async function waitForOrdersAbsent(controller, accountAddress, symbols, timeoutM
       standalone: true,
       userAddress: accountAddress,
     });
-    const remaining = orders.filter((order) => symbols.includes(symbolForItem(order)));
+    const remaining = orders.filter((order) => orderIds.includes(order.orderId));
     if (remaining.length === 0) return orders;
     if (Date.now() >= deadline) return orders;
     await sleep(1000);
@@ -79,20 +72,22 @@ export async function closeOrders(input) {
     };
   }
 
-  // Cancel by the selected symbols. cancelOrders() filters the active provider's
-  // open orders to these symbols and batch-cancels them on the exchange.
-  const result = await controller.cancelOrders({ symbols });
+  const orderIds = matching.map((order) => order.orderId);
+  if (orderIds.some((id) => typeof id !== 'string' || !id.trim()) || new Set(orderIds).size !== orderIds.length) {
+    throw new Error('Selected Core orders require unique non-empty orderId values before cancellation.\nNext: mm-harness actions metamask.perps.read_orders --adapter core --json');
+  }
+  const result = await controller.cancelOrders({ orderIds });
   const failure = cancelOrdersFailure(result);
   if (failure !== undefined) {
     throw controllerRejection({
       action: 'core cancelOrders',
-      detail: `${JSON.stringify(symbols)}: ${JSON.stringify(result)}`,
+      detail: `${JSON.stringify(orderIds)}: ${JSON.stringify(result)}`,
       code: failure,
     });
   }
 
-  const after = await waitForOrdersAbsent(controller, accountAddress, symbols, timeoutMs);
-  const stillOpen = after.filter((order) => symbols.includes(symbolForItem(order)));
+  const after = await waitForOrdersAbsent(controller, accountAddress, orderIds, timeoutMs);
+  const stillOpen = after.filter((order) => orderIds.includes(order.orderId));
   if (stillOpen.length > 0) {
     throw new Error(
       `Expected selected orders to cancel, but ${stillOpen.length} remain: ${JSON.stringify(result)}`,
@@ -109,6 +104,7 @@ export async function closeOrders(input) {
     successCount: result.successCount,
     failureCount: result.failureCount,
     symbols,
+    orderIds,
     results: result.results,
     orders: stillOpen.map(redactOrder),
     proofPath: 'perps-controller-cancelOrders',

package/library/actions/extension/assets/home-token-identity.mjs

@@ -0,0 +1,30 @@
+import { openHome } from '../ui/navigate.mjs';
+
+export async function verifyHomeIdentity(page, token, assetId, timeoutMs) {
+  try {
+    await page.clickPoint(token.point.x, token.point.y);
+    const deadline = Date.now() + timeoutMs;
+    let route;
+    while (Date.now() < deadline) {
+      const value = String(await page.evaluate('location.hash'));
+      if (value.startsWith('#/asset/')) {
+        route = value;
+        break;
+      }
+      await page.evaluate('new Promise((resolve) => setTimeout(resolve, 150))');
+    }
+    if (!route) throw new Error('The selected Home token did not expose an asset-details route.');
+    const [, , chainId, address] = route.split('/');
+    if (!/^0x[0-9a-f]+$/iu.test(chainId ?? '') || !/^0x[0-9a-f]{40}$/iu.test(address ?? '')) {
+      throw new Error('The selected Home route does not expose an ERC-20 identity.');
+    }
+    const observed = `eip155:${BigInt(chainId).toString()}/erc20:${address.toLowerCase()}`;
+    if (observed !== assetId) {
+      throw new Error(`Home asset identity ${observed} does not match ${assetId}.\nNext: select a network filter with an unambiguous matching token before continuing.`);
+    }
+    return { assetId, route, verified: true };
+  } finally {
+    await openHome(page, timeoutMs);
+    delete token.point;
+  }
+}

package/library/actions/extension/assets/import_custom_token.mjs

@@ -1,10 +1,13 @@
 import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { readWalletStateExpression } from '../wallet/state.mjs';
+import { verifyHomeIdentity } from './home-token-identity.mjs';
 
 const OPTIONS = dataTestId('asset-list-control-bar-action-button');
 const MANAGE = dataTestId('manageTokens__button');
 const ADD = dataTestId('token-management-add-custom-token-button');
 const PAGE = dataTestId('custom-token-import-page');
 const NETWORK = dataTestId('network-selector');
+const NETWORK_PICKER = dataTestId('custom-token-import-network-selector');
 const ADDRESS = dataTestId('custom-token-import-address-input');
 const SYMBOL = dataTestId('custom-token-import-symbol-input');
 const DECIMALS = dataTestId('custom-token-import-decimal-input');
@@ -33,96 +36,69 @@ async function waitFor(page, predicate, message, timeoutMs) {
   throw new Error(message);
 }
 
-async function visibleButton(page, label) {
-  const marker = `mm-harness-${Date.now()}-${Math.random().toString(16).slice(2)}`;
-  const found = await page.evaluate(`(() => {
-    const label = ${JSON.stringify(label)};
-    const marker = ${JSON.stringify(marker)};
-    for (const element of document.querySelectorAll('button')) {
-      const text = String(element.innerText || element.textContent || '').replace(/\\s+/gu, ' ').trim();
-      const style = getComputedStyle(element);
-      const rect = element.getBoundingClientRect();
-      if (text === label && style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0) {
-        element.setAttribute('data-mm-harness-target', marker);
-        return true;
-      }
-    }
-    return false;
-  })()`);
-  if (!found) throw new Error(`Visible button ${JSON.stringify(label)} was not found.`);
-  return `[data-mm-harness-target="${marker}"]`;
-}
-
-async function networkOption(page, network, chainId) {
+async function networkOption(page, chainId) {
   return page.evaluate(`(() => {
-    const network = ${JSON.stringify(network.toLowerCase())};
+    const picker = document.querySelector(${JSON.stringify(NETWORK_PICKER)});
+    if (!picker) return null;
     const chainIds = new Set(${JSON.stringify([
       String(chainId),
       `0x${chainId.toString(16)}`,
       `eip155:${chainId}`,
     ].map((value) => value.toLowerCase()))});
-    for (const element of document.querySelectorAll('[data-testid^="network-list-item-"]')) {
+    for (const element of picker.querySelectorAll('[data-testid^="network-list-item-"]')) {
       const testId = String(element.getAttribute('data-testid') || '');
       const suffix = testId.slice('network-list-item-'.length).toLowerCase();
+      if (!chainIds.has(suffix)) continue;
+      element.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+      const rect = element.getBoundingClientRect();
+      const hit = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+      if (!element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })
+        || rect.width <= 0 || rect.height <= 0 || !hit || !element.contains(hit)) continue;
       const label = String(element.innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 500);
-      if (chainIds.has(suffix) || label.toLowerCase().includes(network)) return { testId, label };
+      return { testId, label };
     }
     return null;
   })()`);
 }
 
-async function homeToken(page, symbol) {
+async function homeToken(page, symbol, verifyIdentity = false) {
   return page.evaluate(`(() => {
     const symbol = ${JSON.stringify(symbol.toLowerCase())};
+    const verifyIdentity = ${JSON.stringify(verifyIdentity)};
+    const matches = [];
     for (const row of document.querySelectorAll('[data-testid="multichain-token-list-button"]')) {
       const name = String(row.querySelector('[data-testid="multichain-token-list-item-token-name"]')?.innerText || '').replace(/\\s+/gu, ' ').trim();
       const amount = String(row.querySelector('[data-testid="multichain-token-list-item-value"]')?.innerText || '').replace(/\\s+/gu, ' ').trim();
       const observed = amount.match(/\\b([A-Za-z][A-Za-z0-9]{1,11})$/u)?.[1] || '';
-      if (observed.toLowerCase() === symbol) return { name, symbol: observed.toUpperCase(), amount };
+      const style = getComputedStyle(row);
+      const rect = row.getBoundingClientRect();
+      if (observed.toLowerCase() !== symbol || style.display === 'none' || style.visibility === 'hidden'
+        || rect.width <= 0 || rect.height <= 0) continue;
+      matches.push({ row, name, symbol: observed.toUpperCase(), amount });
     }
-    return null;
+    if (matches.length > 1) throw new Error('Visible token symbol matches multiple rows; identity is ambiguous.\\nNext: narrow the product network filter before importing.');
+    if (!matches.length) return null;
+    const { row, ...token } = matches[0];
+    if (verifyIdentity) {
+      row.scrollIntoView({ block: 'center', inline: 'nearest' });
+      const rect = row.getBoundingClientRect();
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      const hit = document.elementFromPoint(x, y);
+      if (!hit || !row.contains(hit)) throw new Error('The matching Home token is covered; identity cannot be verified.\\nNext: uncover the token row before importing.');
+      token.point = { x, y };
+    }
+    return token;
   })()`);
 }
 
-async function importedTokenIdentity(page, chainId, address, expectedSymbol) {
-  return page.evaluate(`(async () => {
-    const hooks = globalThis.stateHooks || {};
-    const root = (await hooks.getCleanAppState?.()) || hooks.store?.getState?.() || {};
-    const state = root.metamask || root;
-    const allTokens = state.allTokens;
-    const selectedAddress = String(state.selectedAddress || '').toLowerCase();
-    if (!allTokens || typeof allTokens !== 'object' || !selectedAddress) {
-      return { available: false, token: null };
-    }
-    const expectedChainId = ${JSON.stringify(chainId)};
-    const chainEntry = Object.entries(allTokens).find(([key]) => {
-      const normalized = String(key).toLowerCase();
-      const value = normalized.startsWith('eip155:')
-        ? Number(normalized.slice('eip155:'.length))
-        : normalized.startsWith('0x')
-          ? Number.parseInt(normalized.slice(2), 16)
-          : Number(normalized);
-      return value === expectedChainId;
-    });
-    const accountEntry = chainEntry && Object.entries(chainEntry[1] || {})
-      .find(([account]) => String(account).toLowerCase() === selectedAddress);
-    const tokens = Array.isArray(accountEntry?.[1]) ? accountEntry[1] : [];
-    const expectedAddress = ${JSON.stringify(address.toLowerCase())};
-    const expectedSymbol = ${JSON.stringify(expectedSymbol)};
-    const token = tokens.find((entry) => {
-      const tokenAddress = String(entry?.address || entry?.contractAddress || '').toLowerCase();
-      return tokenAddress === expectedAddress && String(entry?.symbol || '').toUpperCase() === expectedSymbol;
-    });
-    return {
-      available: true,
-      token: token ? {
-        address: String(token.address || token.contractAddress),
-        symbol: String(token.symbol),
-        decimals: token.decimals == null ? null : String(token.decimals),
-        chainId: chainEntry?.[0] || null,
-      } : null,
-    };
-  })()`, { awaitPromise: true });
+async function selectedEvmAccount(page) {
+  const { selectedAccount } = await page.evaluate(readWalletStateExpression(), { awaitPromise: true });
+  if (!selectedAccount?.id || !['eip155:eoa', 'eip155:erc4337'].includes(selectedAccount.type)
+    || !/^0x[0-9a-f]{40}$/iu.test(selectedAccount.address ?? '')) {
+    throw new Error('The selected EVM account is unavailable; existing token identity cannot be verified.\nNext: select the intended EVM account before importing.');
+  }
+  return { id: selectedAccount.id, address: selectedAccount.address.toLowerCase(), type: selectedAccount.type };
 }
 
 runAdapter(async (input) => withExtensionPage(input, async (page) => {
@@ -136,39 +112,44 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
     throw new Error('metamask.assets.import_custom_token requires network, positive chain_id, ERC-20 address, and expected_symbol.');
   }
 
-  const existingToken = await homeToken(page, expectedSymbol);
-  const existingIdentity = existingToken
-    ? await importedTokenIdentity(page, chainId, address, expectedSymbol)
-    : null;
-  if (existingToken && existingIdentity?.token) {
+  const account = await selectedEvmAccount(page);
+  const existingToken = await homeToken(page, expectedSymbol, true);
+  if (existingToken) {
+    const existingIdentity = await verifyHomeIdentity(
+      page, existingToken, `eip155:${chainId}/erc20:${address.toLowerCase()}`, timeoutMs,
+    );
+    const afterAccount = await selectedEvmAccount(page);
+    if (JSON.stringify(afterAccount) !== JSON.stringify(account)) {
+      throw new Error('The selected EVM account changed while checking the existing token.\nNext: keep the intended account selected for the full import check.');
+    }
     return {
       action: input.action,
       network,
       chainId,
       address,
       alreadyImported: true,
+      changed: false,
       token: existingToken,
-      identity: existingIdentity.token,
+      identity: { ...existingIdentity, account, address, symbol: expectedSymbol, decimals: null, chainId: `0x${chainId.toString(16)}` },
       proofPath: 'trusted-pointer-visible-ui',
     };
   }
 
   if (!(await visible(page, MANAGE))) await page.click(OPTIONS);
   await waitFor(page, () => visible(page, MANAGE), 'Manage tokens did not become visible.', timeoutMs);
-  await page.click(await visibleButton(page, 'Manage tokens'));
+  await page.click(MANAGE);
   await waitFor(page, () => visible(page, ADD), 'Add a custom token did not become visible.', timeoutMs);
-  await page.click(await visibleButton(page, 'Add a custom token'));
+  await page.click(ADD);
   await waitFor(page, () => visible(page, PAGE), 'Custom token import did not open.', timeoutMs);
   await page.click(NETWORK);
   const selectedNetwork = await waitFor(
     page,
-    () => networkOption(page, network, chainId),
+    () => networkOption(page, chainId),
     `${network} (${chainId}) was not available in the custom token network selector.`,
     timeoutMs,
   );
-  await page.click(dataTestId(selectedNetwork.testId));
-  await waitFor(page, () => visible(page, ADDRESS), 'Custom token address input did not become visible.', timeoutMs);
-  await page.evaluate('new Promise((resolve) => setTimeout(resolve, 2000))');
+  await page.click(`${NETWORK_PICKER} ${dataTestId(selectedNetwork.testId)}`);
+  await waitFor(page, async () => !(await visible(page, NETWORK_PICKER)) && await visible(page, ADDRESS), 'Custom token network selection did not return to the address form.', timeoutMs);
   await page.setInput(ADDRESS, address);
 
   let metadataSource = 'network';
@@ -183,7 +164,7 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
       return state.symbol && state.enabled ? state : null;
     }, 'Custom token metadata did not resolve to an enabled import.', Math.min(timeoutMs, 15_000));
   } catch (error) {
-    if (expectedDecimals === null) throw error;
+    if (expectedDecimals === null || !(await visible(page, SYMBOL)) || !(await visible(page, DECIMALS))) throw error;
     metadataSource = 'manual';
     await page.setInput(SYMBOL, expectedSymbol);
     await page.setInput(DECIMALS, expectedDecimals);
@@ -216,6 +197,7 @@ runAdapter(async (input) => withExtensionPage(input, async (page) => {
 
   return {
     action: input.action,
+    changed: true,
     network: selectedNetwork.label || network,
     chainId,
     address,