@deeeed/metamask-harness 0.59.0 → 0.60.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.60.0 - 2026-09-19
+
+### Changed
+
+- Site: a Features page (`features.html`) catalogues every harness capability with its command or action and the clients it runs on, linked from the lobby and every page's nav. A feature PR adds or updates its row next to its changelog bullet.
+
+### Added
+
+- Remote feature flags are a first-class capability with the same signature on both clients. `mm-harness launch --remote-flag KEY=VALUE[,KEY=VALUE]` pins a flag for the launch and `prepare` forwards it. Mobile applies it through the running `RemoteFeatureFlagController` and fails the launch when a key does not read back; the Extension writes it into the per-run dist snapshot manifest and then re-reads that manifest, so the launch reports the pin it proved rather than the one it requested. The wallet fixture takes an optional `remoteFeatureFlags` object: every launch on both clients makes the override set exactly that baseline merged with the `--remote-flag` map, so a plain launch keeps the fixture's variant and drops the previous run's (Mobile clears the controller's persisted overrides first; the Extension re-creates the snapshot unless its harness-owned record, `_harness.remoteFeatureFlags`, already equals the request, which keeps the build's own `.manifest-flags.json` flags from ever reading as a stale pin). `fixtures set` applies the block the same way and takes `--remote-flag` for a one-run override, so `prepare --remote-flag` keeps its pin through the fixtures step. The record is written on every snapshot (an empty map on a plain launch), a snapshot without it is re-created rather than trusted, and a reload in place (`reattach`, the watcher's sync, a recipe's runtime recovery) carries it across the rebuilt snapshot. `--watch` refuses `--remote-flag` because the watcher never re-creates the snapshot; a verified release artifact refuses any pin rather than testing the wrong arm; a Mobile launch that could not prove its override set reports `remoteFeatureFlags: null`. Three actions on every adapter: `metamask.feature_flags.set`, `.read`, and `.clear`. The Extension exposes no runtime override RPC (`setFlagOverride` is never registered in `metamask-controller.js` `getApi()`), so its `set` reports the relaunch that does pin the flag and exits non-zero rather than claiming a change it cannot make; core answers `supported: false`. `doctor` and `status` print a `feature flags:` line and carry the object in `--json`, distinguishing no runtime and an unreadable snapshot from a genuine zero. Mobile reads it on the live probe that already runs, so neither command spawns a second bridge evaluation. Value grammar is parsed in exactly one place (`src/feature-flags.ts`) and every leaf receives the resolved map as JSON: a bare word is a named A/B variant, `true`/`false` is a boolean, and a value opening with `{` or `[` is JSON.
+
 ## 0.59.0 - 2026-09-18
 
 ### Changed

package/README.md

@@ -98,6 +98,54 @@ Extension `launch` keeps its incremental watcher running. Refresh the active
 page after a successful rebuild; use `launch --build` only for an explicit
 production-like LavaMoat rebuild.
 
+### Remote feature flags
+
+`--remote-flag KEY=VALUE[,KEY=VALUE]` pins a remote feature flag for the launch,
+which is how a screen gated behind an A/B variant becomes reachable:
+
+```bash
+mm-harness launch --remote-flag perpsTAT3938AbtestScreenVsBottomSheet=treatment
+mm-harness launch ios --remote-flag perpsEnabled=true,perpsConfig='{"tier":2}'
+```
+
+A bare word is a named variant (`treatment` becomes `{ "name": "treatment" }`),
+`true`/`false` is a boolean, and a value opening with `{` or `[` is parsed as
+JSON. The grammar is parsed once and every leaf receives the resolved map, so a
+boolean stays a boolean rather than becoming the string `"true"`.
+
+Every launch makes the app's override set exactly the wallet fixture's
+`remoteFeatureFlags` object (the baseline every run shares) merged with the
+`--remote-flag` map (a one-launch override), on both clients. A plain `launch`
+therefore drops a previous run's `--remote-flag` variant and keeps the fixture's.
+Mobile clears and re-applies the set through the running
+`RemoteFeatureFlagController` and fails the launch if it does not read back. The
+Extension writes it into the per-run dist snapshot manifest and re-reads the
+harness-owned record there (`_harness.remoteFeatureFlags`, written on every
+snapshot), so the launch reports the pin it proved; reuse of a running browser
+is allowed only while that record already equals the request, a reload in
+place carries the record across the rebuilt snapshot, and `--watch` (which
+never re-creates the snapshot) refuses `--remote-flag`. A recipe's own recovery
+relaunch carries the live pin rather than dropping it mid-run. A verified
+release artifact is never rewritten, so a launch that would have to pin it
+(`--remote-flag` or a fixture that declares flags) refuses instead of testing
+the wrong arm.
+
+Read or change flags on a running app with the actions. `fixtures set` follows
+the same rule as launch: the fixture's block is the baseline and
+`fixtures set --remote-flag KEY=VALUE` layers a one-run override on it, which is
+how `prepare --remote-flag` keeps its pin through the fixtures step.
+
+```bash
+mm-harness call metamask.feature_flags.read
+mm-harness call metamask.feature_flags.set --arg 'flags={"perpsEnabled":true}'   # mobile
+mm-harness call metamask.feature_flags.clear                                      # mobile
+```
+
+`doctor` and `status` print a `feature flags:` line naming every active
+override, so a slot never runs a proof under an unnamed variant. The line
+distinguishes `(no runtime)` and an unreadable snapshot from a genuine
+`0 override(s)`.
+
 Log sources stay separate:
 
 ```bash

package/adapters/extension/build-handoff.cjs

@@ -7,6 +7,7 @@ const { spawnSync } = require('node:child_process');
 const { connectBrowserViaCdp, evaluatePageViaCdp } = require('./lib/playwright-cdp.cjs');
 const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = require('./lib/chrome-args.cjs');
 const { stampRuntimeTitles } = require('./stamp-runtime-title.cjs');
+const { carryHarnessPin } = require('./pin-remote-flags.cjs');
 
 function acquireBuildHandoff(runtimeDir) {
   const lock = path.join(runtimeDir, 'extension-build-handoff.lock');
@@ -142,6 +143,9 @@ async function handoffRuntimeBuild({ target, runtimeDist, dist, cdpPort }) {
       const configured = spawnSync(process.execPath, [path.join(__dirname, 'configure-runtime-manifest.cjs'), '--target', target, '--manifest', path.join(runtimeDist, 'manifest.json')], { encoding: 'utf8' });
       if (configured.status !== 0) throw new Error(`Extension runtime configuration failed: ${configured.stderr || configured.stdout}`);
       stampRuntimeTitles({ target, runtimeDist });
+      // The rsync replaced the manifest with the build's own; the pin the
+      // running slot was launched under must survive a reload in place.
+      carryHarnessPin(oldManifest, path.join(runtimeDist, 'manifest.json'));
     }
     await setEnabled(true);
     for (const entry of pages) {

package/adapters/extension/live.sh

@@ -17,7 +17,7 @@
 #   --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
+#   --remote-flags-json <json-object> (pins manifest _flags into the
 #       ephemeral runtime-dist snapshot before launch; omit for default behavior)
 #   --out <recipes-dir>, --artifacts-dir <dir>
 #   env RECIPE_HARNESS_CHROME_BIN (validated executable; else Playwright
@@ -69,8 +69,8 @@ while [ "$#" -gt 0 ]; do
     --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|--external-artifact --dist-dir <absolute-dir> --artifact-provenance <absolute-file>|--prepare-cmd <cmd>] [--preserve-profile|--reset-profile] [--launch-only] [--dist-dir dist/chrome] [--remote-flag KEY=VARIANT] [--artifacts-dir <dir>]"; exit 0 ;;
+    --remote-flags-json) [ "$#" -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|--external-artifact --dist-dir <absolute-dir> --artifact-provenance <absolute-file>|--prepare-cmd <cmd>] [--preserve-profile|--reset-profile] [--launch-only] [--dist-dir dist/chrome] [--remote-flags-json '<normalised-json-map>'] [--artifacts-dir <dir>]"; exit 0 ;;
     *) echo "Unknown arg: $1" >&2; exit 2 ;;
   esac
 done
@@ -327,14 +327,18 @@ NODE
   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.
-  if [ -n "$REMOTE_FLAGS" ]; then
+  # Remote feature-flag pinning: patch the ephemeral snapshot manifest so
+  # manifest._flags wins over the fetched ClientConfigApi value, and record the
+  # harness-owned pin on EVERY snapshot (an empty map without --remote-flags-json)
+  # so launch can tell a snapshot it wrote from one it never did. The snapshot is
+  # re-created each run, so no revert.
+  if ! $EXTERNAL_ARTIFACT; then
     quoted_pin_flags="$(printf '%q' "$SCRIPT_DIR/pin-remote-flags.cjs")"
-    quoted_remote_flags="$(printf '%q' "$REMOTE_FLAGS")"
+    # The empty default is spelled literally: printf %q renders {} differently
+    # across bash versions, and the sequencer golden must not depend on that.
+    if [ -n "$REMOTE_FLAGS" ]; then quoted_remote_flags="$(printf '%q' "$REMOTE_FLAGS")"; else quoted_remote_flags="'{}'"; fi
     quoted_runtime_manifest="$(printf '%q' "$RUNTIME_DIST_ABS/manifest.json")"
-    prepare_parts+=("node ${quoted_pin_flags} ${quoted_runtime_manifest} ${quoted_remote_flags}")
+    prepare_parts+=("node ${quoted_pin_flags} ${quoted_runtime_manifest} --flags-json ${quoted_remote_flags}")
     REMOTE_FLAGS_APPLIED=true
   fi
   if [ -n "$WALLET_FIXTURE_ABS" ]; then
@@ -354,7 +358,7 @@ NODE
 fi
 
 if [ -n "$REMOTE_FLAGS" ] && [ "$REMOTE_FLAGS_APPLIED" != "true" ]; then
-  echo "[recipe-harness] WARN: --remote-flag '$REMOTE_FLAGS' had no effect: flag pinning only applies to the snapshot launch path (--launch-existing-dist/--start-watch/--build-lavamoat without a custom --prepare-cmd)." >&2
+  echo "[recipe-harness] WARN: --remote-flags-json '$REMOTE_FLAGS' had no effect: flag pinning only applies to the snapshot launch path (--launch-existing-dist/--start-watch/--build-lavamoat without a custom --prepare-cmd)." >&2
 fi
 
 echo "Extension live validation command:"
@@ -364,7 +368,7 @@ $BUILD_LAVAMOAT && display_args+=(--build-lavamoat)
 $EXTERNAL_ARTIFACT && display_args+=(--external-artifact --dist-dir "$DIST_DIR" --artifact-provenance "$ARTIFACT_PROVENANCE")
 $RESET_PROFILE && display_args+=(--reset-profile)
 $RESET_PROFILE || display_args+=(--preserve-profile)
-[ -n "$REMOTE_FLAGS" ] && display_args+=(--remote-flag "$REMOTE_FLAGS")
+[ -n "$REMOTE_FLAGS" ] && display_args+=(--remote-flags-json "$REMOTE_FLAGS")
 [ -n "$CHROME_USER_DATA_DIR" ] && display_args+=(--chrome-user-data-dir "$CHROME_USER_DATA_DIR")
 printf '  '
 printf '%q ' "${display_args[@]}"

package/adapters/extension/pin-remote-flags.cjs

@@ -1,45 +1,84 @@
 #!/usr/bin/env node
-// pin-remote-flags.cjs <manifest.json> <KEY=VARIANT[,KEY=VARIANT...]>
+// pin-remote-flags.cjs <manifest.json> --flags-json '<normalised-map>'
 //
-// Pins A/B remote feature-flag variants into an extension manifest's
-// `_flags.remoteFeatureFlags`. MetaMask resolves the active flags as
+// Writes an already-normalised remote feature-flag map into an extension
+// manifest's `_flags.remoteFeatureFlags`. MetaMask resolves the active flags as
 //   getRemoteFeatureFlags = merge({}, fetchedState, manifest._flags.remoteFeatureFlags)
-// with the manifest winning, so this deterministically forces a variant in the
-// live browser regardless of the real ClientConfigApi response — which otherwise
-// overwrites any seeded controller state on refetch.
+// with the manifest winning, so this deterministically forces the requested
+// values in the live browser regardless of the real ClientConfigApi response —
+// which otherwise overwrites any seeded controller state on refetch.
+//
+// This leaf does NOT parse the KEY=VALUE grammar. Value normalisation lives in
+// exactly one place, src/feature-flags.ts, and every caller hands the result
+// here as JSON. A second parser here silently disagreed with it: a spec of
+// `flagA=true,flagB={"enabled":true}` used to pin the STRINGS
+// {"flagA":{"name":"true"},"flagB":{"name":"{\"enabled\":true}"}}.
+//
+// The extension build can author `_flags.remoteFeatureFlags` itself (from
+// .manifest-flags.json), so the pin merges over that map and ALSO records
+// exactly what the harness pinned under `_harness.remoteFeatureFlags` — on
+// every snapshot, an empty map included. Launch, fixtures, status and reuse
+// compare against that record, so a build's own flags are reported as live
+// state and never mistaken for a stale pin, a previous run's pin can never
+// hide behind them, and a snapshot without the record is one this harness
+// never wrote (pre-upgrade or foreign) and is re-created rather than trusted.
 //
 // Intended for the per-run runtime-dist SNAPSHOT (ephemeral, re-created from
 // dist/chrome on every launch), so it never mutates the real dist/chrome build
-// and needs no revert bookkeeping. Values are written as { name: VARIANT }
-// (named-variant A/B flags); boolean/other flag shapes are out of scope.
+// and needs no revert bookkeeping. Every path that rsyncs dist over the
+// snapshot again (build-handoff.cjs: reattach, the watcher's sync monitor)
+// carries the record across with carryHarnessPin().
 'use strict';
 
 const fs = require('node:fs');
 
-const [, , manifestPath, spec] = process.argv;
-if (!manifestPath || !spec) {
-  throw new Error('usage: pin-remote-flags.cjs <manifest.json> <KEY=VARIANT[,KEY=VARIANT...]>');
+function assertFlagMap(flags, where) {
+  if (!flags || typeof flags !== 'object' || Array.isArray(flags)) {
+    throw new Error(`${where} must be a JSON object of flag key to already-normalised value.`);
+  }
 }
 
-const pairs = spec
-  .split(',')
-  .map((entry) => entry.trim())
-  .filter(Boolean);
-if (pairs.length === 0) throw new Error(`--remote-flag had no KEY=VARIANT pairs: ${spec}`);
-
-const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-manifest._flags = manifest._flags || {};
-const flags = manifest._flags.remoteFeatureFlags || (manifest._flags.remoteFeatureFlags = {});
+/** Merge `flags` into the manifest's effective map and record it as the harness pin. */
+function pinRemoteFlags(manifestPath, flags) {
+  assertFlagMap(flags, 'flags');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const keys = Object.keys(flags);
+  if (keys.length > 0) {
+    manifest._flags = manifest._flags || {};
+    const effective = manifest._flags.remoteFeatureFlags || (manifest._flags.remoteFeatureFlags = {});
+    for (const key of keys) effective[key] = flags[key];
+  }
+  manifest._harness = { ...(manifest._harness || {}), remoteFeatureFlags: flags };
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return keys;
+}
 
-const applied = [];
-for (const pair of pairs) {
-  const eq = pair.indexOf('=');
-  const key = eq > 0 ? pair.slice(0, eq) : '';
-  const variant = eq > 0 ? pair.slice(eq + 1) : '';
-  if (!key || !variant) throw new Error(`--remote-flag expects KEY=VARIANT, got: ${pair}`);
-  flags[key] = { name: variant };
-  applied.push(`${key}=${variant}`);
+/**
+ * Re-apply the pin a previous snapshot manifest recorded to a freshly synced
+ * one. A manifest without the record contributes an empty pin: the fresh
+ * snapshot then carries `_harness` so the next launch can trust it.
+ */
+function carryHarnessPin(previousManifest, manifestPath) {
+  const pinned = previousManifest && previousManifest._harness && previousManifest._harness.remoteFeatureFlags;
+  return pinRemoteFlags(manifestPath, pinned && typeof pinned === 'object' && !Array.isArray(pinned) ? pinned : {});
 }
 
-fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
-console.log(`[flags] Pinned ${applied.join(', ')} into ${manifestPath}`);
+module.exports = { pinRemoteFlags, carryHarnessPin };
+
+if (require.main === module) {
+  const [, , manifestPath, flagOption, flagsJson] = process.argv;
+  if (!manifestPath || flagOption !== '--flags-json' || !flagsJson) {
+    throw new Error("usage: pin-remote-flags.cjs <manifest.json> --flags-json '<json-object>'");
+  }
+  let flags;
+  try {
+    flags = JSON.parse(flagsJson);
+  } catch (error) {
+    throw new Error(`--flags-json is not valid JSON: ${error.message}`);
+  }
+  assertFlagMap(flags, '--flags-json');
+  const keys = pinRemoteFlags(manifestPath, flags);
+  console.log(keys.length > 0
+    ? `[flags] Pinned ${keys.join(', ')} into ${manifestPath}`
+    : `[flags] Recorded an empty remote feature-flag pin in ${manifestPath}`);
+}

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -431,11 +431,27 @@ const COMMANDS = {
       var keyringUnlocked = false;
       try { account = globalThis.__AGENTIC__?.getSelectedAccount() || null; } catch(e) {}
       try { keyringUnlocked = globalThis.Engine?.context?.KeyringController?.isUnlocked?.() === true; } catch(e) {}
+      // Remote feature-flag overrides ride along on this one evaluation: status
+      // and doctor must not spawn a second bridge probe to name the variant a
+      // slot is pinned to. null means the controller did not answer, which is
+      // not the same as "no overrides".
+      var featureFlags = null;
+      try {
+        var flagController = globalThis.Engine?.context?.RemoteFeatureFlagController;
+        var flagState = flagController && flagController.state;
+        if (flagState) {
+          featureFlags = {
+            effective: flagState.remoteFeatureFlags || {},
+            overrides: flagState.localOverrides || {},
+          };
+        }
+      } catch(e) {}
       return {
         route: route,
         account: account,
         agenticPresent: agenticPresent,
         keyringUnlocked: keyringUnlocked,
+        featureFlags: featureFlags,
       };
     })()`;
     const snapshot = await cdpEval(client, expr);

package/adapters/mobile/bridge-runtime/setup-wallet.sh

@@ -47,6 +47,7 @@ export CDP_DISCOVERY_RETRIES="${CDP_DISCOVERY_RETRIES:-3}"
 WALLET_SETUP_SETTLE_TIMEOUT="${WALLET_SETUP_SETTLE_TIMEOUT:-180}"
 CDP="node $SCRIPTS/cdp-bridge.cjs"
 FIXTURE_PATH=""
+REMOTE_FEATURE_FLAGS=""
 
 cdp_json_command() {
   local mode="$1"
@@ -70,7 +71,10 @@ while [[ $# -gt 0 ]]; do
     --fixture)
       [ $# -ge 2 ] || { echo "ERROR: --fixture requires a path argument"; exit 2; }
       FIXTURE_PATH="$2"; shift 2 ;;
-    -h|--help) echo "Usage: setup-wallet.sh [--fixture path.json]"; exit 0 ;;
+    --remote-flags-json)
+      [ $# -ge 2 ] || { echo "ERROR: --remote-flags-json requires a JSON argument"; exit 2; }
+      REMOTE_FEATURE_FLAGS="$2"; shift 2 ;;
+    -h|--help) echo "Usage: setup-wallet.sh [--fixture path.json] [--remote-flags-json '<normalised-json-map>']"; exit 0 ;;
     *)         echo "Unknown arg: $1"; exit 2 ;;
   esac
 done
@@ -167,7 +171,17 @@ echo "Vault backup guard intent: $DISABLE_BACKUP"
 wait_for_engine
 
 # Read fixture JSON and escape it for safe embedding in a JS string literal.
-FIXTURE_JSON=$(jq -c '.' "$FIXTURE_PATH")
+# remoteFeatureFlags is a harness field: __AGENTIC__.setupWallet/applyWalletFixture
+# know nothing about it, so strip it here and apply it separately below against
+# RemoteFeatureFlagController once the wallet is up.
+#
+# The VALUES come from --remote-flags-json, already normalised by
+# src/feature-flags.ts. This script must not read them from the fixture itself:
+# a second reader here disagreed with that grammar (a bare "treatment" stayed a
+# string instead of becoming { "name": "treatment" }).
+[ -n "$REMOTE_FEATURE_FLAGS" ] || REMOTE_FEATURE_FLAGS="{}"
+echo "$REMOTE_FEATURE_FLAGS" | jq empty 2>/dev/null || { echo "ERROR: --remote-flags-json is not valid JSON"; exit 2; }
+FIXTURE_JSON=$(jq -c 'del(.remoteFeatureFlags)' "$FIXTURE_PATH")
 ESCAPED_FIXTURE=$(node -p "JSON.stringify(JSON.stringify(JSON.parse(process.argv[1])))" "$FIXTURE_JSON")
 EXPECTED_ADDRESSES=$(node - "$FIXTURE_PATH" <<'NODE'
 const fs = require('fs');
@@ -440,6 +454,59 @@ case "$ROUTE_NAME" in
     exit 1
     ;;
 esac
+# -- Apply the fixture's remote feature-flag overrides --
+# setFlagOverride writes localOverrides and recomputes remoteFeatureFlags, so the
+# override persists and wins over every later ClientConfigApi refetch. Applied on
+# every `fixtures set`, like the rest of the fixture.
+if [ "$REMOTE_FEATURE_FLAGS" = "{}" ]; then
+  # The fixture is authoritative: a fixture that declares no flags leaves the
+  # slot with no overrides, so one run's variant never leaks into the next.
+  CLEAR_RESULT=$(cdp_eval "(function(){ try { var ctx = globalThis.Engine && globalThis.Engine.context; var c = ctx && ctx.RemoteFeatureFlagController; if (!c || typeof c.clearAllFlagOverrides !== 'function') { return JSON.stringify({ok:true, proven:false, skipped:'controller-unavailable'}); } var before = Object.keys((c.state || {}).localOverrides || {}); c.clearAllFlagOverrides(); return JSON.stringify({ok:true, proven:true, cleared: before}); } catch (e) { return JSON.stringify({ok:false, error: e && (e.message || String(e))}); } })()")
+  if [ "$(echo "$CLEAR_RESULT" | jq -r '.ok // false')" != "true" ]; then
+    echo "ERROR: could not clear remote feature-flag overrides — $(echo "$CLEAR_RESULT" | jq -r '.error // "unknown error"')"
+    exit 1
+  fi
+  if [ "$(echo "$CLEAR_RESULT" | jq -r '.proven // false')" != "true" ]; then
+    # Not an error: an app without the controller has no overrides to carry. It
+    # is not proof of a clean slot either, so say which it is.
+    echo "WARN: remote feature-flag overrides were not cleared — $(echo "$CLEAR_RESULT" | jq -r '.skipped // "unknown reason"'); the app exposes no RemoteFeatureFlagController to prove the slot is clean."
+  else
+    CLEARED=$(echo "$CLEAR_RESULT" | jq -r '.cleared // [] | join(", ")')
+    [ -n "$CLEARED" ] && echo "Cleared remote feature-flag override(s): $CLEARED"
+  fi
+else
+  ESCAPED_FLAGS=$(node -p "JSON.stringify(JSON.stringify(JSON.parse(process.argv[1])))" "$REMOTE_FEATURE_FLAGS")
+  echo "Applying remote feature-flag overrides: $REMOTE_FEATURE_FLAGS"
+  # Clear first: the controller persists overrides, so the set must become
+  # exactly the fixture's map, never the fixture's plus a previous run's.
+  FLAG_RESULT=$(cdp_eval "(function(){ try { var ctx = globalThis.Engine && globalThis.Engine.context; var c = ctx && ctx.RemoteFeatureFlagController; if (!c || typeof c.setFlagOverride !== 'function') { return JSON.stringify({ok:false, error:'RemoteFeatureFlagController.setFlagOverride is unavailable on the running app'}); } if (typeof c.clearAllFlagOverrides === 'function') c.clearAllFlagOverrides(); var requested = JSON.parse($ESCAPED_FLAGS); var applied = []; for (var k in requested) { if (Object.prototype.hasOwnProperty.call(requested, k)) { c.setFlagOverride(k, requested[k]); applied.push(k); } } var st = c.state || {}; return JSON.stringify({ok:true, applied: applied, effective: st.remoteFeatureFlags || {}, overrides: st.localOverrides || {}}); } catch (e) { return JSON.stringify({ok:false, error: e && (e.message || String(e))}); } })()")
+  FLAG_OK=$(echo "$FLAG_RESULT" | jq -r '.ok // false')
+  if [ "$FLAG_OK" != "true" ]; then
+    echo "ERROR: remote feature-flag overrides were not applied — $(echo "$FLAG_RESULT" | jq -r '.error // "unknown error"')"
+    exit 1
+  fi
+  # Read back: a flag nobody can observe is not applied.
+  FLAG_MISMATCH=$(node - "$REMOTE_FEATURE_FLAGS" "$FLAG_RESULT" <<'NODE'
+const requested = JSON.parse(process.argv[2]);
+const result = JSON.parse(process.argv[3]);
+const effective = result.effective || {};
+const overrides = result.overrides || {};
+// A requested key that did not read back, or an override that survived the clear.
+const mismatched = [
+  ...Object.keys(requested).filter((key) => JSON.stringify(effective[key]) !== JSON.stringify(requested[key])),
+  ...Object.keys(overrides).filter((key) => !(key in requested)),
+];
+process.stdout.write(mismatched.join(', '));
+NODE
+)
+  if [ -n "$FLAG_MISMATCH" ]; then
+    echo "ERROR: remote feature-flag override(s) did not read back: $FLAG_MISMATCH"
+    echo "$FLAG_RESULT" | jq .
+    exit 1
+  fi
+  echo "Remote feature flags applied: $(echo "$FLAG_RESULT" | jq -r '.applied | join(", ")')"
+fi
+
 echo ""
 echo "=== Wallet Ready ==="
 echo "Route: ${ROUTE_NAME:-unknown}"

package/dist/adapters/extension/feature-flags.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { normalizeFeatureFlagRecord } from "../../feature-flags.js";
+import { recipeRuntimeDir } from "../../paths.js";
+import { releaseArtifactState } from "./runtime-decision.js";
+function extensionRuntimeManifestPath(target) {
+  return path.join(
+    target,
+    recipeRuntimeDir(),
+    process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist",
+    "manifest.json"
+  );
+}
+function readExtensionPinnedFlags(target) {
+  const manifestPath = extensionRuntimeManifestPath(target);
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, "utf8");
+  } catch {
+    return { overrides: null, pinned: null };
+  }
+  try {
+    const manifest = JSON.parse(raw);
+    return {
+      overrides: normalizeFeatureFlagRecord(manifest._flags?.remoteFeatureFlags, manifestPath),
+      pinned: manifest._harness?.remoteFeatureFlags !== void 0 ? normalizeFeatureFlagRecord(manifest._harness.remoteFeatureFlags, manifestPath) : releaseArtifactState(target).status === "valid" ? {} : null,
+      sourcePath: manifestPath
+    };
+  } catch (error) {
+    return {
+      overrides: null,
+      pinned: null,
+      error: error instanceof Error ? error.message : String(error),
+      sourcePath: manifestPath
+    };
+  }
+}
+export {
+  extensionRuntimeManifestPath,
+  readExtensionPinnedFlags
+};

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

@@ -313,6 +313,7 @@ function normalizedRuntimeManifest(file) {
       delete manifest._flags.remoteFeatureFlags;
       if (Object.keys(manifest._flags).length === 0) delete manifest._flags;
     }
+    delete manifest._harness;
     return JSON.stringify(manifest);
   } catch {
     return null;

package/dist/adapters/mobile/feature-flags.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { runnerDir } from "../../paths.js";
+const DEFAULT_TIMEOUT_MS = 1e4;
+function bridgeScriptPath() {
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT ?? path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+}
+const CONTROLLER_PREAMBLE = `
+  var ctx = globalThis.Engine && globalThis.Engine.context;
+  var c = ctx && ctx.RemoteFeatureFlagController;
+  if (!c) return JSON.stringify({ ok: false, error: 'Engine.context.RemoteFeatureFlagController is not available on the running app.' });
+  var snap = function () {
+    var st = c.state || {};
+    return { effective: st.remoteFeatureFlags || {}, overrides: st.localOverrides || {} };
+  };
+`;
+function evalExpression(body) {
+  return `(function(){ try {${CONTROLLER_PREAMBLE}${body} } catch (e) { return JSON.stringify({ ok: false, error: e && (e.message || String(e)) }); } })()`;
+}
+function runBridgeEval(target, expression, timeoutMs) {
+  const script = bridgeScriptPath();
+  if (!fs.existsSync(script)) return Promise.resolve(null);
+  return new Promise((resolve) => {
+    let settled = false;
+    let stdout = "";
+    const child = spawn(process.execPath, [script, "eval", expression], {
+      cwd: target,
+      env: { ...process.env, APP_ROOT: target, CDP_TIMEOUT: String(timeoutMs) },
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      const killTimer = setTimeout(() => child.kill("SIGKILL"), 500);
+      child.once("close", () => clearTimeout(killTimer));
+      finish(null);
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.on("close", (code) => {
+      if (code !== 0) return finish(null);
+      const trimmed = stdout.trim();
+      if (!trimmed) return finish(null);
+      try {
+        const first = JSON.parse(trimmed);
+        const parsed = typeof first === "string" ? JSON.parse(first) : first;
+        return finish(parsed);
+      } catch {
+        return finish(null);
+      }
+    });
+    child.on("error", () => finish(null));
+  });
+}
+async function readMobileFeatureFlags(target, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const result = await runBridgeEval(
+    target,
+    evalExpression("var s = snap(); return JSON.stringify({ ok: true, effective: s.effective, overrides: s.overrides });"),
+    timeoutMs
+  );
+  if (!result || result.ok !== true) return null;
+  return { effective: result.effective ?? {}, overrides: result.overrides ?? {} };
+}
+async function pinMobileFeatureFlags(target, flags, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const payload = JSON.stringify(JSON.stringify(flags));
+  const result = await runBridgeEval(
+    target,
+    evalExpression(`
+      if (typeof c.setFlagOverride !== 'function') {
+        return JSON.stringify({ ok: false, error: 'RemoteFeatureFlagController.setFlagOverride is unavailable in this build.' });
+      }
+      var requested = JSON.parse(${payload});
+      if (typeof c.clearAllFlagOverrides === 'function') c.clearAllFlagOverrides();
+      var applied = [];
+      for (var k in requested) {
+        if (Object.prototype.hasOwnProperty.call(requested, k)) { c.setFlagOverride(k, requested[k]); applied.push(k); }
+      }
+      var s = snap();
+      return JSON.stringify({ ok: true, applied: applied, effective: s.effective, overrides: s.overrides });
+    `),
+    timeoutMs
+  );
+  if (!result) {
+    return {
+      ok: false,
+      error: "the mobile bridge did not answer, so no remote feature flag was applied.",
+      applied: [],
+      effective: {},
+      overrides: {},
+      mismatched: Object.keys(flags)
+    };
+  }
+  if (result.ok !== true) {
+    return {
+      ok: false,
+      error: result.error ?? "the mobile runtime refused the remote feature-flag override.",
+      applied: [],
+      effective: {},
+      overrides: {},
+      mismatched: Object.keys(flags)
+    };
+  }
+  const effective = result.effective ?? {};
+  const overrides = result.overrides ?? {};
+  const mismatched = [
+    ...Object.keys(flags).filter((key) => JSON.stringify(effective[key]) !== JSON.stringify(flags[key])),
+    ...Object.keys(overrides).filter((key) => !(key in flags))
+  ];
+  return {
+    ok: mismatched.length === 0,
+    applied: result.applied ?? [],
+    effective,
+    overrides,
+    mismatched
+  };
+}
+export {
+  pinMobileFeatureFlags,
+  readMobileFeatureFlags
+};

package/dist/adapters.js

@@ -105,6 +105,11 @@ const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.list_accounts",
   "metamask.wallet.read_state"
 ]);
+const LIVE_ONLY_FEATURE_FLAG_ACTIONS = /* @__PURE__ */ new Set([
+  "metamask.feature_flags.set",
+  "metamask.feature_flags.read",
+  "metamask.feature_flags.clear"
+]);
 const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set([
   "ui.navigate",
   "app.network_capture",
@@ -113,7 +118,7 @@ const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set([
   "app.performance_assert"
 ]);
 function requiresLiveAdapter(platform, action) {
-  return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
+  return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_FEATURE_FLAG_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
 }
 function liveRuntimeConfigured(platform, node) {
   if (platform === "mobile" || platform === "core") return true;

package/dist/command-contract.js

@@ -154,7 +154,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--platform": value(["mobile", "extension", "core"]),
       "--mobile-platform": value(["ios", "android"]),
       "--clear-metro": bool(),
-      "--artifacts-dir": value()
+      "--artifacts-dir": value(),
+      "--remote-flag": value()
     })
   },
   task: {
@@ -329,7 +330,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--sidepanel": bool(),
       "--fullscreen": bool(),
       "--url": value(),
-      "--heal": value(["off", "infra-only", "auto"])
+      "--heal": value(["off", "infra-only", "auto"]),
+      "--remote-flag": value()
     }),
     positionals: [{ label: "platform", choices: ["ios", "android"] }]
   },
@@ -383,7 +385,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--cdp-port": value(),
       "--extension-dir": value(),
       "--extension-id-file": value(),
-      "--action-manifest": value()
+      "--action-manifest": value(),
+      "--remote-flag": value()
     }),
     positionals: [{ label: "action", choices: ["init", "sync", "set", "reset", "generate", "finalize"] }],
     minimumPositionals: 0