@deeeed/metamask-harness 0.41.0 → 0.41.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## 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

package/adapters/manifest.json

@@ -39,9 +39,25 @@
       "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",

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-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

@@ -68,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 ------------------------------------------------------------------
 
@@ -172,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"
@@ -249,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
@@ -256,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
@@ -276,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/launch/index.js

@@ -53,6 +53,21 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "jsonStream"
 ]);
 const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
+function metroLaunchEvidence(adapter, target) {
+  if (adapter !== "mobile") return void 0;
+  const evidencePath = recipeRuntimePath(target, "metro-generation.json");
+  let descriptor;
+  try {
+    descriptor = fs.openSync(evidencePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > 256 * 1024) return void 0;
+    return JSON.parse(fs.readFileSync(descriptor, "utf8"));
+  } catch {
+    return void 0;
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+  }
+}
 async function handleLaunch(argv) {
   const { options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
@@ -627,14 +642,15 @@ async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget,
         platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
         tier,
         recovered: state.recovered,
-        mutations: state.mutations
+        mutations: state.mutations,
+        metro: metroLaunchEvidence(adapter, target)
       });
     }
     return exitCode;
   }
-  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, state);
+  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, target, state);
 }
-function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, state) {
+function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, target, state) {
   if (stream.enabled) {
     for (const mutation of state.mutations) stream.mutation(mutation);
     for (const recovery of state.recovered) stream.recovery(recovery);
@@ -643,7 +659,8 @@ function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, stat
       platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
       tier,
       recovered: state.recovered,
-      mutations: state.mutations
+      mutations: state.mutations,
+      metro: metroLaunchEvidence(adapter, target)
     });
   } else if (json) {
     console.log(
@@ -658,6 +675,7 @@ function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, stat
           phase: "launch",
           recovered: state.recovered,
           mutations: state.mutations,
+          metro: metroLaunchEvidence(adapter, target),
           exitCode: EXIT.ok
         },
         null,
@@ -706,7 +724,8 @@ function launchFail(json, stream, adapter, mobileTarget, tier, state, target, fa
       recovered: state.recovered,
       mutations: state.mutations,
       recoverable: failure.recoverable,
-      attemptedRecoveries: state.attemptedRecoveries
+      attemptedRecoveries: state.attemptedRecoveries,
+      metro: metroLaunchEvidence(adapter, target)
     });
   } else if (json) {
     console.log(
@@ -723,6 +742,7 @@ function launchFail(json, stream, adapter, mobileTarget, tier, state, target, fa
           mutations: state.mutations,
           recoverable: failure.recoverable,
           attemptedRecoveries: state.attemptedRecoveries,
+          metro: metroLaunchEvidence(adapter, target),
           exitCode: failure.exitCode,
           error: {
             code: failure.code,

package/docs/QA.md

@@ -124,6 +124,8 @@ mm-harness debug
 - [ ] Status matches verified product routes: `Login`/`LockScreen` are locked;
   `WalletView` is unlocked.
 - [ ] App and Metro logs are separate.
+- [ ] A restarted Metro rotates the previous `metro.log`, records its generation and retention actions in launch JSON, and classifies bundle failures only from the current log.
+- [ ] `mm-harness logs --full` preserves errors, completion, and meaningful timestamped bundle progress without repeated same-percentage module counts.
 - [ ] A JS edit rebuilds through Metro and appears after reload without a native
   rebuild; revert restores a clean tree.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.41.0",
+  "version": "0.41.1",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"