@deeeed/metamask-harness 0.9.1 → 0.11.0

package/dist/commands/run-engine.js

@@ -97,6 +97,7 @@ function recipeRunEnv(adapter, runtimeOptions = {}) {
     METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
     IOS_SIMULATOR: process.env.IOS_SIMULATOR,
     ANDROID_DEVICE: process.env.ANDROID_DEVICE,
+    ANDROID_TARGET_DEVICE_NAME: process.env.ANDROID_TARGET_DEVICE_NAME,
     ADB_SERIAL: process.env.ADB_SERIAL,
     ANDROID_SERIAL: process.env.ANDROID_SERIAL
   };
@@ -139,19 +140,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 +180,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 +221,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/dist/mm-harness-cli.js

@@ -411,6 +411,7 @@ Example:
   --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
+  --device <udid|serial|name>        Mobile only: target this device for sync/set
   --json                             Machine-readable output
 
 Example:

package/dist/paths.js

@@ -113,6 +113,12 @@ async function importRecipeHarnessRuntimeCdp() {
     "packages/recipe-harness/src/runtime/cdp.ts"
   );
 }
+async function importRecipeHarnessAppLifecycle() {
+  return importProtocolPackage(
+    "@farmslot/recipe-harness/adapters/app-lifecycle",
+    "packages/recipe-harness/src/adapters/app-lifecycle.ts"
+  );
+}
 async function importRecipeHarnessRuntimeBrowserExtension() {
   return importProtocolPackage(
     "@farmslot/recipe-harness/runtime/browser-extension",
@@ -154,7 +160,7 @@ async function importProtocolPackage(packageName, localSourceEntry) {
 function isMissingPackageError(error, packageName) {
   if (!(error instanceof Error)) return false;
   const code = error.code;
-  return code === "ERR_MODULE_NOT_FOUND" && error.message.includes(packageName);
+  return (code === "ERR_MODULE_NOT_FOUND" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED") && error.message.includes(packageName);
 }
 export {
   DEFAULT_RECIPE_HARNESS_ROOT,
@@ -162,6 +168,7 @@ export {
   assertAdapter,
   extensionIdPath,
   importRecipeHarness,
+  importRecipeHarnessAppLifecycle,
   importRecipeHarnessCli,
   importRecipeHarnessRuntimeBrowserExtension,
   importRecipeHarnessRuntimeCdp,

package/dist/runner.js

@@ -1,8 +1,9 @@
 import { execSync } from "node:child_process";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
+import { resolveMetaMaskMobileLifecycleTarget } from "./app-lifecycle.js";
 import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from "./manifest.js";
 import { createMetaMaskRecordingTargetProvider } from "./recording-target.js";
-import { importRecipeHarness, importRecipeHarnessRuntimeCdp, importRecipeHarnessRuntimeReactNativeBridge, runnerDir } from "./paths.js";
+import { importRecipeHarness, importRecipeHarnessAppLifecycle, importRecipeHarnessRuntimeCdp, importRecipeHarnessRuntimeReactNativeBridge, runnerDir } from "./paths.js";
 async function createMetaMaskMobileRunner(options = {}) {
   return createMetaMaskRunner(
     "mobile",
@@ -23,13 +24,14 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   } = await importRecipeHarness();
   const { createCdpWebUiTransport } = await importRecipeHarnessRuntimeCdp();
   const { createReactNativeBridgeUiTransport } = await importRecipeHarnessRuntimeReactNativeBridge();
+  const { createAppLifecycleAdapters } = await importRecipeHarnessAppLifecycle();
   const actions = [
     ...actionManifest.supported_official_actions,
     ...(actionManifest.custom_actions ?? []).map((entry) => entry.name)
   ];
   const declaredActions = new Set(actions);
   const core = createStandardCoreAdapters({ actions });
-  const projectOwnedOfficialActions = /* @__PURE__ */ new Set(["app.status"]);
+  const projectOwnedOfficialActions = /* @__PURE__ */ new Set(["app.status", "app.lifecycle"]);
   const ui = createStandardUiAdapters({
     actions: actions.filter((action) => !projectOwnedOfficialActions.has(action)),
     transport: createMetaMaskUiTransport(adapter, {
@@ -38,14 +40,18 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     })
   });
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
+  const lifecycle = adapter === "mobile" ? createAppLifecycleAdapters({
+    actions,
+    targetProvider: { resolveTarget: resolveMetaMaskMobileLifecycleTarget }
+  }) : [];
   const custom = createMetaMaskAdapters(adapter).filter(
-    (entry) => declaredActions.has(entry.action) && !existing.has(entry.action)
+    (entry) => declaredActions.has(entry.action) && !existing.has(entry.action) && !lifecycle.some((lifecycleEntry) => lifecycleEntry.action === entry.action)
   );
   const autoHudDisabled = process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false";
   const logger = options.quietStdout ? new console.Console(process.stderr) : console;
   return createRecipeRunner({
     actionManifest,
-    adapters: [...core, ...ui, ...custom],
+    adapters: [...core, ...ui, ...lifecycle, ...custom],
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter)

package/docs/CLI-SPEC.md

@@ -439,7 +439,7 @@ 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`. 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'`.
+`--device` is the uniform mobile device selector on `run`, `call`, `doctor`, and `fixtures`. 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).
 
@@ -447,6 +447,7 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 |---|---|---|
 | `run` / `call` | resolve id → set serial/simulator env; proceed | **ambiguity gate:** >1 connected mobile device (across both android and ios, counting only targetable ones: android state `device`, iOS state `Booted`) → fail fast (exit 2), listing connected devices and `--device <id>` hints. Exactly one targetable (or zero — existing engine errors speak) → unchanged behavior. |
 | `doctor` | resolve id → set env | no gate — doctor is diagnostic and **reports** the device list (`devices[]`) instead. |
+| `fixtures` | resolve id → set serial/simulator env before sync/set and recovery relaunch | no gate — preserves existing single-device and ambient slot behavior. |
 
 `--device` on the **extension/core** adapter is a teaching usage error (those adapters have no device to target). `run --plan` is static (touches no device) and is exempt from the gate.
 

package/docs/recipe-libraries.md

@@ -93,3 +93,206 @@ 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
+
+# Canonical start-state variants — same installed app, no rebuild.
+mm-harness run app-lifecycle-android-smoke \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/lifecycle-smoke
+mm-harness run perps-performance-warm-start \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/warm
+mm-harness run perps-performance-background-resume \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/background
+mm-harness run perps-performance-cold-start \
+  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/cold
+
+# 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.
+
+Run `app-lifecycle-android-smoke` first when validating a new Android slot; it
+isolates lifecycle control from wallet setup and Perps navigation. The start-state
+variants use the standard outer `app.lifecycle` action. Every
+variant begins with `app.status` so `trace.json` records an idempotent start
+marker before lifecycle setup and Perps timing nodes. Android background resume
+sends HOME, then relaunches through the Expo dev-client deep link. Cold start
+force-stops the installed package, then launches the same build through the deep
+link.
+
+### 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

@@ -71,10 +71,14 @@ export async function bridgeEnv(input) {
   const watcherPort = target.watcherPort;
   const simulator = target.iosSimulator;
   const androidDevice = target.androidDevice;
+  const androidTargetDeviceName = target.androidTargetDeviceName;
   const adbSerial = target.adbSerial;
   if (watcherPort !== undefined && watcherPort !== null && String(watcherPort) !== '') env.WATCHER_PORT = String(watcherPort);
   if (simulator !== undefined && simulator !== null && String(simulator) !== '') env.IOS_SIMULATOR = String(simulator);
   if (androidDevice !== undefined && androidDevice !== null && String(androidDevice) !== '') env.ANDROID_DEVICE = String(androidDevice);
+  if (androidTargetDeviceName !== undefined && androidTargetDeviceName !== null && String(androidTargetDeviceName) !== '') {
+    env.ANDROID_TARGET_DEVICE_NAME = String(androidTargetDeviceName);
+  }
   if (adbSerial !== undefined && adbSerial !== null && String(adbSerial) !== '') {
     env.ADB_SERIAL = String(adbSerial);
     env.ANDROID_SERIAL = String(adbSerial);
@@ -93,6 +97,20 @@ export async function bridgeEnv(input) {
       env.ANDROID_TARGET_DEVICE_NAME = model;
     }
   }
+  if (serialStr) {
+    // 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;
 }
 
@@ -101,8 +119,74 @@ function resolveMobileTarget(input) {
   const watcherPort = input.node?.watcher_port ?? input.node?.metro_port ?? input.node?.cdp_port ?? contextEnv.WATCHER_PORT ?? contextEnv.CDP_PORT ?? contextEnv.RECIPE_CDP_PORT ?? process.env.WATCHER_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
   const iosSimulator = input.node?.simulator ?? input.node?.ios_simulator ?? contextEnv.IOS_SIMULATOR ?? process.env.IOS_SIMULATOR;
   const androidDevice = input.node?.android_device ?? contextEnv.ANDROID_DEVICE ?? process.env.ANDROID_DEVICE;
+  const androidTargetDeviceName = input.node?.android_target_device_name ?? input.node?.androidTargetDeviceName ?? contextEnv.ANDROID_TARGET_DEVICE_NAME ?? process.env.ANDROID_TARGET_DEVICE_NAME;
   const adbSerial = input.node?.adb_serial ?? contextEnv.ADB_SERIAL ?? contextEnv.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL ?? androidDevice;
-  return { watcherPort, iosSimulator, androidDevice, adbSerial };
+  return { watcherPort, iosSimulator, androidDevice, androidTargetDeviceName, adbSerial };
+}
+
+function androidDeviceNameMatches(deviceName, targetName) {
+  if (!targetName) return false;
+  return deviceName === targetName || deviceName.startsWith(`${targetName} -`);
+}
+
+// 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) {
+  const entries = Array.isArray(status)
+    ? status.filter((entry) => entry && typeof entry === 'object')
+    : (status && typeof status === 'object' ? [status] : []);
+  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 androidTargetDeviceName = target.androidTargetDeviceName != null ? String(target.androidTargetDeviceName) : '';
+  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 && (androidTargetDeviceName || androidDevice === adbSerial || !androidDevice)) {
+    const android = entries.filter((entry) => entry.platform === 'android');
+    if (androidTargetDeviceName) {
+      const matchesAndroidTargetNameEntry = (entry) => {
+        const deviceName = String(entry.deviceName ?? '');
+        return androidDeviceNameMatches(deviceName, androidTargetDeviceName);
+      };
+      const byName = android.filter(matchesAndroidTargetNameEntry);
+      if (byName.length === 1) return byName[0];
+      const byModelName = entries.filter(matchesAndroidTargetNameEntry);
+      if (byModelName.length === 1) return byModelName[0];
+    }
+    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) => androidDeviceNameMatches(String(entry.deviceName ?? ''), 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.
@@ -129,9 +213,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;