@deeeed/metamask-harness 0.2.0

package/orchestration/extension/launch.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# launch.sh — extension instance launch: prepare command + CDP readiness
+#
+# Purpose:
+#   Runs the caller-supplied prepare command (cwd = target) for one slot,
+#   then confirms the app-control runtime via extension-readiness.
+#
+# Inputs (flags / env):
+#   --target <metamask-extension> (default $PWD)
+#   --cdp-port <port> (numeric-validated)
+#   --prepare-cmd <cmd> (env RECIPE_HARNESS_EXTENSION_LAUNCH_CMD)
+#   --artifacts-dir <dir> (default <harness>/launch/<UTC>)
+#
+# Outputs:
+#   <artifacts>/summary.json (adapter/action/status/prepare/appControl),
+#   <artifacts>/logs/{launch.log,extension-readiness.json}.
+#   Exit 0 — launch pass; 1 — harness not installed / prepare or readiness
+#   failed; 2 — bad args.
+#
+# Never touches: product source files; anything outside the target's
+# harness dir and the artifacts dir.
+set -euo pipefail
+
+TARGET="$PWD"
+CDP_PORT=""
+ARTIFACTS=""
+PREPARE_CMD="${RECIPE_HARNESS_EXTENSION_LAUNCH_CMD:-}"
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --cdp-port) CDP_PORT="$2"; shift 2 ;;
+    --artifacts-dir) ARTIFACTS="$2"; shift 2 ;;
+    --prepare-cmd) PREPARE_CMD="$2"; shift 2 ;;
+    -h|--help) echo "Usage: launch.sh [--target <metamask-extension>] [--cdp-port <port>] [--prepare-cmd <cmd>] [--artifacts-dir <dir>]"; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+# Reject a non-numeric --cdp-port before it reaches the prepare/launch command.
+if [ -n "$CDP_PORT" ]; then
+  case "$CDP_PORT" in
+    *[!0-9]*) echo "Invalid --cdp-port (must be numeric): $CDP_PORT" >&2; exit 2 ;;
+  esac
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+  [ -f "$_hp" ] && { . "$_hp"; break; }
+done
+unset _hp
+if ! command -v harness_root >/dev/null 2>&1; then
+  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+READINESS_MJS="$SCRIPT_DIR/readiness.mjs"
+if [ ! -f "$READINESS_MJS" ]; then
+  echo "mm-harness: readiness.mjs not found next to $SCRIPT_DIR; reinstall the runner." >&2
+  exit 1
+fi
+TARGET="$(cd "$TARGET" && pwd)"
+HARNESS_DIR="$(harness_dir "$TARGET" extension)"
+ARTIFACTS="${ARTIFACTS:-$HARNESS_DIR/launch/$(date -u +%Y%m%dT%H%M%SZ)}"
+mkdir -p "$ARTIFACTS/logs"
+
+if [ ! -f "$HARNESS_DIR/manifest.json" ]; then
+  echo "Extension recipe harness is not installed in $TARGET. Run metamask-recipe extension prepare --target $TARGET first." >&2
+  exit 1
+fi
+
+LIB_DIR=""
+for _lib in "$SCRIPT_DIR/lib" "$SCRIPT_DIR/../lib"; do
+  [ -f "$_lib/log-tui.mjs" ] && LIB_DIR="$_lib" && break
+done
+unset _lib
+
+if [ -n "$PREPARE_CMD" ]; then
+  launch_log="$ARTIFACTS/logs/launch.log"
+  : > "$launch_log"
+  echo "[recipe-harness] running prepare pipeline (watch/build, dist snapshot, browser, fixture seed)..." | tee "$launch_log"
+  watch_pid=""
+  if [ -n "$LIB_DIR" ] && [ "${RECIPE_LOG_UI:-compact}" != "full" ] && [ "${RECIPE_LOG_TUI_PARENT:-}" != "1" ]; then
+    node "$LIB_DIR/log-tui.mjs" watch \
+      --log "$launch_log" \
+      --events "${RECIPE_LOG_EVENTS:-10}" \
+      --mode "${RECIPE_LOG_UI:-compact}" \
+      --label "extension prepare" \
+      --success-pattern 'yarn start compiled|runtime-dist snapshot complete|Extension harness launch pass|phase 2/2' \
+      --poll-ms 1000 &
+    watch_pid=$!
+  fi
+  set +e
+  (
+    cd "$TARGET"
+    bash -lc "$PREPARE_CMD"
+  ) 2>&1 | tee -a "$launch_log"
+  prepare_status=${PIPESTATUS[0]}
+  set -e
+  [ -n "$watch_pid" ] && kill "$watch_pid" >/dev/null 2>&1 && wait "$watch_pid" 2>/dev/null || true
+else
+  echo "No Extension prepare command supplied; reusing existing CDP runtime if reachable." | tee "$ARTIFACTS/logs/launch.log"
+  prepare_status=0
+fi
+
+status="pass"
+if [ "$prepare_status" -ne 0 ]; then
+  status="fail"
+elif [ -z "$CDP_PORT" ]; then
+  echo "Missing --cdp-port; cannot confirm Extension app-control runtime." | tee -a "$ARTIFACTS/logs/launch.log"
+  status="fail"
+elif node "$READINESS_MJS" --target "$TARGET" --cdp-port "$CDP_PORT" --json > "$ARTIFACTS/logs/extension-readiness.json" 2>&1; then
+  :
+else
+  status="fail"
+fi
+
+# Live extension-console viewer tab (default-on): tail the running extension's
+# service worker + UI-page console in a tmux window, mirroring the Metro/webpack
+# tabs. Skipped silently when there is no tmux session or CDP (headless/CI), so
+# it never affects the launch result.
+if [ "$status" = "pass" ] && [ -n "$CDP_PORT" ] && command -v tmux >/dev/null 2>&1; then
+  console_session="${RECIPE_TMUX_SESSION:-}"
+  if [ -z "$console_session" ] && [[ "$(basename "$TARGET")" =~ -([0-9]+)$ ]]; then
+    console_session="mme-${BASH_REMATCH[1]}"
+  fi
+  console_tail="$SCRIPT_DIR/console-tail.mjs"
+  if [ -n "$console_session" ] && [ -f "$console_tail" ] && tmux has-session -t "$console_session" 2>/dev/null; then
+    console_runtime="$TARGET/$( (cd "$TARGET" && recipe_runtime_dir) 2>/dev/null || echo temp/recipe/runtime)"
+    mkdir -p "$console_runtime"
+    console_log="$console_runtime/extension-console.log"
+    : > "$console_log"
+    console_window="console-${CDP_PORT}"
+    tmux kill-window -t "${console_session}:${console_window}" >/dev/null 2>&1 || true
+    tmux new-window -d -t "$console_session" -n "$console_window" \
+      "exec node $(printf '%q' "$console_tail") --cdp-port ${CDP_PORT} --log $(printf '%q' "$console_log")"
+    echo "[recipe-harness] extension console viewer in tmux window ${console_session}:${console_window}"
+  fi
+fi
+
+TARGET_FOR_SUMMARY="$TARGET" ARTIFACTS_FOR_SUMMARY="$ARTIFACTS" STATUS_FOR_SUMMARY="$status" CDP_PORT_FOR_SUMMARY="$CDP_PORT" PREPARE_SUPPLIED="$([ -n "$PREPARE_CMD" ] && echo true || echo false)" PREPARE_STATUS="$prepare_status" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const target = process.env.TARGET_FOR_SUMMARY;
+const artifacts = process.env.ARTIFACTS_FOR_SUMMARY;
+let readiness = null;
+try { readiness = JSON.parse(fs.readFileSync(path.join(artifacts, 'logs/extension-readiness.json'), 'utf8')); } catch {}
+const appControlStatus =
+  process.env.STATUS_FOR_SUMMARY === 'pass' && readiness && readiness.status !== 'fail' ? 'pass' : 'fail';
+fs.writeFileSync(path.join(artifacts, 'summary.json'), `${JSON.stringify({
+  adapter: 'extension',
+  action: 'launch',
+  status: process.env.STATUS_FOR_SUMMARY,
+  target,
+  cdpPort: process.env.CDP_PORT_FOR_SUMMARY || null,
+  prepare: {
+    commandSupplied: process.env.PREPARE_SUPPLIED === 'true',
+    status: Number(process.env.PREPARE_STATUS) === 0 ? 'pass' : 'fail',
+    exitCode: Number(process.env.PREPARE_STATUS),
+    logPath: path.join(artifacts, 'logs/launch.log'),
+  },
+  runtimePolicy: {
+    runtimeReusePolicy: 'reuse a running harness-compatible CDP target when possible; caller-supplied startup commands must use cached/watch-only paths unless the human explicitly permits a rebuild',
+  },
+  appControl: {
+    status: appControlStatus,
+    readiness,
+  },
+  cleanupCommand: 'Use the installed harness manifest cleanupCommand.',
+  note: 'Launch starts/reuses the harness runtime only; it does not run a recipe or claim evidence validation. Extension startup commands are caller-supplied so the runner does not encode local machine aliases.',
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+
+echo "Extension harness launch $status: $ARTIFACTS/summary.json"
+[ "$status" = "pass" ]

package/orchestration/extension/live.sh

@@ -0,0 +1,320 @@
+#!/usr/bin/env bash
+# live.sh — extension launch-then-verify sequencer for one live slot run
+# mega-string now decomposed into start-watch.sh / snapshot-dist.sh /
+# seed-fixture.sh)
+#
+# Purpose:
+#   Builds the per-run prepare command from the named feature scripts
+#   (watch, dist snapshot, fixture seed, detached chrome, CDP poll), then
+#   runs launch.sh and verify.sh under a timestamped artifact dir.
+#
+# Inputs (flags / env):
+#   --target <metamask-extension> (default $PWD)
+#   --cdp-port <port> (required, numeric-validated)
+#   --launch-existing-dist | --start-watch | --prepare-cmd <cmd>
+#       (env RECIPE_HARNESS_EXTENSION_LAUNCH_CMD)
+#   --dist-dir <rel> (default dist/chrome), --chrome-user-data-dir <dir>,
+#   --remote-flag <KEY=VARIANT[,KEY=VARIANT...]> (pins manifest _flags into the
+#       ephemeral runtime-dist snapshot before launch; omit for default behavior)
+#   --out <recipes-dir>, --artifacts-dir <dir>
+#   env RECIPE_HARNESS_CHROME_BIN (validated executable; else Playwright
+#   chromium with approval-gated install messaging), RECIPE_WALLET_FIXTURE,
+#   RECIPE_HARNESS_LIVE_KEEP (artifact pruning, default 5)
+#
+# Outputs:
+#   <artifacts>/summary.json (adapter/action/status, launch/verify exit
+#   codes + child summary paths, easyCommand), <artifacts>/{launch,verify},
+#   <artifacts>/logs/fixture-source.json provenance.
+#   Exit 0 — launch and verify both passed; 1 — either failed; 2 — bad args.
+#
+# Never touches: product source files; live artifact dirs newer than the
+# pruning window; anything outside the target's harness dir.
+set -euo pipefail
+
+TARGET="$PWD"
+CDP_PORT=""
+ARTIFACTS=""
+OUT=""
+PREPARE_CMD="${RECIPE_HARNESS_EXTENSION_LAUNCH_CMD:-}"
+LAUNCH_EXISTING_DIST=false
+START_WATCH=false
+DIST_DIR="dist/chrome"
+CHROME_USER_DATA_DIR=""
+REMOTE_FLAGS=""
+REMOTE_FLAGS_APPLIED=false
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; TARGET="$2"; shift 2 ;;
+    --out) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; OUT="$2"; shift 2 ;;
+    --cdp-port) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; CDP_PORT="$2"; shift 2 ;;
+    --artifacts-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; ARTIFACTS="$2"; shift 2 ;;
+    --prepare-cmd) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; PREPARE_CMD="$2"; shift 2 ;;
+    --launch-existing-dist) LAUNCH_EXISTING_DIST=true; shift ;;
+    --start-watch|--start-test-watch) START_WATCH=true; LAUNCH_EXISTING_DIST=true; shift ;;
+    --dist-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; DIST_DIR="$2"; shift 2 ;;
+    --chrome-user-data-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; CHROME_USER_DATA_DIR="$2"; shift 2 ;;
+    --remote-flag) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; REMOTE_FLAGS="$2"; shift 2 ;;
+    -h|--help) echo "Usage: live.sh [--target <metamask-extension>] [--out <recipes-dir>] --cdp-port <port> [--launch-existing-dist|--start-watch|--prepare-cmd <cmd>] [--dist-dir dist/chrome] [--remote-flag KEY=VARIANT] [--artifacts-dir <dir>]"; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$CDP_PORT" ] || { echo "Missing --cdp-port for Extension live validation" >&2; exit 2; }
+# Reject a non-numeric port before it is interpolated into the Chrome launch
+# command and the CDP HTTP probes.
+case "$CDP_PORT" in
+  *[!0-9]*) echo "Invalid --cdp-port (must be numeric): $CDP_PORT" >&2; exit 2 ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+  [ -f "$_hp" ] && { . "$_hp"; break; }
+done
+unset _hp
+if ! command -v harness_root >/dev/null 2>&1; then
+  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+# verify.sh is a recipe-tree feature: co-located in installed copies, under
+# runner/extension in a repo checkout.
+VERIFY_SH=""
+for _v in "$SCRIPT_DIR/verify.sh" "$SCRIPT_DIR/../../runner/extension/verify.sh"; do
+  [ -f "$_v" ] && { VERIFY_SH="$_v"; break; }
+done
+unset _v
+if [ -z "$VERIFY_SH" ]; then
+  echo "mm-harness: extension verify.sh not found next to $SCRIPT_DIR; reinstall the runner." >&2
+  exit 1
+fi
+TARGET="$(cd "$TARGET" && pwd)"
+RUNTIME_DIR="$(recipe_runtime_dir)"
+# Runner bin (installed wrapper → source runner). Used by the watch prepare path
+# to defer the cache-clear DECISION to `runtime-decision` (single source) and to
+# record the deps/cache baseline after a confirmed-good build.
+RUNNER_BIN="$(harness_dir "$TARGET" extension)/runner/bin/metamask-recipe"
+OUT="${OUT:-$(harness_root)/extension/runner/recipes}"
+ARTIFACTS="${ARTIFACTS:-$(harness_dir "$TARGET" extension)/live/$(date -u +%Y%m%dT%H%M%SZ)}"
+mkdir -p "$ARTIFACTS/logs"
+
+# Prune stale live artifact dirs (configurable harness root, not a hardcoded path)
+# so old runtime-dist snapshots can't be loaded and don't accumulate to GBs.
+# Keep the most recent few; override count with RECIPE_HARNESS_LIVE_KEEP.
+LIVE_ROOT="$(harness_dir "$TARGET" extension)/live"
+LIVE_KEEP="${RECIPE_HARNESS_LIVE_KEEP:-5}"
+# Must be a positive integer: a non-numeric value would break the arithmetic and a
+# 0 would `tail -n +1` and delete every dir including this run's fresh $ARTIFACTS.
+case "$LIVE_KEEP" in ''|*[!0-9]*) LIVE_KEEP=5 ;; esac
+[ "$LIVE_KEEP" -ge 1 ] 2>/dev/null || LIVE_KEEP=5
+if [ -d "$LIVE_ROOT" ]; then
+  # `|| true`: an empty live/ (no child dirs) makes ls exit non-zero, which would
+  # abort the script under `set -euo pipefail`. Pruning is best-effort.
+  ls -1dt "$LIVE_ROOT"/*/ 2>/dev/null | tail -n "+$((LIVE_KEEP + 1))" | while IFS= read -r _old; do rm -rf "$_old"; done || true
+fi
+
+if $LAUNCH_EXISTING_DIST && [ -z "$PREPARE_CMD" ]; then
+  DIST_ABS="$TARGET/$DIST_DIR"
+  RUNTIME_DIST_ABS="$ARTIFACTS/runtime-dist"
+  PROFILE_ABS="${CHROME_USER_DATA_DIR:-$ARTIFACTS/chrome-profile}"
+  FIXTURE_STATE_ABS="$ARTIFACTS/fixture-state.json"
+  FIXTURE_VALIDATION_ABS="$ARTIFACTS/logs/fixture-account-parity.json"
+  # Wallet fixture resolution chain + provenance live in seed-fixture.sh.
+  WALLET_FIXTURE_ABS="$(bash "$SCRIPT_DIR/seed-fixture.sh" resolve --target "$TARGET" --cdp-port "$CDP_PORT" --source-out "$ARTIFACTS/logs/fixture-source.json")"
+  if [ ! -f "$ARTIFACTS/logs/fixture-source.json" ]; then
+    # resolve failed before writing provenance (invalid RECIPE_WALLET_FIXTURE);
+    # keep the documented missing-provenance artifact.
+    node - "$ARTIFACTS/logs/fixture-source.json" "" <<'NODE'
+const fs = require('fs');
+const [out, fixture] = process.argv.slice(2);
+fs.mkdirSync(require('path').dirname(out), { recursive: true });
+fs.writeFileSync(out, `${JSON.stringify({
+  status: fixture ? 'present' : 'missing',
+  fixturePath: fixture || null,
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+  fi
+  mkdir -p "$PROFILE_ABS"
+  quoted_dist="$(printf '%q' "$DIST_ABS")"
+  quoted_runtime_dist="$(printf '%q' "$RUNTIME_DIST_ABS")"
+  quoted_profile="$(printf '%q' "$PROFILE_ABS")"
+  quoted_seed_fixture="$(printf '%q' "$SCRIPT_DIR/seed-fixture.sh")"
+  quoted_start_watch="$(printf '%q' "$SCRIPT_DIR/start-watch.sh")"
+  quoted_snapshot_dist="$(printf '%q' "$SCRIPT_DIR/snapshot-dist.sh")"
+  quoted_chrome_launcher="$(printf '%q' "$SCRIPT_DIR/launch-browser.cjs")"
+  quoted_fixture_state="$(printf '%q' "$FIXTURE_STATE_ABS")"
+  quoted_fixture_validation="$(printf '%q' "$FIXTURE_VALIDATION_ABS")"
+  quoted_extension_id_file="$(printf '%q' "$TARGET/$RUNTIME_DIR/extension.id")"
+  quoted_target="$(printf '%q' "$TARGET")"
+  quoted_runner="$(printf '%q' "$RUNNER_BIN")"
+  quoted_runtime_dir="$(printf '%q' "$RUNTIME_DIR")"
+  if [ -n "${RECIPE_HARNESS_CHROME_BIN:-}" ]; then
+    CHROME_BIN="$RECIPE_HARNESS_CHROME_BIN"
+    if [ ! -f "$CHROME_BIN" ] || [ ! -x "$CHROME_BIN" ]; then
+      echo "[recipe-harness] RECIPE_HARNESS_CHROME_BIN is not an executable file: $CHROME_BIN" >&2
+      exit 1
+    fi
+  fi
+
+  if [ -z "${CHROME_BIN:-}" ]; then
+    # bash 3.2 (macOS /bin/bash) mis-parses heredocs inside $(...): its scanner
+    # trips on quotes/backticks in the JS. Write the probe to a temp file and
+    # command-substitute a plain `node` invocation instead.
+    _chrome_probe="$(mktemp -t chrome-probe-XXXXXX)"
+    cat > "$_chrome_probe" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const { createRequire } = require('module');
+const requireFromTarget = createRequire(path.join(process.cwd(), 'package.json'));
+
+let chromium = null;
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+for (const pkg of ['@playwright/test', 'playwright']) {
+  try {
+    chromium = requireFromTarget(pkg).chromium;
+    if (chromium) break;
+  } catch (_error) {
+    // Optional Playwright package unavailable; try the next package name.
+  }
+}
+if (!chromium) {
+  console.error('[recipe-harness] Playwright is not available from this checkout; install dependencies first, or set RECIPE_HARNESS_CHROME_BIN to an explicitly approved browser.');
+  process.exit(1);
+}
+
+let executable = '';
+try {
+  executable = chromium.executablePath();
+} catch (error) {
+  const message = error && error.message ? error.message : String(error);
+  console.error(`[recipe-harness] Could not resolve Playwright Chromium executable: ${message}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes); ask the user before running yarn exec playwright install chromium.`);
+  process.exit(1);
+}
+if (!fs.existsSync(executable)) {
+  console.error(`[recipe-harness] Playwright Chromium is not installed at ${executable}. Manual approval required before installing the Playwright Chromium browser cache (no package.json changes). Ask the user for approval; if they agree, run: cd ${shellQuote(process.cwd())} && yarn exec playwright install chromium`);
+  console.error('[recipe-harness] To use a browser that is already installed, set RECIPE_HARNESS_CHROME_BIN=/path/to/chrome explicitly.');
+  process.exit(1);
+}
+
+process.stdout.write(executable);
+NODE
+    CHROME_PROBE_LOG="$ARTIFACTS/logs/chrome-probe.log"
+    CHROME_BIN="$(cd "$TARGET" && node "$_chrome_probe" 2>"$CHROME_PROBE_LOG" || true)"
+    rm -f "$_chrome_probe"
+  fi
+
+  if [ -z "${CHROME_BIN:-}" ]; then
+    for candidate in \
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+      "/Applications/Chromium.app/Contents/MacOS/Chromium" \
+      "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary" \
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"; do
+      if [ -x "$candidate" ]; then
+        CHROME_BIN="$candidate"
+        break
+      fi
+    done
+    if [ -n "${CHROME_BIN:-}" ]; then
+      echo "[recipe-harness] WARN: Playwright Chromium unavailable; falling back to system browser: $CHROME_BIN" >&2
+    fi
+  fi
+
+  if [ -z "${CHROME_BIN:-}" ]; then
+    [ -n "${CHROME_PROBE_LOG:-}" ] && cat "$CHROME_PROBE_LOG" >&2 2>/dev/null || true
+    echo "[recipe-harness] No approved Chromium binary selected; stopping before live Extension launch." >&2
+    exit 1
+  fi
+  quoted_chrome="$(printf '%q' "$CHROME_BIN")"
+  quoted_chrome_log="$(printf '%q' "$ARTIFACTS/logs/chrome.log")"
+  quoted_chrome_pid="$(printf '%q' "$ARTIFACTS/logs/chrome.pid")"
+  prepare_parts=()
+  if $START_WATCH; then
+    prepare_parts+=("bash ${quoted_start_watch} --runtime-dir ${quoted_runtime_dir} --runner-bin ${quoted_runner}")
+  fi
+  prepare_parts+=("bash ${quoted_snapshot_dist} --dist ${quoted_dist} --runtime-dist ${quoted_runtime_dist}")
+  # Optional A/B feature-flag pinning: patch the ephemeral snapshot manifest so
+  # manifest._flags wins over the fetched ClientConfigApi value. No-op unless
+  # --remote-flag was passed; the snapshot is re-created each run, so no revert.
+  if [ -n "$REMOTE_FLAGS" ]; then
+    quoted_pin_flags="$(printf '%q' "$SCRIPT_DIR/pin-remote-flags.cjs")"
+    quoted_remote_flags="$(printf '%q' "$REMOTE_FLAGS")"
+    quoted_runtime_manifest="$(printf '%q' "$RUNTIME_DIST_ABS/manifest.json")"
+    prepare_parts+=("node ${quoted_pin_flags} ${quoted_runtime_manifest} ${quoted_remote_flags}")
+    REMOTE_FLAGS_APPLIED=true
+  fi
+  if [ -n "$WALLET_FIXTURE_ABS" ]; then
+    quoted_wallet_fixture="$(printf '%q' "$WALLET_FIXTURE_ABS")"
+    prepare_parts+=("bash ${quoted_seed_fixture} prefill --target ${quoted_target} --fixture ${quoted_wallet_fixture} --state ${quoted_fixture_state} --profile ${quoted_profile} --extension-dir ${quoted_runtime_dist} --extension-id-file ${quoted_extension_id_file}")
+  fi
+  chrome_launch_cmd="node ${quoted_chrome_launcher} --chrome-bin ${quoted_chrome} --profile ${quoted_profile} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --chrome-log ${quoted_chrome_log} --chrome-pid ${quoted_chrome_pid}"
+  prepare_parts+=("$chrome_launch_cmd")
+  prepare_parts+=("for i in {1..60}; do curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null 2>&1 && break; sleep 1; done; curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null")
+  if [ -n "$WALLET_FIXTURE_ABS" ]; then
+    prepare_parts+=("bash ${quoted_seed_fixture} seed-cdp --target ${quoted_target} --fixture ${quoted_wallet_fixture} --state ${quoted_fixture_state} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --extension-id-file ${quoted_extension_id_file} --out ${quoted_fixture_validation}")
+  fi
+  PREPARE_CMD="set -euo pipefail; $(IFS='; '; printf '%s' "${prepare_parts[*]}")"
+fi
+
+if [ -n "$REMOTE_FLAGS" ] && [ "$REMOTE_FLAGS_APPLIED" != "true" ]; then
+  echo "[recipe-harness] WARN: --remote-flag '$REMOTE_FLAGS' had no effect: flag pinning only applies to the snapshot launch path (--launch-existing-dist/--start-watch without a custom --prepare-cmd)." >&2
+fi
+
+echo "Extension live validation command:"
+display_args=(mm-harness launch --verify --target "$TARGET")
+$LAUNCH_EXISTING_DIST && display_args+=(--launch-existing-dist)
+$START_WATCH && display_args+=(--start-watch)
+[ -n "$REMOTE_FLAGS" ] && display_args+=(--remote-flag "$REMOTE_FLAGS")
+printf '  '
+printf '%q ' "${display_args[@]}"
+printf '\n'
+echo "Launch artifacts: $ARTIFACTS/launch"
+echo "Verify artifacts: $ARTIFACTS/verify"
+
+launch_args=(--target "$TARGET" --cdp-port "$CDP_PORT" --artifacts-dir "$ARTIFACTS/launch")
+[ -n "$PREPARE_CMD" ] && launch_args+=(--prepare-cmd "$PREPARE_CMD")
+
+echo "[recipe-harness] phase 1/2: launch (prepare + CDP readiness)" >&2
+set +e
+"$SCRIPT_DIR/launch.sh" "${launch_args[@]}"
+launch_status=$?
+set -e
+
+verify_status=1
+if [ "$launch_status" -eq 0 ]; then
+  echo "[recipe-harness] phase 2/2: live verify (readiness + smoke recipe)" >&2
+  set +e
+  "$VERIFY_SH" --target "$TARGET" --out "$OUT" --cdp-port "$CDP_PORT" --artifacts-dir "$ARTIFACTS/verify"
+  verify_status=$?
+  set -e
+else
+  echo "Skipping Extension live verify because launch failed; see $ARTIFACTS/launch/summary.json" >&2
+fi
+
+TARGET_FOR_SUMMARY="$TARGET" ARTIFACTS_FOR_SUMMARY="$ARTIFACTS" CDP_PORT_FOR_SUMMARY="$CDP_PORT" LAUNCH_STATUS="$launch_status" VERIFY_STATUS="$verify_status" LAUNCH_EXISTING_DIST="$LAUNCH_EXISTING_DIST" START_WATCH="$START_WATCH" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const artifacts = process.env.ARTIFACTS_FOR_SUMMARY;
+const launchSummary = path.join(artifacts, 'launch', 'summary.json');
+const verifySummary = path.join(artifacts, 'verify', 'summary.json');
+const launchStatus = Number(process.env.LAUNCH_STATUS);
+const verifyStatus = Number(process.env.VERIFY_STATUS);
+fs.writeFileSync(path.join(artifacts, 'summary.json'), `${JSON.stringify({
+  adapter: 'extension',
+  action: 'live',
+  status: launchStatus === 0 && verifyStatus === 0 ? 'pass' : 'fail',
+  target: process.env.TARGET_FOR_SUMMARY,
+  cdpPort: process.env.CDP_PORT_FOR_SUMMARY,
+  launchExistingDist: process.env.LAUNCH_EXISTING_DIST === 'true',
+  startWatch: process.env.START_WATCH === 'true',
+  launch: { exitCode: launchStatus, summaryPath: fs.existsSync(launchSummary) ? launchSummary : null },
+  verify: { exitCode: verifyStatus, summaryPath: fs.existsSync(verifySummary) ? verifySummary : null },
+  easyCommand: `mm-harness launch --verify --target <repo>`,
+  note: 'Runs launch then live verify so a developer can validate browser startup, CDP readiness, recipe bridge, screenshots/fallback classification, and sample recipes from one runner-owned command.',
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+
+echo "Extension live validation summary: $ARTIFACTS/summary.json"
+[ "$launch_status" -eq 0 ] && [ "$verify_status" -eq 0 ]

package/orchestration/extension/pin-remote-flags.cjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// pin-remote-flags.cjs <manifest.json> <KEY=VARIANT[,KEY=VARIANT...]>
+//
+// Pins A/B remote feature-flag variants into an extension manifest's
+// `_flags.remoteFeatureFlags`. MetaMask resolves the active flags as
+//   getRemoteFeatureFlags = merge({}, fetchedState, manifest._flags.remoteFeatureFlags)
+// with the manifest winning, so this deterministically forces a variant in the
+// live browser regardless of the real ClientConfigApi response — which otherwise
+// overwrites any seeded controller state on refetch.
+//
+// Intended for the per-run runtime-dist SNAPSHOT (ephemeral, re-created from
+// dist/chrome on every launch), so it never mutates the real dist/chrome build
+// and needs no revert bookkeeping. Values are written as { name: VARIANT }
+// (named-variant A/B flags); boolean/other flag shapes are out of scope.
+'use strict';
+
+const fs = require('node:fs');
+
+const [, , manifestPath, spec] = process.argv;
+if (!manifestPath || !spec) {
+  throw new Error('usage: pin-remote-flags.cjs <manifest.json> <KEY=VARIANT[,KEY=VARIANT...]>');
+}
+
+const pairs = spec
+  .split(',')
+  .map((entry) => entry.trim())
+  .filter(Boolean);
+if (pairs.length === 0) throw new Error(`--remote-flag had no KEY=VARIANT pairs: ${spec}`);
+
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+manifest._flags = manifest._flags || {};
+const flags = manifest._flags.remoteFeatureFlags || (manifest._flags.remoteFeatureFlags = {});
+
+const applied = [];
+for (const pair of pairs) {
+  const eq = pair.indexOf('=');
+  const key = eq > 0 ? pair.slice(0, eq) : '';
+  const variant = eq > 0 ? pair.slice(eq + 1) : '';
+  if (!key || !variant) throw new Error(`--remote-flag expects KEY=VARIANT, got: ${pair}`);
+  flags[key] = { name: variant };
+  applied.push(`${key}=${variant}`);
+}
+
+fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+console.log(`[flags] Pinned ${applied.join(', ')} into ${manifestPath}`);