@deeeed/metamask-harness 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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
+- **`status` auto-probes live app state per device** — the `yarn a:status` successor. Static info prints instantly; within a strict 2s window each device line is enriched with `screen=` (active route via the `__AGENTIC__` bridge, Route objects normalised), `wallet=locked|unlocked|onboarding`, `account=<label> (0x1234…abcd)` and `fixture=READY|missing`. `--fast` skips all probes (guaranteed-instant for scripts); `--json` carries the enriched `devices[]` in one envelope. All RN targets attached to the checkout's Metro are probed and matched per device (exact id → exact name → platform-uniqueness → leftover 1:1), so android + ios side by side on one Metro both report. Honest degradation: `no-bridge` (nothing matched/answering) vs `bridge-absent` (target attached but the installed build predates `__AGENTIC__`, rendered with a rebuild hint) — surfacing pre-bridge builds required the target discovery probe to become three-state (agentic/responsive/unreachable) instead of silently dropping them.
+- **Every action now carries self-discovery metadata.** `action_metadata` (description + example recipe node, derived from the real handler implementations) covers all official and custom actions across the mobile, extension and core manifests — previously `app.status`, `cdp.target` and all 16 `metamask.wallet.*`/`metamask.perps.*` actions were bare names to agents. A new contract guard enforces coverage (including example structure: `node.action` must match), and locks mobile ↔ extension action-set parity with an explicit platform-only allowlist.
+
 ## 0.8.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,15 +181,18 @@ 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 } = {}) {
     const expr = `(function() {
+      var agenticPresent = typeof globalThis.__AGENTIC__ !== 'undefined';
       var route = globalThis.__AGENTIC__?.getRoute() || null;
       var account = null;
       try { account = globalThis.__AGENTIC__?.getSelectedAccount() || null; } catch(e) {}
-      return { route: route, account: account };
+      return { route: route, account: account, agenticPresent: agenticPresent };
     })()`;
     const snapshot = await cdpEval(client, expr);
     return { ...snapshot, deviceName: deviceName || '', platform: platform || '' };
@@ -658,7 +674,9 @@ Environment:
         const result = await handler(client, args.slice(1), { deviceName: target.deviceName, platform });
         results.push(result);
       } catch {
-        // Target not responsive — skip
+        // Recovery is correct: status probes every target advisory; an
+        // unresponsive one degrades to absent-from-the-listing rather than
+        // failing the whole multi-target command.
       } finally {
         if (client) client.close();
       }

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);
@@ -48,6 +48,18 @@ async function fetchJSON(url) {
  * Returns true if __AGENTIC__ is installed, false otherwise.
  */
 async function probeTarget(wsUrl) {
+  return (await probeTargetDetailed(wsUrl)) === 'agentic';
+}
+
+/**
+ * Three-state probe so callers can tell a pre-__AGENTIC__ build apart from a
+ * dead target:
+ *   'agentic'     — JS runtime answered and __AGENTIC__ is installed.
+ *   'responsive'  — the target evaluated JS but has no __AGENTIC__ (an app build
+ *                   that predates the bridge, or a non-runtime page).
+ *   'unreachable' — connect/eval failed.
+ */
+async function probeTargetDetailed(wsUrl) {
   try {
     const client = await createWSClient(wsUrl, 3000);
     try {
@@ -56,13 +68,13 @@ async function probeTarget(wsUrl) {
         returnByValue: true,
         awaitPromise: false,
       });
-      return result?.result?.value === 'object';
+      return result?.result?.value === 'object' ? 'agentic' : 'responsive';
     } finally {
       client.close();
     }
   } catch {
-    // Connection failed — target is not the right one
-    return false;
+    // Connection failed — target is not usable at all
+    return 'unreachable';
   }
 }
 
@@ -113,14 +125,76 @@ async function discoverTarget(port) {
     }
   }
 
-  // Filter by device name if ANDROID_DEVICE is set
+  // 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();
-  if (androidDevice && candidates.length > 1) {
-    const deviceFiltered = candidates.filter(
-      (t) => t.deviceName === androidDevice,
-    );
-    if (deviceFiltered.length > 0) {
-      candidates = deviceFiltered;
+  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
+
+  if (candidates.length > 1) {
+    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;
     }
   }
 
@@ -186,18 +260,32 @@ async function discoverAllTargets(port) {
     return bPage - aPage;
   });
 
-  // Group by deviceName, probe each to find the JS runtime target
-  const seen = new Set();
-  const results = [];
+  // Group by deviceName, probe each to find the JS runtime target. Prefer the
+  // device's __AGENTIC__-bearing target; when a device has none, keep its first
+  // RESPONSIVE candidate (candidates are sorted JS-runtime-first) so a build
+  // that predates the bridge still surfaces — the status consumer reports it as
+  // bridge-absent instead of the device silently vanishing from discovery.
+  // Known ambiguity: when a device's JS runtime is attached-but-busy while its
+  // native C++ Hermes page answers, that page is also 'responsive' (no
+  // __AGENTIC__ in the native context), so the device reports bridge-absent even
+  // though the app build may carry the bridge. Low probability, and the degraded
+  // report is informative rather than harmful.
+  const agenticByDevice = new Map();
+  const responsiveByDevice = new Map();
   for (const candidate of candidates) {
     const device = candidate.deviceName || candidate.id || candidate.webSocketDebuggerUrl;
-    if (seen.has(device)) continue;
-    const hasAgentic = await probeTarget(candidate.webSocketDebuggerUrl);
-    if (hasAgentic) {
-      seen.add(device);
-      results.push({ wsUrl: candidate.webSocketDebuggerUrl, deviceName: device });
+    if (agenticByDevice.has(device)) continue;
+    const state = await probeTargetDetailed(candidate.webSocketDebuggerUrl);
+    if (state === 'agentic') {
+      agenticByDevice.set(device, { wsUrl: candidate.webSocketDebuggerUrl, deviceName: device });
+    } else if (state === 'responsive' && !responsiveByDevice.has(device)) {
+      responsiveByDevice.set(device, { wsUrl: candidate.webSocketDebuggerUrl, deviceName: device });
     }
   }
+  const results = [...agenticByDevice.values()];
+  for (const [device, entry] of responsiveByDevice) {
+    if (!agenticByDevice.has(device)) results.push(entry);
+  }
   return results;
 }
 

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/cli-commands.js

@@ -7,7 +7,7 @@ const SPEC = {
     { name: "help", aliases: ["-h", "--help"], desc: "Show usage" }
   ],
   shared: [
-    { name: "status", aliases: ["health", "home"], desc: "Home status + next commands", flags: ["--json"] },
+    { name: "status", aliases: ["health", "home"], desc: "Home status + next commands", flags: ["--json", "--fast"] },
     { name: "ports", desc: "Slot ports and runtime paths", flags: ["--json"] },
     { name: "up", desc: "Decide + run minimum work to reach ready", flags: ["--json", "--dry-run"] },
     { name: "sync", desc: "Refresh harness + canonicalize wallet fixture", flags: ["--json"] },

package/dist/commands/parse-args.js

@@ -29,6 +29,7 @@ function parseArgs(argv, command) {
     "force",
     "resolveOnly",
     "expectLive",
+    "fast",
     "help"
   ]);
   for (let i = 0; i < argv.length; i += 1) {

package/dist/commands/status-probe.js

@@ -0,0 +1,167 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fixtureSummary } from "../doctor.js";
+import { runnerDir } from "../paths.js";
+const PROBE_TIMEOUT_MS = 2e3;
+function bridgeScriptPath() {
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT ?? path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+}
+function truncateAddress(address) {
+  if (!address || address.length <= 10) return address;
+  return `${address.slice(0, 6)}\u2026${address.slice(-4)}`;
+}
+function routeToString(route) {
+  if (typeof route === "string") return route;
+  if (route && typeof route === "object" && "name" in route) {
+    const n = route.name;
+    if (typeof n === "string") return n;
+  }
+  return void 0;
+}
+function deriveWalletState(account, route) {
+  const routeStr = (routeToString(route) ?? "").toLowerCase();
+  if (routeStr.includes("onboard")) return "onboarding";
+  if (account !== null && account !== void 0 && typeof account === "object") return "unlocked";
+  return "locked";
+}
+function parseBridgeEntries(raw) {
+  if (!raw || typeof raw !== "object") return [];
+  const items = Array.isArray(raw) ? raw : [raw];
+  return items.filter((e) => Boolean(e && typeof e === "object" && !Array.isArray(e))).map((e) => ({
+    route: e.route,
+    account: e.account,
+    deviceName: typeof e.deviceName === "string" ? e.deviceName : "",
+    platform: typeof e.platform === "string" ? e.platform : "",
+    // agenticPresent is only set when the bridge explicitly sends it (false = absent).
+    // Omitted by older bridge versions → leave undefined so caller treats as present.
+    ...typeof e.agenticPresent === "boolean" ? { agenticPresent: e.agenticPresent } : {}
+  }));
+}
+function matchBridgeEntry(device, entries) {
+  const byId = entries.find((e) => e.deviceName === device.id);
+  if (byId) return byId;
+  if (device.name) {
+    const byName = entries.find((e) => e.deviceName === device.name);
+    if (byName) return byName;
+  }
+  const platformEntries = entries.filter((e) => e.platform === device.platform);
+  if (platformEntries.length === 1) return platformEntries[0];
+  return null;
+}
+function probeMobileBridge(target) {
+  const script = bridgeScriptPath();
+  if (!fs.existsSync(script)) {
+    return Promise.resolve({ ok: false, liveState: "no-bridge" });
+  }
+  return new Promise((resolve) => {
+    const env = {
+      ...process.env,
+      APP_ROOT: target,
+      CDP_TIMEOUT: String(PROBE_TIMEOUT_MS)
+    };
+    let settled = false;
+    let stdout = "";
+    const child = spawn(process.execPath, [script, "status"], {
+      cwd: target,
+      env,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      const killTimer = setTimeout(() => child.kill("SIGKILL"), 500);
+      child.once("close", () => clearTimeout(killTimer));
+      resolve({ ok: false, liveState: "no-bridge" });
+    }, PROBE_TIMEOUT_MS);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code !== 0) {
+        resolve({ ok: false, liveState: "no-bridge" });
+        return;
+      }
+      try {
+        const raw = JSON.parse(stdout);
+        const entries = parseBridgeEntries(raw);
+        if (entries.length === 0) {
+          resolve({ ok: false, liveState: "no-bridge" });
+          return;
+        }
+        resolve({ ok: true, entries });
+      } catch {
+        resolve({ ok: false, liveState: "no-bridge" });
+      }
+    });
+    child.on("error", () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: false, liveState: "no-bridge" });
+    });
+  });
+}
+function resolveFixtureStatus(target) {
+  const summary = fixtureSummary(target);
+  return summary.status === "ready" ? "READY" : "missing";
+}
+async function probeMobileLiveState(target, devices) {
+  const result = /* @__PURE__ */ new Map();
+  if (devices.length === 0) return result;
+  const fixtureStatus = resolveFixtureStatus(target);
+  const probeResult = await probeMobileBridge(target);
+  if (!probeResult.ok) {
+    for (const device of devices) result.set(device.id, { fixtureStatus, liveState: "no-bridge" });
+    return result;
+  }
+  const { entries } = probeResult;
+  const matched = /* @__PURE__ */ new Map();
+  const usedEntries = /* @__PURE__ */ new Set();
+  for (const device of devices) {
+    const entry = matchBridgeEntry(device, entries.filter((e) => !usedEntries.has(e)));
+    if (entry) {
+      matched.set(device.id, entry);
+      usedEntries.add(entry);
+    }
+  }
+  const leftoverEntries = entries.filter(
+    (e) => !usedEntries.has(e) && e.platform === "" && e.agenticPresent === false
+  );
+  const unmatchedDevices = devices.filter((d) => !matched.has(d.id));
+  if (leftoverEntries.length === 1 && unmatchedDevices.length === 1) {
+    matched.set(unmatchedDevices[0].id, leftoverEntries[0]);
+  }
+  for (const device of devices) {
+    const entry = matched.get(device.id);
+    if (!entry) {
+      result.set(device.id, { fixtureStatus, liveState: "no-bridge" });
+      continue;
+    }
+    if (entry.agenticPresent === false) {
+      result.set(device.id, { fixtureStatus, liveState: "bridge-absent" });
+      continue;
+    }
+    const account = entry.account;
+    const walletState = deriveWalletState(account, entry.route);
+    const currentScreen = routeToString(entry.route);
+    const addrRaw = typeof account?.address === "string" ? account.address : void 0;
+    const labelRaw = typeof account?.name === "string" ? account.name : void 0;
+    const liveEntry = {
+      fixtureStatus,
+      walletState,
+      ...currentScreen !== void 0 ? { currentScreen } : {},
+      ...labelRaw !== void 0 && addrRaw !== void 0 ? { selectedAccount: { label: labelRaw, address: truncateAddress(addrRaw) } } : {}
+    };
+    result.set(device.id, liveEntry);
+  }
+  return result;
+}
+export {
+  probeMobileLiveState,
+  resolveFixtureStatus
+};

package/dist/commands/status.js

@@ -4,11 +4,13 @@ import { assertAdapter } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { listConnectedDevices } from "../devices.js";
 import { deviceSelected, renderDeviceList } from "./device-target.js";
+import { probeMobileLiveState } from "./status-probe.js";
 import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
 import { optionFlag, targetPath } from "./parse-args.js";
 async function handleStatus({ options }) {
   const target = targetPath(options);
   const json = optionFlag(options, "json");
+  const fast = optionFlag(options, "fast");
   const adapter = detectAdapter(target);
   if (!adapter) {
     return usageOut(json, "status", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
@@ -17,15 +19,70 @@ async function handleStatus({ options }) {
   const devices = adapter === "mobile" ? listConnectedDevices().map((device) => ({ ...device, selected: deviceSelected(device) })) : [];
   const next = getAdapterSurface(adapter).hints.relaunch;
   if (json) {
-    console.log(JSON.stringify({ schemaVersion: 1, command: "status", adapter, target, devices, next }, null, 2));
+    const doProbe = !fast && adapter === "mobile" && devices.length > 0;
+    if (doProbe) {
+      const liveMap = await probeMobileLiveState(target, devices);
+      const devicesWithLive = devices.map((d) => mergeDeviceLive(d, liveMap.get(d.id)));
+      console.log(
+        JSON.stringify(
+          { schemaVersion: 1, command: "status", adapter, target, devices: devicesWithLive, next },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(
+        JSON.stringify({ schemaVersion: 1, command: "status", adapter, target, devices, next }, null, 2)
+      );
+    }
     return EXIT.ok;
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });
   console.log(`${out("label", "status")} ${out("bold", adapter)} ${out("dim", target)}`);
   if (adapter === "mobile") renderDeviceList(devices, out);
   console.log(`${out("label", "Next:")} ${out("cmd", next)}`);
+  if (!fast && adapter === "mobile" && devices.length > 0) {
+    const liveMap = await probeMobileLiveState(target, devices);
+    renderLiveBlock(devices, liveMap, out);
+  }
   return EXIT.ok;
 }
+function mergeDeviceLive(device, live) {
+  if (!live) return device;
+  return {
+    ...device,
+    fixtureStatus: live.fixtureStatus,
+    ...live.liveState !== void 0 ? { liveState: live.liveState } : {},
+    ...live.currentScreen !== void 0 ? { currentScreen: live.currentScreen } : {},
+    ...live.walletState !== void 0 ? { walletState: live.walletState } : {},
+    ...live.selectedAccount !== void 0 ? { selectedAccount: live.selectedAccount } : {}
+  };
+}
+function renderLiveBlock(devices, liveMap, out) {
+  console.log(`${out("label", "live:")}`);
+  for (const device of devices) {
+    const live = liveMap.get(device.id);
+    const prefix = `  ${device.platform} ${out("dim", device.id)}${device.name ? ` (${device.name})` : ""}`;
+    if (!live || live.liveState === "no-bridge") {
+      console.log(`${prefix}: ${out("dim", "(no-bridge)")}`);
+      continue;
+    }
+    if (live.liveState === "bridge-absent") {
+      console.log(`${prefix}: ${out("warn", "(bridge-absent \u2014 app attached, build lacks __AGENTIC__; rebuild/reinstall a dev build)")}`);
+      continue;
+    }
+    const parts = [];
+    if (live.currentScreen !== void 0) parts.push(`screen=${out("cmd", live.currentScreen)}`);
+    if (live.walletState !== void 0) parts.push(`wallet=${out(live.walletState === "unlocked" ? "ok" : "warn", live.walletState)}`);
+    if (live.selectedAccount !== void 0) {
+      parts.push(`account=${live.selectedAccount.label} ${out("dim", `(${live.selectedAccount.address})`)}`);
+    }
+    if (live.fixtureStatus !== void 0) {
+      parts.push(`fixture=${out(live.fixtureStatus === "READY" ? "ok" : "warn", live.fixtureStatus)}`);
+    }
+    console.log(`${prefix}: ${parts.join("  ")}`);
+  }
+}
 export {
   handleStatus
 };

package/dist/mm-harness-cli.js

@@ -18,18 +18,31 @@ const REAL = [
     helpText: `mm-harness status [flags]
 
   Home dashboard for the current checkout \u2014 the detected adapter, the next command
-  to run, and (mobile only) the connected devices with which one is the selected
-  target (matches ADB_SERIAL / IOS_SIMULATOR). Aliases: health, home.
+  to run, and (mobile only) the connected devices with live app state. Aliases: health, home.
 
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable envelope { adapter, target, devices[], next }
+  --fast                             Skip all live-state probes (instant output, safe for scripts)
 
-  The devices[] section carries { platform, id, name, state, selected } per device;
-  extension/core checkouts report an empty list (no device surface).
+  Human output: static device list prints immediately; live-state lines append
+  after the ~2s probe window (screen, wallet, account, fixture per device).
+
+  The devices[] section carries per device:
+    { platform, id, name, state, selected }   always present
+    { currentScreen, walletState, selectedAccount, fixtureStatus }  when bridge reachable
+    { liveState: 'no-bridge' }   when bridge unreachable or --fast
+
+  All RN targets attached to the checkout's Metro are probed and matched to their
+  devices; a device whose target cannot be confidently matched (Metro's device
+  description matches neither the serial nor the model name) degrades to
+  liveState:'no-bridge'. An attached target whose build predates __AGENTIC__
+  reports liveState:'bridge-absent'.
+  Extension/core live-state probing is V1-pending (use doctor for runtime status).
 
 Example:
   mm-harness status
-  mm-harness status --json`
+  mm-harness status --json
+  mm-harness status --fast`
   },
   {
     name: "actions",