@deeeed/metamask-harness 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 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 `--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
 
 ### Fixed

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.7",
+  "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,7 +7,9 @@
 
 import path from 'node:path';
 
-import { EXIT, spawnScript } from '../../commands/shared.ts';
+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';
 import {
@@ -24,10 +26,23 @@ 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 {
-  /** Pass through to leaf-script spawnScript calls so output is suppressed in --json mode. */
+  /**
+   * Whether the caller emits a --json envelope on stdout. Leaf progress always
+   * streams to stderr (see dispatchAction/spawnScriptStreaming); this only gates
+   * the in-process teaching messages so they never pollute the stdout envelope.
+   */
   json?: boolean;
   /**
    * Passed to open-device.sh --preflight-mode.
@@ -55,6 +70,7 @@ export async function mobileRuntimeStatus(
     metroLog: opts.metroLog,
     platform: opts.platform,
     record: opts.record,
+    preflightMode: opts.preflightMode,
   });
 }
 
@@ -77,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 };
   }
@@ -106,8 +124,13 @@ export async function prepareMobile(
       )
     : report.actions;
   for (const action of actions) {
-    const result = dispatchAction(action, target, platform, json, preflightMode);
+    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.
@@ -118,7 +141,7 @@ export async function prepareMobile(
       watcherPort: opts.watcherPort,
       metroLog: opts.metroLog,
       platform,
-      record: true,
+      preflightMode,
     });
     switch (postInstall.decision) {
       case 'install': {
@@ -132,13 +155,13 @@ export async function prepareMobile(
       }
       case 'ready': {
         // Deps resolved and runtime appears ready — still confirm bridge is live.
-        const bridge = dispatchAction({ id: 'wait-for-bridge', cwd: target }, target, platform, json, preflightMode);
+        const bridge = await dispatchAction({ id: 'wait-for-bridge', cwd: target }, target, platform, json, preflightMode);
         if (bridge.status !== 0) return bridge;
         break;
       }
       case 'launch': {
         for (const action of postInstall.actions) {
-          const result = dispatchAction(action, target, platform, json, preflightMode);
+          const result = await dispatchAction(action, target, platform, json, preflightMode);
           if (result.status !== 0) return result;
         }
         break;
@@ -157,51 +180,53 @@ export async function prepareMobile(
   return { status: 0, output: '' };
 }
 
-function dispatchAction(
+// Long-running leaves stream their output to stderr live (spawnScriptStreaming),
+// so the multi-minute prepare phase is not silent; stdout stays reserved for the
+// caller's --json envelope. Async so the parent can await each leaf in sequence.
+async function dispatchAction(
   action: { id: string; argv?: string[]; cwd?: string },
   target: string,
   platform: string,
   json: boolean,
   preflightMode = 'fast',
-): ScriptResult {
+): Promise<ScriptResult> {
   const cwd = action.cwd ?? target;
   switch (action.id) {
     case 'yarn-setup': {
       // Leaf: install node_modules (deps missing or stale); `yarn setup` runs pods.
       const leaf = path.join(runnerDir, 'adapters/mobile/yarn-setup.sh');
-      return spawnScript(leaf, ['--target', cwd], target, json, POD_PROBE_ENV);
+      return spawnScriptStreaming(leaf, ['--target', cwd], target, POD_PROBE_ENV);
     }
     case 'start-metro': {
       // Leaf: ensure Metro is running; argv may carry --clear for cache reset.
       const leaf = path.join(runnerDir, 'adapters/mobile/start-metro.sh');
       const extra: string[] = action.argv ?? [];
-      return spawnScript(leaf, ['--target', cwd, ...extra], target, json);
+      return spawnScriptStreaming(leaf, ['--target', cwd, ...extra], target);
     }
     case 'prewarm-bundle': {
       // Leaf: curl the bundle URL before opening the dev client.
       const leaf = path.join(runnerDir, 'adapters/mobile/prewarm-bundle.sh');
-      return spawnScript(leaf, ['--platform', platform, '--target', cwd], target, json);
+      return spawnScriptStreaming(leaf, ['--platform', platform, '--target', cwd], target);
     }
     case 'wait-for-bridge': {
       // Leaf: poll CDP bridge until a route target registers.
       const leaf = path.join(runnerDir, 'adapters/mobile/wait-for-bridge.sh');
-      return spawnScript(leaf, ['--target', cwd], target, json);
+      return spawnScriptStreaming(leaf, ['--target', cwd], target);
     }
     case 'clear-metro-cache': {
       // Legacy alias for start-metro --clear (kept for backward compat).
       const leaf = path.join(runnerDir, 'adapters/mobile/start-metro.sh');
-      return spawnScript(leaf, ['--target', cwd, '--clear'], target, json);
+      return spawnScriptStreaming(leaf, ['--target', cwd, '--clear'], target);
     }
     case 'launch-mobile-runtime': {
       // Leaf: open the MetaMask Mobile dev client on the simulator/device. In
       // auto/rebuild modes this runs the native build (`yarn start:*`), which
       // triggers pod install — pass the pod-probe env so it stays FORCE_COLOR-safe.
       const leaf = path.join(runnerDir, 'adapters/mobile/open-device.sh');
-      return spawnScript(
+      return spawnScriptStreaming(
         leaf,
         ['--platform', platform, '--target', cwd, '--preflight-mode', preflightMode],
         target,
-        json,
         POD_PROBE_ENV,
       );
     }