@deeeed/metamask-harness 0.2.0

package/orchestration/porcelain/mme-recipe

@@ -0,0 +1,1181 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage:
+  mme-recipe                         home status screen (default)
+  mme-recipe status [--json]         readiness summary + suggested next commands
+  mme-recipe ports [--json]          slot ports, runtime paths, tmux hint
+  mme-recipe up [--json] [--dry-run] decide + run minimum work to reach ready
+  mme-recipe sync [--json]           refresh harness scripts + canonicalize wallet fixture
+  mme-recipe completion [install]    install shell tab completion (bash + zsh)
+  mme-recipe prepare                 install harness and optionally validate CDP health
+    --target <repo> --cdp-port <port> --runtime-dir <dir> [--validate]
+  mme-recipe runtime-status [--json] structured decision/health status
+  mme-recipe decision                runtime-decision (what next?)
+  mme-recipe update                  perform the recommended runtime action
+  mme-recipe ready                   ensure one healthy extension home tab
+  mme-recipe watch                   start/reuse one webpack watcher for fast refresh
+  mme-recipe stop                    stop this checkout's watcher
+  mme-recipe logs [--full]           tail last build events (default) or full webpack log
+  mme-recipe rebuild                 clean webpack + browser launch + verify (2-8 min)
+  mme-recipe reset                   alias for rebuild
+  mme-recipe reload                  alias for rebuild (browser refresh semantics)
+  mme-recipe reopen|launch           aliases for rebuild
+  mme-recipe refresh                 fast refresh using an active watcher only
+  mme-recipe build                   rebuild when no watcher; refresh when watcher is active
+  mme-recipe refresh:once            one-shot refresh-build helper, then ready
+  mme-recipe sidepanel [cycle|open]  use harness sidepanel helper
+  mme-recipe debug [--json] [worker] open Chrome DevTools for extension UI or worker
+  mme-recipe interactive             interactive menu
+  mme-recipe actions [--json]
+  mme-recipe doctor [--json]
+  mme-recipe run <recipe.json> [args] run recipe with detected CDP/env
+  mme-recipe <recipe.json> [args]    shortcut for run
+
+Detects Extension root, recipe runtime context, CDP_PORT, WATCHER_PORT.
+EOF
+  recipe_speed_ladder
+}
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+runner="$script_dir/metamask-recipe"
+# This script lives at <root>/orchestration/porcelain/; the runner root is two up.
+runner_root="$(cd "$script_dir/../.." && pwd -P)"
+# shellcheck disable=SC1091
+. "$runner_root/orchestration/lib/harness-path.sh"
+. "$runner_root/orchestration/lib/cli-ux.sh"
+# shellcheck disable=SC1091
+. "$runner_root/orchestration/lib/resolve-farmslot-ports.sh"
+RECIPE_RUNNER_ROOT="$runner_root"
+install_script="$runner_root/orchestration/extension/inject.mjs"
+open_debug_script="$runner_root/orchestration/lib/open-debug.mjs"
+
+find_extension_root() {
+  local dir="$(pwd -P)"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/package.json" ] && { grep -q 'metamask-extension' "$dir/package.json" 2>/dev/null || [[ "$(basename "$dir")" == metamask-extension* ]]; }; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+json_field() {
+  local file="$1" field="$2"
+  [ -f "$file" ] || return 1
+  node - "$file" "$field" <<'NODE'
+const fs = require('fs');
+const [file, field] = process.argv.slice(-2);
+try {
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const value = field.split('.').reduce((node, key) => node?.[key], data);
+  if (value !== undefined && value !== null && value !== '') process.stdout.write(String(value));
+} catch { process.exit(1); }
+NODE
+}
+
+load_env_file() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line#export }"
+    case "$line" in
+      CDP_PORT=*|RECIPE_CDP_PORT=*|WATCHER_PORT=*|RECIPE_WATCHER_PORT=*)
+        key="${line%%=*}"
+        val="${line#*=}"
+        val="${val%%#*}"
+        val="$(printf '%s' "$val" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' -e 's/^"//' -e 's/"$//' -e "s/^'//" -e "s/'$//")"
+        [ -n "${!key:-}" ] || export "$key=$val"
+        ;;
+    esac
+  done < "$file"
+}
+
+infer_slot_number() {
+  local root="$1" base
+  base="$(basename "$root")"
+  [[ "$base" =~ -([0-9]+)$ ]] && printf '%s\n' "${BASH_REMATCH[1]}"
+}
+
+ensure_extension_node() {
+  local arn
+  for arn in \
+    "$runner_root/orchestration/lib/activate-repo-node.sh" \
+    "$root/$harness_root/extension/scripts/lib/activate-repo-node.sh"; do
+    [ -f "$arn" ] || continue
+    # shellcheck disable=SC1090
+    . "$arn"
+    break
+  done
+  if command -v require_repo_node >/dev/null 2>&1; then
+    require_repo_node "$root"
+    return $?
+  fi
+  echo "mme-recipe: activate-repo-node.sh missing; run: recipe sync" >&2
+  return 1
+}
+
+write_extension_runtime_context() {
+  local farmslot="${FARMSLOT_ROOT:-$HOME/dev/farmslot}"
+  local slot_id="${RECIPE_SLOT_ID:-}"
+  [ -n "$slot_id" ] || slot_id="$(json_field "$runtime_json" slotId 2>/dev/null || true)"
+  [ -n "$slot_id" ] || { [ -n "${slot:-}" ] && slot_id="local-extension-${slot}"; }
+  apply_resolved_extension_ports "$root"
+  [ -n "${CDP_PORT:-}" ] || return 0
+  [ -n "${WATCHER_PORT:-}" ] || return 0
+  if [ -x "$farmslot/scripts/write-runtime-context.sh" ]; then
+    bash "$farmslot/scripts/write-runtime-context.sh" \
+      --repo "$root" \
+      --slot-id "${slot_id:-local-extension-${slot:-1}}" \
+      --runtime-dir "$runtime_dir" \
+      --platform chrome-extension \
+      --cdp-port "$CDP_PORT" \
+      --watcher-port "$WATCHER_PORT" \
+      --strict false >/dev/null
+    return 0
+  fi
+  mkdir -p "$root/$runtime_dir"
+  cat > "$root/$runtime_dir/agentic-runtime.json" <<JSON
+{
+  "slotId": "${slot_id:-local-extension-${slot:-1}}",
+  "cdpPort": ${CDP_PORT},
+  "watcherPort": ${WATCHER_PORT}
+}
+JSON
+  cat > "$root/$runtime_dir/agentic-runtime.env" <<ENV
+# Generated by mme-recipe sync
+export CDP_PORT='${CDP_PORT}'
+export RECIPE_CDP_PORT='${CDP_PORT}'
+export WATCHER_PORT='${WATCHER_PORT}'
+export RECIPE_WATCHER_PORT='${WATCHER_PORT}'
+ENV
+}
+
+init_context() {
+  root="$(find_extension_root)" || { echo "mme-recipe: run from a metamask-extension checkout" >&2; exit 2; }
+  runtime_dir="$(recipe_runtime_dir)"
+  harness_root="$(harness_root)"
+  export RECIPE_RUNTIME_DIR="$runtime_dir" RECIPE_HARNESS_ROOT="$harness_root"
+  runtime_json="$root/$runtime_dir/recipe-runtime.json"
+  [ -f "$runtime_json" ] || runtime_json="$root/$runtime_dir/agentic-runtime.json"
+  load_env_file "$root/$runtime_dir/recipe-runtime.env"
+  load_env_file "$root/$runtime_dir/agentic-runtime.env"
+  load_env_file "$root/.js.env"
+  load_env_file "$root/.env"
+  load_env_file "$root/.env.local"
+  [ -n "${CDP_PORT:-}" ] || CDP_PORT="$(json_field "$runtime_json" cdpPort || true)"
+  [ -n "${WATCHER_PORT:-}" ] || WATCHER_PORT="$(json_field "$runtime_json" watcherPort || json_field "$runtime_json" devServerPort || true)"
+  slot="$(infer_slot_number "$root" || true)"
+  apply_resolved_extension_ports "$root"
+  if [ -n "$slot" ]; then
+    [ -n "${CDP_PORT:-}" ] || CDP_PORT="$((6660 + slot))"
+    [ -n "${WATCHER_PORT:-}" ] || WATCHER_PORT="$((9010 + slot))"
+  fi
+  export CDP_PORT RECIPE_CDP_PORT="${CDP_PORT:-}" WATCHER_PORT RECIPE_WATCHER_PORT="${WATCHER_PORT:-}"
+  mkdir -p "$root/temp/recipe-artifacts"
+}
+
+
+pretty_json() {
+  node -e '
+let d="";
+process.stdin.on("data", c => d += c).on("end", () => {
+  const color = process.env.RECIPE_COLOR === "1";
+  const c = (code, s) => color ? `\x1b[${code}m${s}\x1b[0m` : s;
+  try {
+    const v = JSON.parse(d);
+    const printDecision = (value) => {
+      const decision = value && typeof value === "object" ? value.decision : value;
+      if (!decision) return false;
+      const reasonCode = value && typeof value === "object" ? value.reasonCode : undefined;
+      const reasons = value && typeof value === "object" ? value.reasons : undefined;
+      console.log(`${c("1;33", "Decision")}: ${c("1;32", decision)}${reasonCode ? ` ${c("2", "-")} ${c("0;37", reasonCode)}` : ""}`);
+      if (Array.isArray(reasons)) for (const r of reasons) console.log(`  ${c("2", "-")} ${r}`);
+      return true;
+    };
+    if (v.schemaVersion === 1 && v.status && v.cdpPort !== undefined) {
+      const status = String(v.status).toUpperCase();
+      const code = status === "PASS" ? "1;32" : "1;31";
+      console.log(`${c(code, status)} ${c("1;36", "runtime-launch")} ${c("2", `cdp=${v.cdpPort}`)}`);
+      if (v.reason) console.log(`  ${c("2", "reason")}: ${c("0;37", v.reason)}`);
+      if (v.fix) console.log(`  ${c("1;33", "fix")}: ${v.fix}`);
+      if (v.artifactsDir) console.log(`  ${c("2", "artifacts")}: ${v.artifactsDir}`);
+      return;
+    }
+    if (v.schemaVersion === 1 && v.adapter && typeof v.ready === "boolean") {
+      const label = v.ready ? "READY" : "NOT READY";
+      const code = v.ready ? "1;32" : "1;33";
+      console.log(`${c(code, label)} ${c("1;36", v.adapter)}${v.reason ? ` ${c("2", "-")} ${c("0;37", v.reason)}` : ""}`);
+      if (v.cdp && v.cdp.port) console.log(`${c("1;36", "CDP")}: ${v.cdp.port}${v.cdp.health && v.cdp.health.status ? ` ${c("2", `(${v.cdp.health.status})`)}` : ""}`);
+      if (v.watcher && v.watcher.port) console.log(`${c("1;36", "Watcher")}: ${v.watcher.port}`);
+      if (v.fixture) console.log(`${c("1;36", "Fixture")}: ${v.fixture.present ? "present" : "missing"}${v.fixture.path ? ` ${c("2", v.fixture.path)}` : ""}`);
+      if (v.decision) printDecision(v.decision);
+      if (Array.isArray(v.errors) && v.errors.length) for (const e of v.errors) console.log(`${c("1;31", "Error")}: ${e}`);
+      return;
+    }
+    if (v.decision) {
+      printDecision(v);
+      return;
+    }
+    if (v.adapter && Array.isArray(v.actions) && v.actions.every(a => a && a.name)) {
+      console.log(`${c("1;36", "Actions")} ${c("2", `(${v.adapter})`)}:`);
+      for (const a of v.actions) {
+        console.log(`  ${c("1;32", a.name)}${a.description ? ` ${c("2", "-")} ${c("0;37", a.description)}` : ""}`);
+      }
+      return;
+    }
+    if (v.status && v.adapter) {
+      const status = String(v.status).toUpperCase();
+      const code = status === "PASS" || status === "OK" ? "1;32" : status === "FAIL" || status === "ERROR" ? "1;31" : "1;33";
+      console.log(`${c(code, status)} ${c("1;36", v.adapter)}${v.compatibilityMode ? ` ${c("2", "-")} ${v.compatibilityMode}` : ""}`);
+      return;
+    }
+    if (v.account || v.route || v.deviceName) {
+      console.log(`${c("1;36", "Device")}: ${v.deviceName || "?"}${v.platform ? ` ${c("2", `(${v.platform})`)}` : ""}`);
+      console.log(`${c("1;36", "Route")}: ${v.route && v.route.name ? v.route.name : JSON.stringify(v.route || null)}`);
+      if (v.account) console.log(`${c("1;36", "Account")}: ${v.account.name || "?"} ${c("2", v.account.address || "")}`);
+      return;
+    }
+    console.log(JSON.stringify(v, null, 2));
+  } catch {
+    process.stdout.write(d);
+  }
+})'
+}
+
+json_requested() {
+  for arg in "$@"; do [ "$arg" = "--json" ] && return 0; done
+  return 1
+}
+
+full_logs_requested() {
+  for arg in "$@"; do
+    case "$arg" in
+      --full|-f) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+dry_run_requested() {
+  for arg in "$@"; do
+    case "$arg" in
+      --dry-run|--explain|-n) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+color_requested() {
+  [ "${RECIPE_NO_COLOR:-}" != "1" ] && { [ "${RECIPE_COLOR:-}" = "1" ] || [ "${FORCE_COLOR:-}" = "1" ] || [ -t 1 ]; }
+}
+
+pipe_pretty() {
+  if color_requested; then (export RECIPE_COLOR=1; pretty_json); else pretty_json; fi
+}
+
+run_pretty() {
+  if json_requested "$@"; then "$@"; else "$@" | pipe_pretty; fi
+}
+
+run_json_pretty() {
+  if json_requested "$@"; then "$@"; else "$@" --json | pipe_pretty; fi
+}
+log() { printf 'mme-recipe: %s\n' "$*" >&2; }
+need_cdp() { [ -n "${CDP_PORT:-}" ] || { echo "mme-recipe: CDP_PORT not found" >&2; exit 2; }; }
+
+report_open_debug() {
+  local payload="$1" want_json="$2"
+  if [ "$want_json" = true ]; then
+    printf '%s\n' "$payload"
+    return 0
+  fi
+  node - "$payload" <<'NODE'
+const [text] = process.argv.slice(2);
+try {
+  const v = JSON.parse(text);
+  if (v.ok) {
+    const detail = v.method ? ` via ${v.method}` : '';
+    const where = v.cdpPort ? ` (cdp ${v.cdpPort})` : '';
+    const kind = v.targetKind === 'worker' ? 'service worker' : 'extension page';
+    console.log(`mme-recipe: opened ${kind} DevTools${detail}${where}`);
+    if (v.target?.url) console.log(`mme-recipe: target ${v.target.url}`);
+    if (v.configureHint) console.log(`mme-recipe: chrome://inspect target ${v.configureHint}`);
+    if (v.hint) console.log(`mme-recipe: ${v.hint}`);
+    process.exit(0);
+  }
+  console.error(`mme-recipe: ${v.error || 'failed to open debugger'}`);
+  if (v.hint) console.error(`mme-recipe: ${v.hint}`);
+  process.exit(1);
+} catch (error) {
+  console.error(`mme-recipe: ${error.message}`);
+  process.exit(1);
+}
+NODE
+}
+
+open_debug_ui() {
+  init_context
+  need_cdp
+  local target_kind="page" want_json=false
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --json) want_json=true; shift ;;
+      --target)
+        target_kind="$2"
+        shift 2
+        ;;
+      worker|service-worker|background)
+        target_kind="worker"
+        shift
+        ;;
+      page|ui)
+        target_kind="page"
+        shift
+        ;;
+      -h|--help)
+        echo "Usage: mme-recipe debug [--json] [worker|page]"
+        return 0
+        ;;
+      *) echo "mme-recipe debug: unknown arg: $1" >&2; return 2 ;;
+    esac
+  done
+  local payload exit_code=0
+  payload="$(node "$open_debug_script" --adapter extension --cdp-port "$CDP_PORT" --target "$target_kind" --json 2>/dev/null)" || exit_code=$?
+  if [ "$exit_code" -eq 0 ]; then
+    report_open_debug "$payload" "$want_json"
+    return 0
+  fi
+  report_open_debug "$payload" "$want_json" || return 1
+}
+
+do_completion() {
+  local install_script="$runner_root/scripts/install-completions.sh"
+  bash "$install_script" "${1:-install}" "${@:2}"
+}
+
+do_sync() {
+  init_context
+  local start=$SECONDS farmslot_slot="" seed_script="" fixture_ready=false summary_file=""
+  RECIPE_CLI_PREFIX=mme-recipe
+  recipe_progress sync start "refreshing harness + fixture context"
+  farmslot_slot="$(json_field "$runtime_json" slotId 2>/dev/null || true)"
+  [ -n "$farmslot_slot" ] || { [ -n "${slot:-}" ] && farmslot_slot="local-extension-${slot}"; }
+  seed_script="$root/$harness_root/extension/scripts/seed-fixture.sh"
+  log "sync: refreshing harness scripts"
+  if ! RECIPE_RUNTIME_DIR="$runtime_dir" "$install_script" --target "$root"; then
+    recipe_done sync fail "harness inject failed" $((SECONDS - start))
+    return 1
+  fi
+  log "sync: canonicalizing wallet fixture"
+  if recipe_sync_wallet_fixture "$root" "$runtime_dir" "${CDP_PORT:-}" "$seed_script" "$farmslot_slot"; then
+    fixture_ready=true
+    log "sync: fixture ready at ${runtime_dir}/wallet-fixture.json"
+  else
+    log "sync: fixture missing - create ${runtime_dir}/wallet-fixture.json or set RECIPE_WALLET_FIXTURE"
+  fi
+  if recipe_check_harness_stale extension "$root" "$harness_root" "$runner_root"; then
+    log "sync: warning - harness still reports stale after inject"
+  else
+    log "sync: harness up to date"
+  fi
+  log "sync: writing runtime context (cdp=${CDP_PORT:-?} watcher=${WATCHER_PORT:-?})"
+  write_extension_runtime_context
+  summary_file="$root/$runtime_dir/sync-summary.json"
+  mkdir -p "$(dirname "$summary_file")"
+  node - "$summary_file" "$fixture_ready" <<'NODE'
+const fs = require('fs');
+const [file, fixtureReady] = process.argv.slice(2);
+fs.writeFileSync(file, `${JSON.stringify({
+  schemaVersion: 1,
+  adapter: 'extension',
+  status: 'pass',
+  harnessRefreshed: true,
+  fixtureReady: fixtureReady === 'true',
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+  if json_requested "$@"; then
+    cat "$summary_file"
+  fi
+  if $fixture_ready; then
+    recipe_done sync pass "harness refreshed; fixture ready" $((SECONDS - start))
+  else
+    recipe_done sync pass "harness refreshed; fixture missing" $((SECONDS - start))
+  fi
+  return 0
+}
+
+prepare_extension() {
+  local target="" cdp_port="${CDP_PORT:-${RECIPE_CDP_PORT:-}}" runtime_dir="$(recipe_runtime_dir)" validate=false
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --target) target="$2"; shift 2 ;;
+      --cdp-port) cdp_port="$2"; validate=true; shift 2 ;;
+      --runtime-dir) runtime_dir="$2"; shift 2 ;;
+      --validate) validate=true; shift ;;
+      -h|--help)
+        echo "Usage: mme-recipe prepare [--target <repo>] [--cdp-port <port>] [--runtime-dir <dir>] [--validate]"
+        return 0
+        ;;
+      *) echo "mme-recipe prepare: unknown arg: $1" >&2; return 2 ;;
+    esac
+  done
+  if [ -n "$target" ]; then
+    target="$(cd "$target" && pwd -P)"
+    (cd "$target" && RECIPE_RUNTIME_DIR="$runtime_dir" "$install_script" --target "$target")
+  else
+    init_context
+    target="$root"
+    RECIPE_RUNTIME_DIR="$runtime_dir" "$install_script" --target "$target"
+  fi
+  if $validate; then
+    [ -n "$cdp_port" ] || { echo "mme-recipe prepare: --validate requires --cdp-port or CDP_PORT" >&2; return 2; }
+    run_json_pretty "$runner" runtime-health --adapter extension --target "$target" --cdp-port "$cdp_port"
+  fi
+}
+
+harness_helper() {
+  local field="$1" fallback="$2" rel script manifest
+  manifest="$root/$harness_root/extension/manifest.json"
+  rel="$(json_field "$manifest" "runtimeHelpers.$field" || true)"
+  if [ -n "$rel" ]; then
+    case "$rel" in
+      /*) script="$rel" ;;
+      *) script="$root/$rel" ;;
+    esac
+  else
+    script="$root/$fallback"
+  fi
+  [ -f "$script" ] || { echo "mme-recipe: missing $field helper. Run: recipe sync" >&2; exit 1; }
+  printf '%s\n' "$script"
+}
+
+status_home() {
+  init_context
+  if ! json_requested "$@"; then
+    recipe_instant_hint "checking extension runtime..."
+    recipe_progress status start "probing CDP, watcher, and readiness"
+  fi
+  local rs_file="$root/$runtime_dir/runtime-status.json"
+  local dec_file="$root/$runtime_dir/.recipe-decision.json"
+  local slot_id harness_stale=false
+  mkdir -p "$root/$runtime_dir"
+  recipe_warn_harness_stale extension "$root" "$harness_root" "$runner_root" && harness_stale=false || harness_stale=true
+  runtime_status --json > "$rs_file"
+  "$runner" runtime-decision --adapter extension --target "$root" \
+    ${CDP_PORT:+--cdp-port "$CDP_PORT"} \
+    ${WATCHER_PORT:+--watch-log "$root/$runtime_dir/webpack.log"} \
+    --json > "$dec_file" 2>/dev/null || : > "$dec_file"
+  slot_id="$(json_field "$runtime_json" slotId || true)"
+  local home_args=(
+    --adapter extension --target "$root" --runtime-dir "$runtime_dir"
+    --cdp-port "${CDP_PORT:-}" --watcher-port "${WATCHER_PORT:-}"
+    --runtime-status-file "$rs_file" --decision-file "$dec_file"
+  )
+  [ "$harness_stale" = true ] && home_args+=(--harness-stale)
+  if json_requested "$@"; then
+    node "$(recipe_home_script)" "${home_args[@]}" --json
+  else
+    node "$(recipe_home_script)" "${home_args[@]}"
+  fi
+}
+
+show_ports() {
+  init_context
+  local slot_id
+  slot_id="$(json_field "$runtime_json" slotId || true)"
+  local args=(
+    --mode ports --adapter extension --target "$root" --runtime-dir "$runtime_dir"
+    --cdp-port "${CDP_PORT:-}" --watcher-port "${WATCHER_PORT:-}" --slot-id "${slot_id:-}"
+  )
+  if json_requested "$@"; then
+    node "$(recipe_home_script)" "${args[@]}" --json
+  else
+    node "$(recipe_home_script)" "${args[@]}"
+  fi
+}
+
+status() { status_home "$@"; }
+decision() { init_context; run_json_pretty "$runner" runtime-decision --adapter extension --target "$root" ${CDP_PORT:+--cdp-port "$CDP_PORT"} ${WATCHER_PORT:+--watch-log "$root/$runtime_dir/webpack.log"} "$@"; }
+ready() { init_context; need_cdp; exec "$runner" ensure-ready --adapter extension --target "$root" --cdp-port "$CDP_PORT" "$@"; }
+
+decision_field() {
+  node - "$1" "$2" <<'NODE'
+const [text, field] = process.argv.slice(2);
+try {
+  const value = JSON.parse(text);
+  const result = field.split('.').reduce((node, key) => node?.[key], value);
+  if (result !== undefined && result !== null) process.stdout.write(String(result));
+} catch {
+  process.exit(1);
+}
+NODE
+}
+
+runtime_status() {
+  local target="" cdp_port="" runtime_dir_arg=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --target) target="$2"; shift 2 ;;
+      --cdp-port) cdp_port="$2"; shift 2 ;;
+      --runtime-dir) runtime_dir_arg="$2"; shift 2 ;;
+      --json) shift ;;
+      -h|--help)
+        echo "Usage: mme-recipe runtime-status [--target <repo>] [--cdp-port <port>] [--runtime-dir <dir>] [--json]"
+        return 0
+        ;;
+      *) echo "mme-recipe runtime-status: unknown arg: $1" >&2; return 2 ;;
+    esac
+  done
+  [ -n "$target" ] && cd "$target"
+  [ -n "$runtime_dir_arg" ] && export RECIPE_RUNTIME_DIR="$runtime_dir_arg"
+  [ -n "$cdp_port" ] && export CDP_PORT="$cdp_port" RECIPE_CDP_PORT="$cdp_port"
+  init_context
+  local runtime_abs="$root/$runtime_dir"
+  local status_file="$runtime_abs/runtime-status.json"
+  mkdir -p "$runtime_abs"
+  local decision_json health_json health_exit=0
+  decision_json="$("$runner" runtime-decision --adapter extension --target "$root" ${CDP_PORT:+--cdp-port "$CDP_PORT"} ${WATCHER_PORT:+--watch-log "$root/$runtime_dir/webpack.log"} --json)"
+  if [ -n "${CDP_PORT:-}" ]; then
+    health_json="$("$runner" runtime-health --adapter extension --target "$root" --cdp-port "$CDP_PORT" --json 2>/dev/null)" || health_exit=$?
+  else
+    health_json=""
+  fi
+  node - "$root" "$runtime_dir" "${CDP_PORT:-}" "${WATCHER_PORT:-}" "$status_file" "$decision_json" "$health_json" "$health_exit" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const [target, runtimeDir, cdpPort, watcherPort, statusFile, decisionText, healthText, healthExit] = process.argv.slice(2);
+const parse = (label, text) => {
+  if (!text) return { value: null, error: null };
+  try {
+    return { value: JSON.parse(text), error: null };
+  } catch (error) {
+    return { value: null, error: `${label} JSON parse failed: ${error.message}` };
+  }
+};
+const decisionResult = parse('runtime-decision', decisionText);
+const healthResult = parse('runtime-health', healthText);
+const decision = decisionResult.value;
+const health = healthResult.value;
+const ready = decision?.decision === 'ready' && (!health || health.status === 'PASS');
+function fixtureStatus() {
+  const candidates = [
+    process.env.RECIPE_WALLET_FIXTURE,
+    path.join(target, runtimeDir, 'wallet-fixture.json'),
+    path.join(target, 'temp/runtime/wallet-fixture.json'),
+    cdpPort ? path.join(target, `temp/.recipe-validation-${cdpPort}/wallet-fixture.json`) : null,
+    path.join(target, 'temp/.agent-validation/wallet-fixture.json'),
+  ].filter(Boolean);
+  const fixturePath = candidates.find((candidate) => fs.existsSync(candidate)) || null;
+  return {
+    present: Boolean(fixturePath),
+    path: fixturePath,
+    candidates,
+  };
+}
+const status = {
+  schemaVersion: 1,
+  adapter: 'extension',
+  target,
+  runtimeDir,
+  updatedAt: new Date().toISOString(),
+  ready,
+  reason: ready ? 'ready' : decision?.reasonCode || health?.findings?.[0] || 'not-ready',
+  cdp: { port: cdpPort ? Number(cdpPort) : null, healthExit: Number(healthExit || 0), health },
+  watcher: { port: watcherPort ? Number(watcherPort) : null },
+  fixture: fixtureStatus(),
+  decision,
+  errors: [decisionResult.error, healthResult.error].filter(Boolean),
+};
+fs.writeFileSync(statusFile, `${JSON.stringify(status, null, 2)}\n`);
+console.log(JSON.stringify(status, null, 2));
+NODE
+}
+
+do_reopen() {
+  init_context; need_cdp
+  local pids launch_args start=$SECONDS exit_code=0 rebuild_log watch_pid=""
+  recipe_progress rebuild start "preparing clean runtime rebuild"
+  pids="$(watcher_pids || true)"
+  if [ -n "$pids" ]; then
+    log "stopping existing watcher before rebuild ($(pids_inline "$pids"))"
+    printf '%s\n' "$pids" | xargs kill 2>/dev/null || true
+    sleep 2
+    pids="$(watcher_pids || true)"
+    if [ -n "$pids" ]; then
+      log "force stopping existing watcher ($(pids_inline "$pids"))"
+      printf '%s\n' "$pids" | xargs kill -9 2>/dev/null || true
+    fi
+  fi
+  rm -f "$root/$runtime_dir/webpack.pid" "$root/$runtime_dir/recipe-harness-webpack.pid"
+  rebuild_log="$root/$runtime_dir/rebuild.log"
+  mkdir -p "$(dirname "$rebuild_log")"
+  : > "$rebuild_log"
+  log "rebuild cdp=$CDP_PORT watcher=${WATCHER_PORT:-?}"
+  log "phases: (1) clean webpack build  (2) dist snapshot  (3) browser+fixture  (4) live verify"
+  log "typical duration 2-8 min; compact events below (full log: ${runtime_dir}/rebuild.log, recipe logs --full)"
+  recipe_progress rebuild webpack-compile "clean webpack build starting"
+  if [ "$(recipe_log_ui_mode)" != "quiet" ] && ! full_logs_requested "$@"; then
+    recipe_watch_rebuild_log "$rebuild_log" &
+    watch_pid=$!
+  fi
+  launch_args=(runtime-launch --adapter extension --target "$root" --cdp-port "$CDP_PORT" --start-watch)
+  if json_requested "$@"; then
+    env RECIPE_LOG_TUI_PARENT=1 "$runner" "${launch_args[@]}" --json "$@" 2>&1 | tee "$rebuild_log" | pipe_pretty || exit_code=$?
+  else
+    env RECIPE_LOG_TUI_PARENT=1 "$runner" "${launch_args[@]}" "$@" 2>&1 | tee "$rebuild_log" || exit_code=$?
+  fi
+  [ -n "$watch_pid" ] && kill "$watch_pid" 2>/dev/null && wait "$watch_pid" 2>/dev/null || true
+  if [ "$exit_code" -eq 0 ]; then
+    # The console viewer is created by launch.sh inside runtime-launch; no
+    # second create here (avoids killing/truncating the just-opened tab).
+    recipe_done rebuild pass "runtime rebuild complete" $((SECONDS - start))
+  else
+    recipe_done rebuild fail "runtime rebuild failed" $((SECONDS - start))
+    node "$(recipe_log_tui_script)" events --log "$rebuild_log" --events "$(recipe_log_events_limit)" >&2 || true
+    recipe_failure_playbook rebuild "runtime-launch did not pass" \
+      --prefix mme-recipe \
+      --log "${runtime_dir}/rebuild.log" \
+      --artifact "temp/recipe/harness/extension/runtime-launch/"
+  fi
+  return "$exit_code"
+}
+
+# Live extension-console viewer tab: tail the running extension's service worker
+# + UI-page console in a tmux window, mirroring the webpack tab. Guarded so a
+# missing tmux/session/CDP is a silent no-op (never affects the bringup result).
+start_console_viewer_window() {
+  local cdp_port="${1:-}" session window console_tail log_file hr
+  # Numeric-validate before interpolating into the tmux shell command.
+  case "$cdp_port" in ''|*[!0-9]*) return 0 ;; esac
+  command -v tmux >/dev/null 2>&1 || return 0
+  hr="$(harness_root 2>/dev/null || true)"
+  [ -n "$hr" ] || return 0
+  console_tail="$root/$hr/extension/scripts/console-tail.mjs"
+  [ -f "$console_tail" ] || return 0
+  session="${RECIPE_TMUX_SESSION:-}"
+  if [ -z "$session" ] && [ -n "${slot:-}" ]; then session="mme-$slot"; fi
+  [ -n "$session" ] || return 0
+  tmux has-session -t "$session" 2>/dev/null || return 0
+  window="console-${cdp_port}"
+  log_file="$root/$runtime_dir/extension-console.log"
+  mkdir -p "$(dirname "$log_file")"
+  : > "$log_file"
+  tmux kill-window -t "${session}:${window}" >/dev/null 2>&1 || true
+  tmux new-window -d -t "$session" -n "$window" "exec node $(printf '%q' "$console_tail") --cdp-port ${cdp_port} --log $(printf '%q' "$log_file")"
+  log "extension console viewer in tmux window ${session}:${window}"
+}
+
+# Close the webpack `tail -F` viewer window paired with the watcher do_stop kills.
+# Guarded no-op when there is no tmux/session/port. The console viewer is NOT
+# closed here: it tails the running browser, which `recipe stop` leaves up.
+close_webpack_viewer_window() {
+  command -v tmux >/dev/null 2>&1 || return 0
+  local session="${RECIPE_TMUX_SESSION:-}"
+  if [ -z "$session" ] && [ -n "${slot:-}" ]; then session="mme-$slot"; fi
+  [ -n "$session" ] || return 0
+  # Match the open-side name (do_watch/start-watch use the same :-default fallback).
+  tmux kill-window -t "${session}:webpack-${WATCHER_PORT:-default}" >/dev/null 2>&1 || true
+}
+
+do_up() {
+  init_context
+  local start=$SECONDS report action exit_code=0
+  recipe_progress up start "evaluating extension runtime"
+  report="$("$runner" runtime-decision --adapter extension --target "$root" \
+    ${CDP_PORT:+--cdp-port "$CDP_PORT"} \
+    ${WATCHER_PORT:+--watch-log "$root/$runtime_dir/webpack.log"} --json)"
+  action="$(decision_field "$report" decision || true)"
+  if dry_run_requested "$@"; then
+    if json_requested "$@"; then
+      printf '%s\n' "$report"
+    else
+      printf '%s\n' "$report" | pipe_pretty
+    fi
+    case "$action" in
+      ready) log "dry-run: would run ensure-ready (seconds)" ;;
+      relaunch|build) log "dry-run: would run recipe rebuild (2-8 min)" ;;
+      install) log "dry-run: would run yarn install --immutable, then re-check" ;;
+      blocked|unknown|'') log "dry-run: blocked — inspect recipe status" ;;
+      *) log "dry-run: unsupported decision ($action)" ;;
+    esac
+    return 0
+  fi
+  if json_requested "$@"; then
+    printf '%s\n' "$report"
+  else
+    printf '%s\n' "$report" | pipe_pretty
+  fi
+  case "$action" in
+    ready)
+      if [ -n "${CDP_PORT:-}" ]; then
+        recipe_progress up ready "ensuring healthy extension tab"
+        if json_requested "$@"; then
+          "$runner" ensure-ready --adapter extension --target "$root" --cdp-port "$CDP_PORT" --json || exit_code=$?
+        else
+          "$runner" ensure-ready --adapter extension --target "$root" --cdp-port "$CDP_PORT" || exit_code=$?
+        fi
+      fi
+      if [ "$exit_code" -eq 0 ]; then
+        start_console_viewer_window "${CDP_PORT:-}"
+        recipe_done up pass "runtime ready" $((SECONDS - start))
+      else
+        recipe_done up fail "ensure-ready failed" $((SECONDS - start))
+        recipe_failure_playbook up "ensure-ready failed" --prefix mme-recipe --log "${runtime_dir}/webpack.log"
+      fi
+      return "$exit_code"
+      ;;
+    relaunch|build)
+      recipe_progress up "$action" "running rebuild path"
+      do_reopen "$@" || exit_code=$?
+      if [ "$exit_code" -eq 0 ]; then
+        recipe_done up pass "rebuild finished" $((SECONDS - start))
+      fi
+      return "$exit_code"
+      ;;
+    install)
+      if [ "${RECIPE_UP_INSTALL_ATTEMPTED:-0}" = "1" ]; then
+        local reason_code=""
+        report="$("$runner" runtime-decision --adapter extension --target "$root" \
+          ${CDP_PORT:+--cdp-port "$CDP_PORT"} \
+          ${WATCHER_PORT:+--watch-log "$root/$runtime_dir/webpack.log"} --json)"
+        reason_code="$(decision_field "$report" reasonCode || true)"
+        recipe_done up fail "install did not resolve runtime (${reason_code:-install})" $((SECONDS - start))
+        if json_requested "$@"; then
+          printf '%s\n' "$report"
+        else
+          printf '%s\n' "$report" | pipe_pretty
+        fi
+        recipe_failure_playbook up "yarn install completed but runtime-decision is still install" \
+          --prefix mme-recipe
+        return 2
+      fi
+      recipe_progress up install "installing dependencies"
+      export RECIPE_UP_INSTALL_ATTEMPTED=1
+      if ! (cd "$root" && yarn install --immutable); then
+        recipe_done up fail "yarn install failed" $((SECONDS - start))
+        return 1
+      fi
+      "$runner" runtime-decision --adapter extension --target "$root" \
+        ${CDP_PORT:+--cdp-port "$CDP_PORT"} \
+        ${WATCHER_PORT:+--watch-log "$root/$runtime_dir/webpack.log"} \
+        --record-baseline --json >/dev/null
+      RECIPE_UP_INSTALL_ATTEMPTED=1 do_up "$@"
+      ;;
+    blocked|unknown|'')
+      recipe_done up fail "blocked (${action:-unknown})" $((SECONDS - start))
+      recipe_failure_playbook up "blocked (${action:-unknown})" --prefix mme-recipe
+      return 2
+      ;;
+    *)
+      recipe_done up fail "unsupported decision: $action" $((SECONDS - start))
+      recipe_failure_playbook up "unsupported decision: $action" --prefix mme-recipe
+      return 2
+      ;;
+  esac
+}
+
+do_update() {
+  init_context
+  local report action
+  report="$("$runner" runtime-decision --adapter extension --target "$root" ${CDP_PORT:+--cdp-port "$CDP_PORT"} ${WATCHER_PORT:+--watch-log "$root/$runtime_dir/webpack.log"} --json)"
+  printf '%s\n' "$report" | pipe_pretty
+  action="$(decision_field "$report" decision || true)"
+  case "$action" in
+    ready)
+      if [ -n "${CDP_PORT:-}" ]; then
+        "$runner" ensure-ready --adapter extension --target "$root" --cdp-port "$CDP_PORT" --json | pipe_pretty
+      else
+        log "runtime decision is ready; CDP_PORT is not set, so no browser action was needed"
+      fi
+      ;;
+    relaunch)
+      do_reopen "$@"
+      ;;
+    build)
+      do_reopen "$@"
+      ;;
+    install)
+      log "installing dependencies before runtime update"
+      (cd "$root" && yarn install --immutable)
+      do_update "$@"
+      ;;
+    blocked|unknown|'')
+      echo "mme-recipe: runtime decision is ${action:-unknown}; inspect with: recipe decision --json" >&2
+      return 2
+      ;;
+    *)
+      echo "mme-recipe: unsupported runtime decision: $action" >&2
+      return 2
+      ;;
+  esac
+}
+
+watcher_pids() {
+  local pids pid_file pid current_pid command
+  pids="$(
+    ps -axo pid=,command= | while read -r current_pid command; do
+      [ -n "${current_pid:-}" ] || continue
+      case "$command" in
+        *"yarn start"*|*"webpack --watch"*|*"development/webpack/launch.ts --watch"*) ;;
+        *) continue ;;
+      esac
+      if printf '%s' "$command" | grep -Fq "$root"; then
+        printf '%s\n' "$current_pid"
+        continue
+      fi
+      if command -v lsof >/dev/null 2>&1; then
+        if lsof -a -p "$current_pid" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p' | grep -Fxq "$root"; then
+          printf '%s\n' "$current_pid"
+        fi
+      fi
+    done
+    true
+  )"
+  pid_file="$root/$runtime_dir/webpack.pid"
+  pid="$(cat "$pid_file" 2>/dev/null || true)"
+  if [ -n "$pid" ] && kill -0 "$pid" >/dev/null 2>&1; then
+    if ! printf '%s\n' "$pids" | grep -qx "$pid"; then
+      pids="$(printf '%s\n%s\n' "$pids" "$pid" | sed '/^$/d')"
+    fi
+  fi
+  printf '%s\n' "$pids" | sed '/^$/d'
+}
+
+do_watch() {
+  init_context
+  local pids log_file pid_file session window log_q compiled elapsed
+  pids="$(watcher_pids || true)"
+  if [ -n "$pids" ]; then
+    log "watcher already running ($(pids_inline "$pids"))"
+    return 0
+  fi
+  log_file="$root/$runtime_dir/webpack.log"
+  pid_file="$root/$runtime_dir/webpack.pid"
+  mkdir -p "$(dirname "$log_file")"
+  rm -f "$pid_file"
+  : > "$log_file"
+  rm -rf "$root/node_modules/.cache/webpack"
+  log "starting watcher port=${WATCHER_PORT:-default} log=${log_file#$root/}"
+  ensure_extension_node
+  local path_prefix="${REPO_NODE_PATH_PREFIX:-}"
+  # Launch the watcher detached writing to the log; the tmux window is a read-only tail viewer.
+  (cd "$root" && nohup bash -lc "exec env -u BUNDLED_DEBUGPY_PATH ${path_prefix:+PATH=\"${path_prefix}\$PATH\"} ${WATCHER_PORT:+PORT=\"$WATCHER_PORT\"} yarn start" > "$log_file" 2>&1 & echo $! > "$pid_file")
+  if command -v tmux >/dev/null 2>&1; then
+    session="${RECIPE_TMUX_SESSION:-}"
+    if [ -z "$session" ] && [ -n "${slot:-}" ]; then session="mme-$slot"; fi
+    if [ -n "$session" ] && tmux has-session -t "$session" 2>/dev/null; then
+      window="webpack-${WATCHER_PORT:-default}"
+      log_q="$(printf '%q' "$log_file")"
+      tmux kill-window -t "${session}:${window}" >/dev/null 2>&1 || true
+      tmux new-window -d -t "$session" -n "$window" "exec tail -n +1 -F $log_q"
+    fi
+  fi
+  compiled=false
+  local tail_pid=""
+  if full_logs_requested "$@"; then
+    tail -f "$log_file" &
+    tail_pid=$!
+  elif [ "$(recipe_log_ui_mode)" != "quiet" ]; then
+    node "$(recipe_log_tui_script)" watch \
+      --log "$log_file" \
+      --events "$(recipe_log_events_limit)" \
+      --mode "$(recipe_log_ui_mode)" \
+      --label "webpack watcher" \
+      --success-pattern 'compiled successfully|compiled with [0-9]+ warning|MetaMask .* compiled|Bundle end:' &
+    tail_pid=$!
+  fi
+  for elapsed in $(seq 1 240); do
+    pids="$(watcher_pids || true)"
+    if [ -z "$pids" ]; then
+      if [ "$elapsed" -le 10 ]; then
+        sleep 2
+        continue
+      fi
+      [ -n "$tail_pid" ] && kill "$tail_pid" >/dev/null 2>&1 || true
+      wait "$tail_pid" 2>/dev/null || true
+      recipe_failure_playbook watch "watcher exited before compile completed" \
+        --prefix mme-recipe --log "${log_file#$root/}"
+      node "$(recipe_log_tui_script)" events --log "$log_file" --events 15 >&2 || true
+      rm -f "$pid_file"
+      return 1
+    fi
+    printf '%s\n' "$pids" | head -1 > "$pid_file"
+    if grep -Eq 'Module build failed|^ERROR in |compiled with [1-9][0-9]* error' "$log_file" 2>/dev/null; then
+      [ -n "$tail_pid" ] && kill "$tail_pid" >/dev/null 2>&1 || true
+      wait "$tail_pid" 2>/dev/null || true
+      recipe_failure_playbook watch "webpack build failed" \
+        --prefix mme-recipe --log "${log_file#$root/}"
+      node "$(recipe_log_tui_script)" events --log "$log_file" --events 15 >&2 || true
+      return 1
+    fi
+    if grep -Eq 'compiled successfully|compiled with [0-9]+ warning|MetaMask .* compiled|Bundle end: service worker|Bundle end:.*app-init' "$log_file" 2>/dev/null; then
+      compiled=true
+      [ -n "$tail_pid" ] && kill "$tail_pid" >/dev/null 2>&1 || true
+      wait "$tail_pid" 2>/dev/null || true
+      break
+    fi
+    sleep 2
+  done
+  if [ "$compiled" != true ]; then
+    [ -n "$tail_pid" ] && kill "$tail_pid" >/dev/null 2>&1 || true
+    wait "$tail_pid" 2>/dev/null || true
+    recipe_failure_playbook watch "compile timeout (8 min)" \
+      --prefix mme-recipe --log "${log_file#$root/}"
+    node "$(recipe_log_tui_script)" events --log "$log_file" --events 15 >&2 || true
+    return 1
+  fi
+  pids="$(watcher_pids || true)"
+  printf '%s\n' "$pids" | head -1 > "$pid_file"
+  log "watcher compiled ($(pids_inline "$pids")); use: recipe refresh"
+}
+
+pids_inline() {
+  printf '%s' "$1" | tr '\n' ' '
+}
+
+latest_source_stamp() {
+  node - "$root" <<'NODE'
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const root = process.argv[2];
+function lines(args) {
+  try { return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8' }).split('\n').filter(Boolean); }
+  catch { return []; }
+}
+const files = new Set([
+  ...lines(['diff', '--name-only', 'HEAD']),
+  ...lines(['ls-files', '--others', '--exclude-standard']),
+]);
+let best = { mtime: 0, file: '' };
+for (const rel of files) {
+  if (!/\.(tsx?|jsx?|mjs|cjs|json|scss|css)$/u.test(rel)) continue;
+  const abs = path.join(root, rel);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+  const mtime = fs.statSync(abs).mtimeMs;
+  if (mtime > best.mtime) best = { mtime, file: rel };
+}
+if (best.mtime) console.log(`${Math.floor(best.mtime)}\t${best.file}`);
+NODE
+}
+
+latest_dist_mtime_ms() {
+  node - "$root" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const root = process.argv[2];
+const dir = path.join(root, 'dist/chrome');
+let best = 0;
+function walk(p) {
+  if (!fs.existsSync(p)) return;
+  for (const name of fs.readdirSync(p)) {
+    const abs = path.join(p, name);
+    const st = fs.statSync(abs);
+    if (st.isDirectory()) walk(abs);
+    else if (st.isFile()) best = Math.max(best, st.mtimeMs);
+  }
+}
+walk(dir);
+console.log(Math.floor(best));
+NODE
+}
+
+do_stop() {
+  init_context
+  local pids
+  pids="$(watcher_pids || true)"
+  if [ -z "$pids" ]; then
+    log "no watcher running for this checkout"
+    rm -f "$root/$runtime_dir/webpack.pid"
+    close_webpack_viewer_window
+    return 0
+  fi
+  log "stopping watcher ($(pids_inline "$pids"))"
+  printf '%s
+' "$pids" | xargs kill 2>/dev/null || true
+  sleep 2
+  pids="$(watcher_pids || true)"
+  if [ -n "$pids" ]; then
+    log "force stopping watcher ($(pids_inline "$pids"))"
+    printf '%s
+' "$pids" | xargs kill -9 2>/dev/null || true
+  fi
+  rm -f "$root/$runtime_dir/webpack.pid"
+  close_webpack_viewer_window
+  log "next: recipe watch | recipe rebuild"
+}
+
+tail_logs() {
+  init_context
+  local log_file="$root/$runtime_dir/webpack.log"
+  [ -f "$log_file" ] || { echo "mme-recipe: webpack log missing: $runtime_dir/webpack.log. Start with: recipe watch" >&2; return 1; }
+  if full_logs_requested "$@"; then
+    log "full log: $runtime_dir/webpack.log (Ctrl-C to stop)"
+    tail -f "$log_file"
+    return 0
+  fi
+  log "compact tail — full stream: recipe logs --full"
+  exec node "$(recipe_log_tui_script)" tail \
+    --log "$log_file" \
+    --events "$(recipe_log_events_limit)" \
+    --follow \
+    --mode compact
+}
+
+do_refresh_once() {
+  init_context
+  local s
+  s="$(harness_helper refreshBuild "$runtime_dir/refresh-build.sh")"
+  log "one-shot refresh watcher=${WATCHER_PORT:-?}"
+  bash "$s" --repo "$root" ${WATCHER_PORT:+--watcher-port "$WATCHER_PORT"} "$@"
+  if [ -n "${CDP_PORT:-}" ]; then
+    "$runner" ensure-ready --adapter extension --target "$root" --cdp-port "$CDP_PORT" --json || true
+  fi
+}
+
+do_build() {
+  init_context
+  local pids
+  pids="$(watcher_pids || true)"
+  if [ -n "$pids" ]; then
+    do_refresh "$@"
+    return $?
+  fi
+  log "build: no active watcher — running full rebuild path"
+  do_reopen "$@"
+}
+
+do_refresh() {
+  init_context
+  local pids stamp src_mtime src_file dist_mtime timeout elapsed
+  pids="$(watcher_pids || true)"
+  if [ -z "$pids" ]; then
+    recipe_failure_playbook refresh "no active watcher" --prefix mme-recipe
+    return 2
+  fi
+
+  stamp="$(latest_source_stamp || true)"
+  if [ -z "$stamp" ]; then
+    log "watcher active ($(pids_inline "$pids")); no changed source files"
+    [ -n "${CDP_PORT:-}" ] && "$runner" ensure-ready --adapter extension --target "$root" --cdp-port "$CDP_PORT" --json || true
+    return
+  fi
+  src_mtime="${stamp%%$'\t'*}"
+  src_file="${stamp#*$'\t'}"
+  timeout="${RECIPE_REFRESH_TIMEOUT:-90}"
+  log "watcher active ($(pids_inline "$pids")); waiting for incremental build of $src_file"
+
+  for elapsed in $(seq 0 "$timeout"); do
+    dist_mtime="$(latest_dist_mtime_ms)"
+    if [ "$dist_mtime" -ge "$src_mtime" ]; then
+      log "dist/chrome timestamp is current (${elapsed}s); checking runtime"
+      if [ -n "${CDP_PORT:-}" ]; then
+        local ready_json
+        ready_json="$($runner ensure-ready --adapter extension --target "$root" --cdp-port "$CDP_PORT" --json 2>/dev/null || true)"
+        printf '%s
+' "$ready_json"
+        if printf '%s' "$ready_json" | grep -q '"ready"[[:space:]]*:[[:space:]]*true'; then
+          log "runtime ready; run: recipe reopen only if the visible page is stale"
+          return
+        fi
+        recipe_failure_playbook refresh "dist is current but runtime is unhealthy" --prefix mme-recipe
+        return 2
+      fi
+      log "dist/chrome timestamp is current; run: recipe reopen"
+      return
+    fi
+    if [ $elapsed -gt 0 ] && [ $((elapsed % 10)) -eq 0 ]; then
+      log "still waiting for watcher... (${elapsed}s)"
+    fi
+    sleep 1
+  done
+
+  recipe_failure_playbook refresh "watcher did not update dist/chrome within ${timeout}s" \
+    --prefix mme-recipe --log "${runtime_dir}/webpack.log"
+  return 2
+}
+
+sidepanel() {
+  init_context; need_cdp
+  local s
+  s="$(harness_helper sidepanelToggle "$runtime_dir/sidepanel-toggle.sh")"
+  bash "$s" "${1:-cycle}" --cdp-port "$CDP_PORT" --agent-dir "$root/$runtime_dir"
+}
+
+run_recipe() {
+  init_context; need_cdp
+  local recipe="$1"; shift
+  [ -f "$recipe" ] || { echo "mme-recipe: recipe not found: $recipe" >&2; exit 2; }
+  local out="$root/temp/recipe-artifacts/$(basename "$recipe" .json)-$(date -u +%Y%m%dT%H%M%SZ)"
+  log "root=$root cdp=$CDP_PORT watcher=${WATCHER_PORT:-?} out=$out"
+  exec "$runner" run "$recipe" --adapter extension --project-root "$root" --cdp-port "$CDP_PORT" --artifacts-dir "$out" "$@"
+}
+
+interactive() {
+  init_context
+  echo "mme-recipe (${root}, cdp=${CDP_PORT:-?}, watcher=${WATCHER_PORT:-?})"
+  PS3='choose> '
+  select choice in status ports up runtime-status decision update ready rebuild refresh refresh-once watch stop logs debug sidepanel actions doctor quit; do
+    case "$choice" in
+      status) status_home ;;
+      ports) show_ports ;;
+      up) do_up ;;
+      runtime-status) runtime_status | pipe_pretty ;;
+      decision) run_json_pretty "$runner" runtime-decision --adapter extension --target "$root" ${CDP_PORT:+--cdp-port "$CDP_PORT"} ;;
+      update) do_update ;;
+      ready) "$runner" ensure-ready --adapter extension --target "$root" --cdp-port "$CDP_PORT" ;;
+      watch) do_watch ;;
+      stop) do_stop ;;
+      rebuild) do_reopen ;;
+      refresh) do_refresh ;;
+      refresh-once) do_refresh_once ;;
+      logs) tail_logs ;;
+      debug) open_debug_ui ;;
+      sidepanel) sidepanel cycle ;;
+      actions) run_json_pretty "$runner" actions --adapter extension ;;
+      doctor) run_json_pretty "$runner" doctor --adapter extension --target "$root" ;;
+      quit|'') break ;;
+    esac
+    echo
+  done
+}
+
+cmd="${1:-status}"
+[ "$#" -gt 0 ] && shift
+case "$cmd" in
+  -h|--help) usage; exit 0 ;;
+  interactive|menu) interactive ;;
+  sync) do_sync "$@" ;;
+  completion|complete) do_completion "$@" ;;
+  prepare) prepare_extension "$@" ;;
+  status|health|home) status_home "$@" ;;
+  ports) show_ports "$@" ;;
+  up) do_up "$@" ;;
+  runtime-status) if json_requested "$@"; then runtime_status "$@"; else runtime_status "$@" | pipe_pretty; fi ;;
+  decision|decide) decision "$@" ;;
+  update|sync-runtime) do_update "$@" ;;
+  ready|ensure-ready) ready "$@" ;;
+  watch|start-watch|watcher) do_watch "$@" ;;
+  stop|stop-watch|stop-watcher) do_stop "$@" ;;
+  logs|tail|tail-webpack) tail_logs "$@" ;;
+  rebuild|reset|reopen|reload|browser|launch|full-launch|runtime-launch)
+    [ "$cmd" = "reload" ] && log "reload runs a full rebuild (not a tab refresh); for fast updates use: recipe refresh"
+    do_reopen "$@"
+    ;;
+  refresh) do_refresh "$@" ;;
+  build) do_build "$@" ;;
+  refresh:once|refresh-once|build:once|build-once) do_refresh_once "$@" ;;
+  debug|devtools|inspect) open_debug_ui "$@" ;;
+  sidepanel) sidepanel "$@" ;;
+  actions) init_context; run_json_pretty "$runner" actions --adapter extension "$@" ;;
+  doctor) init_context; run_json_pretty "$runner" doctor --adapter extension --target "$root" "$@" ;;
+  run) recipe="${1:-}"; [ -n "$recipe" ] || { usage; exit 2; }; shift; run_recipe "$recipe" "$@" ;;
+  *.json) run_recipe "$cmd" "$@" ;;
+  *) echo "mme-recipe: unknown command or missing recipe: $cmd" >&2; usage; exit 2 ;;
+esac