@deeeed/metamask-harness 0.17.5 → 0.18.0

package/adapters/mobile/launch-console-forwarder.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const args = { port: '', out: '', err: '' };
+for (let i = 2; i < process.argv.length; i += 1) {
+  const key = process.argv[i];
+  if (key === '--port') args.port = process.argv[++i] || '';
+  else if (key === '--out') args.out = process.argv[++i] || '';
+  else if (key === '--err') args.err = process.argv[++i] || '';
+  else if (key === '--help' || key === '-h') {
+    process.stdout.write('Usage: launch-console-forwarder.cjs --port <port> --out <app-log> --err <error-log>\n');
+    process.exit(0);
+  } else {
+    process.stderr.write(`launch-console-forwarder: unknown arg: ${key}\n`);
+    process.exit(2);
+  }
+}
+
+if (!args.port || !args.out || !args.err) {
+  process.stderr.write('launch-console-forwarder: --port, --out, and --err are required\n');
+  process.exit(2);
+}
+
+const forwarder = path.join(__dirname, 'bridge-runtime', 'console-forwarder.cjs');
+const errFd = fs.openSync(args.err, 'a');
+try {
+  const child = spawn(process.execPath, [forwarder, '--port', args.port, '--out', args.out], {
+    detached: true,
+    stdio: ['ignore', errFd, errFd],
+  });
+  child.unref();
+  process.stdout.write(`${child.pid}\n`);
+} finally {
+  fs.closeSync(errFd);
+}

package/adapters/mobile/open-device.sh

@@ -13,6 +13,7 @@
 #   --simulator <udid|name|"booted">    iOS simulator (default: IOS_SIMULATOR env, else "booted")
 #   --adb-serial <serial>               Android device serial (default: ADB_SERIAL env)
 #   --preflight-mode fast|auto|rebuild-native|clean  (default: fast; env MOBILE_PREFLIGHT_MODE)
+#   --ui-only                           iOS only: ensure Simulator.app is visible; do not relaunch the app
 # Outputs:
 #   Progress on stderr; exit 0 pass; 1 open failed; 2 bad args.
 #
@@ -25,6 +26,7 @@ SIMULATOR="${IOS_SIMULATOR:-${SIM_UDID:-booted}}"
 ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
 PREFLIGHT_MODE="${MOBILE_PREFLIGHT_MODE:-fast}"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+UI_ONLY=false
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -34,10 +36,11 @@ while [ "$#" -gt 0 ]; do
     --adb-serial)     ADB_SERIAL_ARG="$2"; shift 2 ;;
     --preflight-mode) PREFLIGHT_MODE="$2"; shift 2 ;;
     --port)           PORT="$2"; shift 2 ;;
+    --ui-only)        UI_ONLY=true; shift ;;
     -h|--help)
       printf 'Usage: open-device.sh [--platform ios|android] [--target <dir>]\n'
       printf '  [--simulator <udid|name|booted>] [--adb-serial <serial>]\n'
-      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>]\n'
+      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>] [--ui-only]\n'
       exit 0
       ;;
     *) printf 'open-device: unknown arg: %s\n' "$1" >&2; exit 2 ;;
@@ -48,6 +51,10 @@ case "$PLATFORM" in
   ios|android) ;;
   *) printf 'open-device: --platform must be ios or android (got: %s)\n' "$PLATFORM" >&2; exit 2 ;;
 esac
+if $UI_ONLY && [ "$PLATFORM" != "ios" ]; then
+  printf 'open-device: --ui-only is supported only for ios.\n' >&2
+  exit 2
+fi
 
 TARGET="$(cd "$TARGET" && pwd)"
 
@@ -149,19 +156,46 @@ boot_simulator_if_needed() {
   xcrun simctl bootstatus "$udid" -b >/dev/null
 }
 
-show_simulator() {
+simulator_ui_running() {
+  pgrep -x Simulator >/dev/null 2>&1
+}
+
+open_simulator_in_background_if_needed() {
   local target="$1" udid=""
+  [ "${MM_HARNESS_SHOW_SIMULATOR:-1}" != "0" ] || return 0
+  simulator_ui_running && return 0
+  printf 'Opening Simulator UI in the background\n' >&2
   if [ "$target" = "booted" ]; then
-    printf 'Opening Simulator UI\n' >&2
-    open -a Simulator >/dev/null 2>&1 || true
+    open -g -a Simulator >/dev/null 2>&1 || {
+      printf 'open-device: failed to open Simulator UI.\n' >&2
+      return 1
+    }
   else
     udid="$(sim_udid_for_target "$target")"
     if [ -n "$udid" ]; then
-      open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+      open -g -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || {
+        printf 'open-device: failed to open Simulator UI for %s.\n' "$target" >&2
+        return 1
+      }
     else
-      open -a Simulator >/dev/null 2>&1 || true
+      open -g -a Simulator >/dev/null 2>&1 || {
+        printf 'open-device: failed to open Simulator UI.\n' >&2
+        return 1
+      }
     fi
   fi
+}
+
+focus_simulator() {
+  local target="$1" udid=""
+  if [ "$target" != "booted" ]; then
+    udid="$(sim_udid_for_target "$target")"
+  fi
+  if [ -n "$udid" ]; then
+    open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+  else
+    open -a Simulator >/dev/null 2>&1 || true
+  fi
   osascript -e 'tell application "Simulator" to activate' >/dev/null 2>&1 || true
 }
 
@@ -220,8 +254,12 @@ if [ "$PLATFORM" = "ios" ]; then
   DEV_CLIENT_SCHEME="${IOS_DEV_CLIENT_SCHEME:-expo-metamask}"
 
   boot_simulator_if_needed "$SIM_TARGET" || exit 1
+  open_simulator_in_background_if_needed "$SIM_TARGET" || exit 1
   if [ "${MM_HARNESS_FOCUS_SIMULATOR:-0}" = "1" ]; then
-    show_simulator "$SIM_TARGET"
+    focus_simulator "$SIM_TARGET"
+  fi
+  if $UI_ONLY; then
+    exit 0
   fi
 
   LAUNCHED=false

package/adapters/mobile/start-console-forwarder.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Ensure one runner-owned CDP console forwarder is alive for this Mobile slot.
+set -uo pipefail
+
+TARGET="$PWD"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+QUIET=false
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) [ "$#" -ge 2 ] || { echo "Missing value for --target" >&2; exit 2; }; TARGET="$2"; shift 2 ;;
+    --port)   [ "$#" -ge 2 ] || { echo "Missing value for --port" >&2; exit 2; }; PORT="$2"; shift 2 ;;
+    --quiet)  QUIET=true; shift ;;
+    -h|--help)
+      printf 'Usage: start-console-forwarder.sh [--target <dir>] [--port <port>] [--quiet]\n'
+      exit 0
+      ;;
+    *) printf 'start-console-forwarder: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+[ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || exit 0
+TARGET="$(cd "$TARGET" && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../shared/harness-path.sh"
+LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
+FORWARDER="$SCRIPT_DIR/bridge-runtime/console-forwarder.cjs"
+PID_FILE="$LOG_DIR/console-forwarder.pid"
+APP_LOG_FILE="$LOG_DIR/app-console.log"
+
+{ [ -f "$FORWARDER" ] && command -v node >/dev/null 2>&1; } || exit 0
+mkdir -p "$LOG_DIR"
+
+# One debugger owns a React Native page. Reap any collector for this Metro port,
+# including one left by an older globally installed harness.
+while read -r pid cmd; do
+  case "$cmd" in
+    *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
+      kill "$pid" 2>/dev/null || true
+      ;;
+  esac
+done < <(ps -axo pid=,command= 2>/dev/null || true)
+
+if [ -f "$PID_FILE" ]; then
+  old_pid="$(cat "$PID_FILE" 2>/dev/null || true)"
+  if [ -n "$old_pid" ]; then
+    case "$(ps -p "$old_pid" -o command= 2>/dev/null)" in
+      *console-forwarder.cjs*) kill "$old_pid" 2>/dev/null || true ;;
+    esac
+  fi
+  rm -f "$PID_FILE"
+fi
+
+: > "$APP_LOG_FILE"
+pid="$(node "$SCRIPT_DIR/launch-console-forwarder.cjs" \
+  --port "$PORT" \
+  --out "$APP_LOG_FILE" \
+  --err "$LOG_DIR/console-forwarder.err")" || exit 1
+printf '%s\n' "$pid" > "$PID_FILE"
+
+# A successful launch must never claim capture when the collector died at boot.
+sleep 0.1
+if ! kill -0 "$pid" 2>/dev/null; then
+  rm -f "$PID_FILE"
+  printf 'start-console-forwarder: collector exited during startup; inspect %s\n' \
+    "$LOG_DIR/console-forwarder.err" >&2
+  exit 1
+fi
+[ "$QUIET" = true ] || printf 'Device console → app-console.log (CDP forwarder pid %s)\n' "$pid" >&2

package/adapters/mobile/start-metro.sh

@@ -77,45 +77,6 @@ default_metro_workers() {
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/tmux-viewer.sh"
 
-# Bridgeless RN gates console→Metro forwarding on console._isPolyfilled, which is
-# false with the Hermes native console — device logs (incl. DevLogger) never reach
-# metro.log. The forwarder attaches over CDP and appends them back. Kill switch:
-# METAMASK_RECIPE_CONSOLE_FORWARD=0.
-start_console_forwarder() {
-  local forwarder="$SCRIPT_DIR/bridge-runtime/console-forwarder.cjs"
-  local fwd_pid_file="$LOG_DIR/console-forwarder.pid"
-  [ "${METAMASK_RECIPE_CONSOLE_FORWARD:-1}" != "0" ] || return 0
-  { [ -f "$forwarder" ] && command -v node >/dev/null 2>&1; } || return 0
-  # Only one debugger can own a React Native page. Reap any forwarder already
-  # attached to this Metro port, even if it was launched from another checkout or
-  # package install path and therefore does not own this runtime dir's pid file.
-  local pid cmd
-  while read -r pid cmd; do
-    case "$cmd" in
-      *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
-        kill "$pid" 2>/dev/null || true
-        ;;
-    esac
-  done < <(ps -axo pid=,command= 2>/dev/null || true)
-  if [ -f "$fwd_pid_file" ]; then
-    local old_fwd
-    old_fwd="$(cat "$fwd_pid_file" 2>/dev/null || true)"
-    # A crash can leave a stale pid file and the OS can recycle the pid for an
-    # unrelated process — only kill when the command line is really ours.
-    if [ -n "$old_fwd" ]; then
-      case "$(ps -p "$old_fwd" -o command= 2>/dev/null)" in
-        *console-forwarder.cjs*) kill "$old_fwd" 2>/dev/null ;;
-      esac
-    fi
-    rm -f "$fwd_pid_file"
-  fi
-  nohup node "$forwarder" --port "$PORT" --out "$LOG_FILE" \
-    </dev/null >> "$LOG_DIR/console-forwarder.err" 2>&1 &
-  echo "$!" > "$fwd_pid_file"
-  disown 2>/dev/null || true
-  printf 'Device console → metro.log (CDP forwarder pid %s)\n' "$(cat "$fwd_pid_file")" >&2
-}
-
 write_metro_runner() {
   local runner="$1"
   local clear_flag=""
@@ -179,7 +140,6 @@ if metro_ready; then
     rm -f "$PID_FILE"
   elif metro_listener_valid; then
     printf 'Metro already running and valid on port %s\n' "$PORT" >&2
-    start_console_forwarder
     exit 0
   else
     stop_metro_listener || exit 1
@@ -269,7 +229,6 @@ if [ "$READY" = true ]; then
   first_ready_pid="${ready_pids%% *}"
   [ -z "$first_ready_pid" ] || printf '%s\n' "$first_ready_pid" > "$PID_FILE"
   printf 'Metro ready on port %s\n' "$PORT" >&2
-  start_console_forwarder
   printf '  Next: mm-harness logs  (tail Metro)\n' >&2
   exit 0
 fi

package/adapters/mobile/verify.sh

@@ -261,76 +261,19 @@ check_file "package.json"
 check_file "app/dev-tools/AgenticService/AgenticService.ts"
 
 if ! grep -q "AgenticService.install" "$TARGET/app/core/NavigationService/NavigationService.ts" 2>/dev/null; then
-  checks+=("{\"name\":\"NavigationService patch\",\"status\":\"fail\"}")
+  checks+=("{\"name\":\"NavigationService agentic bridge\",\"status\":\"fail\"}")
   status="fail"
 else
-  checks+=("{\"name\":\"NavigationService patch\",\"status\":\"pass\"}")
+  checks+=("{\"name\":\"NavigationService agentic bridge\",\"status\":\"pass\"}")
 fi
 
 if ! grep -q "AgentStepHud" "$TARGET/app/components/Nav/App/App.tsx" 2>/dev/null; then
-  checks+=("{\"name\":\"App AgentStepHud patch\",\"status\":\"fail\"}")
+  checks+=("{\"name\":\"App AgentStepHud\",\"status\":\"fail\"}")
   status="fail"
 else
-  checks+=("{\"name\":\"App AgentStepHud patch\",\"status\":\"pass\"}")
+  checks+=("{\"name\":\"App AgentStepHud\",\"status\":\"pass\"}")
 fi
 
-# Drift detection (read-only): compare the in-repo AgenticService/HUD against
-# the resolved runner overlay, not a runner-owned copy. The runner is the only
-# MetaMask-aware source of truth for Mobile injection.
-overlay_drift_check="$(
-  HARNESS_DIR_FOR_DRIFT="$HARNESS_DIR" TARGET_FOR_DRIFT="$TARGET" node <<'NODE'
-const fs = require('fs');
-const path = require('path');
-const name = 'agentic overlay matches runner (HUD freshness)';
-const harnessDir = process.env.HARNESS_DIR_FOR_DRIFT;
-const targetDir = path.join(process.env.TARGET_FOR_DRIFT, 'app', 'dev-tools', 'AgenticService');
-function readTrimmed(file) {
-  try { return fs.readFileSync(file, 'utf8').trim(); } catch { return ''; }
-}
-let runnerDir = readTrimmed(path.join(harnessDir, 'runner', '.runner-source'));
-if (!runnerDir) {
-  try {
-    const manifest = JSON.parse(fs.readFileSync(path.join(harnessDir, 'manifest.json'), 'utf8'));
-    runnerDir = manifest && manifest.source && manifest.source.runnerDir || '';
-  } catch {}
-}
-if (!runnerDir) {
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner source unavailable; overlay freshness compare skipped' }));
-  process.exit(0);
-}
-const overlayDir = path.join(runnerDir, 'adapters', 'mobile', 'overlay', 'app', 'dev-tools', 'AgenticService');
-let checked = 0;
-const drifted = [];
-const missing = [];
-try {
-  for (const entry of fs.readdirSync(overlayDir)) {
-    if (!entry.endsWith('.patch')) continue;
-    if (/\.test\./u.test(entry)) continue;
-    const base = entry.slice(0, -'.patch'.length);
-    const targetFile = path.join(targetDir, base);
-    if (!fs.existsSync(targetFile)) { missing.push(base); continue; }
-    checked += 1;
-    if (fs.readFileSync(path.join(overlayDir, entry), 'utf8') !== fs.readFileSync(targetFile, 'utf8')) {
-      drifted.push(base);
-    }
-  }
-} catch (error) {
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner overlay compare skipped: ' + String((error && error.message) || error) }));
-  process.exit(0);
-}
-if (drifted.length || missing.length) {
-  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 mm-harness fixtures sync to refresh the in-repo HUD/AgenticService from the runner' }));
-} else if (checked === 0) {
-  process.stdout.write(JSON.stringify({ name, status: 'pass' }));
-} else {
-  process.stdout.write(JSON.stringify({ name, status: 'pass' }));
-}
-NODE
-)"
-checks+=("$overlay_drift_check")
 run_with_timeout() {
   local log_path="$1"
   local timeout_s="$2"
@@ -386,9 +329,21 @@ JSON
 
 ensure_live_runtime() {
   local device_target="$1"
-  if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log" "$device_target"; then
-    return 0
-  fi
+  local attempt
+  for attempt in 1 2 3 4 5; do
+    if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log" "$device_target"; then
+      return 0
+    fi
+    # A freshly booted simulator can expose its Metro bridge just before
+    # `simctl list devices booted` publishes the device. Bound that launch→verify
+    # race instead of reporting a false DEVICE_NOT_FOUND immediately.
+    if [ "$attempt" -lt 5 ] && grep -q '"code"[[:space:]]*:[[:space:]]*"DEVICE_NOT_FOUND"' "$ARTIFACTS/logs/app-status-precheck.log"; then
+      echo "Waiting for Mobile device discovery (${attempt}/5): ${device_target:-configured target}" >&2
+      sleep 1
+      continue
+    fi
+    break
+  done
   if [ "$AUTO_START" = true ]; then
     cat >&2 <<'EOF'
 Mobile auto-start is not allowed from product-local scripts. Start or prepare the app through the runner/slot runtime, then rerun verify with --no-auto-start.

package/adapters/mobile/wait-for-bridge.sh

@@ -24,10 +24,10 @@ REQUIRE_PLATFORM=""
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
-    --target)     TARGET="$2"; shift 2 ;;
-    --port)       PORT="$2"; shift 2 ;;
-    --max-polls)  MAX_POLLS="$2"; shift 2 ;;
-    --platform)   REQUIRE_PLATFORM="$2"; shift 2 ;;
+    --target)     [ "$#" -ge 2 ] || { echo "Missing value for --target" >&2; exit 2; }; TARGET="$2"; shift 2 ;;
+    --port)       [ "$#" -ge 2 ] || { echo "Missing value for --port" >&2; exit 2; }; PORT="$2"; shift 2 ;;
+    --max-polls)  [ "$#" -ge 2 ] || { echo "Missing value for --max-polls" >&2; exit 2; }; MAX_POLLS="$2"; shift 2 ;;
+    --platform)   [ "$#" -ge 2 ] || { echo "Missing value for --platform" >&2; exit 2; }; REQUIRE_PLATFORM="$2"; shift 2 ;;
     -h|--help)
       printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>] [--platform ios|android]\n'
       exit 0
@@ -36,7 +36,12 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
-TARGET="$(cd "$TARGET" && pwd)"
+case "$MAX_POLLS" in
+  ''|*[!0-9]*) echo "wait-for-bridge: --max-polls must be an integer of at least 2." >&2; exit 2 ;;
+esac
+[ "$MAX_POLLS" -ge 2 ] || { echo "wait-for-bridge: --max-polls must be at least 2 for stable readiness." >&2; exit 2; }
+
+TARGET="$(cd "$TARGET" && pwd -P)"
 
 # The matcher reads the required platform from the environment so the value survives
 # into the node subprocess that runs the shared matcher against the status output.
@@ -128,15 +133,24 @@ try {
 ' "$MATCH_LIB" "$STATUS_LOG" 2>/dev/null || printf 'none'
 }
 
+READY_STREAK=0
 for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
   if bridge_has_route; then
-    printf 'Mobile bridge ready\n' >&2
-    exit 0
+    READY_STREAK=$((READY_STREAK + 1))
+    # The bridge can appear briefly while React Native is still completing its
+    # startup navigation/reload. Require two consecutive healthy snapshots so a
+    # following command never inherits that transient gap.
+    if [ "$READY_STREAK" -ge 2 ]; then
+      printf 'Mobile bridge ready\n' >&2
+      exit 0
+    fi
+  else
+    READY_STREAK=0
   fi
   if [ "$ATTEMPT" = "1" ] || [ $((ATTEMPT % 5)) -eq 0 ]; then
     printf 'Waiting for Mobile bridge (%s/%s): %s\n' "$ATTEMPT" "$MAX_POLLS" "$(bridge_wait_reason)" >&2
   fi
-  sleep 2
+  [ "$ATTEMPT" -ge "$MAX_POLLS" ] || sleep 2
 done
 
 cat "$STATUS_LOG" >&2 || true

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

@@ -172,10 +172,10 @@ function extensionRuntimeContextPath(repo) {
   const repoRoot = path.resolve(repo);
   const envCtx = process.env.RECIPE_RUNTIME_CONTEXT;
   if (envCtx) {
-    const resolved = path.resolve(envCtx);
-    if (resolved === repoRoot || resolved.startsWith(`${repoRoot}${path.sep}`)) {
-      return resolved;
-    }
+    // Farmslot may manage runtime context outside the checkout. Treat the
+    // explicit environment override as authoritative; containment is not a
+    // security boundary and silently dropping it selects the wrong port.
+    return path.resolve(envCtx);
   }
   return path.join(repoRoot, recipeRuntimeDir(), 'agentic-runtime.json');
 }
@@ -198,12 +198,22 @@ export function resolveExtensionRuntimeContext(repo) {
   }
 }
 
-// Checkout-scoped extension ports: runtime context (authoritative) → pool → suffix formula.
-export function formatExtensionSlotPorts(repo) {
+// Context and pool describe checkout identity and therefore replace stale
+// inherited env values. The suffix formula is only a fallback and is applied
+// separately by callers so an explicitly supplied env port can still win.
+export function formatExtensionIdentityPorts(repo) {
   const realRepo = path.resolve(repo);
   return mergeKvLayers(
     { source: resolveExtensionRuntimeContext(realRepo), overwrite: true },
     { source: resolveSlotPortsByRepo(realRepo), overwrite: false },
+  );
+}
+
+// Checkout-scoped extension ports: runtime context (authoritative) → pool → suffix formula.
+export function formatExtensionSlotPorts(repo) {
+  const realRepo = path.resolve(repo);
+  return mergeKvLayers(
+    { source: formatExtensionIdentityPorts(realRepo), overwrite: true },
     { source: resolveDefaultExtensionPorts(realRepo), overwrite: false },
   );
 }
@@ -285,6 +295,7 @@ export const cliFns = {
   // Back-compat cli key for one release.
   resolve_farmslot_ports_by_repo: resolveSlotPortsByRepo,
   resolve_default_extension_ports: resolveDefaultExtensionPorts,
+  resolve_extension_identity_ports: (repo) => formatExtensionIdentityPorts(repo) || null,
   resolve_extension_runtime_context: resolveExtensionRuntimeContext,
   resolve_extension_slot_ports: (repo) => formatExtensionSlotPorts(repo) || null,
   resolve_extension_runtime_ports: (repo) => resolveExtensionRuntimePorts(repo) || null,

package/adapters/shared/resolve-slot-ports.sh

@@ -52,12 +52,13 @@ apply_extension_slot_ports() {
   local repo="${1:-.}" line key val resolved="" ctx_file="" runtime_rel="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
   repo="$(cd "$repo" && pwd)"
   ctx_file="$repo/$runtime_rel/agentic-runtime.json"
-  if [ -f "$ctx_file" ]; then
+  if [ -z "${RECIPE_RUNTIME_CONTEXT:-}" ] && [ -f "$ctx_file" ]; then
     RECIPE_RUNTIME_CONTEXT="$ctx_file"
-  else
-    unset RECIPE_RUNTIME_CONTEXT
   fi
-  resolved="$(_resolve_ports_cli resolve_extension_slot_ports "$repo" 2>/dev/null)" || return 0
+  export RECIPE_RUNTIME_CONTEXT
+  # Context/pool are authoritative checkout identity. Formula ports are only
+  # fallback values and must not replace explicitly supplied env ports.
+  resolved="$(_resolve_ports_cli resolve_extension_identity_ports "$repo" 2>/dev/null)" || resolved=""
   while IFS= read -r line; do
     [ -n "$line" ] || continue
     key="${line%%=*}"
@@ -68,6 +69,17 @@ apply_extension_slot_ports() {
       SLOT_ID) RECIPE_SLOT_ID="$val" ;;
     esac
   done <<< "$resolved"
+  resolved="$(_resolve_ports_cli resolve_default_extension_ports "$repo" 2>/dev/null)" || return 0
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      CDP_PORT) [ -n "${CDP_PORT:-}" ] || CDP_PORT="$val" ;;
+      WATCHER_PORT) [ -n "${WATCHER_PORT:-}" ] || WATCHER_PORT="$val" ;;
+      SLOT_ID) [ -n "${RECIPE_SLOT_ID:-}" ] || RECIPE_SLOT_ID="$val" ;;
+    esac
+  done <<< "$resolved"
 }
 
 apply_resolved_extension_ports() {
@@ -111,4 +123,4 @@ apply_resolved_mobile_ports() {
         ;;
     esac
   done <<< "$resolved"
-}
+}

package/adapters/shared/update-check-worker.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const [cacheFile, timeoutText, endpoint] = process.argv.slice(2);
+const timeoutMs = Number.parseInt(timeoutText ?? '', 10);
+
+function stableVersion(value) {
+  const match = /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})$/u.exec(value);
+  if (!match) return null;
+  return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
+}
+
+async function main() {
+  if (!cacheFile || !endpoint || !Number.isInteger(timeoutMs) || timeoutMs < 1) return;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(endpoint, { signal: controller.signal });
+    if (!response.ok) return;
+    const data = await response.json();
+    if (!data || typeof data.latest !== 'string' || data.latest.length === 0) return;
+    const latest = stableVersion(data.latest);
+    if (!latest) return;
+    let lastCheck = Date.now();
+    try {
+      const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      if (typeof cached.lastCheck === 'number') lastCheck = cached.lastCheck;
+    } catch {
+      // The parent may have exited before creating the cache; recreate it below.
+    }
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    const temporary = `${cacheFile}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify({ lastCheck, latest }));
+    fs.renameSync(temporary, cacheFile);
+  } catch {
+    // Passive checks are intentionally silent; the explicit update command teaches failures.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+await main();

package/bin/mm-harness

@@ -5,6 +5,17 @@
 # end-state surface; it resolves node/tsx/dist the same way whether the package is
 # installed as a dependency or run from a source checkout.
 set -euo pipefail
+INVOKED_AS="$0"
+if [[ "$INVOKED_AS" == */* ]]; then
+  INVOKED_AS="$(cd "$(dirname "$INVOKED_AS")" && pwd -L)/${INVOKED_AS##*/}"
+else
+  RESOLVED_INVOKED_AS="$(command -v "$INVOKED_AS" 2>/dev/null || true)"
+  if [[ -z "$RESOLVED_INVOKED_AS" ]]; then
+    echo "ERROR: Cannot resolve the invoked mm-harness executable: $INVOKED_AS" >&2
+    exit 1
+  fi
+  INVOKED_AS="$RESOLVED_INVOKED_AS"
+fi
 SOURCE="${BASH_SOURCE[0]}"
 while [ -L "$SOURCE" ]; do
   SOURCE_DIR="$(cd "$(dirname "$SOURCE")" && pwd -P)"
@@ -26,7 +37,7 @@ RUNNER_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 # already points at this script — including via a symlink (both sides are resolved
 # to their real paths before comparing).
 if [ -n "${MM_HARNESS_BIN:-}" ]; then
-  self_real="$SCRIPT_DIR/$(basename "$SOURCE")"
+  self_real="$SCRIPT_DIR/${SOURCE##*/}"
   # Resolve MM_HARNESS_BIN through any symlink chain so a symlink-to-self is caught.
   mm_bin_src="$MM_HARNESS_BIN"
   while [ -L "$mm_bin_src" ]; do
@@ -39,7 +50,7 @@ if [ -n "${MM_HARNESS_BIN:-}" ]; then
     fi
   done
   bin_real_dir="$(cd "$(dirname "$mm_bin_src")" 2>/dev/null && pwd -P || true)"
-  bin_real="${bin_real_dir:+$bin_real_dir/$(basename "$mm_bin_src")}"
+  bin_real="${bin_real_dir:+$bin_real_dir/${mm_bin_src##*/}}"
   if [ "$bin_real" != "$self_real" ]; then
     if [ ! -x "$MM_HARNESS_BIN" ]; then
       echo "mm-harness: MM_HARNESS_BIN is not an executable: $MM_HARNESS_BIN" >&2
@@ -50,6 +61,14 @@ if [ -n "${MM_HARNESS_BIN:-}" ]; then
   fi
 fi
 
+# Internal executable identity (not part of the public env surface): the CLI
+# embeds this in emitted recovery commands so they run verbatim even when
+# mm-harness is not on PATH (task-local installs). Set AFTER the MM_HARNESS_BIN
+# delegation above so the final executable entered always overwrites any
+# inherited/stale value with its own resolved self path.
+export MM_HARNESS_EXECUTABLE="$SCRIPT_DIR/${SOURCE##*/}"
+export MM_HARNESS_INVOKED_AS="$INVOKED_AS"
+
 ENTRY_TS="$RUNNER_DIR/src/mm-harness-cli.ts"
 ENTRY_DIST="$RUNNER_DIR/dist/mm-harness-cli.js"
 

package/dist/adapters/core/surface.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { shellQuote } from "../../commands/parse-args.js";
 const coreSurface = {
   adapter: "core",
   headless: true,
@@ -14,6 +15,7 @@ const coreSurface = {
       reasons: [
         ready ? "Core is headless; dependencies are installed. Run recipes with mm-harness run." : "Core is headless; dependencies are not fully installed."
       ],
+      nextAction: ready ? void 0 : `cd ${shellQuote(path.resolve(target))} && yarn install --immutable`,
       deps: deps.status
     };
   },
@@ -49,7 +51,8 @@ const coreSurface = {
   },
   hints: {
     launch: "mm-harness run <recipe>   # run recipes against the headless core",
-    relaunch: "mm-harness verify"
+    relaunch: "mm-harness verify",
+    runtimeProbeRecovery: (target) => `mm-harness verify --adapter core --target ${shellQuote(path.resolve(target))}`
   }
 };
 export {