@deeeed/metamask-harness 0.85.0 → 0.86.1

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## Unreleased
 
+## 0.86.1 - 2026-10-09
+
+### Fixed
+
+- Extension `metamask.perps.close_visible_position cleanup_only=true` reconciles the final balance against the margin the close releases. With no placement receipt, the baseline is the available balance read while the position is still open. That baseline excludes the position's margin, so a clean full close went over the $1 tolerance and left an `outcome-unknown` receipt. A 0.11 SOL testnet close moved $524.42 to $536.45 and failed this way. The action now reads the close modal's "You'll receive" amount before dispatch and records it in the receipt as `closeReleaseBaseUnits`. It then checks the final balance against baseline + receive, with the same tolerance. If the amount is not visible, the action refuses before publishing a receipt or clicking. Closes backed by a placement receipt still reconcile against the pre-order balance. Cleanup output adds `releaseBaseUnits` and `expectedBalanceAfterBaseUnits`.
+- Mobile `metamask.perps.read_visible_state` on iOS sees Perps Text test IDs. iOS accessibility lists React Native Text as a StaticText with no identifier, so a visible Lite market price (`perps-market-header-price`) failed `require_features: ["price"]`. On a non-opaque iOS run, `ui.visible` now reads each mounted `perps-` Text's test ID, string and size over the dev bridge. It gives that test ID to the on-screen StaticText with the same label and size, when exactly one test ID matches. Offscreen StaticText stays unbound, and so does a same-text twin of another size (the collapsed header price). Other Text, such as a revealed Secret Recovery Phrase word, is not read. This reaches every iOS `ui.visible` consumer: `ui.locators`, native-navigation test-ID waits, `readVisiblePerpsTestIds`, `configure_order`, and the assets and swap-bridge `read_visible_state`. Opaque runtimes and Android are unchanged. A non-opaque run with Metro down pays one bridge attempt (at most 2 s) per observation and gets a `ui.visible` warning; a read over 500 Texts is truncated with a warning.
+- An empty `METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT` means the bundled `cdp-bridge.cjs` everywhere the TypeScript side spawns the Mobile bridge, as `run` and the action library already treated it. `launch`'s feature-flag reads and pins (and `doctor`'s) and the `status` live probe read the variable with `??`. An empty value made them check for a script named `""`, so they reported no runtime and never spawned a bridge. All TypeScript callers now share one `mobileBridgeScript()`; the action library keeps the same rule in its own `bridgeScript()` because it cannot import `src/`.
+
+## 0.86.0 - 2026-10-09
+
+### Added
+
+- `MM_HARNESS_SIBLING_LIBRARIES=0` turns off sibling discovery: libraries and reference checkouts beside the checkout or under `~/shared-library` are no longer found.
+- `call` takes `--hud show|hide` like `run`. With recipe-cli 0.11.1 a call draws the HUD by default, and its HUD text is its `intent=` input (`mm-harness call ui.screenshot intent="Show the order filled"`).
+- `MOBILE_RELOAD_VERIFY_TIMEOUT_MS` sets how long `adapters/mobile/reload-app.mjs` waits to verify a reload (default 30 000), and `MM_HARNESS_CONSOLE_ATTACH_TIMEOUT_MS` how long `launch` waits for the Extension console collector to attach (default about 10 s). A value that is not a positive number uses the default. Contract tests use them where no app or extension target can answer.
+
+### Changed
+
+- Depend on `@farmslot/recipe-runner` 0.28.1, `@farmslot/recipe-cli` 0.11.1, `@farmslot/adapter-sdk` 0.8.1, `@farmslot/adapter-web` 0.6.5, `@farmslot/adapter-node` 0.1.7 and `@farmslot/adapter-rn` 0.19.4 (were 0.28.0, 0.11.0, 0.8.0, 0.6.4, 0.1.6 and 0.19.3), pinned together; the install holds one `@farmslot/recipe-runner` and one `@farmslot/adapter-sdk`. Farmslot #869 and #870:
+  - `run` and `call` draw the HUD for every recipe source, an untrusted or inherited one (a task's `recipe-source.json`) included, unless `--hud hide`. The HUD is part of the plan an approval covers, so an untrusted-source approval made before this release without `--hud hide` (on an adapter that draws the HUD), or with another `--hud` setting, must be approved again; the refusal prints the new digest.
+  - The HUD on Extension pages is drawn in a closed shadow root with its text capped at 180 characters, so a node's own intent can no longer satisfy its `ui.wait_for text=` check or catch a text-target press.
+  - `call app.hud` drives the HUD itself, with no automatic updates.
+- A Mobile `run` arms and collects the app's issue buffer through `METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT` when it is set, as launch, status and the action library already do (it always used the bundled `cdp-bridge.cjs`). An empty value means the bundled bridge, as in the action library.
+- Extension `start-watch.sh` checks for the webpack compile marker every 0.5 s (was 2 s) and still refreshes the watcher pid every 2 s; its 480 s limit is now wall-clock time. It waits for stale watchers to stop instead of a fixed 2 s.
+
+### Fixed
+
+- Mobile `status` and `doctor` pair a physical Android device whose bridge entry carries a manufacturer prefix. A Pixel 6a over USB lists as `model:Pixel_6a` in adb while its bridge entry says `Google Pixel 6a`; it read `liveState: no-bridge`, so `doctor --print-ready` printed `not-ready` and Farmslot slot.check health failed on an unlocked wallet. The prefixed name pairs only the sole physical device (not `emulator-*`) of that model, so a same-model emulator cannot take the phone's entry; bare-model matching is unchanged.
+- Extension `ui.navigate hash=` and `url=` accept a route the Extension router rewrites in the same document. Extension 13.52 canonicalizes Perps symbols (`#/perps/trade/sol` becomes `#/perps/trade/SOL`, `XYZ%3Atsla` becomes `xyz%3ATSLA`, query kept), and readiness waited for the requested URL until it timed out. Readiness for a requested URL now takes the rewritten URL once it holds for two polls, if only the hash changed on the same extension page (same origin, path and query). Another origin, extension page or query, a `chrome-error://` page or a document that never becomes ready still fails; the error names the last URL (`Extension page did not reach <url> within <n>ms (last URL <url>)`). A lock screen that redirects to `#/unlock` is reported, not failed, so assert the route on `href`. `hash=` returns `href` (where the page landed), `requestedHref` and `redirected`; `url=` returns `href`.
+- `metamask.wallet.select_account name=` on Extension and Mobile also matches account group names. Multichain wallets (Extension 13.52) keep fixture names such as `dev1` on the account group while the internal account stays `Account 1`, so `name=dev1` failed with `Requested account was not found in internalAccounts`. A name with no internal account match now selects the EVM account of the account group with that name; a name two account groups share, or a group with no EVM account, fails without selecting anything. Extension, like Mobile, returns `alreadySelected: true` without a write when the requested account is already selected.
+
+- Docs, `help` and the Mobile, Extension and Core Perps action descriptions no longer say mainnet is read-only; they state the real mainnet rule (the shared Perps order rule, Core's `CORE_PERPS_ALLOW_MAINNET_WRITES=1`, Mobile cleanup acting on the app's current network, Extension cancel refused on mainnet outside the funded release lane). Core close, ensure and teardown descriptions no longer claim testnet only.
+- Contributors: the feature-guard scripts (`differential.mjs`, `release-smoke.mjs`, `builds.mjs`) reach a remote host with `-o ConnectTimeout=10` on every `ssh` and `scp`, and `BatchMode=yes` on `scp` as on `ssh`. A host name whose first address does not answer (`ssh macpro.local` from macwork: `connect to host macpro.local port 22: Undefined error: 0`) failed or hung without it; with it, ssh moves on to the next address.
+- Extension `refresh-build.sh` writes its build log under `$TMPDIR` as `refresh-build.XXXXXX`, without the `.log` suffix (macOS `mktemp` takes no suffix after the X's); macOS `mktemp -t` ignored `TMPDIR`, so each contract run left two logs in the machine's temp dir.
+- Contributors: a unit run gets one TMPDIR that every worker inherits. When the run ends, interrupted (Ctrl-C, SIGTERM) or not, the processes still naming it are stopped and it is removed; an interrupted run used to leave its per-file temp dirs, vitest's transform dir and detached test browsers behind. Every unit run also left a CDP broker socket in `/tmp` (the console-forwarder test killed the forwarder before it could release it), and the mutation-receipt test now writes under TMPDIR, not the checkout. Two contract tests whose bare `mktemp -d` ignored the runner's TMPDIR on macOS now create under it.
+- Contributors: contract and unit tests no longer see the operator's recipe libraries. `ct_init` and the unit setup point `MM_HARNESS_CONFIG` at a missing file, set `MM_HARNESS_SIBLING_LIBRARIES=0`, point `FARMSLOT_HOME` into the sandbox (the personal library) and clear `RECIPE_LIBRARY_PATH` and any exported `MM_HARNESS_REF_<ADAPTER>`. Port claims go to a sandbox `MM_HARNESS_PORT_REGISTRY`, not `~/.cache/mm-harness/ports`. From a checkout with perps and terminal configured, or checked out beside it, `run-name-resolution` and `extension-perps-g005` failed (`mm-harness-wave2` failed with the config). A test that covers one of these sources sets it up itself.
+
 ## 0.85.0 - 2026-10-09
 
 ### Added
@@ -34,6 +71,8 @@
 
 ### Fixed
 
+- A command no longer runs `git rev-parse` on every library it finds before dispatch. Library path hydration ran on every command, `--version` included, and pinned each discovered library (a sibling checkout, a config entry, the fetch cache) to its revision, which it never reads. The revision is now looked up only by what reports it (`status`, `domain`, `review`), as before. In a workspace with recipe-library checkouts beside the product checkout, that was one git process per library on every start.
+- `tests/contract/run.sh`, and `yarn test:goldens` through it, refuse to start (exit 2, `Next: npm run build`) when `dist/` is missing or older than any `src/**/*.ts`. `bin/mm-harness` then runs the TypeScript source on every start, type-stripped each time (about 260 ms more per start, over a thousand starts per run). CI and the full local suite build first, so only a bare `run.sh` or `yarn test:goldens` was affected.
 - Extension reopen (`adapters/extension/ensure-browser.sh`) no longer builds its `node -e` script or its `python3` profile cleanup from the slot id, checkout, runtime, profile, extension and runner paths, CDP port, webpack pid or wallet fixture path. The scripts are fixed text and get those values as argv. Before, a checkout path with an apostrophe (`/tmp/Arthur's checkout`) broke the reopen script's syntax and silently skipped the profile cleanup, and a crafted value could change the code the reopen ran.
 
 ## 0.84.0 - 2026-10-08

package/README.md

@@ -419,9 +419,11 @@ A team library supplies `review/antipatterns.md` (one `##` section per family),
 optional `review/antipatterns.<adapter>.md` families appended for that adapter only,
 `review/parity.md`, and `owned-paths.json`; the harness composes them and never
 copies them. Locations resolve env (`RECIPE_LIBRARY_PATH`, `MM_HARNESS_REF_<ADAPTER>`)
-→ `mm-harness config` → sibling directory beside the checkout → shallow fetch into
-`<checkout>/.skills-cache/<name>`. A missing reference checkout degrades the parity
-step to "not checked" with the reason.
+→ `mm-harness config` → sibling directory beside the checkout or under
+`~/shared-library` → shallow fetch into `<checkout>/.skills-cache/<name>`.
+`MM_HARNESS_SIBLING_LIBRARIES=0` turns the sibling step off, for libraries and
+reference checkouts alike (the test sandboxes set it). A missing reference
+checkout degrades the parity step to "not checked" with the reason.
 
 ## Recover
 

package/adapters/extension/refresh-build.sh

@@ -103,7 +103,7 @@ fi
 
 echo "[refresh] Using node $(node -v 2>/dev/null || echo 'not found')"
 echo "[refresh] Starting yarn start (watcher-port=${WATCHER_PORT:-default})..."
-LOG="$(mktemp -t refresh-build-XXXXXX.log)"
+LOG="$(mktemp "${TMPDIR:-/tmp}/refresh-build.XXXXXX")"
 echo "[refresh] Log: $LOG"
 env ${PORT_ARG} yarn start > "$LOG" 2>&1 &
 BUILD_PID=$!

package/adapters/extension/start-watch.sh

@@ -19,7 +19,7 @@
 #   <runtime-dir>/recipe-harness-webpack.{pid,log}; optional --summary file
 #   {feature,status,inputs,outputs,generatedAt}.
 #   Exit 0 — compiled; 1 — slot watcher owns the checkout, build failed, or
-#   compile-marker timeout (240x2s); 2 — bad args.
+#   compile-marker timeout (480 s); 2 — bad args.
 #
 # Never touches: the slot-owned webpack.pid watcher process (refusal only,
 # removes the pid file only when stale); product source files.
@@ -229,8 +229,11 @@ existing_watch_pids="$(watcher_pids || true)"
 if [ -n "$existing_watch_pids" ]; then
   echo "[recipe-harness] Stopping stale target-scoped watcher(s): $(printf '%s' "$existing_watch_pids" | tr '\n' ' ')"
   printf '%s\n' "$existing_watch_pids" | xargs kill 2>/dev/null || true
-  sleep 2
-  existing_watch_pids="$(watcher_pids || true)"
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    existing_watch_pids="$(watcher_pids || true)"
+    [ -z "$existing_watch_pids" ] && break
+    sleep 0.2
+  done
   if [ -n "$existing_watch_pids" ]; then
     printf '%s\n' "$existing_watch_pids" | xargs kill -9 2>/dev/null || true
   fi
@@ -290,7 +293,13 @@ elif [ -n "$LIB_DIR" ] && [ "${RECIPE_LOG_TUI_PARENT:-}" != "1" ]; then
   watch_tail_pid=$!
 fi
 compiled=false
-for i in {1..240}; do
+# The log is checked every 0.5 s, so a marker is seen at once. The watcher pid
+# needs a full process listing, so it is refreshed every 2 s. Bounded by time:
+# 480 s for a compile marker, 20 s for yarn start's watcher to appear.
+poll_started=$SECONDS
+i=0
+while [ $((SECONDS - poll_started)) -lt 480 ]; do
+  i=$((i + 1))
   if [ -n "$watch_tail_pid" ] && ! kill -0 "$watch_tail_pid" >/dev/null 2>&1; then
     wait "$watch_tail_pid" 2>/dev/null || true
     if grep -Eq 'compiled successfully|compiled with [0-9]+ warning|MetaMask .* compiled|Bundle end: service worker|Bundle end:.*app-init' "$watch_log" 2>/dev/null; then
@@ -300,9 +309,9 @@ for i in {1..240}; do
     echo '[recipe-harness] compact build watcher exited before compile marker; continuing to poll webpack log' >&2
     watch_tail_pid=""
   fi
-  if ! write_canonical_watch_pid; then
-    if [ "$i" -le 10 ]; then
-      sleep 2
+  if [ $((i % 4)) -eq 1 ] && ! write_canonical_watch_pid; then
+    if [ $((SECONDS - poll_started)) -lt 20 ]; then
+      sleep 0.5
       continue
     fi
     [ -n "$watch_tail_pid" ] && kill "$watch_tail_pid" >/dev/null 2>&1 || true
@@ -331,7 +340,7 @@ for i in {1..240}; do
     [ -n "$watch_tail_pid" ] && wait "$watch_tail_pid" 2>/dev/null || true
     break
   fi
-  sleep 2
+  sleep 0.5
 done
 if [ "$compiled" != true ]; then
   [ -n "$watch_tail_pid" ] && kill "$watch_tail_pid" >/dev/null 2>&1 || true

package/adapters/manifest.json

@@ -47,7 +47,7 @@
       "entry": "adapters/mobile/reload-app.mjs",
       "kind": "node",
       "purpose": "Request an in-place React Native app reload through Metro's protocol-v2 message endpoint.",
-      "inputs": "--port --json; env WATCHER_PORT, METRO_PORT",
+      "inputs": "--port --json; env WATCHER_PORT, METRO_PORT, MOBILE_RELOAD_VERIFY_TIMEOUT_MS (default 30000)",
       "outputs": "reload result on stdout; exit 0 requested / 1 unavailable or invalid input"
     },
     {

package/adapters/mobile/reload-app.mjs

@@ -146,7 +146,8 @@ async function reload(port) {
 }
 
 async function waitForReload(port, targetBefore, processBefore, observer) {
-  const deadline = Date.now() + 30_000;
+  const timeoutMs = Number(process.env.MOBILE_RELOAD_VERIFY_TIMEOUT_MS);
+  const deadline = Date.now() + (timeoutMs > 0 ? timeoutMs : 30_000);
   let lastError;
   while (Date.now() < deadline) {
     if (processBefore && readAndroidPid() !== processBefore) {

package/dist/adapters/console-capture.js

@@ -58,7 +58,9 @@ async function ensureConsoleCollector(options) {
   fs.writeFileSync(pidFile, `${child.pid}
 `);
   const attachmentFrom = { [extensionLog]: fileSize(extensionLog), [pageLog]: fileSize(pageLog) };
-  for (let attempt = 0; attempt < 100; attempt += 1) {
+  const timeoutMs = Number(process.env.MM_HARNESS_CONSOLE_ATTACH_TIMEOUT_MS);
+  const attempts = Math.ceil((timeoutMs > 0 ? timeoutMs : 1e4) / 100);
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
     const proc = processArgs(child.pid);
     if (!proc) break;
     if (collectorMatches(proc, identity)) {

package/dist/adapters/mobile/bridge-script.js

@@ -0,0 +1,12 @@
+import path from "node:path";
+import { runnerDir } from "../../paths.js";
+function mobileBridgeScriptOverride() {
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || void 0;
+}
+function mobileBridgeScript() {
+  return mobileBridgeScriptOverride() ?? path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+}
+export {
+  mobileBridgeScript,
+  mobileBridgeScriptOverride
+};

package/dist/adapters/mobile/feature-flags.js

@@ -1,11 +1,7 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
-import path from "node:path";
-import { runnerDir } from "../../paths.js";
+import { mobileBridgeScript } from "./bridge-script.js";
 const DEFAULT_TIMEOUT_MS = 1e4;
-function bridgeScriptPath() {
-  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT ?? path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
-}
 const CONTROLLER_PREAMBLE = `
   var ctx = globalThis.Engine && globalThis.Engine.context;
   var c = ctx && ctx.RemoteFeatureFlagController;
@@ -19,7 +15,7 @@ function evalExpression(body) {
   return `(function(){ try {${CONTROLLER_PREAMBLE}${body} } catch (e) { return JSON.stringify({ ok: false, error: e && (e.message || String(e)) }); } })()`;
 }
 function runBridgeEval(target, expression, timeoutMs) {
-  const script = bridgeScriptPath();
+  const script = mobileBridgeScript();
   if (!fs.existsSync(script)) return Promise.resolve(null);
   return new Promise((resolve) => {
     let settled = false;

package/dist/adapters/mobile/run.js

@@ -2,7 +2,6 @@ import { EXIT, isRecord } from "@farmslot/recipe-cli/harness";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { IOS_SIMULATOR_RECORDING_TARGET_PREFIX } from "@farmslot/adapter-rn";
-import { runnerDir } from "../../paths.js";
 import { devicePlatformFromEnv } from "../performance/device-platform.js";
 import {
   resolveAndroidDeviceSerial,
@@ -10,6 +9,7 @@ import {
 } from "./recording-target.js";
 import { emitProofFailure } from "../proof-failure.js";
 import { mobileAppIdentityEnv } from "./app-identity.js";
+import { mobileBridgeScript } from "./bridge-script.js";
 import { requireCurrentMobileReleaseArtifactState } from "./release-artifact-state.js";
 const EXPLICIT_DEVICE_KEYS = [
   "PLATFORM",
@@ -158,7 +158,7 @@ const mobileObservation = {
   }
 };
 function runMobileIssueCommand(projectRoot, command) {
-  const bridge = path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+  const bridge = mobileBridgeScript();
   const result = spawnSync(process.execPath, [bridge, command], {
     cwd: projectRoot,
     env: { ...process.env, APP_ROOT: projectRoot, CDP_TIMEOUT: "5000" },

package/dist/adapters/mobile/ui.js

@@ -10,6 +10,7 @@ import { trustedMutationContextExtras } from "../../funding-execution-context.js
 import { LIBRARY_ACTION_NAMESPACE } from "../../paths.js";
 import { liveTsxCandidates } from "../../live-tsx.js";
 import { mobileAppIdentityEnv } from "./app-identity.js";
+import { mobileBridgeScriptOverride } from "./bridge-script.js";
 const execFileAsync = promisify(execFile);
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -58,7 +59,7 @@ function mobileProbeOutput(status, input, projectRoot) {
   };
 }
 function mobileBridgePath(_projectRoot) {
-  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || "runner:adapters/mobile/bridge-runtime/cdp-bridge.cjs";
+  return mobileBridgeScriptOverride() ?? "runner:adapters/mobile/bridge-runtime/cdp-bridge.cjs";
 }
 function resolveMobileWaitTarget(payload) {
   const testId = optionalScalarText(

package/dist/command-contract.js

@@ -721,12 +721,14 @@ Example:
   --action-manifest <path>           Override the action manifest
   --library <name=path>              Add/override a recipe-library source (repeatable)
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
+  --hud <show|hide>                  Recipe HUD: the call's intent= drawn over the app, headless included (default: show)
   --json                             Machine-readable output
 
 Example (real actions; run mm-harness actions for this checkout's full set):
   mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
   mm-harness call navigate page=perps --adapter mobile
   mm-harness call command cmd="echo hi" --adapter core   # the universal action (all adapters)
+  mm-harness call ui.screenshot intent="Show the order filled"   # intent= is the HUD text
 
 Remote feature flags (mobile applies at runtime; extension pins at launch):
   mm-harness call metamask.feature_flags.read --adapter mobile
@@ -738,7 +740,8 @@ Remote feature flags (mobile applies at runtime; extension pins at launch):
         "--list": bool(),
         "--domain": value(),
         "--source": value(),
-        "--sort": value(["domain", "name", "library"])
+        "--sort": value(["domain", "name", "library"]),
+        "--hud": value(["show", "hide"])
       }),
       positionals: [{ label: "action" }],
       minimumPositionals: 0,

package/dist/commands/status-probe.js

@@ -1,13 +1,9 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
-import path from "node:path";
 import { fixtureSummary } from "../doctor.js";
 import { normalizeFeatureFlagRecord } from "../feature-flags.js";
-import { runnerDir } from "../paths.js";
+import { mobileBridgeScript } from "../adapters/mobile/bridge-script.js";
 const PROBE_TIMEOUT_MS = 2e3;
-function bridgeScriptPath() {
-  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT ?? path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
-}
 function truncateAddress(address) {
   if (!address || address.length <= 10) return address;
   return `${address.slice(0, 6)}\u2026${address.slice(-4)}`;
@@ -52,6 +48,13 @@ function parseBridgeEntries(raw) {
     ...e.featureFlags !== void 0 ? { featureFlags: e.featureFlags } : {}
   }));
 }
+function androidModelMatches(deviceName, model, device, devices) {
+  if (deviceName === model || deviceName.startsWith(`${model} -`)) return true;
+  if (!deviceName.endsWith(` ${model}`) && !deviceName.includes(` ${model} -`)) return false;
+  const physical = (d) => d.platform === "android" && !d.id.startsWith("emulator-");
+  if (!physical(device)) return false;
+  return devices.filter((d) => physical(d) && d.name === device.name).length === 1;
+}
 function matchBridgeEntry(device, entries, devices) {
   const byId = entries.find((e) => e.deviceName === device.id);
   if (byId) return byId;
@@ -60,7 +63,7 @@ function matchBridgeEntry(device, entries, devices) {
     if (byName) return byName;
     if (device.platform === "android") {
       const model = device.name.replace(/_/gu, " ");
-      const byModel = entries.find((e) => e.deviceName === model || e.deviceName.startsWith(`${model} -`));
+      const byModel = entries.find((e) => androidModelMatches(e.deviceName, model, device, devices));
       if (byModel) return byModel;
     }
   }
@@ -70,7 +73,7 @@ function matchBridgeEntry(device, entries, devices) {
   return null;
 }
 function probeMobileBridge(target) {
-  const script = bridgeScriptPath();
+  const script = mobileBridgeScript();
   if (!fs.existsSync(script)) {
     return Promise.resolve({ ok: false, liveState: "no-bridge" });
   }

package/dist/review/knowledge.js

@@ -95,6 +95,7 @@ function withRevision(location) {
   return revision ? { ...location, revision } : location;
 }
 function siblingRoots(context) {
+  if ((context.env ?? process.env).MM_HARNESS_SIBLING_LIBRARIES === "0") return [];
   const home = context.homeDir ?? os.homedir();
   const parents = [path.dirname(path.resolve(context.target)), path.join(home, "shared-library")];
   const roots = [];
@@ -173,6 +174,9 @@ function resolveLibrary(name, options) {
   return void 0;
 }
 function discoverLibraries(context) {
+  return discoverLibraryLocations(context).map(withRevision);
+}
+function discoverLibraryLocations(context) {
   const env = context.env ?? process.env;
   const seenRoots = /* @__PURE__ */ new Set();
   const seenNames = /* @__PURE__ */ new Set();
@@ -184,7 +188,7 @@ function discoverLibraries(context) {
     if (seenNames.has(libraryName)) return;
     seenRoots.add(resolved);
     seenNames.add(libraryName);
-    found.push(withRevision({ name: libraryName, root: resolved, source }));
+    found.push({ name: libraryName, root: resolved, source });
   };
   for (const entry of parseLibraryPathEnv(declaredLibraryPathFor(env))) add(entry.name, entry.root, "env");
   for (const [name, root] of Object.entries(context.config?.libraries ?? {})) add(name, root, "config");
@@ -215,7 +219,7 @@ async function hydrateLibraryPathEnv(context) {
       (entry) => entry.name ?? loadOwnedPaths(entry.root)?.domain ?? path.basename(entry.root)
     )
   );
-  const discovered = discoverLibraries(context).filter(
+  const discovered = discoverLibraryLocations(context).filter(
     (library) => library.source !== "env" && !declared.has(library.name)
   );
   if (discovered.length === 0) return;

package/docs/CONTRIBUTING.md

@@ -176,10 +176,13 @@ or wrapper, verify real callers and retain compatibility only when one exists.
 yarn test:unit
 yarn test:coverage
 yarn check
+npm run build
 bash tests/contract/run.sh
 ```
 
-`run.sh` runs half the cores' worth of tests at once (`-j N` to change it), each
+`run.sh` refuses to start when `dist/` is missing or older than any `src/**/*.ts`: the
+CLI would then run the TypeScript source on every start. It runs half the
+cores' worth of tests at once (`-j N` to change it), each
 in its own process group and `TMPDIR`, and prints each test's duration and the
 15 slowest. A test gets 60 s (`CONTRACT_TEST_TIMEOUT`); one whose product waits
 are longer declares `# contract: timeout=<seconds>`, and one that cannot share

package/docs/QA.md

@@ -183,6 +183,7 @@ mm-harness debug
 
 ```bash
 yarn check
+npm run build
 bash tests/contract/run.sh
 ```
 

package/docs/RECIPES.md

@@ -329,7 +329,10 @@ block, skip, or refuse; a fixture that demands an empty account must converge
 rather than refuse. Extension `ensure_*` and `teardown_state` only assert, so
 converge there through an explicitly funded leaf action. Never broaden cleanup
 onto an account or market the task does not own; obtain an owned one instead
-of blocking. Mainnet is read-only.
+of blocking. On mainnet, orders follow the Perps order rule above, Core needs
+`CORE_PERPS_ALLOW_MAINNET_WRITES=1` for any write, Mobile cleanup acts on
+whatever network the app is on, and Extension refuses mainnet writes other than
+orders and `close_visible_position` in the fixture-policy lane.
 
 ### Mobile advanced-order setup
 

package/docs/cli-contract.md

@@ -101,6 +101,7 @@ Outside this boundary: a successful `launch` and the `temp/recipe/runtime/termin
 ## Running the goldens
 
 ```bash
+npm run build                   # first: the families run the CLI from dist/, and refuse a stale one
 yarn test:goldens               # compare all families in parallel, within 2 minutes (CI runs them in the contract shards)
 yarn test:goldens mobile        # families whose name contains "mobile"
 yarn test:goldens --update      # rewrite goldens, print a per-field diff summary, drop orphans

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

@@ -229,8 +229,8 @@ let cached = null;
 /**
  * Resolve the requested network. Default testnet; mainnet only when a node
  * explicitly sets network: "mainnet". Mainnet reads are safe; mainnet mutations
- * use REAL funds and must be explicitly requested — mirrors the extension/mobile
- * "mainnet is read-only unless explicitly requested" contract.
+ * use REAL funds and must be explicitly requested (see the Perps order rule in
+ * docs/RECIPES.md).
  */
 export function resolveNetwork(input) {
   const raw = String(input.node?.network ?? 'testnet').toLowerCase();

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

@@ -208,10 +208,11 @@ async function prepareCloseModal(page, partialAmount) {
   return confirmation;
 }
 
-async function proveGlobalCleanup(page, balanceBeforeBaseUnits, toleranceBaseUnits, timeoutMs = 20_000) {
+async function proveGlobalCleanup(page, balanceBeforeBaseUnits, releaseBaseUnits, toleranceBaseUnits, timeoutMs = 20_000) {
   await page.navigateHash('#/perps-home');
   const state = await waitForStableGlobalPerpsHome(page, { timeoutMs, requireZero: true });
-  const balanceDeltaBaseUnits = absoluteDelta(state.balanceBaseUnits, balanceBeforeBaseUnits);
+  const expectedBalanceAfterBaseUnits = `${BigInt(balanceBeforeBaseUnits) + BigInt(releaseBaseUnits ?? '0')}`;
+  const balanceDeltaBaseUnits = absoluteDelta(state.balanceBaseUnits, expectedBalanceAfterBaseUnits);
   if (BigInt(balanceDeltaBaseUnits) > BigInt(toleranceBaseUnits)) {
     throw new Error('Final visible Perps balance exceeds the authorized reconciliation tolerance.');
   }
@@ -219,6 +220,8 @@ async function proveGlobalCleanup(page, balanceBeforeBaseUnits, toleranceBaseUni
     positionCount: 0,
     orderCount: 0,
     balanceBeforeBaseUnits,
+    releaseBaseUnits: releaseBaseUnits ?? null,
+    expectedBalanceAfterBaseUnits,
     balanceAfterBaseUnits: state.balanceBaseUnits,
     balanceDeltaBaseUnits,
     toleranceBaseUnits,
@@ -327,9 +330,14 @@ export async function closeVisiblePosition(input) {
                 if (!/^(?:0|[1-9][0-9]{0,29})$/u.test(balanceBeforeBaseUnits)) {
                   throw new Error('Resumed close receipt has no valid pre-order balance.');
                 }
+                const releaseBaseUnits = existingReceipt.record?.facts?.closeReleaseBaseUnits ?? null;
+                if (releaseBaseUnits != null && !/^-?(?:0|[1-9][0-9]{0,29})$/u.test(String(releaseBaseUnits))) {
+                  throw new Error('Resumed close receipt has an invalid close release amount.');
+                }
                 const cleanup = await proveGlobalCleanup(
                   page,
                   balanceBeforeBaseUnits,
+                  releaseBaseUnits,
                   balanceToleranceBaseUnits,
                 );
                 return {
@@ -413,6 +421,11 @@ export async function closeVisiblePosition(input) {
   if (partialAmount == null && (!confirmation.fullSizeSelected || !confirmation.marketOrder)) {
     throw new Error('Receipt-bound full close requires the visible 100% market-close form.');
   }
+  // Without a placement receipt the baseline is the in-position balance, which excludes the released margin.
+  const closeReleaseBaseUnits = placement ? null : parseUsdBaseUnits(confirmation.receive);
+  if (!placement && closeReleaseBaseUnits == null) {
+    throw new Error('Close without a placement receipt requires the visible close receive amount.');
+  }
   const closeSizing = partialAmount == null ? { size: sizeMatch[1], side: fundingSide === 'long' ? 'short' : 'long' } : null;
   let submissionObserver = null;
   let mutation;
@@ -427,6 +440,7 @@ export async function closeVisiblePosition(input) {
       cleanupOnly,
       fundingBalance,
       tradingContext,
+      ...(closeReleaseBaseUnits != null ? { closeReleaseBaseUnits } : {}),
       ...(acceptedFill ? { acceptedFill } : {}),
       ...(closeSizing ? { closeSizing } : {}),
     },
@@ -507,6 +521,7 @@ export async function closeVisiblePosition(input) {
             const cleanup = await proveGlobalCleanup(
               page,
               balanceBeforeBaseUnits,
+              closeReleaseBaseUnits,
               balanceToleranceBaseUnits,
             );
             return {

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

@@ -981,8 +981,52 @@ export class ExtensionPage extends CdpWebPage {
       location.hash = ${JSON.stringify(normalizedHash)};
       return { before, href: location.href };
     })()`);
-    await this.waitForDocumentReady({ expectedUrl: navigation.href, timeoutMs });
-    return { ...navigation, sameDocument: true };
+    const ready = await this.waitForDocumentReady({ expectedUrl: navigation.href, timeoutMs });
+    return {
+      before: navigation.before,
+      requestedHref: navigation.href,
+      href: ready.url,
+      redirected: ready.redirected,
+      sameDocument: true,
+    };
+  }
+
+  // The Extension router may replace a requested hash with its canonical route
+  // in the same document (e.g. Perps symbol casing). The runtime still decides
+  // readiness; this accepts the rewritten URL once it holds for two polls. Any
+  // other origin, page or query still fails.
+  async waitForDocumentReady({ expectedUrl, timeoutMs = 10000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    let url;
+    let redirectCandidate;
+    while (true) {
+      await super.waitForDocumentReady({ timeoutMs: Math.max(1, deadline - Date.now()) });
+      // A context lost between the two probes counts as an unmatched poll.
+      url = await this.evaluate('location.href').catch(() => undefined);
+      if (!expectedUrl || url === expectedUrl) return { url, redirected: false };
+      const redirect = this.isSameDocumentRedirect(expectedUrl, url) ? url : undefined;
+      if (redirect && redirect === redirectCandidate) return { url, redirected: true };
+      redirectCandidate = redirect;
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) break;
+      await sleep(Math.min(50, remainingMs));
+    }
+    throw new Error(`Extension page did not reach ${expectedUrl} within ${timeoutMs}ms (last URL ${url ?? 'unavailable'})`);
+  }
+
+  isSameDocumentRedirect(expectedUrl, actualUrl) {
+    try {
+      const expected = new URL(expectedUrl);
+      const actual = new URL(actualUrl);
+      return `${expected.protocol}//${expected.host}` === this.origin
+        && actual.protocol === expected.protocol
+        && actual.host === expected.host
+        && actual.pathname === expected.pathname
+        && actual.search === expected.search
+        && actual.hash !== expected.hash;
+    } catch {
+      return false;
+    }
   }
 
   async readPositions() {

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

@@ -591,7 +591,9 @@ export async function navigateExtensionUi(input) {
   const url = input.node?.url;
   if (typeof url === 'string' && url.length > 0) {
     const navigation = await page.navigate(url);
-    return { action: input.action, url, navigation, proofPath: 'ui-navigation' };
+    // The router may canonicalize the requested route; report where it landed.
+    const href = await currentHref(page);
+    return { action: input.action, url, href, navigation, proofPath: 'ui-navigation' };
   }
 
   const hash = input.node?.hash ?? input.node?.path;

package/library/actions/extension/wallet/select_account.mjs

@@ -1,9 +1,10 @@
-// Selects an account by address, ID, or name through the background request hook.
-// Falls back to visible account search when that hook is unavailable and checks the selected address.
+// Selects an account by address, ID, or account group/internal name through the background request hook.
+// Returns without a write when the account is already selected. Falls back to visible account search
+// when that hook is unavailable and checks the selected address.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import {
-  listWalletAccountsExpression,
   readWalletStateExpression,
+  resolveWalletAccountExpression,
   selectWalletAccountExpression,
 } from './state.mjs';
 
@@ -18,25 +19,24 @@ runAdapter((input) => withExtensionPage(input, async (page) => {
   if (!requestedAddress && !requestedId && !requestedName) {
     throw new Error('metamask.wallet.select_account extension live adapter requires node.address, node.id, or node.name.');
   }
+  const criteria = { address: requestedAddress, id: requestedId, name: requestedName };
   try {
-    const selected = await page.evaluate(selectWalletAccountExpression({
-      address: requestedAddress,
-      id: requestedId,
-      name: requestedName,
-    }), { awaitPromise: true });
-    return { action: input.action, selected, proofPath: 'extension-background-account-selection' };
+    const { alreadySelected, ...selected } = await page.evaluate(
+      selectWalletAccountExpression(criteria),
+      { awaitPromise: true },
+    );
+    return {
+      action: input.action,
+      selected,
+      ...(alreadySelected ? { alreadySelected: true } : {}),
+      proofPath: 'extension-background-account-selection',
+    };
   } catch (error) {
     if (!String(error?.message ?? error).includes('submitRequestToBackground is unavailable')) throw error;
   }
 
-  let searchAddress = requestedAddress;
-  if (!searchAddress) {
-    const listed = await page.evaluate(listWalletAccountsExpression('all'), { awaitPromise: true });
-    const account = listed.accounts.find((entry) =>
-      (requestedId && entry.id === requestedId) ||
-      (requestedName && entry.name === requestedName));
-    searchAddress = normalize(account?.address);
-  }
+  const resolved = await page.evaluate(resolveWalletAccountExpression(criteria), { awaitPromise: true });
+  const searchAddress = normalize(resolved?.address);
   if (!searchAddress) throw new Error('Requested account does not have a searchable EVM address.');
 
   await page.navigateHash('#/account-list');

package/library/actions/extension/wallet/state.mjs

@@ -94,40 +94,94 @@ export function listWalletAccountsExpression(scope) {
   })()`;
 }
 
+// Resolves id, address, or internal metadata name against internalAccounts first. A name
+// with no internal match falls back to AccountTreeController group names (multichain
+// wallets keep fixture names there, e.g. group "dev1" over internal "Account 1") and
+// selects the group's EVM account; a group without one is rejected.
+const resolveAccountPreamble = `
+    const resolveRequestedAccount = (state, criteria) => {
+      const accounts = state.internal.accounts || {};
+      const entries = Object.entries(accounts);
+      const isEvm = (account) => /^0x[0-9a-f]{40}$/iu.test(String(account?.address || ''));
+      const direct = entries.find(([id, account]) =>
+        (criteria.id && id === criteria.id) ||
+        (criteria.address && String(account?.address || '').toLowerCase() === criteria.address) ||
+        (criteria.name && account?.metadata?.name === criteria.name));
+      if (direct) return { id: direct[0], accountGroup: null };
+      if (!criteria.name) return null;
+      const groups = [];
+      for (const wallet of Object.values(state.metamask.accountTree?.wallets || {})) {
+        for (const [groupId, group] of Object.entries(wallet?.groups || {})) {
+          if (group?.metadata?.name === criteria.name) groups.push({ id: groupId, accounts: group.accounts || [] });
+        }
+      }
+      if (groups.length > 1) {
+        throw new Error('Requested account name ' + JSON.stringify(criteria.name) + ' matches ' + groups.length +
+          ' account groups; select by address instead.');
+      }
+      if (!groups.length) return null;
+      const id = groups[0].accounts.find((candidate) => isEvm(accounts[candidate]));
+      if (!id) {
+        throw new Error('Account group ' + JSON.stringify(criteria.name) +
+          ' has no EVM account; select by id instead.');
+      }
+      return { id, accountGroup: { id: groups[0].id, name: criteria.name } };
+    };
+    const describeAccount = (state, resolved) => {
+      const account = state.internal.accounts?.[resolved.id];
+      return {
+        id: resolved.id,
+        address: account?.address || null,
+        name: account?.metadata?.name || null,
+        type: account?.type || null,
+        ...(resolved.accountGroup ? { accountGroup: resolved.accountGroup } : {}),
+      };
+    };
+`;
+
+function criteriaLiteral(criteria) {
+  return JSON.stringify({
+    address: criteria.address || null,
+    id: criteria.id || null,
+    name: criteria.name || null,
+  });
+}
+
+export function resolveWalletAccountExpression(criteria) {
+  return `(async () => {
+    ${walletStatePreamble}
+    ${resolveAccountPreamble}
+    const state = await readWalletState();
+    const resolved = resolveRequestedAccount(state, ${criteriaLiteral(criteria)});
+    if (!resolved) throw new Error('Requested account was not found in account groups or internalAccounts.');
+    return {
+      ...describeAccount(state, resolved),
+      alreadySelected: resolved.id === (state.internal.selectedAccount || null),
+    };
+  })()`;
+}
+
 export function selectWalletAccountExpression(criteria, timeoutMs = 5000) {
   return `(async () => {
     ${walletStatePreamble}
+    ${resolveAccountPreamble}
     const before = await readWalletState();
-    const accounts = before.internal.accounts || {};
-    const requestedAddress = ${JSON.stringify(criteria.address)};
-    const requestedId = ${JSON.stringify(criteria.id)};
-    const requestedName = ${JSON.stringify(criteria.name)};
-    const match = Object.entries(accounts).find(([id, account]) => {
-      const metadata = account?.metadata || {};
-      return (requestedId && id === requestedId) ||
-        (requestedAddress && String(account?.address || '').toLowerCase() === requestedAddress) ||
-        (requestedName && metadata.name === requestedName);
-    });
-    if (!match) throw new Error('Requested account was not found in internalAccounts.');
+    const resolved = resolveRequestedAccount(before, ${criteriaLiteral(criteria)});
+    if (!resolved) throw new Error('Requested account was not found in account groups or internalAccounts.');
+    const id = resolved.id;
+    if ((before.internal.selectedAccount || null) === id) {
+      return { ...describeAccount(before, resolved), alreadySelected: true };
+    }
     if (typeof before.hooks.submitRequestToBackground !== 'function') {
       throw new Error('stateHooks.submitRequestToBackground is unavailable.');
     }
-    const [id] = match;
     await before.hooks.submitRequestToBackground('setSelectedInternalAccount', [id]);
     const deadline = Date.now() + ${Number(timeoutMs)};
     let observedId = before.internal.selectedAccount || null;
     while (Date.now() <= deadline) {
       const after = await readWalletState();
       observedId = after.internal.selectedAccount || null;
-      if (observedId === id) {
-        const selected = after.internal.accounts?.[observedId];
-        return {
-          id: observedId,
-          address: selected?.address || null,
-          name: selected?.metadata?.name || null,
-          type: selected?.type || null,
-        };
-      }
+      if (observedId === id) return describeAccount(after, resolved);
       await new Promise((resolve) => setTimeout(resolve, 100));
     }
     throw new Error(

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

@@ -107,6 +107,8 @@ export async function runAdapter(callback) {
   }
 }
 
+// Same rule as src/adapters/mobile/bridge-script.ts (unset or empty means the
+// bundled bridge); the library cannot import src/.
 function bridgeScript(input) {
   if (process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT) {
     return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT;

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

@@ -16,6 +16,41 @@ import { mobileToolRecovery, resolveMobileToolPath } from '@farmslot/adapter-rn'
 const execFileAsync = promisify(execFile);
 const VISIBLE_LIMIT = 200;
 const HIDDEN_LIMIT = 100;
+// iOS accessibility exposes React Native Text as StaticText without its testID.
+// Read each mounted Perps Text's testID, string and size (synchronous on Fabric)
+// so the visible native element with the same label and size can carry that
+// testID. Only perps- Texts leave the app: other Text, such as a revealed
+// Secret Recovery Phrase word, never reaches the harness or a trace.
+const TEXT_TEST_ID_LIMIT = 500;
+const IOS_TEXT_TEST_IDS = `(() => {
+  const ui = globalThis.nativeFabricUIManager;
+  const hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!ui?.measureInWindow || !hook?.getFiberRoots) return { texts: [], total: 0 };
+  const texts = [];
+  const content = (fiber) => {
+    let value = '';
+    for (let child = fiber.child; child; child = child.sibling) {
+      value += typeof child.memoizedProps === 'string' || typeof child.memoizedProps === 'number'
+        ? String(child.memoizedProps) : content(child);
+    }
+    return value;
+  };
+  const visit = (fiber) => {
+    for (; fiber; fiber = fiber.sibling) {
+      const testId = fiber.memoizedProps?.testID;
+      if (fiber.type === 'RCTText' && typeof testId === 'string' && testId.startsWith('perps-') && fiber.stateNode?.node) {
+        let bounds;
+        ui.measureInWindow(fiber.stateNode.node, (x, y, width, height) => { bounds = { x, y, width, height }; });
+        if (bounds) texts.push({ testId, label: content(fiber), bounds });
+      }
+      visit(fiber.child);
+    }
+  };
+  const roots = new Set();
+  for (const id of hook.renderers.keys()) hook.getFiberRoots(id)?.forEach((root) => roots.add(root));
+  roots.forEach((root) => visit(root.current));
+  return { texts: texts.slice(0, ${TEXT_TEST_ID_LIMIT}), total: texts.length };
+})()`;
 
 export async function observeNativeUi(payload, context) {
   await hideAccessibilityMaskingHud(payload, context);
@@ -39,7 +74,26 @@ export async function observeNativeUi(payload, context) {
         warnings.push({ ref: 'ui.screen', message: `Navigation route unavailable: ${error.message}` });
       }
     }
-    const hierarchy = await readNativeHierarchy(payload, context);
+    let textTestIds = [];
+    if (
+      supported.includes('ui.visible') &&
+      resolvePlatform(record(payload?.node), env) === 'ios' &&
+      !isOpaqueRuntime(env) && (env.METRO_PORT || env.WATCHER_PORT)
+    ) {
+      try {
+        const read = await bridgeCommand(routeInput, ['eval', IOS_TEXT_TEST_IDS]);
+        textTestIds = Array.isArray(read?.texts) ? read.texts : [];
+        if (read?.total > textTestIds.length) {
+          warnings.push({
+            ref: 'ui.visible',
+            message: `Text test IDs truncated: read ${textTestIds.length} of ${read.total}.`,
+          });
+        }
+      } catch (error) {
+        warnings.push({ ref: 'ui.visible', message: `Text test IDs unavailable: ${error.message}` });
+      }
+    }
+    const hierarchy = await readNativeHierarchy(payload, context, textTestIds);
     if (routeBefore?.name) {
       const routeAfter = await bridgeCommand(routeInput, ['get-route']);
       if (routeAfter?.name !== routeBefore.name || routeAfter?.key !== routeBefore.key) {
@@ -85,7 +139,7 @@ export async function hideAccessibilityMaskingHud(payload, context) {
   }
 }
 
-async function readNativeHierarchy(payload, context) {
+async function readNativeHierarchy(payload, context, textTestIds) {
   const node = record(payload?.node);
   const env = {
     ...process.env,
@@ -98,13 +152,13 @@ async function readNativeHierarchy(payload, context) {
   const appLabel = nativeAppLabel(env);
   const hierarchy = platform === 'android'
     ? await readAndroidHierarchy(node, env)
-    : await readIosHierarchy(node, env);
+    : await readIosHierarchy(node, env, textTestIds);
   // No screen name and no labelled item: name the screen after the app.
   hierarchy.screen.name ??= appLabel;
   return hierarchy;
 }
 
-async function readIosHierarchy(node, env) {
+async function readIosHierarchy(node, env, textTestIds) {
   const idbPath = resolveMobileToolPath('idb');
   if (!idbPath) {
     throw new Error(
@@ -123,7 +177,7 @@ async function readIosHierarchy(node, env) {
     },
   );
   const parsed = parseJsonOutput(stdout);
-  const hierarchy = flattenIosHierarchy(parsed);
+  const hierarchy = flattenIosHierarchy(parsed, textTestIds);
   if (hierarchy.nodeCount === 0) {
     throw new Error('idb returned an empty accessibility hierarchy.');
   }
@@ -364,7 +418,12 @@ function parseJsonOutput(output) {
   }
 }
 
-function flattenIosHierarchy(value) {
+function flattenIosHierarchy(value, textTestIds = []) {
+  const texts = (Array.isArray(textTestIds) ? textTestIds : []).map((entry) => ({
+    testId: text(entry?.testId),
+    label: text(entry?.label),
+    bounds: normalizeBounds(entry?.bounds),
+  })).filter((entry) => entry.testId && entry.label && entry.bounds);
   const visible = [];
   const hidden = [];
   let nodeCount = 0;
@@ -382,9 +441,10 @@ function flattenIosHierarchy(value) {
       text(item.role_description) ?? text(item.className);
     const label = text(item.label) ?? text(item.AXLabel) ?? text(item.name) ??
       text(item.title);
-    const testId = text(item.identifier) ?? text(item.accessibilityIdentifier) ??
-      text(item.AXUniqueId) ?? text(item.id);
     const bounds = normalizeBounds(item.frame ?? item.AXFrame ?? item.bounds);
+    const testId = text(item.identifier) ?? text(item.accessibilityIdentifier) ??
+      text(item.AXUniqueId) ?? text(item.id) ??
+      (label && hasVisibleBounds(bounds, screenBounds) ? textTestId(texts, label, bounds) : undefined);
     if (isApplicationRole(role)) {
       screenName ??= label;
       screenBounds ??= bounds;
@@ -466,6 +526,17 @@ function parseAndroidHierarchy(output) {
   return { visible, hidden, nodeCount, screenName };
 }
 
+// Bind an exact label and size to one testID. Origins are not compared: Fabric
+// frames omit native screen offsets such as a modal card. A same-text twin with
+// another size (the collapsed header price) or another testID stays unbound.
+function textTestId(texts, label, bounds) {
+  const testIds = new Set(texts
+    .filter((entry) => entry.label === label &&
+      ['width', 'height'].every((key) => Math.abs(entry.bounds[key] - bounds[key]) <= 1))
+    .map((entry) => entry.testId));
+  return testIds.size === 1 ? [...testIds][0] : undefined;
+}
+
 function isApplicationRole(role) {
   return role?.toLowerCase().includes('application') ?? false;
 }

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

@@ -1,4 +1,5 @@
 // Select a wallet account by address, ID, or name and verify the resulting selection.
+// A name with no internal account match falls back to AccountTreeController group names.
 // Observe ambiguous bridge write failures until the deadline without repeating the switch.
 import { pathToFileURL } from 'node:url';
 import {
@@ -34,13 +35,13 @@ function withRemainingDeadline(input, deadline, attemptTimeoutMs) {
   };
 }
 
-async function readSelectedAccount(input, deadline) {
+async function readBridge(input, deadline, args, timeoutMessage) {
   let lastError = null;
   while (Date.now() < deadline) {
     try {
       return await bridgeCommand(
         withRemainingDeadline(input, deadline, READ_ATTEMPT_TIMEOUT_MS),
-        ['get-selected-account'],
+        args,
       );
     } catch (error) {
       if (!TRANSIENT_READ_CODES.has(error?.code)) throw error;
@@ -48,24 +49,34 @@ async function readSelectedAccount(input, deadline) {
       await sleep(Math.min(100, Math.max(0, deadline - Date.now())));
     }
   }
-  throw lastError ?? new Error('Timed out reading the selected Mobile account.');
+  throw lastError ?? new Error(timeoutMessage);
 }
 
-async function readAccounts(input, deadline) {
-  let lastError = null;
-  while (Date.now() < deadline) {
-    try {
-      return await bridgeCommand(
-        withRemainingDeadline(input, deadline, READ_ATTEMPT_TIMEOUT_MS),
-        ['list-accounts'],
-      );
-    } catch (error) {
-      if (!TRANSIENT_READ_CODES.has(error?.code)) throw error;
-      lastError = error;
-      await sleep(Math.min(100, Math.max(0, deadline - Date.now())));
+const readSelectedAccount = (input, deadline) =>
+  readBridge(input, deadline, ['get-selected-account'], 'Timed out reading the selected Mobile account.');
+
+const readAccounts = (input, deadline) =>
+  readBridge(input, deadline, ['list-accounts'], 'Timed out reading Mobile accounts.');
+
+// Multichain wallets name the account group, not always the internal account.
+async function findAccountByGroupName(input, deadline, accounts, name) {
+  const wallets = await readBridge(
+    input,
+    deadline,
+    ['get-state', 'engine.backgroundState.AccountTreeController.accountTree.wallets'],
+    'Timed out reading Mobile account groups.',
+  );
+  const groups = [];
+  for (const wallet of Object.values(wallets && typeof wallets === 'object' ? wallets : {})) {
+    for (const [groupId, group] of Object.entries(wallet?.groups ?? {})) {
+      if (group?.metadata?.name === name) groups.push({ id: groupId, accounts: group.accounts ?? [] });
     }
   }
-  throw lastError ?? new Error('Timed out reading Mobile accounts.');
+  if (groups.length > 1) {
+    throw new Error(`Requested mobile account name ${JSON.stringify(name)} matches ${groups.length} account groups; select by address instead.`);
+  }
+  const match = accounts.find((account) => groups[0]?.accounts.includes(account?.id));
+  return match ? { ...match, accountGroup: { id: groups[0].id, name } } : null;
 }
 
 function ambiguousWriteFailure(writeError, match, finalSelected, readError) {
@@ -98,7 +109,7 @@ export async function selectAccount(input) {
   if (!Array.isArray(accounts)) {
     throw new Error(`metamask.wallet.select_account expected list-accounts to return an array, got ${typeof accounts}.`);
   }
-  const match = accounts.find((account) => {
+  let match = accounts.find((account) => {
     const address = String(account?.address ?? '').toLowerCase();
     const id = String(account?.id ?? '');
     const name = String(account?.name ?? '');
@@ -106,8 +117,11 @@ export async function selectAccount(input) {
       (requestedId && id === requestedId) ||
       (requestedName && name === requestedName);
   });
+  if (!match && requestedName) {
+    match = await findAccountByGroupName(input, deadline, accounts, requestedName);
+  }
   if (!match?.address) {
-    throw new Error(`Requested mobile account was not found in list-accounts: ${JSON.stringify({ address: requestedAddress, id: requestedId, name: requestedName })}`);
+    throw new Error(`Requested mobile account was not found in list-accounts or account groups: ${JSON.stringify({ address: requestedAddress, id: requestedId, name: requestedName })}`);
   }
   const current = await readSelectedAccount(input, deadline);
   const matchAddress = String(match.address).toLowerCase();
@@ -118,6 +132,7 @@ export async function selectAccount(input) {
         address: current?.address ?? match.address,
         id: current?.id ?? match.id,
         name: current?.name ?? match.name,
+        ...(match.accountGroup ? { accountGroup: match.accountGroup } : {}),
       },
       alreadySelected: true,
       proofPath: 'agentic-account-selection',
@@ -172,6 +187,7 @@ export async function selectAccount(input) {
       address: selected?.address ?? result?.address ?? match.address,
       id: selected?.id ?? result?.id ?? match.id,
       name: selected?.name ?? result?.name ?? match.name,
+      ...(match.accountGroup ? { accountGroup: match.accountGroup } : {}),
     },
     ...(ambiguousWriteError
       ? { recoveredAfterAmbiguousWrite: true }

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

@@ -1321,7 +1321,7 @@
       ]
     },
     "metamask.perps.close_positions": {
-      "description": "core Close selected live Perps positions on HyperLiquid testnet by driving the headless perps controller closePosition() through the full signing/provider path. Testnet only. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
+      "description": "core Close selected live Perps positions by driving the headless perps controller closePosition() through the full signing/provider path. Testnet by default; mainnet needs network: mainnet and CORE_PERPS_ALLOW_MAINNET_WRITES=1. Pre-existing testnet state on an account the task owns is converged, not refused.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1591,7 +1591,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_positions": {
-      "description": "core Higher-level wrapper that reads selected positions, places or closes via the headless controller as needed, then asserts the final position state. Testnet only. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
+      "description": "core Higher-level wrapper that reads selected positions, places or closes via the headless controller as needed, then asserts the final position state. Testnet by default; mainnet needs network: mainnet and CORE_PERPS_ALLOW_MAINNET_WRITES=1, and placing follows the shared Perps order rule. Pre-existing testnet state on an account the task owns is converged, not refused.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1744,7 +1744,7 @@
       ]
     },
     "metamask.perps.close_orders": {
-      "description": "Core Perps cancellation selects current orders by market/side or mode=all, then dispatches and verifies those exact order IDs. Missing or duplicate selected IDs fail before dispatch. Requires authorized signing and task-owned selection; defaults to testnet. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
+      "description": "Core Perps cancellation selects current orders by market/side or mode=all, then dispatches and verifies those exact order IDs. Missing or duplicate selected IDs fail before dispatch. Requires authorized signing and task-owned selection. Testnet by default; mainnet needs network: mainnet and CORE_PERPS_ALLOW_MAINNET_WRITES=1. Pre-existing testnet state on an account the task owns is converged, not refused.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2078,7 +2078,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_orders": {
-      "description": "core Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested.Higher-level wrapper that reads selected orders, cancels when needed, then asserts final order state. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
+      "description": "core Higher-level wrapper that reads selected orders, cancels when needed, then asserts final order state. Testnet by default; mainnet needs network: mainnet and CORE_PERPS_ALLOW_MAINNET_WRITES=1. An open state is a resting limit order, which the shared Perps order rule refuses on mainnet. Pre-existing testnet state on an account the task owns is converged, not refused.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2233,7 +2233,7 @@
       ]
     },
     "metamask.perps.start_state": {
-      "description": "core Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested.Recommended configurable Perps start state that composes reusable domain operations before the proof window. Headless: converges POSITION and ORDER baselines on testnet via the controller; no navigation/page/HUD.",
+      "description": "core Recommended configurable Perps start state that composes reusable domain operations before the proof window. Headless: converges POSITION and ORDER baselines via the controller; no navigation/page/HUD. Testnet by default; mainnet needs network: mainnet and CORE_PERPS_ALLOW_MAINNET_WRITES=1, and orders follow the shared Perps order rule.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2554,7 +2554,7 @@
       ]
     },
     "metamask.perps.teardown_state": {
-      "description": "core Recommended configurable Perps teardown state that restores the selected environment after proof. Headless: converges POSITION and ORDER baselines on testnet via the controller; no navigation/page/HUD.",
+      "description": "core Recommended configurable Perps teardown state that restores the selected environment after proof. Headless: converges POSITION and ORDER baselines via the controller; no navigation/page/HUD. Testnet by default; mainnet needs network: mainnet and CORE_PERPS_ALLOW_MAINNET_WRITES=1.",
       "schema": {
         "type": "object",
         "properties": {

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

@@ -4131,7 +4131,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.close_orders": {
-      "description": "extension Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action. Mainnet is never mutated.",
+      "description": "extension Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. On mainnet, cancel is refused in the fixture-policy lane and needs the funded release lane. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action.",
       "schema": {
         "type": "object",
         "properties": {

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

@@ -2522,7 +2522,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.close_positions": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Close selected live Perps positions. Use selector/mode params to close matching symbols or all positions. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
+      "description": "mobile Close selected live Perps positions on the app's current Perps network, with no mainnet opt-in. Use selector/mode params to close matching symbols or all positions. Pre-existing testnet state on an account the task owns is converged, not refused.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2613,7 +2613,7 @@
       "execution_capabilities": ["app-mutation", "external-mutation"]
     },
     "metamask.perps.close_orders": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
+      "description": "mobile Cancel selected live Perps open orders on the app's current Perps network, with no mainnet opt-in. Use selector/mode params to cancel matching symbols or all orders. Pre-existing testnet state on an account the task owns is converged, not refused.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3025,7 +3025,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_positions": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Higher-level wrapper that reads selected positions, closes or places when needed, then asserts final position state. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
+      "description": "mobile Higher-level wrapper that reads selected positions, closes or places when needed, then asserts final position state. Acts on the app's current Perps network: closing has no mainnet opt-in, and placing follows the shared Perps order rule, so it cannot leave a position open on mainnet. Pre-existing testnet state on an account the task owns is converged, not refused.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3141,7 +3141,7 @@
       "execution_capabilities": ["app-mutation", "external-mutation"]
     },
     "metamask.perps.ensure_orders": {
-      "description": "mobile Converge selected testnet orders to open or absent, then independently assert the final state. Creating an open state uses a resting limit order. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
+      "description": "mobile Converge selected testnet orders to open or absent, then independently assert the final state. Creating an open state uses a resting limit order, which the shared Perps order rule refuses on mainnet; cancelling acts on the app's current Perps network with no mainnet opt-in. Pre-existing testnet state on an account the task owns is converged, not refused.",
       "schema": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.85.0",
+  "version": "0.86.1",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -21,15 +21,15 @@
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
   },
   "dependencies": {
-    "@farmslot/adapter-node": "0.1.6",
-    "@farmslot/adapter-rn": "0.19.3",
-    "@farmslot/adapter-sdk": "0.8.0",
-    "@farmslot/adapter-web": "0.6.4",
+    "@farmslot/adapter-node": "0.1.7",
+    "@farmslot/adapter-rn": "0.19.4",
+    "@farmslot/adapter-sdk": "0.8.1",
+    "@farmslot/adapter-web": "0.6.5",
     "@farmslot/agent-runtime": "0.17.1",
     "@farmslot/handoff": "^0.3.1",
     "@farmslot/protocol": "0.35.0",
-    "@farmslot/recipe-cli": "0.11.0",
-    "@farmslot/recipe-runner": "0.28.0",
+    "@farmslot/recipe-cli": "0.11.1",
+    "@farmslot/recipe-runner": "0.28.1",
     "agent-device": "0.19.3",
     "commander": "^12.0.0",
     "esbuild": "0.28.1",

package/scripts/completions.sh

@@ -45,8 +45,8 @@ _mmh_flags_for() {
     execution-template) printf '%s' "--dir --domain-dir --project-worker --project-name --package-templates --package-id --flow --run-mode --platform --domain --id --provenance --include-shadowed --no-include-shadowed --title --force --json" ;;
     recipe-quality) printf '%s' "--input --output --recipe --task --evidence --params --adapter --library --advisor --advisor-model --advisor-stages --json" ;;
     actions)  printf '%s' "--adapter --action --kind --raw --action-manifest --target --json" ;;
-    call)     printf '%s' "--list --domain --source --sort --adapter --target --artifacts-dir --action-manifest --heal --json" ;;
-    run)      printf '%s' "--list --domain --source --sort --describe --plan --adapter --artifacts-dir --target --library --cdp-port --heal --record-video --json" ;;
+    call)     printf '%s' "--list --domain --source --sort --adapter --target --artifacts-dir --action-manifest --heal --hud --json" ;;
+    run)      printf '%s' "--list --domain --source --sort --describe --plan --adapter --artifacts-dir --target --library --cdp-port --heal --record-video --hud --json" ;;
     doctor)   printf '%s' "--adapter --target --fix --json" ;;
     install|verify|cleanup) printf '%s' "--adapter --target --json" ;;
     *)        printf '%s' "" ;;

package/site/assets/help-recipes.json

@@ -201,7 +201,7 @@
         "Analytics: verify the collection destination and existing consent before capture. Changing participation or marketing consent requires operator approval and restoration of the prior settings; a recipe's hardcoded opt-in is not permission. Missing collection prerequisites are not missing product events.",
         "Flake risk: wait on observable state instead of sleeping, keep device and runtime identity explicit, and never overwrite a prior run's artifacts.",
         "Mutation: require an independent state assertion and identity-bound receipt. Bind activity to that operation's accepted ID; an old row or nonzero count is insufficient. Opening and closing orders have different IDs. Schedule authorized cleanup in teardown, verify its result, and report any residue. Testnet cleanup closes what the task opened and never silently undoes another task's live proof on a reserved account or market.",
-        "Testnet account state: on a testnet account or market the task owns for its run (the slot's fixture account, or one reserved with exclusive_testnet_market=true), converging is an explicit, ownership-scoped setup choice, not a violation. Use the team library's perps.ensure-market-state or perps.clean-market-testnet, or on Mobile and Core metamask.perps.ensure_positions / metamask.perps.ensure_orders (mode=all for strays), record what was closed in the trace, then prove. A pre-existing position or order on an account the task owns is never a reason to block, skip, or refuse, and a fixture that demands an empty account must converge rather than refuse. Extension ensure_* and teardown_state only assert; converge there through an explicitly funded leaf action. Never broaden cleanup onto an account or market the task does not own; obtain an owned one instead of blocking. Mainnet is read-only.",
+        "Testnet account state: on a testnet account or market the task owns for its run (the slot's fixture account, or one reserved with exclusive_testnet_market=true), converging is an explicit, ownership-scoped setup choice, not a violation. Use the team library's perps.ensure-market-state or perps.clean-market-testnet, or on Mobile and Core metamask.perps.ensure_positions / metamask.perps.ensure_orders (mode=all for strays), record what was closed in the trace, then prove. A pre-existing position or order on an account the task owns is never a reason to block, skip, or refuse, and a fixture that demands an empty account must converge rather than refuse. Extension ensure_* and teardown_state only assert; converge there through an explicitly funded leaf action. Never broaden cleanup onto an account or market the task does not own; obtain an owned one instead of blocking. On mainnet, orders follow the shared Perps order rule (PERPS_MAINNET_ORDER_REFUSED), Core needs CORE_PERPS_ALLOW_MAINNET_WRITES=1 for any write, Mobile cleanup acts on whatever network the app is on, and Extension refuses mainnet writes other than orders and `close_visible_position` in the fixture-policy lane.",
         {
           "text": "An accepted order can fill before the UI updates. Preserve its receipt even when the expected resting-order assertion fails; one empty read does not prove cleanup. Check the read API's cache and freshness options before adding polling. Reconcile returned margin against the pre-placement balance. A successful close does not turn the original failed proof into a pass.",
           "adapters": [