@deeeed/metamask-harness 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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
+- **Metro survives the launching shell.** `start-metro.sh` spawned Metro without SIGHUP protection, so closing the launching tmux window/shell killed it, leaving a stale `metro.pid` and hanging every subsequent bridge/fixtures call. Metro now starts under `nohup` (argv spawn, no `bash -c` string interpolation), and a stale `metro.pid` naming a dead process is detected and cleaned before start.
+- **`--device <adb serial>` reaches CDP target selection.** The runner's ambiguity gate resolved the serial, but target discovery compared it against Metro's `deviceName` ("Pixel 6 - 16 - API 36") — never a serial — so with an iOS simulator also attached, a recipe pinned to the physical Android device could silently drive the simulator. The serial is now mapped to the Metro identity via `adb -s <serial> shell getprop ro.product.model` with model-prefix matching (scoped to non-simulator targets); an unmatchable or ambiguous pin (two same-model devices) fails fast listing every Metro `/json/list` candidate instead of silently picking one. `--device <serial>` remains the only thing users pass.
+- **Bridge commands always emit valid JSON.** `get-route` printed the literal string `undefined` when the route was transiently unavailable mid-navigation, so `bridgeCommand()` threw on parse and `waitForRoute()` aborted instead of polling. `get-route`/`navigate`/`go-back` now normalise a missing route to `null`, `bridgeCommand()` treats `''`/`undefined` stdout as not-settled-yet only for transient-legitimate commands, and `waitForRoute()` polls through `null` until timeout — the timeout error carries the expected route, last parsed route, last bridge reply and the device pin.
+- **Wallet setup env propagation.** `bridgeEnv()` became async with the serial mapping; the wallet setup action now awaits it instead of spreading a Promise, which would have handed `setup-wallet.sh` an almost-empty environment.
+
 ## 0.9.0 - 2026-07-07
 
 ### Added

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -104,7 +104,17 @@ const COMMANDS = {
       client,
       'globalThis.__AGENTIC__?.getRoute()',
     );
-    return { navigated: routeName, params, previousRoute, currentRoute, deviceName, platform };
+    // Normalize route values: cdpEval returns undefined when the optional-chain
+    // short-circuits (mid-navigation transient or bridge not yet installed).
+    // null is valid JSON; undefined produces the literal string "undefined".
+    return {
+      navigated: routeName,
+      params,
+      previousRoute: previousRoute ?? null,
+      currentRoute: currentRoute ?? null,
+      deviceName,
+      platform,
+    };
   },
 
   async 'get-route'(client) {
@@ -112,7 +122,10 @@ const COMMANDS = {
       client,
       'globalThis.__AGENTIC__?.getRoute()',
     );
-    return route;
+    // cdpEval returns undefined when the optional-chain short-circuits (bridge not
+    // yet installed, mid-navigation, or route state transiently missing). Return null
+    // so JSON.stringify produces valid JSON ("null") instead of literal "undefined".
+    return route ?? null;
   },
 
   async 'get-state'(client, args) {
@@ -168,7 +181,9 @@ const COMMANDS = {
       client,
       'globalThis.__AGENTIC__?.getRoute()',
     );
-    return { currentRoute: route, deviceName, platform };
+    // Same normalization as navigate/get-route: a transiently-missing route must
+    // serialize as "currentRoute": null, not have the key silently omitted.
+    return { currentRoute: route ?? null, deviceName, platform };
   },
 
   async status(client, _args, { deviceName, platform } = {}) {

package/adapters/mobile/bridge-runtime/lib/config.cjs

@@ -30,10 +30,22 @@ function loadSimulatorName() {
   return loadEnvValue('IOS_SIMULATOR') || '';
 }
 
-/** Read ANDROID_DEVICE serial from .js.env or env (default: none — accept any device) */
+/** Read ANDROID_DEVICE from .js.env or env (default: none — accept any device) */
 function loadAndroidDevice() {
   if ('ANDROID_DEVICE' in process.env) return process.env.ANDROID_DEVICE;
   return loadEnvValue('ANDROID_DEVICE') || '';
 }
 
-module.exports = { loadEnvValue, loadPort, loadSimulatorName, loadAndroidDevice };
+/**
+ * Read ANDROID_TARGET_DEVICE_NAME from env — the Metro-compatible model prefix
+ * resolved from an adb serial by bridge.mjs. Used by target-discovery to select
+ * the correct Metro CDP target when multiple devices are connected.
+ *
+ * Set automatically by the bridge when --device <serial> is used. Users never
+ * need to set this; pass --device <adb-serial> and the harness maps it internally.
+ */
+function loadAndroidTargetDeviceName() {
+  return process.env.ANDROID_TARGET_DEVICE_NAME || '';
+}
+
+module.exports = { loadEnvValue, loadPort, loadSimulatorName, loadAndroidDevice, loadAndroidTargetDeviceName };

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

@@ -1,7 +1,7 @@
 'use strict';
 
 const http = require('node:http');
-const { loadSimulatorName, loadAndroidDevice } = require('./config.cjs');
+const { loadSimulatorName, loadAndroidDevice, loadAndroidTargetDeviceName } = require('./config.cjs');
 const { createWSClient } = require('./ws-client.cjs');
 
 const FETCH_TIMEOUT_MS = Number.parseInt(process.env.CDP_TIMEOUT || '30000', 10);
@@ -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,14 +140,69 @@ async function discoverTarget(port) {
     }
   }
 
-  // Filter by device name if ANDROID_DEVICE is set
-  const androidDevice = loadAndroidDevice();
-  if (androidDevice && candidates.length > 1) {
-    const deviceFiltered = candidates.filter(
-      (t) => t.deviceName === androidDevice,
-    );
-    if (deviceFiltered.length > 0) {
-      candidates = deviceFiltered;
+  // 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) {
+      // Model prefix match: "Pixel 6" matches "Pixel 6 - 16 - API 36". Metro's
+      // /json/list has no explicit platform field, so scope the ANDROID pin by
+      // excluding the one iOS identity we do know (the pinned simulator name) —
+      // a simulator named to shadow a model string must not satisfy an android pin.
+      androidFiltered = candidates.filter(
+        (t) => t.deviceName !== simName &&
+               (t.deviceName === androidTargetName ||
+                (t.deviceName != null && t.deviceName.startsWith(androidTargetName))),
+      );
+      if (androidFiltered.length > 1) {
+        // Two same-model devices produce identical Metro model prefixes — the pin
+        // is genuinely ambiguous; picking one silently is exactly the bug this
+        // path exists to prevent.
+        const ambiguousList = androidFiltered
+          .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
+          .join('\n');
+        throw new Error(
+          `Pinned Android device is ambiguous: model '${androidTargetName}' matches ${androidFiltered.length} Metro targets.\n` +
+          `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
+          `  Matching Metro targets:\n${ambiguousList}\n` +
+          `  Set ANDROID_DEVICE to the exact Metro deviceName to disambiguate.`,
+        );
+      }
+      if (androidFiltered.length === 0) {
+        // Pinned device could not be matched — never silently pick another target.
+        const candidateList = targets
+          .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
+          .join('\n');
+        throw new Error(
+          `Pinned Android device did not match any Metro target.\n` +
+          `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
+          `  Resolved model (ANDROID_TARGET_DEVICE_NAME): ${androidTargetName}\n` +
+          `  ANDROID_DEVICE: ${androidDevice || '(not set)'}\n` +
+          `  Metro /json/list candidates:\n${candidateList}`,
+        );
+      }
+      candidates = androidFiltered;
+    } else if (androidDevice) {
+      // Exact Metro deviceName match (user set ANDROID_DEVICE to the Metro name, or
+      // legacy path where ANDROID_DEVICE was not resolved from serial).
+      androidFiltered = candidates.filter((t) => t.deviceName === androidDevice);
+      if (androidFiltered.length === 0) {
+        // Pinned by exact Metro name but no candidate matched — fail fast.
+        const candidateList = targets
+          .map((t) => `  deviceName=${JSON.stringify(t.deviceName || '')} ws=${t.webSocketDebuggerUrl || ''}`)
+          .join('\n');
+        throw new Error(
+          `Pinned Android device (ANDROID_DEVICE='${androidDevice}') did not match any Metro target.\n` +
+          `  ADB_SERIAL: ${adbSerial || '(not set)'}\n` +
+          `  Metro /json/list candidates:\n${candidateList}`,
+        );
+      }
+      candidates = androidFiltered;
     }
   }
 

package/adapters/mobile/start-metro.sh

@@ -79,6 +79,18 @@ default_metro_workers() {
 
 # --- main ---------------------------------------------------------------------
 
+# Detect stale metro.pid: if the pid file names a dead process, clean it up.
+# A stale file survives when Metro is killed externally (session close, SIGKILL)
+# and the normal stop path never ran. Cleaning it here keeps metro_ready and the
+# log from attributing a new start to the old process id.
+if [ -f "$PID_FILE" ]; then
+  stale_pid="$(cat "$PID_FILE" 2>/dev/null || true)"
+  if [ -n "$stale_pid" ] && ! kill -0 "$stale_pid" 2>/dev/null; then
+    printf 'start-metro: stale metro.pid (pid %s no longer alive); cleaning up\n' "$stale_pid" >&2
+    rm -f "$PID_FILE"
+  fi
+fi
+
 # Decide whether to (re)start or skip.
 if metro_ready; then
   if [ "$CLEAR" = true ]; then
@@ -97,11 +109,11 @@ fi
 stop_metro_listener || exit 1
 
 METRO_WORKERS="${METRO_MAX_WORKERS:-$(default_metro_workers)}"
-CLEAR_SUFFIX=""
-[ "$CLEAR" = true ] && CLEAR_SUFFIX=" --clear"
+CLEAR_LABEL=""
+[ "$CLEAR" = true ] && CLEAR_LABEL=", clear"
 
 printf 'Starting Metro on port %s (workers=%s%s)\n' \
-  "$PORT" "$METRO_WORKERS" "${CLEAR:+, clear}" >&2
+  "$PORT" "$METRO_WORKERS" "$CLEAR_LABEL" >&2
 printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FILE" >&2
 
 # Metro runs detached, writing to the log. The tmux window is a read-only tail.
@@ -127,12 +139,17 @@ printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FIL
   export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
   export METRO_MAX_WORKERS="${METRO_WORKERS}"
   # shellcheck disable=SC2094
-  bash -c "exec yarn expo start --port ${PORT}${CLEAR_SUFFIX}" \
+  # nohup sets SIGHUP to ignored (inherited across exec), so Metro survives the
+  # launching shell or tmux window closing; when this subshell exits the process
+  # is reparented to init. That alone is the detach guarantee — Metro was never
+  # in the parent shell's job table, so there is nothing to disown.
+  # nohup.out is suppressed (stdout/stderr both go to $LOG_FILE via >>).
+  metro_args=(expo start --port "$PORT")
+  [ "$CLEAR" = true ] && metro_args+=(--clear)
+  nohup yarn "${metro_args[@]}" \
     </dev/null >> "$LOG_FILE" 2>&1 &
   echo "$!" > "$PID_FILE"
 )
-# Disown the background process so it outlives this script.
-disown "$(cat "$PID_FILE" 2>/dev/null || true)" 2>/dev/null || true
 
 start_viewer_window "$LOG_FILE"
 

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/CLI-SPEC.md

@@ -439,7 +439,9 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 ## `--device <id>` — first-class mobile device targeting (REAL)
 
-`--device` is the uniform mobile device selector on `run`, `call`, and `doctor`. It sets the **same env `launch` does** before the engine reads `process.env`, so the engine needs no changes: an Android serial → `ADB_SERIAL` + `ANDROID_SERIAL` + `ANDROID_DEVICE`; an iOS UDID/simulator name → `IOS_SIMULATOR`. The android-vs-ios decision comes from matching the id against the connected-device lists (`adb devices -l` + booted `xcrun simctl` simulators); an id that matches neither list is a teaching usage error that lists the connected devices.
+`--device` is the uniform mobile device selector on `run`, `call`, and `doctor`. Pass the **adb serial** for Android (from `adb devices`) or the **UDID / simulator name** for iOS. The harness resolves the adb serial to the Metro CDP target identity internally — users never need to know or set `ANDROID_DEVICE='Pixel 6 - 16 - API 36'`.
+
+**Internal Android identity mapping**: `ADB_SERIAL` / `ANDROID_SERIAL` carry the raw adb serial. The bridge resolves the device model via `adb -s <serial> shell getprop ro.product.model` and propagates it as `ANDROID_TARGET_DEVICE_NAME`. Target-discovery uses `ANDROID_TARGET_DEVICE_NAME` for Metro `deviceName` prefix matching (e.g. `"Pixel 6"` matches `"Pixel 6 - 16 - API 36"`). When the pinned model cannot be matched to any Metro `/json/list` candidate and multiple candidates exist, the bridge fails fast with a diagnostic listing every candidate's `deviceName` — it never silently selects the wrong device. iOS UDID/simulator name → `IOS_SIMULATOR` (unchanged).
 
 | Verb | `--device` given | `--device` omitted (mobile) |
 |---|---|---|

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

@@ -1,8 +1,11 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const execFileAsync = promisify(execFile);
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -34,7 +37,30 @@ function runtimeDir() {
   return fileURLToPath(new URL('../../../../adapters/mobile/bridge-runtime', import.meta.url));
 }
 
-export function bridgeEnv(input) {
+/**
+ * Resolve the Android model name from an adb serial.
+ * Returns the trimmed ro.product.model value, or null when adb is unavailable
+ * or the serial does not respond. Uses execFile (never shell interpolation).
+ */
+async function resolveAndroidModel(adbSerial) {
+  try {
+    const { stdout } = await execFileAsync(
+      'adb',
+      ['-s', adbSerial, 'shell', 'getprop', 'ro.product.model'],
+      { timeout: 5000, encoding: 'utf8' },
+    );
+    const model = stdout.trim();
+    return model || null;
+  } catch {
+    // Recovery is correct: model resolution for Metro target selection is advisory.
+    // If adb is unavailable or the serial is unreachable, discovery falls through to
+    // the exact ANDROID_DEVICE match or probe-and-pick. The error will surface from
+    // the CDP connection attempt if the wrong target is selected.
+    return null;
+  }
+}
+
+export async function bridgeEnv(input) {
   /** @type {NodeJS.ProcessEnv} */
   const env = {
     ...process.env,
@@ -53,6 +79,32 @@ export function bridgeEnv(input) {
     env.ADB_SERIAL = String(adbSerial);
     env.ANDROID_SERIAL = String(adbSerial);
   }
+  // When --device passes an adb serial, device-target.ts sets both ANDROID_DEVICE and
+  // ADB_SERIAL to the same value. ANDROID_DEVICE must be the Metro deviceName for
+  // target-discovery to select the right CDP target; it cannot be a raw adb serial.
+  // Resolve the device model via adb getprop and propagate it as
+  // ANDROID_TARGET_DEVICE_NAME so target-discovery can match by model prefix
+  // (e.g. "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36").
+  const serialStr = adbSerial != null ? String(adbSerial) : '';
+  const deviceStr = androidDevice != null ? String(androidDevice) : '';
+  if (serialStr && deviceStr === serialStr) {
+    const model = await resolveAndroidModel(serialStr);
+    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;
 }
 
@@ -65,13 +117,70 @@ 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.
+const TRANSIENT_NULL_COMMANDS = new Set(['get-route']);
+
 export async function bridgeCommand(input, args) {
   const script = bridgeScript(input);
+  // bridgeEnv is async: it may call `adb getprop` to resolve the Metro device name.
+  const env = await bridgeEnv(input);
   const result = await new Promise((resolve, reject) => {
     const timeoutMs = Number(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? 30000);
     const child = spawn(process.execPath, [script, ...args], {
       cwd: input.context.projectRoot,
-      env: { ...bridgeEnv(input), APP_ROOT: input.context.projectRoot },
+      env: { ...env, APP_ROOT: input.context.projectRoot },
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     let stdout = '';
@@ -82,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;
@@ -111,6 +223,14 @@ export async function bridgeCommand(input, args) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
     throw new Error(`Mobile CDP bridge command failed: ${command}\n${redactBridgeOutput(result.stderr || result.stdout, sensitiveBridgeArgs(args))}`);
   }
+  // For transient commands, stdout of '' or 'undefined' means the state is not yet
+  // settled (e.g. mid-navigation). Return null so callers like waitForRoute can poll
+  // rather than aborting on a JSON parse error.
+  const command = String(args[0] ?? '');
+  const trimmedStdout = result.stdout.trim();
+  if ((trimmedStdout === '' || trimmedStdout === 'undefined') && TRANSIENT_NULL_COMMANDS.has(command)) {
+    return null;
+  }
   try {
     const parsed = JSON.parse(result.stdout);
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.ok === false) {
@@ -195,13 +315,35 @@ function routeName(route) {
 export async function waitForRoute(input, expectedRoute, timeoutMs = 15000) {
   const expected = String(expectedRoute);
   const deadline = Date.now() + timeoutMs;
+  // lastRoute is null when bridgeCommand returns null (transient: route not yet
+  // settled mid-navigation). Null means "not ready yet" — keep polling.
   let lastRoute = null;
+  let pollCount = 0;
   while (Date.now() < deadline) {
     lastRoute = await bridgeCommand(input, ['get-route']);
     if (routeName(lastRoute) === expected) return lastRoute;
+    pollCount += 1;
     await sleep(250);
   }
-  throw new Error(`Timed out waiting for Mobile route ${expected}; last route was ${JSON.stringify(lastRoute)}`);
+  const target = resolveMobileTarget(input);
+  const deviceHint = [
+    target.adbSerial && `ADB_SERIAL=${target.adbSerial}`,
+    target.androidDevice && target.androidDevice !== target.adbSerial && `ANDROID_DEVICE=${target.androidDevice}`,
+    target.iosSimulator && `IOS_SIMULATOR=${target.iosSimulator}`,
+  ].filter(Boolean).join(', ') || 'no device pin';
+  // bridgeCommand already parsed (or null-normalized) the reply, so raw stdout is
+  // not available here — describe the reply honestly instead of relabeling the
+  // parsed value as "raw".
+  const lastReply = lastRoute === null
+    ? 'empty/undefined (route transiently unavailable — bridge not yet settled)'
+    : JSON.stringify(lastRoute);
+  throw new Error(
+    `Timed out waiting for Mobile route '${expected}' after ${timeoutMs}ms (${pollCount} polls).\n` +
+    `  Expected route: ${expected}\n` +
+    `  Last parsed route: ${JSON.stringify(lastRoute)}\n` +
+    `  Last bridge reply: ${lastReply}\n` +
+    `  Device: ${deviceHint}`,
+  );
 }
 
 export async function simulatorScreenshot(input, relPath) {

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);
@@ -112,7 +91,10 @@ function setupWalletScript() {
   return fileURLToPath(new URL('../../../../adapters/mobile/bridge-runtime/setup-wallet.sh', import.meta.url));
 }
 
-function runSetupWallet(input, fixture) {
+async function runSetupWallet(input, fixture) {
+  // bridgeEnv is async (it may shell adb to resolve the Metro device name);
+  // spreading its un-awaited Promise would hand the child an almost-empty env.
+  const env = await bridgeEnv(input);
   return new Promise((resolve, reject) => {
     const timeoutMs = Number(
       input.node?.setup_timeout_ms ?? input.node?.timeout_ms ?? 120000,
@@ -122,7 +104,7 @@ function runSetupWallet(input, fixture) {
       [setupWalletScript(), '--fixture', fixture.absolutePath],
       {
         cwd: input.context.projectRoot,
-        env: { ...bridgeEnv(input), CDP_TIMEOUT: String(timeoutMs), APP_ROOT: input.context.projectRoot },
+        env: { ...env, CDP_TIMEOUT: String(timeoutMs), APP_ROOT: input.context.projectRoot },
         stdio: ['ignore', 'pipe', 'pipe'],
       },
     );
@@ -135,9 +117,12 @@ 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.0",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"