@deeeed/metamask-harness 0.40.1 → 0.41.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.41.1 - 2026-08-19
+
+### Fixed
+
+- Rotate each harness-owned Metro start into a run-scoped evidence generation, bound retained archives, coalesce repetitive bundle progress, and keep bundle-error recovery state inside one launch invocation.
+
+## 0.41.0 - 2026-08-19
+
+### Added
+
+- Add one parameterized, platform-neutral Mobile Perps performance recipe covering cold, cached, resume, reconnect, account-switch, and network-switch lifecycles with native visible-content proof and production loading/WebSocket evidence.
+
+### Changed
+
+- Replace the duplicated Android, iOS, cold, warm, and background Perps performance recipes with the single lifecycle recipe.
+
+### Fixed
+
+- Keep explicitly pinned iOS and Android bridge targets isolated when both platforms are active, and classify bounded CDP target failures as infrastructure failures.
+- Make Mobile wallet unlock and account selection deterministic across app restarts, propagate recipe timeouts through Perps state setup, and preserve missing performance counts and offsets as unknown instead of zero.
+- Keep the entire checkout-local `temp` tree outside Metro watching during canonical `yarn watch` launches, and leave the Mobile recipe HUD visible by default for performance lifecycles.
+
 ## 0.40.1 - 2026-08-16
 
 ### Fixed

package/adapters/manifest.json

@@ -39,9 +39,33 @@
       "entry": "adapters/mobile/launch-metro.cjs",
       "kind": "node",
       "purpose": "Launch Metro detached from the invoking process group so the runtime survives command cleanup.",
-      "inputs": "--target --port --log --pid-file [--workers] [--clear]",
+      "inputs": "--target --port --log --pid-file --build-env --runner [--workers] [--clear]",
       "outputs": "Metro PID/launch metadata and redirected log; exit 0/1/2"
     },
+    {
+      "id": "mobile/metro-log-generation",
+      "entry": "adapters/mobile/metro-log-generation.cjs",
+      "kind": "module",
+      "purpose": "Rotate one Metro generation, retain bounded archives, and publish launch evidence.",
+      "inputs": "runtime directory, Metro port, rotation reason; env MM_HARNESS_METRO_LOG_ARCHIVE_COUNT, MM_HARNESS_METRO_LOG_ARCHIVE_BYTES",
+      "outputs": "metro.log, archived logs, metro-generation.json"
+    },
+    {
+      "id": "mobile/coalesce-metro-log",
+      "entry": "adapters/mobile/coalesce-metro-log.cjs",
+      "kind": "module",
+      "purpose": "Coalesce repetitive Metro percentage progress while preserving diagnostics.",
+      "inputs": "Metro output on stdin",
+      "outputs": "errors, completion, and timestamped meaningful progress on stdout"
+    },
+    {
+      "id": "mobile/metro-config",
+      "entry": "adapters/mobile/metro-config.cjs",
+      "kind": "module",
+      "purpose": "Preserve the product Metro config while excluding the checkout-local temp tree owned by harness evidence and runtime state.",
+      "inputs": "base Metro config; env MM_HARNESS_METRO_PROJECT_ROOT, MM_HARNESS_METRO_BASE_CONFIG",
+      "outputs": "merged Metro config with resolver.blockList for <projectRoot>/temp"
+    },
     {
       "id": "mobile/stop-metro",
       "entry": "adapters/mobile/stop-metro.sh",

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -30,12 +30,13 @@ const {
 const { cdpEval, cdpEvalAsync } = require('./lib/cdp-eval.cjs');
 const { buildArmSnippet, buildCollectSnippet } = require('./lib/issue-capture.cjs');
 
-function parseHomepagePerformanceConsoleEvent(params) {
-  const marker = '[HomepagePerf] ';
+function parsePerformanceConsoleEvent(params) {
+  const markers = ['[PerpsPerf] ', '[HomepagePerf] '];
   for (const arg of params?.args || []) {
     const text = typeof arg?.value === 'string' ? arg.value : '';
+    const marker = markers.find((candidate) => text.includes(candidate));
+    if (!marker) continue;
     const markerIndex = text.indexOf(marker);
-    if (markerIndex < 0) continue;
     try {
       return JSON.parse(text.slice(markerIndex + marker.length));
     } catch {}
@@ -490,7 +491,7 @@ const COMMANDS = {
     let removeConsoleListener = null;
     if (visibleEventStage) {
       removeConsoleListener = client.on('Runtime.consoleAPICalled', (params) => {
-        const payload = parseHomepagePerformanceConsoleEvent(params);
+        const payload = parsePerformanceConsoleEvent(params);
         if (payload?.stage === visibleEventStage) visibleEvents.push(payload);
       });
       await client.send('Runtime.enable');

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -145,6 +145,9 @@ async function discoverTarget(port) {
   const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
   const androidPinned = Boolean(androidTargetName || androidDevice);
   const simName = loadSimulatorName();
+  const iosPinned =
+    process.env.MM_HARNESS_EXPLICIT_PLATFORM === 'ios' ||
+    Boolean(process.env.SIM_UDID);
   const matchesAndroidPin = (target) => androidTargetName
     ? target.deviceName !== simName &&
       (target.deviceName === androidTargetName ||
@@ -166,6 +169,18 @@ async function discoverTarget(port) {
         }
         return false;
       }
+      if (iosPinned && simName) {
+        const pinnedCandidates = runtimeCandidates.filter(
+          (candidate) => candidate.deviceName === simName,
+        );
+        for (const candidate of pinnedCandidates) {
+          if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+            acceptedPinnedCandidate = candidate;
+            return true;
+          }
+        }
+        return false;
+      }
       return true;
     });
   } catch (e) {
@@ -193,12 +208,16 @@ async function discoverTarget(port) {
   // context, and letting it win here sends a pinned android action to the iOS
   // target. No-match keeps the full candidate set (ambient sim configs tolerate a
   // sim that is not currently attached).
-  if (simName && !androidPinned && candidates.length > 1) {
+  if (simName && !androidPinned) {
     const deviceFiltered = candidates.filter(
       (t) => t.deviceName === simName,
     );
     if (deviceFiltered.length > 0) {
       candidates = deviceFiltered;
+    } else if (iosPinned) {
+      throw coded(new Error(
+        `Pinned iOS simulator '${simName}' did not match any Metro target.`,
+      ), BRIDGE_ERROR_CODES.NO_TARGET);
     }
   }
 
@@ -306,15 +325,15 @@ async function discoverTarget(port) {
     }
   }
 
-  if (androidPinned) {
+  if (androidPinned || iosPinned) {
     const candidateList = candidates
       .map((target) => `  deviceName=${JSON.stringify(target.deviceName || '')} ws=${target.webSocketDebuggerUrl || ''}`)
       .join('\n');
     throw coded(new Error(
-      `Pinned Android device has no responding __AGENTIC__ JS runtime after ${FETCH_RETRIES} discovery attempt(s).\n` +
-      `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` +
+      `Pinned ${androidPinned ? 'Android device' : `iOS simulator '${simName || process.env.SIM_UDID || '(unknown)'}'`} has no responding __AGENTIC__ JS runtime after ${FETCH_RETRIES} discovery attempt(s).\n` +
+      (androidPinned ? `  Requested --device (ADB_SERIAL): ${adbSerial || '(not set)'}\n` : '') +
       `  Matching non-agentic targets:\n${candidateList}\n` +
-      `  The native C++ page is not a valid recipe target; wait for Android Hermes to re-register or relaunch the Android app.`,
+      `  The native C++ page is not a valid recipe target; wait for Hermes to re-register or relaunch the pinned app.`,
     ), BRIDGE_ERROR_CODES.NO_TARGET);
   }
 

package/adapters/mobile/coalesce-metro-log.cjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+const readline = require('node:readline');
+
+const progressPattern = /^\s*(?:iOS|Android).*?(\d{1,3}(?:\.\d+)?)%/u;
+let lastPercent = null;
+let lastProgressAt = 0;
+
+const lines = readline.createInterface({ input: process.stdin, crlfDelay: Infinity, terminal: false });
+lines.on('line', (line) => {
+  const progress = progressPattern.exec(line);
+  if (!progress) {
+    process.stdout.write(`${line}\n`);
+    return;
+  }
+  const percent = Math.floor(Number(progress[1]));
+  const now = Date.now();
+  if (percent !== lastPercent || now - lastProgressAt >= 15_000) {
+    process.stdout.write(`${line} [metro-progress ${new Date(now).toISOString()}]\n`);
+    lastPercent = percent;
+    lastProgressAt = now;
+  }
+});

package/adapters/mobile/launch-metro.cjs

@@ -26,33 +26,34 @@ function parseArgs(argv) {
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
-    console.log('Usage: launch-metro.cjs --target <path> --port <port> --log <path> --pid-file <path> --build-env <path> [--workers <n>] [--clear]');
+    console.log('Usage: launch-metro.cjs --target <path> --port <port> --log <path> --pid-file <path> --build-env <path> --runner <path> [--workers <n>] [--clear]');
     return;
   }
-  for (const required of ['target', 'port', 'log', 'pid-file', 'build-env']) {
+  for (const required of ['target', 'port', 'log', 'pid-file', 'build-env', 'runner']) {
     if (!args[required]) throw new Error(`--${required} is required`);
   }
   const target = path.resolve(args.target);
   const log = path.resolve(args.log);
   const pidFile = path.resolve(args['pid-file']);
+  const runner = path.resolve(args.runner);
   fs.mkdirSync(path.dirname(log), { recursive: true });
   fs.mkdirSync(path.dirname(pidFile), { recursive: true });
-  const logFd = fs.openSync(log, 'a');
-  const childArgs = ['watch'];
+  const runnerStat = fs.lstatSync(runner);
+  if (!runnerStat.isFile()) throw new Error('--runner must be a regular file');
+  fs.accessSync(runner, fs.constants.X_OK);
   const env = { ...process.env };
   env.BASH_ENV = args['build-env'];
   if (args.workers) env.METRO_MAX_WORKERS = String(args.workers);
-  const child = spawn('yarn', childArgs, {
+  const child = spawn(runner, [], {
     cwd: target,
     detached: true,
     env,
-    stdio: ['ignore', logFd, logFd],
+    stdio: 'ignore',
   });
   await new Promise((resolve, reject) => {
     child.once('spawn', resolve);
     child.once('error', reject);
   });
-  fs.closeSync(logFd);
   fs.writeFileSync(pidFile, `${String(child.pid)}\n`);
   fs.writeFileSync(
     path.join(path.dirname(pidFile), 'metro-launch.json'),
@@ -64,7 +65,7 @@ async function main() {
       target,
       port: Number(args.port),
       clear: Boolean(args.clear),
-      command: `yarn ${childArgs[0]}`,
+      command: runner,
     }, null, 2)}\n`,
   );
   child.unref();

package/adapters/mobile/metro-config.cjs

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs = require('node:fs');
+const { createRequire } = require('node:module');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function appendBlockList(blockList, pattern) {
+  if (Array.isArray(blockList)) return [...blockList, pattern];
+  return blockList instanceof RegExp ? [blockList, pattern] : [pattern];
+}
+
+function blockListFlags(blockList) {
+  const first = Array.isArray(blockList) ? blockList[0] : blockList;
+  return first instanceof RegExp && first.ignoreCase ? 'i' : '';
+}
+
+function resolveExpoConfigLoader(projectRoot) {
+  const requireFromProject = createRequire(path.join(projectRoot, 'package.json'));
+  let requireUtilsPath;
+  try {
+    requireUtilsPath = requireFromProject.resolve('@expo/require-utils');
+  } catch (error) {
+    if (error?.code !== 'MODULE_NOT_FOUND') throw error;
+    return null;
+  }
+  const { loadModuleSync } = requireFromProject(requireUtilsPath);
+  return typeof loadModuleSync === 'function' ? loadModuleSync : null;
+}
+
+async function loadProductConfig(configPath, baseConfig, projectRoot) {
+  let loaded;
+  const expoConfigLoader = resolveExpoConfigLoader(projectRoot);
+  if (expoConfigLoader) {
+    loaded = expoConfigLoader(configPath);
+  } else {
+    try {
+      loaded = require(configPath);
+    } catch (error) {
+      if (error?.code !== 'ERR_REQUIRE_ESM') throw error;
+      loaded = await import(pathToFileURL(configPath).href);
+    }
+  }
+
+  const moduleValue = await loaded;
+  const exported =
+    moduleValue?.__esModule || moduleValue?.[Symbol.toStringTag] === 'Module'
+      ? moduleValue.default
+      : moduleValue;
+  const config = await exported;
+  return typeof config === 'function' ? config(baseConfig) : config;
+}
+
+module.exports = async function harnessMetroConfig(baseConfig) {
+  const projectRoot = path.resolve(
+    process.env.MM_HARNESS_METRO_PROJECT_ROOT || process.cwd(),
+  );
+  const productConfigPath = path.resolve(
+    process.env.MM_HARNESS_METRO_BASE_CONFIG ||
+      path.join(projectRoot, 'metro.config.js'),
+  );
+  if (productConfigPath === __filename) {
+    throw new Error(
+      'MM_HARNESS_METRO_BASE_CONFIG must reference the product Metro config, not the harness wrapper.',
+    );
+  }
+  let productConfig = baseConfig;
+  if (fs.existsSync(productConfigPath)) {
+    productConfig = await loadProductConfig(
+      productConfigPath,
+      baseConfig,
+      projectRoot,
+    );
+  }
+
+  const tempRoot = path.join(projectRoot, 'temp');
+  const existingBlockList =
+    productConfig.resolver?.blockList ?? baseConfig.resolver?.blockList;
+  const tempPattern = new RegExp(
+    `^${escapeRegExp(tempRoot)}(?:${escapeRegExp(path.sep)}|$)`,
+    blockListFlags(existingBlockList),
+  );
+  return {
+    ...productConfig,
+    resolver: {
+      ...productConfig.resolver,
+      blockList: appendBlockList(existingBlockList, tempPattern),
+    },
+  };
+};

package/adapters/mobile/metro-log-generation.cjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const generationIdPattern = /^[A-Za-z0-9-]+$/u;
+
+function archiveGenerationId(name) {
+  if (!name.startsWith('metro.') || !name.endsWith('.log')) return null;
+  const generationId = name.slice('metro.'.length, -'.log'.length);
+  return generationIdPattern.test(generationId) ? generationId : null;
+}
+
+function positiveInteger(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === '') return fallback;
+  if (!/^[1-9][0-9]*$/u.test(raw)) throw new Error(`${name} must be a positive integer`);
+  return Number(raw);
+}
+
+function main() {
+  const runtimeArg = process.argv[2];
+  const port = process.argv[3];
+  const reason = process.argv[4];
+  if (!runtimeArg || !/^[1-9][0-9]*$/u.test(port ?? '') || !reason) {
+    throw new Error('usage: metro-log-generation.cjs <runtime-dir> <port> <reason>');
+  }
+  const runtimeDir = fs.realpathSync(runtimeArg);
+  const activeLog = path.join(runtimeDir, 'metro.log');
+  const evidenceFile = path.join(runtimeDir, 'metro-generation.json');
+  const maxArchives = positiveInteger('MM_HARNESS_METRO_LOG_ARCHIVE_COUNT', 4);
+  const maxArchiveBytes = positiveInteger('MM_HARNESS_METRO_LOG_ARCHIVE_BYTES', 8 * 1024 * 1024);
+  const generationId = `${new Date().toISOString().replace(/[-:.]/gu, '')}-${port}-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  if (!generationIdPattern.test(generationId)) throw new Error('generated Metro log identity is invalid');
+  let rotatedLog = null;
+
+  rotatedLog = path.join(runtimeDir, `metro.${generationId}.log`);
+  try {
+    fs.renameSync(activeLog, rotatedLog);
+    const stat = fs.lstatSync(rotatedLog);
+    if (!stat.isFile()) {
+      fs.renameSync(rotatedLog, activeLog);
+      throw new Error('metro.log must be a regular file');
+    }
+  } catch (error) {
+    if (error && error.code === 'ENOENT') rotatedLog = null;
+    else throw error;
+  }
+  try {
+    fs.closeSync(fs.openSync(activeLog, 'wx', 0o600));
+  } catch (error) {
+    if (error && error.code === 'EEXIST') throw new Error('another Metro generation recreated metro.log; refusing to truncate it');
+    throw error;
+  }
+
+  const archives = fs.readdirSync(runtimeDir)
+    .filter((name) => archiveGenerationId(name) !== null)
+    .map((name) => {
+      const file = path.join(runtimeDir, name);
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile()) return null;
+      return { file, size: stat.size, mtimeMs: stat.mtimeMs };
+    })
+    .filter(Boolean)
+    .sort((left, right) => right.mtimeMs - left.mtimeMs || right.file.localeCompare(left.file));
+
+  let retainedBytes = 0;
+  let retainedCount = 0;
+  const retained = [];
+  const removed = [];
+  for (const archive of archives) {
+    if (retainedCount < maxArchives && retainedBytes + archive.size <= maxArchiveBytes) {
+      retained.push(archive.file);
+      retainedCount += 1;
+      retainedBytes += archive.size;
+      continue;
+    }
+    fs.unlinkSync(archive.file);
+    removed.push({ path: archive.file, size: archive.size, reason: retainedCount >= maxArchives ? 'count-limit' : 'size-limit' });
+  }
+
+  const evidence = {
+    schemaVersion: 1,
+    generationId,
+    port: Number(port),
+    startedAt: new Date().toISOString(),
+    currentLog: activeLog,
+    rotatedLog: rotatedLog && fs.existsSync(rotatedLog) ? rotatedLog : null,
+    archivedLogs: retained,
+    rotationReason: reason,
+    retention: { maxArchives, maxArchiveBytes, retainedBytes, removed },
+  };
+  const temporary = `${evidenceFile}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(evidence, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  fs.renameSync(temporary, evidenceFile);
+  process.stdout.write(`${JSON.stringify(evidence)}\n`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`metro-log-generation: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}

package/adapters/mobile/start-metro.sh

@@ -50,7 +50,16 @@ fi
 # only ever inspect or signal a Metro listening on $PORT.
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/metro-listener.sh"
-MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID METAMASK_BUILD_TYPE METAMASK_ENVIRONMENT}"
+HARNESS_METRO_CONFIG="$SCRIPT_DIR/metro-config.cjs"
+if [ "${EXPO_OVERRIDE_METRO_CONFIG:-}" = "$HARNESS_METRO_CONFIG" ]; then
+  PRODUCT_METRO_CONFIG="${MM_HARNESS_METRO_BASE_CONFIG:-$TARGET/metro.config.js}"
+else
+  PRODUCT_METRO_CONFIG="${EXPO_OVERRIDE_METRO_CONFIG:-$TARGET/metro.config.js}"
+fi
+export MM_HARNESS_METRO_PROJECT_ROOT="$TARGET"
+export MM_HARNESS_METRO_BASE_CONFIG="$PRODUCT_METRO_CONFIG"
+export EXPO_OVERRIDE_METRO_CONFIG="$HARNESS_METRO_CONFIG"
+MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID METAMASK_BUILD_TYPE METAMASK_ENVIRONMENT} MM_HARNESS_METRO_PROJECT_ROOT MM_HARNESS_METRO_BASE_CONFIG EXPO_OVERRIDE_METRO_CONFIG"
 
 # RECIPE_RUNTIME_DIR (relative, validated) makes runtime state per-run so jobs
 # sharing one checkout do not collide on metro.log / metro.pid / metro.tmux.
@@ -59,6 +68,8 @@ mkdir -p "$LOG_DIR"
 LOG_FILE="$LOG_DIR/metro.log"
 PID_FILE="$LOG_DIR/metro.pid"
 METRO_BUILD_ENV_FILE="$LOG_DIR/metro-build-env.sh"
+METRO_LOG_GENERATION="$SCRIPT_DIR/metro-log-generation.cjs"
+METRO_LOG_COALESCER="$SCRIPT_DIR/coalesce-metro-log.cjs"
 
 # --- helpers ------------------------------------------------------------------
 
@@ -88,6 +99,9 @@ write_metro_build_env() {
     done
   )" || { rm -f "$temporary"; return 1; }
   eval "$product_values"
+  required_MM_HARNESS_METRO_PROJECT_ROOT="$MM_HARNESS_METRO_PROJECT_ROOT"
+  required_MM_HARNESS_METRO_BASE_CONFIG="$MM_HARNESS_METRO_BASE_CONFIG"
+  required_EXPO_OVERRIDE_METRO_CONFIG="$EXPO_OVERRIDE_METRO_CONFIG"
   [ "$CLEAR" = true ] && clear_value=1
   {
     printf 'export MM_HARNESS_METRO_WATCHER_PORT=%q\n' "$PORT"
@@ -160,23 +174,21 @@ write_metro_runner() {
 #!/usr/bin/env bash
 set -uo pipefail
 cd "$(printf '%q' "$TARGET")"
-: > "$(printf '%q' "$LOG_FILE")"
 export EXPO_NO_TYPESCRIPT_SETUP=1
 export WATCHER_PORT="$(printf '%q' "$PORT")" METRO_PORT="$(printf '%q' "$PORT")"
 $worker_env_line
-BASH_ENV=$(printf '%q' "$METRO_BUILD_ENV_FILE") command yarn $(printf '%q' "$watcher_script") 2>&1 | tee -a "$(printf '%q' "$LOG_FILE")"
+BASH_ENV=$(printf '%q' "$METRO_BUILD_ENV_FILE") command yarn $(printf '%q' "$watcher_script") 2>&1 | node $(printf '%q' "$METRO_LOG_COALESCER") | tee -a "$(printf '%q' "$LOG_FILE")"
 EOF
   chmod +x "$runner"
 }
 
 start_metro_tmux() {
+  local runner="$1"
   command -v tmux >/dev/null 2>&1 || return 1
-  local session window runner
+  local session window
   session="$(resolve_run_tmux_session "$LOG_DIR")"
   { [ -n "$session" ] && tmux has-session -t "=$session" 2>/dev/null; } || return 1
   window="metro-${PORT}"
-  runner="$LOG_DIR/run-metro-${PORT}.sh"
-  write_metro_runner "$runner"
   tmux kill-window -t "${session}:${window}" >/dev/null 2>&1 || true
   tmux new-window -d -t "$session" -n "$window" "exec $(printf '%q' "$runner")" || return 1
   printf '%s:%s\n' "$session" "$window" > "$LOG_DIR/metro.tmux"
@@ -237,6 +249,14 @@ else
 fi
 printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FILE" >&2
 
+[ -f "$METRO_LOG_GENERATION" ] && [ -f "$METRO_LOG_COALESCER" ] || {
+  printf 'start-metro: Metro log generation helpers are missing; reinstall the runner\n' >&2
+  exit 1
+}
+ROTATION_REASON="metro-start"
+[ "$CLEAR" = true ] && ROTATION_REASON="clear-cache-restart"
+node "$METRO_LOG_GENERATION" "$LOG_DIR" "$PORT" "$ROTATION_REASON" >/dev/null || exit 1
+
 write_metro_build_env || {
   printf 'start-metro: could not stage the scoped Metro environment\n' >&2
   exit 1
@@ -244,13 +264,14 @@ write_metro_build_env || {
 
 STARTED_METRO_PID=""
 STARTED_METRO_TMUX=""
-if start_metro_tmux; then
+METRO_RUNNER="$LOG_DIR/run-metro-${PORT}.sh"
+write_metro_runner "$METRO_RUNNER"
+if start_metro_tmux "$METRO_RUNNER"; then
   STARTED_METRO_TMUX="$(cat "$LOG_DIR/metro.tmux" 2>/dev/null || true)"
 else
   # Metro runs detached, writing to the log. The tmux window is a read-only tail.
   (
     cd "$TARGET"
-    : > "$LOG_FILE"
     export EXPO_NO_TYPESCRIPT_SETUP=1
     export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
     if [ -n "$METRO_WORKERS" ]; then
@@ -264,6 +285,7 @@ else
       --log "$LOG_FILE"
       --pid-file "$PID_FILE"
       --build-env "$METRO_BUILD_ENV_FILE"
+      --runner "$METRO_RUNNER"
     )
     [ -z "$METRO_WORKERS" ] || launcher_args+=(--workers "$METRO_WORKERS")
     [ "$CLEAR" = true ] && launcher_args+=(--clear)

package/adapters/mobile/stop-metro.sh

@@ -83,15 +83,14 @@ if [ -n "$fwd_pid" ]; then
   esac
 fi
 rm -f "$FWD_PID_FILE"
-pkill -f "console-forwarder.cjs --port .* --out $TARGET/" 2>/dev/null
+pkill -f "console-forwarder.cjs --port $PORT --out $TARGET/" 2>/dev/null
 
-# Port-scoped stop above misses bundlers a prior launch left on a DIFFERENT port
-# (port drift / missing pid file). Sweep every Metro bound to this checkout so
-# stop fully cleans up — the leak that stacked bundlers across relaunches.
-# Guarded: the reap lib may be absent in a minimal install; skip rather than abort.
+# Reap a detached bundler for this exact port when its listener disappeared
+# before the normal stop path. Other ports in the same checkout are separate
+# runtime generations and must remain untouched.
 if [ -f "$SCRIPT_DIR/../shared/reap-checkout-metros.sh" ]; then
   . "$SCRIPT_DIR/../shared/reap-checkout-metros.sh"
-  reap_checkout_metros "$TARGET" || true
+  reap_checkout_metros_on_port "$TARGET" "$PORT" || true
 fi
 
 # Close the read-only log-tail window start-metro opened, if it is still there.

package/adapters/shared/reap-checkout-metros.sh

@@ -40,6 +40,23 @@ LIST
   return 0
 }
 
+reap_checkout_metros_on_port() {
+  local repo="$1" port="$2" reaped="" pid args
+  [ -n "$repo" ] && [ -n "$port" ] || return 0
+  while IFS= read -r pid; do
+    [ -n "$pid" ] || continue
+    args="$(ps -o args= -p "$pid" 2>/dev/null || true)"
+    case " $args " in *" --port $port "*|*" --port=$port "*) ;; *) continue ;; esac
+    kill "$pid" 2>/dev/null && reaped="$reaped $pid"
+  done <<LIST
+$(_checkout_metro_pids "$repo")
+LIST
+  if [ -n "$reaped" ]; then
+    printf 'Reaped leaked Metro bundler(s) for checkout port %s:%s\n' "$port" "$reaped" >&2
+  fi
+  return 0
+}
+
 detect_checkout_metros() {
   local repo="$1" live_port="${2:-}" pid args
   [ -n "$repo" ] || return 0

package/dist/adapters/mobile/runtime-decision.js

@@ -2,13 +2,11 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import {
-  clearDecisionState,
   depsCheck,
   recordDepsBaseline
 } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import {
   analyzeBundleLog,
-  evaluatePersistentBundleError,
   supersededErrorCapture
 } from "@farmslot/recipe-harness/runtime/log-analysis";
 import { probeMetroPackager } from "@farmslot/recipe-harness/runtime/metro-probe";
@@ -160,9 +158,6 @@ async function computeMobileReadiness(resolved, options, fast) {
   }
   const metroLog = metroLogCheck(resolved, options.metroLog);
   const metro = options.watcherPort ? await probeMetroPackager(options.watcherPort) : { status: "skipped" };
-  if (metroLog.status === "ok") {
-    clearDecisionState(resolved, "bundle-error-state.json");
-  }
   const checks = { deps, metroLog, metro };
   if (deps.status === "missing") {
     return {
@@ -229,22 +224,6 @@ async function computeMobileReadiness(resolved, options, fast) {
     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",

package/dist/commands/device-target.js

@@ -26,6 +26,7 @@ function resolveAndroidModel(serial) {
 }
 function setAndroidDeviceEnv(id, fallbackName) {
   process.env.PLATFORM = "android";
+  process.env.MM_HARNESS_EXPLICIT_PLATFORM = "android";
   process.env.ADB_SERIAL = id;
   process.env.ANDROID_SERIAL = id;
   process.env.ANDROID_DEVICE = id;
@@ -33,9 +34,11 @@ function setAndroidDeviceEnv(id, fallbackName) {
   if (model) process.env.ANDROID_TARGET_DEVICE_NAME = model;
   else delete process.env.ANDROID_TARGET_DEVICE_NAME;
   process.env.IOS_SIMULATOR = "";
+  process.env.SIM_UDID = "";
 }
 function setIosDeviceEnv(id, fallbackName) {
   process.env.PLATFORM = "ios";
+  process.env.MM_HARNESS_EXPLICIT_PLATFORM = "ios";
   process.env.IOS_SIMULATOR = fallbackName?.trim() || id;
   process.env.SIM_UDID = id;
   process.env.ADB_SERIAL = "";