@deeeed/metamask-harness 0.41.0 → 0.42.0

package/adapters/mobile/bridge-runtime/lib/devtools-proxy.cjs

@@ -0,0 +1,177 @@
+'use strict';
+
+const fs = require('node:fs');
+const { WebSocket, WebSocketServer } = require('ws');
+
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const SESSION_TIMEOUT_MS = 10_000;
+const EVENT_GATED_DOMAINS = new Set([
+  'Debugger',
+  'Log',
+  'Network',
+  'Page',
+  'ReactNativeApplication',
+  'Runtime',
+]);
+
+function createDevtoolsProxy({
+  descriptorPath,
+  sessions,
+  sendCommand,
+  requestDiscovery,
+  allowedOrigins,
+}) {
+  if (!Array.isArray(allowedOrigins) || allowedOrigins.length === 0) {
+    throw new Error('DevTools proxy requires at least one allowed Origin');
+  }
+  let listeningPort = null;
+  const clients = new Set();
+  const server = new WebSocketServer({
+    host: '127.0.0.1',
+    port: 0,
+    maxPayload: MAX_FRAME_BYTES,
+  });
+
+  async function waitForSession(deviceId) {
+    const ready = sessions.get(deviceId);
+    if (ready?.brokerReady) return ready;
+    requestDiscovery();
+    const deadline = Date.now() + SESSION_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      const session = sessions.get(deviceId);
+      if (session?.brokerReady) return session;
+    }
+    throw new Error('Hermes runtime is unavailable or reloading; retry the command');
+  }
+
+  function writeDescriptor() {
+    if (!listeningPort) return;
+    fs.writeFileSync(
+      descriptorPath,
+      `${JSON.stringify({ schemaVersion: 1, pid: process.pid, port: listeningPort })}\n`,
+      { mode: 0o600 },
+    );
+  }
+
+  async function forward(client, message) {
+    if (
+      !message ||
+      typeof message !== 'object' ||
+      !Number.isInteger(message.id) ||
+      typeof message.method !== 'string'
+    ) {
+      return;
+    }
+    if (message.method.endsWith('.disable')) {
+      client.enabled.delete(message.method.replace(/\.disable$/u, '.enable'));
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(JSON.stringify({ id: message.id, result: {} }));
+      }
+      return;
+    }
+    const isEnable = message.method.endsWith('.enable');
+    if (isEnable) {
+      client.enabled.set(message.method, message.params || {});
+    }
+    try {
+      const session = await waitForSession(client.deviceId);
+      const result = await sendCommand(
+        session,
+        message.method,
+        message.params || {},
+        SESSION_TIMEOUT_MS,
+      );
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(JSON.stringify({ id: message.id, result }));
+      }
+    } catch (error) {
+      if (isEnable) client.enabled.delete(message.method);
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(
+          JSON.stringify({
+            id: message.id,
+            error: {
+              code: -32000,
+              message: String(error?.message || error).slice(0, 256),
+            },
+          }),
+        );
+      }
+    }
+  }
+
+  server.on('connection', (socket, request) => {
+    const url = new URL(request.url || '/', 'http://127.0.0.1');
+    const deviceId = url.searchParams.get('device');
+    if (
+      !deviceId ||
+      !allowedOrigins.includes(request.headers.origin)
+    ) {
+      socket.close(1008, 'invalid DevTools proxy Origin or device');
+      return;
+    }
+    for (const client of clients) {
+      if (client.deviceId === deviceId) {
+        client.socket.close(1000, 'replaced by a newer DevTools window');
+      }
+    }
+    const client = { socket, deviceId, enabled: new Map() };
+    clients.add(client);
+    socket.on('message', (data) => {
+      let message;
+      try {
+        message = JSON.parse(String(data));
+      } catch {
+        return;
+      }
+      void forward(client, message);
+    });
+    const drop = () => clients.delete(client);
+    socket.on('close', drop);
+    socket.on('error', drop);
+  });
+
+  server.on('listening', () => {
+    const address = server.address();
+    if (!address || typeof address === 'string') return;
+    listeningPort = address.port;
+    writeDescriptor();
+  });
+
+  return {
+    onSessionOpen(deviceId, session) {
+      for (const client of clients) {
+        if (client.deviceId !== deviceId) continue;
+        for (const [method, params] of client.enabled) {
+          void sendCommand(session, method, params, SESSION_TIMEOUT_MS).catch(
+            () => undefined,
+          );
+        }
+      }
+    },
+    onCdpEvent(deviceId, method, params) {
+      const payload = JSON.stringify({ method, params });
+      const domain = method.split('.', 1)[0];
+      for (const client of clients) {
+        if (
+          client.deviceId === deviceId &&
+          client.socket.readyState === WebSocket.OPEN &&
+          (!EVENT_GATED_DOMAINS.has(domain) ||
+            client.enabled.has(`${domain}.enable`))
+        ) {
+          client.socket.send(payload);
+        }
+      }
+    },
+    close() {
+      for (const client of clients) client.socket.close();
+      server.close();
+      try {
+        fs.unlinkSync(descriptorPath);
+      } catch {}
+    },
+  };
+}
+
+module.exports = { createDevtoolsProxy };

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

@@ -138,7 +138,7 @@ function targetDeviceIdentity(target) {
  *     page 1 = native C++ runtime, page 2+ = JS runtime (where __AGENTIC__ lives)
  *   - We probe candidates to find the one with __AGENTIC__ installed
  */
-async function discoverTarget(port) {
+async function discoverTarget(port, { probe = true } = {}) {
   const listUrl = `http://localhost:${port}/json/list`;
   const androidTargetName = loadAndroidTargetDeviceName();
   const androidDevice = loadAndroidDevice();
@@ -162,7 +162,7 @@ async function discoverTarget(port) {
       if (androidPinned) {
         const pinnedCandidates = runtimeCandidates.filter(matchesAndroidPin);
         for (const candidate of pinnedCandidates) {
-          if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+          if (!probe || (await probeTarget(candidate.webSocketDebuggerUrl))) {
             acceptedPinnedCandidate = candidate;
             return true;
           }
@@ -174,7 +174,7 @@ async function discoverTarget(port) {
           (candidate) => candidate.deviceName === simName,
         );
         for (const candidate of pinnedCandidates) {
-          if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+          if (!probe || (await probeTarget(candidate.webSocketDebuggerUrl))) {
             acceptedPinnedCandidate = candidate;
             return true;
           }
@@ -307,6 +307,16 @@ async function discoverTarget(port) {
     }
   }
 
+  // The persistent console forwarder already owns and validates brokered CDP
+  // sessions. Re-probing here would evict that debugger; preserve the normal
+  // platform/device filtering and select the highest-ranked runtime instead.
+  if (!probe) {
+    return {
+      wsUrl: candidates[0].webSocketDebuggerUrl,
+      deviceName: candidates[0].deviceName || '',
+    };
+  }
+
   // Sort by page number descending (JS runtime has higher page number than C++
   // native). rankRuntimeCandidates output arrives pre-sorted; this re-sort is
   // load-bearing only when the raw targets.filter() fallback above repopulated

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/reload-app.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const WebSocket = require('ws');
+
+function parseArgs(argv) {
+  const args = { port: process.env.WATCHER_PORT || process.env.METRO_PORT || '8081', json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === '--port') args.port = argv[++index];
+    else if (argv[index] === '--json') args.json = true;
+    else if (argv[index] === '--help' || argv[index] === '-h') {
+      console.log('Usage: reload-app.mjs [--port <Metro port>] [--json]');
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${argv[index]}`);
+    }
+  }
+  return args;
+}
+
+async function reload(port) {
+  const numericPort = Number.parseInt(String(port), 10);
+  if (!Number.isInteger(numericPort) || numericPort <= 0) {
+    throw new Error(`Metro port is invalid: ${port}`);
+  }
+  await new Promise((resolve, reject) => {
+    const socket = new WebSocket(`ws://127.0.0.1:${numericPort}/message`);
+    const timeout = setTimeout(() => {
+      socket.close();
+      reject(new Error(`Metro reload timed out on port ${numericPort}`));
+    }, 5000);
+    socket.on('open', () => {
+      socket.send(JSON.stringify({ method: 'reload', version: 2 }));
+      setTimeout(() => {
+        clearTimeout(timeout);
+        socket.close();
+        resolve();
+      }, 50);
+    });
+    socket.on('error', () => {
+      clearTimeout(timeout);
+      reject(new Error(`Metro is not reachable on port ${numericPort}`));
+    });
+  });
+  return {
+    ok: true,
+    adapter: 'mobile',
+    method: 'metro-message',
+    command: 'reload',
+    port: numericPort,
+  };
+}
+
+const args = parseArgs(process.argv.slice(2));
+reload(args.port)
+  .then((result) => {
+    if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else console.log(`Reload requested through Metro :${result.port}`);
+  })
+  .catch((error) => {
+    const result = { ok: false, adapter: 'mobile', error: String(error?.message || error) };
+    if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else console.error(result.error);
+    process.exitCode = 1;
+  });

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

@@ -32,12 +32,27 @@ APP_LOG_FILE="$LOG_DIR/app-console.log"
 { [ -f "$FORWARDER" ] && command -v node >/dev/null 2>&1; } || exit 0
 mkdir -p "$LOG_DIR"
 
+stopped_pids=()
+stop_forwarder() {
+  local pid="$1"
+  case " ${stopped_pids[*]-} " in
+    *" $pid "*) return ;;
+  esac
+  stopped_pids+=("$pid")
+  kill "$pid" 2>/dev/null || true
+  for _ in {1..20}; do
+    kill -0 "$pid" 2>/dev/null || return
+    sleep 0.05
+  done
+  kill -KILL "$pid" 2>/dev/null || true
+}
+
 # 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
+      stop_forwarder "$pid"
       ;;
   esac
 done < <(ps -axo pid=,command= 2>/dev/null || true)
@@ -46,7 +61,7 @@ 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 ;;
+      *console-forwarder.cjs*) stop_forwarder "$old_pid" ;;
     esac
   fi
   rm -f "$PID_FILE"

package/adapters/mobile/start-metro.sh

@@ -4,8 +4,8 @@
 # Checks if Metro is already running and owned by this checkout with required env vars.
 # Clears stale or foreign listeners before starting. Uses the checkout's canonical
 # yarn watch script and sets EXPO_NO_TYPESCRIPT_SETUP=1. Cache clearing is
-# injected as Expo --clear without invoking Mobile's global watchman cleanup.
-# Metro owns its default worker count; METRO_MAX_WORKERS is an explicit override.
+# passed to Expo only for the explicit --clear option. Metro defaults to four
+# workers; METRO_MAX_WORKERS remains an explicit override.
 #
 # Inputs:
 #   --target <metamask-mobile dir>  (default $PWD)
@@ -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"
@@ -227,8 +227,8 @@ fi
 
 stop_metro_listener || exit 1
 
-METRO_WORKERS="${METRO_MAX_WORKERS:-}"
-if [ -n "$METRO_WORKERS" ] && ! printf '%s' "$METRO_WORKERS" | grep -Eq '^[1-9][0-9]*$'; then
+METRO_WORKERS="${METRO_MAX_WORKERS:-4}"
+if ! printf '%s' "$METRO_WORKERS" | grep -Eq '^[1-9][0-9]*$'; then
   printf 'start-metro: METRO_MAX_WORKERS must be a positive integer, got %s\n' "$METRO_WORKERS" >&2
   exit 2
 fi
@@ -240,15 +240,18 @@ fi
 CLEAR_LABEL=""
 [ "$CLEAR" = true ] && CLEAR_LABEL=", clear"
 
-if [ -n "$METRO_WORKERS" ]; then
-  printf 'Starting Metro on port %s (workers=%s%s)\n' \
-    "$PORT" "$METRO_WORKERS" "$CLEAR_LABEL" >&2
-else
-  printf 'Starting Metro on port %s (workers=Metro default%s)\n' \
-    "$PORT" "$CLEAR_LABEL" >&2
-fi
+printf 'Starting Metro on port %s (workers=%s%s)\n' \
+  "$PORT" "$METRO_WORKERS" "$CLEAR_LABEL" >&2
 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 +259,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 +280,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

@@ -21,7 +21,7 @@ while [ $# -gt 0 ]; do
   esac
 done
 
-TARGET="$(cd "$TARGET" && pwd)"
+TARGET="$(cd "$TARGET" && pwd -P)"
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
@@ -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.
@@ -103,6 +102,15 @@ if [ -f "$TMUX_FILE" ] && command -v tmux >/dev/null 2>&1; then
 fi
 rm -f "$TMUX_FILE"
 
+# A stopped checkout must not remain in Watchman's global root set. Metro will
+# add the root again on the next launch; removing only this exact target keeps
+# every other active slot untouched.
+if command -v watchman >/dev/null 2>&1; then
+  if watchman watch-del "$TARGET" >/dev/null 2>&1; then
+    printf 'Removed Watchman root %s\n' "$TARGET" >&2
+  fi
+fi
+
 # Reaching here = cleanup done (nothing needed stopping, or it stopped and
 # windows/pids were cleared). The idempotent-stop contract is success; do not
 # leak an incidental non-zero from the last command on any platform.