@deeeed/metamask-harness 0.3.8 → 0.3.9

package/CHANGELOG.md

@@ -1,19 +1,43 @@
 # Changelog
 
+## 0.3.9 - 2026-07-04
+
+### Fixed
+- **Readiness is presence-authoritative** — a no-baseline mtime-only stale verdict no longer re-runs `yarn setup` inside every launch (warning instead; fingerprint-verified drift still installs), the deps baseline is recorded after any successful setup, and the `ready` decision probes that the dev client is actually running on the target device before doing nothing (`launch` launches).
+- **Slot-context-first resolution** — device/ports resolve from the checkout's `agentic-runtime.json` before pool/formula fallbacks, for mobile (simulator, Metro port) and extension (CDP + watcher ports, overwriting stale inherited env); naming formulas no longer hardcode pool prefixes.
+- **UTF-8 locale for pod-triggering spawns** — CocoaPods no longer dies on multibyte podspecs under locale-less orchestrator environments.
+- **Hermetic contract tests** — tmux/xcrun/adb are stubbed; the Metro log-window opens only in a run-owned session, never an unrelated attached one.
+
+### Added
+- **`mm-harness stop`** — stop the port-scoped Metro this checkout owns and close its log-tail window; idempotent; teaching error on extension/core.
+- **Extension launch streams live** with an upfront intent line (ports named); mobile and extension long operations are never silent.
+- **Doctor reports live runtime state per platform** (deps currency, Metro on the slot's resolved port, dev-client presence) with adapter-scoped, colored runtime-context rows.
+- **Colored grouped help with DEV OVERRIDE banner and SLOT line**; `mmdev-harness` completions; outcome-stating launch summaries with a `[dev]` marker.
+- **docs/UX-PRINCIPLES.md** — the CLI interaction contract (human surface rules; `--json` envelope purity is exempt and inviolable).
+
+## Unreleased
+
+### Fixed
+- **Mobile preflight no longer re-runs `yarn setup` on every launch** — the deps readiness decision escalated an mtime hint to `stale` and ran the FULL `yarn setup` (submodules + inpage bridge + jetify + pods) inside the launch phase on every invocation in orchestrated (farmslot) contexts. `depsCheck` reports `stale` for a no-baseline checkout whenever a manifest is newer than the install markers; the orchestrator's git phase refreshes tracked-file mtimes on every sync while its deps phase leaves `node_modules` untouched, so "manifest newer than markers" is normal and not proof of drift — yet it duplicated the orchestrator's deps work and turned a fast preflight into 15+ minutes (the behavior that also looked like a hang before 0.3.8's streaming). **Presence is now authoritative:** without a recorded baseline an mtime-only `stale` is trusted as `current` (with a one-line stderr warning), so a churned-but-present checkout launches with zero `yarn` in both tiers. Genuine drift is still caught by the recorded-baseline fingerprint. `mm-harness launch` (quick tier / no `--build`) also dropped `preflightMode` before deciding, so the fast contract never took effect; it is threaded through now.
+- **Fast tier never installs; genuine gaps teach the orchestrator** — in the fast tier (quick launch / orchestrated), deps that genuinely need work (absent markers, an absent required package, a fingerprint drift, or Metro unable to resolve a module) return a teaching block naming the orchestrator deps/prepare phase (plus the standalone `yarn setup:expo` / `launch --build` remedies) instead of an implicit setup — deps are the orchestrator's contract. The standalone/full tier still installs.
+- **Deps baseline recorded the instant a setup leaf succeeds** — `prepareMobile` records the deps fingerprint baseline immediately after any successful `yarn-setup`, unconditionally (previously only a later `record: true` re-decide did, gated on the original decision being `install` and on `RECIPE_UP_INSTALL_ATTEMPTED`). Genuine-drift detection is fingerprint-based and self-sustaining after one good install.
+- **CocoaPods no longer crashes on non-UTF-8 podspecs under a locale-less env** — pod-triggering spawns (`yarn setup` / native `yarn start:*`) now pin a UTF-8 `LANG`/`LC_ALL` when the caller has none. A gateway/tmux parent env without a locale made Ruby parse podspecs as US-ASCII and die on the first multibyte byte (`Invalid react-native-mmkv.podspec: "\xE2" on US-ASCII`).
+- **`launch` no longer reports a dead app as ready** — the mobile readiness decision treated a healthy Metro + successful bundle as `ready` without checking the target device, so a dev client that had crashed or was never opened produced `✓ ready` while nothing was running. The decision now probes the device (`xcrun simctl spawn … launchctl list` / `adb shell ps -A`, fail-closed) and returns `launch`/`app-not-running` (relaunch the client) unless the app is actually alive.
+- **Metro log-tail window no longer leaks into an unrelated tmux session** — running `start-metro` outside a tmux client fell back to `tmux display-message` (the last-attached session, e.g. the user's own) and created its `metro-<port>` window — with a `tail -F` — there, outliving the run. The viewer now opens a window only in a session that belongs to this run (a named slot session that exists, or the current session when actually inside tmux) and otherwise skips it; Metro still runs detached to the log. Extracted to `adapters/mobile/lib/tmux-viewer.sh` so the rule is unit-tested; contract tests stub tmux hermetically so no suite run can create a real window.
+
+### Added
+- **`mm-harness stop`** — stop the port-scoped Metro dev server this mobile checkout owns and close its log-tail window (idempotent; extension/core are slot-managed and get a teaching error). Slot-context-aware port resolution.
+- **Slot-context device/port detection** — `resolve-farmslot-ports.sh` reads `agentic-runtime.json` (the mapping the orchestrator's prepare wrote into the checkout) first, so device/port resolution survives pool renames that break any naming formula.
+- **CLI help surface** — grouped/colored `mm-harness` help, a `DEV OVERRIDE ACTIVE` banner when `MM_HARNESS_BIN` is set, and a `SLOT` line when the checkout is a prepared slot; `mmdev-harness` completion alias.
+
+### Changed
+- **Deps install uses a scoped `setup:expo` variant when native isn't wanted** — `adapters/mobile/yarn-setup.sh` gains `--mode full|expo`. `expo` runs `yarn setup:expo --no-build-ios --no-build-android` (JS deps + prebuild, no native — native builds come from `open-device.sh`, never doubled); the full `yarn setup` runs only for a native build (`launch --build`). This is also the standalone Metro-only remedy taught by the fast-tier deps block.
+- **`mm-harness runtime-decision --adapter mobile` accepts `--preflight-mode`** — surfaces the fast (presence, blocks on a genuine gap) vs full (installs) decision for inspection and callers.
+
 ## 0.3.8 - 2026-07-04
 
 ### Fixed
-- **Mobile launch streams progress in  mode** — mobile prepare leaves now run through , which tees the child's stdout+stderr to the parent's stderr live while stdout stays reserved for the JSON envelope. A multi-minute {
-  "schemaVersion": 1,
-  "command": "launch",
-  "status": "fail",
-  "exitCode": 2,
-  "error": {
-    "code": "USAGE",
-    "message": "could not detect the MetaMask repo type for /private/tmp/claude-501/-Users-deeeed-dev-metamask-principal-pitch-2025/4645d206-3e7f-482d-a5c1-2274f26a7411/scratchpad/emh-review",
-    "userAction": "cd into a MetaMask checkout or pass --target <path>, or force it with --adapter <mobile|extension|core>"
-  }
-} is no longer silent (previously  buffered leaf output and suppressed it entirely under ). Contract test asserts leaf progress reaches stderr, the envelope stays clean, and the streaming conversion preserves the exit-code contract.
+- **Mobile launch streams progress in `--json` mode** — mobile prepare leaves now run through `spawnScriptStreaming`, which tees the child's stdout+stderr to the parent's stderr live while stdout stays reserved for the JSON envelope. A multi-minute `mm-harness launch --json` is no longer silent (previously `spawnSync` buffered leaf output and suppressed it entirely under `--json`). Contract test asserts leaf progress reaches stderr, the envelope stays clean, and the streaming conversion preserves the exit-code contract.
 
 ## 0.3.7 - 2026-07-04
 

package/adapters/extension/start-watch.sh

@@ -243,7 +243,14 @@ printf '%s\n' "$started_pid" > "$watch_pid_file"
 tmux_session="${RECIPE_TMUX_SESSION:-}"
 if [ -z "$tmux_session" ]; then
   slot="$(slot_number || true)"
-  [ -z "$slot" ] || tmux_session="mme-$slot"
+  if [ -n "$slot" ] && tmux has-session -t "=mme-$slot" 2>/dev/null; then
+    tmux_session="mme-$slot"
+  fi
+fi
+# Fall back to the session this run is inside: renamed pools and manual runs in
+# any tmux still get their watcher window; outside tmux there is nowhere to put one.
+if [ -z "$tmux_session" ]; then
+  tmux_session="$(tmux display-message -p '#S' 2>/dev/null || true)"
 fi
 if [ -n "$tmux_session" ] && command -v tmux >/dev/null 2>&1 && tmux has-session -t "$tmux_session" 2>/dev/null; then
   tmux_window="webpack-${WATCHER_PORT:-default}"

package/adapters/manifest.json

@@ -18,6 +18,14 @@
       "inputs": "--target --port --clear; env WATCHER_PORT, METRO_PORT, MOBILE_METRO_REQUIRED_ENV, METRO_MAX_WORKERS",
       "outputs": "Metro PID file + log; exit 0 ready / 1 timeout / 2 bad args"
     },
+    {
+      "id": "mobile/stop-metro",
+      "entry": "adapters/mobile/stop-metro.sh",
+      "kind": "bash",
+      "purpose": "Stop the port-scoped Metro bundler this checkout owns and close its log-tail window (idempotent).",
+      "inputs": "--target --port; env WATCHER_PORT",
+      "outputs": "progress on stderr; exit 0 stopped-or-nothing / 1 stop failed / 2 bad args"
+    },
     {
       "id": "mobile/prewarm-bundle",
       "entry": "adapters/mobile/prewarm-bundle.sh",

package/adapters/mobile/lib/tmux-viewer.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# tmux-viewer — open a read-only tmux window tailing the Metro log, but ONLY in a
+# session that belongs to this run. Sourced by start-metro.sh; kept separate so
+# the session-resolution rule (the part that must never leak into a user session)
+# is unit-testable in isolation.
+#
+# Contract: never create a window in "whatever session happens to be attached".
+# Outside a tmux client `tmux display-message -p '#S'` returns the last-attached
+# session (e.g. the user's own), which would land the window — and its `tail -F` —
+# in an unrelated session that outlives the run. When no run-owned session can be
+# resolved, skip the viewer entirely (Metro still runs detached to the log).
+#
+# Inputs (env/args): $1 = metro log path; PORT, LOG_DIR, and optional `slot` from
+# the caller; TMUX indicates we are inside a tmux client.
+
+# shellcheck disable=SC2329  # sourced by start-metro.sh; also sourced by tests.
+start_viewer_window() {
+  local metro_log="$1"
+  command -v tmux >/dev/null 2>&1 || return 0
+  local window="metro-${PORT}"
+  local metro_tmux="$LOG_DIR/metro.tmux"
+  local session=""
+  # (1) the slot session, when one is named and actually exists. The mm-<slot>
+  #     formula predates the mmdev rename; a session named otherwise simply falls
+  #     through — has-session gates it, so a wrong name never creates a window.
+  if [ -n "${slot:-}" ] && tmux has-session -t "=mm-${slot}" 2>/dev/null; then
+    session="mm-${slot}"
+  # (2) the current session, but ONLY when we are actually inside a tmux client.
+  elif [ -n "${TMUX:-}" ]; then
+    session="$(tmux display-message -p '#S' 2>/dev/null || true)"
+  fi
+  # No run-owned session → skip the viewer; no orphaned tail-window is left behind.
+  { [ -n "$session" ] && tmux has-session -t "=$session" 2>/dev/null; } || return 0
+  tmux kill-window -t "${session}:${window}" >/dev/null 2>&1 || true
+  tmux new-window -d -t "$session" -n "$window" "exec tail -n +1 -F $(printf '%q' "$metro_log")"
+  printf '%s:%s\n' "$session" "$window" > "$metro_tmux"
+  printf 'Metro log viewer → tmux %s:%s\n' "$session" "$window" >&2
+}

package/adapters/mobile/start-metro.sh

@@ -72,24 +72,10 @@ default_metro_workers() {
   fi
 }
 
-start_viewer_window() {
-  local metro_log="$1"
-  command -v tmux >/dev/null 2>&1 || return 0
-  local window="metro-${PORT}"
-  local metro_tmux="$LOG_DIR/metro.tmux"
-  local session=""
-  if [ -n "${slot:-}" ] && tmux has-session -t "=mm-${slot}" 2>/dev/null; then
-    session="mm-${slot}"
-  fi
-  if [ -z "$session" ]; then
-    session="$(tmux display-message -p '#S' 2>/dev/null || true)"
-  fi
-  [ -n "$session" ] || return 0
-  tmux kill-window -t "${session}:${window}" >/dev/null 2>&1 || true
-  tmux new-window -d -t "$session" -n "$window" "exec tail -n +1 -F $(printf '%q' "$metro_log")"
-  printf '%s:%s\n' "$session" "$window" > "$metro_tmux"
-  printf 'Metro log viewer → tmux %s:%s\n' "$session" "$window" >&2
-}
+# Log-tail viewer window (session-safe): sourced so its run-owned-session rule is
+# unit-testable and can never leak a window into an unrelated user session.
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/lib/tmux-viewer.sh"
 
 # --- main ---------------------------------------------------------------------
 

package/adapters/mobile/stop-metro.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# stop-metro.sh — stop the Metro dev server this checkout owns and close its
+# log-tail window. Port-scoped like start-metro: only the listener on the
+# resolved port is signalled, so concurrent slots on other ports are untouched.
+# Idempotent: nothing running is a success, not an error.
+set -euo pipefail
+
+TARGET="."
+PORT="${WATCHER_PORT:-}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --port)   PORT="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: stop-metro.sh [--target <dir>] [--port <port>]\n'
+      printf '  --target  MetaMask Mobile checkout directory\n'
+      printf '  --port    Metro port (default: WATCHER_PORT env, else the slot context, else 8081)\n'
+      exit 0
+      ;;
+    *) printf 'stop-metro: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+TARGET="$(cd "$TARGET" && pwd)"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../shared/harness-path.sh"
+if ! command -v recipe_runtime_dir >/dev/null 2>&1; then
+  echo "stop-metro: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+
+# No explicit port: resolve the checkout's own (slot context first, then the
+# pool/formula fallbacks) so we stop THIS slot's Metro, not the 8081 default.
+if [ -z "$PORT" ]; then
+  # shellcheck disable=SC1091
+  . "$SCRIPT_DIR/../shared/resolve-farmslot-ports.sh"
+  resolved_port="$(resolve_mobile_runtime_ports "$TARGET" 2>/dev/null | sed -n 's/^WATCHER_PORT=//p' | head -1 || true)"
+  PORT="${resolved_port:-8081}"
+fi
+
+LOG_DIR="$TARGET/$(recipe_runtime_dir)"
+PID_FILE="$LOG_DIR/metro.pid"
+TMUX_FILE="$LOG_DIR/metro.tmux"
+
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/lib/metro-listener.sh"
+
+pids="$(metro_listener_pids 2>/dev/null || true)"
+if [ -n "$pids" ]; then
+  stop_metro_listener || exit 1
+  printf 'Stopped Metro on port %s (pid %s)\n' "$PORT" "$pids" >&2
+else
+  printf 'Metro not running on port %s — nothing to stop\n' "$PORT" >&2
+fi
+rm -f "$PID_FILE"
+
+# Close the read-only log-tail window start-metro opened, if it is still there.
+if [ -f "$TMUX_FILE" ] && command -v tmux >/dev/null 2>&1; then
+  win="$(cat "$TMUX_FILE" 2>/dev/null || true)"
+  if [ -n "$win" ] && tmux kill-window -t "$win" 2>/dev/null; then
+    printf 'Closed Metro log window %s\n' "$win" >&2
+  fi
+fi
+rm -f "$TMUX_FILE"

package/adapters/mobile/yarn-setup.sh

@@ -2,19 +2,31 @@
 # yarn-setup — install node_modules for MetaMask Mobile.
 #
 # Inputs:  --target <metamask-mobile dir>  (default $PWD)
+#          --mode full|expo                 (default full)
 # Outputs: yarn install output on stderr; exit 0 pass, 1 install failed, 2 bad args.
 #
 # Single device op: install node_modules. No other sequencing.
+#   full — `yarn setup` (JS deps + expo prebuild + native pods/jetify). Use only
+#          when a native build is wanted (launch --build / rebuild-native).
+#   expo — `yarn setup:expo --no-build-ios --no-build-android` (JS deps + prebuild,
+#          no native). The Metro-only remedy: native builds come from open-device.
 set -euo pipefail
 
 TARGET="$PWD"
+MODE="full"
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --target)  TARGET="$2"; shift 2 ;;
-    -h|--help) printf 'Usage: yarn-setup.sh [--target <dir>]\n'; exit 0 ;;
+    --mode)    MODE="$2"; shift 2 ;;
+    -h|--help) printf 'Usage: yarn-setup.sh [--target <dir>] [--mode full|expo]\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
+cd "$TARGET"
+case "$MODE" in
+  full) exec yarn setup ;;
+  expo) exec yarn setup:expo --no-build-ios --no-build-android ;;
+  *) printf 'yarn-setup: unknown --mode: %s (want full|expo)\n' "$MODE" >&2; exit 2 ;;
+esac

package/adapters/shared/resolve-farmslot-ports.sh

@@ -155,8 +155,29 @@ resolve_mobile_slot_defaults() {
   printf 'SLOT_ID=local-mobile-%s\n' "$n"
 }
 
+# Slot context the orchestrator's prepare wrote INTO the checkout — the
+# authoritative device/port mapping for this repo (survives pool renames that
+# break any naming formula). Highest-priority detection source.
+resolve_mobile_runtime_context() {
+  local repo="$1" ctx
+  ctx="$repo/${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}/agentic-runtime.json"
+  [ -f "$ctx" ] || return 1
+  node -e '
+    try {
+      const c = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+      if (!c.simulator && !c.metroPort) process.exit(1);
+      if (c.metroPort) console.log(`WATCHER_PORT=${c.metroPort}`);
+      if (c.simulator) console.log(`IOS_SIMULATOR=${c.simulator}`);
+      if (c.slotId) console.log(`SLOT_ID=${c.slotId}`);
+    } catch { process.exit(1); }
+  ' "$ctx" 2>/dev/null
+}
+
 resolve_mobile_runtime_ports() {
   local repo="${1:-.}"
+  if resolve_mobile_runtime_context "$repo"; then
+    return 0
+  fi
   if resolve_farmslot_ports_by_repo "$repo"; then
     return 0
   fi

package/docs/UX-PRINCIPLES.md

@@ -0,0 +1,61 @@
+# UX principles — the mm-harness interaction contract
+
+Every command surface follows these rules. They are review criteria, not aspirations:
+a PR that adds a command or output path is checked against each one.
+
+**Scope: the HUMAN surface.** The agent contract is exempt and inviolable: under
+`--json`, stdout carries exactly one machine-readable envelope — no color, no
+banners, no decorative lines, schema per CLI-SPEC.md. Progress/streaming exists
+for agents too, but only ever on stderr. When a rule below conflicts with envelope
+purity, the envelope wins.
+
+## 1. Context-aware by default
+The CLI answers relative to the checkout it is standing in.
+- Adapter is auto-detected everywhere (`--adapter` overrides; a bare command never
+  fails on a value detection can supply).
+- The slot context the orchestrator wrote into the checkout
+  (`<runtime_dir>/agentic-runtime.json`) is the authoritative source for device,
+  ports, and slot identity — naming formulas are last-resort fallbacks and never
+  hardcode pool prefixes (they go stale on rename).
+- Output is scoped to the platform: an extension-only field is noise on a mobile
+  slot; help, flag lists, and completion candidates shrink to what applies here.
+
+## 2. Never silent, never opaque
+Long operations show intent immediately and progress continuously.
+- First line within milliseconds: what is being done, where (device/port), and
+  where the full log lives.
+- Leaf output streams live to stderr — `--json` reserves stdout for the envelope,
+  it never buys silence. Quiet stretches get heartbeats with elapsed time.
+- Each dev server a command starts gets its tmux log-tail window at launch time
+  (window creation is launch-coupled; users re-create separately when they close one).
+
+## 3. Summaries state outcomes
+The final line says what actually happened: target device, what the tier meant,
+resulting state — never a bare status word. Dev-override runs are marked
+(`[dev: MM_HARNESS_BIN]`) so it is always evident which bin served.
+
+## 4. Dev and prod are explicit
+The global install is prod (`mm-harness`); a dev checkout runs via the documented
+`MM_HARNESS_BIN` switch (conventionally aliased `mmdev-harness`). The dev override
+announces itself in help and summaries. Completions cover both names.
+
+## 5. Errors teach the exact escape
+Every failure states the next command for the caller's actual situation. A wrong
+hint (an escape for a different failure mode) is a bug of the same severity as
+the failure itself.
+
+## 6. Lifecycle verbs are symmetric and idempotent
+What a command starts, a sibling verb stops (`launch`/`stop`), scoped to what this
+checkout owns (port-scoped, session-scoped) — never "whatever is running".
+Nothing-to-do is success. Tests never leak into the operator's real tmux.
+
+## 7. Color is consistent and optional
+All human output styles through `cli-color.ts` (headers, ok/warn/err states,
+provenance, "Next:" hints); `NO_COLOR`/non-TTY degrade to plain text. No surface
+invents its own ANSI.
+
+## 8. Doctor is the status surface
+`doctor` reports, per platform: live runtime state (deps currency, dev-server
+up/stale on the slot's resolved port, app/browser presence), the scoped runtime
+context with provenance (`[file]`/`[env]`/`[default]`), and the exact customize
+hint per row. Read-only unless `--fix`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -17,8 +17,13 @@
     "@farmslot/protocol": "^0.7.2",
     "@farmslot/recipe-harness": "^0.3.3",
     "commander": "^12.0.0",
-    "tsx": "^4.19.0",
-    "viem": "^2.52.2"
+    "tsx": "^4.23.0",
+    "viem": "^2.54.3"
+  },
+  "resolutions": {
+    "esbuild": "0.28.1",
+    "undici": "6.27.0",
+    "ws": "8.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/scripts/completions.sh

@@ -29,12 +29,13 @@ _mmh_bin() {
   return 1
 }
 
-_mmh_commands="launch logs debug fixtures actions call flows run doctor install verify cleanup completions"
+_mmh_commands="launch stop logs debug fixtures actions call flows run doctor install verify cleanup completions"
 
 # Per-command flags (static, from the mm-harness surface).
 _mmh_flags_for() {
   case "$1" in
     launch)   printf '%s' "--build --watch --verify --sidepanel --fullscreen --runway --device --cdp-port --watcher-port --heal --adapter --target --json" ;;
+    stop)     printf '%s' "--port --target --json" ;;
     logs)     printf '%s' "--full --events --source --adapter --target --json" ;;
     debug)    printf '%s' "--worker --dev-menu --adapter --target --json" ;;
     fixtures) printf '%s' "--fixture --adapter --target --json" ;;
@@ -83,7 +84,9 @@ if [ -n "${BASH_VERSION:-}" ]; then
       *)           COMPREPLY=($(compgen -W "$(_mmh_flags_for "$cmd")" -- "$cur")) ;;
     esac
   }
+  # mmdev-harness is the documented dev-checkout alias; complete it identically.
   complete -F _mmh_complete_bash mm-harness 2>/dev/null || true
+  complete -F _mmh_complete_bash mmdev-harness 2>/dev/null || true
 fi
 
 # ── Zsh ─────────────────────────────────────────────────────────────────
@@ -117,9 +120,9 @@ if [ -n "${ZSH_VERSION:-}" ]; then
   }
 
   if (( $+functions[compdef] )); then
-    compdef _mmh_complete_zsh mm-harness
+    compdef _mmh_complete_zsh mm-harness mmdev-harness
   else
     autoload -Uz compinit 2>/dev/null && compinit -u 2>/dev/null
-    (( $+functions[compdef] )) && compdef _mmh_complete_zsh mm-harness
+    (( $+functions[compdef] )) && compdef _mmh_complete_zsh mm-harness mmdev-harness
   fi
 fi

package/src/adapters/mobile/prepare.ts

@@ -7,6 +7,8 @@
 
 import path from 'node:path';
 
+import { recordDepsBaseline } from '@farmslot/recipe-harness/runtime/deps-readiness';
+
 import { EXIT, spawnScriptStreaming } from '../../commands/shared.ts';
 import type { ScriptResult } from '../../commands/shared.ts';
 import { runnerDir } from '../../paths.ts';
@@ -24,7 +26,16 @@ export { type MobileRuntimeDecisionReport };
 // An inherited FORCE_COLOR makes node emit a colorized `undefined`, so VisionCamera
 // misdetects the worklets pod, enables FrameProcessors, and fails on the missing
 // pod. Force plain output for pod-triggering spawns so the probe reads `undefined`.
-const POD_PROBE_ENV: Record<string, string> = { FORCE_COLOR: '0', NO_COLOR: '1' };
+// CocoaPods reads UTF-8 podspecs; a parent env without a locale (gateway/tmux
+// spawns) makes Ruby parse them as US-ASCII and die on the first multibyte byte
+// ('"\xE2" on US-ASCII' in react-native-mmkv.podspec). Pin a UTF-8 locale for
+// pod-triggering spawns when the caller has none.
+const POD_PROBE_ENV: Record<string, string> = {
+  FORCE_COLOR: '0',
+  NO_COLOR: '1',
+  LANG: process.env.LANG?.includes('UTF-8') ? process.env.LANG : 'en_US.UTF-8',
+  LC_ALL: process.env.LC_ALL?.includes('UTF-8') ? process.env.LC_ALL : 'en_US.UTF-8',
+};
 
 export interface PrepareMobileOptions extends MobileRuntimeDecisionOptions {
   /**
@@ -59,6 +70,7 @@ export async function mobileRuntimeStatus(
     metroLog: opts.metroLog,
     platform: opts.platform,
     record: opts.record,
+    preflightMode: opts.preflightMode,
   });
 }
 
@@ -81,11 +93,13 @@ export async function prepareMobile(
     metroLog: opts.metroLog,
     platform,
     record: opts.record,
+    preflightMode,
   });
 
   if (report.decision === 'blocked') {
     const reasons = report.reasons.join(' ');
-    const msg = `mobile prepare blocked: ${reasons}\n  Next: fix the bundle error in app code before retrying recipe up.`;
+    const next = report.userAction ?? 'fix the bundle error in app code before retrying recipe up.';
+    const msg = `mobile prepare blocked: ${reasons}\n  Next: ${next}`;
     if (!json) process.stderr.write(`${msg}\n`);
     return { status: EXIT.runtime, output: msg };
   }
@@ -112,6 +126,11 @@ export async function prepareMobile(
   for (const action of actions) {
     const result = await dispatchAction(action, target, platform, json, preflightMode);
     if (result.status !== 0) return result;
+    // Record the deps baseline the instant a setup/install leaf succeeds, so the
+    // mtime freshness fallback stops firing forever after one good install. This
+    // is unconditional (not gated on a later re-decide or an env flag), so the
+    // baseline lifecycle is self-sustaining regardless of the caller's path.
+    if (action.id === 'yarn-setup') recordDepsBaseline(path.resolve(target));
   }
 
   // After install: re-decide and run appropriate actions.
@@ -122,7 +141,7 @@ export async function prepareMobile(
       watcherPort: opts.watcherPort,
       metroLog: opts.metroLog,
       platform,
-      record: true,
+      preflightMode,
     });
     switch (postInstall.decision) {
       case 'install': {

package/src/adapters/mobile/runtime-decision.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -43,6 +44,9 @@ export interface MobileRuntimeDecisionReport {
   decision: MobileReadinessDecision;
   reasonCode: string;
   reasons: string[];
+  // A single teaching escape for the caller's actual situation, set on decisions
+  // the runner deliberately refuses to auto-resolve (e.g. fast-mode deps gaps).
+  userAction?: string;
   checks: {
     deps: DepsCheck;
     metroLog: MetroLogCheck;
@@ -56,6 +60,9 @@ export interface MobileRuntimeDecisionOptions {
   metroLog?: string;
   platform?: string;
   record?: boolean;
+  // 'fast' (quick launch / no --build) makes deps readiness a presence check only:
+  // freshness is the orchestrator's deps-phase contract, never re-decided here.
+  preflightMode?: string;
 }
 
 const BUNDLE_ERR = /Bundling failed|Unable to resolve /u;
@@ -128,38 +135,38 @@ function missingRequiredDeps(target: string): string[] {
   }
 }
 
-// Returns true when any manifest input (package.json or yarn.lock) is newer than
-// the install markers written by yarn on a successful install. A reliable signal
-// that deps changed since the last install, even when depsCheck found no recorded
-// baseline drift (e.g. git checkout preserved an old author-date mtime on the
-// manifest, then a new dep was committed, making the manifest newer than markers).
-function depsStaleByMtime(target: string): boolean {
-  // Use the same install markers as depsCheck: the files yarn writes on install.
-  const INSTALL_MARKERS = ['node_modules/.yarn-state.yml', '.yarn/install-state.gz'];
-  let markerMtime = 0;
-  for (const rel of INSTALL_MARKERS) {
-    try {
-      const mt = fs.statSync(path.join(target, rel)).mtimeMs;
-      if (mt > markerMtime) markerMtime = mt;
-    } catch {
-      // marker absent; keep searching
-    }
-  }
-  if (markerMtime === 0) return false; // no markers → depsCheck already handles via 'missing'
-  for (const file of ['package.json', 'yarn.lock']) {
-    try {
-      if (fs.statSync(path.join(target, file)).mtimeMs > markerMtime) return true;
-    } catch {
-      // manifest absent; skip
-    }
-  }
-  return false;
-}
-
 const installActions = (target: string): MobileRuntimeDecisionAction[] => [
   { id: 'yarn-setup', argv: ['yarn', 'setup'], cwd: target },
 ];
 
+// True when a MetaMask dev client process is alive on the target device
+// (IOS_SIMULATOR / ADB_SERIAL, falling back to the booted simulator). Probe
+// failures count as not-running: the worst case is an idempotent relaunch,
+// while failing open would declare a dead app "ready".
+function appRunningOnDevice(platform?: string): boolean {
+  try {
+    if (platform === 'android') {
+      const serial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL;
+      const args = serial ? ['-s', serial] : [];
+      const out = execFileSync('adb', [...args, 'shell', 'ps', '-A'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 5_000,
+      });
+      return out.includes('io.metamask');
+    }
+    const device = process.env.IOS_SIMULATOR || 'booted';
+    const out = execFileSync('xcrun', ['simctl', 'spawn', device, 'launchctl', 'list'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5_000,
+    });
+    return out.toLowerCase().includes('io.metamask');
+  } catch {
+    return false;
+  }
+}
+
 const launchActions = (target: string, clearMetro = false): MobileRuntimeDecisionAction[] => {
   const actions: MobileRuntimeDecisionAction[] = [];
   // start-metro ensures Metro is running; --clear resets the bundle cache.
@@ -184,22 +191,60 @@ export async function decideMobileReadiness(
   const resolved = path.resolve(target);
   if (options.record) recordDepsBaseline(resolved);
 
+  const fast = options.preflightMode === 'fast';
+  const report = await computeMobileReadiness(resolved, options, fast);
+
+  // mtime churn is already neutralized above, so a fast-mode 'install' verdict
+  // means deps genuinely need work (absent markers, an absent required package, a
+  // fingerprint-baseline drift, or Metro unable to resolve a module). In an
+  // orchestrated run the deps phase owns installation; having the runner install
+  // mid-launch is inverted authority. Surface a teaching block, not an implicit
+  // setup, so a runway preflight never re-does the orchestrator's deps work.
+  if (fast && report.decision === 'install') {
+    return {
+      ...report,
+      decision: 'blocked',
+      reasonCode: 'deps-not-ready',
+      reasons: [
+        'Fast preflight found dependencies not ready and does not install them (the orchestrator deps phase owns installation).',
+        ...report.reasons,
+      ],
+      userAction:
+        'run the slot deps/prepare phase; standalone: `yarn setup:expo --no-build-ios --no-build-android` in the checkout, or `mm-harness launch <platform> --build` to install and build',
+      actions: [],
+    };
+  }
+  return report;
+}
+
+async function computeMobileReadiness(
+  resolved: string,
+  options: MobileRuntimeDecisionOptions,
+  fast: boolean,
+): Promise<MobileRuntimeDecisionReport> {
   const rawDeps = depsCheck(resolved, {
     productMarkers: mobileProductMarkers(options.platform),
   });
-  // Mtime-based fallback: when depsCheck found no recorded baseline, supplement
-  // with a direct mtime comparison — if package.json or yarn.lock is newer than
-  // node_modules, a dep change landed after the last install. Fail fast at
-  // pre-flight rather than launching a doomed Metro bundle. Skip when a baseline
-  // was found (hasBaseline=true) so fingerprint-verified 'current' is trusted.
-  let deps: DepsCheck =
-    rawDeps.status === 'current' && !rawDeps.hasBaseline && depsStaleByMtime(resolved)
-      ? { installed: rawDeps.installed, status: 'stale', hasBaseline: rawDeps.hasBaseline }
-      : rawDeps;
-  // Required-dep absence: even when fingerprint + mtime reports 'current', a
-  // top-level dependency could be absent from node_modules (e.g. added in a
-  // branch merge but install not re-run). Catch at pre-flight before Metro
-  // discovers it during a 249s bundle run.
+  // Presence is authoritative; mtime is only a hint. Without a recorded baseline
+  // the only way depsCheck reports 'stale' is mtime drift (a manifest newer than
+  // the install markers). In a managed checkout the orchestrator's git phase
+  // refreshes tracked-file mtimes on every sync while its deps phase leaves
+  // node_modules untouched, so "manifest newer than markers" is normal and NOT
+  // proof of drift — treating it as stale re-ran the full yarn setup inside every
+  // launch. Trust the installed node_modules and warn; genuine drift is caught by
+  // the recorded-baseline fingerprint when one exists (hasBaseline=true stays 'stale').
+  let deps: DepsCheck = rawDeps;
+  if (rawDeps.status === 'stale' && !rawDeps.hasBaseline) {
+    deps = { installed: rawDeps.installed, status: 'current', hasBaseline: false };
+    process.stderr.write(
+      '[runtime-decision] manifest is newer than install markers (no recorded baseline); ' +
+        'trusting installed node_modules — run yarn setup manually if deps truly changed.\n',
+    );
+  }
+  // Required-dep absence is a presence check (both modes): a top-level dependency
+  // can be absent from node_modules even when markers + fingerprint report
+  // 'current' (e.g. added in a branch merge but install not re-run). Catch at
+  // pre-flight before Metro discovers it during a long bundle run.
   if (deps.status === 'current') {
     const absent = missingRequiredDeps(resolved);
     if (absent.length > 0) {
@@ -373,13 +418,29 @@ export async function decideMobileReadiness(
   }
 
   if (metro.status === 'up' && metroLog.status === 'ok') {
+    // Metro health alone is not runtime readiness: the dev client may be
+    // installed but not running on the target device (launch must launch).
+    // Probe the device before declaring ready; a healthy Metro with a dead
+    // app relaunches the client without touching Metro.
+    if (!appRunningOnDevice(options.platform)) {
+      return {
+        schemaVersion: 1,
+        adapter: 'mobile',
+        target: resolved,
+        decision: 'launch',
+        reasonCode: 'app-not-running',
+        reasons: ['Metro is healthy but the dev client is not running on the target device; launching it.'],
+        checks,
+        actions: launchActions(resolved),
+      };
+    }
     return {
       schemaVersion: 1,
       adapter: 'mobile',
       target: resolved,
       decision: 'ready',
       reasonCode: 'healthy',
-      reasons: ['Dependencies are current and Metro reports a successful bundle. Verify bridge before replay.'],
+      reasons: ['Dependencies are current, Metro reports a successful bundle, and the dev client is running. Verify bridge before replay.'],
       checks,
       actions: [],
     };

package/src/cli.ts

@@ -4,6 +4,7 @@ import { mkdtemp } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
+import { color } from './cli-color.ts';
 import { createDoctorReport, renderRuntimeContext } from './doctor.ts';
 import {
   invalidateCompletionCache,
@@ -420,7 +421,7 @@ async function runSelfTest(options: CliOptions) {
 }
 
 async function handleManifest({ options }: ParsedArgs): Promise<number> {
-  const adapter = adapterOption(options);
+  const { adapter } = resolveAdapter(options);
   const actionManifestPath = actionManifestPathOption(options, adapter);
   const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
   await validateManifest(manifest);
@@ -430,7 +431,7 @@ async function handleManifest({ options }: ParsedArgs): Promise<number> {
 }
 
 async function handleActions({ options }: ParsedArgs): Promise<number> {
-  const adapter = adapterOption(options);
+  const { adapter } = resolveAdapter(options);
   const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
   await validateManifest(manifest);
   const action = optionString(options, 'action');
@@ -475,9 +476,38 @@ async function handleDoctor({ options }: ParsedArgs): Promise<number> {
   }
 
   const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-  if (json) console.log(JSON.stringify(result, null, 2));
+  // Live runtime state, per platform: mobile reports the same read-only readiness
+  // the launch decision uses (deps currency, Metro on the slot's port, decision +
+  // reasons). Extension/core gain their sections when their readiness probes exist.
+  let runtime: { decision: string; reasonCode?: string; reasons: string[]; deps?: string; metro?: string } | undefined;
+  if (adapter === 'mobile') {
+    try {
+      const { mobileRuntimeStatus } = await import('./adapters/mobile/prepare.ts');
+      const { resolveMobileSlotPorts } = await import('./commands/launch.ts');
+      resolveMobileSlotPorts(target);
+      const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : undefined;
+      const report = await mobileRuntimeStatus(target, { watcherPort });
+      runtime = {
+        decision: report.decision,
+        reasonCode: report.reasonCode,
+        reasons: report.reasons,
+        deps: report.checks?.deps?.status,
+        metro: report.checks?.metro?.status,
+      };
+    } catch { /* readiness probe unavailable — doctor stays useful without it */ }
+  }
+  if (json) console.log(JSON.stringify({ ...result, runtime }, null, 2));
   else {
-    console.log(`${result.status} ${adapter} ${result.compatibilityMode} manifest=${actionManifestPath}`);
+    const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
+    const stateStyle = (value: string | undefined, good: string) => (value === good ? 'ok' : 'warn');
+    console.log(`${out(result.status === 'pass' ? 'ok' : 'err', result.status)} ${out('bold', adapter)} ${result.compatibilityMode} ${out('dim', `manifest=${actionManifestPath}`)}`);
+    if (runtime) {
+      const decisionStyle = runtime.decision === 'ready' ? 'ok' : runtime.decision === 'blocked' ? 'err' : 'warn';
+      console.log(
+        `${out('label', 'runtime:')} decision=${out(decisionStyle, runtime.decision)}${runtime.reasonCode ? ` ${out('dim', `(${runtime.reasonCode})`)}` : ''} deps=${out(stateStyle(runtime.deps, 'current'), runtime.deps ?? 'unknown')} metro=${out(stateStyle(runtime.metro, 'up'), runtime.metro ?? 'unprobed')}`,
+      );
+      for (const reason of runtime.reasons) console.log(`  ${out('dim', reason)}`);
+    }
     console.log(renderRuntimeContext(result.runtimeContext));
   }
   return result.status === 'pass' ? 0 : 1;
@@ -758,6 +788,7 @@ async function handleRuntimeDecision({ options }: ParsedArgs): Promise<number> {
       metroLog: optionString(options, 'metroLog'),
       platform: optionString(options, 'platform') ?? process.env.PLATFORM ?? process.env.RECIPE_HARNESS_PLATFORM,
       record: optionFlag(options, 'record'),
+      preflightMode: optionString(options, 'preflightMode'),
     });
     if (optionFlag(options, 'json')) console.log(JSON.stringify(report, null, 2));
     else console.log(`${report.decision} ${report.reasonCode} — ${report.reasons[0] ?? ''}`);
@@ -1082,6 +1113,47 @@ function emitPlanUsageError(
 // hand it to runRecipe). One execution path, two doors: `call` = one node, `run` =
 // a graph. Inherits run semantics: always-validates (adapter-aware, exit 5), same
 // trace/evidence artifacts, same --json contract.
+async function handleStop(argv: string[]): Promise<number> {
+  const { options } = parseArgs(argv, 'stop');
+  const json = optionFlag(options, 'json');
+  const { adapter, target } = resolveAdapter(options);
+  if (adapter !== 'mobile') {
+    return usageOut(
+      json,
+      'stop',
+      `stop owns the mobile Metro dev server; the ${adapter} dev server is slot-managed`,
+      'stop the extension watcher via its runtime pids: kill $(cat <runtime_dir>/webpack.pid); core runs no dev server',
+    );
+  }
+  const leaf = path.join(runnerDir, 'adapters', 'mobile', 'stop-metro.sh');
+  const args = ['--target', target];
+  const port = optionString(options, 'port') ?? optionString(options, 'watcherPort');
+  if (port) args.push('--port', port);
+  const result = spawnSync('bash', [leaf, ...args], {
+    stdio: json ? 'pipe' : 'inherit',
+    encoding: 'utf8',
+  });
+  const exitCode = result.status ?? 1;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: 'stop',
+          adapter,
+          target,
+          status: exitCode === 0 ? 'pass' : 'fail',
+          exitCode,
+          output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim(),
+        },
+        null,
+        2,
+      ),
+    );
+  }
+  return exitCode;
+}
+
 async function handleCall(argv: string[]): Promise<number> {
   // Grammar: mm-harness call <action> [--arg k=v ...] [flags].
   // If the first token is a flag, the action positional is missing — parseCallArgs
@@ -1803,6 +1875,7 @@ export async function main(argv: string[]): Promise<number> {
   // launch/logs/debug/fixtures compose adapter scripts directly and own policy,
   // healing, teaching, and the --json contract.
   if (command === 'launch') return handleLaunch(argv.slice(1));
+  if (command === 'stop') return handleStop(argv.slice(1));
   if (command === 'logs') return handleLogs(argv.slice(1));
   if (command === 'debug') return handleDebug(argv.slice(1));
   if (command === 'fixtures') return handleFixtures(argv.slice(1), { runOneNode });

package/src/commands/launch.ts

@@ -8,7 +8,8 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { handleHarness } from '../harness.ts';
+import { color } from '../cli-color.ts';
+import { handleHarness, readRuntimeContextField, resolveRuntimeContextPath } from '../harness.ts';
 import { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, runnerDir } from '../paths.ts';
 import type { MetaMaskRecipeAdapter } from '../types.ts';
 import { prepareMobile } from '../adapters/mobile/prepare.ts';
@@ -19,6 +20,7 @@ import {
   parseFlags,
   resolveAdapter,
   spawnScript,
+  spawnScriptStreaming,
   str,
   targetOf,
   usageOut,
@@ -227,15 +229,33 @@ function applyKVLines(output: string, overwrite: boolean): void {
       case 'SLOT_ID':
         if (overwrite || !process.env['RECIPE_SLOT_ID']) process.env['RECIPE_SLOT_ID'] = val;
         break;
+      case 'CDP_PORT':
+        if (overwrite || !process.env['CDP_PORT']) {
+          process.env['CDP_PORT'] = val;
+          process.env['RECIPE_CDP_PORT'] = val;
+        }
+        break;
     }
   }
 }
 
-// Resolve mobile slot port/simulator from the farmslot pool (pool-wins-over-env)
-// or from the slot-suffix formula (only fills unset vars). Called before explicit
+// Resolve mobile slot port/simulator: the slot context the orchestrator wrote
+// into the checkout wins first, then the farmslot pool (both overwrite env),
+// then the slot-suffix formula (only fills unset vars). Called before explicit
 // CLI flag overrides so flags always win at the top.
-function resolveMobileSlotPorts(target: string): void {
+export function resolveMobileSlotPorts(target: string): void {
   const resolveScript = path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh');
+  try {
+    // The checkout's own runtime context is authoritative — it names the exact
+    // simulator/port this slot was prepared with, surviving pool renames.
+    const ctxOut = execFileSync('bash', [
+      '-c', `source "${resolveScript}" && resolve_mobile_runtime_context "${target}"`,
+    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    if (ctxOut.trim()) {
+      applyKVLines(ctxOut, true);
+      return;
+    }
+  } catch { /* no runtime context — fall through to pool */ }
   try {
     // Pool match always wins — overwrite whatever is in the environment.
     const poolOut = execFileSync('bash', [
@@ -255,6 +275,43 @@ function resolveMobileSlotPorts(target: string): void {
   } catch { /* no slot suffix in dir name — stays at env defaults */ }
 }
 
+// Resolve extension slot ports the same way as mobile: the checkout's runtime
+// context first (cdpPort/devServerPort written by the orchestrator's prepare),
+// then the farmslot pool, then the directory-suffix formula (fills unset only).
+function resolveExtensionSlotPorts(target: string): void {
+  // The prepared checkout's context OVERWRITES inherited env (same authority as
+  // mobile's context/pool resolution): a stale CDP_PORT from the shell must not
+  // hijack the slot's browser. Explicit CLI flags are applied after and win.
+  const contextPath = resolveRuntimeContextPath(target);
+  const cdp = readRuntimeContextField(contextPath, 'cdpPort');
+  if (cdp) {
+    process.env['CDP_PORT'] = cdp;
+    process.env['RECIPE_CDP_PORT'] = cdp;
+  }
+  const dev = readRuntimeContextField(contextPath, 'devServerPort');
+  if (dev) {
+    process.env['WATCHER_PORT'] = dev;
+    process.env['RECIPE_WATCHER_PORT'] = dev;
+  }
+  if (process.env['CDP_PORT']) return;
+  const resolveScript = path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh');
+  try {
+    const poolOut = execFileSync('bash', [
+      '-c', `source "${resolveScript}" && resolve_farmslot_ports_by_repo "${target}"`,
+    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    if (poolOut.trim()) {
+      applyKVLines(poolOut, true);
+      return;
+    }
+  } catch { /* no pool match — fall through to formula */ }
+  try {
+    const defOut = execFileSync('bash', [
+      '-c', `source "${resolveScript}" && resolve_default_extension_ports "${target}"`,
+    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    if (defOut.trim()) applyKVLines(defOut, false);
+  } catch { /* no slot suffix in dir name — stays at env defaults */ }
+}
+
 // Map the env-gap flags onto the env vars the leaf scripts read. For mobile, slot
 // port/simulator defaults are resolved first (pool-wins, then formula-fills-empty)
 // so that the harness respects slot isolation; explicit CLI flags applied below
@@ -265,9 +322,12 @@ function applyLaunchEnvOverrides(
   mobileTarget: string | undefined,
   target: string,
 ): void {
-  // Mobile slot isolation: resolve WATCHER_PORT / IOS_SIMULATOR / SLOT_ID from
-  // the farmslot pool or directory-suffix formula BEFORE applying explicit flags.
+  // Slot isolation: resolve ports/device from the checkout's own slot context,
+  // the farmslot pool, or the directory-suffix formula BEFORE applying explicit
+  // flags — extension needs this as much as mobile (CDP_PORT), so neither
+  // adapter hard-fails on a value its slot already knows.
   if (adapter === 'mobile') resolveMobileSlotPorts(target);
+  if (adapter === 'extension') resolveExtensionSlotPorts(target);
 
   const device = str(options, 'device');
   if (device && adapter === 'mobile') {
@@ -346,17 +406,19 @@ async function executeComposition(
     return extensionRebuild(target, json);
   }
 
-  // Extension build or watch: full webpack compile via start-watch.sh.
+  // Extension build or watch: full webpack compile via start-watch.sh. Streams
+  // live — a webpack compile is minutes long and must never look hung.
   const startWatchSh = path.join(runnerDir, 'adapters/extension/start-watch.sh');
   const watchArgs = ['--target', target];
   if (process.env.WATCHER_PORT) watchArgs.push('--watcher-port', process.env.WATCHER_PORT);
-  return spawnScript(startWatchSh, watchArgs, target, json);
+  console.error(`→ extension ${wantWatch ? 'watch' : 'build'} — webpack :${process.env.WATCHER_PORT ?? 'default'} (output streams below)`);
+  return spawnScriptStreaming(startWatchSh, watchArgs, target);
 }
 
 // Extension rebuild: kill the harness-owned webpack watcher (pid file + ps-scan
 // for orphans), clear the rebuild log, then drive the installed overlay's
 // live.sh --start-watch and tee its output into the rebuild log.
-function extensionRebuild(target: string, json: boolean): ScriptResult {
+async function extensionRebuild(target: string, json: boolean): Promise<ScriptResult> {
   const runtimeDirRel = recipeRuntimeDir();
   const runtimeAbs = path.join(target, runtimeDirRel);
   const webpackPidFile = path.join(runtimeAbs, 'recipe-harness-webpack.pid');
@@ -418,7 +480,10 @@ function extensionRebuild(target: string, json: boolean): ScriptResult {
   const liveArgs = ['--target', target, '--start-watch'];
   if (process.env.CDP_PORT) liveArgs.push('--cdp-port', process.env.CDP_PORT);
   if (process.env.WATCHER_PORT) liveArgs.push('--watcher-port', process.env.WATCHER_PORT);
-  const result = spawnScript(liveScript, liveArgs, target, json);
+  // Streams live: the watcher restart + Chromium boot runs for minutes and the
+  // command must show progress immediately, not a silent prompt.
+  console.error(`→ extension quick relaunch — webpack :${process.env.WATCHER_PORT ?? 'default'} · CDP :${process.env.CDP_PORT ?? 'default'} (output streams below)`);
+  const result = await spawnScriptStreaming(liveScript, liveArgs, target);
   // Tee live.sh output into rebuild.log for post-mortem diagnosis.
   if (result.output) {
     try { fs.appendFileSync(rebuildLog, result.output); } catch { /* best-effort */ }
@@ -489,7 +554,18 @@ function launchPass(
       ),
     );
   } else {
-    console.error(`✓ launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ''} (${tier}) ready`);
+    // The summary must say what actually happened where: the target device,
+    // what the tier meant, and that the app+bridge are up — "(quick) ready"
+    // alone reads as a no-op even when a launch occurred.
+    const device =
+      adapter === 'mobile'
+        ? process.env.IOS_SIMULATOR || process.env.ADB_SERIAL || 'booted device'
+        : displayMode;
+    const tierNote = tier === 'quick' ? 'quick relaunch, no native build' : tier;
+    const devNote = process.env.MM_HARNESS_BIN ? ` ${color('dim', '[dev: MM_HARNESS_BIN]')}` : '';
+    console.error(
+      `${color('ok', '✓')} launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ''} — ${color('ok', String(device))} · ${tierNote} · app + bridge ready${devNote}`,
+    );
   }
   return EXIT.ok;
 }

package/src/doctor.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { color } from './cli-color.ts';
 import { readRuntimeContextField, resolveRuntimeContextPath } from './harness.ts';
 import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from './paths.ts';
 import type {
@@ -100,26 +101,32 @@ const RUNTIME_CONTEXT_FIELDS: ReadonlyArray<{
   envVars: readonly string[];
   envVar: string | null;
   customize: string;
+  adapters: readonly MetaMaskRecipeAdapter[];
 }> = [
-  { key: 'slotId', envVars: ['RECIPE_SLOT_ID'], envVar: 'RECIPE_SLOT_ID', customize: 'farmslot dispatch writes this' },
-  { key: 'extensionId', envVars: ['RECIPE_HARNESS_EXTENSION_ID'], envVar: 'RECIPE_HARNESS_EXTENSION_ID', customize: 'auto-resolved; edit file to pin' },
-  { key: 'cdpPort', envVars: ['RECIPE_CDP_PORT', 'CDP_PORT'], envVar: 'CDP_PORT', customize: 'edit file or pass --cdp-port' },
-  { key: 'runtimeStart.approved', envVars: ['RECIPE_RUNTIME_START_APPROVED'], envVar: 'RECIPE_RUNTIME_START_APPROVED', customize: 'edit file (true/false)' },
-  { key: 'runtimeStart.command', envVars: [], envVar: null, customize: 'edit file' },
-  { key: 'runtimeStart.readyUrl', envVars: ['RECIPE_RUNTIME_READY_URL'], envVar: 'RECIPE_RUNTIME_READY_URL', customize: 'edit file' },
+  { key: 'slotId', envVars: ['RECIPE_SLOT_ID'], envVar: 'RECIPE_SLOT_ID', customize: 'farmslot dispatch writes this', adapters: ['mobile', 'extension', 'core'] },
+  { key: 'extensionId', envVars: ['RECIPE_HARNESS_EXTENSION_ID'], envVar: 'RECIPE_HARNESS_EXTENSION_ID', customize: 'auto-resolved; edit file to pin', adapters: ['extension'] },
+  { key: 'cdpPort', envVars: ['RECIPE_CDP_PORT', 'CDP_PORT'], envVar: 'CDP_PORT', customize: 'edit file or pass --cdp-port', adapters: ['extension'] },
+  { key: 'runtimeStart.approved', envVars: ['RECIPE_RUNTIME_START_APPROVED'], envVar: 'RECIPE_RUNTIME_START_APPROVED', customize: 'edit file (true/false)', adapters: ['mobile', 'extension'] },
+  { key: 'runtimeStart.command', envVars: [], envVar: null, customize: 'edit file', adapters: ['mobile', 'extension'] },
+  { key: 'runtimeStart.readyUrl', envVars: ['RECIPE_RUNTIME_READY_URL'], envVar: 'RECIPE_RUNTIME_READY_URL', customize: 'edit file', adapters: ['mobile', 'extension'] },
 ];
 
 // Report every runtime-context field with its current value and where it came from
 // (live env override > file > unset default), reusing the harness's own file reader
 // so doctor and dispatch agree on resolution. Absent file → fileExists:false and
 // every field falls back to env or default; the path shows where it WOULD live.
-export function runtimeContextSummary(target: string): MetaMaskRuntimeContextReport {
+// An adapter scopes the report to that platform's fields — an extension-only row
+// (cdpPort, extensionId) is noise on a mobile or core slot.
+export function runtimeContextSummary(target: string, adapter?: MetaMaskRecipeAdapter): MetaMaskRuntimeContextReport {
   const contextPath = resolveRuntimeContextPath(target);
   const envOverride = process.env.RECIPE_RUNTIME_CONTEXT ?? null;
   const fileExists = fs.existsSync(contextPath);
   const file = envOverride ?? path.relative(target, contextPath);
   const fields: Record<string, MetaMaskRuntimeContextField> = {};
-  for (const spec of RUNTIME_CONTEXT_FIELDS) {
+  const specs = adapter
+    ? RUNTIME_CONTEXT_FIELDS.filter((spec) => spec.adapters.includes(adapter))
+    : RUNTIME_CONTEXT_FIELDS;
+  for (const spec of specs) {
     const envValue = spec.envVars
       .map((name) => process.env[name])
       .find((value) => value !== undefined && value !== '');
@@ -137,16 +144,21 @@ export function runtimeContextSummary(target: string): MetaMaskRuntimeContextRep
 
 // Human-readable runtime-context section for `doctor` without --json.
 export function renderRuntimeContext(runtimeContext: MetaMaskRuntimeContextReport): string {
+  // Human render: set values read bright with their provenance highlighted;
+  // unset defaults read dim so the eye lands on what is actually configured.
+  const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
   const lines: string[] = [];
   lines.push(
     runtimeContext.fileExists
-      ? `runtime-context: ${runtimeContext.file} (present)`
-      : `runtime-context: ${runtimeContext.file} (absent — written by farmslot prepare/dispatch)`,
+      ? `${out('label', 'runtime-context:')} ${runtimeContext.file} ${out('ok', '(present)')}`
+      : `${out('label', 'runtime-context:')} ${runtimeContext.file} ${out('dim', '(absent — written by farmslot prepare/dispatch)')}`,
   );
   for (const [key, field] of Object.entries(runtimeContext.fields)) {
-    const value = field.value ?? '(unset)';
+    const isSet = field.value !== undefined && field.value !== null && field.value !== '';
+    const value = isSet ? out('ok', String(field.value)) : out('dim', '(unset)');
     const origin = field.source === 'env' && field.envVar ? `env ${field.envVar}` : field.source;
-    lines.push(`  ${key.padEnd(22)} ${value}  [${origin}] — ${field.customize}`);
+    const originTag = isSet ? out('accent', `[${origin}]`) : out('dim', `[${origin}]`);
+    lines.push(`  ${key.padEnd(22)} ${value}  ${originTag} ${out('dim', `— ${field.customize}`)}`);
   }
   return lines.join('\n');
 }
@@ -189,7 +201,7 @@ export function createDoctorReport(
     compatibilityMode: mode,
     shape: repoShape(target),
     fixture: fixtureSummary(target),
-    runtimeContext: runtimeContextSummary(target),
+    runtimeContext: runtimeContextSummary(target, adapter),
     manifestValidation: manifestValidation.summary,
   };
 }

package/src/mm-harness-cli.ts

@@ -7,11 +7,13 @@
 // teach; genuinely-unknown commands fall to commander's default.
 
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { Command } from 'commander';
 
+import { color } from './cli-color.ts';
 import { handleUpdate, maybeNudge } from './commands/update.ts';
 
 // …/src → its parent is the package root that holds scripts/.
@@ -57,6 +59,25 @@ Example:
   mm-harness actions --adapter mobile
   mm-harness actions --adapter extension --raw`,
   },
+  {
+    name: 'stop',
+    summary: 'Stop the dev server this checkout owns (mobile: port-scoped Metro) and close its log window.',
+    example: 'mm-harness stop',
+    helpText: `mm-harness stop [flags]
+
+  Stop the Metro dev server this checkout owns and close its tmux log-tail window.
+  Port-scoped: only the listener on the checkout's resolved port is signalled, so
+  concurrent slots are untouched. Nothing running = success (idempotent).
+  Extension/core: teaching error (their dev servers are slot-managed).
+
+  --port <port>                      Metro port (default: the checkout's slot context)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness stop
+  mm-harness stop --port 8061`,
+  },
   {
     name: 'call',
     summary: 'Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).',
@@ -345,7 +366,7 @@ const HELP_GROUPS: HelpGroup[] = [
   {
     title: 'DAILY LOOP',
     blurb: 'what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)',
-    commands: ['launch', 'logs', 'debug', 'fixtures'],
+    commands: ['launch', 'stop', 'logs', 'debug', 'fixtures'],
   },
   {
     title: 'DISCOVER',
@@ -375,19 +396,51 @@ function commandMeta(name: string): { summary: string; example: string; planned:
   return { summary: '', example: '', planned: false };
 }
 
+// Slot context the orchestrator's prepare wrote into the checkout, when the
+// help is run from inside one. Presence-gated: no context, no line.
+function detectedSlotLine(out: (style: string, text: string) => string): string | null {
+  const ctxPath = path.join(
+    process.cwd(),
+    process.env.RECIPE_RUNTIME_DIR || 'temp/recipe/runtime',
+    'agentic-runtime.json',
+  );
+  try {
+    const ctx = JSON.parse(fs.readFileSync(ctxPath, 'utf8')) as Record<string, unknown>;
+    const parts: string[] = [];
+    if (ctx.slotId) parts.push(`slot ${out('ok', String(ctx.slotId))}`);
+    if (ctx.simulator) parts.push(`device ${out('ok', String(ctx.simulator))}`);
+    if (ctx.metroPort) parts.push(`metro :${out('ok', String(ctx.metroPort))}`);
+    if (ctx.gitBranch) parts.push(`branch ${out('info', String(ctx.gitBranch))}`);
+    if (parts.length === 0) return null;
+    return `${out('label', 'SLOT')} — this checkout is a prepared slot: ${parts.join(' · ')}`;
+  } catch {
+    return null;
+  }
+}
+
 function groupedHelp(): string {
+  const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
   const lines: string[] = [];
-  lines.push('mm-harness — one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.');
+  lines.push(`${out('bold', 'mm-harness')} — one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.`);
   lines.push('Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.');
-  lines.push('Grammar: mm-harness <command> [target] [flags]   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)');
+  lines.push(`Grammar: ${out('cmd', 'mm-harness <command> [target] [flags]')}   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)`);
+  if (process.env.MM_HARNESS_BIN) {
+    lines.push('');
+    lines.push(`${out('warn', 'DEV OVERRIDE ACTIVE')} — this run is served by MM_HARNESS_BIN=${out('path', process.env.MM_HARNESS_BIN)} (unset it to return to the installed/global bin).`);
+  }
+  const slotLine = detectedSlotLine(out);
+  if (slotLine) {
+    lines.push('');
+    lines.push(slotLine);
+  }
   for (const group of HELP_GROUPS) {
     lines.push('');
-    lines.push(`${group.title} — ${group.blurb}:`);
+    lines.push(`${out('label', group.title)} — ${group.blurb}:`);
     for (const name of group.commands) {
       const meta = commandMeta(name);
       const planned = meta.planned ? '   (planned)' : '';
-      lines.push(`  ${name.padEnd(10)} ${meta.summary}${planned}`);
-      lines.push(`               ${meta.example}`);
+      lines.push(`  ${out('cmd', name.padEnd(10))} ${meta.summary}${planned}`);
+      lines.push(`               ${out('comment', meta.example)}`);
     }
   }
   lines.push('');