@deeeed/metamask-harness 0.58.0 → 0.60.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## 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
+
+- Extension `verify` is runner-owned TypeScript: `adapters/extension/verify.sh` (572 lines, with node heredocs assembling `summary.json`, the fixture status and the CDP holder probe) is now `src/adapters/extension/verify.ts`, run in-process by `mm-harness verify --adapter extension`. Same flags, env, exit codes, check names and artifacts (`summary.json`, `artifact-manifest.json`, `logs/`, `runner-smoke/`); a live run against the same checkout produced a byte-identical normalised summary. Deliberate differences: `install` no longer copies a `scripts/verify.sh` into the checkout and dispatch no longer prefers one, so an older overlay cannot shadow the current runner's verify; the two shell-lib preflights (`harness-path.sh`, `json-field.sh`) are gone because the typed helpers cannot be missing; usage now names `mm-harness verify --adapter extension`; a `--target` that does not exist is a named exit-1 refusal instead of a bare `cd` failure; and `live.sh` reaches verify through the checkout's runner delegate, refusing early when that delegate is absent. Three more deliberate differences: `--artifacts-dir` is resolved to an absolute path once (the shell resolved a relative value against the cwd for its own files and against the target for the smoke run); `readiness.mjs` runs under the harness's own node instead of `PATH` `node`; and `live.sh`, having just installed the overlay, tells verify to skip the overlay re-ensure (`MM_HARNESS_SKIP_OVERLAY_ENSURE=1`) instead of reinstalling it between launch and the live probe.
+
+### Fixed
+
+- Slot identity resolves against this machine's pool first. Every farm node keeps the same checkout paths, so a repo path matched a slot in every `pool/*.json` and the alphabetically first pool won: `doctor --fix` on macwork stamped `metamask-extension-2` as `macpro-mme-2` on CDP 7662 instead of `macwork-mmedev-2` on 6662. Pools whose `machine` or `host` is this host are consulted first; other machines' pools only when none of ours names the repo. A malformed pool file is skipped like the port resolver already did, and `*.bak` files never count.
+- An invalid `RECIPE_RUNTIME_DIR` no longer crashes every command at startup with a stack trace. The extension runtime decision read it while loading; it reads it when a build-log check needs it, so `--help` still works and the command that needs the value reports it.
+
 ## 0.58.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/inject.mjs

@@ -114,7 +114,6 @@ copyFile(path.join(runnerDir, 'adapters/extension/sidepanel-toggle.sh'), path.jo
 copyFile(path.join(runnerDir, 'adapters/extension/reattach.sh'), path.join(harnessDir, 'scripts/reattach.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/readiness.mjs'), path.join(harnessDir, 'scripts/readiness.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/wallet-fixture-state.cjs'), path.join(harnessDir, 'scripts/wallet-fixture-state.cjs'));
-copyFile(path.join(runnerDir, 'adapters/extension/verify.sh'), path.join(harnessDir, 'scripts/verify.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/refresh-build.sh'), path.join(harnessDir, 'scripts/refresh-build.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/ensure-browser.sh'), path.join(harnessDir, 'scripts/reopen-browser.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/harness-path.sh'), path.join(harnessDir, 'scripts/lib/harness-path.sh'));

package/adapters/extension/live.sh

@@ -6,8 +6,8 @@
 # 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, unless --launch-only is set, verify.sh under a
-#   timestamped artifact dir.
+#   runs launch.sh and, unless --launch-only is set, `mm-harness verify` under
+#   a timestamped artifact dir.
 #
 # Inputs (flags / env):
 #   --target <metamask-extension> (default $PWD)
@@ -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
@@ -128,17 +128,6 @@ case "$CDP_PORT" in
   *[!0-9]*) echo "Invalid --cdp-port (must be numeric): $CDP_PORT" >&2; exit 2 ;;
 esac
 
-# verify.sh is a recipe-tree feature: co-located in installed copies, under
-# adapters/extension in a repo checkout.
-VERIFY_SH=""
-for _v in "$SCRIPT_DIR/verify.sh" "$SCRIPT_DIR/../../adapters/extension/verify.sh"; do
-  [ -f "$_v" ] && { VERIFY_SH="$_v"; break; }
-done
-unset _v
-if [ -z "$VERIFY_SH" ]; then
-  echo "mm-harness: extension verify.sh not found next to $SCRIPT_DIR; reinstall the runner." >&2
-  exit 1
-fi
 RUNTIME_DIR="$(recipe_runtime_dir)"
 RUNTIME_DIST_DIR="${RECIPE_RUNTIME_DIST_DIR:-runtime-dist}"
 case "$RUNTIME_DIST_DIR" in
@@ -152,6 +141,12 @@ CHROME_PROFILE_NAME="${RECIPE_CHROME_PROFILE_NAME:-chrome-profile}"
 # to defer the cache-clear DECISION to `runtime-decision` (single source) and to
 # record the deps/cache baseline after a confirmed-good build.
 RUNNER_BIN="$(harness_dir "$TARGET" extension)/runner/bin/mm-harness"
+# Verify is runner-owned typed code reached through the runner delegate, not a
+# shipped leaf this sequencer could resolve next to itself.
+if $RUN_VERIFY && [ ! -x "$RUNNER_BIN" ]; then
+  echo "mm-harness: runner delegate missing at $RUNNER_BIN; run mm-harness install --adapter extension --target $TARGET." >&2
+  exit 1
+fi
 OUT="${OUT:-$(harness_root)/extension/runner/recipes}"
 ARTIFACTS="${ARTIFACTS:-$(harness_dir "$TARGET" extension)/live/$(date -u +%Y%m%dT%H%M%SZ)}"
 mkdir -p "$ARTIFACTS/logs"
@@ -332,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
@@ -359,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:"
@@ -369,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[@]}"
@@ -390,7 +389,9 @@ 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"
+  # The overlay was installed by this sequencer moments ago; verify must not
+  # reinstall it between launch and the live probe.
+  MM_HARNESS_SKIP_OVERLAY_ENSURE=1 "$RUNNER_BIN" verify --adapter extension --target "$TARGET" -- --out "$OUT" --cdp-port "$CDP_PORT" --artifacts-dir "$ARTIFACTS/verify"
   verify_status=$?
   set -e
 elif [ "$launch_status" -ne 0 ]; then

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/manifest.json

@@ -164,10 +164,10 @@
     },
     {
       "id": "extension/verify",
-      "entry": "adapters/extension/verify.sh",
-      "kind": "bash",
-      "purpose": "Verify the extension harness/runtime is present and healthy (no app launch).",
-      "inputs": "--target --out --cdp-port --static-only",
+      "entry": "src/adapters/extension/verify.ts",
+      "kind": "module",
+      "purpose": "Verify the extension harness/runtime is present and healthy (no app launch). Runner-owned: mm-harness verify runs it in-process.",
+      "inputs": "--target --out --cdp-port --static-only --artifacts-dir",
       "outputs": "verify report + evidence; exit 0/1/2"
     },
     {

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/adapters/shared/resolve-slot-ports-core.mjs

@@ -73,6 +73,35 @@ function scoreSlot(slot, slotSuffix) {
   return [score, cdp, port, slotId, simulator, adbSerial, androidDevice];
 }
 
+// Pool files that describe this machine, then the rest. Every farm node keeps
+// the same checkout paths, so a repo path alone matches a slot in every pool;
+// the pool whose `machine`/`host` is this host is the one that owns the slot.
+export function poolFilesForHost(poolDir, hostname = os.hostname()) {
+  // macOS may report a capitalised or FQDN hostname; pools carry lowercase names.
+  const canonical = (value) => String(value ?? '').toLowerCase().replace(/\.$/u, '');
+  const full = canonical(hostname);
+  const short = full.split('.')[0];
+  const names = (value) => {
+    const name = canonical(value);
+    return name ? [name, name.split('.')[0]] : [];
+  };
+  const local = [];
+  const other = [];
+  for (const name of fs.readdirSync(poolDir).sort()) {
+    // Backups (`*.json.bak.<ts>`, `*.bak`) never define a live slot.
+    if (!name.endsWith('.json') || name.includes('.bak')) continue;
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(path.join(poolDir, name), 'utf8'));
+    } catch {
+      continue;
+    }
+    const isLocal = [...names(data.machine), ...names(data.host)].some((name) => name === full || name === short);
+    (isLocal ? local : other).push({ name, data });
+  }
+  return { local, other };
+}
+
 export function resolveSlotPortsByRepo(repo) {
   const realRepo = realRepoPath(repo);
   if (!realRepo) return null;
@@ -91,29 +120,28 @@ export function resolveSlotPortsByRepo(repo) {
   for (const root of roots) {
     if (!root || !fs.existsSync(path.join(root, 'pool'))) continue;
     const poolDir = path.join(root, 'pool');
+    const pools = poolFilesForHost(poolDir);
     let best = null;
 
-    for (const name of fs.readdirSync(poolDir).sort()) {
-      if (!name.endsWith('.json') || name.includes('.bak.')) continue;
-      let data;
-      try {
-        data = JSON.parse(fs.readFileSync(path.join(poolDir, name), 'utf8'));
-      } catch {
-        continue;
-      }
-      for (const slot of data.slots ?? []) {
-        const slotRepo = slot.repo ?? '';
-        if (!slotRepo) continue;
-        let slotReal;
-        try {
-          slotReal = fs.realpathSync(slotRepo);
-        } catch {
-          continue;
+    // This host's pools decide first; other machines' pools only when none of
+    // ours names the repo (single-node and demo setups).
+    for (const group of [pools.local, pools.other]) {
+      for (const { data } of group) {
+        for (const slot of data.slots ?? []) {
+          const slotRepo = slot.repo ?? '';
+          if (!slotRepo) continue;
+          let slotReal;
+          try {
+            slotReal = fs.realpathSync(slotRepo);
+          } catch {
+            continue;
+          }
+          if (slotReal !== realRepo) continue;
+          const scored = scoreSlot(slot, slotSuffix);
+          if (!best || scored[0] > best[0]) best = scored;
         }
-        if (slotReal !== realRepo) continue;
-        const scored = scoreSlot(slot, slotSuffix);
-        if (!best || scored[0] > best[0]) best = scored;
       }
+      if (best) break;
     }
 
     if (best) {

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
+};