@deeeed/metamask-harness 0.14.5 → 0.15.0

package/adapters/mobile/lib/tmux-viewer.sh

@@ -11,11 +11,11 @@
 # resolved, skip the viewer entirely (Metro still runs detached to the log).
 #
 # Inputs (env/args): $1 = metro log path; PORT, LOG_DIR, and optional `slot` from
-# the caller; TMUX indicates we are inside a tmux client.
+# the caller.
 
-# Session resolution (RECIPE_TMUX_SESSION → agentic-runtime.json session → current
-# tmux client). Sourced relative to this lib; harness-path fallback for the
-# installed layout where shared libs live beside this file.
+# Session resolution (RECIPE_TMUX_SESSION → agentic-runtime.json session). Sourced
+# relative to this lib; harness-path fallback for the installed layout where shared
+# libs live beside this file.
 _tv_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 for _tv_src in "$_tv_dir/tmux-session.sh" "$_tv_dir/../../shared/tmux-session.sh"; do

package/adapters/mobile/open-device.sh

@@ -220,7 +220,9 @@ if [ "$PLATFORM" = "ios" ]; then
   DEV_CLIENT_SCHEME="${IOS_DEV_CLIENT_SCHEME:-expo-metamask}"
 
   boot_simulator_if_needed "$SIM_TARGET" || exit 1
-  show_simulator "$SIM_TARGET"
+  if [ "${MM_HARNESS_FOCUS_SIMULATOR:-0}" = "1" ]; then
+    show_simulator "$SIM_TARGET"
+  fi
 
   LAUNCHED=false
   for BUNDLE_ID in "${BUNDLE_IDS[@]}"; do

package/adapters/mobile/start-metro.sh

@@ -89,11 +89,8 @@ start_console_forwarder() {
   # Only one debugger can own a React Native page. Reap any forwarder already
   # attached to this Metro port, even if it was launched from another checkout or
   # package install path and therefore does not own this runtime dir's pid file.
-  while IFS= read -r line; do
-    local pid cmd
-    pid="${line%% *}"
-    cmd="${line#* }"
-    [ "$pid" != "$line" ] || continue
+  local pid cmd
+  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
@@ -227,19 +224,16 @@ if ! start_metro_tmux; then
     export EXPO_NO_TYPESCRIPT_SETUP=1
     export WATCHER_PORT="${PORT}" METRO_PORT="${PORT}"
     export METRO_MAX_WORKERS="${METRO_WORKERS}"
-    # shellcheck disable=SC2094
-    # nohup sets SIGHUP to ignored (inherited across exec), so Metro survives the
-    # launching shell or tmux window closing; when this subshell exits the process
-    # is reparented to init. nohup.out is suppressed (stdout/stderr both go to
-    # $LOG_FILE via >>).
-    metro_args=(expo start --port "$PORT")
-    [ "$CLEAR" = true ] && metro_args+=(--clear)
-    nohup yarn "${metro_args[@]}" \
-      </dev/null >> "$LOG_FILE" 2>&1 &
-    metro_pid="$!"
-    echo "$metro_pid" > "$PID_FILE"
-    disown "$metro_pid" 2>/dev/null || true
-  )
+    launcher_args=(
+      --target "$TARGET"
+      --port "$PORT"
+      --log "$LOG_FILE"
+      --pid-file "$PID_FILE"
+      --workers "$METRO_WORKERS"
+    )
+    [ "$CLEAR" = true ] && launcher_args+=(--clear)
+    node "$SCRIPT_DIR/launch-metro.cjs" "${launcher_args[@]}"
+  ) || exit 1
 
   start_viewer_window "$LOG_FILE"
 fi

package/adapters/mobile/stop-metro.sh

@@ -61,6 +61,7 @@ fi
 # incidental non-zero (platform-dependent) can never turn success into exit 1.
 set +e
 rm -f "$PID_FILE"
+rm -f "$LOG_DIR/metro-launch.json"
 
 # start-metro runs a per-checkout console-forwarder holding the device debugger
 # slot; Metro going down must take it too, or the orphan keeps polling and later

package/adapters/mobile/verify.sh

@@ -283,7 +283,7 @@ const fs = require('fs');
 const path = require('path');
 const name = 'agentic overlay matches runner (HUD freshness)';
 const harnessDir = process.env.HARNESS_DIR_FOR_DRIFT;
-const targetDir = path.join(process.env.TARGET_FOR_DRIFT, 'app', 'core', 'AgenticService');
+const targetDir = path.join(process.env.TARGET_FOR_DRIFT, 'app', 'dev-tools', 'AgenticService');
 function readTrimmed(file) {
   try { return fs.readFileSync(file, 'utf8').trim(); } catch { return ''; }
 }
@@ -298,7 +298,7 @@ if (!runnerDir) {
   process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner source unavailable; overlay freshness compare skipped' }));
   process.exit(0);
 }
-const overlayDir = path.join(runnerDir, 'adapters', 'mobile', 'overlay', 'app', 'core', 'AgenticService');
+const overlayDir = path.join(runnerDir, 'adapters', 'mobile', 'overlay', 'app', 'dev-tools', 'AgenticService');
 let checked = 0;
 const drifted = [];
 const missing = [];
@@ -318,13 +318,13 @@ try {
   process.stdout.write(JSON.stringify({ name, status: 'warn', detail: 'runner overlay compare skipped: ' + String((error && error.message) || error) }));
   process.exit(0);
 }
-if (checked === 0) {
-  process.stdout.write(JSON.stringify({ name, status: 'pass' }));
-} else if (drifted.length || missing.length) {
+if (drifted.length || missing.length) {
   const parts = [];
   if (drifted.length) parts.push('behind runner: ' + drifted.join(', '));
   if (missing.length) parts.push('absent in repo: ' + missing.join(', '));
   process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun mm-harness install --force-overlay or mm-harness fixtures sync to refresh the in-repo HUD/AgenticService from the runner' }));
+} else if (checked === 0) {
+  process.stdout.write(JSON.stringify({ name, status: 'pass' }));
 } else {
   process.stdout.write(JSON.stringify({ name, status: 'pass' }));
 }

package/adapters/shared/install-repo-deps.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TARGET=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target)
+      [[ $# -ge 2 ]] || { echo "Usage: install-repo-deps.sh --target <checkout>" >&2; exit 2; }
+      TARGET="$2"
+      shift 2
+      ;;
+    -h|--help)
+      echo "Usage: install-repo-deps.sh --target <checkout>"
+      exit 0
+      ;;
+    *) echo "Unknown flag: $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -n "$TARGET" ]] || { echo "install-repo-deps: --target is required" >&2; exit 2; }
+TARGET="$(cd "$TARGET" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/activate-repo-node.sh"
+require_repo_node "$TARGET"
+
+cd "$TARGET"
+corepack yarn install --immutable

package/adapters/shared/open-debug.mjs

@@ -75,6 +75,12 @@ function emit(result, json) {
   if (result.ok) {
     const detail = result.method ? ` via ${result.method}` : '';
     const where = result.port ? ` (port ${result.port})` : result.cdpPort ? ` (cdp ${result.cdpPort})` : '';
+    if (result.opened === false) {
+      if (result.endpoint) console.log(`Resolved debugger endpoint${detail}${where}: ${result.endpoint}`);
+      else console.log(`Debugger action not invoked${detail}${where}`);
+      if (result.detail) console.log(result.detail);
+      return;
+    }
     console.log(`Opened debugger${detail}${where}`);
     if (result.target?.url) console.log(`Target: ${result.target.url}`);
     if (result.configureHint) console.log(`Configure chrome://inspect target: ${result.configureHint}`);
@@ -144,16 +150,30 @@ async function openMobileDebugger(port, action, shouldOpen) {
   if (!Number.isInteger(numericPort) || numericPort <= 0) {
     return { ok: false, adapter: 'mobile', action: normalizedAction, error: 'invalid-port', port };
   }
+  const endpoint = `http://127.0.0.1:${numericPort}${urlPath}`;
+  if (!shouldOpen) {
+    return {
+      ok: true,
+      adapter: 'mobile',
+      action: normalizedAction,
+      method: 'metro-http',
+      endpoint,
+      port: numericPort,
+      opened: false,
+      detail: 'Open action not invoked (--no-open).',
+    };
+  }
 
   let metroError = null;
   try {
-    const opened = await fetchOk(`http://127.0.0.1:${numericPort}${urlPath}`, { method: 'POST' });
+    const opened = await fetchOk(endpoint, { method: 'POST' });
     if (opened) {
       return {
         ok: true,
         adapter: 'mobile',
         action: normalizedAction,
         method: 'metro-http',
+        endpoint,
         port: numericPort,
         opened: shouldOpen,
       };
@@ -171,6 +191,9 @@ async function openMobileDebugger(port, action, shouldOpen) {
       adapter: 'mobile',
       action: normalizedAction,
       method: 'cdp-eval',
+      endpoint: normalizedAction === 'dev-menu'
+        ? 'NativeModules.DevSettings.show()'
+        : 'NativeModules.DevSettings.openDebugger()',
       port: numericPort,
       opened: shouldOpen,
     };
@@ -181,6 +204,7 @@ async function openMobileDebugger(port, action, shouldOpen) {
     adapter: 'mobile',
     action: normalizedAction,
     method: 'metro-http',
+    endpoint,
     port: numericPort,
     error: metroError,
     hint: 'Metro may be down or the debug target is not ready. Check metro status and try again.',
@@ -214,9 +238,11 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
 
   const inspectUrl = 'chrome://inspect/#devices';
   const configureHint = `127.0.0.1:${numericPort}`;
+  const versionEndpoint = `http://127.0.0.1:${numericPort}/json/version`;
+  const listEndpoint = `http://127.0.0.1:${numericPort}/json/list`;
 
   try {
-    await fetchJson(`http://127.0.0.1:${numericPort}/json/version`);
+    await fetchJson(versionEndpoint);
   } catch (error) {
     return {
       ok: false,
@@ -224,6 +250,7 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
       targetKind,
       cdpPort: numericPort,
       error: 'cdp-unreachable',
+      endpoint: versionEndpoint,
       inspectUrl,
       configureHint,
       hint: `Start the extension runtime first (mm-harness launch). Then open chrome://inspect and add ${configureHint}.`,
@@ -233,7 +260,7 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
 
   let targets;
   try {
-    targets = await fetchJson(`http://127.0.0.1:${numericPort}/json/list`);
+    targets = await fetchJson(listEndpoint);
   } catch (error) {
     return {
       ok: false,
@@ -241,6 +268,7 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
       targetKind,
       cdpPort: numericPort,
       error: 'cdp-list-failed',
+      endpoint: listEndpoint,
       inspectUrl,
       configureHint,
       hint: `CDP is up but /json/list failed. Open chrome://inspect and add ${configureHint}.`,
@@ -255,6 +283,7 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
       targetKind,
       cdpPort: numericPort,
       error: 'cdp-list-invalid',
+      endpoint: listEndpoint,
       inspectUrl,
       configureHint,
       hint: `Open chrome://inspect and add ${configureHint}.`,
@@ -269,6 +298,7 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
       adapter: 'extension',
       targetKind,
       method: 'devtools-frontend',
+      endpoint: picked.devtoolsFrontendUrl,
       cdpPort: numericPort,
       target: {
         type: picked.type,
@@ -291,6 +321,7 @@ async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
     adapter: 'extension',
     targetKind,
     method: picked?.devtoolsFrontendUrl ? 'devtools-frontend' : 'chrome-inspect',
+    endpoint: picked?.devtoolsFrontendUrl || inspectUrl,
     cdpPort: numericPort,
     target: picked
       ? { type: picked.type, url: picked.url, title: picked.title || null }
@@ -341,4 +372,4 @@ main().catch((error) => {
     console.error(payload.error);
   }
   process.exit(1);
-});
+});

package/adapters/shared/open-log-window.sh

@@ -45,7 +45,7 @@ session=""
 command -v resolve_run_tmux_session >/dev/null 2>&1 && session="$(resolve_run_tmux_session "$RUNTIME_DIR")"
 if [ -z "$session" ] || ! tmux has-session -t "=$session" 2>/dev/null; then
   echo "open-log-window: no run-owned tmux session to place the window in." >&2
-  echo "  Next: run inside your slot's tmux session, or set RECIPE_TMUX_SESSION=<session>, then retry" >&2
+  echo "  Next: set RECIPE_TMUX_SESSION=<session>, or configure agentic-runtime.json session, then retry" >&2
   exit 1
 fi
 

package/adapters/shared/resolve-slot-ports-core.mjs

@@ -139,8 +139,77 @@ export function resolveDefaultExtensionPorts(repo) {
   });
 }
 
+function parseKvLines(output) {
+  if (!output?.trim()) return {};
+  const kv = {};
+  for (const line of output.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq);
+    const val = trimmed.slice(eq + 1);
+    if (val === 'null' || val === 'undefined' || val === '') continue;
+    kv[key] = val;
+  }
+  return kv;
+}
+
+function mergeKvLayers(...layers) {
+  const result = {};
+  for (const layer of layers) {
+    const source = typeof layer === 'string' ? layer : layer?.source;
+    const overwrite = typeof layer === 'string' ? false : Boolean(layer?.overwrite);
+    const kv = parseKvLines(source);
+    for (const [key, val] of Object.entries(kv)) {
+      if (overwrite || result[key] === undefined) result[key] = val;
+    }
+  }
+  return Object.keys(result).length ? formatKvLines(result) : '';
+}
+
+function extensionRuntimeContextPath(repo) {
+  const repoRoot = path.resolve(repo);
+  const envCtx = process.env.RECIPE_RUNTIME_CONTEXT;
+  if (envCtx) {
+    const resolved = path.resolve(envCtx);
+    if (resolved === repoRoot || resolved.startsWith(`${repoRoot}${path.sep}`)) {
+      return resolved;
+    }
+  }
+  return path.join(repoRoot, recipeRuntimeDir(), 'agentic-runtime.json');
+}
+
+export function resolveExtensionRuntimeContext(repo) {
+  const ctxPath = extensionRuntimeContextPath(repo);
+  if (!fs.existsSync(ctxPath)) return null;
+  try {
+    const c = JSON.parse(fs.readFileSync(ctxPath, 'utf8'));
+    const cdp = c.cdpPort;
+    const watcher = c.devServerPort ?? c.watcherPort ?? c.metroPort;
+    if ((cdp == null || cdp === '') && (watcher == null || watcher === '') && !c.slotId) return null;
+    return formatKvLines({
+      ...(cdp != null && cdp !== '' ? { CDP_PORT: cdp } : {}),
+      ...(watcher != null && watcher !== '' ? { WATCHER_PORT: watcher } : {}),
+      ...(c.slotId ? { SLOT_ID: c.slotId } : {}),
+    });
+  } catch {
+    return null;
+  }
+}
+
+// Checkout-scoped extension ports: runtime context (authoritative) → pool → suffix formula.
+export function formatExtensionSlotPorts(repo) {
+  const realRepo = path.resolve(repo);
+  return mergeKvLayers(
+    { source: resolveExtensionRuntimeContext(realRepo), overwrite: true },
+    { source: resolveSlotPortsByRepo(realRepo), overwrite: false },
+    { source: resolveDefaultExtensionPorts(realRepo), overwrite: false },
+  );
+}
+
 export function resolveExtensionRuntimePorts(repo) {
-  return resolveSlotPortsByRepo(repo) ?? resolveDefaultExtensionPorts(repo) ?? '';
+  return formatExtensionSlotPorts(repo);
 }
 
 export function resolveMobileSlotDefaults(repo) {
@@ -216,6 +285,8 @@ export const cliFns = {
   // Back-compat cli key for one release.
   resolve_farmslot_ports_by_repo: resolveSlotPortsByRepo,
   resolve_default_extension_ports: resolveDefaultExtensionPorts,
+  resolve_extension_runtime_context: resolveExtensionRuntimeContext,
+  resolve_extension_slot_ports: (repo) => formatExtensionSlotPorts(repo) || null,
   resolve_extension_runtime_ports: (repo) => resolveExtensionRuntimePorts(repo) || null,
   resolve_mobile_runtime_context: resolveMobileRuntimeContext,
   resolve_mobile_slot_defaults: resolveMobileSlotDefaults,

package/adapters/shared/resolve-slot-ports.sh

@@ -43,33 +43,37 @@ resolve_extension_runtime_ports() {
   _resolve_ports_cli resolve_extension_runtime_ports "${1:-.}"
 }
 
-apply_resolved_extension_ports() {
-  local repo="${1:-.}" line key val from_pool=false resolved=""
-  if resolved="$(_resolve_ports_cli resolve_slot_ports_by_repo "$repo" 2>/dev/null)"; then
-    from_pool=true
-  elif resolved="$(_resolve_ports_cli resolve_default_extension_ports "$repo" 2>/dev/null)"; then
-    from_pool=false
+resolve_extension_slot_ports() {
+  _resolve_ports_cli resolve_extension_slot_ports "${1:-.}"
+}
+
+# Apply the checkout-scoped extension port ladder (context → pool → formula).
+apply_extension_slot_ports() {
+  local repo="${1:-.}" line key val resolved="" ctx_file="" runtime_rel="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
+  repo="$(cd "$repo" && pwd)"
+  ctx_file="$repo/$runtime_rel/agentic-runtime.json"
+  if [ -f "$ctx_file" ]; then
+    export RECIPE_RUNTIME_CONTEXT="$ctx_file"
   else
-    return 0
+    unset RECIPE_RUNTIME_CONTEXT
   fi
+  resolved="$(_resolve_ports_cli resolve_extension_slot_ports "$repo" 2>/dev/null)" || return 0
   while IFS= read -r line; do
     [ -n "$line" ] || continue
     key="${line%%=*}"
     val="${line#*=}"
     case "$key" in
-      CDP_PORT)
-        if [ "$from_pool" = true ] || [ -z "${CDP_PORT:-}" ]; then CDP_PORT="$val"; fi
-        ;;
-      WATCHER_PORT)
-        if [ "$from_pool" = true ] || [ -z "${WATCHER_PORT:-}" ]; then WATCHER_PORT="$val"; fi
-        ;;
-      SLOT_ID)
-        if [ "$from_pool" = true ] || [ -z "${RECIPE_SLOT_ID:-}" ]; then RECIPE_SLOT_ID="$val"; fi
-        ;;
+      CDP_PORT) CDP_PORT="$val" ;;
+      WATCHER_PORT) WATCHER_PORT="$val" ;;
+      SLOT_ID) RECIPE_SLOT_ID="$val" ;;
     esac
   done <<< "$resolved"
 }
 
+apply_resolved_extension_ports() {
+  apply_extension_slot_ports "$@"
+}
+
 resolve_mobile_slot_defaults() {
   _resolve_ports_cli resolve_mobile_slot_defaults "$1"
 }
@@ -107,4 +111,4 @@ apply_resolved_mobile_ports() {
         ;;
     esac
   done <<< "$resolved"
-}
+}

package/adapters/shared/tmux-session.sh

@@ -7,8 +7,6 @@
 # tail -F) in the wrong place. Resolution ladder, first hit wins:
 #   1. RECIPE_TMUX_SESSION            — the orchestrator's explicit hand-off.
 #   2. agentic-runtime.json `session` — the prepared checkout's recorded session.
-#   3. the current session            — but ONLY inside a tmux client (never the
-#      last-attached session reported outside one, which would be a foreign leak).
 # Prints the resolved name (empty when none). Callers still gate on has-session
 # before creating a window.
 
@@ -28,8 +26,5 @@ resolve_run_tmux_session() {
       return 0
     fi
   fi
-  if [ -n "${TMUX:-}" ]; then
-    tmux display-message -p '#S' 2>/dev/null || true
-  fi
   return 0
 }

package/adapters/shared/tmux-viewer.sh

@@ -53,9 +53,14 @@ tmux_viewer_close_marker() {
   local marker_file="$1"
   command -v tmux >/dev/null 2>&1 || { rm -f "$marker_file"; return 0; }
   if [ -f "$marker_file" ]; then
-    local target
+    local target marker_session owned_session runtime_dir
     target="$(cat "$marker_file" 2>/dev/null || true)"
-    [ -z "$target" ] || tmux kill-window -t "$target" >/dev/null 2>&1 || true
+    marker_session="${target%%:*}"
+    runtime_dir="$(dirname "$marker_file")"
+    owned_session="$(resolve_run_tmux_session "$runtime_dir")"
+    if [ -n "$target" ] && [ -n "$owned_session" ] && [ "$marker_session" = "$owned_session" ]; then
+      tmux kill-window -t "$target" >/dev/null 2>&1 || true
+    fi
   fi
   rm -f "$marker_file"
 }

package/dist/adapters/core/surface.js

@@ -44,6 +44,9 @@ const coreSurface = {
   logSources() {
     return [];
   },
+  appLogSource() {
+    return null;
+  },
   hints: {
     launch: "mm-harness run <recipe>   # run recipes against the headless core",
     relaunch: "mm-harness verify"

package/dist/adapters/extension/ensure-ready.js

@@ -27,12 +27,6 @@ async function closeTab(port, id) {
   } catch {
   }
 }
-async function activateTab(port, id) {
-  try {
-    await fetch(`http://127.0.0.1:${port}/json/activate/${id}`, { signal: AbortSignal.timeout(4e3) });
-  } catch {
-  }
-}
 function isStrayTab(url) {
   if (typeof url !== "string") return false;
   return /^chrome:\/\/newtab\/?$/.test(url) || /^chrome:\/\/new-tab-page\b/.test(url) || url === "about:blank";
@@ -131,7 +125,6 @@ async function ensureExtensionReady(target, options) {
     for (const t of convergedTargets) {
       if (t.type === "page" && t.id && isStrayTab(t.url)) await closeTab(cdpPort, String(t.id));
     }
-    if (homesNow[0]?.id) await activateTab(cdpPort, String(homesNow[0].id));
   }
   const finalListing = await jsonList(cdpPort);
   if (!finalListing.ok) {

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

@@ -7,7 +7,7 @@ import {
   INSTALL_MARKERS,
   recordDepsBaseline
 } from "@farmslot/recipe-harness/runtime/deps-readiness";
-import { recipeHarnessPath, recipeWatchLogCandidates } from "../../paths.js";
+import { recipeHarnessPath, recipeRuntimeDir, recipeWatchLogCandidates } from "../../paths.js";
 const WEBPACK_DIRECT_INPUTS = ["package.json", "yarn.lock", ".yarnrc.yml", ".tool-versions"];
 const WEBPACK_RECURSIVE_INPUTS = ["development/webpack"];
 const WEBPACK_CACHE_DIR = "node_modules/.cache/webpack";
@@ -152,6 +152,80 @@ function latestDistMtime(target) {
   walk2(distDir);
   return latest;
 }
+function runtimeDistCheck(target) {
+  const dist = path.join(target, "dist/chrome");
+  const runtimeDist = path.join(
+    target,
+    recipeRuntimeDir(),
+    process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist"
+  );
+  if (!fs.existsSync(path.join(runtimeDist, "manifest.json"))) return { status: "missing" };
+  let output;
+  try {
+    output = execFileSync("rsync", [
+      "-rni",
+      "--exclude",
+      "_metadata",
+      "--out-format=%n",
+      `${dist}${path.sep}`,
+      `${runtimeDist}${path.sep}`
+    ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      try {
+        const modified2 = filesystemSnapshotDiff(dist, runtimeDist).slice(0, 10);
+        return modified2.length > 0 ? { status: "stale", comparison: "filesystem-quick", modified: modified2 } : { status: "fresh", comparison: "filesystem-quick" };
+      } catch (fallbackError) {
+        return {
+          status: "unknown",
+          error: `snapshot comparison failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`
+        };
+      }
+    }
+    const status = error.status;
+    return {
+      status: "unknown",
+      error: `rsync snapshot comparison failed${typeof status === "number" ? ` with exit ${status}` : ""}`
+    };
+  }
+  const modified = output.split("\n").map((line) => line.trim()).filter(Boolean).slice(0, 10);
+  return modified.length > 0 ? { status: "stale", comparison: "rsync-quick", modified } : { status: "fresh", comparison: "rsync-quick" };
+}
+function filesystemSnapshotDiff(source, snapshot) {
+  const sourceEntries = snapshotEntries(source);
+  const snapshotEntriesByPath = snapshotEntries(snapshot);
+  const paths = [.../* @__PURE__ */ new Set([...sourceEntries.keys(), ...snapshotEntriesByPath.keys()])].sort();
+  return paths.filter((relative) => {
+    const left = sourceEntries.get(relative);
+    const right = snapshotEntriesByPath.get(relative);
+    return left === void 0 || right === void 0 || JSON.stringify(left) !== JSON.stringify(right);
+  });
+}
+function snapshotEntries(root) {
+  const entries = /* @__PURE__ */ new Map();
+  const walk2 = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name === "_metadata") continue;
+      const absolute = path.join(directory, entry.name);
+      const relative = path.relative(root, absolute);
+      const stat = fs.lstatSync(absolute);
+      if (entry.isDirectory()) {
+        entries.set(relative, { type: "directory" });
+        walk2(absolute);
+      } else if (entry.isSymbolicLink()) {
+        entries.set(relative, { type: "symlink", link: fs.readlinkSync(absolute) });
+      } else if (entry.isFile()) {
+        entries.set(relative, {
+          type: "file",
+          size: stat.size,
+          mtimeSeconds: Math.floor(stat.mtimeMs / 1e3)
+        });
+      }
+    }
+  };
+  walk2(root);
+  return entries;
+}
 function distCheck(target) {
   const manifestPath = path.join(target, "dist/chrome/manifest.json");
   if (!fs.existsSync(manifestPath)) return { status: "no-build" };
@@ -206,8 +280,9 @@ async function decideExtensionReadiness(target, options = {}) {
   const webpackCache = webpackCacheCheck(resolved);
   const buildLog = buildLogCheck(resolved, options.watchLog);
   const dist = distCheck(resolved);
+  const runtimeDist = runtimeDistCheck(resolved);
   const cdp = await cdpCheck(resolved, options.cdpPort, options.pageMode);
-  const checks = { deps, webpackCache, buildLog, dist, cdp };
+  const checks = { deps, webpackCache, buildLog, dist, runtimeDist, cdp };
   const install = [{ id: "yarn-install", argv: ["yarn", "install", "--immutable"], cwd: resolved }];
   const relaunch = [{ id: "relaunch-browser" }];
   const cacheStale = buildLog.reason === "stale-cache";
@@ -259,6 +334,20 @@ async function decideExtensionReadiness(target, options = {}) {
       reasons: [dist.reason === "uncommitted-source" ? `Uncommitted source since the build (${dist.modified?.length ?? 0} file(s)); rebuild.` : `dist git id ${dist.distGitId} != HEAD ${dist.head}; rebuild.`],
       actions: buildAction(resolved, false)
     },
+    {
+      when: runtimeDist.status === "unknown",
+      decision: "blocked",
+      reasonCode: "runtime-dist-check-failed",
+      reasons: [runtimeDist.error ?? "The loaded runtime snapshot could not be compared with dist/chrome."],
+      actions: []
+    },
+    {
+      when: runtimeDist.status !== "fresh",
+      decision: "relaunch",
+      reasonCode: runtimeDist.status === "missing" ? "runtime-dist-missing" : "runtime-dist-stale",
+      reasons: [runtimeDist.status === "missing" ? "The loaded runtime snapshot is missing; launch before proving behavior." : `The loaded runtime snapshot differs from dist/chrome (${runtimeDist.modified?.length ?? 0} file(s)); reload before proving behavior.`],
+      actions: relaunch
+    },
     {
       when: cdp.status === "pass",
       decision: "ready",
@@ -305,5 +394,6 @@ function buildAction(target, clean) {
 export {
   decideExtensionReadiness,
   isExtensionDistStale,
-  recordReadinessBaseline
+  recordReadinessBaseline,
+  runtimeDistCheck
 };