@deeeed/metamask-harness 0.7.4 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.8.0 - 2026-07-07
+
+### Added
+- **`run <name>` — the recipe positional resolves packaged-library recipe names.** An existing file path (absolute or cwd-relative) wins; otherwise the arg is a library recipe name, adapter-scoped first (`run smoke` on mobile → `smoke.mobile.recipe.json`), then adapterless (`run perps-lifecycle`), then the exact library filename. A miss teaches `RECIPE_NOT_FOUND` naming the library recipes available for the adapter — no more `$LIB`-style path prefixes in docs or demo scripts. A directory shadowing a library name never wins, and path-shaped args (containing a separator) never fall through to the library.
+- **`--device <udid|serial|name>` — first-class mobile device targeting on `run`, `call`, and `doctor`.** Resolves against connected devices (adb + booted simulators; exact id first, then exact name with an ambiguity teaching error) and sets the same env `launch --device` does. Mobile `run`/`call` **without** `--device` while more than one targetable device is connected (across android + ios; android state `device`, iOS `Booted`) fail fast listing the devices and the `--device` hint, so a recipe never lands on the wrong device silently. `run --plan`/`--list` are exempt; extension/core teach. Errors honor `--json` with structured envelopes.
+- **`status` gains `devices[]`** (additive): `{platform, id, name, state, selected}` for connected android devices and booted iOS simulators on mobile checkouts — the `yarn a:status` successor; `selected` reflects the current env pinning.
+
+## 0.7.5 - 2026-07-07
+
+### Fixed
+- **`launch --verify` converges duplicate extension home tabs instead of failing prepare forever.** A second bare `home.html` tab can appear beside the operator's slot-titled one outside the harness's control (the extension opens its own tab after the build-freeze reload), and the live verify health gate requires exactly one home tab — but nothing in launch/verify ever collapsed duplicates (`ensureExtensionReady` was only reachable via the retired `ensure-ready` verb), so every preflight retry recounted two tabs and failed. `launch --verify` (extension, with a CDP port) now runs the convergence before the live verify phase.
+- **Convergence keeps the operator's tab.** With multiple home tabs, `ensureExtensionReady` now prunes the extras keeping the preferred tab — attached (another client is driving it) over custom slot title (`<slot-id> — MetaMask`, how operators tell which agent owns a browser) over first listed — instead of closing all and reopening fresh, which discarded the slot title. The deterministic close-all + fresh-open remains as a one-shot fallback when the kept tab fails the health check, and a failed re-listing during the fallback reports `cdp-unreachable` instead of a stale tab count.
+
+### Changed
+- **`EnsureReadyAction` gains `pruned`** — extras were closed keeping the preferred tab; `reopened` now specifically means the pruned keeper failed the health check and one fresh tab was reopened.
+
 ## 0.7.4 - 2026-07-07
 
 ### Added

package/dist/adapters/extension/ensure-ready.js

@@ -47,6 +47,12 @@ function homePages(targets, extensionId) {
     (t) => t.type === "page" && typeof t.url === "string" && t.url.startsWith(prefix) && t.url.includes("/home.html") && t.id
   );
 }
+function pickHomeKeeper(homes) {
+  const attached = homes.filter((t) => typeof t.webSocketDebuggerUrl !== "string");
+  const pool = attached.length > 0 ? attached : homes;
+  const marked = pool.find((t) => typeof t.title === "string" && t.title.trim() !== "" && t.title.trim() !== "MetaMask");
+  return marked ?? pool[0];
+}
 async function ensureExtensionReady(target, options) {
   const resolved = path.resolve(target);
   const { cdpPort } = options;
@@ -91,14 +97,14 @@ async function ensureExtensionReady(target, options) {
       opened = await openHome(cdpPort, extensionId) || opened;
       await sleep(1500);
     } else {
-      action = "reopened";
+      action = "pruned";
+      const keeper = pickHomeKeeper(homes);
       for (const h of homes) {
+        if (h === keeper) continue;
         await closeTab(cdpPort, String(h.id));
         closed += 1;
       }
       await sleep(500);
-      opened = await openHome(cdpPort, extensionId) || opened;
-      await sleep(1500);
     }
     const next = await jsonList(cdpPort);
     if (!next.ok) {
@@ -125,14 +131,35 @@ async function ensureExtensionReady(target, options) {
   if (!finalListing.ok) {
     return base({ extensionId, opened, action, homeTabs: { before, closed, after: homesNow.length }, reasonCode: "cdp-unreachable" });
   }
-  const after = homePages(finalListing.targets, extensionId).length;
-  let health = { status: "unknown", findings: [] };
-  try {
-    const { checkExtensionRuntimeHealth } = await import("./runtime.js");
-    const report = await checkExtensionRuntimeHealth(resolved, cdpPort);
-    health = { status: report.status, findings: report.findings };
-  } catch (error) {
-    health = { status: "FAIL", findings: [error instanceof Error ? error.message : String(error)] };
+  let after = homePages(finalListing.targets, extensionId).length;
+  const checkHealth = async () => {
+    try {
+      const { checkExtensionRuntimeHealth } = await import("./runtime.js");
+      const report = await checkExtensionRuntimeHealth(resolved, cdpPort);
+      return { status: report.status, findings: report.findings };
+    } catch (error) {
+      return { status: "FAIL", findings: [error instanceof Error ? error.message : String(error)] };
+    }
+  };
+  let health = await checkHealth();
+  if (action === "pruned" && (health.status !== "PASS" || after !== 1)) {
+    const listing = await jsonList(cdpPort);
+    if (listing.ok) {
+      action = "reopened";
+      for (const h of homePages(listing.targets, extensionId)) {
+        await closeTab(cdpPort, String(h.id));
+        closed += 1;
+      }
+      await sleep(500);
+      opened = await openHome(cdpPort, extensionId) || opened;
+      await sleep(1500);
+      const relisted = await jsonList(cdpPort);
+      if (!relisted.ok) {
+        return base({ extensionId, opened, action, homeTabs: { before, closed, after }, reasonCode: "cdp-unreachable" });
+      }
+      after = homePages(relisted.targets, extensionId).length;
+      health = await checkHealth();
+    }
   }
   const ready = health.status === "PASS" && after === 1;
   return base({

package/dist/cli-commands.js

@@ -15,8 +15,8 @@ const SPEC = {
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
     { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--json"] },
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
-    { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--cdp-port"] },
-    { name: "run", desc: "Execute a proof recipe", args: ["recipe.json"], flags: ["--list"] },
+    { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--cdp-port", "--device"] },
+    { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
     { name: "recipe-quality", desc: "Build the recipe-quality artifact from compact JSON", args: ["build"], flags: ["--input", "--output", "--json"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },
     { name: "prepare", desc: "Install harness (+ optional validate)", flags: ["--target", "--runtime-dir", "--json"] },

package/dist/cli.js

@@ -18,6 +18,7 @@ import { handleLogs } from "./commands/logs.js";
 import { handleDebug } from "./commands/debug.js";
 import { handleFixtures } from "./commands/fixtures.js";
 import { handleRecipeQuality } from "./commands/recipe-quality.js";
+import { handleStatus } from "./commands/status.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
 import { runOneNode } from "./commands/run-engine.js";
 const COMMANDS = {
@@ -92,6 +93,9 @@ async function main(argv) {
     usage();
     return command ? 0 : 2;
   }
+  if (command === "status" || command === "health" || command === "home") {
+    return handleStatus(parseArgs(argv.slice(1), "status"));
+  }
   if (command === "flows") return handleFlows(argv.slice(1));
   if (command === "call") return handleCall(argv.slice(1));
   if (command === "completion-candidates") return handleCompletionCandidates(argv.slice(1));

package/dist/commands/call.js

@@ -15,6 +15,7 @@ import {
   usageError
 } from "./parse-args.js";
 import { handleListExecutables } from "./list-executables.js";
+import { applyDeviceTargeting } from "./device-target.js";
 import {
   emitHealViolation,
   executeWithHealBounds,
@@ -57,6 +58,12 @@ async function handleCall(argv) {
     return EXIT.usage;
   }
   const { adapter, target } = resolveAdapter(options);
+  const dtResult = applyDeviceTargeting("call", adapter, options, { gate: true, rerun: "" });
+  if ("code" in dtResult) {
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, error: { code: dtResult.code, message: dtResult.message } }, null, 2));
+    else console.error(`\u2717 call: ${dtResult.message}`);
+    return EXIT.usage;
+  }
   if (recipeRunning(target)) {
     const msg = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
     if (json) {

package/dist/commands/device-target.js

@@ -0,0 +1,105 @@
+import { listConnectedDevices } from "../devices.js";
+import { optionString } from "./parse-args.js";
+function setAndroidDeviceEnv(id) {
+  process.env.ADB_SERIAL = id;
+  process.env.ANDROID_SERIAL = id;
+  process.env.ANDROID_DEVICE = id;
+}
+function setIosDeviceEnv(id) {
+  process.env.IOS_SIMULATOR = id;
+}
+function formatConnectedDevices(devices) {
+  return devices.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n");
+}
+function renderDeviceList(devices, out) {
+  console.log(
+    `${out("label", "devices:")} ${devices.length === 0 ? out("dim", "none connected (adb devices / booted iOS simulators)") : `${devices.length} connected`}`
+  );
+  for (const device of devices) {
+    const marker = device.selected ? out("ok", "\u25CF selected") : out("dim", "\u25CB");
+    console.log(
+      `  ${marker} ${device.id}${device.name ? ` (${device.name})` : ""} ${out("dim", `[${device.state}] ${device.platform}`)}`
+    );
+  }
+}
+function deviceSelected(device) {
+  if (device.platform === "android") {
+    return process.env.ADB_SERIAL === device.id || process.env.ANDROID_SERIAL === device.id;
+  }
+  return process.env.IOS_SIMULATOR === device.id;
+}
+function isTargetable(device) {
+  if (device.platform === "android") return device.state === "device";
+  if (device.platform === "ios") return device.state === "Booted";
+  return false;
+}
+function applyDeviceTargeting(command, adapter, options, opts) {
+  const device = optionString(options, "device");
+  if (adapter !== "mobile") {
+    if (device !== void 0) {
+      return {
+        ok: false,
+        code: "DEVICE_WRONG_ADAPTER",
+        message: `--device is only supported on the mobile adapter (the ${adapter} adapter has no device to target).
+  Drop --device, or run this ${command} inside a metamask-mobile checkout.`
+      };
+    }
+    return { ok: true };
+  }
+  if (device !== void 0) {
+    const connected2 = listConnectedDevices();
+    const androidById = connected2.find((d) => d.platform === "android" && d.id === device);
+    if (androidById) {
+      setAndroidDeviceEnv(device);
+      return { ok: true };
+    }
+    const iosById = connected2.find((d) => d.platform === "ios" && d.id === device);
+    if (iosById) {
+      setIosDeviceEnv(device);
+      return { ok: true };
+    }
+    const byName = connected2.filter((d) => d.name === device);
+    if (byName.length === 1) {
+      const matched = byName[0];
+      if (matched.platform === "android") setAndroidDeviceEnv(matched.id);
+      else setIosDeviceEnv(matched.id);
+      return { ok: true };
+    }
+    if (byName.length > 1) {
+      return {
+        ok: false,
+        code: "DEVICE_NAME_AMBIGUOUS",
+        message: `device name '${device}' is ambiguous; use the id:
+` + byName.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n")
+      };
+    }
+    return {
+      ok: false,
+      code: "DEVICE_NOT_FOUND",
+      message: `--device ${device} did not match any connected device.
+` + (connected2.length > 0 ? `  Connected devices:
+${formatConnectedDevices(connected2)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
+    };
+  }
+  if (!opts.gate) return { ok: true };
+  const connected = listConnectedDevices();
+  const targetable = connected.filter(isTargetable);
+  if (targetable.length > 1) {
+    return {
+      ok: false,
+      code: "DEVICE_AMBIGUOUS",
+      message: `${targetable.length} mobile devices available \u2014 ${command} needs exactly one target.
+  Connected devices:
+${formatConnectedDevices(connected)}
+  Add --device <id> to disambiguate, e.g.:${targetable.map((d) => `
+    --device ${d.id}`).join("")}`
+    };
+  }
+  return { ok: true };
+}
+export {
+  applyDeviceTargeting,
+  deviceSelected,
+  formatConnectedDevices,
+  renderDeviceList
+};

package/dist/commands/doctor.js

@@ -7,6 +7,8 @@ import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { ensureOverlay, newHealState, recipeRunning } from "../heal-bounds.js";
+import { listConnectedDevices } from "../devices.js";
+import { applyDeviceTargeting, deviceSelected, renderDeviceList } from "./device-target.js";
 import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
 import {
   actionManifestPathOption,
@@ -39,6 +41,12 @@ async function handleDoctor({ options }) {
     return usageOut(json, "doctor", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   assertAdapter(adapter);
+  const dtResult = applyDeviceTargeting("doctor", adapter, options, { gate: false, rerun: "" });
+  if ("code" in dtResult) {
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "doctor", adapter, target, error: { code: dtResult.code, message: dtResult.message } }, null, 2));
+    else console.error(`\u2717 doctor: ${dtResult.message}`);
+    return EXIT.usage;
+  }
   const actionManifestPath = actionManifestPathOption(options, adapter);
   const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
   const manifestValidation = await validateManifest(manifest);
@@ -60,8 +68,9 @@ async function handleDoctor({ options }) {
   }
   const orphanMetros = adapter === "mobile" ? detectOrphanMetros(target, process.env.WATCHER_PORT) : [];
   const capture = captureHelperHealth();
-  if (expectLive) return emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, json);
-  if (json) console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture }, null, 2));
+  const devices = adapter === "mobile" ? enumerateSelectedDevices() : [];
+  if (expectLive) return emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, json);
+  if (json) console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture, devices }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -91,13 +100,17 @@ async function handleDoctor({ options }) {
         console.log(`  ${out("dim", "Next: grant Screen Recording (System Settings \u2192 Privacy & Security \u2192 Screen Recording), or run: capture-helper doctor --open-permissions")}`);
       }
     }
+    if (adapter === "mobile") renderDeviceList(devices, out);
   }
   return result.status === "pass" ? 0 : 1;
 }
-function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, json) {
+function enumerateSelectedDevices() {
+  return listConnectedDevices().map((device) => ({ ...device, selected: deviceSelected(device) }));
+}
+function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, json) {
   const live = runtime?.decision === "ready";
   if (json) {
-    console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture }, null, 2));
+    console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture, devices }, null, 2));
     return live ? EXIT.ok : EXIT.runtime;
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });

package/dist/commands/launch/index.js

@@ -104,6 +104,14 @@ async function handleLaunch(argv) {
     });
   }
   if (tier === "verify") {
+    const verifyCdpPort = Number(process.env.CDP_PORT ?? "");
+    if (adapter === "extension" && Number.isInteger(verifyCdpPort) && verifyCdpPort > 0) {
+      const { ensureExtensionReady } = await import("../../adapters/extension/ensure-ready.js");
+      const convergence = await ensureExtensionReady(target, { cdpPort: verifyCdpPort });
+      console.error(
+        `[launch] home-tab convergence: ${convergence.action} (${convergence.homeTabs.before}\u2192${convergence.homeTabs.after} tabs, closed ${convergence.homeTabs.closed})${convergence.ready ? "" : ` \u2014 ${convergence.reasonCode}`}`
+      );
+    }
     const liveArgs = ["live", "--adapter", adapter, "--target", target];
     if (adapter === "mobile" && mobileTarget) liveArgs.push("--platform", mobileTarget);
     if (json) liveArgs.push("--json");

package/dist/commands/run-engine.js

@@ -14,6 +14,7 @@ import { getAdapterSurface } from "../adapters/surface.js";
 import {
   importRecipeHarness,
   importRecipeProtocol,
+  recipePath,
   runnerDir
 } from "../paths.js";
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
@@ -131,11 +132,47 @@ async function validateRecipeAdapterAware(recipe, manifest, librarySources) {
   const warnings = findings.length - errors;
   return { status: errors > 0 ? "invalid" : "valid", findings, summary: { errors, warnings } };
 }
+function isRecipeFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+function resolveRunRecipeArg(recipeArg, adapter) {
+  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 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}.`)
+  };
+}
+function libraryRecipeNames(adapter) {
+  let entries;
+  try {
+    entries = fs.readdirSync(recipePath(""));
+  } catch {
+    return [];
+  }
+  const scopes = ["mobile", "extension", "core"];
+  const names = entries.filter((f) => f.endsWith(".recipe.json")).map((f) => f.slice(0, -".recipe.json".length)).filter((n) => {
+    const scope = n.split(".").pop() ?? "";
+    return !scopes.includes(scope) || scope === adapter;
+  }).map((n) => n.endsWith(`.${adapter}`) ? n.slice(0, -(adapter.length + 1)) : n);
+  return [...new Set(names)].sort();
+}
 async function validateRunRecipeStatic(recipeArg, adapter, options) {
-  const recipeFile = path.resolve(recipeArg);
+  const resolved = resolveRunRecipeArg(recipeArg, adapter);
+  const recipeFile = "recipeFile" in resolved ? resolved.recipeFile : path.resolve(recipeArg);
   const empty = { recipe: void 0, recipeFile, findings: [], errorCount: 0, manifestOk: false, schemaValid: false };
-  if (!fs.existsSync(recipeFile)) {
-    return { ...empty, usageError: { code: "RECIPE_NOT_FOUND", message: `recipe not found: ${recipeFile}` } };
+  if ("notFound" in resolved) {
+    return { ...empty, usageError: { code: "RECIPE_NOT_FOUND", message: resolved.notFound } };
   }
   let recipe;
   try {
@@ -333,6 +370,7 @@ export {
   executeWithHealBounds,
   prepareHeal,
   resolveMetaMaskLibrarySources,
+  resolveRunRecipeArg,
   runOneNode,
   runRecipe,
   synthesizeOneNodeRecipe,

package/dist/commands/run.js

@@ -20,6 +20,7 @@ import {
   validateRunRecipeStatic
 } from "./run-engine.js";
 import { handleListExecutables } from "./list-executables.js";
+import { applyDeviceTargeting } from "./device-target.js";
 async function handleRun({ positional, options }) {
   if (optionFlag(options, "list")) return handleListExecutables("run", options);
   const targetRecipe = positional[0];
@@ -27,6 +28,10 @@ async function handleRun({ positional, options }) {
   if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options);
   const { adapter, target } = resolveAdapter(options);
   const json = optionFlag(options, "json");
+  const dtResult = applyDeviceTargeting("run", adapter, options, { gate: true, rerun: "" });
+  if ("code" in dtResult) {
+    return emitRunUsageError(json, adapter, targetRecipe, dtResult.code, dtResult.message);
+  }
   const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
   const prepared = await prepareHeal(adapter, target, options, json);
   if (typeof prepared === "number") return prepared;
@@ -45,7 +50,9 @@ async function handleRun({ positional, options }) {
     stdoutIsMachineContract: json
   };
   const { result, violation } = await executeWithHealBounds(
-    () => runRecipe(adapter, targetRecipe, artifactsDir, target, optionString(options, "actionManifest"), runtimeOptions),
+    // validated.recipeFile, not the raw arg: the arg may be a library recipe NAME
+    // that only the resolver knows how to turn into a file.
+    () => runRecipe(adapter, validated.recipeFile, artifactsDir, target, optionString(options, "actionManifest"), runtimeOptions),
     adapter,
     target,
     heal,

package/dist/commands/status.js

@@ -0,0 +1,31 @@
+import { color } from "../cli-color.js";
+import { detectAdapter } from "../harness.js";
+import { assertAdapter } from "../paths.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import { listConnectedDevices } from "../devices.js";
+import { deviceSelected, renderDeviceList } from "./device-target.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 adapter = detectAdapter(target);
+  if (!adapter) {
+    return usageOut(json, "status", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  }
+  assertAdapter(adapter);
+  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));
+    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)}`);
+  return EXIT.ok;
+}
+export {
+  handleStatus
+};

package/dist/devices.js

@@ -0,0 +1,66 @@
+import { execFileSync } from "node:child_process";
+function listConnectedDevices(platform) {
+  const devices = [];
+  if (!platform || platform === "android") devices.push(...listAndroidDevices());
+  if (!platform || platform === "ios") devices.push(...listIosSimulators());
+  return devices;
+}
+function listAndroidDevices() {
+  let output;
+  try {
+    output = execFileSync("adb", ["devices", "-l"], {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return [];
+  }
+  const devices = [];
+  for (const line of output.split("\n").slice(1)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const fields = trimmed.split(/\s+/u);
+    const id = fields[0];
+    const state = fields[1] ?? "unknown";
+    if (!id) continue;
+    const modelField = fields.find((f) => f.startsWith("model:"));
+    const name = modelField ? modelField.slice("model:".length) : void 0;
+    devices.push({ platform: "android", id, state, ...name ? { name } : {} });
+  }
+  return devices;
+}
+function listIosSimulators() {
+  let output;
+  try {
+    output = execFileSync("xcrun", ["simctl", "list", "devices", "booted", "-j"], {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(output);
+  } catch {
+    return [];
+  }
+  const devices = [];
+  for (const runtimeDevices of Object.values(parsed.devices ?? {})) {
+    for (const device of runtimeDevices) {
+      if (!device.udid) continue;
+      devices.push({
+        platform: "ios",
+        id: device.udid,
+        state: device.state ?? "unknown",
+        ...device.name ? { name: device.name } : {}
+      });
+    }
+  }
+  return devices;
+}
+export {
+  listConnectedDevices
+};

package/dist/mm-harness-cli.js

@@ -10,6 +10,27 @@ globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
 const rawArgv = process.argv.slice(2);
 const REAL = [
+  {
+    name: "status",
+    aliases: ["health", "home"],
+    summary: "Home dashboard for a checkout: detected adapter, next command, and (mobile) connected devices with the selected target.",
+    example: "mm-harness status",
+    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.
+
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable envelope { adapter, target, devices[], next }
+
+  The devices[] section carries { platform, id, name, state, selected } per device;
+  extension/core checkouts report an empty list (no device surface).
+
+Example:
+  mm-harness status
+  mm-harness status --json`
+  },
   {
     name: "actions",
     summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
@@ -64,6 +85,7 @@ Example:
 
   --list                             List everything invocable for the adapter (actions + flows); no <action> needed
   --arg k=v                          Action field value (repeatable)
+  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Where to write evidence (default: temp dir)
@@ -103,6 +125,7 @@ Example:
 
   --list                             List everything invocable for the adapter (actions + flows); no <recipe> needed
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
+  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Where to write evidence (required unless --plan)
@@ -128,6 +151,7 @@ Example:
   --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
   --expect-live                      Exit 0 iff the runtime is live (extension: watcher+CDP; mobile: Metro+bridge; core: deps), non-zero + teaching escape otherwise
   --cdp-port <port>                  Extension CDP port for the liveness probe (env: CDP_PORT / RECIPE_CDP_PORT)
+  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). doctor reports the connected devices; it never gates on ambiguity.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
@@ -417,7 +441,7 @@ const HELP_GROUPS = [
   {
     title: "DAILY LOOP",
     blurb: "what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)",
-    commands: ["launch", "stop", "logs", "debug", "fixtures"]
+    commands: ["status", "launch", "stop", "logs", "debug", "fixtures"]
   },
   {
     title: "DISCOVER",
@@ -530,7 +554,9 @@ const pkgVersion = (() => {
 const program = new Command();
 program.name("mm-harness").description("the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay").version(pkgVersion, "-v, --version", "Print the mm-harness version").helpOption("-h, --help", "Show grouped help").showHelpAfterError("(run `mm-harness --help` for the full surface)").configureHelp({ formatHelp: () => groupedHelp() });
 for (const command of REAL) {
-  program.command(command.name).description(command.summary).allowUnknownOption().helpOption("-h, --help", "Show command help").configureHelp({ formatHelp: () => `${command.helpText}
+  const registered = program.command(command.name).description(command.summary).allowUnknownOption().helpOption("-h, --help", "Show command help");
+  if (command.aliases?.length) registered.aliases(command.aliases);
+  registered.configureHelp({ formatHelp: () => `${command.helpText}
 ` }).argument("[args...]").action(async () => {
     if (command.name === "update") {
       process.exit(await handleUpdate(rawArgv.slice(1)));

package/docs/CLI-SPEC.md

@@ -437,6 +437,41 @@ 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.
+
+| Verb | `--device` given | `--device` omitted (mobile) |
+|---|---|---|
+| `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. |
+
+`--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.
+
+## `status` (aliases `health`, `home`) — home dashboard + devices[] (REAL)
+
+`status` is the compact home dashboard for a checkout: the detected adapter, the next command to run (`next`), and — for **mobile** checkouts — a `devices[]` section. Extension/core checkouts report an empty `devices[]` (CDP tab detail is out of scope). Additive envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "status",
+  "adapter": "mobile",
+  "target": "/path/to/checkout",
+  "devices": [
+    { "platform": "android", "id": "emulator-5554", "name": "Pixel_6", "state": "device", "selected": true },
+    { "platform": "ios", "id": "AAAA-BBBB", "name": "iPhone 15", "state": "Booted", "selected": false }
+  ],
+  "next": "mm-harness launch ios"
+}
+```
+
+`selected` is `true` when the device id matches the current `ADB_SERIAL`/`ANDROID_SERIAL` (android) or `IOS_SIMULATOR` (ios) env. `doctor --json` carries the same `devices[]` shape (with `selected`) for mobile checkouts.
+
+**Exit:** 0 (2 when the repo type cannot be detected).
+
+---
+
 ## DISCOVER — agent composition input
 
 > **Decided (Arthur):** DISCOVER is a distinct group, not a sub-PROVE. The audience

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -69,4 +69,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}