@deeeed/metamask-harness 0.59.0 → 0.60.0

package/dist/commands/doctor.js

@@ -2,6 +2,8 @@ import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { readExtensionPinnedFlags } from "../adapters/extension/feature-flags.js";
+import { featureFlagReport } from "../feature-flags.js";
 import { color } from "../cli-color.js";
 import { collectCheckoutView, renderCheckoutView } from "../checkout-view.js";
 import { createDoctorReport, fixtureSummary, requiredDoctorCheckSummary } from "../doctor.js";
@@ -209,12 +211,14 @@ async function handleDoctor({ options }) {
   }
   const skills = skillsView(target);
   const update = updateStatus();
+  const extensionFlags = adapter === "extension" ? readExtensionPinnedFlags(target) : null;
+  const featureFlags = extensionFlags ? featureFlagReport(extensionFlags.overrides, extensionFlags) : featureFlagReport(liveView?.featureFlagOverrides ?? null);
   const doctorUserAction = doctorResult.checks.find(
     (check) => check.required && check.status === "fail" && check.userAction
   )?.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
   const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
   const next = doctorError?.userAction ?? discovery.deviceDiscoveryErrors?.[0]?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
-  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, view, orphanMetros, capture, skills, update, devices, additionalReachableDevices, ...discovery, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, view, orphanMetros, capture, skills, update, featureFlags, devices, additionalReachableDevices, ...discovery, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -236,6 +240,10 @@ async function handleDoctor({ options }) {
       console.log(`${out("err", "runtime probe failed:")} ${out("dim", runtimeProbeError)}`);
     }
     console.log(renderCheckoutView(view));
+    console.log(`${out("label", "feature flags:")} ${out(
+      featureFlags.error || (featureFlags.overrideCount ?? 0) > 0 ? "warn" : "dim",
+      featureFlags.summary.replace(/^feature flags: /u, "")
+    )}`);
     if (adapter === "mobile") {
       const perps = mobilePerpsEnvironment(target);
       console.log(

package/dist/commands/fixtures.js

@@ -8,6 +8,8 @@ import { acquireCheckoutLock } from "../checkout-lock.js";
 import { colorHumanMessage } from "../cli-color.js";
 import { applyDeviceTargeting } from "./device-target.js";
 import { ADAPTER_DETECT_NEXT, checkoutBusyOut, EXIT, flag, parseFlags, resolveAdapter, scriptOverride, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
+import { FeatureFlagSpecError, fixtureFeatureFlags, parseRemoteFlagSpec, sameFeatureFlags } from "../feature-flags.js";
+import { readExtensionPinnedFlags } from "../adapters/extension/feature-flags.js";
 const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["dev", "force", "json"]);
 const FIXTURE_STREAM_TIMEOUT_MS = 12e4;
 const MOBILE_SETUP_WALLET_TIMEOUT_MS = 36e4;
@@ -177,8 +179,20 @@ async function handleFixturesLocked(argv) {
       );
     }
   }
+  const remoteFlagSpec = str(options, "remoteFlag");
+  let fixtureFlags;
+  try {
+    fixtureFlags = {
+      ...fixtureFeatureFlags(fixturePath),
+      ...remoteFlagSpec === void 0 ? {} : parseRemoteFlagSpec(remoteFlagSpec)
+    };
+  } catch (error) {
+    if (!(error instanceof FeatureFlagSpecError)) throw error;
+    return usageOut(json, "fixtures", error.message, error.userAction);
+  }
+  const fixtureFlagsJson = JSON.stringify(fixtureFlags);
   if (adapter === "extension") {
-    return applyExtensionFixture(target, fixturePath, canonicalFixture, json, sub);
+    return applyExtensionFixture(target, fixturePath, canonicalFixture, json, sub, fixtureFlags);
   }
   const reset = sub === "reset";
   process.stderr.write(`\u2192 fixtures ${sub} ${adapter} \u2014 ${reset ? "resetting selected app data, relaunching, then applying" : "connecting bridge + applying"} wallet fixture (can take ~30s)\u2026
@@ -252,7 +266,7 @@ async function handleFixturesLocked(argv) {
       if (!resetError) {
         mobileSetupResult = await spawnScriptStreaming(
           setupWalletSh,
-          ["--fixture", fixturePath],
+          ["--fixture", fixturePath, "--remote-flags-json", fixtureFlagsJson],
           target,
           {
             env: {
@@ -303,7 +317,7 @@ async function handleFixturesLocked(argv) {
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;
 }
-async function applyExtensionFixture(target, fixturePath, canonicalFixture, json, action) {
+async function applyExtensionFixture(target, fixturePath, canonicalFixture, json, action, fixtureFlags) {
   const distManifest = path.join(target, "dist/chrome/manifest.json");
   const userAction = `mm-harness launch --build --verify --target ${JSON.stringify(target)}`;
   if (!fs.existsSync(distManifest)) {
@@ -330,11 +344,39 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
 `);
   const liveScript = path.join(runnerDir, "adapters/extension/live.sh");
   const args = ["--target", target, "--launch-existing-dist", "--launch-only", "--reset-profile"];
+  const flagKeys = Object.keys(fixtureFlags);
+  if (flagKeys.length > 0) args.push("--remote-flags-json", JSON.stringify(fixtureFlags));
   if (process.env.CDP_PORT) args.push("--cdp-port", process.env.CDP_PORT);
   const result = await spawnScriptStreaming(liveScript, args, target, {
     env: { RECIPE_WALLET_FIXTURE: fixturePath },
     timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
   });
+  const pinned = readExtensionPinnedFlags(target);
+  const pinnedFlags = pinned.pinned ?? {};
+  const flagMismatch = result.status === 0 && !pinned.error && (pinned.pinned === null || !sameFeatureFlags(pinnedFlags, fixtureFlags)) ? [.../* @__PURE__ */ new Set([...flagKeys, ...Object.keys(pinnedFlags)])].filter(
+    (key) => JSON.stringify(pinnedFlags[key]) !== JSON.stringify(fixtureFlags[key])
+  ) : [];
+  if (result.status === 0 && (pinned.error || flagMismatch.length > 0)) {
+    const detail = pinned.error ? `the launched snapshot manifest could not be read (${pinned.sourcePath ?? "unknown path"}): ${pinned.error}` : `snapshot pin disagrees with the fixture for: ${flagMismatch.join(", ")}`;
+    const flagNext = `mm-harness launch --adapter extension --build --target ${JSON.stringify(target)}`;
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "fixtures",
+        action,
+        adapter: "extension",
+        fixture: fixturePath,
+        canonicalFixture,
+        status: "fail",
+        exitCode: EXIT.runtime,
+        error: { code: "EXTENSION_FIXTURE_FLAGS_NOT_APPLIED", message: detail, userAction: flagNext }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness fixtures ${action}: ${detail}
+  Next: ${flagNext}`);
+    }
+    return EXIT.runtime;
+  }
   const status = result.status === 0 ? "pass" : "fail";
   const exitCode = status === "pass" ? EXIT.ok : EXIT.runtime;
   const message = status === "pass" ? `Wallet fixture applied and validated. Want different accounts? Edit: ${canonicalFixture}` : "Extension wallet fixture could not be applied and validated.";

package/dist/commands/launch/extension.js

@@ -30,6 +30,8 @@ import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
 import { isExtensionWatcherLive, stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { EXIT, spawnScriptStreaming } from "../shared.js";
+import { readExtensionPinnedFlags } from "../../adapters/extension/feature-flags.js";
+import { sameFeatureFlags } from "../../feature-flags.js";
 const { CdpSession } = await importRecipeHarnessRuntimeCdp();
 const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = createRequire(import.meta.url)(
   path.join(runnerDir, "adapters/extension/lib/chrome-args.cjs")
@@ -55,7 +57,7 @@ async function installExtensionDeps(target) {
   if (result.status === 0) recordDepsBaseline(target);
   return result;
 }
-async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
+async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen", remoteFlags) {
   const requestedCdpPort = process.env.CDP_PORT;
   const requestedRecipeCdpPort = process.env.RECIPE_CDP_PORT;
   const restoreRequestedPorts = () => {
@@ -68,8 +70,19 @@ async function launchExtension(target, tier, wantWatch, displayMode = "fullscree
   const artifact = releaseArtifactState(target);
   const artifactSnapshot = runtimeDistCheck(target, artifact);
   const artifactLaunchable = !wantWatch && tier !== "build" && artifact.status === "valid" && artifactSnapshot.status === "fresh";
-  const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target, artifact);
+  const livePin = readExtensionPinnedFlags(target);
+  const requestedPin = remoteFlags?.flags ?? {};
+  const pinCurrent = !livePin.error && (livePin.overrides === null ? Object.keys(requestedPin).length === 0 : livePin.pinned !== null) && sameFeatureFlags(livePin.pinned ?? {}, requestedPin);
+  const reusable = !wantWatch && tier !== "build" && pinCurrent && await extensionRuntimeReusable(target, artifact);
   restoreRequestedPorts();
+  if (!pinCurrent && !wantWatch) {
+    const have = Object.keys(livePin.pinned ?? {});
+    const want = Object.keys(requestedPin);
+    const dropping = have.filter((key) => !want.includes(key));
+    console.error(colorHumanMessage(
+      `\u2192 extension launch \u2014 re-creating the dist snapshot to pin remote feature flags` + (want.length ? ` (${want.join(", ")})` : "") + (dropping.length ? `, dropping the previous run's ${dropping.join(", ")}` : "")
+    ));
+  }
   if (artifact.status !== "none" && !reusable && !artifactLaunchable) {
     const detail = artifact.status === "invalid" ? `identity is invalid: ${artifact.reason ?? "unknown reason"}` : "runtime is not healthy and reusable";
     return {
@@ -98,7 +111,7 @@ Next: ${block.userAction}`
     return spawnScriptStreaming(startWatchSh, watchArgs, target);
   }
   if (tier === "build") {
-    return extensionRebuild(target);
+    return extensionRebuild(target, remoteFlags);
   }
   if (reusable) {
     if (artifact.status === "valid") {
@@ -110,9 +123,16 @@ Next: ${block.userAction}`
     return extensionReattach(target, displayMode);
   }
   if (artifactLaunchable) {
+    if (remoteFlags) {
+      return {
+        status: EXIT.infra,
+        output: `REMOTE_FLAG_NOT_PINNABLE: the remote feature-flag pin '${remoteFlags.spec}' (from --remote-flag and the wallet fixture's remoteFeatureFlags) cannot be applied to a verified release artifact; the artifact's manifest is signed evidence and is never rewritten.
+Next: drop --remote-flag and remove remoteFeatureFlags from the wallet fixture to validate the artifact as shipped, or validate the variant on a source checkout launched without the artifact.`
+      };
+    }
     return extensionLaunchReleaseArtifact(target, artifact);
   }
-  return extensionLaunchDevelopment(target);
+  return extensionLaunchDevelopment(target, remoteFlags);
 }
 async function extensionRuntimeReusable(target, artifact = releaseArtifactState(target)) {
   const cdpPort = process.env.CDP_PORT;
@@ -370,11 +390,12 @@ async function extensionReattach(target, displayMode = "fullscreen") {
   console.error(colorHumanMessage(`\u2192 extension quick reattach \u2014 reload in place \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no rebuild, no relaunch)`));
   return spawnScriptStreaming(reattachScript, reattachArgs, target);
 }
-async function extensionLaunchDevelopment(target) {
+async function extensionLaunchDevelopment(target, remoteFlags) {
   const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
   const liveArgs = ["--target", target];
   const existingBuild = isExtensionWatcherLive(target) && harnessWatcherMatchesProductConfig(target) && extensionCompiledScriptsMatchProductConfig(target, path.join(target, "dist/chrome")) && fs.existsSync(path.join(target, "dist/chrome/manifest.json")) && !isExtensionDistStale(target);
   liveArgs.push(existingBuild ? "--launch-existing-dist" : "--start-watch");
+  if (remoteFlags) liveArgs.push("--remote-flags-json", remoteFlags.json);
   if (process.env.CDP_PORT) liveArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.EXTENSION_START_URL) liveArgs.push("--start-url", process.env.EXTENSION_START_URL);
   console.error(colorHumanMessage(
@@ -425,7 +446,7 @@ function harnessWatcherMatchesProductConfig(target) {
     return false;
   }
 }
-async function extensionRebuild(target) {
+async function extensionRebuild(target, remoteFlags) {
   const runtimeDirRel = recipeRuntimeDir();
   const runtimeAbs = path.join(target, runtimeDirRel);
   const rebuildLog = path.join(runtimeAbs, "rebuild.log");
@@ -434,6 +455,7 @@ async function extensionRebuild(target) {
   fs.writeFileSync(rebuildLog, "");
   const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
   const liveArgs = ["--target", target, "--build-lavamoat"];
+  if (remoteFlags) liveArgs.push("--remote-flags-json", remoteFlags.json);
   if (process.env.CDP_PORT) liveArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.EXTENSION_START_URL) liveArgs.push("--start-url", process.env.EXTENSION_START_URL);
   console.error(colorHumanMessage(`\u2192 extension quick relaunch \u2014 production-like LavaMoat build \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`));

package/dist/commands/launch/index.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { color, colorHumanMessage } from "../../cli-color.js";
 import { handleHarness } from "../../harness.js";
-import { recipeRuntimePath, runnerDir } from "../../paths.js";
+import { recipeRuntimePath, runnerDir, walletFixturePath } from "../../paths.js";
 import { getAdapterSurface } from "../../adapters/surface.js";
 import {
   ADAPTER_DETECT_NEXT,
@@ -35,6 +35,15 @@ import { launchMobile } from "./mobile.js";
 import { applyDeviceTargeting } from "../device-target.js";
 import { acquireCheckoutLock } from "../../checkout-lock.js";
 import { JsonStreamWriter } from "../../json-stream.js";
+import {
+  FeatureFlagSpecError,
+  fixtureFeatureFlags,
+  parseRemoteFlagSpec,
+  remoteFlagRequestFor,
+  sameFeatureFlags,
+  toRemoteFlagSpec
+} from "../../feature-flags.js";
+import { readExtensionPinnedFlags } from "../../adapters/extension/feature-flags.js";
 import { ensureExtensionConsoleCapture } from "../../adapters/extension/console-capture.js";
 import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
 import {
@@ -178,6 +187,25 @@ async function handleLaunchLocked(argv, stream) {
     );
   }
   const displayMode = requestedSurface ?? legacySurface ?? "fullscreen";
+  const remoteFlagSpec = str(options, "remoteFlag");
+  if (remoteFlagSpec !== void 0 && adapter === "extension" && wantWatch) {
+    return launchUsage(
+      jsonOutput,
+      stream,
+      "--remote-flag cannot be applied with --watch: the watcher never re-creates the dist snapshot that carries the pin.",
+      `mm-harness launch --adapter extension --remote-flag ${remoteFlagSpec} --target ${shellQuote(target)}`
+    );
+  }
+  let remoteFlagRequest;
+  try {
+    remoteFlagRequest = remoteFlagRequestFor({
+      ...fixtureFeatureFlags(walletFixturePath(target)),
+      ...remoteFlagSpec === void 0 ? {} : parseRemoteFlagSpec(remoteFlagSpec)
+    });
+  } catch (error) {
+    if (!(error instanceof FeatureFlagSpecError)) throw error;
+    return launchUsage(jsonOutput, stream, error.message, error.userAction);
+  }
   for (const portFlag of ["cdpPort", "watcherPort"]) {
     const value = str(options, portFlag);
     if (value !== void 0 && !/^\d+$/u.test(value)) {
@@ -286,10 +314,23 @@ async function handleLaunchLocked(argv, stream) {
     machine,
     displayMode,
     false,
-    wantClearMetro
+    wantClearMetro,
+    remoteFlagRequest
   );
   if (attempt.status === 0) {
-    return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+    return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, attempt.remoteFeatureFlags);
+  }
+  if (adapter === "extension" && attempt.output.includes("REMOTE_FLAG_NOT_PINNABLE:")) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "REMOTE_FLAG_NOT_PINNABLE",
+      message: `a verified release artifact cannot carry a remote feature-flag pin (${remoteFlagRequest?.spec ?? ""}); its manifest is signed evidence and is never rewritten. Validate the artifact as shipped (drop --remote-flag and the fixture's remoteFeatureFlags) or validate the variant on a source build.`,
+      recoverable: false,
+      // The next step must leave the artifact alone: a --build here would replace
+      // the artifact under validation with a source build.
+      userAction: Object.keys(fixtureFeatureFlags(walletFixturePath(target))).length > 0 ? `remove remoteFeatureFlags from ${shellQuote(walletFixturePath(target))}, then: mm-harness launch --adapter extension --target ${shellQuote(target)}` : `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
+      exitCode: EXIT.infra,
+      originalError: attempt.output.trim() || void 0
+    });
   }
   if (adapter === "extension" && extensionProductConfigMissing(attempt.output)) {
     const block = extensionProductConfigBlock(target);
@@ -352,10 +393,10 @@ async function handleLaunchLocked(argv, stream) {
     const recoveryCode2 = "chrome.relaunched";
     state.attemptedRecoveries.push(recoveryCode2);
     stream.phase("recover");
-    const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode);
+    const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode, false, false, remoteFlagRequest);
     if (rebuildAttempt.status === 0) {
       state.recovered.push(recoveryCode2);
-      return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+      return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, rebuildAttempt.remoteFeatureFlags);
     }
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "EXTENSION_RELAUNCH_FAILED",
@@ -434,11 +475,13 @@ async function handleLaunchLocked(argv, stream) {
     target,
     machine,
     displayMode,
-    restartMobileApp
+    restartMobileApp,
+    false,
+    remoteFlagRequest
   );
   if (attempt.status === 0) {
     state.recovered.push(recoveryCode);
-    return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+    return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, attempt.remoteFeatureFlags);
   }
   return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
     code: "SAME_RECOVERY_TWICE",
@@ -560,7 +603,39 @@ function nativeInputsChanged(target, adapter) {
     return false;
   }
 }
-async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode = "fullscreen", restartMobileApp = false, clearMobileMetro = false) {
+function verifyExtensionPin(target, requested) {
+  const pinned = readExtensionPinnedFlags(target);
+  if (pinned.error) {
+    return {
+      ok: false,
+      flags: {},
+      code: "RUNTIME_MANIFEST_UNREADABLE",
+      message: `the launched dist snapshot manifest could not be read (${pinned.sourcePath ?? "unknown path"}): ${pinned.error}`
+    };
+  }
+  if (pinned.overrides !== null && pinned.pinned === null) {
+    return {
+      ok: false,
+      flags: {},
+      code: "REMOTE_FLAG_NOT_APPLIED",
+      message: `the launched dist snapshot manifest (${pinned.sourcePath ?? "unknown path"}) carries no harness pin record; it was not written by this launch.`
+    };
+  }
+  const actual = pinned.pinned ?? {};
+  if (!sameFeatureFlags(actual, requested)) {
+    const mismatched = [.../* @__PURE__ */ new Set([...Object.keys(requested), ...Object.keys(actual)])].filter(
+      (key) => JSON.stringify(actual[key]) !== JSON.stringify(requested[key])
+    );
+    return {
+      ok: false,
+      flags: {},
+      code: "REMOTE_FLAG_NOT_APPLIED",
+      message: `the remote feature-flag pin ${toRemoteFlagSpec(requested) || "(none)"} does not match the launched snapshot manifest: ` + mismatched.map((key) => `${key} expected ${JSON.stringify(requested[key])}, got ${JSON.stringify(actual[key])}`).join("; ")
+    };
+  }
+  return { ok: true, flags: actual, message: "" };
+}
+async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode = "fullscreen", restartMobileApp = false, clearMobileMetro = false, remoteFlagRequest) {
   if (adapter === "mobile") {
     return launchMobile(
       target,
@@ -568,12 +643,44 @@ async function executeComposition(adapter, mobileTarget, tier, wantWatch, target
       tier,
       json,
       restartMobileApp,
-      clearMobileMetro
+      clearMobileMetro,
+      remoteFlagRequest?.flags
     );
   }
-  return launchExtension(target, tier, wantWatch, displayMode);
+  return launchExtension(target, tier, wantWatch, displayMode, remoteFlagRequest);
 }
-async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, sidepanelRecoveryAllowed = true) {
+async function settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, sidepanelRecoveryAllowed = true, mobileProvenFlags) {
+  const requested = remoteFlagRequest?.flags ?? {};
+  const pinned = adapter !== "extension" ? { ok: true, flags: mobileProvenFlags === void 0 ? requested : mobileProvenFlags, message: "" } : wantWatch ? { ok: true, flags: readExtensionPinnedFlags(target).pinned, message: "" } : verifyExtensionPin(target, requested);
+  if (!pinned.ok) {
+    const spec = remoteFlagRequest?.spec;
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: pinned.code ?? "REMOTE_FLAG_NOT_APPLIED",
+      message: pinned.message,
+      recoverable: false,
+      // A rebuild re-creates the snapshot; the flag is repeated only when one was asked for.
+      userAction: `mm-harness launch --adapter extension --build${spec ? ` --remote-flag ${spec}` : ""} --target ${shellQuote(target)}`,
+      exitCode: EXIT.runtime
+    });
+  }
+  return finishLaunch(
+    jsonOutput,
+    machine,
+    stream,
+    adapter,
+    mobileTarget,
+    tier,
+    displayMode,
+    target,
+    state,
+    wantWatch,
+    wantVerify,
+    sidepanelRecoveryAllowed,
+    remoteFlagRequest,
+    pinned.flags
+  );
+}
+async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, sidepanelRecoveryAllowed = true, remoteFlagRequest, remoteFlags = {}) {
   if (adapter === "extension" && displayMode === "fullscreen") {
     const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
     const sidepanelArgs = ["close"];
@@ -605,10 +712,10 @@ async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget,
       if (sidepanelRecoveryAllowed && tier === "quick" && extensionRuntimeBlocked(sidepanel.output) && !state.attemptedRecoveries.includes(recoveryCode)) {
         state.attemptedRecoveries.push(recoveryCode);
         stream.phase("recover");
-        const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode);
+        const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode, false, false, remoteFlagRequest);
         if (rebuildAttempt.status === 0) {
           state.recovered.push(recoveryCode);
-          return await finishLaunch(
+          return await settleLaunch(
             jsonOutput,
             machine,
             stream,
@@ -620,6 +727,7 @@ async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget,
             state,
             wantWatch,
             wantVerify,
+            remoteFlagRequest,
             false
           );
         }
@@ -668,14 +776,15 @@ async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget,
         tier,
         recovered: state.recovered,
         mutations: state.mutations,
-        metro: metroLaunchEvidence(adapter, target)
+        metro: metroLaunchEvidence(adapter, target),
+        remoteFeatureFlags: remoteFlags
       });
     }
     return exitCode;
   }
-  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, target, state);
+  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, target, state, remoteFlags);
 }
-function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, target, state) {
+function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, target, state, remoteFlags = {}) {
   if (stream.enabled) {
     for (const mutation of state.mutations) stream.mutation(mutation);
     for (const recovery of state.recovered) stream.recovery(recovery);
@@ -685,7 +794,8 @@ function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, targ
       tier,
       recovered: state.recovered,
       mutations: state.mutations,
-      metro: metroLaunchEvidence(adapter, target)
+      metro: metroLaunchEvidence(adapter, target),
+      remoteFeatureFlags: remoteFlags
     });
   } else if (json) {
     console.log(
@@ -701,6 +811,7 @@ function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, targ
           recovered: state.recovered,
           mutations: state.mutations,
           metro: metroLaunchEvidence(adapter, target),
+          remoteFeatureFlags: remoteFlags,
           exitCode: EXIT.ok
         },
         null,

package/dist/commands/launch/mobile.js

@@ -4,9 +4,11 @@ import {
   recordMobileSourceBaseline
 } from "../../adapters/mobile/source-freshness.js";
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
+import { pinMobileFeatureFlags } from "../../adapters/mobile/feature-flags.js";
+import { toRemoteFlagSpec } from "../../feature-flags.js";
 import { clearMobileReleaseArtifactState } from "../../adapters/mobile/release-artifact-state.js";
 import { EXIT } from "../shared.js";
-async function launchMobile(target, mobileTarget, tier, json, restartApp = false, clearMetro = false) {
+async function launchMobile(target, mobileTarget, tier, json, restartApp = false, clearMetro = false, remoteFlags) {
   clearMobileReleaseArtifactState(target);
   await ensureHarnessFresh(target, "mobile");
   const platform = mobileTarget ?? "ios";
@@ -22,13 +24,35 @@ async function launchMobile(target, mobileTarget, tier, json, restartApp = false
     clearMetro
   });
   if (result.status !== 0) return result;
+  const flags = remoteFlags ?? {};
+  const pin = await pinMobileFeatureFlags(target, flags);
+  let provenFlags = flags;
+  if (!pin.ok && !remoteFlags && pin.error) {
+    provenFlags = null;
+    if (!json) process.stderr.write(`WARN: remote feature-flag overrides were not cleared: ${pin.error}
+`);
+  } else if (!pin.ok) {
+    const detail = pin.error ?? `did not read back: ${pin.mismatched.join(", ")} (got ${JSON.stringify(
+      Object.fromEntries(pin.mismatched.map((key) => [key, pin.effective[key] ?? pin.overrides[key]]))
+    )})`;
+    const message = `REMOTE_FLAG_NOT_APPLIED: remote feature flags ${toRemoteFlagSpec(flags) || "(none: clearing overrides)"} ${detail}
+  Next: confirm the app is running with the harness bridge, then re-run mm-harness launch`;
+    if (!json) process.stderr.write(`${message}
+`);
+    return { status: EXIT.runtime, output: message };
+  } else if (!json) {
+    process.stderr.write(
+      pin.applied.length ? `Remote feature flags pinned: ${pin.applied.join(", ")}
+` : "Remote feature flag overrides cleared.\n"
+    );
+  }
   if (!recordMobileSourceBaseline(target, source.fingerprint)) {
     const message = "Mobile source changed while the app was launching; the loaded-source baseline was not recorded.\n  Next: re-run mm-harness launch.";
     if (!json) process.stderr.write(`${message}
 `);
     return { status: EXIT.runtime, output: message };
   }
-  return result;
+  return { ...result, remoteFeatureFlags: provenFlags };
 }
 export {
   launchMobile

package/dist/commands/mobile-device-view.js

@@ -21,9 +21,16 @@ async function mobileDeviceLiveView(target, view) {
     liveMap,
     devicesWithLive,
     additionalReachableDevices: reachableDevices,
-    androidPortHints: selectedAndroidPortHints(view.devices, liveMap)
+    androidPortHints: selectedAndroidPortHints(view.devices, liveMap),
+    featureFlagOverrides: slotFeatureFlagOverrides(liveMap)
   };
 }
+function slotFeatureFlagOverrides(liveMap) {
+  for (const live of liveMap.values()) {
+    if (live.featureFlagOverrides) return live.featureFlagOverrides;
+  }
+  return null;
+}
 function scopedLiveMap(devices, allLiveMap) {
   const liveMap = /* @__PURE__ */ new Map();
   for (const device of devices) {

package/dist/commands/prepare.js

@@ -11,6 +11,7 @@ import { harnessExecutable, manifestPath, recipeRuntimeDir } from "../paths.js";
 import { optionFlag, optionString, parseArgs, targetPath, usageError } from "./parse-args.js";
 import { EXIT } from "./shared.js";
 import { formatDuration } from "./status-watch.js";
+import { FeatureFlagSpecError, parseRemoteFlagSpec } from "../feature-flags.js";
 const USAGE = "mm-harness prepare [--target <checkout>] [--platform mobile|extension|core] [--mobile-platform ios|android] [--clear-metro] [--artifacts-dir <dir>] [--json]";
 const REPORT_DIR = "prepare";
 const SKIPPED_AFTER_FAILURE = "previous step failed";
@@ -318,6 +319,21 @@ async function handlePrepare(argv) {
     throw usageError(`--clear-metro is mobile only; this checkout is ${platform}
   Next: ${USAGE}`);
   }
+  const remoteFlag = optionString(options, "remoteFlag");
+  if (remoteFlag !== void 0) {
+    if (platform === "core") {
+      throw usageError(`--remote-flag needs an app runtime; this checkout is core
+  Next: ${USAGE}`);
+    }
+    try {
+      parseRemoteFlagSpec(remoteFlag);
+    } catch (error) {
+      if (!(error instanceof FeatureFlagSpecError)) throw error;
+      throw usageError(`${error.message}
+  Next: ${error.userAction}`);
+    }
+  }
+  const remoteFlagArgs = remoteFlag === void 0 ? [] : ["--remote-flag", remoteFlag];
   let mobilePlatform = mobilePlatformOption(optionString(options, "mobilePlatform"));
   const recordPath = path.join(artifactsDir, READINESS_RECORD);
   const chain = stepChain(platform);
@@ -353,17 +369,18 @@ async function handlePrepare(argv) {
       addStep(skippedStep("fixtures", `${executable} fixtures set`, reason));
     } else if (platform === "mobile") {
       const device = mobilePlatform ? [mobilePlatform] : [];
-      await run("launch", ["launch", ...device, ...clearMetro ? ["--clear-metro"] : [], "--verify", "--json", ...targetArgs]);
+      await run("launch", ["launch", ...device, ...clearMetro ? ["--clear-metro"] : [], ...remoteFlagArgs, "--verify", "--json", ...targetArgs]);
       await run("fixtures", [
         "fixtures",
         "set",
         ...mobilePlatform ? ["--platform", mobilePlatform] : [],
+        ...remoteFlagArgs,
         "--json",
         ...targetArgs
       ]);
     } else {
-      await run("launch", ["launch", "--verify", "--json", ...targetArgs]);
-      await run("fixtures", ["fixtures", "set", "--json", ...targetArgs]);
+      await run("launch", ["launch", ...remoteFlagArgs, "--verify", "--json", ...targetArgs]);
+      await run("fixtures", ["fixtures", "set", ...remoteFlagArgs, "--json", ...targetArgs]);
     }
     await run("verify", ["verify", "--json", "--adapter", platform, ...targetArgs]);
   } finally {

package/dist/commands/run-engine.js

@@ -1344,7 +1344,16 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
     );
   const launch = deps.launch ?? (async (requestedTier) => {
     const { launchExtension } = await import("./launch/extension.js");
-    return launchExtension(target, requestedTier, false);
+    const { readExtensionPinnedFlags } = await import("../adapters/extension/feature-flags.js");
+    const { fixtureFeatureFlags, remoteFlagRequestFor } = await import("../feature-flags.js");
+    const { walletFixturePath } = await import("../paths.js");
+    return launchExtension(
+      target,
+      requestedTier,
+      false,
+      "fullscreen",
+      remoteFlagRequestFor(readExtensionPinnedFlags(target).pinned ?? fixtureFeatureFlags(walletFixturePath(target)))
+    );
   });
   const result = await launch(tier);
   const verified = result.status === 0 ? await decide() : initial;

package/dist/commands/runtime-launch.js

@@ -20,6 +20,7 @@ import {
   targetPath,
   usageError
 } from "./parse-args.js";
+import { FeatureFlagSpecError, parseRemoteFlagSpec } from "../feature-flags.js";
 async function handleRuntimeLaunch({ options }) {
   if (optionFlag(options, "help")) {
     console.log(`mm-harness runtime-launch --adapter <extension|mobile> --target <checkout> [flags]
@@ -129,7 +130,15 @@ async function handleRuntimeLaunch({ options }) {
   if (chromeUserDataDir) command.push("--chrome-user-data-dir", chromeUserDataDir);
   command.push(optionFlag(options, "resetProfile") ? "--reset-profile" : "--preserve-profile");
   const remoteFlag = optionString(options, "remoteFlag");
-  if (remoteFlag) command.push("--remote-flag", remoteFlag);
+  if (remoteFlag) {
+    try {
+      command.push("--remote-flags-json", JSON.stringify(parseRemoteFlagSpec(remoteFlag)));
+    } catch (error) {
+      if (!(error instanceof FeatureFlagSpecError)) throw error;
+      throw usageError(`${error.message}
+  Next: ${error.userAction}`);
+    }
+  }
   if (!fs.existsSync(liveScript)) {
     const report2 = runtimeLaunchReport("fail", {
       adapter,