@deeeed/metamask-harness 0.2.0

package/orchestration/extension/readiness.mjs

@@ -0,0 +1,414 @@
+#!/usr/bin/env node
+// readiness.mjs — health probe for one extension instance
+//  runner/extension/extension-readiness.mjs)
+//
+// Purpose:
+//   App-control health probe: verifies the dist build's expected entry
+//   files and (with --cdp-port) the live extension target over CDP,
+//   repairing <runtime-dir>/extension.id when the runtime disagrees.
+//
+// Inputs (flags / env):
+//   --target <metamask-extension> (default $PWD), --cdp-port <port>, --json
+//   env RECIPE_RUNTIME_DIR (else lib path-defaults)
+// Outputs: readiness report (JSON with --json) on stdout.
+//   Exit 0 — ready; non-zero — not ready / bad args (thrown message).
+// Never touches: the dist build (read-only) other than the
+//   <runtime-dir>/extension.id repair.
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+
+function pathDefault(key) {
+  for (const candidate of [
+    path.join(scriptDir, 'lib/path-defaults.json'),
+    path.join(scriptDir, '../lib/path-defaults.json'),
+    path.join(scriptDir, '../../orchestration/lib/path-defaults.json'),
+  ]) {
+    if (!fs.existsSync(candidate)) continue;
+    const value = JSON.parse(fs.readFileSync(candidate, 'utf8'))[key];
+    if (value) return value;
+  }
+  throw new Error(`Missing path default: ${key}`);
+}
+
+function recipeRuntimeDir() {
+  return process.env.RECIPE_RUNTIME_DIR || pathDefault('recipeRuntimeDir');
+}
+
+function parseArgs(argv) {
+  const out = { target: process.cwd(), cdpPort: '', json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--target') {
+      out.target = argv[++i];
+    } else if (arg === '--cdp-port') {
+      out.cdpPort = argv[++i];
+    } else if (arg === '--json') {
+      out.json = true;
+    } else if (arg === '-h' || arg === '--help') {
+      console.log('Usage: readiness.mjs --target <metamask-extension> [--cdp-port <port>] [--json]');
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown arg: ${arg}`);
+    }
+  }
+  return out;
+}
+
+function readManifest(target) {
+  const manifestPath = path.join(target, 'dist/chrome/manifest.json');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  return { manifestPath, manifest };
+}
+
+function manifestExpectedFiles(manifest) {
+  const entries = new Set(['home.html']);
+  if (manifest.background?.service_worker) entries.add(manifest.background.service_worker);
+  for (const script of manifest.background?.scripts || []) entries.add(script);
+  const popup =
+    manifest.action?.default_popup ||
+    manifest.browser_action?.default_popup ||
+    manifest.page_action?.default_popup;
+  if (popup) entries.add(popup);
+  if (manifest.side_panel?.default_path) entries.add(manifest.side_panel.default_path);
+  return [...entries];
+}
+
+function manifestDefaultPage(manifest) {
+  return (
+    manifest.action?.default_popup ||
+    manifest.browser_action?.default_popup ||
+    manifest.page_action?.default_popup ||
+    manifest.side_panel?.default_path ||
+    'home.html'
+  );
+}
+
+function extensionIdPath(target) {
+  return path.join(target, recipeRuntimeDir(), 'extension.id');
+}
+
+function readExpectedExtensionId(target) {
+  const idPath = path.join(target, recipeRuntimeDir(), 'extension.id');
+  if (!fs.existsSync(idPath)) return '';
+  const id = fs.readFileSync(idPath, 'utf8').trim();
+  return /^[a-p]{32}$/.test(id) ? id : '';
+}
+
+function writeExtensionId(target, extensionId) {
+  if (!/^[a-p]{32}$/.test(extensionId)) return false;
+  const idPath = extensionIdPath(target);
+  fs.mkdirSync(path.dirname(idPath), { recursive: true });
+  const existing = fs.existsSync(idPath) ? fs.readFileSync(idPath, 'utf8').trim() : '';
+  if (existing === extensionId) return false;
+  fs.writeFileSync(idPath, `${extensionId}\n`);
+  return true;
+}
+
+function httpJson(url, timeoutMs = 3000) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch (err) {
+          reject(new Error(`invalid JSON from ${url}: ${err.message}`));
+        }
+      });
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`timeout from ${url}`));
+    });
+    req.on('error', reject);
+  });
+}
+
+function httpJsonRequest(method, url, timeoutMs = 3000) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(url, { method }, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch (err) {
+          reject(new Error(`invalid JSON from ${method} ${url}: ${err.message}`));
+        }
+      });
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`timeout from ${method} ${url}`));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function resolveWebSocket(target) {
+  try {
+    return require(require.resolve('ws', { paths: [target, process.cwd()] }));
+  } catch {
+    return typeof WebSocket === 'function' ? WebSocket : null;
+  }
+}
+
+async function cdpEvaluate(target, webSocketDebuggerUrl, expression, timeoutMs = 5000) {
+  const WebSocketImpl = resolveWebSocket(target);
+  if (!WebSocketImpl) return { skipped: true, reason: 'WebSocket unavailable in this Node runtime' };
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocketImpl(webSocketDebuggerUrl);
+    const timer = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {
+        // Best effort timeout cleanup.
+      }
+      reject(new Error('timeout evaluating extension page via CDP'));
+    }, timeoutMs);
+    const onOpen = () => {
+      ws.send(JSON.stringify({
+        id: 1,
+        method: 'Runtime.evaluate',
+        params: { expression, awaitPromise: true, returnByValue: true },
+      }));
+    };
+    const onMessage = (event) => {
+      const raw = event?.data ?? event;
+      const msg = JSON.parse(Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw));
+      if (msg.id !== 1) return;
+      clearTimeout(timer);
+      ws.close();
+      if (msg.error) {
+        reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+        return;
+      }
+      resolve(msg.result?.result?.value ?? null);
+    };
+    const onError = (err) => {
+      clearTimeout(timer);
+      reject(new Error(`CDP websocket error while inspecting extension page: ${err?.message || err || 'unknown'}`));
+    };
+    if (typeof ws.on === 'function') {
+      ws.on('open', onOpen);
+      ws.on('message', onMessage);
+      ws.on('error', onError);
+    } else {
+      ws.addEventListener('open', onOpen);
+      ws.addEventListener('message', onMessage);
+      ws.addEventListener('error', onError);
+    }
+  });
+}
+
+function extensionIdFromTarget(target) {
+  const url = String(target.url || '');
+  const match = url.match(/^chrome-extension:\/\/([a-p]{32})\//u);
+  return match ? match[1] : '';
+}
+
+function chooseExtensionId(targets, expectedExtensionId, expectedServiceWorker) {
+  const byId = new Map();
+  for (const target of targets) {
+    const id = extensionIdFromTarget(target);
+    if (!id) continue;
+    const entries = byId.get(id) || [];
+    entries.push(target);
+    byId.set(id, entries);
+  }
+  const ids = [...byId.keys()];
+  if (ids.length === 0) return { extensionIds: [], selectedExtensionId: '' };
+
+  const hasExpectedWorker = (id) => byId.get(id).some((target) => {
+    const url = String(target.url || '');
+    return target.type === 'service_worker' && expectedServiceWorker && url.endsWith(`/${expectedServiceWorker}`);
+  });
+  const hasAnyWorker = (id) => byId.get(id).some((target) => target.type === 'service_worker');
+
+  const selectedExtensionId =
+    ids.find((id) => id === expectedExtensionId && hasExpectedWorker(id)) ||
+    ids.find((id) => hasExpectedWorker(id)) ||
+    ids.find((id) => id === expectedExtensionId && hasAnyWorker(id)) ||
+    ids.find((id) => hasAnyWorker(id)) ||
+    (expectedExtensionId && ids.includes(expectedExtensionId) ? expectedExtensionId : ids[0]);
+
+  return { extensionIds: ids, selectedExtensionId };
+}
+
+async function openExtensionPage(cdpPort, extensionId, pagePath) {
+  const normalizedPath = String(pagePath || 'home.html').replace(/^\/+/u, '');
+  const url = `chrome-extension://${extensionId}/${normalizedPath}`;
+  try {
+    await httpJsonRequest('PUT', `http://127.0.0.1:${cdpPort}/json/new?${encodeURIComponent(url)}`, 3000);
+    return true;
+  } catch (err) {
+    // Some CDP implementations disable /json/new. Readiness can still pass
+    // when the caller already opened an extension page, so report this as a
+    // best-effort page-open miss instead of hiding a required check failure.
+    return false;
+  }
+}
+
+function findPageTarget(targets, selectedExtensionId, preferredPagePath = '') {
+  const extensionPages = targets.filter((target) => {
+    const url = String(target.url || '');
+    return (
+      target.type === 'page' &&
+      url.startsWith(`chrome-extension://${selectedExtensionId}/`) &&
+      typeof target.webSocketDebuggerUrl === 'string'
+    );
+  });
+  const normalizedPreferred = String(preferredPagePath || '').replace(/^\/+/u, '');
+  return (
+    extensionPages.find((target) => normalizedPreferred && String(target.url || '').endsWith(`/${normalizedPreferred}`)) ||
+    extensionPages.find((target) => !String(target.url || '').includes('/popup-init.html')) ||
+    extensionPages[0]
+  );
+}
+
+async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceWorker, extensionPagePath) {
+  const version = await httpJson(`http://127.0.0.1:${cdpPort}/json/version`);
+  let targets = await httpJson(`http://127.0.0.1:${cdpPort}/json/list`);
+  if (!Array.isArray(targets)) throw new Error('/json/list did not return an array');
+  let { extensionIds, selectedExtensionId } = chooseExtensionId(targets, expectedExtensionId, expectedServiceWorker);
+  if (!selectedExtensionId) {
+    throw new Error('CDP is reachable but no chrome-extension:// targets are present');
+  }
+  let pageTarget = findPageTarget(targets, selectedExtensionId, extensionPagePath);
+  let openedPage = false;
+  if (!pageTarget) {
+    openedPage = await openExtensionPage(cdpPort, selectedExtensionId, extensionPagePath);
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    targets = await httpJson(`http://127.0.0.1:${cdpPort}/json/list`);
+    ({ extensionIds, selectedExtensionId } = chooseExtensionId(targets, expectedExtensionId, expectedServiceWorker));
+    pageTarget = findPageTarget(targets, selectedExtensionId, extensionPagePath);
+  }
+  let ui = null;
+  if (pageTarget) {
+    ui = await cdpEvaluate(
+      target,
+      pageTarget.webSocketDebuggerUrl,
+      `(() => {
+        const text = document.body?.innerText || '';
+        const cell = (sel) => document.querySelector(sel)?.innerText?.trim() || '';
+        // React error-boundary screen (ui/pages/error-page); deterministic testids.
+        const errorBoundaryMessage = cell('[data-testid="error-page-error-message"]');
+        const errorBoundaryName = cell('[data-testid="error-page-error-name"]');
+        // Testid-only trigger: ui/pages/error-page reliably renders these testids.
+        // Avoid matching the visible phrase in body text (false positives).
+        const hasErrorBoundary = Boolean(errorBoundaryMessage) || Boolean(errorBoundaryName);
+        return {
+          title: document.title,
+          url: location.href,
+          textSample: text.slice(0, 500),
+          hasStartupError: /MetaMask had trouble starting|Background connection unresponsive|Unknown Infura network/i.test(text),
+          hasErrorBoundary,
+          errorBoundaryName,
+          errorBoundaryMessage: errorBoundaryMessage || (hasErrorBoundary ? text.slice(0, 300) : ''),
+        };
+      })()`,
+    );
+    if (ui && !ui.skipped && ui.hasStartupError) {
+      throw Object.assign(new Error('MetaMask extension page loaded startup error UI'), {
+        report: { cdp: { browser: version.Browser || 'unknown', selectedExtensionId, ui } },
+      });
+    }
+    if (ui && !ui.skipped && ui.hasErrorBoundary) {
+      const detail = [ui.errorBoundaryName, ui.errorBoundaryMessage].filter(Boolean).join(': ');
+      throw Object.assign(new Error(`MetaMask UI crashed (React error boundary)${detail ? `: ${detail}` : ''}`), {
+        report: { cdp: { browser: version.Browser || 'unknown', selectedExtensionId, ui } },
+      });
+    }
+    if (ui && !ui.skipped && String(ui.url || '').startsWith('chrome-error://')) {
+      throw Object.assign(new Error('MetaMask extension page loaded Chrome error UI'), {
+        report: { cdp: { browser: version.Browser || 'unknown', selectedExtensionId, ui } },
+      });
+    }
+  }
+  return {
+    browser: version.Browser || 'unknown',
+    extensionIds,
+    selectedExtensionId,
+    markerMatched: Boolean(expectedExtensionId && selectedExtensionId === expectedExtensionId),
+    targetCount: targets.length,
+    openedPage,
+    openedPagePath: extensionPagePath,
+    ui,
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const target = path.resolve(args.target);
+  const checks = [];
+  const { manifestPath, manifest } = readManifest(target);
+  const expectedFiles = manifestExpectedFiles(manifest);
+  const missingFiles = [];
+  for (const rel of expectedFiles) {
+    const exists = fs.existsSync(path.join(target, 'dist/chrome', rel));
+    checks.push({ name: `dist/chrome/${rel}`, status: exists ? 'pass' : 'fail' });
+    if (!exists) missingFiles.push(rel);
+  }
+  if (missingFiles.length > 0) {
+    throw Object.assign(
+      new Error(`extension build incomplete; missing ${missingFiles.join(', ')}`),
+      { report: { target, manifestPath, expectedFiles, checks } },
+    );
+  }
+
+  const defaultPage = fs.existsSync(path.join(target, 'dist/chrome/home.html'))
+    ? 'home.html'
+    : manifestDefaultPage(manifest);
+  const report = {
+    target,
+    manifestPath,
+    manifestVersion: manifest.manifest_version || null,
+    defaultPage,
+    expectedFiles,
+    checks,
+  };
+
+  if (args.cdpPort) {
+    const expectedExtensionId = readExpectedExtensionId(target);
+    report.cdp = await inspectCdp(
+      target,
+      args.cdpPort,
+      expectedExtensionId,
+      manifest.background?.service_worker || '',
+      report.defaultPage,
+    );
+    report.cdp.markerRepaired = writeExtensionId(target, report.cdp.selectedExtensionId);
+    checks.push({ name: `CDP ${args.cdpPort} extension targets`, status: 'pass' });
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`Extension readiness OK: ${expectedFiles.join(', ')}`);
+    if (report.cdp) {
+      console.log(`CDP OK: ${report.cdp.browser}; extensions=${report.cdp.extensionIds.join(',')}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  const report = err && err.report ? err.report : null;
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify({ status: 'fail', error: err.message, ...(report || {}) }, null, 2));
+  } else {
+    console.error(`Extension readiness failed: ${err.message}`);
+  }
+  process.exit(1);
+});

package/orchestration/extension/refresh-build.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# refresh-build.sh — one-shot rebuild for a frozen extension slot
+#
+# Usage:
+#   bash refresh-build.sh --repo /path/to/metamask-extension [--watcher-port 9013]
+#
+# Context:
+#   In sidepanel mode, preflight.sh defaults to `watch=off` and kills the
+#   webpack watcher once dist/chrome is stable. That guarantees side-panel
+#   close/reopen never races a rebuild, but means code edits do not reach
+#   the browser until an explicit rebuild.
+#
+#   This script runs `yarn start` once, waits until the critical extension
+#   entry points are back on disk, then kills the watcher again — leaving
+#   dist/chrome fresh AND frozen. After it returns:
+#     - Close any open extension pages (sidepanel / popup / fullscreen)
+#     - Reopen them to pick up the new build
+#   e.g. `bash sidepanel-toggle.sh cycle --cdp-port $CDP_PORT`
+#
+# Exit codes:
+#   0 — success
+#   1 — bad args / repo missing
+#   2 — rebuild did not complete within the timeout
+
+set -euo pipefail
+
+REPO=""
+WATCHER_PORT=""
+TIMEOUT_S="180"
+CLEAN_TIMEOUT_S=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo) REPO="$2"; shift 2 ;;
+    --watcher-port) WATCHER_PORT="$2"; shift 2 ;;
+    --timeout) TIMEOUT_S="$2"; shift 2 ;;
+    --clean-timeout) CLEAN_TIMEOUT_S="$2"; shift 2 ;;
+    -h|--help)
+      echo "Usage: refresh-build.sh --repo /path/to/metamask-extension [--watcher-port <port>] [--timeout <s>] [--clean-timeout <s>]"
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [ -z "$REPO" ] || [ ! -f "$REPO/package.json" ]; then
+  echo "FAIL: --repo must point to a metamask-extension checkout" >&2
+  exit 1
+fi
+
+PORT_ARG=""
+if [ -n "$WATCHER_PORT" ]; then
+  PORT_ARG="PORT=${WATCHER_PORT}"
+fi
+
+cd "$REPO"
+
+HTML_ENTRIES=()
+while IFS= read -r entry; do
+  [ -n "$entry" ] && HTML_ENTRIES+=("dist/chrome/$entry")
+done < <(node <<'NODE'
+const fs = require('fs');
+const manifestPath = 'dist/chrome/manifest.json';
+if (!fs.existsSync(manifestPath)) {
+  console.log('home.html');
+  console.log('scripts/app-init.js');
+  console.log('popup-init.html');
+  console.log('sidepanel.html');
+  process.exit(0);
+}
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+const entries = new Set(['home.html']);
+if (manifest.background?.service_worker) entries.add(manifest.background.service_worker);
+for (const script of manifest.background?.scripts || []) entries.add(script);
+const popup = manifest.action?.default_popup || manifest.browser_action?.default_popup || manifest.page_action?.default_popup;
+if (popup) entries.add(popup);
+if (manifest.side_panel?.default_path) entries.add(manifest.side_panel.default_path);
+for (const entry of entries) console.log(entry);
+NODE
+)
+
+ASDF_SHIMS="${ASDF_DATA_DIR:-$HOME/.asdf}/shims"
+if [ -d "$ASDF_SHIMS" ]; then
+  export PATH="$ASDF_SHIMS:$PATH"
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+for _arn in "$SCRIPT_DIR/lib/activate-repo-node.sh" "$SCRIPT_DIR/../lib/activate-repo-node.sh"; do
+  [ -f "$_arn" ] && { . "$_arn"; break; }
+done
+unset _arn
+if command -v require_repo_node >/dev/null 2>&1; then
+  require_repo_node "$REPO"
+elif command -v activate_repo_node >/dev/null 2>&1; then
+  activate_repo_node "$REPO" || {
+    echo "[refresh] refusing to run yarn start without a pinned Node for $REPO" >&2
+    exit 1
+  }
+else
+  echo "[refresh] activate-repo-node.sh missing from harness; run: recipe sync" >&2
+  exit 1
+fi
+
+echo "[refresh] Using node $(node -v 2>/dev/null || echo 'not found')"
+echo "[refresh] Starting yarn start (watcher-port=${WATCHER_PORT:-default})..."
+LOG="$(mktemp -t refresh-build-XXXXXX.log)"
+echo "[refresh] Log: $LOG"
+env ${PORT_ARG} yarn start > "$LOG" 2>&1 &
+BUILD_PID=$!
+echo "[refresh] Build PID: $BUILD_PID"
+
+cleanup() {
+  if kill -0 "$BUILD_PID" 2>/dev/null; then
+    kill "$BUILD_PID" 2>/dev/null || true
+  fi
+  # Also clear any child yarn/gulp workers holding the watcher port
+  if [ -n "$WATCHER_PORT" ]; then
+    lsof -i ":$WATCHER_PORT" -t 2>/dev/null | xargs kill 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+# First wait for the clean pass (confirms this build, not a pre-existing stale
+# dist, owns the next entry files we observe).
+CLEAN_TIMEOUT_S="${CLEAN_TIMEOUT_S:-$TIMEOUT_S}"
+echo "[refresh] Waiting for clean pass (timeout ${CLEAN_TIMEOUT_S}s)..."
+for i in $(seq 1 "$CLEAN_TIMEOUT_S"); do
+  if grep -q "Finished 'clean'" "$LOG" 2>/dev/null; then
+    echo "[refresh] Clean pass reached (${i}s)"
+    break
+  fi
+  if grep -q "webpack.Progress.*100%" "$LOG" 2>/dev/null; then
+    echo "[refresh] Webpack reached 100% (${i}s)"
+    break
+  fi
+  if ! kill -0 "$BUILD_PID" 2>/dev/null; then
+    echo "FAIL: yarn start exited before clean pass" >&2
+    tail -40 "$LOG" 2>/dev/null || true
+    exit 2
+  fi
+  if [ $((i % 10)) -eq 0 ]; then
+    echo "[refresh] still waiting for clean... (${i}s)"
+    tail -5 "$LOG" 2>/dev/null | sed 's/^/[refresh:log] /' || true
+  fi
+  sleep 1
+done
+if ! grep -q "Finished 'clean'" "$LOG" 2>/dev/null && ! grep -q "webpack.Progress.*100%" "$LOG" 2>/dev/null; then
+  echo "FAIL: build did not reach clean/100% within ${CLEAN_TIMEOUT_S}s" >&2
+  tail -40 "$LOG" 2>/dev/null || true
+  exit 2
+fi
+
+echo "[refresh] Waiting for entry points (timeout ${TIMEOUT_S}s): ${HTML_ENTRIES[*]}"
+for i in $(seq 1 "$TIMEOUT_S"); do
+  ready=true
+  for entry in "${HTML_ENTRIES[@]}"; do
+    if [ ! -f "$REPO/${entry}" ]; then
+      ready=false
+      break
+    fi
+  done
+  $ready && break
+  if [ $((i % 15)) -eq 0 ]; then
+    echo "[refresh] still building entry points... (${i}s)"
+    tail -5 "$LOG" 2>/dev/null | sed 's/^/[refresh:log] /' || true
+  fi
+  sleep 1
+done
+
+all_present=true
+for entry in "${HTML_ENTRIES[@]}"; do
+  if [ ! -f "$REPO/${entry}" ]; then
+    all_present=false
+    echo "[refresh] MISSING: ${entry}"
+  fi
+done
+
+if ! $all_present; then
+  echo "FAIL: rebuild did not restore all entry points within ${TIMEOUT_S}s" >&2
+  tail -40 "$LOG" 2>/dev/null || true
+  exit 2
+fi
+
+# Kill the watcher — leave dist fresh and frozen.
+kill "$BUILD_PID" 2>/dev/null || true
+wait "$BUILD_PID" 2>/dev/null || true
+trap - EXIT
+
+echo "[refresh] Build refreshed and frozen — run: recipe reopen"
+echo "[refresh] Log kept at: $LOG"