@deeeed/metamask-harness 0.6.3 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## 0.7.1
+
+### Added
+- **`doctor --expect-live`** — exit-coded runtime liveness for hooks and scripts: exit 0 only when the adapter runtime decision is `ready` (extension: watcher + CDP; mobile: metro + bridge; core: deps), non-zero with a teaching escape otherwise. Fails closed on every degraded path; reuses the doctor runtime probe, no duplicated checks.
+
+### Fixed
+- **Per-command `--help` documents every implemented flag** (`call/run --list`, `--library`, `--action-manifest`, `logs --window`, `actions --action`, `launch --url`, `doctor --runtime-dir`, `stop --adapter`) and tab-completion matches — the CLI self-teaches its own surface. A contract test guards help/implementation parity.
+- **Injected runner shims resolve at run time** instead of a path baked at inject time: `MM_HARNESS_BIN` → global `mm-harness` on PATH → the recorded install-time path as last resort → teaching escape. A slot copied to or shared with another machine no longer points at a missing absolute path.
+- Removed two parsed-but-unused `launch` flags (`--yes`, `--json-stream`).
+
+## 0.7.0
+
+The "version people use": every remaining identified fix/improvement batched on the
+0.6.x stability foundation. Built on top of the extension quick-reuse regression fix
+(0.6.3, below). One themed commit per item; full contract suite green (macOS).
+
+### Added
+- **`call --list` / `run --list`** — one scope-aware listing of everything invocable
+  for the detected adapter: the fuzzy short-name action universe (each action's full
+  name plus its unambiguous short name — what `call` accepts) and the runnable
+  library flows (what `run <flow>` accepts). No `<action>`/`<recipe>` required; same
+  shape under `--json`.
+- **`logs --window`** — (re)open the read-only tmux tail window for the resolved
+  dev-server port without touching the process (recovers a window closed while
+  Metro/webpack keeps running); teaches when there is no run-owned session or log.
+- **`doctor` surfaces Screen-Recording / capture readiness** (macOS) — shells
+  `capture-helper doctor` and reports pass/WARN with the grant step; capture is
+  optional (absent binary → no row, never a doctor failure). Seam: `CAPTURE_HELPER_PATH`.
+
+### Changed
+- **`fixtures set` is never silent** — an upfront intent line the moment work begins,
+  plus the mobile setup-wallet leaf's own progress streamed live (heartbeat) during
+  the 20-40s wallet build; stdout stays a clean `--json` envelope.
+- **`actions --action <name>` fuzzy-resolves like `call`** (exact full name → exact
+  final segment → substring) and teaches the vocabulary on an unknown name (exit 2,
+  `--json` error envelope) instead of throwing.
+- **`run` auto-detects the adapter** from the target/cwd when `--adapter` is absent
+  (parity with call/doctor); teaches when the repo type cannot be detected.
+- **Log-tail windows follow a run-owned session ladder** — `RECIPE_TMUX_SESSION` →
+  the checkout's `agentic-runtime.json` `session` → the current tmux client — with no
+  slot-number derivation (the orchestrator names the session; the harness only
+  populates windows). Stale `metro-<port>` windows whose port has no live listener
+  are swept on Metro start.
+- **Extension slot ports fill independently** — the resolver no longer early-returns
+  once CDP is known, so a context that pins only `cdpPort` still gets `WATCHER_PORT`
+  from the pool/formula.
+- Orchestrator-neutral protocol-root env: `METAMASK_RUNNER_PROTOCOL_ROOT` is primary,
+  `FARMSLOT_ROOT` a back-compat alias for one release.
+
+### Fixed
+- **Extension `launch` teaches `yarn install --immutable` on missing/stale deps** —
+  a pre-watcher deps-freshness probe fails fast (teaching only, never auto-installs)
+  instead of letting webpack crash deep on stale `node_modules`; gated so a reusable
+  live runtime (reload-in-place) is never blocked.
+- **Core actions run under the target checkout's own tsx** — a core perps action
+  dynamically imports the checkout's controller TypeScript, so it now runs under tsx
+  (resolved from the target first — the published harness ships none; a thin-installed
+  slot has it) rather than bare node throwing `ERR_MODULE_NOT_FOUND`; teaches
+  `yarn install` / `yarn build` when no tsx is found.
+- **Repo-pinned Ruby for iOS pod/gem work** — `yarn setup` / the iOS native build
+  activate the checkout's `.ruby-version` (asdf → rbenv → mise → PATH) so a cold
+  checkout does not build native gems against the system Ruby; teaches the install
+  when the pinned Ruby is unresolved.
+- **iOS deep-link dialog pre-approval at provisioning** — the dev-client scheme
+  approval is persisted right after app install, so the first headless `openurl` does
+  not pause on the "Open in <App>?" dialog (the launch-time write can race).
+- **Extension quick-tier webpack tail window** is regression-guarded (Metro parity).
+
+### Internal
+- Dependabot: no high/critical advisories remain (existing `resolutions` cover them).
+- Boring-library swaps (pidtree, ajv) declined per the "delete hand-rolled code with a
+  bug history" bar: the ps/lsof process detection is contract-tested and working, and
+  manifest validation is already schema-driven via `@farmslot/protocol`.
+- Orchestrator-neutral port leaf: `resolve-farmslot-ports{,-core}.mjs` / `.sh` and
+  `src/adapters/resolve-farmslot-ports.ts` renamed to `resolve-slot-ports*`; the
+  function `resolveFarmslotPortsByRepo`, the bash function / cli key
+  `resolve_farmslot_ports_by_repo`, and the JS export renamed to the `*slot*`
+  equivalents. The old filenames, bash function, cli key, and JS export are kept as
+  delegating shims/aliases for ONE RELEASE (deprecation window) — the next release
+  removes them. The pool-path constants the leaf reads are left as-is (orchestrator
+  data location, not a callable surface).
+
 ## 0.6.3
 
 ### Fixed

package/adapters/core/inject.sh

@@ -88,8 +88,13 @@ install_v1_runner_assets() {
     if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
-    printf 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ "$MM_HARNESS_BIN" != %s ]; then echo "mm-harness overlay: %s: %s (reinstall to repoint: mm-harness install)" >&2; fi\n' "$runner_exec_q" 'delegating to the runner pinned at install time' "$runner_exec_q"
-    printf 'exec %s "$@"\n' "$runner_exec_q"
+    # Resolve the runner at run time (override > global install > install-time
+    # record); the recorded path is last resort so a moved checkout is not pinned.
+    printf '%s\n' 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "${MM_HARNESS_BIN}" ]; then exec "${MM_HARNESS_BIN}" "$@"; fi'
+    printf '%s\n' 'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi'
+    printf 'if [ -x %s ]; then exec %s "$@"; fi\n' "$runner_exec_q" "$runner_exec_q"
+    printf '%s\n' 'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness" >&2'
+    printf '%s\n' 'exit 127'
   } > "$HARNESS_DIR/runner/bin/mm-harness"
   chmod +x "$HARNESS_DIR/runner/bin/mm-harness"
   if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then

package/adapters/extension/inject.mjs

@@ -68,12 +68,19 @@ fs.mkdirSync(path.join(harnessDir, 'runner/recipes'), { recursive: true });
 fs.rmSync(path.join(harnessDir, 'scripts'), { recursive: true, force: true });
 fs.mkdirSync(path.join(harnessDir, 'scripts/lib'), { recursive: true });
 
+// Resolve the runner at run time so a moved or shared checkout is never bound to
+// an install-time absolute path: explicit override, then a global install, then
+// the runner recorded at install time as a last resort; teach install on miss.
+const pinnedBin = shellQuote(path.join(runnerDir, 'bin/mm-harness'));
 const delegate = [
   '#!/usr/bin/env bash',
   'set -euo pipefail',
   protocolRoot ? `export FARMSLOT_ROOT=\${FARMSLOT_ROOT:-${shellQuote(protocolRoot)}}` : null,
-  `if [ -n "\${MM_HARNESS_BIN:-}" ] && [ "\$MM_HARNESS_BIN" != ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} ]; then echo "mm-harness overlay: delegating to the runner pinned at install time: ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} (reinstall to repoint: mm-harness install)" >&2; fi`,
-  `exec ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} "$@"`,
+  'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "${MM_HARNESS_BIN}" ]; then exec "${MM_HARNESS_BIN}" "$@"; fi',
+  'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi',
+  `if [ -x ${pinnedBin} ]; then exec ${pinnedBin} "$@"; fi`,
+  'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness" >&2',
+  'exit 127',
 ].filter(Boolean).join('\n') + '\n';
 fs.writeFileSync(path.join(harnessDir, 'runner/bin/mm-harness'), delegate, { mode: 0o755 });
 if (protocolRoot) fs.writeFileSync(path.join(harnessDir, 'runner/.farmslot-root'), `${protocolRoot}\n`);
@@ -109,11 +116,16 @@ copyFile(path.join(runnerDir, 'adapters/extension/refresh-build.sh'), path.join(
 copyFile(path.join(runnerDir, 'adapters/extension/ensure-browser.sh'), path.join(harnessDir, 'scripts/reopen-browser.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/harness-path.sh'), path.join(harnessDir, 'scripts/lib/harness-path.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/activate-repo-node.sh'), path.join(harnessDir, 'scripts/lib/activate-repo-node.sh'));
+copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports.sh'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports.sh'));
+copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports.mjs'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports.mjs'));
+copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports-core.mjs'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports-core.mjs'));
+// Back-compat shims (one release) so an overlay consumer using the old leaf names still resolves.
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.mjs'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports.mjs'));
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports-core.mjs'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports-core.mjs'));
 copyFile(path.join(runnerDir, 'adapters/shared/path-defaults.json'), path.join(harnessDir, 'scripts/lib/path-defaults.json'));
 copyFile(path.join(runnerDir, 'adapters/shared/json-field.sh'), path.join(harnessDir, 'scripts/lib/json-field.sh'));
+copyFile(path.join(runnerDir, 'adapters/shared/tmux-session.sh'), path.join(harnessDir, 'scripts/lib/tmux-session.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
 makeExecutableTree(path.join(harnessDir, 'scripts'));
 fs.writeFileSync(path.join(harnessDir, 'installed-scripts.sha256'), `${dirContentHash(path.join(harnessDir, 'scripts'))}\n`);

package/adapters/extension/start-watch.sh

@@ -174,12 +174,6 @@ write_canonical_watch_pid() {
   printf '%s\n' "$live_pid" > "$slot_watch_pid_file"
 }
 
-slot_number() {
-  local base
-  base="$(basename "$PWD")"
-  [[ "$base" =~ -([0-9]+)$ ]] && printf '%s\n' "${BASH_REMATCH[1]}"
-}
-
 # Explicit clean-build path: clear the target-scoped webpack cache before
 # starting the harness-owned watcher. Faster incremental refresh stays on
 # `mm-harness refresh`; this script is for proving a clean build works.
@@ -240,17 +234,17 @@ path_prefix="${REPO_NODE_PATH_PREFIX:-}"
 nohup env -u BUNDLED_DEBUGPY_PATH ${path_prefix:+PATH="${path_prefix}${PATH}"} ${WATCHER_PORT:+PORT="$WATCHER_PORT"} yarn start > "$watch_log" 2>&1 &
 started_pid=$!
 printf '%s\n' "$started_pid" > "$watch_pid_file"
-tmux_session="${RECIPE_TMUX_SESSION:-}"
-if [ -z "$tmux_session" ]; then
-  slot="$(slot_number || true)"
-  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)"
+# The orchestrator names the session; the harness only populates windows. Resolve
+# via the run-owned ladder (RECIPE_TMUX_SESSION → agentic-runtime.json session →
+# current tmux client) — no slot-number derivation.
+tmux_session=""
+for _tv_src in "$SCRIPT_DIR/lib/tmux-session.sh" "$SCRIPT_DIR/../shared/tmux-session.sh"; do
+  # shellcheck disable=SC1091
+  [ -f "$_tv_src" ] && { . "$_tv_src"; break; }
+done
+unset _tv_src
+if command -v resolve_run_tmux_session >/dev/null 2>&1; then
+  tmux_session="$(resolve_run_tmux_session "$RUNTIME_DIR")"
 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

@@ -298,6 +298,14 @@
       "inputs": "json path + dotted field",
       "outputs": "field value on stdout"
     },
+    {
+      "id": "lib/tmux-session",
+      "entry": "adapters/shared/tmux-session.sh",
+      "kind": "lib",
+      "purpose": "resolve_run_tmux_session: the run-owned tmux session a log-tail window belongs in (RECIPE_TMUX_SESSION -> agentic-runtime.json session -> current client; no slot-number derivation).",
+      "inputs": "resolve_run_tmux_session [runtime-dir]; env RECIPE_TMUX_SESSION, RECIPE_RUNTIME_CONTEXT, TMUX",
+      "outputs": "resolved session name on stdout (empty when none)"
+    },
     {
       "id": "lib/activate-repo-node",
       "entry": "adapters/shared/activate-repo-node.sh",
@@ -306,6 +314,14 @@
       "inputs": "activate_repo_node [target-dir]; tries asdf, fnm, mise, nvm, then matching node on PATH",
       "outputs": "REPO_NODE_BIN, REPO_NODE_PATH_PREFIX; prepends bin dir to PATH; exit 0/1/2"
     },
+    {
+      "id": "lib/activate-repo-ruby",
+      "entry": "adapters/shared/activate-repo-ruby.sh",
+      "kind": "lib",
+      "purpose": "Manager-agnostic Ruby pin from .ruby-version / .tool-versions for iOS pod/gem work in non-interactive spawns; best-effort variant warns + teaches when unresolved.",
+      "inputs": "activate_repo_ruby [target-dir] (0/1/2); activate_repo_ruby_best_effort [target-dir]; tries asdf, rbenv, mise, then matching ruby on PATH",
+      "outputs": "REPO_RUBY_BIN, REPO_RUBY_PATH_PREFIX; prepends bin dir to PATH"
+    },
     {
       "id": "lib/ensure-runner-deps",
       "entry": "adapters/shared/ensure-runner-deps.sh",
@@ -314,21 +330,37 @@
       "inputs": "ensure-runner-deps.sh [RUNNER_DIR]; env FARMSLOT_ROOT / METAMASK_RUNNER_PROTOCOL_ROOT optional local link target",
       "outputs": "installed node_modules in RUNNER_DIR; exit 0 when deps ready"
     },
+    {
+      "id": "lib/resolve-slot-ports",
+      "entry": "adapters/shared/resolve-slot-ports.mjs",
+      "kind": "node",
+      "purpose": "Resolve CDP + watcher ports from the orchestrator's slot-pool JSON by repo path, else 6660+N / 9010+N.",
+      "inputs": "resolve-slot-ports.mjs resolve_extension_runtime_ports <repo>",
+      "outputs": "CDP_PORT / WATCHER_PORT / SLOT_ID lines on stdout"
+    },
+    {
+      "id": "lib/resolve-slot-ports-core",
+      "entry": "adapters/shared/resolve-slot-ports-core.mjs",
+      "kind": "lib",
+      "purpose": "Self-contained pool/context/formula port resolution imported by the node leaf and TS surface.",
+      "inputs": "ESM import from resolve-slot-ports.mjs or resolve-slot-ports.ts",
+      "outputs": "resolveSlotPortsByRepo and related functions"
+    },
     {
       "id": "lib/resolve-farmslot-ports",
       "entry": "adapters/shared/resolve-farmslot-ports.mjs",
       "kind": "node",
-      "purpose": "Resolve CDP + watcher ports from farmslot pool JSON by repo path, else 6660+N / 9010+N.",
-      "inputs": "resolve-farmslot-ports.mjs resolve_extension_runtime_ports <repo>",
-      "outputs": "CDP_PORT / WATCHER_PORT / SLOT_ID lines on stdout"
+      "purpose": "Back-compat shim (one release): delegates to resolve-slot-ports.mjs.",
+      "inputs": "resolve-farmslot-ports.mjs <fn> <repo>",
+      "outputs": "same as resolve-slot-ports.mjs"
     },
     {
       "id": "lib/resolve-farmslot-ports-core",
       "entry": "adapters/shared/resolve-farmslot-ports-core.mjs",
       "kind": "lib",
-      "purpose": "Self-contained pool/context/formula port resolution imported by the node leaf and TS surface.",
-      "inputs": "ESM import from resolve-farmslot-ports.mjs or resolve-farmslot-ports.ts",
-      "outputs": "resolveFarmslotPortsByRepo and related functions"
+      "purpose": "Back-compat shim (one release): re-exports resolve-slot-ports-core.mjs.",
+      "inputs": "ESM import of the old path",
+      "outputs": "re-exports resolveSlotPortsByRepo (and the resolveFarmslotPortsByRepo alias)"
     },
     {
       "id": "lib/recipe-harness-root",
@@ -339,13 +371,21 @@
       "outputs": "recipeHarnessRoot() relative path string"
     },
     {
-      "id": "lib/resolve-farmslot-ports-sh",
-      "entry": "adapters/shared/resolve-farmslot-ports.sh",
+      "id": "lib/resolve-slot-ports-sh",
+      "entry": "adapters/shared/resolve-slot-ports.sh",
       "kind": "lib",
-      "purpose": "Bash-compat sourced wrapper over resolve-farmslot-ports.mjs for stop-metro and legacy callers.",
+      "purpose": "Bash-compat sourced wrapper over resolve-slot-ports.mjs for stop-metro and legacy callers.",
       "inputs": "source + resolve_* / apply_resolved_* function calls",
       "outputs": "KEY=VALUE lines on stdout; env vars via apply_resolved_*"
     },
+    {
+      "id": "lib/resolve-farmslot-ports-sh",
+      "entry": "adapters/shared/resolve-farmslot-ports.sh",
+      "kind": "lib",
+      "purpose": "Back-compat shim (one release): sources resolve-slot-ports.sh (keeps the resolve_farmslot_ports_by_repo alias).",
+      "inputs": "source",
+      "outputs": "same sourced functions as resolve-slot-ports.sh"
+    },
     {
       "id": "lib/reap-checkout-metros",
       "entry": "adapters/shared/reap-checkout-metros.sh",
@@ -359,6 +399,14 @@
       "inputs": "--target <checkout> --slot-id <id> --cdp-port <port>",
       "outputs": "wallet-fixture.json in runtime dir; exit 0 always (non-zero = informational, no source found)"
     },
+    {
+      "id": "lib/open-log-window",
+      "entry": "adapters/shared/open-log-window.sh",
+      "kind": "bash",
+      "purpose": "(Re)open a read-only tmux tail window for a dev-server log in the run-owned session without touching the process (mm-harness logs --window).",
+      "inputs": "--window <name> --log <path> [--runtime-dir <dir>]",
+      "outputs": "tmux tail window in the resolved session; exit 0 opened / 1 no session or log / 2 bad args"
+    },
     {
       "id": "lib/path-defaults",
       "entry": "adapters/shared/path-defaults.json",

package/adapters/mobile/inject.sh

@@ -187,8 +187,13 @@ install_v1_runner_assets() {
     if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
-    printf 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ "$MM_HARNESS_BIN" != %s ]; then echo "mm-harness overlay: %s: %s (reinstall to repoint: mm-harness install)" >&2; fi\n' "$runner_exec_q" 'delegating to the runner pinned at install time' "$runner_exec_q"
-    printf 'exec %s "$@"\n' "$runner_exec_q"
+    # Resolve the runner at run time (override > global install > install-time
+    # record); the recorded path is last resort so a moved checkout is not pinned.
+    printf '%s\n' 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "${MM_HARNESS_BIN}" ]; then exec "${MM_HARNESS_BIN}" "$@"; fi'
+    printf '%s\n' 'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi'
+    printf 'if [ -x %s ]; then exec %s "$@"; fi\n' "$runner_exec_q" "$runner_exec_q"
+    printf '%s\n' 'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness" >&2'
+    printf '%s\n' 'exit 127'
   } > "$HARNESS_DIR/runner/bin/mm-harness"
   chmod +x "$HARNESS_DIR/runner/bin/mm-harness"
   if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then

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

@@ -13,24 +13,45 @@
 # Inputs (env/args): $1 = metro log path; PORT, LOG_DIR, and optional `slot` from
 # the caller; TMUX indicates we are inside a tmux client.
 
+# Session resolution (RECIPE_TMUX_SESSION → agentic-runtime.json session → current
+# tmux client). Sourced relative to this lib; harness-path fallback for the
+# installed layout where shared libs live beside this file.
+_tv_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _tv_src in "$_tv_dir/tmux-session.sh" "$_tv_dir/../../shared/tmux-session.sh"; do
+  [ -f "$_tv_src" ] && { . "$_tv_src"; break; }
+done
+unset _tv_src _tv_dir
+
 # 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
+  # The orchestrator names the session; the harness only populates windows. No
+  # slot-number derivation — the name comes from the run-owned session ladder.
+  local session
+  session="$(resolve_run_tmux_session "$LOG_DIR")"
   # 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
+  # Hygiene: close stale metro-<port> windows in this session whose port has no
+  # live listener — a previous run's window left tailing a dead log. The current
+  # window is (re)created below, so skip it here.
+  if command -v lsof >/dev/null 2>&1; then
+    tmux list-windows -t "$session" -F '#{window_name}' 2>/dev/null | while IFS= read -r _win; do
+      [ "$_win" = "$window" ] && continue
+      case "$_win" in
+        metro-*) : ;;
+        *) continue ;;
+      esac
+      _p="${_win#metro-}"
+      case "$_p" in ''|*[!0-9]*) continue ;; esac
+      if ! lsof -nP -iTCP:"$_p" -sTCP:LISTEN -t >/dev/null 2>&1; then
+        tmux kill-window -t "${session}:${_win}" >/dev/null 2>&1 || true
+      fi
+    done
+  fi
   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"

package/adapters/mobile/open-device.sh

@@ -51,6 +51,15 @@ esac
 
 TARGET="$(cd "$TARGET" && pwd)"
 
+# Pin the repo's Ruby for the iOS native build (pod/gem work): a cold checkout
+# under nohup/tmux otherwise uses the system Ruby and fails native gem builds.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _rb in "$SCRIPT_DIR/../shared/activate-repo-ruby.sh" "$SCRIPT_DIR/lib/activate-repo-ruby.sh"; do
+  [ -f "$_rb" ] && { . "$_rb"; break; }
+done
+unset _rb
+
 # --- iOS helpers --------------------------------------------------------------
 
 ios_app_installed() {
@@ -61,7 +70,11 @@ ios_app_installed() {
 run_ios_native_build() {
   local sim_target="$1" reason="$2"
   printf '%s; installing with yarn start:ios (WATCHER_PORT=%s)\n' "$reason" "$PORT" >&2
-  (cd "$TARGET" && WATCHER_PORT="$PORT" METRO_PORT="$PORT" IOS_SIMULATOR="$sim_target" EXPO_NO_TYPESCRIPT_SETUP=1 yarn start:ios 2>&1)
+  (
+    cd "$TARGET"
+    command -v activate_repo_ruby_best_effort >/dev/null 2>&1 && activate_repo_ruby_best_effort "$TARGET"
+    WATCHER_PORT="$PORT" METRO_PORT="$PORT" IOS_SIMULATOR="$sim_target" EXPO_NO_TYPESCRIPT_SETUP=1 yarn start:ios 2>&1
+  )
 }
 
 ensure_ios_app_for_mode() {

package/adapters/mobile/stop-metro.sh

@@ -35,7 +35,7 @@ fi
 # 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"
+  . "$SCRIPT_DIR/../shared/resolve-slot-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

package/adapters/mobile/yarn-setup.sh

@@ -12,6 +12,9 @@
 #          no native). The Metro-only remedy: native builds come from open-device.
 set -euo pipefail
 
+# Resolve SCRIPT_DIR before any cd (the script may be invoked by a relative path).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
 TARGET="$PWD"
 MODE="full"
 while [ "$#" -gt 0 ]; do
@@ -25,8 +28,19 @@ done
 
 TARGET="$(cd "$TARGET" && pwd)"
 cd "$TARGET"
+
+# full mode runs native pods/jetify → pin the repo's Ruby so a cold checkout does
+# not build iOS gems against the system Ruby. Best-effort (never blocks the setup).
+# shellcheck disable=SC1091
+for _rb in "$SCRIPT_DIR/../shared/activate-repo-ruby.sh" "$SCRIPT_DIR/lib/activate-repo-ruby.sh"; do
+  [ -f "$_rb" ] && { . "$_rb"; break; }
+done
+unset _rb
+
 case "$MODE" in
-  full) exec yarn setup ;;
+  full)
+    command -v activate_repo_ruby_best_effort >/dev/null 2>&1 && activate_repo_ruby_best_effort "$TARGET"
+    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/activate-repo-ruby.sh

@@ -0,0 +1,124 @@
+# activate-repo-ruby.sh — pin the target repo's declared Ruby for non-interactive spawns
+#
+# iOS pod/gem work (yarn setup, native build) reads Ruby from PATH. Under tmux /
+# nohup / a cold checkout the PATH is the system Ruby, which does not match the
+# repo's .ruby-version and fails `bundle install` / `pod install` with native gem
+# build errors. Sourced by the leaves that trigger pods so they run the pinned
+# Ruby, mirroring activate-repo-node.sh for Node.
+#
+# On success sets REPO_RUBY_VERSION / REPO_RUBY_BIN / REPO_RUBY_BIN_DIR /
+# REPO_RUBY_PATH_PREFIX and prepends the bin dir to PATH.
+#
+# Usage:
+#   . /path/to/activate-repo-ruby.sh
+#   activate_repo_ruby [target-dir]          # 0 pinned; 1 none declared; 2 declared but unresolved
+#   activate_repo_ruby_best_effort [dir]     # never fails the caller; warns + teaches on 2
+
+_repo_ruby_matches_req() {
+  local req="$1" actual="${2:-}"
+  [ -n "$actual" ] || actual="$("$REPO_RUBY_BIN" -e 'print RUBY_VERSION' 2>/dev/null || true)"
+  [ -n "$actual" ] || return 1
+  [ "$actual" = "$req" ] && return 0
+  case "$req" in
+    *.*.*) return 1 ;;
+    *.*) [[ "$actual" == "$req."* ]] ;;
+    *) [[ "$actual" == "$req"* ]] ;;
+  esac
+}
+
+_repo_ruby_set_from_bin() {
+  local candidate="$1"
+  [ -n "$candidate" ] && [ -x "$candidate" ] || return 1
+  REPO_RUBY_BIN="$candidate"
+  REPO_RUBY_BIN_DIR="$(cd "$(dirname "$REPO_RUBY_BIN")" && pwd)"
+  REPO_RUBY_PATH_PREFIX="${REPO_RUBY_BIN_DIR}:"
+  export PATH="${REPO_RUBY_BIN_DIR}:${PATH}"
+  return 0
+}
+
+_repo_ruby_try_req() {
+  local target="$1" req="$2"
+  [ -n "$req" ] || return 1
+  REPO_RUBY_VERSION="$req"
+
+  if command -v asdf >/dev/null 2>&1; then
+    local asdf_root
+    asdf_root="$(asdf where ruby "$req" 2>/dev/null || true)"
+    if [ -n "$asdf_root" ] && _repo_ruby_set_from_bin "$asdf_root/bin/ruby" && _repo_ruby_matches_req "$req"; then
+      echo "[env] ruby $("$REPO_RUBY_BIN" -e 'print RUBY_VERSION') from .ruby-version/.tool-versions via asdf ($req)" >&2
+      return 0
+    fi
+  fi
+
+  if command -v rbenv >/dev/null 2>&1; then
+    local rbenv_root
+    rbenv_root="$(rbenv root 2>/dev/null || true)"
+    if [ -n "$rbenv_root" ] && _repo_ruby_set_from_bin "$rbenv_root/versions/$req/bin/ruby" && _repo_ruby_matches_req "$req"; then
+      echo "[env] ruby $("$REPO_RUBY_BIN" -e 'print RUBY_VERSION') from .ruby-version via rbenv ($req)" >&2
+      return 0
+    fi
+  fi
+
+  if command -v mise >/dev/null 2>&1; then
+    local mise_bin
+    mise_bin="$(mise x -C "$target" -- which ruby 2>/dev/null || true)"
+    if _repo_ruby_set_from_bin "$mise_bin" && _repo_ruby_matches_req "$req"; then
+      echo "[env] ruby $("$REPO_RUBY_BIN" -e 'print RUBY_VERSION') from .ruby-version via mise ($req)" >&2
+      return 0
+    fi
+  fi
+  return 1
+}
+
+activate_repo_ruby() {
+  local target="${1:-.}"
+  REPO_RUBY_VERSION=""
+  REPO_RUBY_BIN=""
+  REPO_RUBY_BIN_DIR=""
+  REPO_RUBY_PATH_PREFIX=""
+
+  local declared=false req=""
+  if [ -f "$target/.ruby-version" ]; then
+    declared=true
+    req="$(tr -d ' \t\r\n' < "$target/.ruby-version")"
+    req="${req#ruby-}"
+    _repo_ruby_try_req "$target" "$req" && return 0
+  fi
+  if [ -z "$req" ] && [ -f "$target/.tool-versions" ]; then
+    declared=true
+    req="$(awk '/^ruby / {print $2; exit}' "$target/.tool-versions")"
+    _repo_ruby_try_req "$target" "$req" && return 0
+  fi
+
+  if [ "$declared" != true ]; then
+    return 1
+  fi
+
+  # Declared already-on-PATH match (e.g. chruby/system already correct).
+  local path_ruby
+  path_ruby="$(command -v ruby 2>/dev/null || true)"
+  if [ -n "$req" ] && _repo_ruby_set_from_bin "$path_ruby" && _repo_ruby_matches_req "$req"; then
+    echo "[env] ruby $("$REPO_RUBY_BIN" -e 'print RUBY_VERSION') already on PATH ($req)" >&2
+    return 0
+  fi
+
+  REPO_RUBY_BIN=""
+  REPO_RUBY_BIN_DIR=""
+  REPO_RUBY_PATH_PREFIX=""
+  return 2
+}
+
+# Best-effort: never fails the caller. On a declared-but-unresolved Ruby, warn with
+# a teaching hint so a subsequent pod/gem failure is diagnosable (system Ruby).
+activate_repo_ruby_best_effort() {
+  local target="${1:-.}"
+  # Guard the call so a non-zero return (no version / unresolved) never trips the
+  # caller's set -e before we can inspect the code.
+  local rc=0
+  activate_repo_ruby "$target" || rc=$?
+  if [ "$rc" -eq 2 ]; then
+    echo "[env] repo pins ruby ${REPO_RUBY_VERSION:-?} (.ruby-version/.tool-versions) but no installed manager provided it; using system ruby." >&2
+    echo "  Next: install it — asdf install ruby ${REPO_RUBY_VERSION:-<version>}  (or rbenv install) — then re-run, so iOS gems build against the pinned Ruby" >&2
+  fi
+  return 0
+}

package/adapters/shared/open-log-window.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# open-log-window.sh — (re)open a read-only tmux tail window for a dev-server log
+# in the run-owned session, WITHOUT touching the dev-server process. Idempotent:
+# an existing same-name window is replaced with a fresh tail. Used by
+# `mm-harness logs --window` to recover a window that was closed while Metro/webpack
+# keeps running.
+#
+# Args: --window <name> --log <path> [--runtime-dir <dir>]
+# Exit: 0 opened; 1 no run-owned session / no tmux / log missing (teaches); 2 bad args.
+set -euo pipefail
+
+WINDOW=""
+LOG=""
+RUNTIME_DIR=""
+require_value() { [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; }
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --window) require_value "$@"; WINDOW="$2"; shift 2 ;;
+    --log) require_value "$@"; LOG="$2"; shift 2 ;;
+    --runtime-dir) require_value "$@"; RUNTIME_DIR="$2"; shift 2 ;;
+    -h|--help) echo "Usage: open-log-window.sh --window <name> --log <path> [--runtime-dir <dir>]"; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$WINDOW" ] && [ -n "$LOG" ] || { echo "open-log-window: --window and --log are required" >&2; exit 2; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _src in "$SCRIPT_DIR/tmux-session.sh" "$SCRIPT_DIR/lib/tmux-session.sh"; do
+  [ -f "$_src" ] && { . "$_src"; break; }
+done
+unset _src
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "open-log-window: tmux is not installed; cannot open a log window." >&2
+  echo "  Next: tail the log directly — mm-harness logs --full" >&2
+  exit 1
+fi
+if [ ! -f "$LOG" ]; then
+  echo "open-log-window: no log at $LOG (dev server not started for this checkout)." >&2
+  echo "  Next: start it — mm-harness launch" >&2
+  exit 1
+fi
+session=""
+command -v resolve_run_tmux_session >/dev/null 2>&1 && session="$(resolve_run_tmux_session "$RUNTIME_DIR")"
+if [ -z "$session" ] || ! tmux has-session -t "=$session" 2>/dev/null; then
+  echo "open-log-window: no run-owned tmux session to place the window in." >&2
+  echo "  Next: run inside your slot's tmux session, or set RECIPE_TMUX_SESSION=<session>, then retry" >&2
+  exit 1
+fi
+
+tmux kill-window -t "${session}:${WINDOW}" 2>/dev/null || true
+log_q="$(printf '%q' "$LOG")"
+tmux new-window -d -t "$session" -n "$WINDOW" "exec tail -n +1 -F $log_q"
+echo "log window → tmux ${session}:${WINDOW}" >&2