@deeeed/metamask-harness 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.5.1 - 2026-07-05
+
+Fresh-install hotfixes found in live validation of 0.5.0.
+
+### Fixed
+- **First launch on a provisioned slot targets the slot's own simulator** — the mobile resolution ladder now reads the `runway-provision.json` baseline (simulator name/udid, watcher port, slot id) when `agentic-runtime.json` doesn't exist yet, and boots that simulator. Previously a provisioned-but-unprepared slot degraded to the simctl `booted` alias, missed the installed dev client, and guessed the wrong Metro port.
+- **`call` works from published installs** — library actions load harness helpers through a dist-preferring bridge instead of importing `src/index.ts` (node refuses to type-strip `.ts` under `node_modules`). The bridge is deliberately narrow (paths + run-recording) to avoid an import cycle through `adapters.ts`.
+- **deps-not-ready guidance matches the caller's state** — on a checkout without node_modules the taught command now leads with `yarn install --immutable` (yarn cannot run scripts at all on a bare checkout), and always ends with the launch re-run.
+
+## Unreleased
+
+### Changed
+- **resolve-farmslot-ports is TypeScript-first** — pool/context/formula port resolution lives in self-contained `adapters/shared/resolve-farmslot-ports-core.mjs` (works from runner and injected overlay copies); `src/adapters/resolve-farmslot-ports.ts` re-exports it for `slot-ports.ts`. `resolve-farmslot-ports.mjs` is the node leaf; `resolve-farmslot-ports.sh` remains a thin bash-compat wrapper for sourced callers.
+
+## 0.5.0 - 2026-07-05
+Minor release: thin Runway provisioning (harness-owned slot provisioning with a shared artifact cache) plus compiled-dist packaging.
+### Added
+- **`mm-harness provision runway`** — provisions a mobile slot with exactly: resolve the latest Runway (expo-dev-build) artifact, download it ONCE into a shared machine cache (`~/.cache/metamask-harness/runway/<runId>/`, sha256+size integrity, corrupt entries re-downloaded, never a slot failure), create the simulator if missing, install the dev client on it. Zero yarn/deps/Metro — those stay dispatch-time (lazy, presence-authoritative readiness unchanged). `install --runway` is the overlay-path equivalent (covered by its own contract test). Baseline recorded so doctor reports provisioned-but-deps-pending as a normal state.
+- **Compiled `dist/` for published installs** — the npm tarball ships esbuild-compiled JS; `npm i -g` installs run the dist entry (~0.21s cold vs ~0.37s tsx). Source checkouts without `dist/` keep the tsx dev path; `bin/mm-harness` prefers dist when present. Packaging contract test (pack → global install → dist entry runs).
+### Changed
+- Runway provisioning callers (farm installer, mobile-farm `runway` prepare profile) delegate to the harness; the profile no longer runs a deps phase and a contract test enforces that.
+
 ## 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).
@@ -34,7 +56,18 @@ Minor release: the adapter-surface architecture plus the day's feature wave (0.3
 
 ## Unreleased
 
+### Added
+- Add `mm-harness provision` for thin mobile Runway artifact provisioning with a shared integrity-checked cache and simulator install path.
+- Add `mm-harness provision runway ios --resolve-only` to return Runway run/revision/artifact metadata without touching simulator, cache, download, install, or baseline state.
+- **Dist publish path** — `npm run build` compiles `src/` to `dist/`; `npm pack` / global install runs the compiled CLI entry (`dist/mm-harness-cli.js`) while a source checkout without `dist/` keeps the tsx+src dev path. Contracts: `packaging-dist-install`, `packaging-dev-checkout`.
+
+### Changed
+- **Leaf stderr hints use mm-harness verbs** — Metro/webpack compact-log prefixes, log-tail hints, and speed-ladder copy now point at `mm-harness logs`, `mm-harness doctor`, `mm-harness launch`, and `mm-harness install` instead of retired `recipe *` commands. Contract: `leaf-branding-retired`.
+
 ### Fixed
+- `mm-harness provision runway ios` now routes through the same Runway provisioning surface as `install --runway`, so overlay dispatch accepts the compatibility command instead of rejecting it as an unsupported harness action.
+- Runway provisioning now accepts farm context flags (`--slot`, `--watcher-port`, `--runtime-dir`), records slot/watcher/runtime-dir baselines correctly, ignores stale provision baselines unless the app is still installed on the simulator, and emits rerunnable `Next:` commands from the actual invocation.
+- Runway iOS artifact extraction now handles the live nested zip layout and app bundle names other than `MetaMask.app` while keeping the cached app directory integrity hash/size contract.
 - **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.

package/adapters/extension/inject.mjs

@@ -108,6 +108,8 @@ copyFile(path.join(runnerDir, 'adapters/extension/ensure-browser.sh'), path.join
 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-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/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));

package/adapters/extension/refresh-build.sh

@@ -97,7 +97,7 @@ elif command -v activate_repo_node >/dev/null 2>&1; then
     exit 1
   }
 else
-  echo "[refresh] activate-repo-node.sh missing from harness; run: recipe sync" >&2
+  echo "[refresh] activate-repo-node.sh missing from harness; run: mm-harness install" >&2
   exit 1
 fi
 
@@ -186,5 +186,5 @@ kill "$BUILD_PID" 2>/dev/null || true
 wait "$BUILD_PID" 2>/dev/null || true
 trap - EXIT
 
-echo "[refresh] Build refreshed and frozen — run: recipe reopen"
+echo "[refresh] Build refreshed and frozen — run: mm-harness launch"
 echo "[refresh] Log kept at: $LOG"

package/adapters/extension/start-watch.sh

@@ -82,7 +82,7 @@ elif command -v activate_repo_node >/dev/null 2>&1; then
     exit 1
   }
 else
-  echo "[recipe-harness] activate-repo-node.sh missing from harness; run: recipe sync" >&2
+  echo "[recipe-harness] activate-repo-node.sh missing from harness; run: mm-harness install" >&2
   exit 1
 fi
 if [ -z "$WATCHER_PORT" ]; then
@@ -233,7 +233,7 @@ for _lib in "$SCRIPT_DIR/lib" "$SCRIPT_DIR/../shared"; do
 done
 unset _lib
 echo "[recipe-harness] Starting yarn start (watcher-port=${WATCHER_PORT:-default})"
-echo "[recipe-harness] compact build view - full log: $watch_log (recipe logs --full)"
+echo "[recipe-harness] compact build view - full log: $watch_log (mm-harness logs --full)"
 started_pid=""
 # Launch the watcher detached writing to the log; the tmux window is a read-only tail viewer.
 path_prefix="${REPO_NODE_PATH_PREFIX:-}"

package/adapters/manifest.json

@@ -308,12 +308,28 @@
     },
     {
       "id": "lib/resolve-farmslot-ports",
-      "entry": "adapters/shared/resolve-farmslot-ports.sh",
-      "kind": "lib",
+      "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_extension_runtime_ports <repo>",
+      "inputs": "resolve-farmslot-ports.mjs resolve_extension_runtime_ports <repo>",
       "outputs": "CDP_PORT / WATCHER_PORT / SLOT_ID lines on stdout"
     },
+    {
+      "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"
+    },
+    {
+      "id": "lib/resolve-farmslot-ports-sh",
+      "entry": "adapters/shared/resolve-farmslot-ports.sh",
+      "kind": "lib",
+      "purpose": "Bash-compat sourced wrapper over resolve-farmslot-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/sync-wallet-fixture",
       "entry": "adapters/shared/sync-wallet-fixture.sh",

package/adapters/mobile/start-metro.sh

@@ -102,7 +102,7 @@ CLEAR_SUFFIX=""
 
 printf 'Starting Metro on port %s (workers=%s%s)\n' \
   "$PORT" "$METRO_WORKERS" "${CLEAR:+, clear}" >&2
-printf '(Full log: %s — recipe logs | recipe logs --full)\n' "$LOG_FILE" >&2
+printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FILE" >&2
 
 # Metro runs detached, writing to the log. The tmux window is a read-only tail.
 (

package/adapters/mobile/verify.sh

@@ -296,7 +296,7 @@ if (checked === 0) {
   const parts = [];
   if (drifted.length) parts.push('behind runner: ' + drifted.join(', '));
   if (missing.length) parts.push('absent in repo: ' + missing.join(', '));
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun mm-harness install --force-overlay or recipe sync to refresh the in-repo HUD/AgenticService from the runner' }));
+  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun mm-harness install --force-overlay or mm-harness fixtures sync to refresh the in-repo HUD/AgenticService from the runner' }));
 } else {
   process.stdout.write(JSON.stringify({ name, status: 'pass' }));
 }

package/adapters/shared/activate-repo-node.sh

@@ -134,7 +134,7 @@ activate_repo_node() {
 require_repo_node() {
   local target="${1:-.}"
   if ! command -v activate_repo_node >/dev/null 2>&1; then
-    echo "[env] activate-repo-node.sh is not sourced; reinstall the harness (recipe sync)" >&2
+    echo "[env] activate-repo-node.sh is not sourced; reinstall the harness (mm-harness install)" >&2
     return 1
   fi
   activate_repo_node "$target" || {

package/adapters/shared/cli-ux.sh

@@ -67,7 +67,7 @@ recipe_instant_hint() {
   local message="$1"
   [ "${RECIPE_PROGRESS_JSON:-}" = "1" ] && return 0
   [ -t 2 ] || return 0
-  local prefix="${RECIPE_CLI_PREFIX:-recipe}"
+  local prefix="${RECIPE_CLI_PREFIX:-mm-harness}"
   printf '%s: %s\n' \
     "$(recipe_color label "$prefix")" \
     "$(recipe_color dim "$message")" >&2
@@ -92,7 +92,7 @@ recipe_done() {
 recipe_failure_playbook() {
   local verb="$1" reason="$2"
   shift 2
-  local log_path="" artifact="" prefix="${RECIPE_CLI_PREFIX:-recipe}"
+  local log_path="" artifact="" prefix="${RECIPE_CLI_PREFIX:-mm-harness}"
   while [ "$#" -gt 0 ]; do
     case "$1" in
       --log) log_path="$2"; shift 2 ;;
@@ -106,31 +106,32 @@ recipe_failure_playbook() {
     "$(recipe_color cmd "$verb")" \
     "$(recipe_color err failed)" \
     "$(recipe_color warn "$reason")" >&2
-  printf '%s\n' "$(recipe_color label next:)" >&2
+  printf '%s\n' "$(recipe_color label "next:")" >&2
   case "$verb" in
     rebuild|up|watch)
-      printf '  %s\n' "$(recipe_color cmd "$prefix logs")" >&2
-      printf '  %s\n' "$(recipe_color cmd "$prefix logs --full")" >&2
-      printf '  %s\n' "$(recipe_color cmd "$prefix doctor")" >&2
-      printf '  %s\n' "$(recipe_color cmd "$prefix sync")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness logs")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness logs --full")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness doctor")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness install")" >&2
       ;;
     refresh)
-      printf '  %s\n' "$(recipe_color cmd "$prefix watch")" >&2
-      printf '  %s\n' "$(recipe_color cmd "$prefix logs")" >&2
-      printf '  %s\n' "$(recipe_color cmd "$prefix rebuild")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness launch")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness logs")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness launch --build")" >&2
       ;;
     metro|ios|android|setup-wallet)
-      printf '  %s\n' "$(recipe_color cmd "$prefix logs")" >&2
-      printf '  %s\n' "$(recipe_color cmd "$prefix logs --full")" >&2
-      printf '  %s\n' "$(recipe_color cmd "$prefix up")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness logs")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness logs --full")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness launch")" >&2
       ;;
     *)
-      printf '  %s\n' "$(recipe_color cmd "$prefix status")" >&2
-      printf '  %s\n' "$(recipe_color cmd "$prefix logs")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness doctor")" >&2
+      printf '  %s\n' "$(recipe_color cmd "mm-harness logs")" >&2
       ;;
   esac
   [ -n "$log_path" ] && printf '%s\n' "$(recipe_color path "log: $log_path")" >&2
   [ -n "$artifact" ] && printf '%s\n' "$(recipe_color path "artifact: $artifact")" >&2
+  return 0
 }
 
 recipe_check_harness_stale() {
@@ -152,12 +153,12 @@ recipe_check_harness_stale() {
 
 recipe_warn_harness_stale() {
   local adapter="$1" root="$2" harness_root="$3" runner_root="$4"
-  local prefix="${RECIPE_CLI_PREFIX:-recipe}"
+  local prefix="${RECIPE_CLI_PREFIX:-mm-harness}"
   if recipe_check_harness_stale "$adapter" "$root" "$harness_root" "$runner_root"; then
     printf '%s: %s - run: %s\n' \
       "$(recipe_color label "$prefix")" \
       "$(recipe_color warn 'harness scripts are stale')" \
-      "$(recipe_color cmd "$prefix sync")" >&2
+      "$(recipe_color cmd "mm-harness install")" >&2
     return 1
   fi
   return 0
@@ -190,7 +191,7 @@ recipe_try_farmslot_fixture_sync() {
 recipe_sync_wallet_fixture() {
   local root="$1" runtime_dir="$2" cdp_port="${3:-}" seed_script="${4:-}" farmslot_slot="${5:-}"
   local canonical="$root/$runtime_dir/wallet-fixture.json"
-  local candidate resolved prefix="${RECIPE_CLI_PREFIX:-recipe}"
+  local candidate resolved prefix="${RECIPE_CLI_PREFIX:-mm-harness}"
 
   mkdir -p "$root/$runtime_dir"
   if [ -f "$canonical" ]; then
@@ -239,10 +240,10 @@ recipe_sync_wallet_fixture() {
 recipe_speed_ladder() {
   cat >&2 <<'EOF'
 Speed ladder:
-  FAST (seconds):  recipe watch -> recipe refresh
-  SLOW (minutes):  recipe rebuild
-  INSPECT:         recipe status | recipe ports | recipe logs | recipe logs --full | recipe debug
-  PROOF:           recipe run <recipe.json>
-  SYNC CONTEXT:    recipe sync
+  FAST (seconds):  mm-harness launch (extension quick relaunch)
+  SLOW (minutes):  mm-harness launch --build
+  INSPECT:         mm-harness doctor | mm-harness logs | mm-harness logs --full | mm-harness debug
+  PROOF:           mm-harness run <recipe.json>
+  SYNC CONTEXT:    mm-harness fixtures sync
 EOF
 }

package/adapters/shared/log-tui.mjs

@@ -153,9 +153,9 @@ function readNewContent(file, offset) {
 
 function renderHeader(label, logPath, title) {
   return [
-    `${color('label', 'recipe', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('bold', title || label, { stream: process.stderr })}`,
-    `${color('label', 'recipe', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('path', `full log: ${logPath}`, { stream: process.stderr })}`,
-    `${color('label', 'recipe', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('comment', 'full stream: recipe logs --full', { stream: process.stderr })}`,
+    `${color('label', 'mm-harness', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('bold', title || label, { stream: process.stderr })}`,
+    `${color('label', 'mm-harness', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('path', `full log: ${logPath}`, { stream: process.stderr })}`,
+    `${color('label', 'mm-harness', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('comment', 'full stream: mm-harness logs --full', { stream: process.stderr })}`,
     '',
   ];
 }
@@ -232,7 +232,7 @@ async function watchLog(options) {
       renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
       if (mode !== 'quiet') {
         const elapsed = Math.round((Date.now() - started) / 1000);
-        process.stderr.write(`${color('label', 'recipe', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('ok', `build complete (${elapsed}s)`, { stream: process.stderr })}\n`);
+        process.stderr.write(`${color('label', 'mm-harness', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('ok', `build complete (${elapsed}s)`, { stream: process.stderr })}\n`);
       }
       return 0;
     }

package/adapters/shared/open-debug.mjs

@@ -221,7 +221,7 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
       error: 'cdp-unreachable',
       inspectUrl,
       configureHint,
-      hint: `Start the extension runtime first (recipe reopen). Then open chrome://inspect and add ${configureHint}.`,
+      hint: `Start the extension runtime first (mm-harness launch). Then open chrome://inspect and add ${configureHint}.`,
       detail: error instanceof Error ? error.message : String(error),
     };
   }

package/adapters/shared/resolve-farmslot-ports-core.mjs

@@ -0,0 +1,196 @@
+// Farmslot pool + slot-suffix port resolution — pure JS for runner and overlay leaves.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const coreDir = path.dirname(fileURLToPath(import.meta.url));
+
+function pathDefault(key) {
+  for (const candidate of [
+    path.join(coreDir, 'path-defaults.json'),
+    path.join(coreDir, '../../adapters/shared/path-defaults.json'),
+  ]) {
+    if (!fs.existsSync(candidate)) continue;
+    const value = JSON.parse(fs.readFileSync(candidate, 'utf8'))[key];
+    if (value) return value;
+  }
+  throw new Error(`Missing path default: ${key}`);
+}
+
+function recipeRuntimeDir() {
+  return process.env.RECIPE_RUNTIME_DIR || pathDefault('recipeRuntimeDir');
+}
+
+export function formatKvLines(kv) {
+  const lines = [];
+  if (kv.CDP_PORT !== undefined) lines.push(`CDP_PORT=${kv.CDP_PORT}`);
+  if (kv.WATCHER_PORT !== undefined) lines.push(`WATCHER_PORT=${kv.WATCHER_PORT}`);
+  if (kv.SLOT_ID) lines.push(`SLOT_ID=${kv.SLOT_ID}`);
+  if (kv.IOS_SIMULATOR) lines.push(`IOS_SIMULATOR=${kv.IOS_SIMULATOR}`);
+  return lines.length ? `${lines.join('\n')}\n` : '';
+}
+
+export function realRepoPath(repo) {
+  if (!repo) return null;
+  try {
+    return fs.realpathSync(repo);
+  } catch {
+    return null;
+  }
+}
+
+export function inferSlotSuffix(repo) {
+  const base = path.basename(repo);
+  const m = /-(\d+)$/u.exec(base);
+  return m ? m[1] : null;
+}
+
+function scoreSlot(slot, slotSuffix) {
+  const resources = slot.resources ?? {};
+  const cdp = resources.browser?.cdp_port;
+  const port = resources['dev-server']?.port;
+  const session = slot.session ?? '';
+  const slotId = slot.id ?? '';
+  let score = 0;
+  if (cdp !== undefined) score += 100;
+  if (port !== undefined) score += 10;
+  if (slotSuffix) {
+    if (session === `mme-${slotSuffix}`) score += 50;
+    if (slotId.endsWith(`mme-${slotSuffix}`) || slotId.includes(`-mme-${slotSuffix}`)) score += 40;
+  }
+  if (!slotId.toLowerCase().includes('demo')) score += 5;
+  return [score, cdp, port, slotId];
+}
+
+export function resolveFarmslotPortsByRepo(repo) {
+  const realRepo = realRepoPath(repo);
+  if (!realRepo) return null;
+
+  const slotSuffix = inferSlotSuffix(realRepo);
+  const roots = [];
+  if (process.env.FARMSLOT_ROOT) roots.push(process.env.FARMSLOT_ROOT);
+  roots.push(path.join(os.homedir(), 'dev', 'farmslot'));
+
+  for (const root of roots) {
+    if (!root || !fs.existsSync(path.join(root, 'pool'))) continue;
+    const poolDir = path.join(root, 'pool');
+    let best = null;
+
+    for (const name of fs.readdirSync(poolDir).sort()) {
+      if (!name.endsWith('.json') || name.includes('.bak.')) continue;
+      let data;
+      try {
+        data = JSON.parse(fs.readFileSync(path.join(poolDir, name), 'utf8'));
+      } catch {
+        continue;
+      }
+      for (const slot of data.slots ?? []) {
+        const slotRepo = slot.repo ?? '';
+        if (!slotRepo) continue;
+        let slotReal;
+        try {
+          slotReal = fs.realpathSync(slotRepo);
+        } catch {
+          continue;
+        }
+        if (slotReal !== realRepo) continue;
+        const scored = scoreSlot(slot, slotSuffix);
+        if (!best || scored[0] > best[0]) best = scored;
+      }
+    }
+
+    if (best) {
+      const [, cdp, port, slotId] = best;
+      return formatKvLines({
+        ...(cdp !== undefined ? { CDP_PORT: cdp } : {}),
+        ...(port !== undefined ? { WATCHER_PORT: port } : {}),
+        ...(slotId ? { SLOT_ID: slotId } : {}),
+      });
+    }
+  }
+  return null;
+}
+
+export function resolveDefaultExtensionPorts(repo) {
+  const n = inferSlotSuffix(repo);
+  if (!n) return null;
+  return formatKvLines({
+    CDP_PORT: 6660 + Number(n),
+    WATCHER_PORT: 9010 + Number(n),
+    SLOT_ID: `local-extension-${n}`,
+  });
+}
+
+export function resolveExtensionRuntimePorts(repo) {
+  return resolveFarmslotPortsByRepo(repo) ?? resolveDefaultExtensionPorts(repo) ?? '';
+}
+
+export function resolveMobileSlotDefaults(repo) {
+  const n = inferSlotSuffix(repo);
+  if (!n) return null;
+  return formatKvLines({
+    WATCHER_PORT: 8060 + Number(n),
+    IOS_SIMULATOR: `mm-${n}`,
+    SLOT_ID: `local-mobile-${n}`,
+  });
+}
+
+export function resolveMobileRuntimeContext(repo) {
+  const ctxPath = path.join(repo, recipeRuntimeDir(), 'agentic-runtime.json');
+  if (fs.existsSync(ctxPath)) {
+    try {
+      const c = JSON.parse(fs.readFileSync(ctxPath, 'utf8'));
+      if (c.simulator || c.metroPort) {
+        return formatKvLines({
+          ...(c.metroPort !== undefined ? { WATCHER_PORT: c.metroPort } : {}),
+          ...(c.simulator ? { IOS_SIMULATOR: c.simulator } : {}),
+          ...(c.slotId ? { SLOT_ID: c.slotId } : {}),
+        });
+      }
+    } catch {
+      /* unreadable context falls through to the provision baseline */
+    }
+  }
+  return resolveMobileProvisionBaseline(repo);
+}
+
+// A provisioned-but-unprepared slot has no agentic-runtime.json yet, but the
+// provision baseline records the same authoritative simulator/port identity —
+// without it, a fresh slot's first launch degrades to the simctl `booted`
+// alias and misses the installed dev client entirely.
+function resolveMobileProvisionBaseline(repo) {
+  const basePath = path.join(repo, recipeRuntimeDir(), 'runway-provision.json');
+  if (!fs.existsSync(basePath)) return null;
+  try {
+    const c = JSON.parse(fs.readFileSync(basePath, 'utf8'));
+    const simulator = c.simulator?.name || c.simulator?.udid;
+    if (!simulator && c.watcherPort === undefined) return null;
+    return formatKvLines({
+      ...(c.watcherPort !== undefined ? { WATCHER_PORT: c.watcherPort } : {}),
+      ...(simulator ? { IOS_SIMULATOR: simulator } : {}),
+      ...(c.slotId ? { SLOT_ID: c.slotId } : {}),
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function resolveMobileRuntimePorts(repo) {
+  return (
+    resolveMobileRuntimeContext(repo)
+    ?? resolveFarmslotPortsByRepo(repo)
+    ?? resolveMobileSlotDefaults(repo)
+    ?? ''
+  );
+}
+
+export const cliFns = {
+  resolve_farmslot_ports_by_repo: resolveFarmslotPortsByRepo,
+  resolve_default_extension_ports: resolveDefaultExtensionPorts,
+  resolve_extension_runtime_ports: (repo) => resolveExtensionRuntimePorts(repo) || null,
+  resolve_mobile_runtime_context: resolveMobileRuntimeContext,
+  resolve_mobile_slot_defaults: resolveMobileSlotDefaults,
+  resolve_mobile_runtime_ports: (repo) => resolveMobileRuntimePorts(repo) || null,
+};

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

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Node leaf for port resolution — self-contained for runner and injected overlay copies.
+
+import { cliFns } from './resolve-farmslot-ports-core.mjs';
+
+const [, , fn, repo] = process.argv;
+if (!fn || fn === '-h' || fn === '--help') {
+  process.stderr.write('Usage: resolve-farmslot-ports.mjs <fn> <repo>\n');
+  process.exit(fn ? 0 : 2);
+}
+
+const handler = cliFns[fn];
+if (!handler) {
+  process.stderr.write(`resolve-farmslot-ports: unknown fn: ${fn}\n`);
+  process.exit(2);
+}
+
+const out = handler(repo ?? '.');
+if (!out?.trim()) process.exit(1);
+process.stdout.write(out.endsWith('\n') ? out : `${out}\n`);