@deeeed/metamask-harness 0.89.0 → 0.91.0

package/dist/doctor.js

@@ -1,11 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import { RECIPE_CLI_VERSION } from "@farmslot/recipe-cli";
-import { color, harnessContext, harnessContextField, harnessExecutable, recipeHarnessRoot, recipeRuntimeDir, readRuntimeContextField, resolveRuntimeContextPath } from "@farmslot/recipe-cli/harness";
+import { color, createDoctorReport as sharedDoctorReport, harnessContext, recipeHarnessRoot, recipeRuntimeDir, readRuntimeContextField, resolveRuntimeContextPath, runnerInstallKind as sharedInstallKind, runnerProvenance as sharedProvenance } from "@farmslot/recipe-cli/harness";
 import { normalizeFeatureFlagRecord } from "./feature-flags.js";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { isPin } from "./harness-pin.js";
-import { readJson, runnerDir } from "./paths.js";
+import { readJson } from "./paths.js";
 function requiredDoctorCheckSummary(checks) {
   const required = checks.filter((check) => check.required);
   const failed = required.filter((check) => check.status === "fail").map((check) => check.id);
@@ -139,99 +138,40 @@ function renderRuntimeContext(runtimeContext) {
   }
   return lines.join("\n");
 }
-function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = getAdapterSurface(adapter).actions.manifestPath(), platform) {
-  const readiness = getAdapterSurface(adapter).readiness;
-  const mode = compatibilityMode(adapter, target);
-  const manifestErrors = Number(manifestValidation.summary?.errors ?? 0);
-  const checks = [
-    {
-      id: "manifest",
-      status: manifestErrors === 0 ? "pass" : "fail",
-      required: true,
-      message: manifestErrors === 0 ? "Action manifest is valid Recipe v1." : `Action manifest has ${manifestErrors} validation error(s).`
-    },
-    {
+const doctorReportOptions = {
+  provenance: { name: "@metamask/recipe-runner", pinned: isPin },
+  checks(target, adapter) {
+    const mode = compatibilityMode(adapter, target);
+    return [{
       id: "bridge",
       status: mode === "unsupported/no bridge" ? "fail" : "pass",
       required: false,
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
-    },
-    ...readiness.checks?.(target, platform) ?? []
-  ];
-  const requiredChecks = requiredDoctorCheckSummary(checks);
-  return {
-    schemaVersion: 1,
-    protocolVersion: "v1",
-    runner_protocol_version: 1,
-    status: requiredChecks.status,
-    checks,
-    requiredChecks,
-    adapter,
-    target,
-    ...harnessContextField(),
-    runner: runnerProvenance(actionManifestPath),
-    compatibilityMode: mode,
+    }];
+  },
+  fields: (target, adapter, environment) => ({
+    compatibilityMode: compatibilityMode(adapter, target),
     shape: repoShape(target),
     fixture: fixtureSummary(target, adapter),
-    environment: readiness.environment?.(target) ?? {},
-    runtimeContext: runtimeContextSummary(target, adapter),
-    manifestValidation: manifestValidation.summary
-  };
+    environment,
+    runtimeContext: runtimeContextSummary(target, adapter)
+  })
+};
+function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = getAdapterSurface(adapter).actions.manifestPath(), platform) {
+  const report = sharedDoctorReport(adapter, target, manifestValidation, actionManifestPath, platform, doctorReportOptions);
+  return { ...report, runner: metaMaskProvenance(report.runner), manifestValidation: manifestValidation.summary };
 }
 function runnerInstallKind(runnerRoot, invokedPath, executablePath) {
-  if (isPin(runnerRoot)) return "pinned-install";
-  const normalizedRoot = path.normalize(runnerRoot);
-  const nodeModulesSegment = `${path.sep}node_modules${path.sep}`;
-  const globalNodeModulesSegment = `${path.sep}lib${path.sep}node_modules${path.sep}`;
-  if (normalizedRoot.includes(globalNodeModulesSegment)) return "global-install";
-  const nodeModulesIndex = normalizedRoot.lastIndexOf(nodeModulesSegment);
-  if (nodeModulesIndex >= 0) {
-    const nodeModulesRoot = normalizedRoot.slice(
-      0,
-      nodeModulesIndex + nodeModulesSegment.length - 1
-    );
-    const invoked = path.resolve(invokedPath);
-    const projectBin = `${path.join(nodeModulesRoot, ".bin")}${path.sep}`;
-    if (invoked === path.resolve(executablePath) || invoked.startsWith(projectBin)) {
-      return "project-install";
-    }
-    return "global-install";
-  }
-  if (path.resolve(invokedPath) !== path.resolve(executablePath)) return "local-link";
-  return "source-checkout";
+  return sharedInstallKind(runnerRoot, invokedPath, executablePath, isPin);
 }
 function runnerProvenance(actionManifestPath) {
-  const packagePath = path.join(runnerDir, "package.json");
-  const packageDocument = readJsonObject(packagePath);
-  const packageName = packageDocument.name;
-  const version = packageDocument.version;
-  if (packageName !== "@deeeed/metamask-harness") {
-    throw new Error(`Expected @deeeed/metamask-harness package name in ${packagePath}`);
-  }
-  if (typeof version !== "string" || !version) {
-    throw new Error(`Expected package version in ${packagePath}`);
+  return metaMaskProvenance(sharedProvenance(actionManifestPath, doctorReportOptions.provenance));
+}
+function metaMaskProvenance(provenance) {
+  if (provenance.name !== "@metamask/recipe-runner" || provenance.packageName !== "@deeeed/metamask-harness") {
+    throw new Error("Doctor provenance does not identify the MetaMask provider.");
   }
-  const executablePath = harnessExecutable();
-  const invokedPath = path.resolve(process.env.MM_HARNESS_INVOKED_AS ?? executablePath);
-  const installKind = runnerInstallKind(runnerDir, invokedPath, executablePath);
-  const packageSource = isPin(runnerDir) ? "pin" : runnerDir.includes(`${path.sep}node_modules${path.sep}`) ? "node_modules" : "source-checkout";
-  return {
-    name: "@metamask/recipe-runner",
-    packageName,
-    version,
-    runnerDir,
-    packagePath,
-    packageSource,
-    installKind,
-    linked: installKind === "local-link",
-    global: installKind === "global-install",
-    invokedPath,
-    executablePath,
-    actionManifestPath,
-    harnessPackage: "@farmslot/recipe-runner",
-    // The @farmslot/recipe-cli this harness runs on (`--version --verbose` prints it too).
-    recipeCliVersion: RECIPE_CLI_VERSION
-  };
+  return { ...provenance, name: provenance.name, packageName: provenance.packageName };
 }
 function readJsonObject(file) {
   const value = readJson(file);
@@ -243,6 +183,7 @@ function readJsonObject(file) {
 export {
   compatibilityMode,
   createDoctorReport,
+  doctorReportOptions,
   fixtureFileSummary,
   fixtureSummary,
   renderRuntimeContext,

package/dist/mm-harness-cli.js

@@ -20,7 +20,7 @@ import {
   parseArgs,
   targetPath
 } from "@farmslot/recipe-cli/harness";
-import { stopProjectCollector } from "../library/actions/shared/analytics/collector.mjs";
+import { stopOptions } from "./provider-lifecycle.js";
 import { adoptPluginAdapter, afterAdapterLoad, configuredLibrarySources } from "./adapters/plugin-surface.js";
 import { withMainnetOrderAbort } from "./adapters/perps-mainnet-cleanup.js";
 import { adapterRegistry } from "./adapters/registry.js";
@@ -70,12 +70,6 @@ const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "
 function hostVersion() {
   return JSON.parse(fs.readFileSync(path.join(harnessHost().packageRoot, "package.json"), "utf8")).version;
 }
-const stopOptions = {
-  companions: async (target) => {
-    const collector = await stopProjectCollector(target);
-    return collector.stopped && collector.pid !== null ? [{ label: "analytics collector", pid: collector.pid }] : [];
-  }
-};
 const targetDevice = (command, adapter, options) => applyDeviceTargeting(command, adapter, options, { gate: true, rerun: "" });
 const runOptions = {
   engine: metaMaskEngine,

package/dist/provider-doctor.js

@@ -0,0 +1,36 @@
+import { doctorFixtureNextActions, repairDoctorFixture, renderSkillsView, renderUpdateStatus, skillsView } from "./commands/doctor.js";
+import { farmslotReadyIndicator } from "./commands/farmslot-ready.js";
+import { updateStatus } from "./commands/update.js";
+import { doctorReportOptions, fixtureSummary } from "./doctor.js";
+import { loadActionManifest, validateManifest } from "./manifest.js";
+import { statusOptions } from "./provider-lifecycle.js";
+import { ensureRuntimeContext } from "./runtime-context.js";
+const doctorOptions = {
+  ...statusOptions,
+  manifest: async (adapter, override) => validateManifest(loadActionManifest(adapter, override)),
+  report: doctorReportOptions,
+  orphanDevServers: { field: "orphanMetros", label: "orphan Metro" },
+  advisory(target) {
+    const skills = skillsView(target);
+    const update = updateStatus();
+    return [
+      { key: "skills", value: skills, render: (out) => renderSkillsView(skills, out) },
+      { key: "update", value: update, render: (out) => renderUpdateStatus(update, out) }
+    ];
+  },
+  fix: {
+    ensureRuntimeContext,
+    repair: repairDoctorFixture,
+    nextActions: (failed, { adapter, target, scope }) => doctorFixtureNextActions(failed, fixtureSummary(target, adapter), scope),
+    userAction: (failed, retry) => failed.includes("wallet-fixture") ? `choose one wallet fixture source from nextActions, run it, then retry: ${retry}` : void 0
+  }
+};
+function configureProviderReadiness(runtime) {
+  Object.assign(runtime.readiness, {
+    readyIndicator: (devices) => farmslotReadyIndicator(runtime.id, [...devices])
+  });
+}
+export {
+  configureProviderReadiness,
+  doctorOptions
+};

package/dist/provider-lifecycle.js

@@ -0,0 +1,26 @@
+import { stopProjectCollector } from "../library/actions/shared/analytics/collector.mjs";
+import { collectCheckoutView, renderCheckoutView } from "./checkout-view.js";
+import { applyDeviceTargeting } from "./commands/device-target.js";
+import { featureFlagReport } from "./feature-flags.js";
+const statusOptions = {
+  checkoutView(target, adapter) {
+    const view = collectCheckoutView(target, adapter);
+    return { json: view, text: renderCheckoutView(view) };
+  },
+  featureFlags: { report: (overrides, detail) => featureFlagReport(overrides, detail) },
+  previewDevice: (command, adapter, options) => applyDeviceTargeting(command, adapter, options, {
+    gate: false,
+    rerun: "",
+    persistPin: false
+  })
+};
+const stopOptions = {
+  companions: async (target) => {
+    const collector = await stopProjectCollector(target);
+    return collector.stopped && collector.pid !== null ? [{ label: "analytics collector", pid: collector.pid }] : [];
+  }
+};
+export {
+  statusOptions,
+  stopOptions
+};

package/dist/provider-logs.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { EXIT, spawnScriptStreaming } from "@farmslot/recipe-cli/harness";
+import { runnerDir } from "./paths.js";
+function createLogsOptions(surface) {
+  return {
+    async compact({ target, logFile, events, mode, signal }) {
+      const result = await spawnScriptStreaming(
+        process.execPath,
+        [path.join(runnerDir, "adapters/shared/log-tui.mjs"), "tail", "--log", logFile, "--events", events, "--follow", "--mode", mode],
+        target,
+        { signal, forward: "original", capture: false }
+      );
+      return result.status === 0 ? EXIT.ok : EXIT.runtime;
+    },
+    async window({ target, logFile, signal }) {
+      surface.resolveSlotPorts(target);
+      const port = process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "default";
+      const window = `${surface.devServer.label}-${port}`;
+      const result = await spawnScriptStreaming(
+        path.join(runnerDir, "adapters/shared/open-log-window.sh"),
+        ["--window", window, "--log", logFile, "--runtime-dir", path.dirname(logFile)],
+        target,
+        { signal, forward: "stderr", capture: false }
+      );
+      return { window, logFile, exitCode: result.status === 0 ? EXIT.ok : EXIT.runtime };
+    }
+  };
+}
+export {
+  createLogsOptions
+};

package/dist/provider.js

@@ -17,6 +17,9 @@ import { getAdapterSurface } from "./adapters/surface.js";
 import { applyDeviceTargeting } from "./commands/device-target.js";
 import { metaMaskEngine } from "./engine.js";
 import { providerHost } from "./host.js";
+import { configureProviderReadiness, doctorOptions } from "./provider-doctor.js";
+import { statusOptions, stopOptions } from "./provider-lifecycle.js";
+import { createLogsOptions } from "./provider-logs.js";
 import { providerHost as providerHost2 } from "./host.js";
 import { PUBLIC_COMMANDS } from "./command-contract.js";
 async function createProvider(context) {
@@ -37,8 +40,9 @@ async function createProvider(context) {
   });
   await afterAdapterLoad();
   const runtime = getAdapterSurface(adapter);
+  configureProviderReadiness(runtime);
   const executes = isRecipeExecution(context.command, options);
-  if (executes) {
+  if (executes || context.command === "reload") {
     applyRuntimeDirOption(options);
     runtime.resolveSlotPorts(context.target.value);
     const selected = applyDeviceTargeting(context.command, adapter, {
@@ -52,6 +56,7 @@ async function createProvider(context) {
   return {
     runtime,
     engine: metaMaskEngine,
+    commandOptions: { status: statusOptions, stop: stopOptions, doctor: doctorOptions, logs: createLogsOptions(runtime) },
     ...executes ? {
       async cancel() {
         await abortRunMainnetOrders(context.target.value);

package/dist/runner.js

@@ -70,6 +70,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   const core = createStandardCoreAdapters({ actions });
   const projectOwnedOfficialActions = /* @__PURE__ */ new Set(["app.status", "app.lifecycle"]);
   const ui = createStandardUiAdapters({
+    captureHudEvidence: options.captureHudEvidence,
     actions: actions.filter((action) => !projectOwnedOfficialActions.has(action)),
     transport: createMetaMaskUiTransport(adapter, {
       createCdpWebUiTransport,

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

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import { walletFixturePath } from '../../harness-exports.mjs';
+import { normalizeSide, sideForItem } from '../../shared/perps/item-side.mjs';
 import { readFixtureAccounts } from '../../shared/wallet/fixture-accounts.mjs';
 import { createRewardsClient, rewardsApiUrl } from './_rewards.mjs';
 
@@ -597,25 +598,6 @@ export function symbolForItem(item) {
   return normalizeMarketSymbol(item?.symbol ?? item?.coin ?? '');
 }
 
-// Orders carry buy/sell sides; Position.size is signed and authoritative.
-function normalizeSide(rawSide) {
-  const side = String(rawSide ?? '').toLowerCase();
-  if (side === 'buy' || side === 'b') return 'long';
-  if (side === 'sell' || side === 'a' || side === 's') return 'short';
-  return side;
-}
-
-function sideForItem(item, itemType) {
-  if (itemType === 'position') {
-    const rawSize = item?.size ?? item?.szi;
-    if (typeof rawSize !== 'string' && typeof rawSize !== 'number') return '';
-    const size = Number(rawSize);
-    if (!Number.isFinite(size) || size === 0) return '';
-    return size > 0 ? 'long' : 'short';
-  }
-  return normalizeSide(item?.side ?? item?.direction ?? '');
-}
-
 function uniqueSymbols(symbols) {
   return Array.from(new Set(symbols.filter(Boolean)));
 }

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

@@ -1,6 +1,7 @@
 // Implement Extension Perps state reads, UI setup and funded trade operations.
 // Funded paths check runtime identity and retain mutation receipts for cleanup.
 
+import { sideForItem } from '../../shared/perps/item-side.mjs';
 import { pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
 import { readFile, writeFile } from 'node:fs/promises';
@@ -66,17 +67,6 @@ function symbolForItem(item) {
   return normalizeMarketSymbol(item?.coin ?? item?.symbol ?? '');
 }
 
-function sideForItem(item) {
-  const side = String(item?.side ?? item?.direction ?? '').toLowerCase();
-  if (side === 'buy' || side === 'b') return 'long';
-  if (side === 'sell' || side === 'a' || side === 's') return 'short';
-  if (side) return side;
-  // Positions carry no side, only a signed size (long > 0, short < 0).
-  const size = Number(item?.size ?? item?.szi);
-  if (Number.isFinite(size) && size !== 0) return size > 0 ? 'long' : 'short';
-  return side;
-}
-
 function uniqueSymbols(symbols) {
   return Array.from(new Set(symbols.filter(Boolean)));
 }

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

@@ -20,7 +20,7 @@ import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 
-import { captureActiveRecipeRecordingSnapshot, recipeHarnessPath } from '@farmslot/recipe-cli/harness';
+import { recipeHarnessPath } from '@farmslot/recipe-cli/harness';
 import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, extensionIdPath, walletFixturePath } from '../../harness-exports.mjs';
 import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
 import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
@@ -375,25 +375,9 @@ export async function captureHelperSnapshot(page, context, relPath, metadata) {
   try {
     pid = await captureHelperBrowserPid(context, page.port);
     const timeoutMs = Number(metadata?.timeoutMs ?? 30000);
-    const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(
-      pid,
-      destination.stagedPath,
-      timeoutMs,
-    );
-    if (sessionSnapshot) {
+    if (context.captureRecordingSnapshot) {
       mode = 'record_session_snapshot';
-      details = sessionSnapshot;
-    } else if (
-      parsePositivePid(process.env.METAMASK_RECIPE_EXTENSION_ACTIVE_RECORDING_PID) === pid
-    ) {
-      await cleanupEvidenceStaging(destination.stagingDir);
-      return captureCdpSnapshot(
-        page,
-        context,
-        relPath,
-        metadata,
-        'native snapshot skipped while full-run recording owns the browser window',
-      );
+      details = await context.captureRecordingSnapshot(path.relative(artifactsRoot, destination.stagedPath));
     } else {
       await reapOrphanedCaptureHelpers(context);
       const result = await runProcess(

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

@@ -46,7 +46,7 @@ function text(value) {
 function pageIntent(node) {
   const page = text(node?.page);
   if (!page) return undefined;
-  if (page === 'back' || page === 'home' || page === 'perps' || page === 'swap') return { page };
+  if (page === 'back' || page === 'home' || page === 'perps' || page === 'swap' || page === 'settings') return { page };
   if (page === 'perps-market-list' || page === 'perps-activity') return { page };
   if (page === 'network') {
     const network = text(node.network);
@@ -61,7 +61,7 @@ function pageIntent(node) {
     if (!market) throw new Error('extension ui.navigate page=perps-market requires market or symbol.');
     return { page, market };
   }
-  throw new Error('extension ui.navigate supported page intents: back, home, network, perps, perps-market-list, perps-market, perps-activity, swap.');
+  throw new Error('extension ui.navigate supported page intents: back, home, settings, network, perps, perps-market-list, perps-market, perps-activity, swap.');
 }
 
 async function goBack(page, timeoutMs) {
@@ -503,6 +503,27 @@ export async function openNetwork(page, network, chainId, addIfMissing, timeoutM
   throw new Error(`Network ${network} (${chainId}) did not become the selected wallet filter.`);
 }
 
+export async function openSettings(page, timeoutMs) {
+  const destination = dataTestId('parent-selector-settings-page');
+  if (await hasVisibleSelector(page, destination)) {
+    return { method: 'visible-ui', href: await currentHref(page), steps: [] };
+  }
+  const deadline = Date.now() + timeoutMs;
+  const menu = dataTestId('account-options-menu-button');
+  const settings = dataTestId('global-menu-settings');
+  const steps = [];
+  if (!(await hasVisibleSelector(page, settings))) {
+    await page.waitFor({ selector: menu, expected: 'visible', timeoutMs: Math.max(1, deadline - Date.now()) });
+    await activateSemanticControl(page, menu);
+    steps.push(menu);
+  }
+  await page.waitFor({ selector: settings, expected: 'visible', timeoutMs: Math.max(1, deadline - Date.now()) });
+  const navigation = await activateSemanticControl(page, settings);
+  steps.push(settings);
+  await page.waitFor({ selector: destination, expected: 'visible', timeoutMs: Math.max(1, deadline - Date.now()) });
+  return { navigation, method: 'visible-ui', href: await currentHref(page), selector: settings, steps };
+}
+
 export async function openSwap(page, timeoutMs) {
   const sourceAmount = dataTestId('from-amount');
   const sourceToken = dataTestId('bridge-source-button');
@@ -588,6 +609,10 @@ export async function navigateExtensionUi(input) {
       );
       return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
     }
+    if (intent.page === 'settings') {
+      const result = await openSettings(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
     if (intent.page === 'swap') {
       const result = await openSwap(page, timeoutMs);
       return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };

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

@@ -1,5 +1,6 @@
 // Implement Mobile Perps navigation, trading mutations, assertions, and setup or cleanup through the bridge.
 // Strategy getters used during cleanup can settle tracked collateral.
+import { sideForItem } from '../../shared/perps/item-side.mjs';
 import { pathToFileURL } from 'node:url';
 import {
   MOBILE_BRIDGE_RESULT_ERROR_CODES,
@@ -300,13 +301,6 @@ function symbolForItem(item) {
   return normalizeMarketSymbol(item?.symbol ?? item?.coin ?? '');
 }
 
-function sideForItem(item) {
-  const side = String(item?.side ?? item?.direction ?? '').toLowerCase();
-  if (side === 'buy' || side === 'b') return 'long';
-  if (side === 'sell' || side === 'a' || side === 's') return 'short';
-  return side;
-}
-
 function configuredSymbols(input, items) {
   const selector = input.node?.selector && typeof input.node.selector === 'object' ? input.node.selector : {};
   const mode = String(input.node?.mode ?? selector.mode ?? 'matching').toLowerCase();

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

@@ -53,10 +53,29 @@ const IOS_TEXT_TEST_IDS = `(() => {
 })()`;
 
 export async function observeNativeUi(payload, context) {
-  await hideAccessibilityMaskingHud(payload, context);
   const refs = Array.isArray(payload?.refs)
     ? payload.refs.filter((ref) => typeof ref === 'string')
     : [];
+  if (refs.length === 1 && refs[0] === 'ui.hud') {
+    // The HUD must stay visible for this capture-bound observation.
+    try {
+      const hierarchy = await readNativeHierarchy(payload, context, []);
+      const expected = String(payload?.node?.intent ?? '').replace(/\s+/gu, ' ').trim();
+      const intents = hierarchy.visible.items.flatMap((item) => {
+        const label = String(item.label ?? '').replace(/\s+/gu, ' ').trim();
+        const intent = hudLabelIntent(label);
+        return intent && item.visible !== false && item.bounds?.width > 0 && item.bounds?.height > 0 ? [intent] : [];
+      });
+      const intent = intents.find((value) => value === expected);
+      return { observations: { 'ui.hud': {
+        visible: Boolean(expected && intent && hierarchy.visible.truncated !== true),
+        intent: intent ?? '', provider: hierarchy.screen.provider,
+      } } };
+    } catch (error) {
+      return { warnings: [{ ref: 'ui.hud', message: error instanceof Error ? error.message : String(error) }] };
+    }
+  }
+  await hideAccessibilityMaskingHud(payload, context);
   const supported = refs.filter((ref) => ref === 'ui.screen' || ref === 'ui.visible');
   const warnings = refs
     .filter((ref) => !supported.includes(ref))
@@ -139,6 +158,10 @@ export async function hideAccessibilityMaskingHud(payload, context) {
   }
 }
 
+function hudLabelIntent(label) {
+  return /^(?:RUN|PASS|FAIL|OK)(?: \d+\/\d+)?\s+(.+)$/u.exec(text(label) ?? '')?.[1];
+}
+
 async function readNativeHierarchy(payload, context, textTestIds) {
   const node = record(payload?.node);
   const env = {
@@ -149,23 +172,24 @@ async function readNativeHierarchy(payload, context, textTestIds) {
     env.METAMASK_RECIPE_PROJECT_ROOT = String(context.projectRoot);
   }
   const platform = resolvePlatform(node, env);
+  const hudIntent = payload?.refs?.length === 1 && payload.refs[0] === 'ui.hud' ? text(node.intent) : undefined;
   const appLabel = nativeAppLabel(env);
   const hierarchy = platform === 'android'
-    ? await readAndroidHierarchy(node, env)
-    : await readIosHierarchy(node, env, textTestIds);
+    ? await readAndroidHierarchy(node, env, hudIntent, context?.signal)
+    : await readIosHierarchy(node, env, textTestIds, hudIntent, context?.signal);
   // No screen name and no labelled item: name the screen after the app.
   hierarchy.screen.name ??= appLabel;
   return hierarchy;
 }
 
-async function readIosHierarchy(node, env, textTestIds) {
+async function readIosHierarchy(node, env, textTestIds, hudIntent, signal) {
   const idbPath = resolveMobileToolPath('idb');
   if (!idbPath) {
     throw new Error(
       `iOS UI observation requires the idb client.\n  Next: ${mobileToolRecovery('idb')}`,
     );
   }
-  const udid = await resolveIosUdid(node, env);
+  const udid = await resolveIosUdid(node, env, signal);
   const { stdout } = await execFileAsync(
     idbPath,
     ['ui', 'describe-all', '--udid', udid],
@@ -174,10 +198,11 @@ async function readIosHierarchy(node, env, textTestIds) {
       timeout: 15_000,
       maxBuffer: 16 * 1024 * 1024,
       env,
+      signal,
     },
   );
   const parsed = parseJsonOutput(stdout);
-  const hierarchy = flattenIosHierarchy(parsed, textTestIds);
+  const hierarchy = flattenIosHierarchy(parsed, textTestIds, hudIntent);
   if (hierarchy.nodeCount === 0) {
     throw new Error('idb returned an empty accessibility hierarchy.');
   }
@@ -191,15 +216,16 @@ async function readIosHierarchy(node, env, textTestIds) {
   );
 }
 
-async function readAndroidHierarchy(node, env) {
+async function readAndroidHierarchy(node, env, hudIntent, signal) {
   const adbPath = resolveMobileToolPath('adb');
   if (!adbPath) {
     throw new Error(
       `Android UI observation requires Android SDK Platform-Tools.\n  Next: ${mobileToolRecovery('adb')}`,
     );
   }
-  const serial = await resolveAndroidSerial(adbPath, node, env);
+  const serial = await resolveAndroidSerial(adbPath, node, env, signal);
   if (isOpaqueRuntime(env)) {
+    if (hudIntent) throw new Error('An opaque runtime has no observable HUD.');
     return readAndroidAgentDeviceHierarchy(serial, env);
   }
   const { stdout } = await execFileAsync(
@@ -210,10 +236,12 @@ async function readAndroidHierarchy(node, env) {
       timeout: 15_000,
       maxBuffer: 16 * 1024 * 1024,
       env,
+      signal,
     },
   );
-  const hierarchy = parseAndroidHierarchy(stdout);
+  const hierarchy = parseAndroidHierarchy(stdout, hudIntent);
   if (hierarchy.nodeCount === 0) {
+    if (hudIntent) throw new Error('The native HUD hierarchy is empty.');
     return readAndroidAgentDeviceHierarchy(serial, env);
   }
   return normalizedHierarchy(
@@ -338,7 +366,7 @@ function normalizedHierarchy(
   };
 }
 
-async function resolveIosUdid(node, env) {
+async function resolveIosUdid(node, env, signal) {
   const requested = text(node.simulator) ?? text(node.ios_simulator) ??
     text(env.SIM_UDID) ?? text(env.IOS_SIMULATOR) ?? 'booted';
   if (/^[0-9a-f-]{36}$/iu.test(requested)) return requested;
@@ -350,6 +378,7 @@ async function resolveIosUdid(node, env) {
       timeout: 5_000,
       maxBuffer: 4 * 1024 * 1024,
       env,
+      signal,
     },
   );
   const parsed = JSON.parse(stdout);
@@ -368,7 +397,7 @@ async function resolveIosUdid(node, env) {
   return udid;
 }
 
-async function resolveAndroidSerial(adbPath, node, env) {
+async function resolveAndroidSerial(adbPath, node, env, signal) {
   const explicit = text(node.adb_serial) ?? text(node.android_serial) ??
     text(env.ADB_SERIAL) ?? text(env.ANDROID_SERIAL);
   if (explicit) return explicit;
@@ -377,6 +406,7 @@ async function resolveAndroidSerial(adbPath, node, env) {
     timeout: 5_000,
     maxBuffer: 4 * 1024 * 1024,
     env,
+    signal,
   });
   const serials = stdout
     .split(/\r?\n/u)
@@ -418,7 +448,7 @@ function parseJsonOutput(output) {
   }
 }
 
-function flattenIosHierarchy(value, textTestIds = []) {
+function flattenIosHierarchy(value, textTestIds = [], hudIntent) {
   const texts = (Array.isArray(textTestIds) ? textTestIds : []).map((entry) => ({
     testId: text(entry?.testId),
     label: text(entry?.label),
@@ -449,7 +479,7 @@ function flattenIosHierarchy(value, textTestIds = []) {
       screenName ??= label;
       screenBounds ??= bounds;
     }
-    if (isActionableRole(role) || testId) {
+    if (isActionableRole(role) || testId || (hudIntent && hudLabelIntent(label) === hudIntent)) {
       const normalized = compactItem({
         role,
         label,
@@ -473,7 +503,7 @@ function flattenIosHierarchy(value, textTestIds = []) {
   return { visible, hidden, nodeCount, screenName };
 }
 
-function parseAndroidHierarchy(output) {
+function parseAndroidHierarchy(output, hudIntent) {
   const xmlStart = Math.max(output.indexOf('<?xml'), output.indexOf('<hierarchy'));
   const xml = xmlStart >= 0 ? output.slice(xmlStart) : output;
   const visible = [];
@@ -514,7 +544,7 @@ function parseAndroidHierarchy(output) {
       isActionableRole(role) ||
       attributes.clickable === 'true' ||
       attributes['long-clickable'] === 'true';
-    if (isActionable || item.test_id) {
+    if (isActionable || item.test_id || (hudIntent && hudLabelIntent(label) === hudIntent)) {
       if (isVisible) {
         visible.push(item);
       } else {