@deeeed/metamask-harness 0.41.0 → 0.42.0

package/adapters/shared/open-debug.mjs

@@ -2,12 +2,23 @@
 /**
  * open-debug.mjs — open human-facing debugger UIs for recipe runtimes.
  *
- * Mobile: Metro /open-debugger or /open-dev-menu HTTP endpoints.
+ * Mobile: broker-backed React Native DevTools or Metro /open-dev-menu.
  * Extension: Chrome DevTools frontend for an extension page or service worker.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
 import http from 'node:http';
 import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const {
+  discoverTarget,
+} = require('../mobile/bridge-runtime/lib/target-discovery.cjs');
+const {
+  deviceIdFromUrl,
+} = require('../mobile/bridge-runtime/lib/cdp-broker.cjs');
 
 function usage() {
   console.error(`Usage:
@@ -236,6 +247,9 @@ async function tryDevSettingsCdpFallback(numericPort, normalizedAction) {
 
 async function openMobileDebugger(port, action, shouldOpen) {
   const normalizedAction = action === 'dev-menu' ? 'dev-menu' : 'debug';
+  if (normalizedAction === 'debug') {
+    return openBrokeredMobileDebugger(port, shouldOpen);
+  }
   const urlPath = normalizedAction === 'dev-menu' ? '/open-dev-menu' : '/open-debugger';
   const numericPort = Number.parseInt(String(port), 10);
   if (!Number.isInteger(numericPort) || numericPort <= 0) {
@@ -302,6 +316,162 @@ async function openMobileDebugger(port, action, shouldOpen) {
   };
 }
 
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function openBrokeredMobileDebugger(port, shouldOpen) {
+  const numericPort = Number.parseInt(String(port), 10);
+  if (!Number.isInteger(numericPort) || numericPort <= 0) {
+    return { ok: false, adapter: 'mobile', action: 'debug', error: 'invalid-port', port };
+  }
+  const runtimeDir = path.resolve(
+    process.cwd(),
+    process.env.RECIPE_RUNTIME_DIR || path.join('temp', 'recipe', 'runtime'),
+  );
+  const descriptorPath = path.join(runtimeDir, 'devtools-proxy.json');
+  let descriptor;
+  try {
+    descriptor = JSON.parse(fs.readFileSync(descriptorPath, 'utf8'));
+  } catch {
+    descriptor = null;
+  }
+  if (
+    descriptor?.schemaVersion !== 1 ||
+    !Number.isInteger(descriptor.port) ||
+    descriptor.port <= 0 ||
+    !processIsAlive(descriptor.pid)
+  ) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: 'debug',
+      error: 'broker-unavailable',
+      port: numericPort,
+      hint: 'Start the Mobile runtime first: mm-harness launch ios|android',
+    };
+  }
+
+  let target;
+  try {
+    const selected = await discoverTarget(numericPort, { probe: false });
+    const targets = await fetchJson(`http://127.0.0.1:${numericPort}/json/list`);
+    const selectedUrl = new URL(selected.wsUrl);
+    target = targets.find(
+      (candidate) => {
+        try {
+          const candidateUrl = new URL(candidate.webSocketDebuggerUrl);
+          return (
+            candidateUrl.pathname === selectedUrl.pathname &&
+            candidateUrl.search === selectedUrl.search
+          );
+        } catch {
+          return false;
+        }
+      },
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: 'debug',
+      error: 'target-unavailable',
+      port: numericPort,
+      hint: 'Wait for the app runtime, then retry: mm-harness debug',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+  if (!target?.webSocketDebuggerUrl) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: 'debug',
+      error: 'target-unavailable',
+      port: numericPort,
+      hint: 'Wait for the app runtime, then retry: mm-harness debug',
+    };
+  }
+
+  const deviceId = deviceIdFromUrl(target.webSocketDebuggerUrl);
+  const proxyPath = `/devtools?device=${encodeURIComponent(deviceId)}`;
+  const publicProxyEndpoint = `ws://127.0.0.1:${descriptor.port}${proxyPath}`;
+  const params = new URLSearchParams([
+    ['ws', `127.0.0.1:${descriptor.port}${proxyPath}`],
+    ['sources.hide_add_folder', 'true'],
+    ['unstable_enableNetworkPanel', 'true'],
+  ]);
+  if (target.appId) params.set('appId', target.appId);
+  const frontendUrl = `http://127.0.0.1:${numericPort}/debugger-frontend/rn_fusebox.html?${params}`;
+  if (!shouldOpen) {
+    return {
+      ok: true,
+      adapter: 'mobile',
+      action: 'debug',
+      method: 'broker-proxy',
+      endpoint: publicProxyEndpoint,
+      port: numericPort,
+      opened: false,
+    };
+  }
+
+  try {
+    const mobileRequire = createRequire(path.join(process.cwd(), 'package.json'));
+    const dotslash = mobileRequire('fb-dotslash');
+    const shellPackage = mobileRequire.resolve(
+      '@react-native/debugger-shell/package.json',
+    );
+    const shellDescriptor = path.join(
+      path.dirname(shellPackage),
+      'bin',
+      'react-native-devtools',
+    );
+    const windowKey = createHash('sha256')
+      .update([frontendUrl, target.appId || '', deviceId].join('-'))
+      .digest('hex');
+    await new Promise((resolve, reject) => {
+      const child = spawn(
+        dotslash,
+        [
+          shellDescriptor,
+          `--frontendUrl=${frontendUrl}`,
+          `--windowKey=${windowKey}`,
+        ],
+        { detached: true, stdio: 'ignore' },
+      );
+      child.once('spawn', resolve);
+      child.once('error', reject);
+      child.unref();
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: 'debug',
+      error: 'devtools-launch-failed',
+      endpoint: publicProxyEndpoint,
+      port: numericPort,
+      hint: 'Install the checkout dependencies, then retry: mm-harness debug',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  return {
+    ok: true,
+    adapter: 'mobile',
+    action: 'debug',
+    method: 'broker-proxy',
+    endpoint: publicProxyEndpoint,
+    port: numericPort,
+    opened: true,
+  };
+}
+
 function pickExtensionTarget(targets, targetKind) {
   const extensionTargets = targets.filter((target) => String(target.url || '').startsWith('chrome-extension://'));
   if (targetKind === 'worker') {

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/extension/network-observer.js

@@ -0,0 +1,300 @@
+import path from "node:path";
+import { WebSocket } from "ws";
+import brokerModule from "../../../adapters/mobile/bridge-runtime/lib/cdp-broker.cjs";
+const DEVICE_ID = "extension";
+const COMMAND_TIMEOUT_MS = 1e4;
+const EXTENSION_TARGET_TYPES = /* @__PURE__ */ new Set([
+  "background_page",
+  "other",
+  "page",
+  "service_worker"
+]);
+const { brokerSocketPath, createBrokerClient, createCdpBroker } = brokerModule;
+async function createExtensionNetworkObserver(cdpPort, runtimeDir) {
+  if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
+    throw new Error("Extension network observation requires a valid CDP port.");
+  }
+  const [version, targets] = await Promise.all([
+    fetchJson(`http://127.0.0.1:${cdpPort}/json/version`),
+    fetchJson(`http://127.0.0.1:${cdpPort}/json`)
+  ]);
+  const browserWebSocketUrl = String(
+    asRecord(version).webSocketDebuggerUrl ?? ""
+  );
+  const extensionId = extensionIdFromTargets(targets);
+  if (!browserWebSocketUrl || !extensionId) {
+    throw new Error(
+      "Extension CDP browser or loaded extension target is unavailable."
+    );
+  }
+  const socket = new WebSocket(browserWebSocketUrl);
+  await waitForOpen(socket);
+  let nextId = 0;
+  let closed = false;
+  const brokerRef = {};
+  const pending = /* @__PURE__ */ new Map();
+  const targetSessions = /* @__PURE__ */ new Map();
+  const attaching = /* @__PURE__ */ new Set();
+  const send = (method, params = {}, sessionId, timeoutMs = COMMAND_TIMEOUT_MS) => new Promise((resolve, reject) => {
+    const id = ++nextId;
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`Extension CDP command timed out: ${method}`));
+    }, timeoutMs);
+    pending.set(id, { resolve, reject, timer });
+    socket.send(
+      JSON.stringify({
+        id,
+        method,
+        params,
+        ...sessionId ? { sessionId } : {}
+      })
+    );
+  });
+  const relevantTarget = (target) => {
+    if (!EXTENSION_TARGET_TYPES.has(String(target.type))) return false;
+    try {
+      return new URL(String(target.url)).hostname === extensionId;
+    } catch {
+      return false;
+    }
+  };
+  const refreshBrokerSession = () => {
+    if (!brokerRef.current) return;
+    brokerRef.current.onSessionClose(DEVICE_ID);
+    brokerRef.current.onSessionOpen(DEVICE_ID);
+  };
+  const attachTarget = async (target) => {
+    if (closed || !relevantTarget(target) || targetSessions.has(target.targetId) || attaching.has(target.targetId)) {
+      return;
+    }
+    attaching.add(target.targetId);
+    try {
+      const result = asRecord(
+        await send("Target.attachToTarget", {
+          targetId: target.targetId,
+          flatten: true
+        })
+      );
+      const sessionId = String(result.sessionId ?? "");
+      if (sessionId) {
+        targetSessions.set(target.targetId, sessionId);
+        refreshBrokerSession();
+      }
+    } catch (error) {
+      if (!/already attached/iu.test(String(error))) {
+        brokerRef.current?.onSessionClose(DEVICE_ID);
+      }
+    } finally {
+      attaching.delete(target.targetId);
+    }
+  };
+  socket.on("message", (data) => {
+    let message;
+    try {
+      message = JSON.parse(String(data));
+    } catch {
+      return;
+    }
+    if (message.id && pending.has(message.id)) {
+      const command = pending.get(message.id);
+      pending.delete(message.id);
+      if (!command) return;
+      clearTimeout(command.timer);
+      if (message.error) {
+        command.reject(
+          new Error(
+            String(message.error.message ?? "Extension CDP command failed")
+          )
+        );
+      } else {
+        command.resolve(message.result ?? {});
+      }
+      return;
+    }
+    if (message.method === "Target.targetCreated") {
+      const target = asTargetInfo(message.params?.targetInfo);
+      if (target) void attachTarget(target);
+      return;
+    }
+    if (message.method === "Target.attachedToTarget") {
+      const target = asTargetInfo(message.params?.targetInfo);
+      const sessionId = String(message.params?.sessionId ?? "");
+      if (target && sessionId && relevantTarget(target)) {
+        targetSessions.set(target.targetId, sessionId);
+        refreshBrokerSession();
+      }
+      return;
+    }
+    if (message.method === "Target.detachedFromTarget") {
+      const sessionId = String(message.params?.sessionId ?? "");
+      for (const [targetId, activeSessionId] of targetSessions) {
+        if (activeSessionId !== sessionId) continue;
+        targetSessions.delete(targetId);
+        refreshBrokerSession();
+      }
+      return;
+    }
+    if (message.sessionId && message.method?.startsWith("Network.")) {
+      brokerRef.current?.onCdpEvent(
+        DEVICE_ID,
+        message.method,
+        message.params ?? {}
+      );
+    }
+  });
+  socket.on("close", () => {
+    if (!closed) brokerRef.current?.onSessionClose(DEVICE_ID);
+    for (const command of pending.values()) {
+      clearTimeout(command.timer);
+      command.reject(new Error("Extension browser CDP connection closed"));
+    }
+    pending.clear();
+  });
+  await send("Target.setDiscoverTargets", { discover: true });
+  const targetResult = asRecord(await send("Target.getTargets"));
+  const targetInfos = Array.isArray(targetResult.targetInfos) ? targetResult.targetInfos : [];
+  await Promise.all(
+    targetInfos.map(asTargetInfo).filter((target) => Boolean(target)).map(attachTarget)
+  );
+  if (targetSessions.size === 0) {
+    socket.close();
+    throw new Error("Extension CDP exposes no attachable extension targets.");
+  }
+  const sessions = /* @__PURE__ */ new Map([[DEVICE_ID, { brokerReady: true }]]);
+  const socketPath = brokerSocketPath(
+    path.join(runtimeDir, "extension-network")
+  );
+  brokerRef.current = createCdpBroker({
+    socketPath,
+    sessions,
+    async sendCommand(_session, method, params, timeoutMs) {
+      const sessionIds = [...new Set(targetSessions.values())];
+      if (sessionIds.length === 0) {
+        throw new Error(
+          "Extension CDP has no active extension target sessions."
+        );
+      }
+      const results = await Promise.allSettled(
+        sessionIds.map(
+          (sessionId) => send(method, params, sessionId, timeoutMs)
+        )
+      );
+      const successes = results.filter(
+        (result) => result.status === "fulfilled"
+      );
+      if (successes.length === 0) {
+        const firstFailure = results.find(
+          (result) => result.status === "rejected"
+        );
+        throw new Error(
+          `Extension CDP command failed on every target: ${String(firstFailure?.reason ?? method)}`
+        );
+      }
+      if (successes.length !== results.length) {
+        results.forEach((result, index) => {
+          if (result.status === "fulfilled") return;
+          const failedSession = sessionIds[index];
+          for (const [targetId, sessionId] of targetSessions) {
+            if (sessionId === failedSession) targetSessions.delete(targetId);
+          }
+        });
+        brokerRef.current?.onSessionClose(DEVICE_ID);
+      }
+      return successes[0].value;
+    },
+    requestDiscovery() {
+      void send("Target.getTargets").then((result) => {
+        const infos = asRecord(result).targetInfos;
+        if (!Array.isArray(infos)) return;
+        for (const value of infos) {
+          const target = asTargetInfo(value);
+          if (target) void attachTarget(target);
+        }
+      }).catch(() => brokerRef.current?.onSessionClose(DEVICE_ID));
+    }
+  });
+  brokerRef.current.onSessionOpen(DEVICE_ID);
+  await waitForSocket(socketPath);
+  const client = await createBrokerClient(
+    socketPath,
+    DEVICE_ID,
+    COMMAND_TIMEOUT_MS
+  );
+  return {
+    start(params) {
+      return client.control("capture-start", params, COMMAND_TIMEOUT_MS);
+    },
+    async end(id) {
+      return asRecord(
+        await client.control("capture-end", { id }, COMMAND_TIMEOUT_MS)
+      );
+    },
+    async close() {
+      closed = true;
+      client.close();
+      brokerRef.current?.close();
+      socket.close();
+    }
+  };
+}
+async function fetchJson(url) {
+  const response = await fetch(url);
+  if (!response.ok)
+    throw new Error(`Extension CDP returned HTTP ${response.status}.`);
+  return response.json();
+}
+function extensionIdFromTargets(targets) {
+  const values = Array.isArray(targets) ? targets : [];
+  for (const target of values) {
+    const info = asTargetInfo(target);
+    if (!info) continue;
+    try {
+      const url = new URL(info.url);
+      if (url.protocol !== "chrome-extension:") continue;
+      const extensionId = url.hostname;
+      if (extensionId) return extensionId;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asTargetInfo(value) {
+  const target = asRecord(value);
+  const targetId = String(target.targetId ?? target.id ?? "");
+  const type = String(target.type ?? "");
+  const url = String(target.url ?? "");
+  return targetId && type && url ? { targetId, type, url } : null;
+}
+function waitForOpen(socket) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      socket.close();
+      reject(new Error("Extension browser CDP connection timed out."));
+    }, COMMAND_TIMEOUT_MS);
+    socket.once("open", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+    socket.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+async function waitForSocket(socketPath) {
+  const { existsSync } = await import("node:fs");
+  const deadline = Date.now() + COMMAND_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (existsSync(socketPath)) return;
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error("Extension network observer broker did not start.");
+}
+export {
+  createExtensionNetworkObserver
+};

package/dist/adapters/mobile/metro-env.js

@@ -32,10 +32,6 @@ function mobileMetroEnvCheck(target) {
     status: marker === null ? "missing" : marker.fingerprint === fingerprint ? "current" : "changed"
   };
 }
-function applyMobileMetroEnvPolicy(target, actions) {
-  if (mobileMetroEnvCheck(target).status === "current") return actions;
-  return actions.map((action) => action.id === "start-metro" && !action.argv?.includes("--clear") ? { ...action, argv: [...action.argv ?? [], "--clear"] } : action);
-}
 function recordMobileMetroEnvBaseline(target, expectedFingerprint) {
   if (mobileMetroEnvFingerprint(target) !== expectedFingerprint) return false;
   const marker = recipeRuntimePath(target, BASELINE_FILE);
@@ -69,7 +65,6 @@ function readBaseline(target) {
   }
 }
 export {
-  applyMobileMetroEnvPolicy,
   mobileMetroEnvCheck,
   mobileMetroEnvFingerprint,
   recordMobileMetroEnvBaseline

package/dist/adapters/mobile/prepare.js

@@ -9,7 +9,6 @@ import {
   launchActions
 } from "./runtime-decision.js";
 import {
-  applyMobileMetroEnvPolicy,
   mobileMetroEnvCheck,
   recordMobileMetroEnvBaseline
 } from "./metro-env.js";
@@ -241,9 +240,8 @@ function withAppRestart(actions, restartApp) {
 }
 async function dispatchActionSequence(requestedActions, target, platform, json, preflightMode, watcherPort) {
   const resolved = path.resolve(target);
-  const actions = applyMobileMetroEnvPolicy(resolved, requestedActions);
   let pendingMetroEnvFingerprint;
-  for (const action of actions) {
+  for (const action of requestedActions) {
     if (action.id === "start-metro") {
       pendingMetroEnvFingerprint = mobileMetroEnvCheck(resolved).fingerprint;
     }

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

@@ -2,20 +2,18 @@ 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";
 import { recipeRuntimePath } from "../../paths.js";
 import { resolveMobileToolPath } from "../../../library/actions/mobile/platform/tool-paths.mjs";
 import { mobileProductMarkers } from "./deps-markers.js";
-import { applyMobileMetroEnvPolicy, mobileMetroEnvCheck } from "./metro-env.js";
+import { mobileMetroEnvCheck } from "./metro-env.js";
 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;
@@ -132,13 +130,10 @@ async function decideMobileReadiness(target, options = {}) {
     decision: "launch",
     reasonCode: report.decision === "ready" ? env.status === "missing" ? "metro-env-baseline-missing" : "metro-env-changed" : report.reasonCode,
     reasons: [
-      env.status === "missing" ? "Metro environment has no successful bundle baseline; restart once with a cleared transform cache." : "Metro environment inputs changed since the successful bundle baseline; restart once with a cleared transform cache.",
+      env.status === "missing" ? "Metro environment has no successful bundle baseline; restart Metro to load the current environment without clearing its transform cache." : "Metro environment inputs changed since the successful bundle baseline; restart Metro without clearing its transform cache. Pass --clear-metro only if stale transforms are observed.",
       ...report.reasons
     ],
-    actions: applyMobileMetroEnvPolicy(
-      resolved,
-      report.decision === "ready" ? launchActions(resolved) : report.actions
-    )
+    actions: report.decision === "ready" ? launchActions(resolved) : report.actions
   };
 }
 async function computeMobileReadiness(resolved, options, fast) {
@@ -160,9 +155,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 {
@@ -221,7 +213,7 @@ async function computeMobileReadiness(resolved, options, fast) {
       checks,
       actions: [
         { id: "rebuild-native-dev-client" },
-        ...launchActions(resolved, true)
+        ...launchActions(resolved)
       ]
     };
   }
@@ -229,22 +221,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",
@@ -252,11 +228,11 @@ async function computeMobileReadiness(resolved, options, fast) {
         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.",
+          metroLog.reason === "stale-bundle-error" ? "Metro log shows prior bundle failures but cited modules are installed; restart Metro without clearing the cache. Pass --clear-metro if the failure persists." : "Metro bundle is failing with current deps; restart Metro without clearing the cache. Pass --clear-metro if the failure persists.",
           ...excerpt ? [excerpt] : []
         ],
         checks,
-        actions: launchActions(resolved, true)
+        actions: launchActions(resolved)
       };
     }
     return {