@deeeed/metamask-harness 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## Unreleased
+
+## 0.14.1 - 2026-07-09
+
+### Added
+- `mm-harness check diff` runs bounded repo-local validation for the active git diff, writing `validation-summary.json`/`.md` plus per-check logs. The fast profile runs changed-file ESLint, Prettier, and changed test files; `--profile full` also runs the repo typecheck when available. The default base follows the active PR base or repo remote HEAD before falling back to common branch names.
+- `mm-harness run` writes a concise human report (`report.md`) and prints a colored step summary for every adapter, so successful Core/Mobile/Extension recipe runs are scannable without opening raw trace files.
+
+### Fixed
+- Mobile slot targeting now refuses a platform launch/run/call when `--platform ios|android` conflicts with the configured default target, preventing an iOS-pinned slot from silently stealing a shared Android device; `status` and `doctor` scope device lists to the configured target by default and `status` reports other reachable bridges as additional targets that can be driven with `--device`.
+- Mobile `status` bases `Next:` on the configured default target only, avoids assigning an additional Android bridge to a same-platform selected device, and reports stale Android reverse ports when the selected device is not connected to the slot Metro.
+- Mobile `doctor` now reports the same additional reachable targets as `status`, so diagnostics and the home view agree on which devices can be driven with `--device`.
+- Mobile `status` and `doctor` reuse one bridge probe for scoped and additional reachable devices, preserving the bounded probe window when the bridge is down.
+- Mobile slot env resolution now preserves a configured Android Metro device name when an ADB serial is also present, instead of overwriting it with the serial.
+- `mm-harness run <action-name>` now teaches `mm-harness call <action-name>` when the argument matches an action instead of a recipe, before requiring `--artifacts-dir`.
+- Core Perps recipes now fail fast with a targeted `yarn install --immutable` teaching step when the target checkout is missing controller dependencies, including Perps actions reached through called library flows.
+- Extension quick reattach refreshes the loaded runtime-dist in place and preserves an explicitly requested dapp/start URL instead of closing it during fullscreen cleanup.
+- `mm-harness check diff` ignores its own artifact directory when that directory lives inside the target checkout, so repeated runs do not validate generated check artifacts.
+- Mobile launch treats missing slot simulators or missing dev clients as provisioning failures, not Metro-healable failures, and prints the matching `mm-harness provision runway ios` recovery command without retrying the wrong layer.
+- Mobile Runway provisioning recreates a deleted slot simulator by resolving the latest available iOS runtime and iPhone simulator type from `simctl`, so accidental simulator deletion is one-command repairable.
+- Extension readiness validates local-only CDP websocket targets and sanitizes slot title data before stamping browser tab titles.
+
+## 0.14.0 - 2026-07-08
+
+### Added
+- `mm-harness call` accepts action fields as direct `key=value` shorthand in addition to repeated `--arg k=v`, so commands like `mm-harness call ui.navigate page=perps` now match the examples agents naturally write.
+- Packaged recipes are grouped by domain under `library/recipes/<domain>/` and still resolve by dotted names (`perps.smoke`, `runner.smoke`) with legacy aliases for the former flat names.
+- Packaged `perps.smoke` recipes for mobile, extension, and core provide an explicit non-mutating Perps domain smoke. The existing bare `smoke` alias remains a runner/transport smoke for compatibility.
+
+### Fixed
+- The top-level help SLOT banner now labels the slot dev-server port by adapter, so extension checkouts show `webpack :<port>` instead of the mobile-only `metro :<port>`.
+- Hidden internal runtime commands remain executable through the installed `mm-harness` bin, fixing Extension verify warnings where `runtime-decision` returned `{}` because the wrapper blocked its own shipped helper.
+- Extension launch/readiness now stamps the live home tab title with the Farmslot slot id after MetaMask has settled, so headed browser windows identify their owning slot.
+- Extension quick launch now reattaches to a live slot browser when CDP belongs to this checkout's Chrome profile and dist is fresh, even if the webpack watcher is not currently listening; foreign CDP profiles still force the clean path.
+- `status` now hydrates slot runtime context before device enumeration, so a Farmslot checkout pinned to `IOS_SIMULATOR=mm-1` reports only the selected slot simulator instead of every booted simulator/device on the machine. Live status also updates `Next:` to `mm-harness logs` when the selected bridge is reachable.
+- The tmux Metro window opened by `launch ios|android` now streams the Metro output it writes to `metro.log` instead of opening a blank server window.
+- `log-tui watch` now matches success/failure patterns only against log content emitted after the watcher starts, so stale markers already present in long-lived Metro/webpack logs cannot false-pass readiness checks.
+- `start-metro` now reaps any existing mobile console-forwarder attached to the same Metro port before spawning this slot's forwarder, even when the old process was launched from another checkout or package install path.
+
 ## 0.13.0 - 2026-07-08
 
 ### Added
@@ -29,7 +68,7 @@
 ### Added
 - Mobile recipes can now use the standard outer `app.lifecycle` action for deterministic performance start states without rebuilding (Android background/foreground/terminate/restart, iOS simulator launch/terminate/restart through the shared Farmslot lifecycle adapter).
 - `fixtures set --device <serial|udid|name>` now pins mobile fixture sync to the requested device using the same targeting rules as `run`, `call`, and `doctor`.
-- New lifecycle-controlled measured flows in the packaged library: `app-lifecycle-android-smoke`, `perps-performance-warm-start`, `perps-performance-background-resume`, `perps-performance-cold-start`; performance recipes now keep lifecycle/unlock in `setup[]`/`startState` so measured nodes carry only CUF timings.
+- New lifecycle-controlled measured flows in the packaged library: `app.lifecycle.android-smoke`, `perps.performance.warm-start`, `perps.performance.background-resume`, `perps.performance.cold-start`; performance recipes now keep lifecycle/unlock in `setup[]`/`startState` so measured nodes carry only CUF timings.
 
 ### Changed
 - `@farmslot/recipe-harness` dependency raised to `^0.4.0` (ships the `app.lifecycle` adapter — the `FARMSLOT_ROOT` local-source fallback is no longer needed at runtime).
@@ -46,9 +85,9 @@
 ## 0.10.0 - 2026-07-07
 
 ### Added
-- **Canonical `perps-performance` measured flow** (`library/recipes/perps-performance.mobile.recipe.json`): unlock → open the Perps market list → read live state → open a market detail — one node per user-visible step with stable node names, so the per-node `duration`s in `trace.json` are the timings you monitor. Run pinned: `mm-harness run perps-performance --device <serial> --heal off`. Device-proven end-to-end on a physical Pixel.
+- **Canonical `perps.performance` measured flow** (`library/recipes/perps/performance.mobile.recipe.json`): unlock → open the Perps market list → read live state → open a market detail — one node per user-visible step with stable node names, so the per-node `duration`s in `trace.json` are the timings you monitor. Run pinned: `mm-harness run perps.performance --device <serial> --heal off`. Device-proven end-to-end on a physical Pixel.
 - **`run <name>` resolves personal/team recipe libraries.** Previously only the packaged library was probed by name; custom recipes ran by path. Sources resolve in library-precedence order (personal > team shadow the packaged canonical — a same-named personal recipe wins), path-shaped args never probe libraries, and a miss teaches which sources were searched. Zero-flag default: `$FARMSLOT_HOME/recipe-library`.
-- **Custom-library walkthrough** ("Your own measured flow" in `docs/recipe-libraries.md`): a peer engineer scaffolds a personal library, copies the canonical flow, retargets the nodes to their journey, and runs it by name. Every step is executed by the `perps-performance-recipe` contract test, so the doc cannot drift from reality.
+- **Custom-library walkthrough** ("Your own measured flow" in `docs/recipe-libraries.md`): a peer engineer scaffolds a personal library, copies the canonical flow, retargets the nodes to their journey, and runs it by name. Every step is executed by the `perps.performance-recipe` contract test, so the doc cannot drift from reality.
 - **`call` declared on mobile and extension manifests** (was core-only) with self-discovery metadata — personal `flows/` segments are now usable from mobile/extension recipes. Honest limitation documented: flows carry no adapter dimension in the protocol yet, so a cross-adapter `call` fails at live-run rather than plan time.
 
 ### Fixed
@@ -71,7 +110,7 @@
 ## 0.8.0 - 2026-07-07
 
 ### Added
-- **`run <name>` — the recipe positional resolves packaged-library recipe names.** An existing file path (absolute or cwd-relative) wins; otherwise the arg is a library recipe name, adapter-scoped first (`run smoke` on mobile → `smoke.mobile.recipe.json`), then adapterless (`run perps-lifecycle`), then the exact library filename. A miss teaches `RECIPE_NOT_FOUND` naming the library recipes available for the adapter — no more `$LIB`-style path prefixes in docs or demo scripts. A directory shadowing a library name never wins, and path-shaped args (containing a separator) never fall through to the library.
+- **`run <name>` — the recipe positional resolves packaged-library recipe names.** An existing file path (absolute or cwd-relative) wins; otherwise the arg is a library recipe name, adapter-scoped first (`run smoke` on mobile → `library/recipes/runner/smoke.mobile.recipe.json`), then adapterless (`run perps.lifecycle` → `library/recipes/perps/lifecycle.recipe.json`), then the exact library filename. A miss teaches `RECIPE_NOT_FOUND` naming the library recipes available for the adapter — no more `$LIB`-style path prefixes in docs or demo scripts. A directory shadowing a library name never wins, and path-shaped args (containing a separator) never fall through to the library.
 - **`--device <udid|serial|name>` — first-class mobile device targeting on `run`, `call`, and `doctor`.** Resolves against connected devices (adb + booted simulators; exact id first, then exact name with an ambiguity teaching error) and sets the same env `launch --device` does. Mobile `run`/`call` **without** `--device` while more than one targetable device is connected (across android + ios; android state `device`, iOS `Booted`) fail fast listing the devices and the `--device` hint, so a recipe never lands on the wrong device silently. `run --plan`/`--list` are exempt; extension/core teach. Errors honor `--json` with structured envelopes.
 - **`status` gains `devices[]`** (additive): `{platform, id, name, state, selected}` for connected android devices and booted iOS simulators on mobile checkouts — the `yarn a:status` successor; `selected` reflects the current env pinning.
 

package/adapters/extension/inject.mjs

@@ -127,6 +127,7 @@ copyFile(path.join(runnerDir, 'adapters/shared/path-defaults.json'), path.join(h
 copyFile(path.join(runnerDir, 'adapters/shared/json-field.sh'), path.join(harnessDir, 'scripts/lib/json-field.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/tmux-session.sh'), path.join(harnessDir, 'scripts/lib/tmux-session.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/lib/extension-id.cjs'), path.join(harnessDir, 'scripts/lib/extension-id.cjs'));
 makeExecutableTree(path.join(harnessDir, 'scripts'));
 fs.writeFileSync(path.join(harnessDir, 'installed-scripts.sha256'), `${dirContentHash(path.join(harnessDir, 'scripts'))}\n`);
 

package/adapters/extension/launch-browser.cjs

@@ -23,6 +23,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { execFileSync, spawn, spawnSync } = require('node:child_process');
+const { extensionIdFromExtensionDir } = require('./lib/extension-id.cjs');
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(
@@ -74,6 +75,10 @@ const ownedPids = new Set(listenerPids);
 const previousPid = readPidFile(args['chrome-pid']);
 if (previousPid !== null && processLoadsProfile(previousPid, args.profile)) ownedPids.add(previousPid);
 terminatePids([...ownedPids]);
+if (args['reset-profile'] !== undefined) {
+  fs.rmSync(args.profile, { recursive: true, force: true });
+  fs.mkdirSync(args.profile, { recursive: true });
+}
 removeProfileSingletonLocks(args.profile);
 
 // --stop-only: release the profile (owned Chrome terminated, singleton locks
@@ -87,6 +92,7 @@ if (args['stop-only'] !== undefined) {
 const logFd = fs.openSync(args['chrome-log'], 'a');
 let child;
 try {
+  const initialUrl = args['start-url'] || extensionHomeUrl(args['extension-dir']) || 'chrome://extensions/';
   child = spawn(args['chrome-bin'], [
     `--user-data-dir=${args.profile}`,
     '--remote-debugging-address=127.0.0.1',
@@ -100,9 +106,10 @@ try {
     '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
     `--disable-extensions-except=${args['extension-dir']}`,
     `--load-extension=${args['extension-dir']}`,
-    // Initial tab: the caller's dapp URL when provided (sidepanel demos pair the
-    // extension sidepanel with a dapp in the main tab), else the extensions page.
-    args['start-url'] || 'chrome://extensions/',
+    // Initial tab: caller's dapp URL when provided, else the extension home. The
+    // extension home avoids leaving disposable chrome://newtab/ or extensions
+    // manager tabs in the operator's slot browser.
+    initialUrl,
   ], {
     detached: true,
     env: {
@@ -228,3 +235,8 @@ function removeProfileSingletonLocks(profile) {
     if (fs.existsSync(file)) fs.rmSync(file, { force: true });
   }
 }
+
+function extensionHomeUrl(extensionDir) {
+  const id = extensionIdFromExtensionDir(extensionDir);
+  return id ? `chrome-extension://${id}/home.html` : '';
+}

package/adapters/extension/lib/extension-id.cjs

@@ -0,0 +1,36 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Chromium extension IDs encode each SHA-256 nibble as a-p.
+const CHROMIUM_EXTENSION_ID_ALPHABET = 'abcdefghijklmnop';
+
+function extensionIdFromManifestKey(keyBase64) {
+  if (typeof keyBase64 !== 'string' || !keyBase64) return '';
+  const digest = crypto.createHash('sha256').update(Buffer.from(keyBase64, 'base64')).digest();
+  return [...digest.subarray(0, 16)]
+    .map((byte) => `${CHROMIUM_EXTENSION_ID_ALPHABET[byte >> 4]}${CHROMIUM_EXTENSION_ID_ALPHABET[byte & 0x0f]}`)
+    .join('');
+}
+
+function extensionIdFromManifestFile(manifestPath) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    return extensionIdFromManifestKey(manifest.key);
+  } catch {
+    return '';
+  }
+}
+
+function extensionIdFromExtensionDir(extensionDir) {
+  return extensionIdFromManifestFile(path.join(extensionDir, 'manifest.json'));
+}
+
+module.exports = {
+  CHROMIUM_EXTENSION_ID_ALPHABET,
+  extensionIdFromManifestKey,
+  extensionIdFromManifestFile,
+  extensionIdFromExtensionDir,
+};

package/adapters/extension/live.sh

@@ -90,6 +90,8 @@ if [ -z "$VERIFY_SH" ]; then
 fi
 TARGET="$(cd "$TARGET" && pwd)"
 RUNTIME_DIR="$(recipe_runtime_dir)"
+RUNTIME_DIST_DIR="${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}"
+CHROME_PROFILE_NAME="${RECIPE_CHROME_PROFILE_NAME:-chrome-profile}"
 # Runner bin (installed wrapper → source runner). Used by the watch prepare path
 # to defer the cache-clear DECISION to `runtime-decision` (single source) and to
 # record the deps/cache baseline after a confirmed-good build.
@@ -118,12 +120,12 @@ if $LAUNCH_EXISTING_DIST && [ -z "$PREPARE_CMD" ]; then
   # Stable beside the profile: the reused profile registers the unpacked
   # extension by PATH; a per-run snapshot path gets pruned and the next launch
   # loads nothing ("No EIP-6963 Provider Detected").
-  RUNTIME_DIST_ABS="$TARGET/temp/recipe/runtime/runtime-dist"
+  RUNTIME_DIST_ABS="$TARGET/$RUNTIME_DIR/$RUNTIME_DIST_DIR"
   # Stable per-checkout profile: successive runs recognize their own Chrome
   # (ownership guard matches on --user-data-dir), take it over cleanly, and the
   # seeded wallet persists across relaunches. A per-run profile made every
   # relaunch "foreign" and let live/ pruning delete profiles still in use.
-  PROFILE_ABS="${CHROME_USER_DATA_DIR:-$TARGET/temp/recipe/runtime/chrome-profile}"
+  PROFILE_ABS="${CHROME_USER_DATA_DIR:-$TARGET/$RUNTIME_DIR/$CHROME_PROFILE_NAME}"
   FIXTURE_STATE_ABS="$ARTIFACTS/fixture-state.json"
   FIXTURE_VALIDATION_ABS="$ARTIFACTS/logs/fixture-account-parity.json"
   # Wallet fixture resolution chain + provenance live in seed-fixture.sh.
@@ -241,7 +243,7 @@ NODE
   if $START_WATCH; then
     prepare_parts+=("bash ${quoted_start_watch} --runtime-dir ${quoted_runtime_dir} --runner-bin ${quoted_runner}")
   fi
-  prepare_parts+=("node ${quoted_chrome_launcher} --stop-only 1 --chrome-bin ${quoted_chrome} --profile ${quoted_profile} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --chrome-log ${quoted_chrome_log} --chrome-pid ${quoted_chrome_pid}")
+  prepare_parts+=("node ${quoted_chrome_launcher} --stop-only 1 --reset-profile 1 --chrome-bin ${quoted_chrome} --profile ${quoted_profile} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --chrome-log ${quoted_chrome_log} --chrome-pid ${quoted_chrome_pid}")
   prepare_parts+=("bash ${quoted_snapshot_dist} --dist ${quoted_dist} --runtime-dist ${quoted_runtime_dist}")
   # Optional A/B feature-flag pinning: patch the ephemeral snapshot manifest so
   # manifest._flags wins over the fetched ClientConfigApi value. No-op unless

package/adapters/extension/readiness.mjs

@@ -100,6 +100,28 @@ function readExpectedExtensionId(target) {
   return /^[a-p]{32}$/.test(id) ? id : '';
 }
 
+function readSlotId(target) {
+  for (const key of ['RECIPE_SLOT_ID', 'SLOT_ID', 'FARMSLOT_SLOT_ID']) {
+    const value = sanitizeSlotId(process.env[key]);
+    if (value) return value;
+  }
+  try {
+    const runtimeContext = JSON.parse(fs.readFileSync(path.join(target, recipeRuntimeDir(), 'agentic-runtime.json'), 'utf8'));
+    const value = sanitizeSlotId(runtimeContext.slotId);
+    if (value) {
+      return value;
+    }
+  } catch {
+    // No slot context: standalone harness users do not need a custom browser title.
+  }
+  return '';
+}
+
+function sanitizeSlotId(value) {
+  const slotId = typeof value === 'string' ? value.trim() : '';
+  return /^[A-Za-z0-9._:-]{1,64}$/u.test(slotId) ? slotId : '';
+}
+
 function writeExtensionId(target, extensionId) {
   if (!/^[a-p]{32}$/.test(extensionId)) return false;
   const idPath = extensionIdPath(target);
@@ -118,6 +140,12 @@ function assertLocalUrl(url) {
   }
 }
 
+function assertLocalWebSocketUrl(url) {
+  if (!/^ws:\/\/(?:127\.0\.0\.1|localhost):\d+\//u.test(String(url))) {
+    throw new Error(`readiness: refusing non-local websocket URL: ${url}`);
+  }
+}
+
 function httpJson(url, timeoutMs = 3000) {
   assertLocalUrl(url);
   return new Promise((resolve, reject) => {
@@ -176,6 +204,7 @@ function resolveWebSocket(target) {
 }
 
 async function cdpEvaluate(target, webSocketDebuggerUrl, expression, timeoutMs = 5000) {
+  assertLocalWebSocketUrl(webSocketDebuggerUrl);
   const WebSocketImpl = resolveWebSocket(target);
   if (!WebSocketImpl) return { skipped: true, reason: 'WebSocket unavailable in this Node runtime' };
   return new Promise((resolve, reject) => {
@@ -333,6 +362,7 @@ async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceW
   // Inspect only when the chosen page exposes a websocket. A present-but-attached
   // tab has none; skip inspection and report it rather than opening a duplicate.
   if (pageTarget && typeof pageTarget.webSocketDebuggerUrl === 'string') {
+    const slotId = readSlotId(target);
     ui = await cdpEvaluate(
       target,
       pageTarget.webSocketDebuggerUrl,
@@ -373,6 +403,24 @@ async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceW
         report: { cdp: { browser: version.Browser || 'unknown', selectedExtensionId, ui } },
       });
     }
+    if (pageInspected && slotId) {
+      const stampedTitle = await cdpEvaluate(
+        target,
+        pageTarget.webSocketDebuggerUrl,
+        `(() => {
+          const slot = ${JSON.stringify(slotId)};
+          const current = document.title || 'MetaMask';
+          const base = current.replace(/^.+?\\s+—\\s+/, '') || 'MetaMask';
+          const next = slot + ' — ' + base;
+          if (document.title !== next) document.title = next;
+          return document.title;
+        })()`,
+      );
+      if (stampedTitle && !stampedTitle.skipped) {
+        ui.title = stampedTitle;
+        ui.slotTitleApplied = true;
+      }
+    }
   }
   return {
     browser: version.Browser || 'unknown',

package/adapters/extension/reattach.sh

@@ -33,6 +33,7 @@ START_URL="${EXTENSION_START_URL:-}"
 EXT_ID="${EXT_ID:-}"
 DIST_DIR="dist/chrome"
 SETTLE_MS="8000"
+DISPLAY_MODE="${EXTENSION_DISPLAY_MODE:-fullscreen}"
 
 require_value() { [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; }
 while [ "$#" -gt 0 ]; do
@@ -44,8 +45,9 @@ while [ "$#" -gt 0 ]; do
     --ext-id) require_value "$@"; EXT_ID="$2"; shift 2 ;;
     --dist-dir) require_value "$@"; DIST_DIR="$2"; shift 2 ;;
     --settle-ms) require_value "$@"; SETTLE_MS="$2"; shift 2 ;;
+    --display-mode) require_value "$@"; DISPLAY_MODE="$2"; shift 2 ;;
     -h|--help)
-      echo "Usage: reattach.sh --target <metamask-extension> --cdp-port <port> [--watcher-port <port>] [--start-url <url>] [--ext-id <id>] [--dist-dir <rel>] [--settle-ms <ms>]"
+      echo "Usage: reattach.sh --target <metamask-extension> --cdp-port <port> [--watcher-port <port>] [--start-url <url>] [--ext-id <id>] [--dist-dir <rel>] [--settle-ms <ms>] [--display-mode fullscreen|sidepanel]"
       exit 0
       ;;
     *) echo "reattach: unknown arg: $1" >&2; exit 2 ;;
@@ -60,6 +62,10 @@ fi
 case "$CDP_PORT" in
   *[!0-9]*) echo "reattach: --cdp-port must be numeric (got: $CDP_PORT)" >&2; exit 2 ;;
 esac
+case "$DISPLAY_MODE" in
+  fullscreen|sidepanel) ;;
+  *) echo "reattach: --display-mode must be fullscreen or sidepanel (got: $DISPLAY_MODE)" >&2; exit 2 ;;
+esac
 
 if [ ! -f "$TARGET/package.json" ]; then
   echo "reattach: --target is not a checkout (no package.json): $TARGET" >&2
@@ -75,23 +81,33 @@ if ! curl -s -m 3 "http://127.0.0.1:${CDP_PORT}/json/version" >/dev/null 2>&1; t
 fi
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../../adapters/shared/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
+  [ -f "$_hp" ] && { . "$_hp"; break; }
+done
+unset _hp
 DIST_ABS="$TARGET/$DIST_DIR"
-# The running Chrome loads the runtime-dist snapshot (frozen at launch), not the
-# live dist. Re-snapshot so the in-place reload serves the latest watched build.
-RUNTIME_DIST_ABS="$TARGET/temp/recipe/runtime/runtime-dist"
-
-if [ -f "$SCRIPT_DIR/snapshot-dist.sh" ] && [ -d "$RUNTIME_DIST_ABS" ]; then
-  echo "[reattach] re-snapshotting dist -> runtime-dist for in-place reload" >&2
-  bash "$SCRIPT_DIR/snapshot-dist.sh" --dist "$DIST_ABS" --runtime-dist "$RUNTIME_DIST_ABS" >&2 || {
-    echo "reattach: dist re-snapshot failed; the loaded extension may be mid-rebuild." >&2
-    echo "  Next: mm-harness launch --build   (clean build + relaunch)" >&2
-    exit 1
-  }
+if command -v recipe_runtime_dir >/dev/null 2>&1; then
+  RUNTIME_DIR="$(recipe_runtime_dir)"
+else
+  RUNTIME_DIR="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
+fi
+RUNTIME_DIST_DIR="${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}"
+# The running Chrome loads this unpacked extension directory. Do not recreate or
+# rsync-delete it while Chrome is live: Chrome can keep the intended
+# chrome-extension:// target URL but serve chrome-error://chromewebdata after its
+# loaded directory is replaced underneath it. Fresh snapshots belong to the clean
+# relaunch path; quick reattach only reloads the already-loaded runtime.
+RUNTIME_DIST_ABS="$TARGET/$RUNTIME_DIR/$RUNTIME_DIST_DIR"
+echo "[reattach] reusing loaded runtime-dist: $RUNTIME_DIST_ABS" >&2
+if [ -d "$DIST_ABS" ] && [ -d "$RUNTIME_DIST_ABS" ]; then
+  echo "[reattach] refreshing loaded runtime-dist in place" >&2
+  rsync -a --exclude _metadata "$DIST_ABS/" "$RUNTIME_DIST_ABS/" >&2
 fi
 
 # Resolve the extension id: explicit flag, then the recorded id file, else CDP.
 if [ -z "$EXT_ID" ]; then
-  for idf in "$TARGET/temp/recipe/runtime/extension.id" "$SCRIPT_DIR/extension.id"; do
+  for idf in "$TARGET/$RUNTIME_DIR/extension.id" "$SCRIPT_DIR/extension.id"; do
     if [ -f "$idf" ]; then
       EXT_ID="$(tr -d '[:space:]' < "$idf")"
       [ -n "$EXT_ID" ] && break
@@ -102,23 +118,82 @@ fi
 cd "$TARGET"
 echo "[reattach] reloading extension in place over CDP :${CDP_PORT}" >&2
 
-CDP_PORT="$CDP_PORT" EXT_ID="$EXT_ID" START_URL="$START_URL" SETTLE_MS="$SETTLE_MS" node <<'NODE'
+CDP_PORT="$CDP_PORT" EXT_ID="$EXT_ID" TARGET="$TARGET" SCRIPT_DIR="$SCRIPT_DIR" RUNTIME_DIR="$RUNTIME_DIR" RUNTIME_DIST_DIR="$RUNTIME_DIST_DIR" START_URL="$START_URL" SETTLE_MS="$SETTLE_MS" DISPLAY_MODE="$DISPLAY_MODE" node <<'NODE'
 let chromium; try { chromium = require('@playwright/test').chromium; } catch { chromium = require('playwright').chromium; }
+const fs = require('node:fs');
+const path = require('node:path');
+const { extensionIdFromManifestFile } = require(path.join(process.env.SCRIPT_DIR, 'lib/extension-id.cjs'));
 
 const port = process.env.CDP_PORT;
+const target = process.env.TARGET;
+const runtimeDir = process.env.RUNTIME_DIR;
+const runtimeDistDir = process.env.RUNTIME_DIST_DIR;
 const startUrl = process.env.START_URL || '';
 const settleMs = Number(process.env.SETTLE_MS || '8000') || 8000;
+const displayMode = process.env.DISPLAY_MODE || 'fullscreen';
+const slotId = process.env.RECIPE_SLOT_ID || process.env.SLOT_ID || process.env.FARMSLOT_SLOT_ID || readRuntimeSlotId();
+
+if (!runtimeDir || !runtimeDistDir) {
+  console.error('reattach: resolved runtime paths were not provided.');
+  process.exit(2);
+}
+
+function readRuntimeSlotId() {
+  try {
+    const runtimeContext = JSON.parse(fs.readFileSync(path.join(target, runtimeDir, 'agentic-runtime.json'), 'utf8'));
+    return typeof runtimeContext.slotId === 'string' ? runtimeContext.slotId.trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+function extensionIdFromRuntimeDist() {
+  return extensionIdFromManifestFile(path.join(target, runtimeDir, runtimeDistDir, 'manifest.json'));
+}
+
+function validExtensionId(value) {
+  return /^[a-p]{32}$/u.test(String(value || '')) ? String(value) : '';
+}
+
+function writeExtensionId(id) {
+  if (!validExtensionId(id)) return;
+  try {
+    const idPath = path.join(target, runtimeDir, 'extension.id');
+    fs.mkdirSync(path.dirname(idPath), { recursive: true });
+    fs.writeFileSync(idPath, `${id}\n`);
+  } catch {
+    // Best-effort marker repair; the live CDP reload is the source of truth.
+  }
+}
 
 function extensionIdFrom(context, provided) {
-  if (provided) return provided;
   const urls = [];
-  for (const page of context.pages()) urls.push(page.url());
-  for (const worker of context.serviceWorkers()) urls.push(worker.url());
+  const ids = [];
+  for (const page of allPages(context)) urls.push(page.url());
+  for (const worker of allServiceWorkers(context)) urls.push(worker.url());
   for (const url of urls) {
     const match = /^chrome-extension:\/\/([^/]+)\//u.exec(url);
-    if (match) return match[1];
+    if (match && !ids.includes(match[1])) ids.push(match[1]);
+  }
+  if (provided) {
+    if (ids.length === 0 || ids.includes(provided)) return provided;
+    return '';
   }
-  return '';
+  return ids[0] || '';
+}
+
+function allContexts(context) {
+  const browser = context.browser?.();
+  const contexts = browser?.contexts?.();
+  return contexts && contexts.length ? contexts : [context];
+}
+
+function allPages(context) {
+  return allContexts(context).flatMap((candidate) => candidate.pages());
+}
+
+function allServiceWorkers(context) {
+  return allContexts(context).flatMap((candidate) => candidate.serviceWorkers());
 }
 
 async function connect() {
@@ -127,20 +202,56 @@ async function connect() {
   return { browser, context };
 }
 
+async function stampSlotTitle(page) {
+  if (!slotId || !page) return;
+  await page.evaluate((slot) => {
+    const base = (document.title || 'MetaMask').replace(/^.+?\s+—\s+/, '') || 'MetaMask';
+    const next = `${slot} — ${base}`;
+    if (document.title !== next) document.title = next;
+  }, slotId).catch(() => {
+    // Best-effort operator affordance; reload success is verified by CDP state.
+  });
+}
+
+async function closeDisposableChromeTabs(context) {
+  for (const page of allPages(context)) {
+    const url = page.url();
+    if (url === 'chrome://newtab/' || url === 'chrome://new-tab-page/' || url === 'chrome://extensions/') {
+      await page.close().catch(() => {
+        // Best-effort tab hygiene; runtime health is verified separately.
+      });
+    }
+  }
+}
+
+async function closePages(context, predicate) {
+  for (const page of allPages(context)) {
+    if (!predicate(page)) continue;
+    await page.close().catch(() => {
+      // Best-effort display-mode cleanup; final health checks own correctness.
+    });
+  }
+}
+
 (async () => {
-  // Phase 1: trigger a full extension reload (service worker + all pages) from an
-  // extension page so Chrome re-reads the freshly snapshotted runtime-dist.
+  // Phase 1: attach to the already-loaded extension page. Do not call
+  // chrome.runtime.reload() here: on the slot Chrome version it can leave the
+  // target URL as chrome-extension://.../home.html while the actual document is
+  // chrome-error://chromewebdata. Clean relaunch owns loading a new unpacked
+  // runtime-dist; quick reattach only refreshes/foregrounds the live UI.
   let { browser, context } = await connect();
-  const extId = extensionIdFrom(context, process.env.EXT_ID);
+  const providedExtId = extensionIdFromRuntimeDist() || validExtensionId(process.env.EXT_ID);
+  const extId = extensionIdFrom(context, providedExtId);
   if (!extId) {
-    await browser.close();
-    console.error('reattach: could not resolve the extension id from the live CDP targets.');
+    if (typeof browser.disconnect === 'function') await browser.disconnect();
+    else await browser.close();
+    console.error('reattach: could not resolve the extension id from runtime-dist or live CDP targets.');
     console.error('  Next: mm-harness launch --build   (clean build + relaunch)');
     process.exit(1);
   }
+  writeExtensionId(extId);
 
-  let page = context
-    .pages()
+  let page = allPages(context)
     .find((candidate) => candidate.url().startsWith(`chrome-extension://${extId}/`));
   if (!page) {
     page = await context.newPage();
@@ -149,35 +260,19 @@ async function connect() {
       timeout: 15000,
     });
   }
-  await page.evaluate(() => chrome.runtime.reload()).catch(() => {
-    // The reload tears the page context down; a rejected evaluate is expected.
+  await page.reload({ waitUntil: 'domcontentloaded', timeout: 15000 }).catch(async () => {
+    await page.goto(`chrome-extension://${extId}/home.html`, {
+      waitUntil: 'domcontentloaded',
+      timeout: 15000,
+    });
   });
-  await browser.close();
-
-  // Phase 2: wait for the extension to come back, then re-open the wallet and,
-  // when requested, a dapp tab. Chrome itself never restarted, so CDP stays up.
-  const deadline = Date.now() + settleMs;
-  let back = false;
-  while (Date.now() < deadline) {
-    try {
-      const probe = await connect();
-      const id = extensionIdFrom(probe.context, extId);
-      await probe.browser.close();
-      if (id) { back = true; break; }
-    } catch {
-      // CDP momentarily unavailable during reload; retry until the deadline.
-    }
-    await new Promise((resolve) => setTimeout(resolve, 250));
-  }
-  if (!back) {
-    console.error(`reattach: extension did not come back within ${settleMs}ms after reload.`);
-    console.error('  Next: mm-harness launch --build   (clean build + relaunch)');
-    process.exit(1);
-  }
+  if (typeof browser.disconnect === 'function') await browser.disconnect();
+  else await browser.close();
 
+  // Phase 2: re-open/retitle the wallet and, when requested, a dapp tab. Chrome
+  // itself never restarted, so CDP stays up.
   ({ browser, context } = await connect());
-  let home = context
-    .pages()
+  let home = allPages(context)
     .find(
       (candidate) =>
         candidate.url().startsWith(`chrome-extension://${extId}/`) &&
@@ -189,16 +284,29 @@ async function connect() {
       .goto(`chrome-extension://${extId}/home.html`, { waitUntil: 'domcontentloaded', timeout: 15000 })
       .catch(() => { /* wallet home is best-effort; the reload already applied */ });
   }
+  await stampSlotTitle(home);
+  await closeDisposableChromeTabs(context);
   if (startUrl) {
-    const dapp = context
-      .pages()
+    const dapp = allPages(context)
       .find((candidate) => candidate.url().startsWith('http://') || candidate.url().startsWith('https://'));
     const tab = dapp || (await context.newPage());
     await tab
       .goto(startUrl, { waitUntil: 'domcontentloaded', timeout: 20000 })
       .catch(() => { /* dapp navigation is best-effort */ });
   }
-  await browser.close();
+  if (displayMode === 'fullscreen') {
+    await closePages(context, (candidate) => {
+      const url = candidate.url();
+      if (url.startsWith(`chrome-extension://${extId}/`) && url.includes('/sidepanel.html')) return true;
+      if (!startUrl && (url.startsWith('http://') || url.startsWith('https://'))) return true;
+      return false;
+    });
+    await home.bringToFront().catch(() => {
+      // Foreground is an operator affordance; health is verified separately.
+    });
+  }
+  if (typeof browser.disconnect === 'function') await browser.disconnect();
+  else await browser.close();
 })().catch((error) => {
   console.error(`reattach: ${error && error.message ? error.message : error}`);
   console.error('  Next: mm-harness launch --build   (clean build + relaunch)');