@deeeed/metamask-harness 0.51.4 → 0.51.6

package/adapters/extension/lib/validation-process-ownership.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const { execFileSync } = require('node:child_process');
+const { execFileSync, spawnSync } = require('node:child_process');
 
 function commandHasExactProfile(command, profile) {
   const expected = `--user-data-dir=${profile}`;
@@ -43,6 +43,61 @@ function delay(milliseconds) {
   return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
+// A process that already exited but has not been reaped yet (zombie) still
+// answers `kill(pid, 0)`. The synchronous stop loop below never yields to the
+// event loop, so a spawned child that dies immediately stays a zombie until the
+// launcher returns; it must not count as a surviving browser.
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    throw error;
+  }
+  const state = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).stdout.trim();
+  return state !== '' && !state.startsWith('Z');
+}
+
+function uniquePids(pids) {
+  return [...new Set(pids)].filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== process.pid);
+}
+
+// Reap every live process that still owns this profile, then refuse to continue
+// if any survive. `open -n` otherwise starts a second headed Chrome on the same
+// user-data-dir while the previous instance is still dying.
+function stopProfileProcessesSync(profile, { extraPids = [], timeoutMs = 5_000, waitForAppearanceMs = 0 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  const appearUntil = Date.now() + Math.max(0, waitForAppearanceMs);
+  let ownersSince = 0;
+  while (Date.now() < deadline) {
+    const pids = uniquePids([
+      ...profileProcessPids(profile),
+      ...extraPids.filter(pidAlive),
+    ]);
+    if (pids.length === 0) {
+      if (Date.now() >= appearUntil) return;
+    } else {
+      if (ownersSince === 0) ownersSince = Date.now();
+      signalPids(pids, Date.now() - ownersSince >= 500 ? 'SIGKILL' : 'SIGTERM');
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+  }
+  const remaining = uniquePids([
+    ...profileProcessPids(profile),
+    ...extraPids.filter(pidAlive),
+  ]);
+  if (remaining.length > 0) {
+    throw new Error(
+      `Owned Chrome processes survived stop (pid ${remaining.join(', ')}). ` +
+        'Next: mm-harness stop --adapter extension --target <checkout>',
+    );
+  }
+}
+
 async function stopProfileProcesses(profile, { quietMs = 0, timeoutMs = 5_000 } = {}) {
   const deadline = Date.now() + timeoutMs;
   let quietSince = Date.now();
@@ -66,4 +121,4 @@ async function stopProfileProcesses(profile, { quietMs = 0, timeoutMs = 5_000 }
   throw new Error(`Extension validation profile did not remain quiescent for ${quietMs}ms.`);
 }
 
-module.exports = { profileProcessPids, stopProfileProcesses };
+module.exports = { profileProcessPids, stopProfileProcesses, stopProfileProcessesSync };

package/adapters/extension/live.sh

@@ -228,7 +228,6 @@ NODE
   quoted_check_infura="$(printf '%q' "$SCRIPT_DIR/check-infura-readiness.cjs")"
   quoted_stamp_title="$(printf '%q' "$SCRIPT_DIR/stamp-runtime-title.cjs")"
   quoted_chrome_launcher="$(printf '%q' "$SCRIPT_DIR/launch-browser.cjs")"
-  quoted_build_handoff="$(printf '%q' "$SCRIPT_DIR/build-handoff.cjs")"
   quoted_artifact_state="$(printf '%q' "$SCRIPT_DIR/artifact-runtime-state.cjs")"
   quoted_fixture_state="$(printf '%q' "$FIXTURE_STATE_ABS")"
   quoted_fixture_validation="$(printf '%q' "$FIXTURE_VALIDATION_ABS")"
@@ -353,7 +352,6 @@ NODE
   fi
   prepare_parts+=("$chrome_launch_cmd")
   prepare_parts+=("for i in {1..60}; do curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null 2>&1 && break; sleep 1; done; curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null")
-  prepare_parts+=("node ${quoted_build_handoff} --target ${quoted_target} --runtime-dist ${quoted_runtime_dist} --cdp-port ${CDP_PORT}")
   if [ -n "$WALLET_FIXTURE_ABS" ]; then
     prepare_parts+=("bash ${quoted_seed_fixture} seed-cdp --target ${quoted_target} --fixture ${quoted_wallet_fixture} --state ${quoted_fixture_state} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --extension-id-file ${quoted_extension_id_file} --out ${quoted_fixture_validation}")
   fi

package/adapters/extension/stop-viewers.sh

@@ -29,7 +29,6 @@ done
 unset _tv_src
 
 runtime_dir="$TARGET/$(recipe_runtime_dir)"
-console_log="$runtime_dir/extension-console.log"
 set +e
 
 if command -v tmux_viewer_close_marker >/dev/null 2>&1; then
@@ -48,7 +47,7 @@ ps -axo pid=,command= 2>/dev/null | while read -r pid command; do
     *) continue ;;
   esac
   case "$command" in
-    *"--log $console_log"*|*"$console_log"*) kill "$pid" 2>/dev/null || true ;;
+    *"$runtime_dir/"*) kill "$pid" 2>/dev/null || true ;;
   esac
 done
 

package/dist/adapters/extension/validation-process-ownership.js

@@ -3,8 +3,9 @@ const require2 = createRequire(import.meta.url);
 const processOwnership = require2(
   "../../../adapters/extension/lib/validation-process-ownership.cjs"
 );
-const { profileProcessPids, stopProfileProcesses } = processOwnership;
+const { profileProcessPids, stopProfileProcesses, stopProfileProcessesSync } = processOwnership;
 export {
   profileProcessPids,
-  stopProfileProcesses
+  stopProfileProcesses,
+  stopProfileProcessesSync
 };

package/dist/adapters/slot-ports.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { recipeRuntimeDir } from "../paths.js";
 import {
@@ -131,11 +132,60 @@ function stopExtensionWatcher(target) {
   }
   return ownedPids.length;
 }
+function commandFlagMatches(command, flag, value, mode) {
+  if (!path.isAbsolute(value)) return false;
+  const escapedFlag = escapeRegex(flag);
+  const escapedValue = escapeRegex(value);
+  const unquotedEnd = mode === "exact" ? "(?=\\s|$)" : "([^\\s]*)";
+  const quotedEnd = (quote) => mode === "exact" ? quote : `([^${quote}]*)`;
+  const patterns = [
+    new RegExp(`(?:^|\\s)${escapedFlag}=${escapedValue}${unquotedEnd}`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}="${escapedValue}${quotedEnd('"')}`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}='${escapedValue}${quotedEnd("'")}`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}\\s+${escapedValue}${unquotedEnd}`, "u")
+  ];
+  for (const pattern of patterns) {
+    const match = pattern.exec(command);
+    if (!match) continue;
+    if (mode === "exact") return true;
+    const tail = match[1] ?? "";
+    if (!tail.split(/[\\/]/u).some((segment) => segment === "." || segment === "..")) return true;
+  }
+  return false;
+}
+function pathIsInsideDir(candidate, root) {
+  const resolved = path.resolve(candidate);
+  const base = path.resolve(root);
+  return resolved === base || resolved.startsWith(`${base}${path.sep}`);
+}
+function chromeUserDataDirOwnedByCheckout(command, runtimeAbs) {
+  return commandFlagMatches(command, "--user-data-dir", `${path.resolve(runtimeAbs)}${path.sep}`, "prefix");
+}
+function chromeUserDataDirIs(command, profileAbs) {
+  return commandFlagMatches(command, "--user-data-dir", path.resolve(profileAbs), "exact");
+}
+function commandLoadsCheckoutExtension(command, targetAbs) {
+  const prefix = `${path.resolve(targetAbs)}${path.sep}`;
+  return commandFlagMatches(command, "--load-extension", prefix, "prefix") || commandFlagMatches(command, "--disable-extensions-except", prefix, "prefix");
+}
+function isSharedOrDefaultBrowserProfile(profile) {
+  const resolved = path.resolve(profile);
+  const home = os.homedir();
+  const osDefaults = [
+    path.join(home, "Library/Application Support/Google/Chrome"),
+    path.join(home, "Library/Application Support/Chromium"),
+    path.join(home, "Library/Application Support/Microsoft Edge"),
+    path.join(home, ".config/google-chrome"),
+    path.join(home, ".config/chromium"),
+    path.join(home, ".config/microsoft-edge")
+  ];
+  const underDefault = (dir) => resolved === dir || resolved.startsWith(`${dir}${path.sep}`);
+  return resolved === home || resolved.includes(`${path.sep}.chrome-farmslot`) || osDefaults.some(underDefault);
+}
 function stopExtensionRuntime(target) {
   const resolved = path.resolve(target);
   const runtimeAbs = path.join(resolved, recipeRuntimeDir());
-  const configuredProfile = process.env.CHROME_USER_DATA_DIR || path.join(runtimeAbs, process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile");
-  const profiles = process.env.CHROME_USER_DATA_DIR ? [path.resolve(configuredProfile)] : [configuredProfile, path.join(runtimeAbs, "chrome-profile-recipe"), path.join(runtimeAbs, "chrome-profile-pw")].map((value) => path.resolve(value));
+  const extraProfile = process.env.CHROME_USER_DATA_DIR ? path.resolve(process.env.CHROME_USER_DATA_DIR) : null;
   let signalled = stopExtensionWatcher(resolved);
   const ownedBrowserPids = /* @__PURE__ */ new Set();
   try {
@@ -144,7 +194,15 @@ function stopExtensionRuntime(target) {
       const match = /^\s*(\d+)\s+(.*)$/u.exec(line);
       if (!match) continue;
       const pid = Number(match[1]);
-      if (pid !== process.pid && profiles.some((profile) => commandHasExactArg(match[2], "--user-data-dir", profile))) ownedBrowserPids.add(pid);
+      if (pid === process.pid) continue;
+      if (chromeUserDataDirOwnedByCheckout(match[2], runtimeAbs)) {
+        ownedBrowserPids.add(pid);
+        continue;
+      }
+      if (!extraProfile || pathIsInsideDir(extraProfile, runtimeAbs) || isSharedOrDefaultBrowserProfile(extraProfile)) continue;
+      if (chromeUserDataDirIs(match[2], extraProfile) && commandLoadsCheckoutExtension(match[2], resolved)) {
+        ownedBrowserPids.add(pid);
+      }
     }
   } catch {
   }
@@ -203,22 +261,16 @@ function processAlive(pid) {
     return error.code === "EPERM";
   }
 }
-function commandHasExactArg(command, flag, value) {
-  const escapedFlag = escapeRegex(flag);
-  const escapedValue = escapeRegex(value);
-  return [
-    new RegExp(`(?:^|\\s)${escapedFlag}=${escapedValue}(?=\\s|$)`, "u"),
-    new RegExp(`(?:^|\\s)${escapedFlag}="${escapedValue}"(?=\\s|$)`, "u"),
-    new RegExp(`(?:^|\\s)${escapedFlag}='${escapedValue}'(?=\\s|$)`, "u"),
-    new RegExp(`(?:^|\\s)${escapedFlag}\\s+${escapedValue}(?=\\s|$)`, "u")
-  ].some((pattern) => pattern.test(command));
-}
 function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 export {
   applyKVLines,
+  chromeUserDataDirIs,
+  chromeUserDataDirOwnedByCheckout,
   isExtensionWatcherLive,
+  isSharedOrDefaultBrowserProfile,
+  pathIsInsideDir,
   resolveExtensionSlotPorts,
   resolveMobileSlotPorts,
   stopExtensionRuntime,

package/dist/cli-commands.js

@@ -8,7 +8,10 @@ const SPEC = {
     { name: "help", aliases: ["-h", "--help"], desc: "Show usage" }
   ],
   shared: [
-    { name: "help", desc: "Load version-matched recipe guidance", flags: ["--json", "--adapter", "--target"] },
+    { name: "help", desc: "Load version-matched recipe guidance (help review composes the review guide)", args: ["review"], flags: ["--json", "--adapter", "--target", "--domain"] },
+    { name: "review", desc: "Materialize a review checklist composed from the base review and a team library", args: ["checklist"], flags: ["--domain", "--since", "--base", "--out", "--adapter", "--target", "--json"] },
+    { name: "domain", desc: "Which team library owns the change (declared value, else owned-paths.json)", flags: ["--domain", "--base", "--adapter", "--target", "--json"] },
+    { name: "config", desc: "Per-engineer locations: libraries.<name>, references.<adapter>", args: ["list", "path", "get", "set", "unset"], flags: ["--json"] },
     { name: "tutorial", desc: "Open the visual recipe tutorial", flags: ["--json", "--no-open"] },
     { name: "setup-base", desc: "Bootstrap numbered product checkouts", flags: ["--dir", "--counts", "--only", "--dry-run", "--force", "--json", "--show-config", "--reset-config", "--skip-harness-update"] },
     { name: "status", aliases: ["health", "home"], desc: "Home status + next commands", flags: ["--json", "--fast"] },

package/dist/cli.js

@@ -25,6 +25,9 @@ import { handleExecutionTemplate } from "./commands/execution-template.js";
 import { handlePrepare } from "./commands/prepare.js";
 import { handleTaskInit } from "./commands/task-init.js";
 import { handleLast } from "./commands/last.js";
+import { handleReview } from "./commands/review.js";
+import { handleDomain } from "./commands/domain.js";
+import { handleConfig } from "./commands/config.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
 const COMMANDS = {
   actions: handleActions,
@@ -132,6 +135,9 @@ async function main(argv) {
   if (command === "task") return handleTaskInit(argv.slice(1));
   if (command === "prepare") return handlePrepare(argv.slice(1));
   if (command === "last") return handleLast(parseArgs(argv.slice(1), command));
+  if (command === "review") return handleReview(argv.slice(1));
+  if (command === "domain") return handleDomain(argv.slice(1));
+  if (command === "config") return handleConfig(argv.slice(1));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);
   return handler(parseArgs(argv.slice(1), command));

package/dist/command-contract.js

@@ -58,7 +58,32 @@ const REMOVED_OPTION_REPLACEMENTS = {
 };
 const PUBLIC_COMMAND_CONTRACTS = {
   help: {
-    options: options(HELP, JSON, TARGET, ADAPTER)
+    options: options(HELP, JSON, TARGET, ADAPTER, { "--domain": value() }),
+    positionals: [{ label: "topic", choices: ["review"] }]
+  },
+  review: {
+    options: options(HELP, JSON, TARGET, ADAPTER, {
+      "--domain": value(),
+      "--since": value(),
+      "--base": value(),
+      "--out": value()
+    }),
+    positionals: [{ label: "action", choices: ["checklist"] }],
+    minimumPositionals: 1
+  },
+  domain: {
+    options: options(HELP, JSON, TARGET, ADAPTER, {
+      "--domain": value(),
+      "--base": value()
+    })
+  },
+  config: {
+    options: options(HELP, JSON),
+    positionals: [
+      { label: "action", choices: ["list", "path", "get", "set", "unset"] },
+      { label: "key" },
+      { label: "value" }
+    ]
   },
   tutorial: {
     options: options(HELP, JSON, NO_OPEN)

package/dist/commands/config.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import {
+  configPath,
+  readConfig,
+  REVIEW_ADAPTERS,
+  writeConfig
+} from "../review/knowledge.js";
+import { optionFlag, parseArgs, usageError } from "./parse-args.js";
+const USAGE = "Usage: mm-harness config <list|path|get <key>|set <key> <path>|unset <key>> [--json]\n  keys: libraries.<name>, references.<mobile|extension|core>";
+function parseKey(raw) {
+  if (!raw) throw usageError(USAGE);
+  const dot = raw.indexOf(".");
+  const section = dot === -1 ? raw : raw.slice(0, dot);
+  const name = dot === -1 ? "" : raw.slice(dot + 1);
+  if (!name) throw usageError(`Config key must be libraries.<name> or references.<adapter> (got ${raw}).`);
+  if (section === "libraries") return { section, name };
+  if (section === "references") {
+    if (!REVIEW_ADAPTERS.includes(name)) {
+      throw usageError(`references.<adapter> must be one of ${REVIEW_ADAPTERS.join(", ")} (got ${name}).`);
+    }
+    return { section, name };
+  }
+  throw usageError(`Config key must start with libraries. or references. (got ${raw}).`);
+}
+function getValue(config, key) {
+  return key.section === "libraries" ? config.libraries?.[key.name] : config.references?.[key.name];
+}
+function setValue(config, key, value) {
+  const section = config[key.section] ?? {};
+  if (value === void 0) delete section[key.name];
+  else section[key.name] = value;
+  if (Object.keys(section).length === 0) delete config[key.section];
+  else config[key.section] = section;
+}
+async function handleConfig(argv) {
+  const parsed = parseArgs(argv, "config");
+  const json = optionFlag(parsed.options, "json");
+  const [action, rawKey, rawValue] = parsed.positional;
+  const expectedPositionals = { path: 1, list: 1, get: 2, set: 3, unset: 2 }[action ?? "list"];
+  if (expectedPositionals !== void 0 && parsed.positional.length > expectedPositionals) {
+    throw usageError(`Unexpected argument "${parsed.positional[expectedPositionals]}". ${USAGE}`);
+  }
+  const file = configPath();
+  const config = readConfig(file);
+  if (action === "path") {
+    process.stdout.write(json ? `${JSON.stringify({ command: "config", path: file })}
+` : `${file}
+`);
+    return 0;
+  }
+  if (action === "list" || action === void 0) {
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ command: "config", path: file, ...config }, null, 2)}
+`);
+      return 0;
+    }
+    const lines = [
+      ...Object.entries(config.libraries ?? {}).map(([name, root]) => `libraries.${name}=${root}`),
+      ...Object.entries(config.references ?? {}).map(([name, root]) => `references.${name}=${root}`)
+    ];
+    process.stdout.write(lines.length > 0 ? `${lines.join("\n")}
+` : `(empty) ${file}
+`);
+    return 0;
+  }
+  if (action === "get") {
+    const value = getValue(config, parseKey(rawKey));
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ command: "config", key: rawKey, value: value ?? null })}
+`);
+      return 0;
+    }
+    if (value === void 0) return 1;
+    process.stdout.write(`${value}
+`);
+    return 0;
+  }
+  if (action === "set") {
+    const key = parseKey(rawKey);
+    if (!rawValue) throw usageError(`mm-harness config set ${rawKey} <path>`);
+    setValue(config, key, path.resolve(rawValue));
+    writeConfig(file, config);
+    process.stdout.write(json ? `${JSON.stringify({ command: "config", key: rawKey, value: path.resolve(rawValue), path: file })}
+` : `${rawKey}=${path.resolve(rawValue)}
+`);
+    return 0;
+  }
+  if (action === "unset") {
+    setValue(config, parseKey(rawKey), void 0);
+    writeConfig(file, config);
+    process.stdout.write(json ? `${JSON.stringify({ command: "config", key: rawKey, value: null, path: file })}
+` : `${rawKey} removed
+`);
+    return 0;
+  }
+  throw usageError(USAGE);
+}
+export {
+  handleConfig
+};

package/dist/commands/domain.js

@@ -0,0 +1,56 @@
+import {
+  changedFiles,
+  classifyDomain,
+  configPath,
+  discoverLibraries,
+  readConfig
+} from "../review/knowledge.js";
+import { optionFlag, optionString, parseArgs, targetPath, usageError } from "./parse-args.js";
+import { adapterFromOptions } from "./review.js";
+async function handleDomain(argv) {
+  const parsed = parseArgs(argv, "domain");
+  const target = targetPath(parsed.options);
+  const json = optionFlag(parsed.options, "json");
+  const declared = optionString(parsed.options, "domain") ?? process.env.MM_HARNESS_DOMAIN;
+  const detected = adapterFromOptions(parsed.options, target);
+  const adapter = detected === "unscoped" ? void 0 : detected;
+  if (declared) {
+    emit(json, { domain: declared, source: "declared", adapter: adapter ?? null, target });
+    return 0;
+  }
+  if (!adapter) {
+    throw usageError("No MetaMask checkout detected: pass --adapter <mobile|extension|core> or --domain <name>.");
+  }
+  const config = readConfig(configPath());
+  const libraries = discoverLibraries({ target, config });
+  const { base, files } = changedFiles(target, optionString(parsed.options, "base"));
+  const matches = classifyDomain(files, adapter, libraries);
+  const best = matches[0];
+  emit(json, {
+    domain: best?.domain ?? null,
+    source: best ? "owned-paths" : "none",
+    adapter,
+    target,
+    base,
+    changedFiles: files.length,
+    libraries: libraries.map((library) => ({ name: library.name, root: library.root, source: library.source, revision: library.revision ?? null })),
+    matches: matches.map((match) => ({ domain: match.domain, library: match.library.root, matched: match.matched }))
+  });
+  return 0;
+}
+function emit(json, payload) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ command: "domain", ...payload }, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${payload.domain ?? "none"}
+`);
+  const best = payload.matches?.[0];
+  const detail = payload.source === "declared" ? "declared via --domain or MM_HARNESS_DOMAIN" : best ? `owned-paths match in ${best.library} (${best.matched.length} of ${payload.changedFiles} changed files)` : `no library owns the ${payload.changedFiles} changed files (base ${payload.base}; libraries scanned: ${payload.libraries?.length ?? 0})`;
+  process.stderr.write(`domain: ${detail}
+`);
+}
+export {
+  handleDomain
+};

package/dist/commands/help.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { color } from "../cli-color.js";
 import { detectAdapter } from "../harness.js";
 import { optionString, parseArgs, targetPath } from "./parse-args.js";
+import { handleHelpReview } from "./review.js";
 const UNSCOPED_NEXT = "cd into a MetaMask checkout or pass --adapter <mobile|extension|core>";
 function validHelpLine(value) {
   return typeof value === "string" || Boolean(value && typeof value.text === "string" && Array.isArray(value.adapters) && value.adapters.length > 0 && value.adapters.every((adapter) => ["mobile", "extension", "core"].includes(adapter)));
@@ -70,6 +71,7 @@ function renderRecipeHelp(topic, harnessVersion, adapter) {
 }
 function handleHelp(argv, context) {
   const parsed = parseArgs(argv, "help");
+  if (parsed.positional[0] === "review") return handleHelpReview(argv, context.harnessVersion);
   const target = targetPath(parsed.options);
   const adapter = optionString(parsed.options, "adapter") ?? detectAdapter(target) ?? "unscoped";
   const topic = loadRecipeHelp(context.packageRoot);

package/dist/commands/launch/index.js

@@ -422,6 +422,10 @@ async function handleLaunchLocked(argv, stream) {
   state.attemptedRecoveries.push(recoveryCode);
   stream.phase("recover");
   const recoveryTier = restartMobileApp && tier === "build" ? "quick" : tier;
+  if (!jsonOutput) {
+    process.stderr.write(`launch: recovering (${recoveryCode}) with the ${recoveryTier} tier
+`);
+  }
   attempt = await executeComposition(
     adapter,
     mobileTarget,
@@ -469,7 +473,7 @@ function ambiguousConfiguredIosSimulator(output) {
   return /open-device: iOS simulator target ("[^"]+") is ambiguous/u.exec(output)?.[1];
 }
 function mobileBridgeTargetMissing(output) {
-  return /no bridge target matched/iu.test(output);
+  return /no bridge target matched|wait-for-bridge: readiness deadline expired/iu.test(output);
 }
 function mobileProvisionCommand(target, mobileTarget) {
   const platform = mobileTarget === "android" ? "android" : "ios";

package/dist/commands/review.js

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import path from "node:path";
+import { detectAdapter } from "../harness.js";
+import { runnerDir } from "../paths.js";
+import {
+  configPath,
+  loadDomainKnowledge,
+  parityAdapter,
+  readConfig,
+  referenceHint,
+  renderReviewChecklist,
+  renderReviewHelp,
+  resolveLibrary,
+  resolveReference,
+  defaultBaseRef
+} from "../review/knowledge.js";
+import { optionFlag, optionString, parseArgs, targetPath, usageError } from "./parse-args.js";
+const EXIT_OK = 0;
+let cachedHarnessVersion;
+function harnessVersion() {
+  if (cachedHarnessVersion === void 0) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(runnerDir, "package.json"), "utf8"));
+    cachedHarnessVersion = pkg.version ?? "unknown";
+  }
+  return cachedHarnessVersion;
+}
+function adapterFromOptions(options, target) {
+  const raw = optionString(options, "adapter") ?? optionString(options, "platform");
+  if (raw !== void 0) {
+    if (raw !== "mobile" && raw !== "extension" && raw !== "core") throw usageError(`--adapter must be mobile, extension, or core (got ${raw}).`);
+    return raw;
+  }
+  return detectAdapter(target) ?? "unscoped";
+}
+function resolveReviewContext(options, { fetch = true } = {}) {
+  const target = targetPath(options);
+  const adapter = adapterFromOptions(options, target);
+  const domain = optionString(options, "domain") ?? process.env.MM_HARNESS_DOMAIN;
+  const config = readConfig(configPath());
+  const context = { target, adapter, ...domain ? { domain } : {} };
+  if (domain) {
+    const library = resolveLibrary(domain, { target, config, fetch });
+    if (library) context.knowledge = loadDomainKnowledge(library, adapter === "unscoped" ? void 0 : adapter);
+    else if (fetch) throw usageError(`No library found for domain "${domain}". Set RECIPE_LIBRARY_PATH="${domain}=<path>" or run: mm-harness config set libraries.${domain} <path>`);
+  }
+  const parity = parityAdapter(adapter);
+  if (parity) {
+    const reference = resolveReference(parity, { target, config });
+    if (reference) context.reference = reference;
+    else context.referenceMissing = `no ${parity} checkout found (${referenceHint(parity)})`;
+  }
+  return context;
+}
+function handleHelpReview(argv, harnessVersion2) {
+  const parsed = parseArgs(argv, "help");
+  const context = resolveReviewContext(parsed.options, { fetch: false });
+  const input = {
+    adapter: context.adapter,
+    harnessVersion: harnessVersion2,
+    ...context.domain ? { domain: context.domain } : {},
+    ...context.knowledge ? { knowledge: context.knowledge } : {},
+    ...context.reference ? { reference: context.reference } : {},
+    ...context.referenceMissing ? { referenceMissing: context.referenceMissing } : {}
+  };
+  if (optionFlag(parsed.options, "json")) {
+    process.stdout.write(`${JSON.stringify({ command: "help", topic: "review", ...input }, null, 2)}
+`);
+  } else {
+    process.stdout.write(renderReviewHelp(input));
+  }
+  return EXIT_OK;
+}
+async function handleReview(argv, version = harnessVersion()) {
+  const parsed = parseArgs(argv, "review");
+  const subcommand = parsed.positional[0];
+  if (subcommand !== "checklist") {
+    throw usageError("Usage: mm-harness review checklist [--domain <name>] [--since <sha>] [--base <ref>] [--out <file>] [--json]");
+  }
+  const context = resolveReviewContext(parsed.options);
+  const since = optionString(parsed.options, "since");
+  const base = optionString(parsed.options, "base") ?? defaultBaseRef(context.target);
+  const checklist = renderReviewChecklist({
+    adapter: context.adapter,
+    target: context.target,
+    base,
+    harnessVersion: version,
+    ...since ? { since } : {},
+    ...context.domain ? { domain: context.domain } : {},
+    ...context.knowledge ? { knowledge: context.knowledge } : {},
+    ...context.reference ? { reference: context.reference } : {},
+    ...context.referenceMissing ? { referenceMissing: context.referenceMissing } : {}
+  });
+  const out = optionString(parsed.options, "out");
+  if (out) {
+    const file = path.resolve(out);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, checklist);
+  }
+  if (optionFlag(parsed.options, "json")) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          command: "review",
+          subcommand: "checklist",
+          target: context.target,
+          adapter: context.adapter,
+          domain: context.domain ?? null,
+          library: context.knowledge?.library ?? null,
+          reference: context.reference ?? null,
+          referenceMissing: context.referenceMissing ?? null,
+          base,
+          since: since ?? null,
+          out: out ? path.resolve(out) : null,
+          checklist
+        },
+        null,
+        2
+      )}
+`
+    );
+  } else if (out) {
+    process.stdout.write(`review checklist: ${path.resolve(out)}
+`);
+  } else {
+    process.stdout.write(checklist);
+  }
+  return EXIT_OK;
+}
+export {
+  adapterFromOptions,
+  handleHelpReview,
+  handleReview,
+  harnessVersion,
+  resolveReviewContext
+};