@deeeed/metamask-harness 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.37.0 - 2026-08-13
+
+### Added
+
+- Add archive and extracted-tree integrity checks, caching, provenance, and isolated launch for downloaded Extension release artifacts without using the checkout build or product configuration.
+- Add verified local Android APK install and launch with expected version name, version code, package ID, trusted digest, explicit device selection, terminal provenance, and native-accessibility recipes that do not require a development bridge or HUD.
+- Add an Extension Perps snapshot action for bounded, redacted account, market, position, open-order, history, and watchlist observations when the background test hook is available.
+- Add a release QA capability map covering the current Perps, Assets, Swap and Bridge, and Networks checklists, with a prioritized parity roadmap.
+- Add native Android release navigation and accessibility observation for wallet home, Perps home, and parameterized Perps markets without Metro, a development bridge, a HUD, or fixed screen coordinates.
+
+### Fixed
+
+- Probe Ethereum through the Extension UI provider when production builds omit test state hooks, while preserving explicit unreachable failures.
+- Import recovery phrases through production LavaMoat onboarding without browser clipboard permissions, and remove the temporary browser bridge after use.
+- Keep release-artifact recipe failures on the acquired binary and fail closed instead of recovering through a checkout build.
+- Relaunch a stopped verified Extension artifact from its integrity-checked cache without switching builds or deleting the imported wallet profile.
+- Recover a newly opened Extension home tab from Chromium's transient blocked-page shell by navigating the selected extension target once before readiness fails.
+- Prefer the visible side panel after official-build onboarding opens it, instead of leaving recipes attached to the completed onboarding tab.
+- Reject unattended biometric setup explicitly, handle default Mobile notification and wallet-tour choices on bridge-backed onboarding, and keep Extension-only Perps snapshot limits out of Core validation.
+- Confine Extension runtime snapshots and artifact identity state to non-symlinked checkout runtime directories before replacing prior state.
+- Complete opaque Mobile onboarding without Metro or a development bridge by cancelling biometric storage for password-only automation, handling notification and wallet-tour prompts with configurable defaults, and proving the imported address through native UI.
+- Close each physical-device accessibility session only after its wallet proof completes, so composed reset/import/state recipes hand the device to the next node cleanly.
+- Label artifact preparation as preparation instead of reporting it as a client build.
+
 ## 0.36.0 - 2026-08-13
 
 ### Added

package/adapters/extension/artifact-runtime-state.cjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log('Usage: artifact-runtime-state.cjs <set|clear> --target <absolute-dir> --runtime-dir <relative-dir> [--source-dir <absolute-dir> --runtime-dist <absolute-dir> --provenance <absolute-file>]');
+  process.exit(0);
+}
+
+const [action, ...argv] = process.argv.slice(2);
+const args = parseArgs(argv);
+const target = requiredPath(args, 'target');
+const runtimeDir = requiredRelative(args, 'runtime-dir');
+
+if (action === 'clear') {
+  const directory = safeRuntimeDirectory(target, runtimeDir, false);
+  if (!directory) process.exit(0);
+  const statePath = path.join(directory, 'extension-release-artifact.json');
+  const existing = fs.lstatSync(statePath, { throwIfNoEntry: false });
+  if (!existing) process.exit(0);
+  if (!existing.isFile() || existing.isSymbolicLink()) throw invalidRuntimeState(statePath);
+  fs.unlinkSync(statePath);
+  process.exit(0);
+}
+if (action !== 'set') throw new Error('Usage: artifact-runtime-state.cjs <set|clear> --target <dir> --runtime-dir <relative> [set flags]');
+
+const sourceDir = requiredPath(args, 'source-dir');
+const runtimeDist = requiredPath(args, 'runtime-dist');
+const provenancePath = requiredPath(args, 'provenance');
+const provenance = readRegularJson(provenancePath);
+const relativeExtensionDir = provenance.extensionDir;
+if (
+  typeof relativeExtensionDir !== 'string' ||
+  !relativeExtensionDir ||
+  path.isAbsolute(relativeExtensionDir) ||
+  relativeExtensionDir.split(/[\\/]+/).includes('..')
+) {
+  throw new Error('Release artifact provenance has an invalid extensionDir.');
+}
+const provenanceRoot = path.dirname(provenancePath);
+const boundSource = path.resolve(provenanceRoot, relativeExtensionDir);
+if (boundSource !== sourceDir) throw new Error('Release artifact provenance does not bind the selected extension directory.');
+if (!/^[a-f0-9]{64}$/.test(provenance.sha256 || '')) throw new Error('Release artifact provenance has an invalid SHA-256.');
+if (!/^[a-f0-9]{64}$/.test(provenance.treeSha256 || '')) throw new Error('Release artifact provenance has an invalid tree SHA-256.');
+if (!fs.existsSync(path.join(sourceDir, 'manifest.json'))) throw new Error('Release artifact source manifest is missing.');
+if (!fs.existsSync(path.join(runtimeDist, 'manifest.json'))) throw new Error('Release artifact runtime manifest is missing.');
+
+const state = {
+  schemaVersion: 1,
+  sourceDir,
+  runtimeDist,
+  provenancePath,
+  sha256: provenance.sha256,
+  treeSha256: provenance.treeSha256,
+  expectedVersion: provenance.expectedVersion,
+  manifestVersion: provenance.manifestVersion,
+  recordedAt: new Date().toISOString(),
+};
+const directory = safeRuntimeDirectory(target, runtimeDir, true);
+const statePath = path.join(directory, 'extension-release-artifact.json');
+const existing = fs.lstatSync(statePath, { throwIfNoEntry: false });
+if (existing && (!existing.isFile() || existing.isSymbolicLink())) throw invalidRuntimeState(statePath);
+const temporary = `${statePath}.${process.pid}.tmp`;
+fs.writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+fs.renameSync(temporary, statePath);
+
+function parseArgs(values) {
+  const parsed = {};
+  for (let index = 0; index < values.length; index += 2) {
+    const flag = values[index];
+    const value = values[index + 1];
+    if (!flag?.startsWith('--') || value === undefined) throw new Error(`Invalid argument: ${flag || ''}`);
+    parsed[flag.slice(2)] = value;
+  }
+  return parsed;
+}
+
+function requiredPath(values, key) {
+  if (!values[key] || !path.isAbsolute(values[key])) throw new Error(`--${key} must be an absolute path.`);
+  return path.resolve(values[key]);
+}
+
+function requiredRelative(values, key) {
+  const value = values[key];
+  const parts = value?.split(/[\\/]+/) ?? [];
+  if (!value || path.isAbsolute(value) || parts.some((part) => !part || part === '.' || part === '..')) {
+    throw new Error(`--${key} must be a safe relative path.`);
+  }
+  return value;
+}
+
+function safeRuntimeDirectory(target, runtimeDir, create) {
+  const targetStat = fs.lstatSync(target, { throwIfNoEntry: false });
+  if (!targetStat?.isDirectory() || targetStat.isSymbolicLink()) {
+    throw invalidRuntimeState(path.join(target, runtimeDir));
+  }
+  let current = target;
+  for (const component of runtimeDir.split(/[\\/]+/)) {
+    current = path.join(current, component);
+    const stat = fs.lstatSync(current, { throwIfNoEntry: false });
+    if (!stat) {
+      if (!create) return null;
+      fs.mkdirSync(current, { mode: 0o700 });
+      continue;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw invalidRuntimeState(current);
+  }
+  const realTarget = fs.realpathSync(target);
+  const realRuntime = fs.realpathSync(current);
+  if (realRuntime !== realTarget && !realRuntime.startsWith(`${realTarget}${path.sep}`)) {
+    throw invalidRuntimeState(current);
+  }
+  return current;
+}
+
+function invalidRuntimeState(file) {
+  return new Error(`Release artifact runtime state path is unsafe: ${file}`);
+}
+
+function readRegularJson(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > 64 * 1024) {
+    throw new Error(`Release artifact provenance must be a regular JSON file: ${file}`);
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}

package/adapters/extension/inject.mjs

@@ -104,6 +104,7 @@ copyFile(path.join(runnerDir, 'adapters/extension/sync-webpack-dist.cjs'), path.
 copyFile(path.join(runnerDir, 'adapters/extension/configure-runtime-manifest.cjs'), path.join(harnessDir, 'scripts/configure-runtime-manifest.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/check-infura-readiness.cjs'), path.join(harnessDir, 'scripts/check-infura-readiness.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/stamp-runtime-title.cjs'), path.join(harnessDir, 'scripts/stamp-runtime-title.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/artifact-runtime-state.cjs'), path.join(harnessDir, 'scripts/artifact-runtime-state.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/stop-viewers.sh'), path.join(harnessDir, 'scripts/stop-viewers.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/snapshot-dist.sh'), path.join(harnessDir, 'scripts/snapshot-dist.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/pin-remote-flags.cjs'), path.join(harnessDir, 'scripts/pin-remote-flags.cjs'));

package/adapters/extension/launch-browser.cjs

@@ -72,6 +72,7 @@ if (args['stop-only'] === undefined) {
 // injects its own already-isolated profile via runtime-context, so this only trips
 // on a genuinely personal/shared path — protecting the user's browser data.
 assertIsolatedProfile(args.profile);
+if (args['reset-profile'] !== undefined) assertResettableProfile(args.profile, runtimeDir);
 
 fs.mkdirSync(args.profile, { recursive: true });
 fs.mkdirSync(path.dirname(args['chrome-log']), { recursive: true });
@@ -301,6 +302,27 @@ function assertIsolatedProfile(profile) {
   }
 }
 
+function assertResettableProfile(profile, expectedRuntimeDir) {
+  const resolved = path.resolve(profile);
+  const runtime = path.resolve(expectedRuntimeDir);
+  if (!resolved.startsWith(`${runtime}${path.sep}`)) {
+    throw new Error(`Refusing to reset --profile ${resolved}: it must be a dedicated child of ${runtime}.`);
+  }
+  const runtimeStat = fs.lstatSync(runtime);
+  if (!runtimeStat.isDirectory() || runtimeStat.isSymbolicLink()) {
+    throw new Error(`Refusing to reset --profile: runtime directory is not a regular directory: ${runtime}.`);
+  }
+  let current = runtime;
+  for (const segment of path.relative(runtime, resolved).split(path.sep)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) break;
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`Refusing to reset --profile: path contains an unsafe entry: ${current}.`);
+    }
+  }
+}
+
 // Proof of ownership: a process is ours iff its command line loads the exact
 // --user-data-dir we launch with. If the process can't be inspected we treat it
 // as NOT ours (fail safe — never assume ownership of an opaque process).

package/adapters/extension/live.sh

@@ -43,6 +43,9 @@ PREPARE_CMD="${RECIPE_HARNESS_EXTENSION_LAUNCH_CMD:-}"
 LAUNCH_EXISTING_DIST=false
 START_WATCH=false
 BUILD_LAVAMOAT=false
+EXTERNAL_ARTIFACT=false
+ARTIFACT_PROVENANCE=""
+RESET_PROFILE=true
 DIST_DIR="dist/chrome"
 CHROME_USER_DATA_DIR="${CHROME_USER_DATA_DIR:-}"
 REMOTE_FLAGS=""
@@ -56,6 +59,9 @@ while [ "$#" -gt 0 ]; do
     --artifacts-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; ARTIFACTS="$2"; shift 2 ;;
     --prepare-cmd) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; PREPARE_CMD="$2"; shift 2 ;;
     --launch-existing-dist) LAUNCH_EXISTING_DIST=true; shift ;;
+    --external-artifact) EXTERNAL_ARTIFACT=true; LAUNCH_EXISTING_DIST=true; shift ;;
+    --artifact-provenance) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; ARTIFACT_PROVENANCE="$2"; shift 2 ;;
+    --preserve-profile) RESET_PROFILE=false; shift ;;
     --start-url) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; START_URL="$2"; shift 2 ;;
     --start-watch|--start-test-watch) START_WATCH=true; LAUNCH_EXISTING_DIST=true; shift ;;
     --build-lavamoat) BUILD_LAVAMOAT=true; LAUNCH_EXISTING_DIST=true; shift ;;
@@ -63,7 +69,7 @@ while [ "$#" -gt 0 ]; do
     --dist-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; DIST_DIR="$2"; shift 2 ;;
     --chrome-user-data-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; CHROME_USER_DATA_DIR="$2"; shift 2 ;;
     --remote-flag) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; REMOTE_FLAGS="$2"; shift 2 ;;
-    -h|--help) echo "Usage: live.sh [--target <metamask-extension>] [--out <recipes-dir>] [--cdp-port <port>] [--launch-existing-dist|--start-watch|--build-lavamoat|--prepare-cmd <cmd>] [--launch-only] [--dist-dir dist/chrome] [--remote-flag KEY=VARIANT] [--artifacts-dir <dir>]"; exit 0 ;;
+    -h|--help) echo "Usage: live.sh [--target <metamask-extension>] [--out <recipes-dir>] [--cdp-port <port>] [--launch-existing-dist|--start-watch|--build-lavamoat|--external-artifact --dist-dir <absolute-dir> --artifact-provenance <absolute-file> [--preserve-profile]|--prepare-cmd <cmd>] [--launch-only] [--dist-dir dist/chrome] [--remote-flag KEY=VARIANT] [--artifacts-dir <dir>]"; exit 0 ;;
     *) echo "Unknown arg: $1" >&2; exit 2 ;;
   esac
 done
@@ -72,6 +78,24 @@ if $BUILD_LAVAMOAT && $START_WATCH; then
   echo "--build-lavamoat cannot be combined with --start-watch" >&2
   exit 2
 fi
+if $EXTERNAL_ARTIFACT && { $BUILD_LAVAMOAT || $START_WATCH || [ -n "$REMOTE_FLAGS" ]; }; then
+  echo "--external-artifact cannot be combined with build, watch, or remote-flag options" >&2
+  exit 2
+fi
+if $EXTERNAL_ARTIFACT && [ ! -f "$ARTIFACT_PROVENANCE" ]; then
+  echo "--external-artifact requires --artifact-provenance <file>" >&2
+  exit 2
+fi
+if ! $RESET_PROFILE && ! $EXTERNAL_ARTIFACT; then
+  echo "--preserve-profile is only valid for a verified external artifact" >&2
+  exit 2
+fi
+if $EXTERNAL_ARTIFACT; then
+  case "$ARTIFACT_PROVENANCE" in
+    /*) ;;
+    *) echo "--artifact-provenance must be an absolute file path" >&2; exit 2 ;;
+  esac
+fi
 
 case "$CHROME_USER_DATA_DIR" in
   ""|/*) ;;
@@ -120,6 +144,12 @@ if [ -z "$VERIFY_SH" ]; then
 fi
 RUNTIME_DIR="$(recipe_runtime_dir)"
 RUNTIME_DIST_DIR="${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}"
+case "$RUNTIME_DIST_DIR" in
+  ""|.|..|*/*|*[!A-Za-z0-9._-]*)
+    echo "RECIPE_RUNTIME_DIST_DIR must be one safe directory name: '$RUNTIME_DIST_DIR'" >&2
+    exit 2
+    ;;
+esac
 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
@@ -145,21 +175,36 @@ if [ -d "$LIVE_ROOT" ]; then
 fi
 
 if $LAUNCH_EXISTING_DIST && [ -z "$PREPARE_CMD" ]; then
-  DIST_ABS="$TARGET/$DIST_DIR"
+  if $EXTERNAL_ARTIFACT; then
+    case "$DIST_DIR" in
+      /*) DIST_ABS="$DIST_DIR" ;;
+      *) echo "--external-artifact requires an absolute --dist-dir" >&2; exit 2 ;;
+    esac
+  else
+    DIST_ABS="$TARGET/$DIST_DIR"
+  fi
   # 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/$RUNTIME_DIR/$RUNTIME_DIST_DIR"
+  RUNTIME_ROOT_ABS="$TARGET/$RUNTIME_DIR"
+  RUNTIME_DIST_ABS="$RUNTIME_ROOT_ABS/$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/$RUNTIME_DIR/$CHROME_PROFILE_NAME}"
+  case "$PROFILE_ABS" in
+    "$TARGET/$RUNTIME_DIR/"*) ;;
+    *) echo "--chrome-user-data-dir must be a dedicated child of $TARGET/$RUNTIME_DIR" >&2; exit 2 ;;
+  esac
   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.
-  WALLET_FIXTURE_ABS="$(bash "$SCRIPT_DIR/seed-fixture.sh" resolve --target "$TARGET" --cdp-port "$CDP_PORT" --source-out "$ARTIFACTS/logs/fixture-source.json")"
-  if [ ! -f "$ARTIFACTS/logs/fixture-source.json" ]; then
+  WALLET_FIXTURE_ABS=""
+  if ! $EXTERNAL_ARTIFACT; then
+    # Wallet fixture resolution chain + provenance live in seed-fixture.sh.
+    WALLET_FIXTURE_ABS="$(bash "$SCRIPT_DIR/seed-fixture.sh" resolve --target "$TARGET" --cdp-port "$CDP_PORT" --source-out "$ARTIFACTS/logs/fixture-source.json")"
+  fi
+  if ! $EXTERNAL_ARTIFACT && [ ! -f "$ARTIFACTS/logs/fixture-source.json" ]; then
     # resolve failed before writing provenance (invalid RECIPE_WALLET_FIXTURE);
     # keep the documented missing-provenance artifact.
     node - "$ARTIFACTS/logs/fixture-source.json" "" <<'NODE'
@@ -175,6 +220,7 @@ NODE
   fi
   mkdir -p "$PROFILE_ABS"
   quoted_dist="$(printf '%q' "$DIST_ABS")"
+  quoted_runtime_root="$(printf '%q' "$RUNTIME_ROOT_ABS")"
   quoted_runtime_dist="$(printf '%q' "$RUNTIME_DIST_ABS")"
   quoted_profile="$(printf '%q' "$PROFILE_ABS")"
   quoted_seed_fixture="$(printf '%q' "$SCRIPT_DIR/seed-fixture.sh")"
@@ -185,6 +231,7 @@ NODE
   quoted_check_infura="$(printf '%q' "$SCRIPT_DIR/check-infura-readiness.cjs")"
   quoted_stamp_title="$(printf '%q' "$SCRIPT_DIR/stamp-runtime-title.cjs")"
   quoted_chrome_launcher="$(printf '%q' "$SCRIPT_DIR/launch-browser.cjs")"
+  quoted_artifact_state="$(printf '%q' "$SCRIPT_DIR/artifact-runtime-state.cjs")"
   quoted_fixture_state="$(printf '%q' "$FIXTURE_STATE_ABS")"
   quoted_fixture_validation="$(printf '%q' "$FIXTURE_VALIDATION_ABS")"
   quoted_extension_id_file="$(printf '%q' "$TARGET/$RUNTIME_DIR/extension.id")"
@@ -257,17 +304,37 @@ NODE
   quoted_chrome_log="$(printf '%q' "$ARTIFACTS/logs/chrome.log")"
   quoted_chrome_pid="$(printf '%q' "$ARTIFACTS/logs/chrome.pid")"
   prepare_parts=()
+  if $EXTERNAL_ARTIFACT; then
+    quoted_artifact_provenance="$(printf '%q' "$ARTIFACT_PROVENANCE")"
+  else
+    node "$SCRIPT_DIR/artifact-runtime-state.cjs" clear --target "$TARGET" --runtime-dir "$RUNTIME_DIR"
+  fi
   if $START_WATCH; then
     prepare_parts+=("bash ${quoted_start_watch} --runtime-dir ${quoted_runtime_dir} --runner-bin ${quoted_runner}")
   fi
   if $BUILD_LAVAMOAT; then
     prepare_parts+=("bash ${quoted_build_lavamoat} --target ${quoted_target} --runtime-dir ${quoted_runtime_dir}")
   fi
-  prepare_parts+=("node ${quoted_check_infura} --target ${quoted_target} --runtime-dist ${quoted_dist}")
-  prepare_parts+=("bash ${quoted_snapshot_dist} --dist ${quoted_dist} --runtime-dist ${quoted_runtime_dist}")
-  prepare_parts+=("node ${quoted_configure_manifest} --target ${quoted_target} --manifest ${quoted_runtime_dist}/manifest.json")
-  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+=("node ${quoted_stamp_title} --target ${quoted_target} --runtime-dist ${quoted_runtime_dist} --runtime-dir ${quoted_runtime_dir}")
+  if ! $EXTERNAL_ARTIFACT; then
+    prepare_parts+=("node ${quoted_check_infura} --target ${quoted_target} --runtime-dist ${quoted_dist}")
+  fi
+  if $EXTERNAL_ARTIFACT; then
+    prepare_parts+=("bash ${quoted_snapshot_dist} --dist ${quoted_dist} --target ${quoted_target} --runtime-root ${quoted_runtime_root} --runtime-dist ${quoted_runtime_dist} --exact")
+  else
+    prepare_parts+=("bash ${quoted_snapshot_dist} --dist ${quoted_dist} --target ${quoted_target} --runtime-root ${quoted_runtime_root} --runtime-dist ${quoted_runtime_dist}")
+  fi
+  if $EXTERNAL_ARTIFACT; then
+    prepare_parts+=("node ${quoted_artifact_state} set --target ${quoted_target} --runtime-dir ${quoted_runtime_dir} --source-dir ${quoted_dist} --runtime-dist ${quoted_runtime_dist} --provenance ${quoted_artifact_provenance}")
+  fi
+  if ! $EXTERNAL_ARTIFACT; then
+    prepare_parts+=("node ${quoted_configure_manifest} --target ${quoted_target} --manifest ${quoted_runtime_dist}/manifest.json")
+  fi
+  reset_profile_arg=""
+  $RESET_PROFILE && reset_profile_arg=" --reset-profile 1"
+  prepare_parts+=("node ${quoted_chrome_launcher} --stop-only 1${reset_profile_arg} --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}")
+  if ! $EXTERNAL_ARTIFACT; then
+    prepare_parts+=("node ${quoted_stamp_title} --target ${quoted_target} --runtime-dist ${quoted_runtime_dist} --runtime-dir ${quoted_runtime_dir}")
+  fi
   # Optional A/B feature-flag pinning: patch the ephemeral snapshot manifest so
   # manifest._flags wins over the fetched ClientConfigApi value. No-op unless
   # --remote-flag was passed; the snapshot is re-created each run, so no revert.
@@ -302,6 +369,8 @@ echo "Extension live validation command:"
 display_args=(mm-harness runtime-launch --adapter extension --target "$TARGET" --cdp-port "$CDP_PORT")
 $START_WATCH && display_args+=(--start-watch)
 $BUILD_LAVAMOAT && display_args+=(--build-lavamoat)
+$EXTERNAL_ARTIFACT && display_args+=(--external-artifact --dist-dir "$DIST_DIR" --artifact-provenance "$ARTIFACT_PROVENANCE")
+$RESET_PROFILE || display_args+=(--preserve-profile)
 [ -n "$REMOTE_FLAGS" ] && display_args+=(--remote-flag "$REMOTE_FLAGS")
 [ -n "$CHROME_USER_DATA_DIR" ] && display_args+=(--chrome-user-data-dir "$CHROME_USER_DATA_DIR")
 printf '  '
@@ -333,7 +402,7 @@ else
   echo "Skipping Extension live verify for launch-only fixture application." >&2
 fi
 
-TARGET_FOR_SUMMARY="$TARGET" ARTIFACTS_FOR_SUMMARY="$ARTIFACTS" CDP_PORT_FOR_SUMMARY="$CDP_PORT" LAUNCH_STATUS="$launch_status" VERIFY_STATUS="$verify_status" RUN_VERIFY="$RUN_VERIFY" LAUNCH_EXISTING_DIST="$LAUNCH_EXISTING_DIST" START_WATCH="$START_WATCH" BUILD_LAVAMOAT="$BUILD_LAVAMOAT" node <<'NODE'
+TARGET_FOR_SUMMARY="$TARGET" ARTIFACTS_FOR_SUMMARY="$ARTIFACTS" CDP_PORT_FOR_SUMMARY="$CDP_PORT" LAUNCH_STATUS="$launch_status" VERIFY_STATUS="$verify_status" RUN_VERIFY="$RUN_VERIFY" LAUNCH_EXISTING_DIST="$LAUNCH_EXISTING_DIST" START_WATCH="$START_WATCH" BUILD_LAVAMOAT="$BUILD_LAVAMOAT" EXTERNAL_ARTIFACT="$EXTERNAL_ARTIFACT" node <<'NODE'
 const fs = require('fs');
 const path = require('path');
 const artifacts = process.env.ARTIFACTS_FOR_SUMMARY;
@@ -351,6 +420,7 @@ fs.writeFileSync(path.join(artifacts, 'summary.json'), `${JSON.stringify({
   launchExistingDist: process.env.LAUNCH_EXISTING_DIST === 'true',
   startWatch: process.env.START_WATCH === 'true',
   buildLavaMoat: process.env.BUILD_LAVAMOAT === 'true',
+  externalArtifact: process.env.EXTERNAL_ARTIFACT === 'true',
   launch: { exitCode: launchStatus, summaryPath: fs.existsSync(launchSummary) ? launchSummary : null },
   verify: runVerify
     ? { status: verifyStatus === 0 ? 'pass' : 'fail', exitCode: verifyStatus, summaryPath: fs.existsSync(verifySummary) ? verifySummary : null }

package/adapters/extension/readiness.mjs

@@ -64,10 +64,29 @@ function parseArgs(argv) {
   return out;
 }
 
+function extensionBuildRoot(target) {
+  const runtimeRoot = path.join(target, recipeRuntimeDir());
+  const statePath = path.join(runtimeRoot, 'extension-release-artifact.json');
+  if (!fs.existsSync(statePath)) return path.join(target, 'dist/chrome');
+  try {
+    const stat = fs.lstatSync(statePath);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > 64 * 1024) {
+      throw new Error('Loaded release artifact identity is not a regular bounded file.');
+    }
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    const expected = path.join(runtimeRoot, process.env.RECIPE_RUNTIME_DIST_DIR || 'runtime-dist');
+    if (state.schemaVersion === 1 && path.resolve(state.runtimeDist || '') === expected) return expected;
+  } catch (error) {
+    throw new Error(`Loaded release artifact identity is invalid: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  throw new Error('Loaded release artifact identity is invalid.');
+}
+
 function readManifest(target) {
-  const manifestPath = path.join(target, 'dist/chrome/manifest.json');
+  const buildRoot = extensionBuildRoot(target);
+  const manifestPath = path.join(buildRoot, 'manifest.json');
   const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-  return { manifestPath, manifest };
+  return { buildRoot, manifestPath, manifest };
 }
 
 function manifestExpectedFiles(manifest) {
@@ -190,6 +209,17 @@ function resolveWebSocket(target) {
 }
 
 async function cdpEvaluate(target, webSocketDebuggerUrl, expression, timeoutMs = 5000) {
+  const result = await cdpCall(
+    target,
+    webSocketDebuggerUrl,
+    'Runtime.evaluate',
+    { expression, awaitPromise: true, returnByValue: true },
+    timeoutMs,
+  );
+  return result?.result?.value ?? null;
+}
+
+async function cdpCall(target, webSocketDebuggerUrl, method, params, timeoutMs = 5000) {
   assertLocalWebSocketUrl(webSocketDebuggerUrl);
   const WebSocketImpl = resolveWebSocket(target);
   if (!WebSocketImpl) return { skipped: true, reason: 'WebSocket unavailable in this Node runtime' };
@@ -206,8 +236,8 @@ async function cdpEvaluate(target, webSocketDebuggerUrl, expression, timeoutMs =
     const onOpen = () => {
       ws.send(JSON.stringify({
         id: 1,
-        method: 'Runtime.evaluate',
-        params: { expression, awaitPromise: true, returnByValue: true },
+        method,
+        params,
       }));
     };
     const onMessage = (event) => {
@@ -220,11 +250,11 @@ async function cdpEvaluate(target, webSocketDebuggerUrl, expression, timeoutMs =
         reject(new Error(msg.error.message || JSON.stringify(msg.error)));
         return;
       }
-      resolve(msg.result?.result?.value ?? null);
+      resolve(msg.result ?? null);
     };
     const onError = (err) => {
       clearTimeout(timer);
-      reject(new Error(`CDP websocket error while inspecting extension page: ${err?.message || err || 'unknown'}`));
+      reject(new Error(`CDP websocket error during ${method}: ${err?.message || err || 'unknown'}`));
     };
     if (typeof ws.on === 'function') {
       ws.on('open', onOpen);
@@ -286,6 +316,23 @@ async function openExtensionPage(cdpPort, extensionId, pagePath) {
   }
 }
 
+const PAGE_UI_EXPRESSION = `(() => {
+  const text = document.body?.innerText || '';
+  const cell = (sel) => document.querySelector(sel)?.innerText?.trim() || '';
+  const errorBoundaryMessage = cell('[data-testid="error-page-error-message"]');
+  const errorBoundaryName = cell('[data-testid="error-page-error-name"]');
+  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) : ''),
+  };
+})()`;
+
 // The page path only, with any '#fragment' or '?query' stripped. The app router
 // rewrites home.html to home.html#/ once loaded, so an exact '/home.html' suffix
 // match must compare against this, not the raw url.
@@ -349,29 +396,7 @@ async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceW
   // 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,
-      `(() => {
-        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) : ''),
-        };
-      })()`,
-    );
+    ui = await cdpEvaluate(target, pageTarget.webSocketDebuggerUrl, PAGE_UI_EXPRESSION);
     pageInspected = Boolean(ui) && !ui.skipped;
     if (pageInspected && ui.hasStartupError) {
       throw Object.assign(new Error('MetaMask extension page loaded startup error UI'), {
@@ -385,9 +410,25 @@ async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceW
       });
     }
     if (pageInspected && 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 } },
-      });
+      const destination = `chrome-extension://${selectedExtensionId}/${String(extensionPagePath || 'home.html').replace(/^\/+/u, '')}`;
+      await cdpCall(
+        target,
+        pageTarget.webSocketDebuggerUrl,
+        'Page.navigate',
+        { url: destination },
+      );
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      ui = await cdpEvaluate(target, pageTarget.webSocketDebuggerUrl, PAGE_UI_EXPRESSION);
+      if (
+        !ui ||
+        String(ui.url || '').startsWith('chrome-error://') ||
+        ui.hasStartupError ||
+        ui.hasErrorBoundary
+      ) {
+        throw Object.assign(new Error('MetaMask extension page loaded Chrome error UI'), {
+          report: { cdp: { browser: version.Browser || 'unknown', selectedExtensionId, ui } },
+        });
+      }
     }
     if (pageInspected && slotId) {
       const stampedTitle = await cdpEvaluate(
@@ -419,12 +460,12 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   const target = path.resolve(args.target);
   const checks = [];
-  const { manifestPath, manifest } = readManifest(target);
+  const { buildRoot, 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' });
+    const exists = fs.existsSync(path.join(buildRoot, rel));
+    checks.push({ name: `${path.relative(target, buildRoot)}/${rel}`, status: exists ? 'pass' : 'fail' });
     if (!exists) missingFiles.push(rel);
   }
   if (missingFiles.length > 0) {
@@ -434,7 +475,7 @@ async function main() {
     );
   }
 
-  const defaultPage = fs.existsSync(path.join(target, 'dist/chrome/home.html'))
+  const defaultPage = fs.existsSync(path.join(buildRoot, 'home.html'))
     ? 'home.html'
     : manifestDefaultPage(manifest);
   const report = {