@deeeed/metamask-harness 0.74.0 → 0.76.0

package/dist/adapters/extension/doctor-checks.js

@@ -0,0 +1,135 @@
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { recipeRuntimeDir, runnerDir } from "../../paths.js";
+function extensionBrowserDoctorCheck(target) {
+  const requireFromTarget = createRequire(path.join(path.resolve(target), "package.json"));
+  for (const packageName of ["@playwright/test", "playwright"]) {
+    try {
+      const playwright = requireFromTarget(packageName);
+      const executable = playwright.chromium?.executablePath?.();
+      if (executable && fs.existsSync(executable)) {
+        return {
+          id: "playwright-chromium",
+          status: "pass",
+          required: true,
+          message: "Checkout-pinned Playwright Chromium is installed.",
+          detail: executable
+        };
+      }
+    } catch {
+    }
+  }
+  return {
+    id: "playwright-chromium",
+    status: "fail",
+    required: true,
+    message: "Checkout-pinned Playwright Chromium is not installed.",
+    userAction: "yarn playwright install chromium"
+  };
+}
+function extensionBrowserResolutionDoctorCheck(target) {
+  const resolver = path.join(runnerDir, "adapters/shared/browser-resolver.cjs");
+  const runtime = path.join(path.resolve(target), recipeRuntimeDir());
+  const record = path.join(runtime, "browser-resolution.json");
+  let profile = process.env.CHROME_USER_DATA_DIR || path.join(runtime, process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile");
+  while (profile.length > 1 && profile.endsWith("/")) profile = profile.slice(0, -1);
+  const profileExists = fs.existsSync(path.join(profile, "Local State"));
+  const result = spawnSync(process.execPath, [
+    resolver,
+    "resolve",
+    "--target",
+    path.resolve(target),
+    "--launch-method",
+    "launch-services",
+    "--display",
+    "headful",
+    ...profileExists && fs.existsSync(record) ? ["--recorded", record] : [],
+    "--json"
+  ], {
+    cwd: path.resolve(target),
+    encoding: "utf8",
+    timeout: 135e3
+  });
+  if (result.status === 0) {
+    const resolution = JSON.parse(result.stdout);
+    const managed = resolution.managedChrome;
+    const managedNote = managed && !resolution.warning?.includes("managed by policy") ? ` Google Chrome is managed by policy (${managed.forcedExtensions.length} forced extension${managed.forcedExtensions.length === 1 ? "" : "s"}: ${managed.forcedExtensions.map(({ id, name }) => name ? `${id} (${name})` : id).join(", ")}${managed.signinForced ? "; browser sign-in forced" : ""}); slots use Chrome for Testing.` : "";
+    const probe = resolution.probe ? `; Chrome for Testing probe (${resolution.probe.launchMethod}, ${resolution.probe.display}${resolution.probe.cached ? ", cached" : ""}${resolution.probe.transient ? `, retried after ${resolution.probe.expiresAt}` : ""}): ${resolution.probe.reason}` : resolution.recordedFrom ? `; kept from the slot profile record ${resolution.recordedFrom}` : "";
+    return {
+      id: "extension-browser",
+      status: "pass",
+      required: false,
+      message: `Launch browser: ${resolution.browser} ${resolution.version ?? "(unknown version)"} via ${resolution.source} (${resolution.mode}); extension loading: ${resolution.extensionLoading}${probe}.${managedNote}${resolution.warning ? ` Warning: ${resolution.warning}` : ""}`,
+      detail: resolution.bin
+    };
+  }
+  const message = (result.stderr || result.error?.message || "browser resolution failed").trim();
+  return {
+    id: "extension-browser",
+    status: "fail",
+    required: message.includes("BROWSER_UNLAUNCHABLE:"),
+    message,
+    userAction: "install Google Chrome, or set RECIPE_HARNESS_BROWSER / RECIPE_HARNESS_CHROME_BIN to a browser that starts"
+  };
+}
+function ensureExtensionPerpsBuildFlag(target) {
+  const configPath = path.join(target, ".metamaskrc");
+  const templatePath = path.join(target, ".metamaskrc.dist");
+  const config = readTextSnapshot(configPath);
+  const template = config.kind === "file" ? null : readTextSnapshot(templatePath);
+  const source = config.kind === "file" ? config : template?.kind === "file" ? template : config.kind === "symlink" ? { kind: "file", text: "", mode: 438 } : null;
+  if (!source) return false;
+  const before = source.text;
+  if (/^\s*PERPS_ENABLED\s*=\s*(['"]?)true\1\s*$/mu.test(before)) return false;
+  const line = "PERPS_ENABLED='true'";
+  const after = /^\s*PERPS_ENABLED\s*=.*$/mu.test(before) ? before.replace(/^\s*PERPS_ENABLED\s*=.*$/mu, line) : `${before.replace(/\s*$/u, "")}
+${line}
+`;
+  const temporary = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+  let descriptor = null;
+  try {
+    const mode = config.kind === "file" ? config.mode : 438;
+    descriptor = fs.openSync(
+      temporary,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+      mode
+    );
+    fs.writeFileSync(descriptor, after);
+    if (config.kind === "file") fs.fchmodSync(descriptor, config.mode);
+    fs.closeSync(descriptor);
+    descriptor = null;
+    fs.renameSync(temporary, configPath);
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
+    fs.rmSync(temporary, { force: true });
+  }
+  return true;
+}
+function readTextSnapshot(file) {
+  let descriptor;
+  try {
+    descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") return { kind: "missing" };
+    if (code === "ELOOP") return { kind: "symlink" };
+    throw error;
+  }
+  try {
+    return {
+      kind: "file",
+      text: fs.readFileSync(descriptor, "utf8"),
+      mode: fs.fstatSync(descriptor).mode & 511
+    };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+export {
+  ensureExtensionPerpsBuildFlag,
+  extensionBrowserDoctorCheck,
+  extensionBrowserResolutionDoctorCheck
+};

package/dist/adapters/extension/fixtures.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import { colorHumanMessage } from "../../cli-color.js";
+import { FIXTURE_STREAM_TIMEOUT_MS } from "../../commands/fixtures.js";
+import { EXIT, spawnScriptStreaming } from "../../commands/shared.js";
+import { sameFeatureFlags } from "../../feature-flags.js";
+import { runnerDir } from "../../paths.js";
+import { readExtensionPinnedFlags } from "./feature-flags.js";
+async function applyExtensionFixture({
+  target,
+  fixturePath,
+  canonicalFixture,
+  json,
+  sub: 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)) {
+    const message2 = `Extension fixture needs an existing dist/chrome build; no manifest was found at ${distManifest}.`;
+    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_BUILD_REQUIRED", message: message2, userAction }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness fixtures ${action}: ${message2}
+  Next: ${userAction}`);
+    }
+    return EXIT.runtime;
+  }
+  process.stderr.write(`${colorHumanMessage(`\u2192 fixtures ${action} extension \u2014 resetting and seeding the slot-owned profile from the existing build\u2026`)}
+`);
+  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.";
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "fixtures",
+      action,
+      adapter: "extension",
+      fixture: fixturePath,
+      canonicalFixture,
+      status,
+      exitCode,
+      profileReset: status === "pass",
+      message,
+      error: status === "fail" ? { code: "EXTENSION_FIXTURE_APPLY_FAILED", message, userAction } : null
+    }, null, 2));
+  } else if (status === "pass") {
+    console.error(message);
+  } else {
+    console.error(`\u2717 mm-harness fixtures ${action}: ${message}
+  Next: ${userAction}`);
+  }
+  return exitCode;
+}
+export {
+  applyExtensionFixture
+};

package/dist/adapters/extension/launch.js

@@ -0,0 +1,315 @@
+import path from "node:path";
+import { colorHumanMessage } from "../../cli-color.js";
+import {
+  extensionDepsBlock,
+  extensionRuntimeReusable,
+  installExtensionDeps,
+  launchExtension
+} from "../../commands/launch/extension.js";
+import { shellQuote } from "../../commands/launch/quote.js";
+import { EXIT, spawnScript } from "../../commands/shared.js";
+import {
+  fixtureFeatureFlags,
+  sameFeatureFlags,
+  toRemoteFlagSpec
+} from "../../feature-flags.js";
+import { RECOVERY_CODE } from "../../heal-bounds.js";
+import { runnerDir, walletFixturePath } from "../../paths.js";
+import { ensureExtensionConsoleCapture } from "./console-capture.js";
+import { readExtensionPinnedFlags } from "./feature-flags.js";
+import { extensionProductConfigBlock } from "./product-config.js";
+import { releaseArtifactState, runtimeDistCheck } from "./runtime-decision.js";
+const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
+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: "" };
+}
+function extensionQuickReattachFailed(output) {
+  return /\[reattach\]|extension quick reattach|mm-harness launch --build/u.test(output);
+}
+function extensionRuntimeBlocked(output) {
+  return /ERR_BLOCKED_BY_CLIENT|has been blocked by Chromium/u.test(output);
+}
+function extensionBrowserMissing(output) {
+  return /Playwright Chromium is not installed|No compatible Chromium binary selected/u.test(output);
+}
+function extensionProductConfigMissing(output) {
+  return /EXTENSION_PRODUCT_CONFIG_REQUIRED:/u.test(output);
+}
+function extensionEvmRpcUnreachable(output) {
+  return /EVM_RPC_UNREACHABLE|EVM RPC readiness probe failed|Infura configured ≠ RPC reachable/u.test(output);
+}
+const extensionLaunchProfile = {
+  refuseFlags({ target }, { watch, runway, clearMetro, remoteFlagSpec }) {
+    if (runway) return { message: "runway is mobile-only.", userAction: "drop --runway for the extension" };
+    if (clearMetro) return { message: "--clear-metro is mobile-only.", userAction: "drop --clear-metro for the extension" };
+    if (remoteFlagSpec !== void 0 && watch) {
+      return {
+        message: "--remote-flag cannot be applied with --watch: the watcher never re-creates the dist snapshot that carries the pin.",
+        userAction: `mm-harness launch --adapter extension --remote-flag ${remoteFlagSpec} --target ${shellQuote(target)}`
+      };
+    }
+    return void 0;
+  },
+  // --url: initial main-tab page for extension launches (dapp beside the
+  // sidepanel); travels to live.sh/launch-browser via env. Sidepanel mode has a
+  // useful default so `mm-harness launch --sidepanel` opens a working dapp, not
+  // just a wallet panel with no page to connect from.
+  start({ options, displayMode, machine, wantWatch, tier }) {
+    const requestedUrl = typeof options["url"] === "string" && options["url"] ? options["url"] : "";
+    if (requestedUrl || displayMode === "sidepanel") {
+      process.env.EXTENSION_START_URL = requestedUrl || DEFAULT_EXTENSION_DAPP_URL;
+    }
+    if (machine) return;
+    const modeNote = displayMode === "sidepanel" ? `sidepanel \xB7 dapp ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}` : "fullscreen";
+    const workNote = wantWatch ? "watch only" : tier === "build" ? "clean build" : "quick reuse probe";
+    console.error(colorHumanMessage(
+      `\u2192 extension launch \u2014 ${modeNote} \xB7 CDP :${process.env.CDP_PORT ?? "default"} \xB7 ${workNote}`
+    ));
+  },
+  nativeInputs: ["package.json", "yarn.lock", "webpack.config.js"],
+  rebuildCommand: () => "mm-harness launch --build",
+  // Source-development launch paths require checkout tooling. A verified local
+  // release artifact can reuse its healthy browser without building or watching.
+  async healthcheck(launch, state) {
+    const { target, tier, wantWatch, heal, stream } = launch;
+    const artifact = releaseArtifactState(target);
+    const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target, artifact);
+    const verifiedReleaseReuse = artifact.status === "valid" && reusable;
+    const verifiedReleaseLaunch = !wantWatch && tier !== "build" && artifact.status === "valid" && runtimeDistCheck(target, artifact).status === "fresh";
+    const willBuild = !reusable;
+    if (willBuild) {
+      const productConfigBlock = extensionProductConfigBlock(target);
+      if (productConfigBlock) {
+        return launch.fail(state, {
+          code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
+          message: productConfigBlock.message,
+          recoverable: false,
+          userAction: productConfigBlock.userAction,
+          exitCode: EXIT.infra
+        });
+      }
+    }
+    const depsBlock = verifiedReleaseReuse || verifiedReleaseLaunch ? null : extensionDepsBlock(target);
+    if (depsBlock) {
+      if (heal === "off") return launch.usage(depsBlock.message, depsBlock.userAction);
+      const recoveryCode = "deps.installed";
+      state.attemptedRecoveries.push(recoveryCode);
+      stream.phase("recover");
+      const repaired = await installExtensionDeps(target);
+      if (repaired.status !== 0 || extensionDepsBlock(target)) {
+        return launch.fail(state, {
+          code: "DEPENDENCY_INSTALL_FAILED",
+          message: depsBlock.message,
+          recoverable: false,
+          userAction: "install the checkout-pinned Node version, then re-run mm-harness launch",
+          originalError: repaired.output,
+          exitCode: EXIT.infra
+        });
+      }
+      state.recovered.push(recoveryCode);
+      state.mutations.push({ type: "dependencies", action: "installed", path: target });
+    }
+    return void 0;
+  },
+  compose: ({ target, wantWatch, displayMode, remoteFlagRequest }, tier) => launchExtension(target, tier, wantWatch, displayMode, remoteFlagRequest),
+  classify({ target, remoteFlagRequest }, output) {
+    if (output.includes("REMOTE_FLAG_NOT_PINNABLE:")) {
+      return {
+        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: output.trim() || void 0
+      };
+    }
+    if (extensionProductConfigMissing(output)) {
+      const block = extensionProductConfigBlock(target);
+      return {
+        code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
+        message: block?.message ?? "Extension product configuration was not ready when the build started.",
+        recoverable: false,
+        userAction: block?.userAction ?? `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
+        exitCode: EXIT.infra
+      };
+    }
+    if (extensionBrowserMissing(output)) {
+      return {
+        code: "EXTENSION_BROWSER_REQUIRED",
+        message: "the checkout Playwright browser is not installed; system Chrome is not a compatible unpacked-extension fallback. Installing the browser cache requires user approval.",
+        recoverable: false,
+        userAction: `ask the user for approval, then run: cd ${shellQuote(target)} && yarn playwright install chromium`,
+        exitCode: EXIT.infra
+      };
+    }
+    if (output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") || output.includes("EXTENSION_STARTUP_UNVERIFIED:")) {
+      return {
+        code: output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") ? "EXTENSION_BACKGROUND_UNRESPONSIVE" : "EXTENSION_STARTUP_UNVERIFIED",
+        message: "Extension startup is not healthy; inspect the background error before restarting or resetting wallet state.",
+        recoverable: false,
+        userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    if (output.includes("EVM_RPC_EXECUTION_FAILED:")) {
+      return {
+        code: "EVM_RPC_EXECUTION_FAILED",
+        message: "Background RPC fetch failed during JavaScript execution; this does not establish an Infura authentication or connectivity failure.",
+        recoverable: false,
+        userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    if (extensionEvmRpcUnreachable(output)) {
+      return {
+        code: "EVM_RPC_UNREACHABLE",
+        message: "EVM RPC readiness failed; Infura configured does not mean RPC reachable.",
+        recoverable: false,
+        userAction: `Check the effective INFURA_PROJECT_ID from the environment, .metamaskprodrc, or ${shellQuote(path.join(target, ".metamaskrc"))}, then rerun: mm-harness launch --verify --target ${shellQuote(target)}`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    return void 0;
+  },
+  async beforeHeal(launch, attempt, state) {
+    if (launch.tier !== "quick" || !extensionQuickReattachFailed(attempt.output)) return void 0;
+    const recoveryCode = "chrome.relaunched";
+    state.attemptedRecoveries.push(recoveryCode);
+    launch.stream.phase("recover");
+    const rebuildAttempt = await launch.compose("build");
+    if (rebuildAttempt.status === 0) {
+      state.recovered.push(recoveryCode);
+      return await launch.settle(state, rebuildAttempt.remoteFeatureFlags);
+    }
+    return launch.fail(state, {
+      code: "EXTENSION_RELAUNCH_FAILED",
+      message: "quick reattach failed, and clean relaunch failed too.",
+      recoverable: false,
+      exitCode: EXIT.infra,
+      originalError: rebuildAttempt.output.trim() || void 0
+    });
+  },
+  recovery: () => ({ code: RECOVERY_CODE.extension, restartApp: false }),
+  // --watch only restarts the webpack watcher; the snapshot, and its pin, are
+  // untouched, so the live record is reported rather than verified against a
+  // request the watcher could never apply (--remote-flag is refused with it;
+  // the fixture baseline stays whatever the last launch pinned).
+  provenFlags({ target, wantWatch, remoteFlagRequest }, requested) {
+    if (wantWatch) return { flags: readExtensionPinnedFlags(target).pinned };
+    const pinned = verifyExtensionPin(target, requested);
+    if (pinned.ok) return { flags: pinned.flags };
+    const spec = remoteFlagRequest?.spec;
+    return {
+      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
+    };
+  },
+  async finish(launch, state, sidepanelRecoveryAllowed) {
+    const { target, machine, displayMode, tier, stream } = launch;
+    const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
+    if (displayMode === "fullscreen") {
+      const sidepanelArgs = ["close"];
+      if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
+      const fullscreen = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
+      if (fullscreen.status !== 0) {
+        return launch.fail(state, {
+          code: "FULLSCREEN_OPEN_FAILED",
+          message: "app launched but restoring the fullscreen Extension surface failed.",
+          recoverable: false,
+          userAction: `bash adapters/extension/sidepanel-toggle.sh close --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
+          exitCode: EXIT.runtime,
+          originalError: fullscreen.output.trim() || void 0
+        });
+      }
+    }
+    if (displayMode === "sidepanel") {
+      const sidepanelArgs = ["open"];
+      if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
+      if (!machine) {
+        console.error(
+          `[sidepanel] opening panel beside ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}`
+        );
+      }
+      const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
+      if (sidepanel.status !== 0) {
+        const recoveryCode = "chrome.relaunched";
+        if (sidepanelRecoveryAllowed && tier === "quick" && extensionRuntimeBlocked(sidepanel.output) && !state.attemptedRecoveries.includes(recoveryCode)) {
+          state.attemptedRecoveries.push(recoveryCode);
+          stream.phase("recover");
+          const rebuildAttempt = await launch.compose("build");
+          if (rebuildAttempt.status === 0) {
+            state.recovered.push(recoveryCode);
+            return await launch.settle(state, void 0, false);
+          }
+          return launch.fail(state, {
+            code: "EXTENSION_RELAUNCH_FAILED",
+            message: "sidepanel open found a blocked extension runtime, and clean relaunch failed too.",
+            recoverable: false,
+            exitCode: EXIT.infra,
+            originalError: rebuildAttempt.output.trim() || void 0
+          });
+        }
+        return launch.fail(state, {
+          code: "SIDEPANEL_OPEN_FAILED",
+          message: "app launched but opening the side panel failed.",
+          recoverable: false,
+          userAction: `bash adapters/extension/sidepanel-toggle.sh open --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
+          exitCode: EXIT.runtime,
+          originalError: sidepanel.output.trim() || void 0
+        });
+      }
+    }
+    try {
+      await ensureExtensionConsoleCapture(target);
+    } catch (error) {
+      if (!machine) {
+        console.error(`WARN: Extension console capture unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return void 0;
+  },
+  verifyArgs: () => process.env.CDP_PORT ? ["--cdp-port", process.env.CDP_PORT] : [],
+  platformLabel: ({ mobileTarget, displayMode }) => mobileTarget ?? displayMode,
+  deviceLabel: ({ displayMode }) => displayMode
+};
+export {
+  extensionLaunchProfile
+};

package/dist/adapters/extension/launched-browser.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { isRecord } from "../../commands/parse-args.js";
+import { recipeRuntimeDir } from "../../paths.js";
+function readRecord(file) {
+  try {
+    const recorded = JSON.parse(fs.readFileSync(file, "utf8"));
+    return isRecord(recorded) ? recorded : null;
+  } catch {
+    return null;
+  }
+}
+const browserCdp = createRequire(import.meta.url)("../../../adapters/shared/browser-cdp.cjs");
+function verifyLaunch(record, cdpPort) {
+  const launch = isRecord(record.launch) ? record.launch : {};
+  const pid = Number(launch.pid);
+  const port = Number(launch.cdpPort);
+  if (!Number.isInteger(pid) || !Number.isInteger(port) || typeof launch.profile !== "string" || typeof launch.processStartedAt !== "string") {
+    return "the browser record has no process identity (pid, start time, profile, CDP port)";
+  }
+  if (cdpPort && port !== Number(cdpPort)) return `the browser record is for CDP port ${port}, not ${cdpPort}`;
+  try {
+    const owner = browserCdp.cdpOwner(port, launch.profile);
+    if (owner.pid !== pid || owner.startedAt !== launch.processStartedAt) {
+      return `CDP port ${port} is now held by another browser process than the recorded pid ${pid}`;
+    }
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  return null;
+}
+function launchedBrowser(target, artifactsDir, cdpPort) {
+  const runtime = readRecord(path.join(artifactsDir, "extension-runtime", "runtime.json"));
+  const autolaunched = runtime && isRecord(runtime.browser) ? runtime.browser : null;
+  const candidates = [];
+  if (autolaunched) candidates.push([autolaunched, "run-autolaunch"]);
+  const slot = readRecord(path.join(path.resolve(target), recipeRuntimeDir(), "browser-resolution.json"));
+  if (slot) candidates.push([slot, "slot-runtime"]);
+  if (candidates.length === 0) return null;
+  const reasons = [];
+  for (const [record, boundTo] of candidates) {
+    const problem = verifyLaunch(record, cdpPort);
+    if (problem === null) return { ...record, boundTo };
+    reasons.push(`${boundTo}: ${problem}`);
+  }
+  return { boundTo: "none", reason: reasons.join("; ") };
+}
+export {
+  launchedBrowser
+};

package/dist/adapters/extension/overlay.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import { readRuntimeContextField, resolveRuntimeContextPath } from "../../harness.js";
+import { resolveExtensionSlotPorts } from "../slot-ports.js";
+function hasArg(args, needle) {
+  return args.some((arg) => arg === needle || arg.startsWith(`${needle}=`));
+}
+function applyExtensionRuntimeEnv(target, args) {
+  const contextPath = resolveRuntimeContextPath(target);
+  const contextExists = fs.existsSync(contextPath);
+  if (contextExists) {
+    process.env.RECIPE_RUNTIME_CONTEXT = contextPath;
+    if (!process.env.RECIPE_SLOT_ID) {
+      const slotId = readRuntimeContextField(contextPath, "slotId");
+      if (slotId) process.env.RECIPE_SLOT_ID = slotId;
+    }
+    if (!process.env.RECIPE_HARNESS_EXTENSION_ID) {
+      const extensionId = readRuntimeContextField(contextPath, "extensionId");
+      if (extensionId) process.env.RECIPE_HARNESS_EXTENSION_ID = extensionId;
+    }
+  } else {
+    delete process.env.RECIPE_RUNTIME_CONTEXT;
+  }
+  resolveExtensionSlotPorts(target);
+  let result = [...args];
+  if (!hasArg(result, "--cdp-port")) {
+    const cdpPort = process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
+    if (cdpPort) {
+      process.env.RECIPE_CDP_PORT = cdpPort;
+      process.env.CDP_PORT = cdpPort;
+      result = [...result, "--cdp-port", cdpPort];
+    }
+  }
+  return result;
+}
+const extensionHarness = {
+  install: { entry: "adapters/extension/inject.mjs", fallback: "scripts/inject-extension-harness.mjs", node: true },
+  cleanup: { entry: "adapters/extension/cleanup.mjs", fallback: "scripts/cleanup-extension-harness.mjs", node: true, fromInstalledRunner: true },
+  // Runner-owned typed code, not a shipped leaf: no installed overlay copy can shadow it.
+  verify: () => ({ inProcess: async () => (await import("./verify.js")).runExtensionVerify }),
+  verifyArgs: applyExtensionRuntimeEnv,
+  restart: "mm-harness launch"
+};
+const extensionRuntimeContext = {
+  forbiddenFields: ["metroPort", "simulator", "simulatorUdid", "adbSerial"],
+  localPorts: { cdp: 2e4, watcher: 3e4 },
+  resources: ({ existing, defaults, envPort }) => ({
+    cdpPort: envPort("RECIPE_CDP_PORT", "CDP_PORT") ?? existing.cdpPort ?? defaults.cdpPort
+  })
+};
+const extensionPrepare = {};
+export {
+  extensionHarness,
+  extensionPrepare,
+  extensionRuntimeContext
+};