@deeeed/metamask-harness 0.3.8 → 0.4.0

package/CHANGELOG.md

@@ -1,19 +1,68 @@
 # Changelog
 
+## 0.4.0 - 2026-07-04
+
+Minor release: the adapter-surface architecture plus the day's feature wave (0.3.6-0.3.9 shipped fixes as they were validated live; this cut marks the surface additions honestly).
+
+### Added
+- **AdapterSurface** — one per-platform surface behind a common interface (`src/adapters/surface.ts`: resolveSlotPorts, runtimeStatus, devServer, logSources, hints); doctor/launch/stop/logs/debug/fixtures are surface-backed, so no verb hand-rolls platform branching. Contract: `docs/ADAPTER-SURFACE.md` (never-branch rule, add-a-platform checklist, migration table).
+- **Platform-adaptive `stop` on every adapter** — extension: kills this checkout's webpack watcher (pid file + orphan scan, slot-scoped) and closes its tail window; mobile: port-scoped Metro; core: headless teaching error. Idempotent, outcome-stating summaries.
+- **Doctor reports live runtime state on every adapter** — mobile Metro, extension webpack (via the extension readiness decision), core deps-only — one uniform shape, adapter-scoped colored context rows.
+- **`logs` is multi-source per adapter** — sources and the `--source` default come from the adapter's logSources (extension: webpack/watcher/rebuild/app).
+- **Context-aware examples and tier-visible flows** — `call` usage/help examples use the detected adapter's real manifest actions; `flows` prints a precedence legend decoding each source into personal > team > canonical.
+
+### Changed
+- **BREAKING (agent contract)**: `doctor --json` `runtime.metro` (string) is now `runtime.devServer` `{label, status}` and is absent for core.
+
+### Feature wave recap (0.3.6-0.3.9)
+- `mm-harness stop`; live-streamed mobile AND extension launches with upfront intent lines; presence-authoritative readiness (no setup-on-every-launch) with the dev-client running probe; slot-context-first device/port resolution; UTF-8 locale for pod spawns; DEV OVERRIDE banner + SLOT line + colored help; `mmdev-harness` completions; hermetic tmux-stubbed contract suite (now gating CI) + ESLint in `npm run check`; `docs/UX-PRINCIPLES.md` interaction contract.
+
+## 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
+- **Adapter surface — one seam for per-platform behavior** — `src/adapters/surface.ts` defines `AdapterSurface` + a `getAdapterSurface(adapter)` registry that owns the behavior commands used to hand-roll with `if (adapter === …)` ladders (slot-port resolution, read-only runtime status, dev-server describe/stop, log sources, and platform-phrased Next: hints), with thin `mobile`/`extension`/`core` implementations that delegate to the existing readiness/port plumbing (re-homed to `src/adapters/slot-ports.ts`). `doctor`, `launch`, `stop`, `logs`, `debug`, and `fixtures` now resolve platform behavior through the surface instead of branching. This closes the platform-blind class of bug (a platform handled in one command but forgotten in another). Documented in `docs/ADAPTER-SURFACE.md`; enforces `docs/UX-PRINCIPLES.md` principle 1.
+- **`doctor` reports a runtime section for every adapter** — the live runtime readiness line (decision + reasons, deps currency, dev server) now renders for extension (webpack watcher via `decideExtensionReadiness`) and core (deps-presence-only), not just mobile; the render is one uniform shape sourced from the surface.
+- **`mm-harness stop` is adaptive per platform** — mobile stops its port-scoped Metro and closes the log-tail window; extension stops the checkout's webpack watcher (pid file + orphan ps-scan, slot-scoped) and closes its tail window; core teaches the headless path. All idempotent (nothing-to-stop is success), with a uniform summary and `--json` envelope.
+- **`logs` resolves dev-server log sources through the surface** — extension now recognizes the webpack, watcher, and rebuild logs (ordered), not only `webpack.log`; each platform's "nothing running" teaches its own launch hint. `--source` default and valid set come from the adapter's own log sources (extension defaults to `webpack`, not `metro`), and core teaches with platform-neutral wording (no Metro vocabulary). `--source <label>` now prefers that dev-server log.
+- **`call` with no action gives a context-aware example** — the usage error shows the DETECTED adapter and a REAL action from its manifest (a wallet action where one exists, else the universal `command`) plus the scoped `mm-harness actions --adapter <detected>` discovery hint. The static `call --help` example now uses real actions (`ensure_unlocked` / `command`) and points at `mm-harness actions`, instead of a hardcoded `call unlock --adapter extension` naming a non-existent `metamask.wallet.unlock`.
+- **`flows` surfaces the resolution tier per source** — `flows` prints a precedence legend mapping each resolved library source to its tier (`personal` / `team` / `canonical`), derived from the actual resolution, so the engine's `source=<name>` per flow is decodable and LOCAL libraries read as first-class; the tier is also named in the recipe-library-unavailable teaching error.
+- **`stop --help` matches the adaptive behavior** — the help text now describes mobile Metro / extension webpack watcher / core headless, instead of the stale "Metro dev server … extension/core: teaching error".
+- **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
+- **`doctor --json` runtime dev-server shape is normalized** — the mobile-only `runtime.metro` string is replaced by a platform-labelled `runtime.devServer: { label, status }` (`metro` for mobile, `webpack` for extension; absent for headless core), so agents read one shape across platforms.
+- **`yarn check` runs ESLint** — flat-config ESLint (typescript-eslint recommended on `src/**/*.ts`, `@eslint/js` recommended on the `.mjs`/`.cjs` library) runs after typecheck and comment-hygiene. Dev-only (not in the published `files`); the baseline is zero-warning by config scoping.
+- **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/ADAPTER-SURFACE.md

@@ -0,0 +1,119 @@
+# The adapter surface — one seam for per-platform behavior
+
+`mm-harness` runs against three platforms (mobile | extension | core). The
+danger is that every command re-derives "what does this platform do?" with its
+own `if (adapter === 'mobile') … else if (adapter === 'extension') …` ladder.
+When it does, a platform gets forgotten in one command but not another — the
+class of bug where `doctor` reported a live runtime section for mobile only,
+`stop` refused every non-mobile adapter, and `logs` knew a single extension log
+file instead of all three. Those are *platform-blind* commands.
+
+The **adapter surface** is the fix: one interface per platform, resolved through
+a registry, that owns the behavior a command would otherwise branch on.
+
+## The interface
+
+`src/adapters/surface.ts` defines `AdapterSurface` and the registry
+`getAdapterSurface(adapter)`. Each platform ships one implementation:
+
+- `src/adapters/mobile/surface.ts`
+- `src/adapters/extension/surface.ts`
+- `src/adapters/core/surface.ts`
+
+```ts
+interface AdapterSurface {
+  readonly adapter: MetaMaskRecipeAdapter;
+  readonly headless: boolean;                       // core runs no app/dev server
+  resolveSlotPorts(target: string): void;           // context > pool > formula (no-op for core)
+  runtimeStatus(target: string): Promise<AdapterRuntimeStatus>; // read-only readiness for doctor
+  devServer: {
+    describe(): string;                             // "Metro" | "webpack watcher" | "no dev server (headless)"
+    stop(target: string): AdapterDevServerStop;     // idempotent, slot-scoped; headless = teach
+  };
+  logSources(target: string): AdapterLogSource[];   // ordered candidate log files (empty for core)
+  hints: { launch: string; relaunch: string };      // platform-phrased Next: hints
+}
+```
+
+`runtimeStatus` returns a normalized shape so `doctor` renders one line the same
+way for every platform:
+
+```ts
+interface AdapterRuntimeStatus {
+  decision: string;
+  reasonCode?: string;
+  reasons: string[];
+  deps?: string;
+  devServer?: { label: string; status: string };    // absent for headless core
+}
+```
+
+The implementations are thin: they delegate to the readiness/port plumbing that
+already existed (`decideExtensionReadiness`, `mobileRuntimeStatus`, the slot-port
+resolvers and the webpack-watcher stop, all re-homed to
+`src/adapters/slot-ports.ts`). The surface is an organizing seam, not a rewrite.
+
+## The rule
+
+**A command never branches on adapter for behavior the surface owns.**
+
+- Do not write `if (adapter === 'core')` — ask `surface.headless`.
+- Do not write `adapter === 'mobile' ? metroPorts() : extensionPorts()` — call
+  `surface.resolveSlotPorts(target)`.
+- Do not print `adapter === 'mobile' ? 'mm-harness launch ios' : 'mm-harness
+  launch'` — use `surface.hints.launch`.
+
+A new platform behavior is added by **extending the surface** (a new member on
+the interface plus its three implementations), never by adding another branch to
+a command. TypeScript then makes it impossible to ship a platform that forgot the
+new member, because each implementation is annotated `: AdapterSurface`.
+
+What the surface deliberately does **not** own: a command may still branch on
+adapter for a *mechanism* that is genuinely platform-specific and not part of the
+interface — e.g. `fixtures set` uses a shell arm on mobile and the engine path on
+extension. Those branches select a mechanism; they never re-derive readiness,
+ports, log locations, dev-server lifecycle, or Next: phrasing, which are the
+surface's responsibility.
+
+## Migration status
+
+Every command that used to branch on adapter now resolves through the surface:
+
+| command | surface-backed | uses |
+| --- | --- | --- |
+| `doctor` | yes | `resolveSlotPorts` + `runtimeStatus` (mobile/extension/core runtime section) |
+| `launch` | yes | `resolveSlotPorts` |
+| `stop` | yes | `resolveSlotPorts` + `devServer.stop` (+ headless teaching) |
+| `logs` | yes | `logSources` + `hints.launch` + `headless` |
+| `debug` | yes | `headless` + `hints.relaunch` (core teaching); flag semantics stay per-command |
+| `fixtures` | yes | `headless` + `hints` (retry/launch); the set *mechanism* stays per-platform |
+| `run` / `call` | n/a | engine path; core-headless is handled by the heal contract, not the surface |
+| `flows` | no (by design) | recipe-library flows are adapter-global; not a platform-owned behavior |
+| `completion-candidates` | partial | `actions` scope to the detected checkout adapter; `flows` are adapter-global |
+
+`flows` is intentionally not surface-backed: a recipe-library flow can compose
+actions across platforms, so flows are adapter-global by design rather than a
+platform-blind gap. `completion-candidates actions` already resolves the adapter
+from the checkout context (cwd/`--target`); only the adapter-global `flows`
+candidates are unscoped, matching the flows model.
+
+## How this composes with the UX principles
+
+`docs/UX-PRINCIPLES.md` principle 1 (*Context-aware by default* — "output is
+scoped to the platform… help, flag lists, and completion candidates shrink to
+what applies here") states the intent. The adapter surface is its **enforcement
+mechanism**: a command that resolves platform behavior through the surface is
+context-aware by construction, and one that hand-rolls an adapter ladder is the
+exact failure principle 1 warns against. When adding a command or output path,
+satisfy principle 1 by going through the surface.
+
+## Adding a platform behavior — checklist
+
+1. Add the member to `AdapterSurface` in `src/adapters/surface.ts`.
+2. Implement it in all three `src/adapters/*/surface.ts` (TypeScript will not
+   compile until you do).
+3. Have the command call `getAdapterSurface(adapter).<member>` instead of
+   branching.
+4. Cover the closed blind spot with a contract test (see
+   `tests/contract/adapter-surface.test.sh`), and keep the registry-completeness
+   assertion green.

package/docs/UX-PRINCIPLES.md

@@ -0,0 +1,64 @@
+# 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.
+- Enforcement: platform-specific behavior is resolved through the adapter surface
+  (`getAdapterSurface(adapter)`), never a per-command `if (adapter === …)` ladder —
+  that ladder is how commands go platform-blind. See docs/ADAPTER-SURFACE.md.
+
+## 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.4.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -17,12 +17,21 @@
     "@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": {
+    "@eslint/js": "^9",
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "eslint": "^9",
+    "globals": "^17.7.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8"
   },
   "main": "./src/index.ts",
   "types": "./src/index.ts",

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/core/surface.ts

@@ -0,0 +1,56 @@
+// Core surface: headless. No app, no dev server — dependency presence is the
+// only runtime signal, and lifecycle commands teach the reachable headless path.
+import path from 'node:path';
+
+import { depsCheck } from '@farmslot/recipe-harness/runtime/deps-readiness';
+
+import type {
+  AdapterDevServerStop,
+  AdapterLogSource,
+  AdapterRuntimeStatus,
+  AdapterSurface,
+} from '../surface.ts';
+
+export const coreSurface: AdapterSurface = {
+  adapter: 'core',
+  headless: true,
+
+  resolveSlotPorts(): void {
+    // Headless: no ports or device to resolve.
+  },
+
+  async runtimeStatus(target: string): Promise<AdapterRuntimeStatus> {
+    const deps = depsCheck(path.resolve(target));
+    const ready = deps.status === 'current';
+    return {
+      decision: ready ? 'ready' : 'install',
+      reasonCode: ready ? 'deps-present' : `deps-${deps.status}`,
+      reasons: [
+        ready
+          ? 'Core is headless; dependencies are installed. Run recipes with mm-harness run.'
+          : 'Core is headless; dependencies are not fully installed.',
+      ],
+      deps: deps.status,
+    };
+  },
+
+  devServer: {
+    describe: () => 'no dev server (headless)',
+    stop(): AdapterDevServerStop {
+      return {
+        kind: 'headless',
+        message: 'core is headless — no dev server runs for a core checkout',
+        userAction: 'use mm-harness verify (readiness) or mm-harness run (execute a recipe)',
+      };
+    },
+  },
+
+  logSources(): AdapterLogSource[] {
+    return [];
+  },
+
+  hints: {
+    launch: 'mm-harness run <recipe>   # run recipes against the headless core',
+    relaunch: 'mm-harness verify',
+  },
+};