@deeeed/metamask-harness 0.2.0 → 0.3.0

package/adapters/mobile/wait-for-bridge.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# wait-for-bridge — poll the CDP bridge until a route target is registered.
+#
+# Calls cdp-bridge.cjs status in a poll loop. Emits structured diagnostics on
+# each probe failure: Metro reachability, React Native target visibility, bundle
+# progress. Fails with non-zero if the bridge is not ready within the poll limit.
+#
+# Inputs:
+#   --target <metamask-mobile dir>  (default $PWD)
+#   --port <number>                 (default WATCHER_PORT env, else METRO_PORT, else 8081)
+#   --max-polls <n>                 (default MOBILE_BRIDGE_READY_POLLS env, else 90; 2s each = 180s)
+# Outputs:
+#   Progress on stderr; exit 0 bridge ready; 1 timeout.
+#
+# Single device op: wait for bridge readiness. Does not start Metro or open the dev client.
+set -uo pipefail
+
+TARGET="$PWD"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+MAX_POLLS="${MOBILE_BRIDGE_READY_POLLS:-90}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)     TARGET="$2"; shift 2 ;;
+    --port)       PORT="$2"; shift 2 ;;
+    --max-polls)  MAX_POLLS="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>]\n'
+      exit 0
+      ;;
+    *) printf 'wait-for-bridge: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+TARGET="$(cd "$TARGET" && pwd)"
+LOG_DIR="$TARGET/temp/recipe/runtime"
+mkdir -p "$LOG_DIR"
+
+BRIDGE_CJS="$(dirname "$0")/bridge-runtime/cdp-bridge.cjs"
+STATUS_LOG="$LOG_DIR/bridge-status.log"
+METRO_LOG="$LOG_DIR/metro.log"
+
+if [ ! -f "$BRIDGE_CJS" ]; then
+  printf 'wait-for-bridge: cdp-bridge.cjs not found at %s\n' "$BRIDGE_CJS" >&2
+  exit 1
+fi
+
+metro_ready() {
+  curl -sf --max-time 2 "http://localhost:${PORT}/status" 2>/dev/null | grep -q 'packager-status:running'
+}
+
+bundle_progress() {
+  local log="$1"
+  [ -f "$log" ] || return 0
+  local p
+  p="$(grep -E '^[[:space:]]*(iOS|Android).*index\.(js|tsx?).*%|Bundl(ed|ing)|Finished' "$log" 2>/dev/null | tail -1 | tr -d '\r' || true)"
+  [ -n "$p" ] && printf ' (%s)' "$p"
+}
+
+bridge_wait_reason() {
+  if ! metro_ready; then
+    printf 'Metro not reachable on port %s' "$PORT"
+    return
+  fi
+  local targets
+  targets="$(curl -sf --max-time 2 "http://localhost:${PORT}/json/list" 2>/dev/null || true)"
+  if [ "$targets" = "[]" ] || [ -z "$targets" ]; then
+    printf 'Metro running; no React Native debug target yet'
+    bundle_progress "$METRO_LOG"
+    return
+  fi
+  if [ -s "$STATUS_LOG" ] && grep -qxF '[]' "$STATUS_LOG"; then
+    printf 'React Native target visible; in-app bridge not ready yet'
+    bundle_progress "$METRO_LOG"
+    return
+  fi
+  printf 'bridge probe failed'
+  bundle_progress "$METRO_LOG"
+}
+
+bridge_has_route() {
+  (cd "$TARGET" && APP_ROOT="$TARGET" node "$BRIDGE_CJS" status > "$STATUS_LOG" 2>&1) \
+  && node - "$STATUS_LOG" <<'NODE'
+const fs = require('fs');
+try {
+  const value = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  const targets = Array.isArray(value) ? value : [value];
+  if (!targets.some((t) => t && typeof t === 'object' && t.route)) process.exit(1);
+} catch { process.exit(1); }
+NODE
+}
+
+for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
+  if bridge_has_route; then
+    printf 'Mobile bridge ready\n' >&2
+    exit 0
+  fi
+  if [ "$ATTEMPT" = "1" ] || [ $((ATTEMPT % 5)) -eq 0 ]; then
+    printf 'Waiting for Mobile bridge (%s/%s): %s\n' "$ATTEMPT" "$MAX_POLLS" "$(bridge_wait_reason)" >&2
+  fi
+  sleep 2
+done
+
+cat "$STATUS_LOG" >&2 || true
+printf 'wait-for-bridge: bridge did not become ready on port %s (%s polls × 2s = %ss)\n' \
+  "$PORT" "$MAX_POLLS" "$((MAX_POLLS * 2))" >&2
+printf '  Next: check %s — or run mm-harness app-status\n' "$STATUS_LOG" >&2
+exit 1

package/adapters/mobile/yarn-setup.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# yarn-setup — install node_modules for MetaMask Mobile.
+#
+# Inputs:  --target <metamask-mobile dir>  (default $PWD)
+# Outputs: yarn install output on stderr; exit 0 pass, 1 install failed, 2 bad args.
+#
+# Single device op: install node_modules. No other sequencing.
+set -euo pipefail
+
+TARGET="$PWD"
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)  TARGET="$2"; shift 2 ;;
+    -h|--help) printf 'Usage: yarn-setup.sh [--target <dir>]\n'; exit 0 ;;
+    *) printf 'yarn-setup: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+TARGET="$(cd "$TARGET" && pwd)"
+cd "$TARGET" && exec yarn setup

package/{orchestration/lib → adapters/shared}/cli-ux.sh

@@ -26,19 +26,15 @@ recipe_color() {
 }
 
 recipe_progress_script() {
-  printf '%s' "${RECIPE_PROGRESS_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/progress.mjs}"
-}
-
-recipe_home_script() {
-  printf '%s' "${RECIPE_HOME_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/cli-home.mjs}"
+  printf '%s' "${RECIPE_PROGRESS_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/src/progress.ts}"
 }
 
 recipe_log_tui_script() {
-  printf '%s' "${RECIPE_LOG_TUI_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/log-tui.mjs}"
+  printf '%s' "${RECIPE_LOG_TUI_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/adapters/shared/log-tui.mjs}"
 }
 
 recipe_version_script() {
-  printf '%s' "${RECIPE_VERSION_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/orchestration/lib/cli-version.mjs}"
+  printf '%s' "${RECIPE_VERSION_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/src/cli-version.ts}"
 }
 
 recipe_log_ui_mode() {
@@ -79,7 +75,7 @@ recipe_instant_hint() {
 
 recipe_progress() {
   local verb="$1" phase="$2" message="$3" elapsed="${4:-}"
-  local args=(emit --verb "$verb" --phase "$phase" --message "$message")
+  local args=(emit --command "$verb" --phase "$phase" --message "$message")
   [ -n "$elapsed" ] && args+=(--elapsed-ms "$elapsed")
   [ "${RECIPE_PROGRESS_JSON:-}" = "1" ] && args+=(--json)
   node "$(recipe_progress_script)" "${args[@]}" || true
@@ -87,7 +83,7 @@ recipe_progress() {
 
 recipe_done() {
   local verb="$1" status="$2" message="$3" elapsed="${4:-}"
-  local args=(done --verb "$verb" --status "$status" --message "$message")
+  local args=(done --command "$verb" --status "$status" --message "$message")
   [ -n "$elapsed" ] && args+=(--elapsed-ms "$elapsed")
   [ "${RECIPE_PROGRESS_JSON:-}" = "1" ] && args+=(--json)
   node "$(recipe_progress_script)" "${args[@]}" || true

package/{orchestration/lib → adapters/shared}/log-tui.mjs

@@ -4,7 +4,63 @@
  */
 import fs from 'node:fs';
 import { parseArgs } from 'node:util';
-import { color, colorLogEvent } from './cli-color.mjs';
+// Inline color helpers — self-contained so both the runner copy and any
+// installed copy work without an external module dependency.
+const STYLES = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  label: '\x1b[1;36m',
+  cmd: '\x1b[1m',
+  ok: '\x1b[1;32m',
+  warn: '\x1b[1;33m',
+  err: '\x1b[1;31m',
+  info: '\x1b[0;37m',
+  accent: '\x1b[1;35m',
+  path: '\x1b[2m',
+  comment: '\x1b[2m',
+  active: '\x1b[1m',
+};
+
+function colorEnabled(stream = process.stderr) {
+  if (process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0') {
+    return false;
+  }
+  if (process.env.RECIPE_NO_COLOR === '1') return false;
+  if (process.env.RECIPE_COLOR === '1' || process.env.FORCE_COLOR === '1') return true;
+  return Boolean(stream?.isTTY);
+}
+
+function color(style, text, { stream = process.stderr } = {}) {
+  const value = String(text);
+  if (!colorEnabled(stream)) return value;
+  const code = STYLES[style];
+  if (!code) return value;
+  return `${code}${value}${STYLES.reset}`;
+}
+
+function classifyLogEvent(event) {
+  const text = String(event || '');
+  if (/Module build failed|^ERROR in |BUILD FAILED|compiled with [1-9][0-9]* error/iu.test(text)) {
+    return 'err';
+  }
+  if (/compiled successfully|compiled with [0-9]+ warning|PASS runtime-launch|launch pass|verify pass|build complete/iu.test(text)) {
+    return 'ok';
+  }
+  if (/phase [0-9]\/[0-9]|prepare pipeline|snapshot|fixture:|dist-freshness|build-health/iu.test(text)) {
+    return 'label';
+  }
+  if (/webpack [0-9]+%|Bundl(ed|ing)|(iOS|Android).*%/iu.test(text)) {
+    return 'warn';
+  }
+  return 'info';
+}
+
+function colorLogEvent(event, { latest = false, stream = process.stderr } = {}) {
+  const style = classifyLogEvent(event);
+  const painted = color(style === 'label' ? 'label' : style, event, { stream });
+  return latest ? color('active', painted, { stream }) : painted;
+}
 
 const DEFAULT_EVENTS = 10;
 

package/{orchestration/lib → adapters/shared}/open-debug.mjs

@@ -115,16 +115,34 @@ function openUrl(url) {
   return null;
 }
 
+// CDP-eval fallback: invoke DevSettings native module directly via the bridge
+// when the Metro HTTP endpoint is unreachable or returns a non-OK response.
+// Used for both debug (openDebugger) and dev-menu (show).
+async function tryDevSettingsCdpFallback(numericPort, normalizedAction) {
+  const bridgePath = new URL('cdp-bridge.cjs', import.meta.url).pathname;
+  const expression =
+    normalizedAction === 'dev-menu'
+      ? 'NativeModules.DevSettings.show()'
+      : 'NativeModules.DevSettings.openDebugger()';
+  const result = spawnSync(process.execPath, [bridgePath, 'eval', expression], {
+    encoding: 'utf8',
+    env: { ...process.env, WATCHER_PORT: String(numericPort) },
+    timeout: 15000,
+  });
+  return result.status === 0;
+}
+
 async function openMobileDebugger(port, action, shouldOpen) {
   const normalizedAction = action === 'dev-menu' ? 'dev-menu' : 'debug';
-  const path = normalizedAction === 'dev-menu' ? '/open-dev-menu' : '/open-debugger';
+  const urlPath = normalizedAction === 'dev-menu' ? '/open-dev-menu' : '/open-debugger';
   const numericPort = Number.parseInt(String(port), 10);
   if (!Number.isInteger(numericPort) || numericPort <= 0) {
     return { ok: false, adapter: 'mobile', action: normalizedAction, error: 'invalid-port', port };
   }
 
+  let metroError = null;
   try {
-    const opened = await fetchOk(`http://127.0.0.1:${numericPort}${path}`, { method: 'POST' });
+    const opened = await fetchOk(`http://127.0.0.1:${numericPort}${urlPath}`, { method: 'POST' });
     if (opened) {
       return {
         ok: true,
@@ -135,16 +153,21 @@ async function openMobileDebugger(port, action, shouldOpen) {
         opened: shouldOpen,
       };
     }
+    metroError = 'metro-http-nok';
   } catch (error) {
+    metroError = error instanceof Error ? error.message : String(error);
+  }
+
+  // CDP-eval fallback via DevSettings native module.
+  const cdpOk = await tryDevSettingsCdpFallback(numericPort, normalizedAction);
+  if (cdpOk) {
     return {
-      ok: false,
+      ok: true,
       adapter: 'mobile',
       action: normalizedAction,
-      method: 'metro-http',
+      method: 'cdp-eval',
       port: numericPort,
-      error: error instanceof Error ? error.message : String(error),
-      hint: 'Metro may be down or the debug target is not ready. Try recipe refresh, then recipe runtime-status.',
-      fallback: 'cdp-eval',
+      opened: shouldOpen,
     };
   }
 
@@ -154,9 +177,8 @@ async function openMobileDebugger(port, action, shouldOpen) {
     action: normalizedAction,
     method: 'metro-http',
     port: numericPort,
-    error: 'metro-http-failed',
-    hint: 'Metro rejected the open-debugger request. Try recipe refresh, then recipe runtime-status.',
-    fallback: 'cdp-eval',
+    error: metroError,
+    hint: 'Metro may be down or the debug target is not ready. Check metro status and try again.',
   };
 }
 

package/{orchestration/lib → adapters/shared}/resolve-farmslot-ports.sh

@@ -142,3 +142,50 @@ apply_resolved_extension_ports() {
     esac
   done <<< "$resolved"
 }
+
+# Mobile slot defaults: derive Metro port + iOS simulator name from directory suffix.
+# Port formula: 8060 + N (slot 1 → 8061). iOS simulator: mm-N.
+# Mirrors the extension convention (6660+N / 9010+N) for multi-slot mobile farms.
+resolve_mobile_slot_defaults() {
+  local repo="$1" n
+  n="$(infer_extension_slot_suffix "$repo" || true)"
+  [ -n "$n" ] || return 1
+  printf 'WATCHER_PORT=%s\n' "$((8060 + n))"
+  printf 'IOS_SIMULATOR=mm-%s\n' "$n"
+  printf 'SLOT_ID=local-mobile-%s\n' "$n"
+}
+
+resolve_mobile_runtime_ports() {
+  local repo="${1:-.}"
+  if resolve_farmslot_ports_by_repo "$repo"; then
+    return 0
+  fi
+  resolve_mobile_slot_defaults "$repo"
+}
+
+apply_resolved_mobile_ports() {
+  local repo="${1:-.}" line key val from_pool=false resolved=""
+  if resolved="$(resolve_farmslot_ports_by_repo "$repo" 2>/dev/null)"; then
+    from_pool=true
+  elif resolved="$(resolve_mobile_slot_defaults "$repo" 2>/dev/null)"; then
+    from_pool=false
+  else
+    return 0
+  fi
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      WATCHER_PORT)
+        if [ "$from_pool" = true ] || [ -z "${WATCHER_PORT:-}" ]; then WATCHER_PORT="$val"; fi
+        ;;
+      IOS_SIMULATOR)
+        if [ "$from_pool" = true ] || [ -z "${IOS_SIMULATOR:-}" ]; then IOS_SIMULATOR="$val"; fi
+        ;;
+      SLOT_ID)
+        if [ "$from_pool" = true ] || [ -z "${RECIPE_SLOT_ID:-}" ]; then RECIPE_SLOT_ID="$val"; fi
+        ;;
+    esac
+  done <<< "$resolved"
+}

package/adapters/shared/sync-wallet-fixture.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# sync-wallet-fixture.sh — copy the wallet fixture to the canonical runtime slot.
+#
+# Purpose:
+#   After a successful overlay install, ensures the canonical wallet fixture is
+#   present in the checkout's runtime dir. Non-zero exit is informational (no
+#   fixture source found); the install already succeeded, so the overlay is fresh.
+#
+# Inputs (flags / env):
+#   --target <checkout>     (default $PWD)
+#   --slot-id <id>          (env FARMSLOT_SLOT_ID, SLOT_ID — farmslot sync source)
+#   --cdp-port <port>       (env CDP_PORT — extension fixture seeding port)
+#
+# Outputs:
+#   Copies wallet-fixture.json to <target>/<RECIPE_RUNTIME_DIR>/wallet-fixture.json
+#   when a source is found. Exit 0 always (non-zero only when no source found;
+#   callers treat this as informational).
+#
+# OS-glue only: file copy and farmslot delegation; decision logic lives in
+# src/commands/fixtures.ts.
+set -uo pipefail
+
+TARGET="$PWD"
+SLOT_ID="${FARMSLOT_SLOT_ID:-${SLOT_ID:-}}"
+CDP_PORT="${CDP_PORT:-}"
+
+require_value() { [ "$#" -ge 2 ] || { printf 'Missing value for %s\n' "$1" >&2; exit 2; }; }
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)   require_value "$@"; TARGET="$2";   shift 2 ;;
+    --slot-id)  require_value "$@"; SLOT_ID="$2";  shift 2 ;;
+    --cdp-port) require_value "$@"; CDP_PORT="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: sync-wallet-fixture.sh [--target <dir>] [--slot-id <id>] [--cdp-port <port>]\n'
+      exit 0
+      ;;
+    *) printf 'Unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+TARGET="$(cd "$TARGET" && pwd)"
+RUNTIME_DIR="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
+CANONICAL="$TARGET/$RUNTIME_DIR/wallet-fixture.json"
+
+mkdir -p "$(dirname "$CANONICAL")"
+
+# Already present — nothing to do.
+if [ -f "$CANONICAL" ]; then
+  exit 0
+fi
+
+# RECIPE_WALLET_FIXTURE env points at a fixture directly.
+if [ -n "${RECIPE_WALLET_FIXTURE:-}" ] && [ -f "${RECIPE_WALLET_FIXTURE}" ]; then
+  cp "${RECIPE_WALLET_FIXTURE}" "$CANONICAL"
+  chmod 600 "$CANONICAL" 2>/dev/null || true
+  printf 'sync-wallet-fixture: linked wallet-fixture.json from RECIPE_WALLET_FIXTURE\n' >&2
+  exit 0
+fi
+
+# Farmslot slot sync (requires farmslot root and sync-fixtures.sh).
+if [ -n "$SLOT_ID" ]; then
+  FARMSLOT_ROOT="${FARMSLOT_ROOT:-}"
+  for candidate in "$HOME/dev/farmslot" "$HOME/farmslot"; do
+    [ -d "$candidate/scripts" ] || continue
+    FARMSLOT_ROOT="$candidate"
+    break
+  done
+  if [ -n "$FARMSLOT_ROOT" ] && [ -f "$FARMSLOT_ROOT/scripts/sync-fixtures.sh" ]; then
+    if bash "$FARMSLOT_ROOT/scripts/sync-fixtures.sh" --slot "$SLOT_ID" 2>/dev/null; then
+      [ -f "$CANONICAL" ] && exit 0
+    fi
+  fi
+fi
+
+# No fixture source found — informational non-zero (callers tolerate this).
+printf 'sync-wallet-fixture: no wallet fixture source found for %s\n' "$TARGET" >&2
+exit 1

package/bin/mm-harness

@@ -1,10 +1,9 @@
 #!/usr/bin/env bash
 # mm-harness — the single front door for the MetaMask recipe loop.
 #
-# Same node/tsx resolution mechanism as bin/metamask-recipe, but the entry is the
-# commander-based CLI (runner/src/mm-harness-cli.ts) that presents only the
-# validated end-state surface. Legacy names (metamask-recipe/mm-recipe/mme-recipe,
-# manifest/live/runtime-*) stay reachable via their own bins until the caller sweep.
+# The entry is the commander-based CLI (src/mm-harness-cli.ts) that presents the
+# end-state surface; it resolves node/tsx/dist the same way whether the package is
+# installed as a dependency or run from a source checkout.
 set -euo pipefail
 SOURCE="${BASH_SOURCE[0]}"
 while [ -L "$SOURCE" ]; do
@@ -19,13 +18,13 @@ done
 SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" && pwd -P)"
 RUNNER_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
-ENSURE_DEPS="$RUNNER_DIR/orchestration/lib/ensure-runner-deps.sh"
+ENSURE_DEPS="$RUNNER_DIR/adapters/shared/ensure-runner-deps.sh"
 if [ -f "$ENSURE_DEPS" ]; then
   # shellcheck disable=SC1090
   bash "$ENSURE_DEPS" "$RUNNER_DIR"
 fi
 
-ENTRY_TS="$RUNNER_DIR/runner/src/mm-harness-cli.ts"
+ENTRY_TS="$RUNNER_DIR/src/mm-harness-cli.ts"
 ENTRY_DIST="$RUNNER_DIR/dist/mm-harness-cli.js"
 
 find_protocol_root() {

package/docs/CLI-SPEC.md

@@ -36,8 +36,8 @@ exhaustive —
 - **REMOVE** — name/bin/subcommand deleted in the wave; **requires a one-line justification** (needs Arthur's sign-off).
 
 **No row may be unmapped.** An unmapped row means the refactor is not allowed to
-proceed. Source of truth: the bins' `case` statements + the naming audit in
-[harness-cli.md](harness-cli.md). Every row is real.
+proceed. Source of truth: the bins' `case` statements + the naming audit.
+Every row is real.
 
 ## Surface A — `metamask-recipe` typed CLI (`runner/src/cli.ts`)
 
@@ -913,3 +913,42 @@ The fleet is just another agent-grade caller:
   slot's prepare hook calls the same verb with slot context; dispatch scales it
   across the fleet.
 
+## Appendix — Extension runtime lifecycle (internal notes)
+
+Internal implementation notes for the Extension runtime lifecycle — the
+self-healing path that gets a checkout from "installed" to "a live, verified
+extension under CDP control". These are **not** a public command surface: the
+probes below are internal functions, composed for you by `launch --verify` and by
+the readiness commands (`doctor --fix`, `verify`). The runner is the source of
+truth for Extension harness injection, readiness decisions, extension-id
+resolution, and live CDP health checks.
+
+Public entry points:
+
+- **`install`** writes the Extension runtime overlay under the configured harness
+  root. CI/agents run it explicitly; the daily-loop commands auto-ensure it.
+- **`verify`** confirms the overlay is present and healthy — a live CDP health
+  probe when a runtime is reachable, no launch.
+- **`launch --verify`** installs the overlay if missing, launches/attaches the
+  extension, and polls CDP until the runtime is ready.
+- **`doctor` / `doctor --fix`** report readiness and (with `--fix`) run the
+  healing steps below WITHOUT starting the app.
+
+Internal lifecycle stages, composed in order (each idempotent, each reporting the
+cheapest next action so the path converges rather than rebuilding from scratch):
+
+- **Extension-id resolution** — resolves the deterministic unpacked extension id
+  from `dist/chrome/manifest.json`, optionally verified against a live CDP target.
+  Runs first; every later stage keys off this id.
+- **Readiness decision** — inspects the checkout + live browser and returns the
+  cheapest next action (`install`, `build`, `relaunch`, or `ready`) plus the
+  concrete `actions[]` to execute.
+- **Runtime launch** — launches Chrome with the installed harness helper, seeds
+  the wallet fixture, and runs live smoke verification. Two tiers: reuse the
+  existing dist (quick relaunch), or the clean-build path (clear webpack cache,
+  start the harness-owned watcher, wait for a clean compile, then launch + verify).
+- **Convergence** — converges the live browser to exactly one healthy `home.html`
+  tab (closing strays, reopening if needed) and confirms it with the health probe.
+- **Health probe** — read-only liveness probe for the running extension over CDP;
+  the final gate of convergence and the standalone answer for `verify`.
+