@deeeed/metamask-harness 0.83.0 → 0.85.0

package/library/actions/web-dapp/platform/page.mjs

@@ -7,11 +7,10 @@
 // so it stays the window's active tab and keeps painting without it.
 
 import { isAppUrl } from '@farmslot/adapter-web/origin';
+import { cdpListenerPids } from '@farmslot/adapter-web/web-dapp';
 
-import { resolveSlowMo } from '../../../../adapters/web-dapp/lib/display.mjs';
-import { HUD_ELEMENT } from '../../../../adapters/web-dapp/lib/hud.mjs';
-import { cdpListenerPids } from '../../../../adapters/web-dapp/lib/processes.mjs';
-import { appOrigin, cdpPort, readBrowserState } from './runtime.mjs';
+import { readHudState, resolveSlowMo } from './adapter-web-lib.mjs';
+import { appOrigin, cdpPort, readBrowserState, webDappRuntimeDir } from './runtime.mjs';
 import { importRecipeHarnessRuntimeCdp } from '../../harness-exports.mjs';
 
 const { CdpSession, CdpWebPage, listCdpTargets, sleep } = await importRecipeHarnessRuntimeCdp();
@@ -73,32 +72,78 @@ export async function selectAppTarget(input) {
 // MetaMask pages run under LavaMoat scuttling, so main-world helpers (timers in
 // wait loops) are unavailable there; evaluate in an isolated world that shares
 // the DOM instead.
+//
+// A wallet screenshot carries the running recipe's HUD too: hud.json's current
+// step is drawn on the MetaMask page for the capture only, then removed. A
+// finished or absent state (--hud hide) draws nothing.
 class WalletSurfacePage extends CdpWebPage {
   evaluate(expression) {
     return this.evaluateInIsolatedWorld(expression, 'web-dapp-wallet-surface');
   }
-}
 
-// Number inputs ignore select(), so the generic setInput would append to a
-// prefilled value (the order form prefills the mid price). Clear the field with
-// the editor's selectAll command, as a user's Cmd+A would, type over the
-// selection and require the field to read back exactly that value.
-// Screenshots are evidence of the app, so the recipe HUD is hidden while one
-// is captured and shown again afterwards.
-export function hudVisibilityExpression(visible) {
-  return `(() => { const host = document.documentElement.querySelector(':scope > ${HUD_ELEMENT}'); if (!host) return false; host.style.visibility = ${JSON.stringify(visible ? '' : 'hidden')}; return true; })()`;
-}
-
-class AppPage extends CdpWebPage {
   async screenshot(context, relPath, metadata = {}) {
-    const hidden = await this.evaluate(hudVisibilityExpression(false)).catch(() => false);
+    const state = context?.projectRoot ? readHudState(webDappRuntimeDir(context.projectRoot)) : null;
+    const drawn = state?.current && !state.finished
+      ? await this.evaluate(walletHudExpression(state)).then((result) => result?.hud === true, () => false)
+      : false;
     try {
       return await super.screenshot(context, relPath, metadata);
     } finally {
-      if (hidden) await this.evaluate(hudVisibilityExpression(true)).catch(() => {});
+      if (drawn) await this.evaluate(walletHudExpression(null)).catch(() => {});
     }
   }
+}
 
+// The wallet-page HUD: a bar docked to the bottom edge that reserves its own
+// height (a spacer after the content and the body's bottom padding), as the
+// Extension's HUD does on MetaMask pages, so the request and its footer
+// buttons move up instead of being covered. Inert, aria-hidden, pointer-events
+// none. null removes it and restores the body padding.
+export const WALLET_HUD_ID = 'mm-harness-wallet-hud';
+
+export function walletHudExpression(state) {
+  const progress = state?.current?.progress;
+  const view = state ? {
+    badge: ['RUN', progress ? `${progress.current}/${progress.total}` : ''].filter(Boolean).join(' '),
+    intent: String(state.current?.intent ?? ''),
+  } : null;
+  return `(() => {
+    const view = ${JSON.stringify(view)};
+    const id = ${JSON.stringify(WALLET_HUD_ID)};
+    const old = document.getElementById(id);
+    if (old) {
+      document.body.style.paddingBottom = old.dataset.previousPadding || '';
+      old.remove();
+      document.getElementById(id + '-space')?.remove();
+    }
+    if (!view) return { hud: false, cleared: Boolean(old) };
+    const bar = document.createElement('div');
+    bar.id = id;
+    bar.setAttribute('aria-hidden', 'true');
+    bar.inert = true;
+    bar.dataset.previousPadding = document.body.style.paddingBottom;
+    Object.assign(bar.style, { position: 'fixed', left: '0', right: '0', bottom: '0', zIndex: '2147483647', pointerEvents: 'none', boxSizing: 'border-box', padding: '5px 8px', background: 'rgba(8, 10, 14, 0.9)', color: '#fff', font: '600 11px/1.3 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif', borderTop: '1px solid rgba(255,255,255,0.14)' });
+    const badge = document.createElement('span');
+    Object.assign(badge.style, { color: '#8ab4ff', fontSize: '9px', fontWeight: '800', marginRight: '6px' });
+    badge.textContent = view.badge;
+    bar.append(badge, view.intent);
+    document.body.append(bar);
+    const height = Math.ceil(bar.getBoundingClientRect().height);
+    const space = document.createElement('div');
+    space.id = id + '-space';
+    space.setAttribute('aria-hidden', 'true');
+    Object.assign(space.style, { display: 'block', height: height + 'px', pointerEvents: 'none' });
+    document.body.insertBefore(space, bar);
+    document.body.style.paddingBottom = height + 'px';
+    return { hud: true, docked: true, height };
+  })()`;
+}
+
+// Number inputs ignore select(), so the generic setInput would append to a
+// prefilled value (the order form prefills the mid price). Clear the field with
+// the editor's selectAll command, as a user's Cmd+A would, type over the
+// selection and require the field to read back exactly that value.
+class AppPage extends CdpWebPage {
   // A tab whose first load is still pending (a slow dev-server compile) has no
   // committed history entry yet; navigating away from it is still fine.
   async currentNavigationUrl() {

package/library/actions/web-dapp/platform/runtime.mjs

@@ -1,186 +1,37 @@
 // Resolve the web-dapp slot runtime: the venue policy, ports, runtime paths,
-// browser state and wallet-fixture accounts. Key material is only ever
-// returned as a viem account object; callers must never log or persist it.
+// browser state and wallet-fixture accounts, from @farmslot/adapter-web; plus
+// the live-action plumbing (input, direct run, output). Key material is only
+// ever returned as a viem account object; callers must never log or persist it.
 
-import { realpathSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
-
-import { recipeRuntimeDir } from '@farmslot/recipe-cli/harness';
-import { walletFixturePath } from '../../harness-exports.mjs';
-import { POLICY_ENV, webDappAdapterId, webDappPolicy } from '../../../../adapters/web-dapp/lib/policy.mjs';
-
-export { POLICY_ENV, webDappAdapterId, webDappPolicy };
-
-export const SIGNER_MODES = Object.freeze(['extension', 'injected']);
-export const DEFAULT_ACCOUNT = 'dev1';
-
-// The checkout's canonical path: a symlinked or /tmp-vs-/private/tmp spelling
-// of the same slot must name the same runtime dir, profile and pid owners.
-export function canonicalPath(target) {
-  const resolved = path.resolve(target);
-  try {
-    return realpathSync(resolved);
-  } catch {
-    return resolved;
-  }
-}
-
-// <checkout>/<runtime>/<adapter id>, e.g. temp/recipe/runtime/terminal.
-export function webDappRuntimeDir(projectRoot) {
-  return path.join(canonicalPath(projectRoot), recipeRuntimeDir(), webDappPolicy().adapterId);
-}
-
-export function webDappRuntimePath(projectRoot, ...segments) {
-  return path.join(webDappRuntimeDir(projectRoot), ...segments);
-}
-
-function portFrom(raw, label) {
-  if (raw === undefined || raw === null || raw === '') return undefined;
-  const port = Number(raw);
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw new Error(`${label} must be a TCP port, got ${JSON.stringify(raw)}.`);
-  }
-  return port;
-}
-
-// The slot's Next.js dev server. Farmslot passes it as --watcher-port {{port}};
-// TERMINAL_APP_PORT is the explicit override.
-export function appPort(input = {}, env = process.env) {
-  const port =
-    portFrom(input.node?.app_port, 'app_port') ??
-    portFrom(env.TERMINAL_APP_PORT, 'TERMINAL_APP_PORT') ??
-    portFrom(env.RECIPE_WATCHER_PORT, 'RECIPE_WATCHER_PORT') ??
-    portFrom(env.WATCHER_PORT, 'WATCHER_PORT');
-  if (!port) {
-    throw new Error(
-      `${webDappPolicy().adapterId} adapter requires the slot dev-server port.\n` +
-      'Next: pass --watcher-port <port> (Farmslot: {{port}}) or set TERMINAL_APP_PORT.',
-    );
-  }
-  return port;
-}
-
-export function appOrigin(input = {}, env = process.env) {
-  return `http://localhost:${appPort(input, env)}`;
-}
-
-export function cdpPort(input = {}, env = process.env) {
-  const port =
-    portFrom(input.node?.cdp_port, 'cdp_port') ??
-    portFrom(env.RECIPE_CDP_PORT, 'RECIPE_CDP_PORT') ??
-    portFrom(env.CDP_PORT, 'CDP_PORT');
-  if (!port) {
-    throw new Error(
-      `${webDappPolicy().adapterId} adapter requires a per-slot browser CDP port.\n` +
-      'Next: pass --cdp-port <port> (Farmslot: {{cdp_port}}).',
-    );
-  }
-  return port;
-}
-
-export async function readJsonFile(file) {
-  try {
-    return JSON.parse(await readFile(file, 'utf8'));
-  } catch (error) {
-    if (error?.code === 'ENOENT') return null;
-    throw error;
-  }
-}
-
-export async function writePrivateJson(file, value) {
-  await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-}
-
-export async function readBrowserState(projectRoot) {
-  return readJsonFile(webDappRuntimePath(projectRoot, 'browser.json'));
-}
-
-export function resolveSigner(raw) {
-  const signer = raw == null || raw === '' ? 'extension' : String(raw);
-  if (!SIGNER_MODES.includes(signer)) {
-    throw new Error(`signer must be one of ${SIGNER_MODES.join(' | ')}, got ${JSON.stringify(raw)}.`);
-  }
-  return signer;
-}
-
-// Account name precedence: node.account_name → node.account (when not an
-// address) → the running browser's account → dev1.
-export function accountName(input = {}, browserState = null) {
-  const explicit = input.node?.account_name ?? input.node?.account;
-  if (typeof explicit === 'string' && explicit.trim() && !/^0x[0-9a-fA-F]{40}$/u.test(explicit.trim())) {
-    return explicit.trim();
-  }
-  return browserState?.account?.name ?? DEFAULT_ACCOUNT;
-}
-
-export function fixturePath(projectRoot, env = process.env) {
-  return env.RECIPE_WALLET_FIXTURE ? path.resolve(env.RECIPE_WALLET_FIXTURE) : walletFixturePath(projectRoot);
-}
-
-export async function loadWalletFixture(projectRoot, env = process.env) {
-  const file = fixturePath(projectRoot, env);
-  const fixture = await readJsonFile(file);
-  if (!fixture) {
-    throw new Error(
-      `wallet fixture not found at ${file}.\n` +
-      `Next: mm-harness install --adapter ${webDappPolicy().adapterId} --target <checkout> with RECIPE_WALLET_FIXTURE set, or copy the fixture there (0600).`,
-    );
-  }
-  if (!Array.isArray(fixture.accounts) || fixture.accounts.length === 0) {
-    throw new Error(`wallet fixture at ${file} has no accounts.`);
-  }
-  return { file, fixture };
-}
-
-export function fixtureEntry(fixture, name) {
-  const entry = fixture.accounts.find((account) => account?.name === name);
-  if (!entry) {
-    const names = fixture.accounts.map((account) => account?.name).filter(Boolean).join(', ');
-    throw new Error(`wallet fixture has no account named "${name}". Available: ${names}.`);
-  }
-  if (entry.type !== 'mnemonic' && entry.type !== 'privateKey') {
-    throw new Error(`wallet fixture account "${name}" must be mnemonic or privateKey, got "${entry.type}".`);
-  }
-  if (typeof entry.value !== 'string' || !entry.value.trim()) {
-    throw new Error(`wallet fixture account "${name}" has no value.`);
-  }
-  return entry;
-}
-
-// Mnemonics use BIP-44 index 0, the MetaMask default and the derivation the
-// Extension fixture flow imports.
-export function viemAccountFromEntry(entry) {
-  if (entry.type === 'mnemonic') return mnemonicToAccount(entry.value.trim(), { addressIndex: 0 });
-  const raw = entry.value.trim();
-  const key = raw.startsWith('0x') ? raw : `0x${raw}`;
-  if (!/^0x[0-9a-fA-F]{64}$/u.test(key)) {
-    throw new Error(`wallet fixture privateKey account "${entry.name}" is not a 32-byte hex key.`);
-  }
-  return privateKeyToAccount(key);
-}
-
-export async function fixtureAccount(projectRoot, name, env = process.env) {
-  const { fixture } = await loadWalletFixture(projectRoot, env);
-  return viemAccountFromEntry(fixtureEntry(fixture, name));
-}
-
-// Address-only view of the account a node targets: an explicit address wins
-// (read-only use), otherwise the fixture account is derived.
-export async function resolveAccountAddress(input, env = process.env) {
-  const raw = input.node?.account;
-  if (typeof raw === 'string' && /^0x[0-9a-fA-F]{40}$/u.test(raw.trim())) {
-    return { name: null, address: raw.trim() };
-  }
-  const projectRoot = input.context?.projectRoot;
-  const browserState = projectRoot ? await readBrowserState(projectRoot) : null;
-  const name = accountName(input, browserState);
-  const account = await fixtureAccount(projectRoot, name, env);
-  return { name, address: account.address };
-}
+import { webDappAdapterId } from '@farmslot/adapter-web/web-dapp';
+
+export {
+  accountName,
+  appOrigin,
+  appPort,
+  canonicalPath,
+  cdpPort,
+  DEFAULT_ACCOUNT,
+  fixtureAccount,
+  fixtureEntry,
+  fixturePath,
+  loadWalletFixture,
+  POLICY_ENV,
+  readBrowserState,
+  readJsonFile,
+  resolveAccountAddress,
+  resolveSigner,
+  SIGNER_MODES,
+  viemAccountFromEntry,
+  webDappAdapterId,
+  webDappPolicy,
+  webDappRuntimeDir,
+  webDappRuntimePath,
+  writePrivateJson,
+} from '@farmslot/adapter-web/web-dapp';
 
 export async function loadInput() {
   const inputPath = process.argv[2] || process.env.METAMASK_RECIPE_ADAPTER_INPUT;
@@ -199,7 +50,7 @@ export async function runAdapter(callback) {
     const output = await callback(input);
     await writeFile(input.outputPath, `${JSON.stringify(output, null, 2)}\n`);
   } catch (error) {
-    process.stderr.write(`[${webDappAdapterId()}] ${input.action} failed: ${error?.stack ?? error}\n`);
+    process.stderr.write(`[${webDappAdapterId()}] ${input.action} failed: ${error?.verdict ? error.message : error?.stack ?? error}\n`);
     process.exitCode = 1;
   }
 }

package/library/diagnostics/console-allowlist.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 3,
+  "entries": [
+    {
+      "signature": "Warning: Using UNSAFE_componentWillMount in strict mode is not recommended and may indicate bugs in your code. See https://reactjs.org/link/unsafe-component-lifecycles for details.",
+      "continuation": "* Move code with side effects to componentDidMount, and set initial state in the constructor.\nPlease update the following components: %s UnlockPageBase",
+      "first_frame": "chrome-extension://<extension>/vendor-node_modules_ra.js",
+      "source": "extension",
+      "reason": "React warns once per load that the Extension unlock page (UnlockPageBase) still uses UNSAFE_componentWillMount. Reproduced on unchanged main (metamask-extension a6765b12, macpro-mme-5, same wallet fixture and selected account as the feature slot).",
+      "link": "https://github.com/MetaMask/metamask-extension/blob/main/ui/pages/unlock-page/unlock-page.component.tsx"
+    }
+  ]
+}

package/library/manifests/extension.action-manifest.json

@@ -1237,6 +1237,42 @@
       },
       "execution_capabilities": []
     },
+    "metamask.app.assert_no_console_errors": {
+      "description": "Fail when MetaMask (service worker or UI pages) logged an error or uncaught exception that no console allowlist (the bundled library's, then each recipe library's diagnostics/console-allowlist.json) marks as known noise, judging the events since the launch began, by their own timestamps. Reads extension-console.log from the offset mm-harness launch records when it starts, and leaves out records the collector stamps with an event time before the launch (a replaced collector's replay of a browser the launch kept); with no recorded launch it fails unless since is start-of-log. The same classification feeds run diagnostics. Fails as unavailable unless this runtime's console collector runs on the run's CDP port and a control line logged in MetaMask's service worker or page reaches extension-console.log. Allowlist entries are exact signatures (schemaVersion 3).",
+      "execution_capabilities": ["host-read-export"],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "levels": {
+            "type": "array",
+            "items": { "type": "string", "enum": ["error", "exception", "warning"] },
+            "description": "Default [\"error\",\"exception\"]."
+          },
+          "since": {
+            "type": "string",
+            "enum": ["launch", "start-of-log"],
+            "default": "launch"
+          },
+          "allowlist_root": {
+            "type": "string",
+            "description": "An extra directory holding diagnostics/console-allowlist.json."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds to wait for the capture control line (default 8000)."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.app.assert_no_console_errors",
+          "intent": "Prove MetaMask logged no unexpected error since launch",
+          "next": "done"
+        }
+      ]
+    },
     "app.network_assert": {
       "description": "Assert a previously indexed app.network_capture summary without hiding its diagnostics on failure.",
       "examples": [

package/library/manifests/mobile.action-manifest.json

@@ -1260,6 +1260,42 @@
       },
       "execution_capabilities": []
     },
+    "metamask.app.assert_no_console_errors": {
+      "description": "Fail when the app logged an error or uncaught exception that no console allowlist (the bundled library's, then each recipe library's diagnostics/console-allowlist.json) marks as known noise, judging the events since the launch began, by their own timestamps. Reads app-console.log from the adapter-rn console forwarder, which stamps each line with the event's own time: mm-harness launch records when it starts, and lines a reused app runtime replays from before then are left out; with no recorded launch it fails unless since is start-of-log. Only the device the bridge selects for the run (the one the control line comes back from) is judged; when that line names no device, every device is, reported as devices: \"all\". The same classification feeds run diagnostics. Fails as unavailable unless this checkout's forwarder is running and a control line logged inside the app through the debug bridge reaches app-console.log; the opaque release runtime has no bridge and always fails as unavailable. Allowlist entries are exact signatures (schemaVersion 3).",
+      "execution_capabilities": ["host-read-export"],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "levels": {
+            "type": "array",
+            "items": { "type": "string", "enum": ["error", "exception", "warning"] },
+            "description": "Default [\"error\",\"exception\"]."
+          },
+          "since": {
+            "type": "string",
+            "enum": ["launch", "start-of-log"],
+            "default": "launch"
+          },
+          "allowlist_root": {
+            "type": "string",
+            "description": "An extra directory holding diagnostics/console-allowlist.json."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds to wait for the capture control line (default 8000)."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.app.assert_no_console_errors",
+          "intent": "Prove the app logged no unexpected error since launch",
+          "next": "done"
+        }
+      ]
+    },
     "app.network_assert": {
       "description": "Assert a previously indexed app.network_capture summary without hiding its diagnostics on failure.",
       "examples": [

package/library/manifests/web-dapp.action-manifest.json

@@ -17,7 +17,7 @@
       }
     },
     "app.hud": {
-      "description": "Display recipe progress in an overlay on the app tab: recipe, step N/M, the current node intent and the last pass/fail. Never drawn in MetaMask's own pages; ignored by clicks and page text. --hud auto shows it only when the browser is headful.",
+      "description": "Display recipe progress in an overlay on the app tab: recipe, step N/M, the current node intent and the last pass/fail. Drawn on a MetaMask wallet page only for the length of a surface=wallet ui.screenshot; ignored by clicks and page text; kept in every ui.screenshot. Drawn in a headless or headful browser unless --hud hide, which also clears the HUD an earlier run left.",
       "examples": [
         {
           "action": "app.hud",

package/library/recipes/core/health/check.recipe.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "MetaMask Core health check",
+  "description": "Read-only check to run before ticket work: the headless Perps controller imports and answers one bounded HyperLiquid testnet account read. A failed precondition stops at the node named after its error; that node's intent gives the recovery. Places no orders.",
+  "paramsSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "timeout_ms": { "type": "integer", "minimum": 1000, "default": 60000 }
+    }
+  },
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": {
+        "action": "app.status",
+        "next": "CONTROLLER_UNAVAILABLE",
+        "intent": "Record the resolved Core checkout"
+      },
+      "CONTROLLER_UNAVAILABLE": {
+        "action": "metamask.perps.read_account",
+        "network": "testnet",
+        "timeout_ms": "{{params.timeout_ms}}",
+        "next": "ACCOUNT_READ_FAILED",
+        "intent": "CONTROLLER_UNAVAILABLE unless the Perps controller imports and reads the testnet account in time. Recovery: mm-harness doctor --fix"
+      },
+      "ACCOUNT_READ_FAILED": {
+        "action": "assert_output",
+        "source": "CONTROLLER_UNAVAILABLE",
+        "assert": { "path": "$.accountState.totalBalance", "operator": "matches", "value": "^-?[0-9]+(\\.[0-9]+)?$" },
+        "next": "done",
+        "intent": "ACCOUNT_READ_FAILED unless the read returned a numeric balance; the controller reports an unreachable venue as a placeholder. Recovery: check network access to HyperLiquid testnet, then rerun"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}

package/library/recipes/extension/health/check.recipe.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "MetaMask Extension health check",
+  "description": "Read-only check to run before ticket work: the extension answers over CDP, onboarding is done, and the wallet is unlocked on a selected account at wallet home. A failed precondition stops at the node named after its error; that node's intent gives the recovery. Changes no app state.",
+  "paramsSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "capture_path": { "type": "string", "default": "screenshots/health-check.png" }
+    }
+  },
+  "workflow": {
+    "entry": "APP_NOT_RUNNING",
+    "nodes": {
+      "APP_NOT_RUNNING": {
+        "action": "cdp.target",
+        "require_reachable": true,
+        "next": "state",
+        "intent": "APP_NOT_RUNNING unless the extension answers over CDP. Recovery: mm-harness launch --verify"
+      },
+      "state": {
+        "action": "metamask.wallet.read_state",
+        "next": "ONBOARDING",
+        "intent": "Read the selected account, lock state and page without changing them"
+      },
+      "ONBOARDING": {
+        "action": "assert_output",
+        "source": "state",
+        "assert": { "path": "$.state.completedOnboarding", "operator": "eq", "value": true },
+        "next": "WALLET_LOCKED",
+        "intent": "ONBOARDING if onboarding is not complete. Recovery: mm-harness run wallet.import"
+      },
+      "WALLET_LOCKED": {
+        "action": "assert_output",
+        "source": "state",
+        "assert": { "path": "$.state.passwordInput", "operator": "falsy" },
+        "next": "NO_SELECTED_ACCOUNT",
+        "intent": "WALLET_LOCKED if the unlock page is showing. Recovery: mm-harness run wallet.smoke"
+      },
+      "NO_SELECTED_ACCOUNT": {
+        "action": "assert_output",
+        "source": "state",
+        "assert": { "path": "$.state.selectedAccount.address", "operator": "not_null" },
+        "next": "NOT_ON_HOME",
+        "intent": "NO_SELECTED_ACCOUNT if the wallet reports no selected account. Recovery: mm-harness run wallet.import"
+      },
+      "NOT_ON_HOME": {
+        "action": "assert_output",
+        "source": "state",
+        "assert": { "path": "$.state.href", "operator": "matches", "value": "/(home|sidepanel)\\.html#/?$" },
+        "next": "CONSOLE_ERRORS",
+        "intent": "NOT_ON_HOME unless wallet home is showing. Recovery: a ui.navigate node with page home, then rerun"
+      },
+      "CONSOLE_ERRORS": {
+        "action": "metamask.app.assert_no_console_errors",
+        "next": "screenshot",
+        "intent": "CONSOLE_ERRORS if the app logged an error outside the console allowlist since launch. Recovery: fix the error, or allowlist known noise with a reason in a library's diagnostics/console-allowlist.json"
+      },
+      "screenshot": {
+        "action": "ui.screenshot",
+        "path": "{{params.capture_path}}",
+        "next": "done",
+        "intent": "Record the ready wallet home as evidence"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}

package/library/recipes/mobile/health/check.recipe.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "MetaMask Mobile health check",
+  "description": "Read-only check to run before ticket work: the app answers, onboarding is done, and the wallet is unlocked on a selected account at wallet home. A failed precondition stops at the node named after its error; that node's intent gives the recovery. Changes no app state.",
+  "paramsSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "capture_path": { "type": "string", "default": "screenshots/health-check.png" }
+    }
+  },
+  "workflow": {
+    "entry": "APP_NOT_RUNNING",
+    "nodes": {
+      "APP_NOT_RUNNING": {
+        "action": "cdp.target",
+        "require_reachable": true,
+        "next": "state",
+        "intent": "APP_NOT_RUNNING unless the app's debug bridge answers. Recovery: mm-harness launch ios|android --verify"
+      },
+      "state": {
+        "action": "metamask.wallet.read_state",
+        "next": "ONBOARDING",
+        "intent": "Read the selected account and route without changing them"
+      },
+      "ONBOARDING": {
+        "action": "assert_output",
+        "source": "state",
+        "assert": { "path": "$.route.name", "operator": "matches", "value": "^(?!Onboarding|OptinMetrics)" },
+        "next": "WALLET_LOCKED",
+        "intent": "ONBOARDING if the app is still in onboarding. Recovery: mm-harness run wallet.import"
+      },
+      "WALLET_LOCKED": {
+        "action": "assert_output",
+        "source": "state",
+        "assert": { "path": "$.route.name", "operator": "ne", "value": "Login" },
+        "next": "NO_SELECTED_ACCOUNT",
+        "intent": "WALLET_LOCKED if the unlock screen is showing. Recovery: mm-harness run wallet.smoke"
+      },
+      "NO_SELECTED_ACCOUNT": {
+        "action": "assert_output",
+        "source": "state",
+        "assert": { "path": "$.account.address", "operator": "not_null" },
+        "next": "NOT_ON_HOME",
+        "intent": "NO_SELECTED_ACCOUNT if the wallet reports no selected account. Recovery: mm-harness run wallet.import"
+      },
+      "NOT_ON_HOME": {
+        "action": "assert_output",
+        "source": "state",
+        "assert": { "path": "$.route.name", "operator": "eq", "value": "WalletView" },
+        "next": "CONSOLE_ERRORS",
+        "intent": "NOT_ON_HOME unless wallet home is showing. Recovery: a ui.navigate node with page home, then rerun"
+      },
+      "CONSOLE_ERRORS": {
+        "action": "metamask.app.assert_no_console_errors",
+        "next": "screenshot",
+        "intent": "CONSOLE_ERRORS if the app logged an error outside the console allowlist since launch. Recovery: fix the error, or allowlist known noise with a reason in a library's diagnostics/console-allowlist.json"
+      },
+      "screenshot": {
+        "action": "ui.screenshot",
+        "path": "{{params.capture_path}}",
+        "next": "done",
+        "intent": "Record the ready wallet home as evidence"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}