@deeeed/metamask-harness 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 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
+- **Extension `launch` reuses a healthy live runtime instead of always clean-building** — quick `launch` / `launch --sidepanel` on an extension slot now probes for a reusable runtime (webpack watcher LISTENing on `WATCHER_PORT` + CDP `/json/version` reachable on `CDP_PORT` + dist not stale). When all hold it REATTACHES: re-snapshots `dist/chrome` into the loaded runtime-dist and reloads the extension in place over CDP (service worker + pages), re-asserts the side panel, and applies `--url` — against the existing slot Chrome profile, with no watcher stop, webpack cache clear, or Chrome kill/relaunch. Reuse is best-effort: a failed probe (watcher down, CDP unreachable, stale dist) falls through to the clean path, and `--build` is the explicit escape that always clean-builds + relaunches a fresh runtime (no probe) to force-recover a broken slot.
+
 ## 0.6.2 - 2026-07-06
 
 ### Added

package/adapters/extension/inject.mjs

@@ -101,6 +101,7 @@ copyFile(path.join(runnerDir, 'adapters/extension/snapshot-dist.sh'), path.join(
 copyFile(path.join(runnerDir, 'adapters/extension/pin-remote-flags.cjs'), path.join(harnessDir, 'scripts/pin-remote-flags.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/seed-fixture.sh'), path.join(harnessDir, 'scripts/seed-fixture.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/sidepanel-toggle.sh'), path.join(harnessDir, 'scripts/sidepanel-toggle.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/reattach.sh'), path.join(harnessDir, 'scripts/reattach.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/readiness.mjs'), path.join(harnessDir, 'scripts/readiness.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/wallet-fixture-state.cjs'), path.join(harnessDir, 'scripts/wallet-fixture-state.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/verify.sh'), path.join(harnessDir, 'scripts/verify.sh'));
@@ -108,11 +109,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`);
@@ -138,6 +144,7 @@ const manifest = {
     refreshBuild: `${harnessRel}/scripts/refresh-build.sh`,
     reopenBrowser: `${harnessRel}/scripts/reopen-browser.sh`,
     sidepanelToggle: `${harnessRel}/scripts/sidepanel-toggle.sh`,
+    reattach: `${harnessRel}/scripts/reattach.sh`,
   },
   patchedFiles: [],
   backupDir: null,

package/adapters/extension/reattach.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# reattach.sh — reload a live extension slot in place (no rebuild, no relaunch)
+#
+# Purpose:
+#   Quick-reuse leaf for `mm-harness launch` on an already-healthy extension slot:
+#   re-snapshots dist/chrome into the loaded runtime-dist so the running Chrome
+#   picks up watched code changes, then reloads the extension over CDP (service
+#   worker + extension pages) and re-opens the wallet. Optionally navigates a
+#   main tab to --start-url. Runs entirely against the EXISTING slot Chrome
+#   profile — it never stops the watcher, kills Chrome, or clears the webpack
+#   cache (that is the clean path in live.sh).
+#
+# Inputs (flags / env):
+#   --target <metamask-extension> (default $PWD; becomes the working dir)
+#   --cdp-port <port> (required, numeric) — the slot's CDP endpoint
+#   --watcher-port <port> (optional; informational only)
+#   --start-url <url> (optional; opened as a main tab beside the wallet)
+#   --ext-id <id> (optional; else resolved from the extension.id file or CDP)
+#   --dist-dir <rel> (default dist/chrome), --settle-ms <ms> (default 8000)
+#
+# Outputs:
+#   Progress on stderr. Exit 0 — reloaded; 1 — repo/reload failed; 2 — bad args
+#   / non-numeric port / CDP unreachable.
+#
+# Never touches: product source files; the webpack watcher; the Chrome process;
+# other slots' browsers (single CDP port scope).
+set -euo pipefail
+
+TARGET="$PWD"
+CDP_PORT="${CDP_PORT:-}"
+WATCHER_PORT="${WATCHER_PORT:-}"
+START_URL="${EXTENSION_START_URL:-}"
+EXT_ID="${EXT_ID:-}"
+DIST_DIR="dist/chrome"
+SETTLE_MS="8000"
+
+require_value() { [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; }
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) require_value "$@"; TARGET="$2"; shift 2 ;;
+    --cdp-port) require_value "$@"; CDP_PORT="$2"; shift 2 ;;
+    --watcher-port) require_value "$@"; WATCHER_PORT="$2"; shift 2 ;;
+    --start-url) require_value "$@"; START_URL="$2"; shift 2 ;;
+    --ext-id) require_value "$@"; EXT_ID="$2"; shift 2 ;;
+    --dist-dir) require_value "$@"; DIST_DIR="$2"; shift 2 ;;
+    --settle-ms) require_value "$@"; SETTLE_MS="$2"; shift 2 ;;
+    -h|--help)
+      echo "Usage: reattach.sh --target <metamask-extension> --cdp-port <port> [--watcher-port <port>] [--start-url <url>] [--ext-id <id>] [--dist-dir <rel>] [--settle-ms <ms>]"
+      exit 0
+      ;;
+    *) echo "reattach: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -z "$CDP_PORT" ]; then
+  echo "reattach: --cdp-port is required" >&2
+  echo "  Next: mm-harness launch --build   (clean build + relaunch a fresh slot)" >&2
+  exit 2
+fi
+case "$CDP_PORT" in
+  *[!0-9]*) echo "reattach: --cdp-port must be numeric (got: $CDP_PORT)" >&2; exit 2 ;;
+esac
+
+if [ ! -f "$TARGET/package.json" ]; then
+  echo "reattach: --target is not a checkout (no package.json): $TARGET" >&2
+  echo "  Next: mm-harness launch --target /path/to/metamask-extension --build" >&2
+  exit 1
+fi
+TARGET="$(cd "$TARGET" && pwd)"
+
+if ! curl -s -m 3 "http://127.0.0.1:${CDP_PORT}/json/version" >/dev/null 2>&1; then
+  echo "reattach: CDP not reachable on port ${CDP_PORT}; the slot browser is not live." >&2
+  echo "  Next: mm-harness launch --build   (clean build + relaunch)" >&2
+  exit 2
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DIST_ABS="$TARGET/$DIST_DIR"
+# The running Chrome loads the runtime-dist snapshot (frozen at launch), not the
+# live dist. Re-snapshot so the in-place reload serves the latest watched build.
+RUNTIME_DIST_ABS="$TARGET/temp/recipe/runtime/runtime-dist"
+
+if [ -f "$SCRIPT_DIR/snapshot-dist.sh" ] && [ -d "$RUNTIME_DIST_ABS" ]; then
+  echo "[reattach] re-snapshotting dist -> runtime-dist for in-place reload" >&2
+  bash "$SCRIPT_DIR/snapshot-dist.sh" --dist "$DIST_ABS" --runtime-dist "$RUNTIME_DIST_ABS" >&2 || {
+    echo "reattach: dist re-snapshot failed; the loaded extension may be mid-rebuild." >&2
+    echo "  Next: mm-harness launch --build   (clean build + relaunch)" >&2
+    exit 1
+  }
+fi
+
+# Resolve the extension id: explicit flag, then the recorded id file, else CDP.
+if [ -z "$EXT_ID" ]; then
+  for idf in "$TARGET/temp/recipe/runtime/extension.id" "$SCRIPT_DIR/extension.id"; do
+    if [ -f "$idf" ]; then
+      EXT_ID="$(tr -d '[:space:]' < "$idf")"
+      [ -n "$EXT_ID" ] && break
+    fi
+  done
+fi
+
+cd "$TARGET"
+echo "[reattach] reloading extension in place over CDP :${CDP_PORT}" >&2
+
+CDP_PORT="$CDP_PORT" EXT_ID="$EXT_ID" START_URL="$START_URL" SETTLE_MS="$SETTLE_MS" node <<'NODE'
+let chromium; try { chromium = require('@playwright/test').chromium; } catch { chromium = require('playwright').chromium; }
+
+const port = process.env.CDP_PORT;
+const startUrl = process.env.START_URL || '';
+const settleMs = Number(process.env.SETTLE_MS || '8000') || 8000;
+
+function extensionIdFrom(context, provided) {
+  if (provided) return provided;
+  const urls = [];
+  for (const page of context.pages()) urls.push(page.url());
+  for (const worker of context.serviceWorkers()) urls.push(worker.url());
+  for (const url of urls) {
+    const match = /^chrome-extension:\/\/([^/]+)\//u.exec(url);
+    if (match) return match[1];
+  }
+  return '';
+}
+
+async function connect() {
+  const browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`);
+  const context = browser.contexts()[0];
+  return { browser, context };
+}
+
+(async () => {
+  // Phase 1: trigger a full extension reload (service worker + all pages) from an
+  // extension page so Chrome re-reads the freshly snapshotted runtime-dist.
+  let { browser, context } = await connect();
+  const extId = extensionIdFrom(context, process.env.EXT_ID);
+  if (!extId) {
+    await browser.close();
+    console.error('reattach: could not resolve the extension id from the live CDP targets.');
+    console.error('  Next: mm-harness launch --build   (clean build + relaunch)');
+    process.exit(1);
+  }
+
+  let page = context
+    .pages()
+    .find((candidate) => candidate.url().startsWith(`chrome-extension://${extId}/`));
+  if (!page) {
+    page = await context.newPage();
+    await page.goto(`chrome-extension://${extId}/home.html`, {
+      waitUntil: 'domcontentloaded',
+      timeout: 15000,
+    });
+  }
+  await page.evaluate(() => chrome.runtime.reload()).catch(() => {
+    // The reload tears the page context down; a rejected evaluate is expected.
+  });
+  await browser.close();
+
+  // Phase 2: wait for the extension to come back, then re-open the wallet and,
+  // when requested, a dapp tab. Chrome itself never restarted, so CDP stays up.
+  const deadline = Date.now() + settleMs;
+  let back = false;
+  while (Date.now() < deadline) {
+    try {
+      const probe = await connect();
+      const id = extensionIdFrom(probe.context, extId);
+      await probe.browser.close();
+      if (id) { back = true; break; }
+    } catch {
+      // CDP momentarily unavailable during reload; retry until the deadline.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  if (!back) {
+    console.error(`reattach: extension did not come back within ${settleMs}ms after reload.`);
+    console.error('  Next: mm-harness launch --build   (clean build + relaunch)');
+    process.exit(1);
+  }
+
+  ({ browser, context } = await connect());
+  let home = context
+    .pages()
+    .find(
+      (candidate) =>
+        candidate.url().startsWith(`chrome-extension://${extId}/`) &&
+        !candidate.url().includes('/sidepanel.html'),
+    );
+  if (!home) {
+    home = await context.newPage();
+    await home
+      .goto(`chrome-extension://${extId}/home.html`, { waitUntil: 'domcontentloaded', timeout: 15000 })
+      .catch(() => { /* wallet home is best-effort; the reload already applied */ });
+  }
+  if (startUrl) {
+    const dapp = context
+      .pages()
+      .find((candidate) => candidate.url().startsWith('http://') || candidate.url().startsWith('https://'));
+    const tab = dapp || (await context.newPage());
+    await tab
+      .goto(startUrl, { waitUntil: 'domcontentloaded', timeout: 20000 })
+      .catch(() => { /* dapp navigation is best-effort */ });
+  }
+  await browser.close();
+})().catch((error) => {
+  console.error(`reattach: ${error && error.message ? error.message : error}`);
+  console.error('  Next: mm-harness launch --build   (clean build + relaunch)');
+  process.exit(1);
+});
+NODE
+
+echo "[reattach] extension reloaded in place — no rebuild, no relaunch" >&2
+echo "  Next: mm-harness verify   (confirm the reloaded runtime)" >&2

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

@@ -178,6 +178,14 @@
       "inputs": "<status|open|close|toggle|cycle> --cdp-port --ext-id --agent-dir --settle-ms; env REPO, CDP_PORT, EXT_ID, SETTLE_MS, AGENT_DIR",
       "outputs": "status/progress on stdout; exit 0/1/2"
     },
+    {
+      "id": "extension/reattach",
+      "entry": "adapters/extension/reattach.sh",
+      "kind": "bash",
+      "purpose": "Reload a live extension slot in place: re-snapshot dist into the loaded runtime-dist, then reload the extension (service worker + pages) over CDP — no watcher stop, no Chrome kill.",
+      "inputs": "--target --cdp-port --watcher-port --start-url --ext-id --dist-dir --settle-ms; env CDP_PORT, WATCHER_PORT, EXTENSION_START_URL, EXT_ID",
+      "outputs": "progress on stderr; exit 0/1/2"
+    },
     {
       "id": "extension/pin-remote-flags",
       "entry": "adapters/extension/pin-remote-flags.cjs",
@@ -290,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",
@@ -298,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",
@@ -306,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",
@@ -331,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",
@@ -351,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/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