@deeeed/metamask-harness 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.10.0 - 2026-07-07
+
+### Added
+- **Canonical `perps-performance` measured flow** (`library/recipes/perps-performance.mobile.recipe.json`): unlock → open the Perps market list → read live state → open a market detail — one node per user-visible step with stable node names, so the per-node `duration`s in `trace.json` are the timings you monitor. Run pinned: `mm-harness run perps-performance --device <serial> --heal off`. Device-proven end-to-end on a physical Pixel.
+- **`run <name>` resolves personal/team recipe libraries.** Previously only the packaged library was probed by name; custom recipes ran by path. Sources resolve in library-precedence order (personal > team shadow the packaged canonical — a same-named personal recipe wins), path-shaped args never probe libraries, and a miss teaches which sources were searched. Zero-flag default: `$FARMSLOT_HOME/recipe-library`.
+- **Custom-library walkthrough** ("Your own measured flow" in `docs/recipe-libraries.md`): a peer engineer scaffolds a personal library, copies the canonical flow, retargets the nodes to their journey, and runs it by name. Every step is executed by the `perps-performance-recipe` contract test, so the doc cannot drift from reality.
+- **`call` declared on mobile and extension manifests** (was core-only) with self-discovery metadata — personal `flows/` segments are now usable from mobile/extension recipes. Honest limitation documented: flows carry no adapter dimension in the protocol yet, so a cross-adapter `call` fails at live-run rather than plan time.
+
+### Fixed
+- **A `--device` pin wins target selection end-to-end on dual-platform slots.** Three independently sufficient holes let a pinned android run drive the iOS simulator (observed live): the discovery simulator filter ran before the android pin and the slot's ambient `IOS_SIMULATOR` captured the candidate set; pins were only enforced when more than one candidate existed (a single WRONG candidate was silently accepted); and the wallet actions' status-entry selectors checked the ambient simulator identity first while never matching serials against Metro device names. Fixed at every layer with live-repro contract cases; an unmatchable pin fails fast listing the Metro candidates.
+
 ## 0.9.1 - 2026-07-07
 
 ### Fixed

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -114,9 +114,24 @@ async function discoverTarget(port) {
         /bridgeless|hermes/i.test(t.description || '')),
   );
 
-  // Filter by device name if IOS_SIMULATOR is set
+  // Android pin identities (loaded before the simulator filter so an explicit
+  // android pin can take precedence over an ambient simulator name):
+  //   ANDROID_TARGET_DEVICE_NAME — Metro-compatible model prefix resolved by bridge.mjs
+  //     from the adb serial via `adb -s <serial> shell getprop ro.product.model`.
+  //     Example: "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36".
+  //   ANDROID_DEVICE — exact Metro deviceName (backward compat / user-specified).
+  const androidTargetName = loadAndroidTargetDeviceName();
+  const androidDevice = loadAndroidDevice();
+  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
+  const androidPinned = Boolean(androidTargetName || androidDevice);
+
+  // Filter by simulator name if IOS_SIMULATOR is set — but never when an android
+  // pin is present: dual-platform slots carry an ambient IOS_SIMULATOR in their
+  // context, and letting it win here sends a pinned android action to the iOS
+  // target. No-match keeps the full candidate set (ambient sim configs tolerate a
+  // sim that is not currently attached).
   const simName = loadSimulatorName();
-  if (simName && candidates.length > 1) {
+  if (simName && !androidPinned && candidates.length > 1) {
     const deviceFiltered = candidates.filter(
       (t) => t.deviceName === simName,
     );
@@ -125,20 +140,13 @@ async function discoverTarget(port) {
     }
   }
 
-  // Android device filtering: support two identity layers.
-  //   ANDROID_TARGET_DEVICE_NAME — Metro-compatible model prefix resolved by bridge.mjs
-  //     from the adb serial via `adb -s <serial> shell getprop ro.product.model`.
-  //     Example: "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36".
-  //   ANDROID_DEVICE — exact Metro deviceName (backward compat / user-specified).
-  //
-  // When a device is pinned and multiple candidates remain, we MUST NOT silently fall
-  // back to another target (e.g. an iOS simulator). If the pin cannot be matched,
-  // fail fast with diagnostics so the operator can diagnose the mismatch.
-  const androidTargetName = loadAndroidTargetDeviceName();
-  const androidDevice = loadAndroidDevice();
-  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
-
-  if (candidates.length > 1) {
+  // Android pin enforcement — at ANY candidate count. A pin gated on
+  // candidates.length > 1 silently accepted a single WRONG candidate (observed
+  // live: the pinned Pixel's target dropped off Metro while the iOS target
+  // remained; the pin was ignored and the recipe drove the simulator). When a
+  // device is pinned, we MUST NOT silently fall back to another target; an
+  // unmatchable pin fails fast with diagnostics.
+  if (androidPinned && candidates.length > 0) {
     let androidFiltered = [];
 
     if (androidTargetName) {

package/dist/adapters/extension/runtime.js

@@ -275,9 +275,8 @@ function runProcess(command, args, options) {
       if (settled) return;
       settled = true;
       child.kill("SIGTERM");
-      setTimeout(() => {
-        if (!child.killed) child.kill("SIGKILL");
-      }, 1e3);
+      const killTimer = setTimeout(() => child.kill("SIGKILL"), 1e3);
+      child.once("close", () => clearTimeout(killTimer));
       resolve({ exitCode: null, stdout, stderr, timedOut: true });
     }, options.timeoutMs) : void 0;
     child.stdout.on("data", (chunk) => {

package/dist/commands/device-target.js

@@ -4,9 +4,13 @@ function setAndroidDeviceEnv(id) {
   process.env.ADB_SERIAL = id;
   process.env.ANDROID_SERIAL = id;
   process.env.ANDROID_DEVICE = id;
+  process.env.IOS_SIMULATOR = "";
 }
 function setIosDeviceEnv(id) {
   process.env.IOS_SIMULATOR = id;
+  process.env.ADB_SERIAL = "";
+  process.env.ANDROID_SERIAL = "";
+  process.env.ANDROID_DEVICE = "";
 }
 function formatConnectedDevices(devices) {
   return devices.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n");

package/dist/commands/run-engine.js

@@ -139,19 +139,30 @@ function isRecipeFile(p) {
     return false;
   }
 }
-function resolveRunRecipeArg(recipeArg, adapter) {
+function resolveRunRecipeArg(recipeArg, adapter, librarySources) {
   const direct = path.resolve(recipeArg);
   if (isRecipeFile(direct)) return { recipeFile: direct };
   if (!recipeArg.includes("/") && !recipeArg.includes(path.sep)) {
-    for (const name of [`${recipeArg}.${adapter}.recipe.json`, `${recipeArg}.recipe.json`, recipeArg]) {
-      const file = recipePath(name);
-      if (isRecipeFile(file)) return { recipeFile: file };
+    const candidates = [`${recipeArg}.${adapter}.recipe.json`, `${recipeArg}.recipe.json`, recipeArg];
+    if (librarySources && librarySources.length > 0) {
+      for (const source of librarySources) {
+        for (const candidate of candidates) {
+          const file = path.join(source.root, "recipes", candidate);
+          if (isRecipeFile(file)) return { recipeFile: file };
+        }
+      }
+    } else {
+      for (const candidate of candidates) {
+        const file = recipePath(candidate);
+        if (isRecipeFile(file)) return { recipeFile: file };
+      }
     }
   }
-  const names = libraryRecipeNames(adapter);
-  return {
-    notFound: `recipe not found: ${recipeArg} \u2014 not a file, and no packaged library recipe matched. ` + (names.length > 0 ? `Library recipes for ${adapter}: ${names.join(", ")} (mm-harness run <name>).` : `The packaged library has no recipes for ${adapter}.`)
-  };
+  const packagedNames = libraryRecipeNames(adapter);
+  const nonCanonical = librarySources?.filter((s) => s.name !== "metamask") ?? [];
+  const notFoundCore = nonCanonical.length > 0 ? `recipe not found: ${recipeArg} \u2014 not a file, and no recipe matched in library sources [${librarySources.map((s) => s.name ?? path.basename(s.root)).join(", ")}].` : `recipe not found: ${recipeArg} \u2014 not a file, and no packaged library recipe matched.`;
+  const suffix = packagedNames.length > 0 ? ` Library recipes for ${adapter}: ${packagedNames.join(", ")} (mm-harness run <name>).` : ` The packaged library has no recipes for ${adapter}.`;
+  return { notFound: notFoundCore + suffix };
 }
 function libraryRecipeNames(adapter) {
   let entries;
@@ -168,9 +179,18 @@ function libraryRecipeNames(adapter) {
   return [...new Set(names)].sort();
 }
 async function validateRunRecipeStatic(recipeArg, adapter, options) {
-  const resolved = resolveRunRecipeArg(recipeArg, adapter);
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const resolved = resolveRunRecipeArg(recipeArg, adapter, librarySources);
   const recipeFile = "recipeFile" in resolved ? resolved.recipeFile : path.resolve(recipeArg);
-  const empty = { recipe: void 0, recipeFile, findings: [], errorCount: 0, manifestOk: false, schemaValid: false };
+  const empty = {
+    recipe: void 0,
+    recipeFile,
+    findings: [],
+    errorCount: 0,
+    manifestOk: false,
+    schemaValid: false,
+    ...librarySources ? { librarySources } : {}
+  };
   if ("notFound" in resolved) {
     return { ...empty, usageError: { code: "RECIPE_NOT_FOUND", message: resolved.notFound } };
   }
@@ -200,11 +220,18 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
       message: error instanceof Error ? error.message : String(error)
     });
   }
-  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
   const validation = manifestOk ? await validateRecipeAdapterAware(recipe, manifest, librarySources) : { status: "invalid", findings: [], summary: { errors: 1, warnings: 0 } };
   findings.push(...validation.findings);
   const errorCount = findings.filter((finding) => finding.severity === "error").length;
-  return { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid: validation.status === "valid" };
+  return {
+    recipe,
+    recipeFile,
+    findings,
+    errorCount,
+    manifestOk,
+    schemaValid: validation.status === "valid",
+    ...librarySources ? { librarySources } : {}
+  };
 }
 async function resolveMetaMaskLibrarySources(libraryEntry) {
   const harness = await importRecipeHarness();

package/dist/commands/run.js

@@ -15,7 +15,6 @@ import {
   emitHealViolation,
   executeWithHealBounds,
   prepareHeal,
-  resolveMetaMaskLibrarySources,
   runRecipe,
   validateRunRecipeStatic
 } from "./run-engine.js";
@@ -43,7 +42,7 @@ async function handleRun({ positional, options }) {
   if (validated.errorCount > 0) {
     return emitRunValidationError(json, adapter, validated.recipeFile, validated.findings, validated.errorCount);
   }
-  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const librarySources = validated.librarySources;
   const runtimeOptions = {
     ...runtimeOptionsFromCli(options),
     ...librarySources ? { librarySources } : {},

package/dist/live-adapter-contract.js

@@ -100,9 +100,8 @@ function runProcess(command, args, options) {
       if (settled) return;
       settled = true;
       child.kill("SIGTERM");
-      setTimeout(() => {
-        if (!child.killed) child.kill("SIGKILL");
-      }, 1e3);
+      const killTimer = setTimeout(() => child.kill("SIGKILL"), 1e3);
+      child.once("close", () => clearTimeout(killTimer));
       resolve({ exitCode: null, stdout, stderr, timedOut: true });
     }, options.timeoutMs) : void 0;
     child.on("error", (error) => {

package/docs/recipe-libraries.md

@@ -93,3 +93,187 @@ and a small flow budget. If a flow is team- or task-specific, it belongs in a
 team or personal library — that is what the precedence order is for.
 `scripts/check.mjs` validates every committed catalog against the action
 manifests.
+
+## Your own measured flow: creating a personal recipe library
+
+A **measured flow** is a recipe you run the same way every time to watch how long
+each user-visible step takes. The runner has no benchmark verb: timings are just
+the per-node `duration`s in a passing run's `trace.json`, so a flow is comparable
+across runs only when you pin the run (same device, healing off) and keep the node
+graph stable. The repo ships one canonical example,
+`library/recipes/perps-performance.mobile.recipe.json` — unlock → open the Perps
+market list → read live state → open a market detail. This walkthrough copies it
+into a library of your own and retargets it to your journey. A peer engineer can
+follow it verbatim; the same steps run as the `perps-performance-recipe` contract
+test.
+
+### 1. Scaffold a personal library
+
+A library is a directory with a `library.json` marker. Keep reusable `flows/`
+(referenced via `call`) beside a `recipes/` folder for the full flows you run:
+
+```bash
+mkdir -p ~/my-recipes/flows ~/my-recipes/recipes
+cat > ~/my-recipes/library.json <<'JSON'
+{ "kind": "recipe-library", "schema_version": 1, "name": "mydev", "owner": "mydev" }
+JSON
+```
+
+In real use this is discovered for you: with no `--library` flag and no
+`RECIPE_LIBRARY_PATH`, the runner reads your personal library at
+`$FARMSLOT_HOME/recipe-library` (default `~/.farmslot/recipe-library`). The
+explicit `--library mydev=<dir>` form below is the same mechanism, spelled out so
+it works headlessly (CI, a scratch checkout) and so the path is unambiguous.
+
+### 2. Copy the canonical recipe as a starting point
+
+Copy it out of your runner checkout's `library/recipes/`:
+
+```bash
+cp library/recipes/perps-performance.mobile.recipe.json \
+   ~/my-recipes/recipes/my-perps-performance.mobile.recipe.json
+```
+
+### 3. Edit the nodes to your journey
+
+Open the copy and change what you measure while keeping the measured-flow shape.
+Retarget `open-market-detail` to your market and add one extra measured step —
+here, reading live orders on the detail screen:
+
+```jsonc
+"open-market-detail": {
+  "action": "ui.navigate",
+  "page": "perps-market",
+  "market": "ETH",                       // was BTC
+  "intent": "Open the ETH Perps market detail screen",
+  "next": "read-orders"                  // was "end"
+},
+"read-orders": {                         // your extra measured step
+  "action": "metamask.perps.read_orders",
+  "market": "ETH",
+  "intent": "Read live ETH orders on the market detail screen",
+  "next": "end"
+}
+```
+
+The canonical recipe keeps its nodes inline — a clean measured baseline. For
+bigger journeys you can extract repeated setup steps into a personal `flows/`
+segment and `call` it. For example, define an unlock + open-Perps-list segment
+in `~/my-recipes/flows/mydev.flows.json`:
+
+```json
+{
+  "schema_version": 1, "kind": "recipe-flow-catalog", "owner": "mydev",
+  "flows": {
+    "mydev.open_perps_setup": {
+      "version": 1,
+      "description": "Unlock the wallet and open the Perps market list.",
+      "workflow": {
+        "entry": "ensure-unlocked",
+        "nodes": {
+          "ensure-unlocked": {
+            "action": "metamask.wallet.ensure_unlocked",
+            "intent": "Unlock the wallet before the Perps journey",
+            "next": "open-perps-list"
+          },
+          "open-perps-list": {
+            "action": "ui.navigate",
+            "page": "perps",
+            "intent": "Open the Perps market list screen",
+            "next": "done"
+          },
+          "done": { "action": "end", "status": "pass" }
+        }
+      }
+    }
+  }
+}
+```
+
+Then replace the two inline setup nodes in your recipe with a single `call` node:
+
+```jsonc
+"setup": {
+  "action": "call",
+  "ref": "mydev.open_perps_setup",
+  "intent": "Run the personal Perps setup segment (unlock + open list)",
+  "next": "read-positions"
+}
+```
+
+The segment validates via `--plan` — the plan step verifies the `call` ref
+resolves from the library. Keep flow segment actions within the mobile action
+surface: the flow catalog format has no `platform`/`adapter` dimension today,
+so a flow using a core-only action (e.g. `command`) will pass `--plan` on mobile
+but fail at live-run time with "No adapter registered for flow action X". There
+is no plan-time cross-adapter enforcement; that gap would require an `adapters`
+field on flow catalog entries — not yet in the protocol.
+
+### 4. Run it and read the timings
+
+Validate statically **by name** first — `run` probes each library source's `recipes/`
+directory in precedence order (personal → team → canonical), so `my-perps-performance`
+resolves from `~/my-recipes/recipes/` without you spelling out the path:
+
+```bash
+# Static validation by NAME — resolves from the personal library via --library.
+mm-harness run my-perps-performance \
+  --library mydev=~/my-recipes --plan --adapter mobile
+
+# Zero-flag personal-library: when ~/my-recipes is placed at
+# $FARMSLOT_HOME/recipe-library (default ~/.farmslot/recipe-library), the runner
+# discovers it automatically and run-by-name works without --library:
+mm-harness run my-perps-performance --plan --adapter mobile
+
+# Pinned live run — same device, healing OFF, so durations are comparable.
+mm-harness run my-perps-performance \
+  --library mydev=~/my-recipes \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts
+
+# Per-node durations to diff across runs (trace.json is an array of entries, or
+# { metadata, entries: [...] }; each entry carries nodeId + durationMs):
+node -e 'const t=require("./artifacts/trace.json"); \
+  for (const e of Array.isArray(t)?t:t.entries) console.log(e.nodeId, e.durationMs)'
+```
+
+A miss with `--library` names the sources that were searched, so you can tell at a
+glance whether a typo or a missing library entry caused the failure.
+
+### The measured-flow pattern
+
+Five rules keep timings meaningful and diffable:
+
+1. **Pin the run** — `--device <serial> --heal off`. Healing retries hide the
+   regressions you are trying to measure.
+2. **One node per user-visible step** — a node's `duration` is only a signal when
+   it maps to a single thing the user sees.
+3. **Stable, human-meaningful node keys** — operators diff node keys across runs;
+   renaming `open-market-detail` breaks every historical comparison.
+4. **No destructive side effects** — a measured flow should be repeatable. The
+   canonical recipe stops at read + navigate; add `place_order`/`close` only in a
+   personal copy when you deliberately want to measure the trade path.
+5. **Read timings from `trace.json`, not the console** — the trace is the durable
+   per-node record; the console is for humans watching the run.
+
+### Shadowing, in practice
+
+Because `--library` sources resolve `call` refs before the canonical `metamask`
+library, a personal flow named like a canonical one shadows it — your history is
+the point. You can watch this happen on mobile with the segment recipe from the
+walkthrough above:
+
+```bash
+# A mobile recipe with "action": "call", "ref": "mydev.open_perps_setup"
+# fails without the library source…
+mm-harness run my-perps-with-segment --plan --adapter mobile
+#   → workflow.unresolved_call_ref
+
+# …and resolves once the personal library is on the path:
+mm-harness run my-perps-with-segment --plan --adapter mobile \
+  --library "mydev=~/my-recipes"
+#   → plan pass
+```
+
+That resolution — unresolved without the source, `pass` with it — is what the
+`perps-performance-recipe` contract test asserts, alongside the canonical recipe
+resolving by name and the personal mobile copy planning by path and basename.

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

@@ -92,6 +92,18 @@ export async function bridgeEnv(input) {
     if (model) {
       env.ANDROID_TARGET_DEVICE_NAME = model;
     }
+    // ANDROID_DEVICE === ADB_SERIAL is the explicit --device android pin shape
+    // (device-target.ts / launch --device). Slots hosting BOTH platforms carry an
+    // ambient IOS_SIMULATOR in their context env, which spreads over process.env
+    // above and would win target discovery's simulator filter — sending a pinned
+    // android action to the iOS target. An explicit android pin suppresses the
+    // ambient simulator identity.
+    // LOAD-BEARING: device-target.ts also clears IOS_SIMULATOR, but
+    // resolveSlotPorts re-injects the slot context over process.env afterwards —
+    // this re-clear (running last, on the child env actually handed to the
+    // bridge) is what actually protects the pin. Keep it even if the CLI-level
+    // clear looks redundant.
+    env.IOS_SIMULATOR = '';
   }
   return env;
 }
@@ -105,6 +117,56 @@ function resolveMobileTarget(input) {
   return { watcherPort, iosSimulator, androidDevice, adbSerial };
 }
 
+// Select THIS action's entry from a multi-target bridge `status` reply (the bridge
+// probes every RN target on Metro, so dual-device slots return an array). Single
+// source of truth for wallet actions — the previous per-action copies checked the
+// ambient IOS_SIMULATOR before the android pin and only ever exact-matched serials
+// against Metro deviceNames (which are model descriptors, never serials), so a
+// pinned android run selected the iOS entry on dual-platform slots.
+export function selectBridgeStatusEntry(status, input) {
+  if (!Array.isArray(status)) {
+    return status && typeof status === 'object' ? status : null;
+  }
+  const entries = status.filter((entry) => entry && typeof entry === 'object');
+  if (entries.length === 0) return null;
+  const target = resolveMobileTarget(input);
+  const adbSerial = target.adbSerial != null ? String(target.adbSerial) : '';
+  const androidDevice = target.androidDevice != null ? String(target.androidDevice) : '';
+  const iosSimulator = target.iosSimulator != null ? String(target.iosSimulator) : '';
+
+  // Explicit android pin shape (--device <serial> sets ANDROID_DEVICE === ADB_SERIAL).
+  // Checked BEFORE the simulator identity: dual-platform slots inject an ambient
+  // IOS_SIMULATOR that must not capture a pinned android action.
+  if (adbSerial && androidDevice === adbSerial) {
+    const android = entries.filter((entry) => entry.platform === 'android');
+    if (android.length === 1) return android[0];
+    if (android.length > 1) {
+      // Two android targets can't be told apart by serial here (Metro deviceNames
+      // are model descriptors); prefer the usable one.
+      return android.find((entry) => entry.account) ?? android[0];
+    }
+    // Pinned android but no android entry answered — failing fast beats letting the
+    // caller read the iOS entry and report misleading wallet state.
+    throw new Error(
+      `Pinned android device ${adbSerial} has no responding bridge target.\n` +
+      `  Bridge status entries:\n` +
+      entries.map((entry) => `    - ${entry.deviceName ?? '?'} [${entry.platform || 'unknown'}]`).join('\n') +
+      `\n  Next: mm-harness launch android   # bring the app back to the foreground`,
+    );
+  }
+  if (iosSimulator) {
+    const sim = entries.find((entry) => entry.deviceName === iosSimulator);
+    if (sim) return sim;
+  }
+  if (androidDevice) {
+    const byName = entries.find(
+      (entry) => entry.deviceName === androidDevice || String(entry.deviceName ?? '').startsWith(androidDevice),
+    );
+    if (byName) return byName;
+  }
+  return entries.find((entry) => entry.account) ?? entries[0];
+}
+
 // Commands where a transient undefined/empty stdout means "not yet settled", not failure.
 // get-route returns undefined mid-navigation when the route state is momentarily unavailable;
 // waitForRoute polls through these nulls rather than aborting on a parse error.
@@ -129,9 +191,12 @@ export async function bridgeCommand(input, args) {
         if (settled) return;
         settled = true;
         child.kill('SIGTERM');
-        setTimeout(() => {
-          if (!child.killed) child.kill('SIGKILL');
-        }, 1000);
+        // Always escalate after the grace period: child.killed only records that
+        // kill() was CALLED, not that the process exited, so gating SIGKILL on it
+        // never fires and a SIGTERM-ignoring child leaks. The close listener
+        // cancels the escalation when the child exits in time.
+        const killTimer = setTimeout(() => child.kill('SIGKILL'), 1000);
+        child.once('close', () => clearTimeout(killTimer));
         resolve({ exitCode: null, stdout, stderr, timedOut: true, timeoutMs });
       }, timeoutMs)
       : null;

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

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';
 
 async function fixturePassword(projectRoot) {
@@ -34,29 +34,8 @@ function routeName(status, input) {
   return route && typeof route === 'object' ? String(route.name ?? '') : '';
 }
 
-function selectedStatus(status, input) {
-  if (!Array.isArray(status)) {
-    return status && typeof status === 'object' ? status : null;
-  }
-  const preferredDevices = [
-    input.node?.ios_simulator,
-    input.node?.simulator,
-    input.node?.android_device,
-    input.node?.adb_serial,
-    process.env.IOS_SIMULATOR,
-    process.env.ANDROID_DEVICE,
-    process.env.ADB_SERIAL,
-  ].filter((value) => typeof value === 'string' && value.length > 0);
-  for (const preferredDevice of preferredDevices) {
-    const match = status.find((entry) => entry?.deviceName === preferredDevice);
-    if (match) return match;
-  }
-  return (
-    status.find((entry) => entry?.account) ??
-    status.find((entry) => entry && typeof entry === 'object') ??
-    null
-  );
-}
+// selectedStatus: shared pin-aware entry selection (see selectBridgeStatusEntry).
+const selectedStatus = selectBridgeStatusEntry;
 
 async function status(input) {
   return bridgeCommand(input, ['status']);

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

@@ -1,28 +1,7 @@
-import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 
-function selectedStatus(status, input) {
-  if (!Array.isArray(status)) {
-    return status && typeof status === 'object' ? status : null;
-  }
-  const preferredDevices = [
-    input.node?.ios_simulator,
-    input.node?.simulator,
-    input.node?.android_device,
-    input.node?.adb_serial,
-    process.env.IOS_SIMULATOR,
-    process.env.ANDROID_DEVICE,
-    process.env.ADB_SERIAL,
-  ].filter((value) => typeof value === 'string' && value.length > 0);
-  for (const preferredDevice of preferredDevices) {
-    const match = status.find((entry) => entry?.deviceName === preferredDevice);
-    if (match) return match;
-  }
-  return (
-    status.find((entry) => entry?.account) ??
-    status.find((entry) => entry && typeof entry === 'object') ??
-    null
-  );
-}
+// selectedStatus: shared pin-aware entry selection (see selectBridgeStatusEntry).
+const selectedStatus = selectBridgeStatusEntry;
 
 runAdapter(async (input) => {
   const status = selectedStatus(await bridgeCommand(input, ['status']), input);

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

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { bridgeCommand, bridgeEnv, runAdapter } from '../platform/bridge.mjs';
+import { bridgeCommand, bridgeEnv, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';
 
 async function fixtureProfile(projectRoot) {
@@ -77,29 +77,8 @@ function mnemonicAccountCount(account, fixturePath, index) {
   return count;
 }
 
-function selectedStatus(status, input) {
-  if (!Array.isArray(status)) {
-    return status && typeof status === 'object' ? status : null;
-  }
-  const preferredDevices = [
-    input.node?.ios_simulator,
-    input.node?.simulator,
-    input.node?.android_device,
-    input.node?.adb_serial,
-    process.env.IOS_SIMULATOR,
-    process.env.ANDROID_DEVICE,
-    process.env.ADB_SERIAL,
-  ].filter((value) => typeof value === 'string' && value.length > 0);
-  for (const preferredDevice of preferredDevices) {
-    const match = status.find((entry) => entry?.deviceName === preferredDevice);
-    if (match) return match;
-  }
-  return (
-    status.find((entry) => entry?.account) ??
-    status.find((entry) => entry && typeof entry === 'object') ??
-    null
-  );
-}
+// selectedStatus: shared pin-aware entry selection (see selectBridgeStatusEntry).
+const selectedStatus = selectBridgeStatusEntry;
 
 function hasSelectedAccount(status, input) {
   return Boolean(selectedStatus(status, input)?.account);
@@ -138,9 +117,12 @@ async function runSetupWallet(input, fixture) {
             if (settled) return;
             settled = true;
             child.kill('SIGTERM');
-            setTimeout(() => {
-              if (!child.killed) child.kill('SIGKILL');
-            }, 1000);
+            // Always escalate after the grace period: child.killed only records
+            // that kill() was CALLED, not that the process exited, so gating
+            // SIGKILL on it never fires and a SIGTERM-ignoring child leaks. The
+            // close listener cancels the escalation when the child exits in time.
+            const killTimer = setTimeout(() => child.kill('SIGKILL'), 1000);
+            child.once('close', () => clearTimeout(killTimer));
             reject(
               new Error(
                 `Mobile setup-wallet.sh timed out after ${timeoutMs}ms.`,

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

@@ -11,6 +11,7 @@
     "watch_logs",
     "index_artifacts",
     "end",
+    "call",
     "ui.navigate",
     "ui.press",
     "ui.key_press",
@@ -724,6 +725,18 @@
           }
         }
       ]
+    },
+    "call": {
+      "description": "Invoke a named sub-recipe flow by ref and run its steps inline.",
+      "examples": [
+        {
+          "node": {
+            "action": "call",
+            "ref": "mydev.open_perps_setup",
+            "intent": "Run a personal Perps setup flow segment"
+          }
+        }
+      ]
     }
   },
   "custom_actions": [

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

@@ -11,6 +11,7 @@
     "watch_logs",
     "index_artifacts",
     "end",
+    "call",
     "ui.navigate",
     "ui.press",
     "ui.key_press",
@@ -724,6 +725,18 @@
           }
         }
       ]
+    },
+    "call": {
+      "description": "Invoke a named sub-recipe flow by ref and run its steps inline.",
+      "examples": [
+        {
+          "node": {
+            "action": "call",
+            "ref": "mydev.open_perps_setup",
+            "intent": "Run a personal Perps setup flow segment"
+          }
+        }
+      ]
     }
   },
   "custom_actions": [

package/library/recipes/perps-performance.mobile.recipe.json

@@ -0,0 +1,50 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps performance flow",
+  "description": "Canonical measured flow for MetaMask Mobile Perps: unlock, open the Perps market list, read live state, and open a market's detail — one node per user-visible step so operators can diff per-node durations across runs. Timings live in trace.json as each node's duration; there is no built-in benchmark verb. Run pinned so numbers are comparable: `mm-harness run perps-performance --device <serial> --heal off`. Optional testnet order placement is intentionally omitted: the recipe DSL has no cheap skippable/conditional node, so a live order would make the flow destructive and non-repeatable; add metamask.perps.place_order + close in a personal copy when you want to measure the trade path.",
+  "validate": {
+    "workflow": {
+      "entry": "ensure-unlocked",
+      "nodes": {
+        "ensure-unlocked": {
+          "action": "metamask.wallet.ensure_unlocked",
+          "intent": "Unlock the wallet before timing the Perps journey",
+          "detail": "Unlock only if the app is currently locked so the first measured node starts from a stable, signed-in state.",
+          "flow": "setup",
+          "next": "open-perps-list"
+        },
+        "open-perps-list": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "intent": "Open the Perps market list screen",
+          "detail": "Navigate to the Perps markets list via the stable page alias; its node duration measures market-list render time.",
+          "flow": "perps",
+          "next": "read-positions"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "intent": "Read the live Perps positions shown on the market list",
+          "detail": "Read live Perps positions through the controller; its node duration measures how long live account state takes to resolve. Mobile has no read_markets action, so read_positions is the canonical read of on-screen live state.",
+          "flow": "perps",
+          "next": "open-market-detail"
+        },
+        "open-market-detail": {
+          "action": "ui.navigate",
+          "page": "perps-market",
+          "market": "BTC",
+          "intent": "Open the BTC Perps market detail screen",
+          "detail": "Navigate to the BTC market detail via the stable page alias; its node duration measures market-detail render time.",
+          "flow": "perps",
+          "next": "end"
+        },
+        "end": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the measured Perps performance flow",
+          "detail": "Terminal node; the passing run's trace.json holds the per-node durations to diff across runs.",
+          "flow": "complete"
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"