@deeeed/metamask-harness 0.13.0 → 0.14.1

package/adapters/extension/sidepanel-toggle.sh

@@ -36,6 +36,11 @@ fi
 shift || true
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../../adapters/shared/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
+  [ -f "$_hp" ] && { . "$_hp"; break; }
+done
+unset _hp
 REPO="${REPO:-}"
 if [ -z "$REPO" ]; then
   d="$SCRIPT_DIR"
@@ -52,6 +57,12 @@ if [ -z "$REPO" ]; then
   exit 1
 fi
 cd "$REPO"
+if command -v recipe_runtime_dir >/dev/null 2>&1; then
+  RUNTIME_DIR="$(recipe_runtime_dir)"
+else
+  RUNTIME_DIR="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
+fi
+RUNTIME_DIST_DIR="${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}"
 
 CDP_PORT="${CDP_PORT:-}"
 EXT_ID="${EXT_ID:-}"
@@ -94,14 +105,33 @@ find_sidepanel_id() {
 }
 
 resolve_ext_id() {
-  if [ -n "$EXT_ID" ]; then
+  if [[ "$EXT_ID" =~ ^[a-p]{32}$ ]]; then
     printf '%s\n' "$EXT_ID"
     return
   fi
-  for idf in "$AGENT_DIR/extension.id" "$REPO/temp/recipe/runtime/extension.id"; do
+
+  local manifest_id
+  manifest_id="$(
+    SCRIPT_DIR="$SCRIPT_DIR" REPO="$REPO" RUNTIME_DIR="$RUNTIME_DIR" RUNTIME_DIST_DIR="$RUNTIME_DIST_DIR" node <<'NODE' 2>/dev/null || true
+const path = require('node:path');
+const { extensionIdFromManifestFile } = require(path.join(process.env.SCRIPT_DIR, 'lib/extension-id.cjs'));
+const id = extensionIdFromManifestFile(path.join(process.env.REPO, process.env.RUNTIME_DIR, process.env.RUNTIME_DIST_DIR, 'manifest.json'));
+if (id) process.stdout.write(id);
+NODE
+  )"
+  if [[ "$manifest_id" =~ ^[a-p]{32}$ ]]; then
+    printf '%s\n' "$manifest_id"
+    return
+  fi
+
+  for idf in "$REPO/$RUNTIME_DIR/extension.id" "$AGENT_DIR/extension.id"; do
     if [ -f "$idf" ]; then
-      tr -d '[:space:]' < "$idf"
-      return
+      local marker_id
+      marker_id="$(tr -d '[:space:]' < "$idf")"
+      if [[ "$marker_id" =~ ^[a-p]{32}$ ]]; then
+        printf '%s\n' "$marker_id"
+        return
+      fi
     fi
   done
   json_list | python3 -c "import json,re,sys; d=json.load(sys.stdin); ids=[]; [ids.extend(re.findall(r'^chrome-extension://([^/]+)/', t.get('url',''))) for t in d]; print(ids[0] if ids else '')"
@@ -142,6 +172,32 @@ print_targets() {
   json_list | python3 -c "import json,sys; d=json.load(sys.stdin); [print(f'  {t.get(\"type\",\"?\")[:18]:18s} {t.get(\"url\",\"\")[:100]}') for t in d]"
 }
 
+activate_dapp_tab() {
+  local target_id
+  target_id="$(
+    json_list | python3 -c "import json,sys; d=json.load(sys.stdin); pages=[t for t in d if t.get('type')=='page']; target=next((t for t in pages if t.get('url','').startswith('http://') or t.get('url','').startswith('https://')), None); print(target.get('id','') if target else '')"
+  )"
+  if [ -n "$target_id" ]; then
+    curl -s "http://127.0.0.1:${CDP_PORT}/json/activate/${target_id}" >/dev/null || true
+  fi
+}
+
+cleanup_sidepanel_tabs() {
+  local ext_id close_ids
+  ext_id="$(resolve_ext_id)"
+  [ -n "$ext_id" ] || return 0
+  close_ids="$(
+    json_list | EXT_ID="$ext_id" python3 -c "import json,os,sys; d=json.load(sys.stdin); ext=os.environ.get('EXT_ID',''); has_panel=any(t.get('type')=='page' and t.get('url','').startswith('chrome-extension://'+ext+'/') and 'sidepanel.html' in t.get('url','') for t in d); has_dapp=any(t.get('type')=='page' and (t.get('url','').startswith('http://') or t.get('url','').startswith('https://')) for t in d); print('\\n'.join(t.get('id','') for t in d if has_panel and has_dapp and t.get('type')=='page' and t.get('url','').startswith('chrome-extension://'+ext+'/') and 'home.html' in t.get('url','')))"
+  )"
+  if [ -n "$close_ids" ]; then
+    while IFS= read -r target_id; do
+      [ -n "$target_id" ] || continue
+      curl -s "http://127.0.0.1:${CDP_PORT}/json/close/${target_id}" >/dev/null || true
+    done <<< "$close_ids"
+  fi
+  activate_dapp_tab
+}
+
 status_sidepanel() {
   local sp
   sp="$(find_sidepanel_id)"
@@ -165,6 +221,7 @@ close_sidepanel() {
 
 open_sidepanel() {
   if [ -n "$(find_sidepanel_id)" ]; then
+    cleanup_sidepanel_tabs
     echo "[sidepanel] already open"
     return 0
   fi
@@ -186,7 +243,6 @@ const { chromium } = require('playwright');
   const extId = process.env.EXT_ID;
   const browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`);
   const context = browser.contexts()[0];
-  let createdPage = false;
   let page = context
     .pages()
     .find(
@@ -197,7 +253,6 @@ const { chromium } = require('playwright');
 
   if (!page) {
     page = await context.newPage();
-    createdPage = true;
     await page.goto(`chrome-extension://${extId}/home.html`, {
       waitUntil: 'domcontentloaded',
       timeout: 15000,
@@ -241,23 +296,35 @@ const { chromium } = require('playwright');
     document.getElementById('__recipe_open_sidepanel__')?.remove();
   });
 
-  // The wallet now lives in the sidepanel: leftover extension home tabs would
-  // show it twice and steal the foreground from the dapp tab. Close every
-  // non-sidepanel extension page (not just one this helper created), then
-  // bring the first http(s) tab back to front.
-  for (const candidate of context.pages()) {
-    if (
-      candidate.url().startsWith(`chrome-extension://${extId}/`) &&
-      !candidate.url().includes('/sidepanel.html')
-    ) {
-      try {
-        await candidate.close();
-      } catch (error) {
-        console.warn(
-          `[sidepanel] extension page close failed after successful open: ${
-            error && error.message ? error.message : error
-          }`,
-        );
+  const deadline = Date.now() + 5000;
+  let sidepanelPage;
+  while (Date.now() < deadline) {
+    sidepanelPage = context
+      .pages()
+      .find((candidate) => candidate.url().startsWith(`chrome-extension://${extId}/`) && candidate.url().includes('/sidepanel.html'));
+    if (sidepanelPage) break;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+
+  // Only collapse fullscreen extension tabs after Chrome exposes the sidepanel
+  // target. chrome.sidePanel.open can return before the panel page appears; if we
+  // close home first, a slow/failed panel leaves the operator with no visible
+  // wallet page and the next readiness probe has to reopen from scratch.
+  if (sidepanelPage) {
+    for (const candidate of context.pages()) {
+      if (
+        candidate.url().startsWith(`chrome-extension://${extId}/`) &&
+        !candidate.url().includes('/sidepanel.html')
+      ) {
+        try {
+          await candidate.close();
+        } catch (error) {
+          console.warn(
+            `[sidepanel] extension page close failed after successful open: ${
+              error && error.message ? error.message : error
+            }`,
+          );
+        }
       }
     }
   }
@@ -271,7 +338,11 @@ const { chromium } = require('playwright');
       // focus is cosmetic; the panel is already open
     }
   }
-  await browser.close();
+  if (typeof browser.disconnect === 'function') {
+    await browser.disconnect();
+  } else {
+    await browser.close();
+  }
 })().catch((error) => {
   console.error(`FAIL: ${error.message || error}`);
   process.exit(4);
@@ -279,6 +350,7 @@ const { chromium } = require('playwright');
 NODE
 
   if wait_for_sidepanel; then
+    cleanup_sidepanel_tabs
     echo "[sidepanel] opened"
     return 0
   fi

package/adapters/extension/verify.sh

@@ -88,7 +88,7 @@ RUNNER_BIN="$HARNESS_DIR/runner/bin/mm-harness"
 # --out (optional): a task-local recipes dir. Resolve it safely within the target
 # (resolve_harness_out rejects absolute/.. escapes) and prefer its smoke recipe so
 # `live --out <dir>` does not silently fall back to the installed default.
-SMOKE_RECIPE="$HARNESS_DIR/runner/recipes/smoke.extension.recipe.json"
+SMOKE_RECIPE="$HARNESS_DIR/runner/recipes/runner/smoke.extension.recipe.json"
 if [ -n "$OUT" ]; then
   # Fail fast on a task-local --out that does not contain the requested recipe.
   # Silently falling back to the installed default would validate a different
@@ -98,11 +98,11 @@ if [ -n "$OUT" ]; then
     echo "extension verify: --out '$OUT' did not resolve to a safe path under the target." >&2
     exit 2
   fi
-  if [ ! -f "$OUT_ABS/smoke.extension.recipe.json" ]; then
-    echo "extension verify: --out '$OUT' (resolved: $OUT_ABS) has no smoke.extension.recipe.json. Refusing to fall back to the installed default recipe; place the recipe under --out or omit --out." >&2
+  if [ ! -f "$OUT_ABS/runner/smoke.extension.recipe.json" ]; then
+    echo "extension verify: --out '$OUT' (resolved: $OUT_ABS) has no runner/smoke.extension.recipe.json. Refusing to fall back to the installed default recipe; place the recipe under --out or omit --out." >&2
     exit 2
   fi
-  SMOKE_RECIPE="$OUT_ABS/smoke.extension.recipe.json"
+  SMOKE_RECIPE="$OUT_ABS/runner/smoke.extension.recipe.json"
 fi
 ARTIFACTS="${ARTIFACTS:-$HARNESS_DIR/verify/$(date -u +%Y%m%dT%H%M%SZ)}"
 mkdir -p "$ARTIFACTS/logs"
@@ -385,6 +385,14 @@ if [ "$STATIC_ONLY" = false ]; then
   else
     live_mode="live"
     cdp_holder_json "$CDP_PORT" > "$ARTIFACTS/logs/cdp-holder.json"
+    if "$RUNNER_BIN" ensure-ready --adapter extension --target "$TARGET" --cdp-port "$CDP_PORT" --json > "$ARTIFACTS/logs/extension-ensure-ready.json" 2>&1; then
+      checks+=("{\"name\":\"home-tab convergence\",\"status\":\"pass\",\"detail\":\"see logs/extension-ensure-ready.json\"}")
+      refresh_extension_id
+    else
+      checks+=("{\"name\":\"home-tab convergence\",\"status\":\"fail\",\"detail\":\"see logs/extension-ensure-ready.json\"}")
+      status="fail"
+    fi
+
     if node "$READINESS_MJS" --target "$TARGET" --cdp-port "$CDP_PORT" --json > "$ARTIFACTS/logs/extension-readiness.json" 2>&1; then
       checks+=("{\"name\":\"live extension readiness\",\"status\":\"pass\"}")
       # extension-readiness.mjs may repair $RUNTIME_DIR/extension.id when the
@@ -438,6 +446,8 @@ try { distFreshness = JSON.parse(fs.readFileSync(path.join(artifacts, 'logs/dist
 try { fixtureStatus = JSON.parse(fs.readFileSync(path.join(artifacts, 'logs/fixture-status.json'), 'utf8')); } catch {}
 try { cdpHolder = JSON.parse(fs.readFileSync(path.join(artifacts, 'logs/cdp-holder.json'), 'utf8')); } catch {}
 try { readinessReport = JSON.parse(fs.readFileSync(path.join(artifacts, 'logs/extension-readiness.json'), 'utf8')); } catch {}
+let ensureReadyReport = null;
+try { ensureReadyReport = JSON.parse(fs.readFileSync(path.join(artifacts, 'logs/extension-ensure-ready.json'), 'utf8')); } catch {}
 function runGit(args) {
   try {
     return cp.execFileSync('git', ['-C', target, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
@@ -498,6 +508,7 @@ fs.writeFileSync(path.join(artifacts, 'summary.json'), `${JSON.stringify({
   },
   fixtureStatus,
   cdpHolder,
+  ensureReady: ensureReadyReport,
   cdpTarget,
   checks: parsedChecks,
   generatedAt: new Date().toISOString(),

package/adapters/extension/wallet-fixture-state.cjs

@@ -20,6 +20,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const http = require('node:http');
 const path = require('node:path');
+const { extensionIdFromManifestKey } = require('./lib/extension-id.cjs');
 
 const EOA_METHODS = [
   'personal_sign',
@@ -573,16 +574,6 @@ function extensionIdFromUrl(url) {
   return String(url).split('/')[2] || '';
 }
 
-function extensionIdFromManifestKey(key) {
-  if (!key) {
-    return '';
-  }
-  const digest = crypto.createHash('sha256').update(Buffer.from(key, 'base64')).digest();
-  return [...digest.subarray(0, 16)]
-    .map((byte) => `${'abcdefghijklmnop'[byte >> 4]}${'abcdefghijklmnop'[byte & 0x0f]}`)
-    .join('');
-}
-
 function versionedStorageState(fixtureState) {
   return fixtureState.data
     ? { data: fixtureState.data, meta: { ...(fixtureState.meta || {}), storageKind: 'data' } }
@@ -639,6 +630,10 @@ async function detectExtension(context, extensionDir, extensionIdFile) {
   const expectedServiceWorker = manifest.background?.service_worker || '';
   const manifestId = extensionIdFromManifestKey(manifest.key);
   const rejected = new Set();
+  if (manifestId && extensionIdFile) {
+    fs.mkdirSync(path.dirname(extensionIdFile), { recursive: true });
+    fs.writeFileSync(extensionIdFile, `${manifestId}\n`);
+  }
 
   for (let attempt = 0; attempt < 30; attempt += 1) {
     const candidates = [];
@@ -648,10 +643,10 @@ async function detectExtension(context, extensionDir, extensionIdFile) {
       }
       candidates.push({ id, reason });
     };
+    push(manifestId, 'manifest key');
     if (extensionIdFile && fs.existsSync(extensionIdFile)) {
       push(fs.readFileSync(extensionIdFile, 'utf8').trim(), 'extension id marker');
     }
-    push(manifestId, 'manifest key');
     for (const worker of context.serviceWorkers()) {
       const id = extensionIdFromUrl(worker.url());
       if (expectedServiceWorker && worker.url().endsWith(`/${expectedServiceWorker}`)) {

package/adapters/mobile/open-device.sh

@@ -106,20 +106,47 @@ sim_udid_for_target() {
   if printf '%s' "$target" | grep -Eq '^[0-9A-Fa-f-]{36}$'; then
     printf '%s\n' "$target"; return 0
   fi
-  xcrun simctl list devices available 2>/dev/null \
-    | sed -n "s/.*${target} (\([0-9A-Fa-f-]*\)) (.*/\1/p" | head -1
+  xcrun simctl list devices available --json 2>/dev/null | TARGET_SIMULATOR="$target" node -e '
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => { input += chunk; });
+process.stdin.on("end", () => {
+  const target = process.env.TARGET_SIMULATOR || "";
+  try {
+    const parsed = JSON.parse(input);
+    for (const devices of Object.values(parsed.devices || {})) {
+      const found = Array.isArray(devices)
+        ? devices.find((device) => device && device.isAvailable !== false && device.name === target)
+        : null;
+      if (found && found.udid) {
+        process.stdout.write(`${found.udid}\n`);
+        return;
+      }
+    }
+  } catch {
+    // Empty stdout means unresolved; callers print the teaching error.
+  }
+});
+'
 }
 
 boot_simulator_if_needed() {
   local target="$1" state=""
   [ "$target" != "booted" ] || return 0
+  local udid=""
+  udid="$(sim_udid_for_target "$target")"
+  if [ -z "$udid" ]; then
+    printf "open-device: configured iOS simulator '%s' does not exist.\n" "$target" >&2
+    printf "Next: mm-harness provision runway ios --adapter mobile --target '%s' --device '%s'\n" "$TARGET" "$target" >&2
+    return 1
+  fi
   local line=""
   line="$(xcrun simctl list devices available 2>/dev/null | grep -F "${target} (" | head -1 || true)"
   case "$line" in *"(Booted)"*) state="Booted" ;; *"(Shutdown)"*) state="Shutdown" ;; esac
   [ "$state" = "Booted" ] && return 0
   printf 'Booting iOS simulator %s%s\n' "$target" "${state:+ ($state)}" >&2
-  xcrun simctl boot "$target" 2>/dev/null || true
-  xcrun simctl bootstatus "$target" -b >/dev/null
+  xcrun simctl boot "$udid" 2>/dev/null || true
+  xcrun simctl bootstatus "$udid" -b >/dev/null
 }
 
 show_simulator() {
@@ -192,7 +219,7 @@ if [ "$PLATFORM" = "ios" ]; then
   # Expo dev-client URL scheme — drives both the deep link and the scheme-approval key.
   DEV_CLIENT_SCHEME="${IOS_DEV_CLIENT_SCHEME:-expo-metamask}"
 
-  boot_simulator_if_needed "$SIM_TARGET"
+  boot_simulator_if_needed "$SIM_TARGET" || exit 1
   show_simulator "$SIM_TARGET"
 
   LAUNCHED=false

package/adapters/mobile/start-metro.sh

@@ -86,6 +86,20 @@ start_console_forwarder() {
   local fwd_pid_file="$LOG_DIR/console-forwarder.pid"
   [ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || return 0
   { [ -f "$forwarder" ] && command -v node >/dev/null 2>&1; } || return 0
+  # Only one debugger can own a React Native page. Reap any forwarder already
+  # attached to this Metro port, even if it was launched from another checkout or
+  # package install path and therefore does not own this runtime dir's pid file.
+  while IFS= read -r line; do
+    local pid cmd
+    pid="${line%% *}"
+    cmd="${line#* }"
+    [ "$pid" != "$line" ] || continue
+    case "$cmd" in
+      *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
+        kill "$pid" 2>/dev/null || true
+        ;;
+    esac
+  done < <(ps -axo pid=,command= 2>/dev/null || true)
   if [ -f "$fwd_pid_file" ]; then
     local old_fwd
     old_fwd="$(cat "$fwd_pid_file" 2>/dev/null || true)"
@@ -126,7 +140,7 @@ set +a
 export EXPO_NO_TYPESCRIPT_SETUP=1
 export WATCHER_PORT="$(printf '%q' "$PORT")" METRO_PORT="$(printf '%q' "$PORT")"
 export METRO_MAX_WORKERS="$(printf '%q' "$METRO_WORKERS")"
-exec yarn expo start --port "$(printf '%q' "$PORT")"$clear_flag >> "$(printf '%q' "$LOG_FILE")" 2>&1
+yarn expo start --port "$(printf '%q' "$PORT")"$clear_flag 2>&1 | tee -a "$(printf '%q' "$LOG_FILE")"
 EOF
   chmod +x "$runner"
 }

package/adapters/mobile/verify.sh

@@ -216,6 +216,34 @@ process.stdout.write(value);
 NODE
 }
 
+runtime_context_value() {
+  TARGET_FOR_RUNTIME_CONTEXT="$TARGET" RUNTIME_DIR_FOR_RUNTIME_CONTEXT="$RUNTIME_DIR" RUNTIME_CONTEXT_NAME="$1" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const target = process.env.TARGET_FOR_RUNTIME_CONTEXT;
+const runtimeDir = process.env.RUNTIME_DIR_FOR_RUNTIME_CONTEXT;
+const names = process.env.RUNTIME_CONTEXT_NAME.split(',');
+const file = path.join(target, runtimeDir, 'agentic-runtime.json');
+let data = {};
+try { data = JSON.parse(fs.readFileSync(file, 'utf8')); } catch {}
+for (const name of names) {
+  const value = data && data[name];
+  if (value !== undefined && value !== null && value !== '') {
+    process.stdout.write(String(value));
+    process.exit(0);
+  }
+}
+NODE
+}
+
+mobile_device_target() {
+  if [ "$PLATFORM" = "android" ]; then
+    printf '%s' "${ADB_SERIAL:-${ANDROID_SERIAL:-${ANDROID_DEVICE:-$(runtime_context_value adbSerial,androidDevice,device)}}}"
+    return
+  fi
+  printf '%s' "${SIM_UDID:-${IOS_SIMULATOR:-$(runtime_context_value simulator,iosSimulator,device)}}"
+}
+
 check_file() {
   local rel="$1"
   if [ -e "$TARGET/$rel" ]; then
@@ -331,6 +359,7 @@ run_with_timeout() {
 
 live_status_ok() {
   local log_path="$1"
+  local device_target="$2"
   cat > "$ARTIFACTS/mobile-status-smoke.recipe.json" <<'JSON'
 {
   "schema_version": 1,
@@ -349,12 +378,15 @@ live_status_ok() {
 JSON
   (
     cd "$TARGET"
-    "$RUNNER_BIN" run "$ARTIFACTS/mobile-status-smoke.recipe.json" --adapter mobile --project-root "$TARGET" --artifacts-dir "$ARTIFACTS/runner-status-smoke" --json
+    device_args=()
+    [ -n "$device_target" ] && device_args=(--device "$device_target")
+    "$RUNNER_BIN" run "$ARTIFACTS/mobile-status-smoke.recipe.json" --adapter mobile --project-root "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-status-smoke" --json
   ) > "$log_path" 2>&1
 }
 
 ensure_live_runtime() {
-  if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log"; then
+  local device_target="$1"
+  if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log" "$device_target"; then
     return 0
   fi
   if [ "$AUTO_START" = true ]; then
@@ -366,7 +398,17 @@ EOF
 }
 
 if [ "$STATIC_ONLY" = false ]; then
-  if ensure_live_runtime; then
+  device_target="$(mobile_device_target)"
+  if [ -z "$device_target" ]; then
+    if [ "$PLATFORM" = "android" ]; then
+      device_target="$(jsenv_value ADB_SERIAL)"
+      [ -n "$device_target" ] || device_target="$(jsenv_value ANDROID_DEVICE)"
+    else
+      device_target="$(jsenv_value IOS_SIMULATOR)"
+    fi
+  fi
+
+  if ensure_live_runtime "$device_target"; then
     checks+=('{"name":"mobile runtime controllable precheck","status":"pass"}')
   else
     checks+=('{"name":"mobile runtime controllable precheck","status":"fail","detail":"see logs/app-status-precheck.log"}')
@@ -394,20 +436,13 @@ if [ "$STATIC_ONLY" = false ]; then
 {
   "schema_version": 1,
   "title": "Mobile v1 runner live bridge smoke",
-  "description": "Verifies the installed MetaMask runner can drive the React Native debug bridge through Recipe v1 actions.",
+  "description": "Verifies the installed MetaMask runner can read the React Native debug bridge without mutating wallet state.",
   "validate": {
     "workflow": {
       "entry": "status",
       "nodes": {
         "status": { "action": "app.status", "intent": "Read Mobile app status through the v1 runner", "next": "cdp-probe" },
-        "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "required": true, "timeout_ms": 15000, "next": "wallet-setup" },
-        "wallet-setup": { "action": "metamask.wallet.setup", "intent": "Prepare the wallet fixture for the live bridge smoke", "timeout_ms": 45000, "next": "wallet-unlock" },
-        "wallet-unlock": { "action": "metamask.wallet.ensure_unlocked", "intent": "Unlock the wallet through the manifest-declared action", "timeout_ms": 45000, "next": "wallet-read" },
-        "wallet-read": { "action": "metamask.wallet.read_state", "intent": "Read wallet state before navigating to the wallet view", "timeout_ms": 45000, "next": "navigate-wallet" },
-        "navigate-wallet": { "action": "ui.navigate", "intent": "Open the wallet view through the UI navigation action", "route": "WalletView", "timeout_ms": 45000, "next": "wait-wallet" },
-        "wait-wallet": { "action": "ui.wait_for", "intent": "Wait until the wallet screen is present", "test_id": "wallet-screen", "expected": "present", "timeout_ms": 45000, "next": "hud-smoke" },
-        "hud-smoke": { "action": "app.hud", "status": "running", "intent": "Show the Mobile live bridge smoke HUD", "progress": { "current": 1, "total": 1 }, "timeout_ms": 45000, "next": "screenshot" },
-        "screenshot": { "action": "ui.screenshot", "intent": "Capture proof that the wallet screen is visible", "path": "screenshots/mobile-v1-live-smoke.png", "timeout_ms": 45000, "next": "done" },
+        "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "required": true, "timeout_ms": 15000, "next": "done" },
         "done": { "action": "end", "status": "pass" }
       }
     }
@@ -417,13 +452,15 @@ JSON
 
   ios_simulator_resolved="$(jsenv_value IOS_SIMULATOR)"
   adb_serial_resolved="$(jsenv_value ADB_SERIAL)"
+  device_args=()
+  [ -n "$device_target" ] && device_args=(--device "$device_target")
   if (
     cd "$TARGET"
     METAMASK_RECIPE_AUTO_HUD=0 \
     IOS_SIMULATOR="${IOS_SIMULATOR:-$ios_simulator_resolved}" \
     ADB_SERIAL="${ADB_SERIAL:-$adb_serial_resolved}" \
     ANDROID_SERIAL="${ANDROID_SERIAL:-$adb_serial_resolved}" \
-    "$RUNNER_BIN" run "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" --adapter mobile --project-root "$TARGET" --artifacts-dir "$ARTIFACTS/runner-live-smoke" --json
+    "$RUNNER_BIN" run "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" --adapter mobile --project-root "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-live-smoke" --json
   ) > "$ARTIFACTS/logs/runner-live-smoke.log" 2>&1; then
     checks+=("{\"name\":\"runner v1 live bridge smoke\",\"status\":\"pass\"}")
   else

package/adapters/shared/log-tui.mjs

@@ -222,13 +222,17 @@ async function watchLog(options) {
     const chunk = readNewContent(logPath, offset);
     offset = chunk.offset;
     const allText = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '';
+    // Match readiness only against bytes read after this watch started. This
+    // assumes line-oriented log writes; a marker split across partial writes
+    // waits for a later complete marker instead of stale-passing.
+    const matchText = chunk.text;
     const events = extractEvents(allText, eventsLimit);
 
-    if (matchesPattern(allText, 'Module build failed|^ERROR in |compiled with [1-9][0-9]* error|FAIL runtime-launch|Extension harness launch fail')) {
+    if (matchesPattern(matchText, 'Module build failed|^ERROR in |compiled with [1-9][0-9]* error|FAIL runtime-launch|Extension harness launch fail')) {
       renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
       return 1;
     }
-    if (matchesPattern(allText, successPattern)) {
+    if (matchesPattern(matchText, successPattern)) {
       renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
       if (mode !== 'quiet') {
         const elapsed = Math.round((Date.now() - started) / 1000);
@@ -357,4 +361,4 @@ async function main() {
 main().catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));
   process.exit(1);
-});
+});

package/adapters/shared/resolve-slot-ports-core.mjs

@@ -31,6 +31,8 @@ export function formatKvLines(kv) {
   if (kv.WATCHER_PORT !== undefined) lines.push(`WATCHER_PORT=${kv.WATCHER_PORT}`);
   if (kv.SLOT_ID) lines.push(`SLOT_ID=${kv.SLOT_ID}`);
   if (kv.IOS_SIMULATOR) lines.push(`IOS_SIMULATOR=${kv.IOS_SIMULATOR}`);
+  if (kv.ADB_SERIAL) lines.push(`ADB_SERIAL=${kv.ADB_SERIAL}`);
+  if (kv.ANDROID_DEVICE) lines.push(`ANDROID_DEVICE=${kv.ANDROID_DEVICE}`);
   return lines.length ? `${lines.join('\n')}\n` : '';
 }
 
@@ -54,6 +56,8 @@ function scoreSlot(slot, slotSuffix) {
   const cdp = resources.browser?.cdp_port;
   const port = resources['dev-server']?.port;
   const simulator = resources['ios-sim']?.simulator;
+  const adbSerial = resources['android-emu']?.adb_serial ?? resources.android?.adb_serial;
+  const androidDevice = resources['android-emu']?.device ?? resources.android?.device;
   const session = slot.session ?? '';
   const slotId = slot.id ?? '';
   let score = 0;
@@ -64,7 +68,7 @@ function scoreSlot(slot, slotSuffix) {
     if (slotId.endsWith(`mme-${slotSuffix}`) || slotId.includes(`-mme-${slotSuffix}`)) score += 40;
   }
   if (!slotId.toLowerCase().includes('demo')) score += 5;
-  return [score, cdp, port, slotId, simulator];
+  return [score, cdp, port, slotId, simulator, adbSerial, androidDevice];
 }
 
 export function resolveSlotPortsByRepo(repo) {
@@ -111,12 +115,14 @@ export function resolveSlotPortsByRepo(repo) {
     }
 
     if (best) {
-      const [, cdp, port, slotId, simulator] = best;
+      const [, cdp, port, slotId, simulator, adbSerial, androidDevice] = best;
       return formatKvLines({
         ...(cdp !== undefined ? { CDP_PORT: cdp } : {}),
         ...(port !== undefined ? { WATCHER_PORT: port } : {}),
         ...(slotId ? { SLOT_ID: slotId } : {}),
         ...(simulator ? { IOS_SIMULATOR: simulator } : {}),
+        ...(adbSerial ? { ADB_SERIAL: adbSerial } : {}),
+        ...(androidDevice ? { ANDROID_DEVICE: androidDevice } : {}),
       });
     }
   }
@@ -152,10 +158,14 @@ export function resolveMobileRuntimeContext(repo) {
   if (fs.existsSync(ctxPath)) {
     try {
       const c = JSON.parse(fs.readFileSync(ctxPath, 'utf8'));
-      if (c.simulator || (c.metroPort != null && c.metroPort !== '')) {
+      const adbSerial = c.adbSerial ?? c.androidSerial;
+      const androidDevice = c.androidDevice;
+      if (c.simulator || adbSerial || androidDevice || (c.metroPort != null && c.metroPort !== '')) {
         return formatKvLines({
           ...(c.metroPort != null && c.metroPort !== '' ? { WATCHER_PORT: c.metroPort } : {}),
           ...(c.simulator ? { IOS_SIMULATOR: c.simulator } : {}),
+          ...(adbSerial ? { ADB_SERIAL: adbSerial } : {}),
+          ...(androidDevice ? { ANDROID_DEVICE: androidDevice } : {}),
           ...(c.slotId ? { SLOT_ID: c.slotId } : {}),
         });
       }
@@ -210,4 +220,4 @@ export const cliFns = {
   resolve_mobile_runtime_context: resolveMobileRuntimeContext,
   resolve_mobile_slot_defaults: resolveMobileSlotDefaults,
   resolve_mobile_runtime_ports: (repo) => resolveMobileRuntimePorts(repo) || null,
-};
+};

package/dist/adapters/core/surface.js

@@ -31,6 +31,7 @@ const coreSurface = {
     }
   },
   devServer: {
+    label: "dev-server",
     describe: () => "no dev server (headless)",
     stop() {
       return {

package/dist/adapters/extension/runtime.js

@@ -25,7 +25,8 @@ async function prepareExtensionRuntime(options) {
   const health = await assertHealthyExtensionRuntime({
     projectRoot,
     cdpPort,
-    timeoutMs: options.healthTimeoutMs
+    timeoutMs: options.healthTimeoutMs,
+    pageMode: options.pageMode
   });
   return { launch, health };
 }
@@ -34,14 +35,16 @@ async function assertHealthyExtensionRuntime(options) {
   const deadline = Date.now() + timeoutMs;
   let lastReport = null;
   while (Date.now() <= deadline) {
-    lastReport = await checkExtensionRuntimeHealth(options.projectRoot, options.cdpPort);
+    lastReport = await checkExtensionRuntimeHealth(options.projectRoot, options.cdpPort, {
+      pageMode: options.pageMode
+    });
     if (lastReport.status === "PASS") return lastReport;
     await sleep(500);
   }
   const report = lastReport ?? failReport(options.cdpPort, ["CDP runtime was not probed."], {});
   throw new Error(formatHealthFailure(report, options.projectRoot));
 }
-async function checkExtensionRuntimeHealth(projectRoot, cdpPort) {
+async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
   const findings = [];
   const warnings = [];
   let targets = [];
@@ -52,11 +55,17 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort) {
   } catch (error) {
     return failReport(cdpPort, [`CDP is not reachable on port ${cdpPort}: ${messageOf(error)}`], {});
   }
-  const extensionTargets = targets.filter(
+  const pageMode = options.pageMode ?? "home";
+  const homeTargets = targets.filter(
     (target2) => target2.type === "page" && String(target2.url ?? "").startsWith("chrome-extension://") && String(target2.url ?? "").includes("/home.html") && Boolean(target2.webSocketDebuggerUrl)
   );
+  const sidepanelTargets = targets.filter(
+    (target2) => target2.type === "page" && String(target2.url ?? "").startsWith("chrome-extension://") && String(target2.url ?? "").includes("/sidepanel.html") && Boolean(target2.webSocketDebuggerUrl)
+  );
+  const extensionTargets = pageMode === "home-or-sidepanel" && homeTargets.length === 0 ? sidepanelTargets : homeTargets;
   if (extensionTargets.length !== 1) {
-    findings.push(`Expected exactly one MetaMask extension home page target, found ${extensionTargets.length}.`);
+    const expected = pageMode === "home-or-sidepanel" ? "exactly one MetaMask extension home page target, or one sidepanel target when home is intentionally closed" : "exactly one MetaMask extension home page target";
+    findings.push(`Expected ${expected}, found ${extensionTargets.length}.`);
   }
   const target = extensionTargets[0];
   if (!target?.webSocketDebuggerUrl) {