@deeeed/metamask-harness 0.2.0

package/orchestration/mobile/launch.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# launch.sh — mobile instance identity intake + prepare/preflight launch
+#
+# Purpose:
+#   Resolves the per-instance tuple (port, simulator/adb-serial, runtime dir,
+#   platform, preflight mode) and runs the installed runner's mobile prepare.
+#
+# Inputs (flags / env precedence):
+#   --target <metamask-mobile> (default $PWD)
+#   --platform ios|android (default ios)
+#   --preflight-mode|--mode fast|auto|default|rebuild-native|clean
+#       (env RECIPE_HARNESS_MOBILE_PREFLIGHT_MODE, default fast)
+#   --port|--watcher-port|--cdp-port <port> (env WATCHER_PORT > METRO_PORT > CDP_PORT)
+#   --simulator <sim> (env IOS_SIMULATOR > SIM_UDID)
+#   --adb-serial <serial> (env ADB_SERIAL > ANDROID_SERIAL)
+#   --runtime-dir <dir> (env RECIPE_RUNTIME_DIR)
+#   --wallet-setup / --no-wallet-setup, --wallet-fixture <json>
+#   --artifacts-dir <dir>
+#
+# Outputs:
+#   <artifacts>/summary.json (adapter/action/status/runtime/generatedAt),
+#   <artifacts>/runtime-status.json, <artifacts>/logs/prepare.log
+#   Exit 0 — launch pass; 1 — runner missing or prepare failed; 2 — bad args.
+#
+# Never touches: product source files; anything outside the target's harness
+# dir and the artifacts dir.
+set -euo pipefail
+
+TARGET="$PWD"
+PLATFORM="ios"
+PREFLIGHT_MODE="${RECIPE_HARNESS_MOBILE_PREFLIGHT_MODE:-fast}"
+ARTIFACTS=""
+PORT="${WATCHER_PORT:-${METRO_PORT:-${CDP_PORT:-}}}"
+SIMULATOR="${IOS_SIMULATOR:-${SIM_UDID:-}}"
+ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
+RUNTIME_DIR_ARG="${RECIPE_RUNTIME_DIR:-}"
+WALLET_SETUP=false
+WALLET_FIXTURE_ARG=""
+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 ;;
+    --platform) require_value "$@"; PLATFORM="$2"; shift 2 ;;
+    --preflight-mode|--mode) require_value "$@"; PREFLIGHT_MODE="$2"; shift 2 ;;
+    --artifacts-dir) require_value "$@"; ARTIFACTS="$2"; shift 2 ;;
+    --port|--watcher-port|--cdp-port) require_value "$@"; PORT="$2"; shift 2 ;;
+    --simulator) require_value "$@"; SIMULATOR="$2"; shift 2 ;;
+    --adb-serial) require_value "$@"; ADB_SERIAL_ARG="$2"; shift 2 ;;
+    --runtime-dir) require_value "$@"; RUNTIME_DIR_ARG="$2"; shift 2 ;;
+    --wallet-setup) WALLET_SETUP=true; shift ;;
+    --no-wallet-setup) WALLET_SETUP=false; shift ;;
+    --wallet-fixture) require_value "$@"; WALLET_FIXTURE_ARG="$2"; shift 2 ;;
+    -h|--help)
+      echo "Usage: launch.sh [--target <metamask-mobile>] [--platform ios|android] [--preflight-mode fast|auto|default|rebuild-native|clean] [--port <port>] [--simulator <sim>] [--runtime-dir <dir>] [--wallet-setup] [--wallet-fixture <json>]"
+      exit 0
+      ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+case "$PLATFORM" in ios|android) ;; *) echo "Unknown --platform: $PLATFORM" >&2; exit 2 ;; esac
+case "$PREFLIGHT_MODE" in fast|auto|default|rebuild-native|clean) ;; *) echo "Unknown --preflight-mode: $PREFLIGHT_MODE" >&2; exit 2 ;; esac
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+  [ -f "$_hp" ] && { . "$_hp"; break; }
+done
+unset _hp
+if ! command -v harness_root >/dev/null 2>&1; then
+  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+TARGET="$(cd "$TARGET" && pwd)"
+HARNESS_DIR="$(harness_dir "$TARGET" mobile)"
+RUNNER_BIN="$HARNESS_DIR/runner/bin/metamask-recipe"
+ARTIFACTS="${ARTIFACTS:-$HARNESS_DIR/launch/$(date -u +%Y%m%dT%H%M%SZ)}"
+mkdir -p "$ARTIFACTS/logs"
+
+if [ ! -x "$RUNNER_BIN" ]; then
+  echo "Mobile recipe runner is not installed in $TARGET. Run metamask-recipe mobile install --target $TARGET first." >&2
+  exit 1
+fi
+
+prepare_args=(mobile prepare --target "$TARGET" --platform "$PLATFORM" --preflight-mode "$PREFLIGHT_MODE")
+[ -n "$PORT" ] && prepare_args+=(--port "$PORT")
+[ -n "$SIMULATOR" ] && prepare_args+=(--simulator "$SIMULATOR")
+[ -n "$ADB_SERIAL_ARG" ] && prepare_args+=(--adb-serial "$ADB_SERIAL_ARG")
+[ -n "$RUNTIME_DIR_ARG" ] && prepare_args+=(--runtime-dir "$RUNTIME_DIR_ARG")
+$WALLET_SETUP && prepare_args+=(--wallet-setup)
+[ -n "$WALLET_FIXTURE_ARG" ] && prepare_args+=(--wallet-fixture "$WALLET_FIXTURE_ARG")
+
+status="pass"
+if (cd "$TARGET" && "$RUNNER_BIN" "${prepare_args[@]}") > "$ARTIFACTS/logs/prepare.log" 2>&1; then
+  runtime_status="pass"
+else
+  runtime_status="fail"
+  status="fail"
+fi
+
+status_args=(mobile runtime-status --target "$TARGET" --json)
+[ -n "$PORT" ] && status_args+=(--port "$PORT")
+[ -n "$RUNTIME_DIR_ARG" ] && status_args+=(--runtime-dir "$RUNTIME_DIR_ARG")
+(cd "$TARGET" && "$RUNNER_BIN" "${status_args[@]}") > "$ARTIFACTS/runtime-status.json" 2> "$ARTIFACTS/logs/runtime-status.err" || true
+
+TARGET_FOR_SUMMARY="$TARGET" ARTIFACTS_FOR_SUMMARY="$ARTIFACTS" STATUS_FOR_SUMMARY="$status" RUNTIME_STATUS="$runtime_status" PLATFORM_FOR_SUMMARY="$PLATFORM" MODE_FOR_SUMMARY="$PREFLIGHT_MODE" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const artifacts = process.env.ARTIFACTS_FOR_SUMMARY;
+let runtime = null;
+try { runtime = JSON.parse(fs.readFileSync(path.join(artifacts, 'runtime-status.json'), 'utf8')); } catch {}
+fs.writeFileSync(path.join(artifacts, 'summary.json'), `${JSON.stringify({
+  adapter: 'mobile',
+  action: 'launch',
+  status: process.env.STATUS_FOR_SUMMARY,
+  platform: process.env.PLATFORM_FOR_SUMMARY,
+  preflightMode: process.env.MODE_FOR_SUMMARY,
+  target: process.env.TARGET_FOR_SUMMARY,
+  runtime: {
+    status: process.env.RUNTIME_STATUS,
+    ready: runtime?.ready === true,
+    reason: runtime?.reason || null,
+    port: runtime?.metro?.port || null,
+    prepareLogPath: path.join(artifacts, 'logs/prepare.log'),
+    runtimeStatusPath: path.join(artifacts, 'runtime-status.json'),
+  },
+  runtimePolicy: {
+    nativeBuildPolicy: process.env.MODE_FOR_SUMMARY === 'fast'
+      ? 'fast mode never runs a native build; it requires an installed dev client, starts/reuses Metro, prewarms the JS bundle, opens the dev client, and waits for the bridge'
+      : 'non-fast modes may install or rebuild the native dev client when needed; then start/reuse Metro, prewarm the JS bundle, open the dev client, and wait for the bridge',
+  },
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+
+echo "Mobile harness launch $status: $ARTIFACTS/summary.json"
+[ "$status" = "pass" ]

package/orchestration/mobile/live.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# live.sh — mobile launch-then-verify chaining for one live slot run
+#
+# Purpose:
+#   Runs launch.sh then verify.sh (verify with --no-auto-start; launch owns
+#   startup) under a timestamped artifact dir and aggregates both results.
+#
+# Inputs (flags / env):
+#   --target <metamask-mobile> (default $PWD)
+#   --platform ios|android (default ios)
+#   --preflight-mode|--mode fast|auto|default|rebuild-native|clean
+#       (env RECIPE_HARNESS_MOBILE_PREFLIGHT_MODE, default fast)
+#   --artifacts-dir <dir> (default <harness>/live/<UTC>)
+#   --wallet-setup|--no-wallet-setup (default auto), --wallet-fixture <json>
+#
+# Outputs:
+#   <artifacts>/summary.json (adapter/action/status, launch/verify exit codes
+#   + child summary paths, easyCommand), <artifacts>/{launch,verify}/.
+#   Exit 0 — launch and verify both passed; 1 — either failed; 2 — bad args.
+#
+# Never touches: product source files; anything outside the target's harness
+# dir and the artifacts dir.
+set -euo pipefail
+
+TARGET="$PWD"
+PLATFORM="ios"
+PREFLIGHT_MODE="${RECIPE_HARNESS_MOBILE_PREFLIGHT_MODE:-fast}"
+ARTIFACTS=""
+WALLET_SETUP="auto"
+WALLET_FIXTURE=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --platform) PLATFORM="$2"; shift 2 ;;
+    --preflight-mode|--mode) PREFLIGHT_MODE="$2"; shift 2 ;;
+    --artifacts-dir) ARTIFACTS="$2"; shift 2 ;;
+    --wallet-setup) WALLET_SETUP="true"; shift ;;
+    --no-wallet-setup) WALLET_SETUP="false"; shift ;;
+    --wallet-fixture) WALLET_FIXTURE="$2"; shift 2 ;;
+    -h|--help) echo "Usage: live.sh [--target <metamask-mobile>] [--platform ios|android] [--preflight-mode fast|auto|default|rebuild-native|clean] [--artifacts-dir <dir>] [--wallet-setup|--no-wallet-setup]"; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+case "$PLATFORM" in ios|android) ;; *) echo "Unknown --platform: $PLATFORM" >&2; exit 2 ;; esac
+case "$PREFLIGHT_MODE" in fast|auto|default|rebuild-native|clean) ;; *) echo "Unknown --preflight-mode: $PREFLIGHT_MODE" >&2; exit 2 ;; esac
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+  [ -f "$_hp" ] && { . "$_hp"; break; }
+done
+unset _hp
+if ! command -v harness_root >/dev/null 2>&1; then
+  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+# verify.sh is a recipe-tree feature: co-located in installed copies, under
+# runner/mobile in a repo checkout.
+VERIFY_SH=""
+for _v in "$SCRIPT_DIR/verify.sh" "$SCRIPT_DIR/../../runner/mobile/verify.sh"; do
+  [ -f "$_v" ] && { VERIFY_SH="$_v"; break; }
+done
+unset _v
+if [ -z "$VERIFY_SH" ]; then
+  echo "mm-harness: mobile verify.sh not found next to $SCRIPT_DIR; reinstall the runner." >&2
+  exit 1
+fi
+TARGET="$(cd "$TARGET" && pwd)"
+WALLET_FIXTURE="${WALLET_FIXTURE:-$(recipe_runtime_dir)/wallet-fixture.json}"
+ARTIFACTS="${ARTIFACTS:-$(harness_dir "$TARGET" mobile)/live/$(date -u +%Y%m%dT%H%M%SZ)}"
+mkdir -p "$ARTIFACTS"
+
+launch_args=(--target "$TARGET" --platform "$PLATFORM" --preflight-mode "$PREFLIGHT_MODE" --artifacts-dir "$ARTIFACTS/launch")
+case "$WALLET_SETUP" in
+  true) launch_args+=(--wallet-setup) ;;
+  false) launch_args+=(--no-wallet-setup) ;;
+esac
+launch_args+=(--wallet-fixture "$WALLET_FIXTURE")
+
+echo "Mobile live validation command:"
+echo "  mm-harness launch $PLATFORM --verify"
+echo "Launch artifacts: $ARTIFACTS/launch"
+echo "Verify artifacts: $ARTIFACTS/verify"
+
+set +e
+"$SCRIPT_DIR/launch.sh" "${launch_args[@]}"
+launch_status=$?
+set -e
+
+verify_status=1
+if [ "$launch_status" -eq 0 ]; then
+  set +e
+  "$VERIFY_SH" --target "$TARGET" --platform "$PLATFORM" --preflight-mode "$PREFLIGHT_MODE" --no-auto-start --artifacts-dir "$ARTIFACTS/verify"
+  verify_status=$?
+  set -e
+else
+  echo "Skipping Mobile live verify because launch failed; see $ARTIFACTS/launch/summary.json" >&2
+fi
+
+TARGET_FOR_SUMMARY="$TARGET" ARTIFACTS_FOR_SUMMARY="$ARTIFACTS" PLATFORM_FOR_SUMMARY="$PLATFORM" MODE_FOR_SUMMARY="$PREFLIGHT_MODE" LAUNCH_STATUS="$launch_status" VERIFY_STATUS="$verify_status" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const artifacts = process.env.ARTIFACTS_FOR_SUMMARY;
+const launchSummary = path.join(artifacts, 'launch', 'summary.json');
+const verifySummary = path.join(artifacts, 'verify', 'summary.json');
+const launchStatus = Number(process.env.LAUNCH_STATUS);
+const verifyStatus = Number(process.env.VERIFY_STATUS);
+fs.writeFileSync(path.join(artifacts, 'summary.json'), `${JSON.stringify({
+  adapter: 'mobile',
+  action: 'live',
+  status: launchStatus === 0 && verifyStatus === 0 ? 'pass' : 'fail',
+  target: process.env.TARGET_FOR_SUMMARY,
+  platform: process.env.PLATFORM_FOR_SUMMARY,
+  preflightMode: process.env.MODE_FOR_SUMMARY,
+  launch: { exitCode: launchStatus, summaryPath: fs.existsSync(launchSummary) ? launchSummary : null },
+  verify: { exitCode: verifyStatus, summaryPath: fs.existsSync(verifySummary) ? verifySummary : null },
+  easyCommand: `mm-harness launch ${process.env.PLATFORM_FOR_SUMMARY} --verify`,
+  note: 'Runs launch then live verify so a developer can validate app startup, runner-owned CDP bridge, screenshot capture, and tiny recipe control from one runner-owned command.',
+  generatedAt: new Date().toISOString(),
+}, null, 2)}\n`);
+NODE
+
+echo "Mobile live validation summary: $ARTIFACTS/summary.json"
+[ "$launch_status" -eq 0 ] && [ "$verify_status" -eq 0 ]

package/orchestration/mobile/runtime-decision.ts

@@ -0,0 +1,292 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  clearDecisionState,
+  depsCheck,
+  recordDepsBaseline,
+  type DepsCheck,
+} from '@farmslot/recipe-harness/runtime/deps-readiness';
+import {
+  analyzeBundleLog,
+  evaluatePersistentBundleError,
+  supersededErrorCapture,
+  type BundleLogAnalysis,
+} from '@farmslot/recipe-harness/runtime/log-analysis';
+import { probeMetroPackager, type MetroReachabilityCheck } from '@farmslot/recipe-harness/runtime/metro-probe';
+
+import { mobileProductMarkers } from './deps-markers.ts';
+
+/**
+ * MetaMask Mobile runtime-readiness adapter.
+ *
+ * Generic deps/log/metro primitives live in `@farmslot/recipe-harness/runtime/*`.
+ * This file owns MetaMask-specific markers, Nitro staleness regex, and action ids.
+ */
+
+export type MobileReadinessDecision = 'install' | 'launch' | 'ready' | 'blocked' | 'unknown';
+
+export interface MobileRuntimeDecisionAction {
+  id: string;
+  argv?: string[];
+  cwd?: string;
+  paths?: string[];
+}
+
+export type MetroLogCheck = BundleLogAnalysis;
+
+export interface MobileRuntimeDecisionReport {
+  schemaVersion: 1;
+  adapter: 'mobile';
+  target: string;
+  decision: MobileReadinessDecision;
+  reasonCode: string;
+  reasons: string[];
+  checks: {
+    deps: DepsCheck;
+    metroLog: MetroLogCheck;
+    metro: MetroReachabilityCheck;
+  };
+  actions: MobileRuntimeDecisionAction[];
+}
+
+export interface MobileRuntimeDecisionOptions {
+  watcherPort?: number;
+  metroLog?: string;
+  platform?: string;
+  record?: boolean;
+}
+
+const BUNDLE_ERR = /Bundling failed|Unable to resolve /u;
+const BUNDLE_OK = /Bundled \d+ms|iOS Bundled|Android Bundled|Finished bundling/u;
+const NATIVE_MODULE_STALE =
+  /\[runtime not ready\].*HybridObject "([^"]+)" - It has not yet been registered in the Nitro Modules HybridObjectRegistry/u;
+
+function resolveMetroLog(target: string, metroLog?: string): string | null {
+  const rel = metroLog ?? 'temp/recipe/runtime/metro.log';
+  const abs = path.isAbsolute(rel) ? rel : path.join(target, rel);
+  return fs.existsSync(abs) ? abs : null;
+}
+
+function metroLogCheck(target: string, metroLog?: string): MetroLogCheck {
+  const abs = resolveMetroLog(target, metroLog);
+  if (!abs) return { status: 'no-log' };
+  const logText = fs.readFileSync(abs, 'utf8');
+  return analyzeBundleLog({
+    target,
+    logText,
+    errorPattern: BUNDLE_ERR,
+    okPattern: BUNDLE_OK,
+  });
+}
+
+const installActions = (target: string): MobileRuntimeDecisionAction[] => [
+  { id: 'yarn-setup', argv: ['yarn', 'setup'], cwd: target },
+];
+
+const launchActions = (target: string, clearMetro = false): MobileRuntimeDecisionAction[] => {
+  const actions: MobileRuntimeDecisionAction[] = [];
+  if (clearMetro) {
+    actions.push({ id: 'clear-metro-cache', argv: ['yarn', 'expo', 'start', '--clear'], cwd: target });
+  }
+  actions.push({ id: 'launch-mobile-runtime' });
+  return actions;
+};
+
+export async function decideMobileReadiness(
+  target: string,
+  options: MobileRuntimeDecisionOptions = {},
+): Promise<MobileRuntimeDecisionReport> {
+  const resolved = path.resolve(target);
+  if (options.record) recordDepsBaseline(resolved);
+
+  const deps = depsCheck(resolved, {
+    productMarkers: mobileProductMarkers(options.platform),
+  });
+  const metroLog = metroLogCheck(resolved, options.metroLog);
+  const metro = options.watcherPort
+    ? await probeMetroPackager(options.watcherPort)
+    : { status: 'skipped' as const };
+
+  if (metroLog.status === 'ok') {
+    clearDecisionState(resolved, 'bundle-error-state.json');
+  }
+
+  const checks = { deps, metroLog, metro };
+
+  if (deps.status === 'missing') {
+    return {
+      schemaVersion: 1,
+      adapter: 'mobile',
+      target: resolved,
+      decision: 'install',
+      reasonCode: 'deps-missing',
+      reasons: ['Dependencies are not installed (no yarn install-state markers).'],
+      checks,
+      actions: installActions(resolved),
+    };
+  }
+
+  if (deps.status === 'partial') {
+    const missing = deps.missingProducts?.join(', ') ?? 'product markers';
+    return {
+      schemaVersion: 1,
+      adapter: 'mobile',
+      target: resolved,
+      decision: 'install',
+      reasonCode: 'deps-partial',
+      reasons: [`node_modules tree is incomplete (missing: ${missing}).`],
+      checks,
+      actions: installActions(resolved),
+    };
+  }
+
+  if (deps.status === 'stale') {
+    return {
+      schemaVersion: 1,
+      adapter: 'mobile',
+      target: resolved,
+      decision: 'install',
+      reasonCode: 'deps-stale',
+      reasons: ['package.json/yarn.lock changed since the recorded install baseline.'],
+      checks,
+      actions: installActions(resolved),
+    };
+  }
+
+  const metroLogAbs = resolveMetroLog(resolved, options.metroLog);
+  const metroLogText = metroLogAbs ? fs.readFileSync(metroLogAbs, 'utf8') : '';
+  const staleNativeModule = supersededErrorCapture(metroLogText, {
+    errorPattern: NATIVE_MODULE_STALE,
+    okPattern: BUNDLE_OK,
+  });
+  if (staleNativeModule) {
+    return {
+      schemaVersion: 1,
+      adapter: 'mobile',
+      target: resolved,
+      decision: 'launch',
+      reasonCode: 'native-module-stale',
+      reasons: [
+        `Installed dev client is missing native module "${staleNativeModule}" (JS deps are current). Rebuild the native app (yarn start:ios / yarn start:android or --preflight-mode rebuild-native).`,
+        'Metro may report a successful bundle while the installed dev client binary predates the native Nitro module link.',
+      ],
+      checks,
+      actions: [
+        { id: 'rebuild-native-dev-client' },
+        ...launchActions(resolved, true),
+      ],
+    };
+  }
+
+  if (metroLog.status === 'errors') {
+    const depsSatisfied = deps.status === 'current';
+    if (
+      depsSatisfied
+      && (metroLog.reason === 'stale-bundle-error'
+        || metroLog.reason === 'bundle-error')
+    ) {
+      const excerpt = metroLog.excerpt ?? '';
+      const persistent = evaluatePersistentBundleError(resolved, excerpt);
+      if (persistent.blocked) {
+        return {
+          schemaVersion: 1,
+          adapter: 'mobile',
+          target: resolved,
+          decision: 'blocked',
+          reasonCode: 'bundle-error-persistent',
+          reasons: [
+            'Metro bundle keeps failing with the same error after a cache-cleared relaunch was already suggested; fix the bundle error in app code before retrying recipe up.',
+            ...(excerpt ? [excerpt] : []),
+          ],
+          checks,
+          actions: [],
+        };
+      }
+      return {
+        schemaVersion: 1,
+        adapter: 'mobile',
+        target: resolved,
+        decision: 'launch',
+        reasonCode: metroLog.reason === 'stale-bundle-error' ? 'metro-stale-log' : 'bundle-errors-recoverable',
+        reasons: [
+          metroLog.reason === 'stale-bundle-error'
+            ? 'Metro log shows prior bundle failures but cited modules are installed; restart Metro with a cleared cache.'
+            : 'Metro bundle is failing with current deps; restart Metro (clear cache) before relaunching the dev client.',
+          ...(excerpt ? [excerpt] : []),
+        ],
+        checks,
+        actions: launchActions(resolved, true),
+      };
+    }
+    return {
+      schemaVersion: 1,
+      adapter: 'mobile',
+      target: resolved,
+      decision: 'install',
+      reasonCode: metroLog.reason === 'unresolved-module' ? 'deps-unresolved-module' : 'bundle-errors',
+      reasons: [
+        metroLog.reason === 'unresolved-module'
+          ? 'Metro cannot resolve modules that are absent from node_modules; run yarn setup.'
+          : 'Metro bundle is failing; reinstall deps or clear Metro cache before retrying.',
+        ...(metroLog.excerpt ? [metroLog.excerpt] : []),
+      ],
+      checks,
+      actions: installActions(resolved),
+    };
+  }
+
+  if (metro.status === 'down') {
+    return {
+      schemaVersion: 1,
+      adapter: 'mobile',
+      target: resolved,
+      decision: 'launch',
+      reasonCode: 'metro-down',
+      reasons: ['Metro is not reachable; start Metro and launch the dev client.'],
+      checks,
+      actions: launchActions(resolved),
+    };
+  }
+
+  if (metroLog.status === 'bundling' || metroLog.status === 'no-log') {
+    return {
+      schemaVersion: 1,
+      adapter: 'mobile',
+      target: resolved,
+      decision: 'launch',
+      reasonCode: metroLog.status === 'bundling' ? 'bundle-in-progress' : 'runtime-cold',
+      reasons: [
+        metroLog.status === 'bundling'
+          ? 'Metro bundle is still in progress; launch or wait for a successful bundle.'
+          : 'No successful Metro bundle recorded; start Metro and launch the dev client.',
+      ],
+      checks,
+      actions: launchActions(resolved),
+    };
+  }
+
+  if (metro.status === 'up' && metroLog.status === 'ok') {
+    return {
+      schemaVersion: 1,
+      adapter: 'mobile',
+      target: resolved,
+      decision: 'ready',
+      reasonCode: 'healthy',
+      reasons: ['Dependencies are current and Metro reports a successful bundle. Verify bridge before replay.'],
+      checks,
+      actions: [],
+    };
+  }
+
+  return {
+    schemaVersion: 1,
+    adapter: 'mobile',
+    target: resolved,
+    decision: 'launch',
+    reasonCode: 'runtime-unverified',
+    reasons: ['Dependencies are current; start or refresh Metro + dev client before replay.'],
+    checks,
+    actions: launchActions(resolved),
+  };
+}

package/orchestration/porcelain/metamask-recipe

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  SOURCE_DIR="$(cd "$(dirname "$SOURCE")" && pwd -P)"
+  TARGET="$(readlink "$SOURCE")"
+  if [[ "$TARGET" == /* ]]; then
+    SOURCE="$TARGET"
+  else
+    SOURCE="$SOURCE_DIR/$TARGET"
+  fi
+done
+SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" && pwd -P)"
+# This script lives at <root>/orchestration/porcelain/; the runner root is two up.
+RUNNER_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+ENSURE_DEPS="$RUNNER_DIR/orchestration/lib/ensure-runner-deps.sh"
+if [ -f "$ENSURE_DEPS" ]; then
+  # shellcheck disable=SC1090
+  bash "$ENSURE_DEPS" "$RUNNER_DIR"
+fi
+
+if [ "${1:-}" = "mobile" ]; then
+  shift
+  exec "$RUNNER_DIR/bin/mm-recipe" "$@"
+fi
+if [ "${1:-}" = "extension" ]; then
+  shift
+  exec "$RUNNER_DIR/bin/mme-recipe" "$@"
+fi
+
+find_protocol_root() {
+  local start="$1"
+  local dir
+  dir="$(cd "$start" && pwd -P)"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/packages/recipe-harness/package.json" ] && [ -f "$dir/packages/protocol/package.json" ]; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    if [ -f "$dir/farmslot/packages/recipe-harness/package.json" ] && [ -f "$dir/farmslot/packages/protocol/package.json" ]; then
+      printf '%s\n' "$dir/farmslot"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+node_can_run_source_typescript() {
+  # Node refuses type-stripping for files under node_modules (ERR_UNSUPPORTED_NODE_
+  # MODULES_TYPE_STRIPPING). When this runner is installed as a dependency, cli.ts
+  # lives under node_modules and cannot run under plain node — a /tmp probe would be a
+  # false positive. Skip the node-source path in that case and fall through to dist/tsx.
+  case "$RUNNER_DIR/" in
+    */node_modules/*) return 1 ;;
+  esac
+  local probe_dir probe_file
+  probe_dir="$(mktemp -d "${TMPDIR:-/tmp}/metamask-recipe-node-ts.XXXXXX")"
+  probe_file="$probe_dir/probe.ts"
+  printf 'const answer: number = 42; if (answer !== 42) process.exit(1);\n' > "$probe_file"
+  if ! node --no-warnings "$probe_file" >/dev/null 2>&1; then
+    rm -rf "$probe_dir"
+    return 1
+  fi
+  rm -rf "$probe_dir"
+}
+
+if [ -f "$RUNNER_DIR/dist/cli.js" ]; then
+  exec node "$RUNNER_DIR/dist/cli.js" "$@"
+fi
+
+TSX_BIN="${TSX_BIN:-$RUNNER_DIR/node_modules/.bin/tsx}"
+if [ ! -x "$TSX_BIN" ] && [ -x "$RUNNER_DIR/../../.bin/tsx" ]; then
+  TSX_BIN="$RUNNER_DIR/../../.bin/tsx"
+fi
+if [ ! -x "$TSX_BIN" ]; then
+  if [ -z "${FARMSLOT_ROOT:-}" ] && [ -f "$RUNNER_DIR/.farmslot-root" ]; then
+    FARMSLOT_ROOT="$(cat "$RUNNER_DIR/.farmslot-root")"
+  fi
+  if [ -z "${FARMSLOT_ROOT:-}" ]; then
+    FARMSLOT_ROOT="$(find_protocol_root "$RUNNER_DIR" || find_protocol_root "$PWD" || true)"
+  fi
+  if [ -n "${FARMSLOT_ROOT:-}" ]; then
+    FARMSLOT_ROOT="$(cd "$FARMSLOT_ROOT" && pwd -P)"
+    TSX_BIN="$FARMSLOT_ROOT/node_modules/.bin/tsx"
+  fi
+fi
+
+if node_can_run_source_typescript; then
+  exec node --no-warnings "$RUNNER_DIR/runner/src/cli.ts" "$@"
+fi
+
+if [ -x "$TSX_BIN" ]; then
+  exec "$TSX_BIN" "$RUNNER_DIR/runner/src/cli.ts" "$@"
+fi
+
+echo "metamask-recipe source checkout requires dist/cli.js, Node.js TypeScript type stripping, or a local tsx binary. Install dependencies normally, or set TSX_BIN/FARMSLOT_ROOT for local protocol co-development." >&2
+exit 1