@deeeed/metamask-harness 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## 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
+
+- Add a composable Mobile and Extension wallet import recipe that either verifies an existing fixture-backed profile or imports the primary mnemonic through visible onboarding UI, with secret-safe inputs, privacy-preserving defaults, and configurable MetaMetrics and Mobile interests.
+- Add `fixtures reset` plus a shared Mobile/Extension reset-import recipe. Extension resets its owned browser profile; Mobile clears only the selected app's data while preserving its installed build. The visible recipe separately proves the real user reset and import flow.
+
+### Fixed
+
+- Restart a harness-owned Extension watcher when its effective Infura credential differs from the current product configuration, and preflight compiled Ethereum and Linea credentials before Chrome starts, preventing a forced-red validation from poisoning later launches or opening a native HTTP authentication dialog.
+- Make normal Extension launch and runtime recovery use the product's `yarn start` development build, while keeping production-like LavaMoat builds behind explicit `launch --build`.
+- Require wallet profile reuse to match the requested account, wait for Mobile onboarding to reach a terminal route, and resolve the exact Mobile reset device and prewarm its bundle before relaunching after app-data reset.
+- Refuse ambiguous installed Mobile app variants during reset, prefer complete environment wallet credentials without parsing a stale fixture, and reject bad Extension RPC configuration before replacing the loaded runtime snapshot.
+- Validate recovery credentials, fixture structure, and platform-specific onboarding choices before destructive resets; prove Mobile reset by the visible import control; honor persisted MetaMetrics consent through Security settings; and keep file-backed wallet secrets out of bridge errors.
+
 ## 0.35.0 - 2026-08-12
 
 ### Fixed

package/README.md

@@ -88,10 +88,14 @@ mm-harness stop
 mm-harness logs
 mm-harness debug
 mm-harness fixtures set
+
+# Delete the current wallet, then reapply the canonical fixture from clean state.
+mm-harness fixtures reset
 ```
 
 Extension `launch` keeps its incremental watcher running. Refresh the active
-page after a successful rebuild; use `launch --build` only for a clean rebuild.
+page after a successful rebuild; use `launch --build` only for an explicit
+production-like LavaMoat rebuild.
 
 Log sources stay separate:
 
@@ -115,6 +119,10 @@ mm-harness call metamask.wallet.ensure_unlocked
 mm-harness run --list
 mm-harness run perps.clean-market-testnet --describe
 mm-harness run wallet.smoke --describe
+mm-harness run wallet.import method=auto
+
+# Use visible client UI to delete and import the wallet again.
+mm-harness run wallet.reset-import
 mm-harness run path/to/recipe.json market=ETH --plan
 mm-harness run path/to/recipe.json
 ```

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/check-infura-readiness.cjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const https = require('node:https');
+const path = require('node:path');
+
+const args = {};
+for (let index = 2; index < process.argv.length; index += 1) {
+  const key = process.argv[index];
+  if (key === '--help' || key === '-h') {
+    process.stdout.write('Usage: check-infura-readiness.cjs --target <metamask-extension> --runtime-dist <dist>\n');
+    process.exit(0);
+  }
+  if (!key.startsWith('--') || index + 1 >= process.argv.length) {
+    throw new Error(`invalid argument: ${key}`);
+  }
+  args[key.slice(2)] = process.argv[++index];
+}
+
+for (const key of ['target', 'runtime-dist']) {
+  if (!args[key]) throw new Error(`--${key} is required`);
+}
+
+const target = path.resolve(args.target);
+const runtimeDist = path.resolve(args['runtime-dist']);
+const config = require('./lib/product-config.cjs');
+
+async function main() {
+  const resolution = config.resolveExtensionInfuraProjectId(target, process.env);
+  if (resolution.kind !== 'configured') {
+    fail('the effective Extension product configuration has no usable Infura project ID');
+  }
+  if (!compiledScriptsContain(runtimeDist, resolution.value)) {
+    fail('the compiled Extension scripts do not match the effective Infura project ID');
+  }
+  for (const host of ['mainnet.infura.io', 'linea-mainnet.infura.io']) {
+    const response = await rpcProbe(host, resolution.value);
+    if (response.statusCode < 200 || response.statusCode >= 300 || response.jsonRpcResult !== true) {
+      fail(`${host} rejected the effective Infura project ID (HTTP ${response.statusCode})`);
+    }
+  }
+  process.stdout.write('Infura readiness preflight passed for Ethereum and Linea.\n');
+}
+
+function compiledScriptsContain(root, value) {
+  const pending = [root];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const file = path.join(current, entry.name);
+      if (entry.isDirectory()) pending.push(file);
+      else if (entry.isFile() && entry.name.endsWith('.js') && fs.readFileSync(file, 'utf8').includes(value)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function rpcProbe(host, projectId) {
+  const body = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_chainId', params: [] });
+  return new Promise((resolve, reject) => {
+    const request = https.request({
+      hostname: host,
+      path: `/v3/${encodeURIComponent(projectId)}`,
+      method: 'POST',
+      timeout: 10_000,
+      headers: {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(body),
+      },
+    }, (response) => {
+      let text = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => { text += chunk; });
+      response.on('end', () => {
+        let jsonRpcResult = false;
+        try {
+          const parsed = JSON.parse(text);
+          jsonRpcResult = typeof parsed.result === 'string' && parsed.result.startsWith('0x');
+        } catch {
+          jsonRpcResult = false;
+        }
+        resolve({ statusCode: response.statusCode || 0, jsonRpcResult });
+      });
+    });
+    request.on('timeout', () => request.destroy(new Error(`${host} timed out`)));
+    request.on('error', reject);
+    request.end(body);
+  });
+}
+
+function fail(detail) {
+  process.stderr.write(
+    `EVM_RPC_UNREACHABLE: Infura readiness preflight failed before browser launch: ${detail}.\n` +
+      `Next: stop the stale watcher, confirm ${path.join(target, '.metamaskrc')} has a real INFURA_PROJECT_ID, then rerun mm-harness launch --verify --target ${JSON.stringify(target)}.\n`,
+  );
+  process.exit(1);
+}
+
+main().catch((error) => fail(error instanceof Error ? error.message : String(error)));

package/adapters/extension/inject.mjs

@@ -102,7 +102,9 @@ copyFile(path.join(runnerDir, 'adapters/extension/build-lavamoat.sh'), path.join
 copyFile(path.join(runnerDir, 'adapters/extension/launch-webpack.cjs'), path.join(harnessDir, 'scripts/launch-webpack.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/sync-webpack-dist.cjs'), path.join(harnessDir, 'scripts/sync-webpack-dist.cjs'));
 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

@@ -6,13 +6,16 @@
 # Purpose:
 #   Builds the per-run prepare command from the named feature scripts
 #   (watch, dist snapshot, fixture seed, detached chrome, CDP poll), then
-#   runs launch.sh and verify.sh under a timestamped artifact dir.
+#   runs launch.sh and, unless --launch-only is set, verify.sh under a
+#   timestamped artifact dir.
 #
 # Inputs (flags / env):
 #   --target <metamask-extension> (default $PWD)
 #   --cdp-port <port> (optional; inferred from checkout context/pool when omitted)
 #   --launch-existing-dist | --start-watch | --build-lavamoat | --prepare-cmd <cmd>
 #       (env RECIPE_HARNESS_EXTENSION_LAUNCH_CMD)
+#   --launch-only (skip recipe verification; used by fixture application while
+#       its checkout lock is held)
 #   --dist-dir <rel> (default dist/chrome), --chrome-user-data-dir <dir>,
 #   --remote-flag <KEY=VARIANT[,KEY=VARIANT...]> (pins manifest _flags into the
 #       ephemeral runtime-dist snapshot before launch; omit for default behavior)
@@ -40,10 +43,14 @@ 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=""
 REMOTE_FLAGS_APPLIED=false
+RUN_VERIFY=true
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --target) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; TARGET="$2"; shift 2 ;;
@@ -52,13 +59,17 @@ 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 ;;
+    --launch-only) RUN_VERIFY=false; shift ;;
     --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>] [--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
@@ -67,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
   ""|/*) ;;
@@ -115,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
@@ -140,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'
@@ -170,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")"
@@ -177,8 +228,10 @@ NODE
   quoted_build_lavamoat="$(printf '%q' "$SCRIPT_DIR/build-lavamoat.sh")"
   quoted_snapshot_dist="$(printf '%q' "$SCRIPT_DIR/snapshot-dist.sh")"
   quoted_configure_manifest="$(printf '%q' "$SCRIPT_DIR/configure-runtime-manifest.cjs")"
+  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")"
@@ -251,16 +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_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}")
-  prepare_parts+=("node ${quoted_configure_manifest} --target ${quoted_target} --manifest ${quoted_runtime_dist}/manifest.json")
-  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.
@@ -295,13 +369,15 @@ 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 '  '
 printf '%q ' "${display_args[@]}"
 printf '\n'
 echo "Launch artifacts: $ARTIFACTS/launch"
-echo "Verify artifacts: $ARTIFACTS/verify"
+$RUN_VERIFY && echo "Verify artifacts: $ARTIFACTS/verify"
 
 launch_args=(--target "$TARGET" --cdp-port "$CDP_PORT" --artifacts-dir "$ARTIFACTS/launch")
 [ -n "$PREPARE_CMD" ] && launch_args+=(--prepare-cmd "$PREPARE_CMD")
@@ -312,18 +388,21 @@ set +e
 launch_status=$?
 set -e
 
-verify_status=1
-if [ "$launch_status" -eq 0 ]; then
+verify_status=0
+if [ "$launch_status" -eq 0 ] && $RUN_VERIFY; then
   echo "[recipe-harness] phase 2/2: live verify (readiness + smoke recipe)" >&2
   set +e
   "$VERIFY_SH" --target "$TARGET" --out "$OUT" --cdp-port "$CDP_PORT" --artifacts-dir "$ARTIFACTS/verify"
   verify_status=$?
   set -e
-else
+elif [ "$launch_status" -ne 0 ]; then
+  verify_status=1
   echo "Skipping Extension live verify because launch failed; see $ARTIFACTS/launch/summary.json" >&2
+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" 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;
@@ -331,6 +410,7 @@ const launchSummary = path.join(artifacts, 'launch', 'summary.json');
 const verifySummary = path.join(artifacts, 'verify', 'summary.json');
 const launchStatus = Number(process.env.LAUNCH_STATUS);
 const verifyStatus = Number(process.env.VERIFY_STATUS);
+const runVerify = process.env.RUN_VERIFY === 'true';
 fs.writeFileSync(path.join(artifacts, 'summary.json'), `${JSON.stringify({
   adapter: 'extension',
   action: 'live',
@@ -340,10 +420,15 @@ 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: { exitCode: verifyStatus, summaryPath: fs.existsSync(verifySummary) ? verifySummary : null },
+  verify: runVerify
+    ? { status: verifyStatus === 0 ? 'pass' : 'fail', exitCode: verifyStatus, summaryPath: fs.existsSync(verifySummary) ? verifySummary : null }
+    : { status: 'skipped', exitCode: null, summaryPath: null },
   easyCommand: `mm-harness launch --verify --target <repo>`,
-  note: 'Runs launch then live verify so a developer can validate browser startup, CDP readiness, recipe bridge, screenshots/fallback classification, and sample recipes from one runner-owned command.',
+  note: runVerify
+    ? 'Runs launch then live verify so a developer can validate browser startup, CDP readiness, recipe bridge, screenshots/fallback classification, and sample recipes from one runner-owned command.'
+    : 'Runs launch validation only for fixture application while the checkout lock is held.',
   generatedAt: new Date().toISOString(),
 }, null, 2)}\n`);
 NODE