@deeeed/metamask-harness 0.5.0 → 0.6.0

package/src/cli.ts

@@ -1,2091 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import { mkdtemp } from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-
-import { color } from './cli-color.ts';
-import { createDoctorReport, renderRuntimeContext } from './doctor.ts';
-import {
-  invalidateCompletionCache,
-  readFreshCandidates,
-  writeCompletionCandidates,
-} from './completions-cache.ts';
-import { detectAdapter, handleHarness } from './harness.ts';
-import { handleLaunch } from './commands/launch.ts';
-import { handleLogs } from './commands/logs.ts';
-import { handleDebug } from './commands/debug.ts';
-import { handleFixtures } from './commands/fixtures.ts';
-import {
-  ensureOverlay,
-  newHealState,
-  parseHeal,
-  recipeRunning,
-  checkHealBounds,
-} from './heal-bounds.ts';
-import type { HealPolicy, HealState, HealBoundViolation } from './heal-bounds.ts';
-import { ensureExtensionReady } from './adapters/extension/ensure-ready.ts';
-import { resolveExtensionId } from './adapters/extension/extension-id.ts';
-import { decideExtensionReadiness } from './adapters/extension/runtime-decision.ts';
-import { decideMobileReadiness } from './adapters/mobile/runtime-decision.ts';
-import { getAdapterSurface } from './adapters/surface.ts';
-import type { AdapterRuntimeStatus } from './adapters/surface.ts';
-// NOTE: extension-runtime.ts loads the recipe harness at module scope, so it
-// is imported LAZILY (dynamic import) only inside the handlers that drive a live
-// runtime. Static-import it here and every command — manifest, doctor,
-// runtime-decision (no --cdp-port) — would fail to load on a checkout without
-// local harness packages built. Keep this lazy.
-import { loadActionManifest, validateManifest } from './manifest.ts';
-import {
-  assertAdapter,
-  importRecipeHarness,
-  importRecipeHarnessCli,
-  importRecipeProtocol,
-  manifestPath,
-  recipeHarnessPath,
-  recipePath,
-  runnerDir,
-  walletFixturePath,
-} from './paths.ts';
-import { captureHelperSupportsRecordSessionSnapshots } from './recording-target.ts';
-import { startRecipeRecording, stopRecipeRecording } from './run-recording.ts';
-// runner.ts → adapters.ts → library/actions/extension/platform/cdp.mjs does a
-// top-level harness import, so it is imported LAZILY inside
-// runRecipe only. Keeping it static would load the recipe harness for every
-// command (manifest, doctor, runtime-decision), defeating their independence.
-import type { RecipeRunResult } from '@farmslot/recipe-harness';
-import type {
-  RecipeActionManifestDocument,
-  RecipeValidationFinding,
-  RecipeValidationResult,
-} from '@farmslot/protocol';
-import type { MetaMaskRecipeAdapter } from './types.ts';
-import { ADAPTER_DETECT_NEXT, usageOut } from './commands/shared.ts';
-
-type CliOptionValue = string | boolean;
-type CliOptions = Record<string, CliOptionValue>;
-
-interface ParsedArgs {
-  positional: string[];
-  options: CliOptions;
-  rawArgv: string[];
-}
-
-interface RuntimeOptions {
-  cdpPort?: string;
-  watcherPort?: string;
-  launchExistingDist?: boolean;
-  startWatch?: boolean;
-  skipExtensionRuntimePrepare?: boolean;
-  slot?: string;
-  validationRuntimeDir?: string;
-  recordVideo?: false | 'full-run';
-  librarySources?: MetaMaskLibrarySource[];
-  // --json mode: stdout is the machine contract, so the engine logger (e.g. its
-  // "Recipe libraries: …" resolution line) must be kept off stdout.
-  stdoutIsMachineContract?: boolean;
-}
-
-interface MetaMaskLibrarySource {
-  name?: string;
-  root: string;
-}
-
-// The installed @farmslot/recipe-harness may predate recipe libraries; probe
-// for the API instead of assuming it so every other command keeps working.
-interface RecipeLibraryCapableHarness {
-  resolveRecipeLibrarySources?: (options?: {
-    cliEntries?: string[];
-  }) => Promise<MetaMaskLibrarySource[]>;
-}
-
-const COMMANDS: Record<string, (args: ParsedArgs) => Promise<number>> = {
-  manifest: handleManifest,
-  actions: handleActions,
-  doctor: handleDoctor,
-  'runtime-health': handleRuntimeHealth,
-  'runtime-decision': handleRuntimeDecision,
-  'runtime-launch': handleRuntimeLaunch,
-  provision: handleProvision,
-  'resolve-extension': handleResolveExtension,
-  'ensure-ready': handleEnsureReady,
-  run: handleRun,
-  'self-test': handleSelfTest,
-};
-
-// Top-level runtime-overlay commands (the tool installs a runtime overlay).
-// Top-level overlay commands route to handleHarness; the `harness <sub>`
-// subcommand form has been removed from the CLI surface.
-const OVERLAY_COMMANDS: readonly string[] = ['install', 'provision', 'verify', 'cleanup', 'live'];
-
-function usage() {
-  // Help is organized by the harness mental model: mm-harness IS the tool; a
-  // recipe is one thing it runs; the "runtime overlay" is what it installs into a
-  // checkout. End state = one bin (mm-harness); help presents only that surface.
-  // Every command ships one copy-pasteable example (cold-start discoverability;
-  // zero-flag happy path where possible).
-  console.error(`mm-harness — the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay.
-Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.
-Grammar: mm-harness <command> [target] [flags]   (target is a positional: ios | android | extension; flags add agent depth)
-
-DAILY LOOP — what a teammate runs many times a day:
-  launch     Launch the app incl. Metro/build, surface auto-detected. Mobile: ios|android required.
-               mm-harness launch ios                    # quick relaunch (add --build | --verify)
-  logs       Tail Metro/webpack + app logs.
-               mm-harness logs
-  debug      Open the debug console (extension DevTools / mobile RN).
-               mm-harness debug
-  fixtures   Sync fixture files + set up the wallet (SRP/password).
-               mm-harness fixtures sync                 # or: mm-harness fixtures set
-
-PROVE — run recipes and inspect capabilities:
-  run        Run a recipe and write evidence (summary/trace/artifacts).
-               mm-harness run recipe.json
-  flows      List/promote recipe library flows (personal/team win over canonical).
-               mm-harness flows list
-  doctor     Readiness check for a checkout (no app launch).
-               mm-harness doctor
-  actions    Describe the actions a manifest declares.
-               mm-harness actions --adapter mobile
-  manifest   Print/validate the action manifest for an adapter.
-               mm-harness manifest --adapter extension --json
-
-RUNTIME OVERLAY — install/verify/clean the per-checkout runtime overlay:
-  install    Install the runtime overlay into the checkout.
-               mm-harness install                      # inside a checkout, auto-detected
-  verify     Check the overlay/runtime is present and healthy (no launch).
-               mm-harness verify
-  live       Launch/reuse the app, then verify live control end-to-end.
-               mm-harness live
-  cleanup    Remove the installed overlay and restore the checkout.
-               mm-harness cleanup
-  # Open sub-question (Arthur): keep these top-level (mm-harness install) or group
-  # them under an \`overlay\` command (mm-harness overlay install)? Top-level for now.
-
-ADVANCED — internal runtime probes (rarely typed by hand):
-  runtime-health     runtime-decision   runtime-launch
-  resolve-extension  ensure-ready       self-test
-  (e.g. mm-harness runtime-decision --adapter extension --target <repo> --json)
-
-ONE bin: mm-harness is the only command. No per-platform binaries — platform is
-auto-detected, the positional target forces it (mm-harness launch ios), and
-platform-specific needs are FLAGS on the same command (e.g. --sidebar, --full-build).
-Human happy path = the bare command; agents add depth via flags (--json, --target, ports).
-See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).
-`);
-}
-
-function parseArgs(argv: string[], command?: string): ParsedArgs {
-  const positional: string[] = [];
-  const options: CliOptions = {};
-  const booleanOptions = new Set(['json', 'launchExistingDist', 'startWatch', 'record', 'plan', 'raw', 'fix', 'force', 'resolveOnly']);
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (!arg.startsWith('--')) {
-      positional.push(arg);
-      continue;
-    }
-    const body = arg.slice(2);
-    const equalsIndex = body.indexOf('=');
-    const rawKey = equalsIndex === -1 ? body : body.slice(0, equalsIndex);
-    const inlineValue = equalsIndex === -1 ? undefined : body.slice(equalsIndex + 1);
-    const key = normalizeOptionKey(rawKey);
-    if (key === 'recordVideo') {
-      options.recordVideo = parseRecordVideoMode(inlineValue);
-      continue;
-    }
-    if (key === 'recordBaseline') {
-      options.record = true;
-      continue;
-    }
-    if (key === 'record') {
-      if (command === 'runtime-decision') {
-        options.record = true;
-        continue;
-      }
-      options.recordVideo = 'full-run';
-      continue;
-    }
-    if (booleanOptions.has(key)) {
-      options[key] = true;
-      continue;
-    }
-    if (inlineValue !== undefined) {
-      options[key] = inlineValue;
-      continue;
-    }
-    if (i + 1 >= argv.length) throw usageError(`Missing value for ${arg}`);
-    options[key] = argv[i + 1];
-    i += 1;
-  }
-  return { positional, options, rawArgv: [...argv] };
-}
-
-function parseRecordVideoMode(value: string | undefined): false | 'full-run' {
-  if (value === undefined || value === '' || value === 'true') return 'full-run';
-  if (value === 'off' || value === 'false') return false;
-  if (value === 'proof-window' || value === 'proof_window') {
-    throw usageError(
-      '--record-video=proof-window is not supported yet; use --record-video=full-run.',
-    );
-  }
-  if (value !== 'full-run') {
-    throw usageError('--record-video must be full-run or off.');
-  }
-  return 'full-run';
-}
-
-function normalizeOptionKey(key: string): string {
-  return key.replace(/-([a-z])/gu, (_, character: string) => character.toUpperCase());
-}
-
-function optionString(options: CliOptions, key: string): string | undefined {
-  const value = options[key];
-  if (value === undefined) return undefined;
-  if (typeof value !== 'string') throw usageError(`--${key} requires a value.`);
-  return value;
-}
-
-function optionFlag(options: CliOptions, key: string): boolean {
-  const value = options[key];
-  return value === true;
-}
-
-
-function applyRuntimeDirOption(options: CliOptions): void {
-  const runtimeDir = optionString(options, 'runtimeDir');
-  if (runtimeDir) process.env.RECIPE_RUNTIME_DIR = runtimeDir;
-}
-
-function applyWatcherPortOption(options: CliOptions): void {
-  const watcherPort = optionString(options, 'watcherPort');
-  if (!watcherPort) return;
-  process.env.WATCHER_PORT = watcherPort;
-  process.env.RECIPE_WATCHER_PORT = watcherPort;
-  process.env.METRO_PORT = watcherPort;
-}
-
-function requiredOption(options: CliOptions, key: string, message: string): string {
-  const value = optionString(options, key);
-  if (!value) throw usageError(message);
-  return value;
-}
-
-function adapterOption(options: CliOptions): MetaMaskRecipeAdapter {
-  const adapter = optionString(options, 'adapter');
-  try {
-    assertAdapter(adapter);
-  } catch (error) {
-    throw usageError(error instanceof Error ? error.message : String(error));
-  }
-  return adapter;
-}
-
-function targetPath(options: CliOptions): string {
-  return path.resolve(optionString(options, 'target') ?? optionString(options, 'projectRoot') ?? process.cwd());
-}
-
-function actionManifestPathOption(options: CliOptions, adapter: MetaMaskRecipeAdapter): string {
-  const configured = optionString(options, 'actionManifest');
-  return configured ? path.resolve(configured) : manifestPath(adapter);
-}
-
-async function runRecipe(
-  adapter: MetaMaskRecipeAdapter,
-  recipe: string,
-  artifactsDir: string,
-  projectRoot: string,
-  actionManifestPath?: string,
-  runtimeOptions: RuntimeOptions = {},
-): Promise<RecipeRunResult> {
-  const previousCdpPort = process.env.CDP_PORT;
-  const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
-  const previousWatcherPort = process.env.WATCHER_PORT;
-  const previousMetroPort = process.env.METRO_PORT;
-  const previousExtensionAutolaunch = process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH;
-  if (runtimeOptions.cdpPort) {
-    process.env.CDP_PORT = runtimeOptions.cdpPort;
-    process.env.RECIPE_CDP_PORT = runtimeOptions.cdpPort;
-  }
-  if (runtimeOptions.watcherPort) {
-    process.env.WATCHER_PORT = runtimeOptions.watcherPort;
-    process.env.METRO_PORT = runtimeOptions.watcherPort;
-  }
-  if (runtimeOptions.launchExistingDist) {
-    process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH = '1';
-  }
-  try {
-    await prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions);
-    const absoluteArtifactsDir = path.resolve(artifactsDir);
-    const recordVideo = runtimeOptions.recordVideo ?? false;
-    const useFramedExtensionRecording =
-      adapter === 'extension' &&
-      recordVideo === 'full-run' &&
-      captureHelperSupportsRecordSessionSnapshots(projectRoot);
-    const recording = useFramedExtensionRecording
-      ? await startRecipeRecording(adapter, projectRoot, absoluteArtifactsDir, {
-          record: true,
-          cdpPort: runtimeOptions.cdpPort,
-        })
-      : undefined;
-    try {
-      const manifest = loadActionManifest(adapter, actionManifestPath);
-      await validateManifest(manifest);
-      const { createMetaMaskRunner } = await import('./runner.ts');
-      const runner = await createMetaMaskRunner(adapter, manifest, {
-        quietStdout: runtimeOptions.stdoutIsMachineContract === true,
-      });
-      // Intersection keeps this compiling against harness versions that
-      // predate recipe libraries; those ignore the extra key at runtime.
-      const runRequest: Parameters<typeof runner.run>[0] & {
-        librarySources?: MetaMaskLibrarySource[];
-      } = {
-        recipePath: path.resolve(recipe),
-        artifactsDir: absoluteArtifactsDir,
-        projectRoot,
-        env: recipeRunEnv(adapter, runtimeOptions),
-        recordVideo: useFramedExtensionRecording ? false : recordVideo,
-        ...(runtimeOptions.librarySources ? { librarySources: runtimeOptions.librarySources } : {}),
-      };
-      const result = await runner.run(runRequest);
-      await stopRecipeRecording(recording, result);
-      return result;
-    } finally {
-      await stopRecipeRecording(recording);
-    }
-  } finally {
-    restoreEnv('CDP_PORT', previousCdpPort);
-    restoreEnv('RECIPE_CDP_PORT', previousRecipeCdpPort);
-    restoreEnv('WATCHER_PORT', previousWatcherPort);
-    restoreEnv('METRO_PORT', previousMetroPort);
-    restoreEnv('METAMASK_RECIPE_EXTENSION_AUTOLAUNCH', previousExtensionAutolaunch);
-  }
-}
-
-function recipeRunEnv(
-  adapter: MetaMaskRecipeAdapter,
-  runtimeOptions: RuntimeOptions = {},
-): Record<string, string | undefined> {
-  const base: Record<string, string | undefined> = {
-    CDP_PORT: runtimeOptions.cdpPort ?? process.env.CDP_PORT,
-    RECIPE_CDP_PORT: runtimeOptions.cdpPort ?? process.env.RECIPE_CDP_PORT,
-    FARMSLOT_SLOT_ID: runtimeOptions.slot ?? process.env.FARMSLOT_SLOT_ID,
-    SLOT_ID: runtimeOptions.slot ?? process.env.SLOT_ID,
-    PLATFORM: process.env.PLATFORM,
-  };
-  if (adapter !== 'mobile') return base;
-  return {
-    ...base,
-    WATCHER_PORT: process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
-    METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
-    IOS_SIMULATOR: process.env.IOS_SIMULATOR,
-    ANDROID_DEVICE: process.env.ANDROID_DEVICE,
-    ADB_SERIAL: process.env.ADB_SERIAL,
-    ANDROID_SERIAL: process.env.ANDROID_SERIAL,
-  };
-}
-
-async function prepareRuntimeIfNeeded(
-  adapter: MetaMaskRecipeAdapter,
-  projectRoot: string,
-  runtimeOptions: RuntimeOptions,
-): Promise<void> {
-  if (adapter !== 'extension' || runtimeOptions.skipExtensionRuntimePrepare === true) return;
-  const { prepareExtensionRuntime } = await import('./adapters/extension/runtime.ts');
-  await prepareExtensionRuntime({
-    projectRoot,
-    cdpPort: runtimeOptions.cdpPort,
-    slot: runtimeOptions.slot,
-    launchExistingDist: runtimeOptions.launchExistingDist === true,
-    validationRuntimeDir: runtimeOptions.validationRuntimeDir,
-  });
-}
-
-function restoreEnv(key: string, value: string | undefined) {
-  if (value === undefined) delete process.env[key];
-  else process.env[key] = value;
-}
-
-async function runSelfTest(options: CliOptions) {
-  const root = optionString(options, 'artifactsDir')
-    ? path.resolve(requiredOption(options, 'artifactsDir', 'self-test artifacts dir missing.'))
-    : await mkdtemp(path.join(os.tmpdir(), 'mm-harness-runner-'));
-  const previousAutoHud = process.env.METAMASK_RECIPE_AUTO_HUD;
-  const runs = [];
-  try {
-    // Self-test is a package wiring check, not a live-device proof. Disable the
-    // automatic HUD and extension launch so it remains safe in fresh checkouts.
-    process.env.METAMASK_RECIPE_AUTO_HUD = '0';
-    for (const adapter of ['mobile', 'extension'] as const) {
-      const manifest = loadActionManifest(adapter);
-      const manifestValidation = await validateManifest(manifest);
-      const smokeRecipe = recipePath(
-        adapter === 'mobile' ? 'smoke.mobile.recipe.json' : 'smoke.extension.recipe.json',
-      );
-      const artifactsDir = path.join(root, adapter);
-      const result = await runRecipe(adapter, smokeRecipe, artifactsDir, runnerDir, undefined, {
-        skipExtensionRuntimePrepare: true,
-      });
-      runs.push({ adapter, manifestValidation: manifestValidation.summary, artifactsDir, result });
-    }
-  } finally {
-    restoreEnv('METAMASK_RECIPE_AUTO_HUD', previousAutoHud);
-  }
-  return {
-    status: runs.every((run) => run.result.status === 'pass') ? 'pass' : 'fail',
-    artifactsDir: root,
-    runs,
-  };
-}
-
-async function handleManifest({ options }: ParsedArgs): Promise<number> {
-  const { adapter } = resolveAdapter(options);
-  const actionManifestPath = actionManifestPathOption(options, adapter);
-  const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
-  await validateManifest(manifest);
-  if (optionFlag(options, 'json')) console.log(JSON.stringify(manifest, null, 2));
-  else console.log(actionManifestPath);
-  return 0;
-}
-
-async function handleActions({ options }: ParsedArgs): Promise<number> {
-  const { adapter } = resolveAdapter(options);
-  const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
-  await validateManifest(manifest);
-  const action = optionString(options, 'action');
-  const actions = describeManifestActions(manifest, action);
-  if (optionFlag(options, 'json')) {
-    console.log(JSON.stringify({ adapter, actions }, null, 2));
-  } else {
-    for (const entry of actions) {
-      const fields = entry.fields.length ? ` fields=${entry.fields.join(',')}` : '';
-      console.log(`${entry.name} (${entry.kind})${fields}${entry.description ? ` — ${entry.description}` : ''}`);
-    }
-  }
-  return 0;
-}
-
-async function handleDoctor({ options }: ParsedArgs): Promise<number> {
-  applyRuntimeDirOption(options);
-  const target = targetPath(options);
-  // Share the exact detect-from-target logic the overlay commands (verify/install/
-  // cleanup) use: when --adapter/--platform is omitted, auto-detect from the
-  // target (defaults to cwd) instead of hard-failing on a missing flag.
-  const json = optionFlag(options, 'json');
-  const explicitAdapter = optionString(options, 'adapter') ?? optionString(options, 'platform');
-  const adapter = explicitAdapter ?? detectAdapter(target);
-  if (!adapter) {
-    return usageOut(json, 'doctor', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
-  }
-  assertAdapter(adapter);
-  const actionManifestPath = actionManifestPathOption(options, adapter);
-  const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
-  const manifestValidation = await validateManifest(manifest);
-
-  // --fix runs the shared healing steps WITHOUT launching the app (overlay
-  // auto-ensure + the same bounds run/launch use; never a fixture reseed) and
-  // reports fixed[]/failed[]. Without --fix, doctor is pure read-only.
-  if (optionFlag(options, 'fix')) {
-    const { fixed, failed } = await runDoctorFix(adapter, target, manifestValidation, json);
-    // Re-read the report AFTER repairs so its checks reflect the healed state.
-    const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-    if (json) console.log(JSON.stringify({ ...result, fixed, failed }, null, 2));
-    else console.log(`${result.status} ${adapter} ${result.compatibilityMode} manifest=${actionManifestPath} fixed=[${fixed.join(',')}] failed=[${failed.join(',')}]`);
-    return failed.length === 0 ? 0 : 1;
-  }
-
-  const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-  // Live runtime state, per platform, via the adapter surface: every adapter
-  // reports the same read-only readiness shape (decision + reasons, deps currency,
-  // and its dev server where it has one) so doctor renders one line the same way
-  // for mobile, extension, and core. doctor never branches on adapter for this.
-  let runtime: AdapterRuntimeStatus | undefined;
-  try {
-    const surface = getAdapterSurface(adapter);
-    surface.resolveSlotPorts(target);
-    runtime = await surface.runtimeStatus(target);
-  } catch { /* readiness probe unavailable — doctor stays useful without it */ }
-  if (json) console.log(JSON.stringify({ ...result, runtime }, null, 2));
-  else {
-    const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
-    const stateStyle = (value: string | undefined, good: string) => (value === good ? 'ok' : 'warn');
-    console.log(`${out(result.status === 'pass' ? 'ok' : 'err', result.status)} ${out('bold', adapter)} ${result.compatibilityMode} ${out('dim', `manifest=${actionManifestPath}`)}`);
-    if (runtime) {
-      const provisionedDepsPending = runtime.reasonCode === 'app-installed-deps-pending';
-      const decisionStyle = provisionedDepsPending
-        ? 'info'
-        : runtime.decision === 'ready' ? 'ok' : runtime.decision === 'blocked' ? 'err' : 'warn';
-      const depsStyle = provisionedDepsPending ? 'info' : stateStyle(runtime.deps, 'current');
-      const devServerStyle = provisionedDepsPending ? 'info' : undefined;
-      const devServer = runtime.devServer
-        ? ` ${runtime.devServer.label}=${out(devServerStyle ?? stateStyle(runtime.devServer.status, 'up'), runtime.devServer.status)}`
-        : '';
-      console.log(
-        `${out('label', 'runtime:')} decision=${out(decisionStyle, runtime.decision)}${runtime.reasonCode ? ` ${out('dim', `(${runtime.reasonCode})`)}` : ''} deps=${out(depsStyle, runtime.deps ?? 'unknown')}${devServer}`,
-      );
-      for (const reason of runtime.reasons) console.log(`  ${out('dim', reason)}`);
-    }
-    console.log(renderRuntimeContext(result.runtimeContext));
-  }
-  return result.status === 'pass' ? 0 : 1;
-}
-
-// `doctor --fix` repair path: the shared self-healing internals with no app launch.
-// Auto-ensures the runtime overlay if missing (infra-only bound; core is headless
-// and no-ops); a manifest that fails validation is not overlay-healable and is
-// reported as failed. Healing NEVER touches fixtures. Returns the codes actually
-// repaired (fixed[]) and the ones it could not (failed[]).
-async function runDoctorFix(
-  adapter: MetaMaskRecipeAdapter,
-  target: string,
-  manifestValidation: RecipeValidationResult,
-  json: boolean,
-): Promise<{ fixed: string[]; failed: string[] }> {
-  const fixed: string[] = [];
-  const failed: string[] = [];
-
-  // Refuse to repair while a recipe is running — mid-run mutation corrupts state.
-  if (recipeRunning(target)) {
-    failed.push('recipe-running');
-    return { fixed, failed };
-  }
-
-  // Manifest validity is a read-only check: a broken manifest is not something the
-  // overlay install can heal, so surface it as a failed code rather than mutating.
-  if (Number(manifestValidation.summary?.errors ?? 0) > 0) failed.push('manifest');
-
-  // Overlay auto-ensure — the one positively-identified infra recovery available
-  // without a launch. ensureOverlay records a mutation only when it actually
-  // installs a missing overlay, so an already-present overlay is not reported.
-  const state = newHealState();
-  const ensured = await ensureOverlay(adapter, target, 'infra-only', state, json);
-  if (!ensured.ok) failed.push('overlay');
-  else if (state.mutations.length > 0) fixed.push('overlay');
-
-  return { fixed, failed };
-}
-
-function describeManifestActions(
-  manifest: unknown,
-  filterAction?: string,
-): Array<{
-  name: string;
-  kind: 'official' | 'custom';
-  description: string;
-  fields: string[];
-  schema?: unknown;
-  examples?: unknown;
-}> {
-  const manifestRecord = isRecord(manifest) ? manifest : {};
-  const metadata = isRecord(manifestRecord.action_metadata) ? manifestRecord.action_metadata : {};
-  const official = Array.isArray(manifestRecord.supported_official_actions)
-    ? manifestRecord.supported_official_actions.filter((value): value is string => typeof value === 'string')
-    : [];
-  const custom = Array.isArray(manifestRecord.custom_actions)
-    ? manifestRecord.custom_actions.flatMap((entry) => {
-        if (typeof entry === 'string') return [{ name: entry, metadata: metadata[entry] }];
-        if (isRecord(entry) && typeof entry.name === 'string') {
-          const entryMetadata = { ...entry };
-          const metadataOverride = metadata[entry.name];
-          if (isRecord(metadataOverride)) Object.assign(entryMetadata, metadataOverride);
-          return [{ name: entry.name, metadata: entryMetadata }];
-        }
-        return [];
-      })
-    : [];
-  const entries = [
-    ...official.map((name) => describeManifestAction(name, 'official' as const, metadata[name])),
-    ...custom.map((entry) => describeManifestAction(entry.name, 'custom' as const, entry.metadata)),
-  ].filter((entry) => !filterAction || entry.name === filterAction);
-  if (filterAction && entries.length === 0) throw new Error(`Action not found in manifest: ${filterAction}`);
-  return entries;
-}
-
-function describeManifestAction(
-  name: string,
-  kind: 'official' | 'custom',
-  metadata: unknown,
-): {
-  name: string;
-  kind: 'official' | 'custom';
-  description: string;
-  fields: string[];
-  schema?: unknown;
-  examples?: unknown;
-} {
-  const record = isRecord(metadata) ? metadata : {};
-  const schema = record.schema;
-  const schemaRecord = isRecord(schema) ? schema : {};
-  const properties = isRecord(schemaRecord.properties) ? Object.keys(schemaRecord.properties).sort() : [];
-  return {
-    name,
-    kind,
-    description: typeof record.description === 'string' ? record.description : '',
-    fields: properties,
-    schema,
-    examples: record.examples,
-  };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-async function handleProvision({ positional, options, rawArgv }: ParsedArgs): Promise<number> {
-  applyWatcherPortOption(options);
-  const json = optionFlag(options, 'json');
-  const { adapter, target } = resolveProvisionAdapter(options);
-  const surface = getAdapterSurface(adapter);
-  const rerunCommand = provisionRerunCommand(rawArgv, options, adapter, target);
-  const result = await surface.runwayProvision.run(target, {
-    json,
-    platform: optionString(options, 'platform') ?? optionString(options, 'devicePlatform') ?? (positional[0] === 'runway' ? positional[1] : positional[0]) ?? 'ios',
-    branch: optionString(options, 'branch'),
-    defaultBranch: optionString(options, 'defaultBranch'),
-    run: optionString(options, 'run'),
-    cacheRoot: optionString(options, 'cacheRoot'),
-    simulator: optionString(options, 'simulator') ?? optionString(options, 'device'),
-    runtime: optionString(options, 'runtime'),
-    deviceType: optionString(options, 'deviceType'),
-    slot: optionString(options, 'slot'),
-    watcherPort: optionString(options, 'watcherPort'),
-    runtimeDir: optionString(options, 'runtimeDir'),
-    force: optionFlag(options, 'force'),
-    resolveOnly: optionFlag(options, 'resolveOnly'),
-    rerunCommand,
-  });
-  if (json) {
-    console.log(JSON.stringify(result, null, 2));
-  } else if (result.status === 'pass') {
-    const cache = typeof result.cache === 'object' && result.cache ? result.cache as Record<string, unknown> : undefined;
-    const simulator = typeof result.simulator === 'object' && result.simulator ? result.simulator as Record<string, unknown> : undefined;
-    const artifact = typeof result.artifact === 'object' && result.artifact ? result.artifact as Record<string, unknown> : undefined;
-    if (result.resolveOnly) {
-      console.error(`✓ resolved ${adapter} ${result.platform ?? ''} run=${artifact?.runId ?? 'unknown'} revision=${artifact?.revision ?? 'unknown'} artifact=${artifact?.artifactName ?? 'unknown'}`);
-    } else {
-      const action = result.skipped ? 'already provisioned' : 'provisioned';
-      console.error(`✓ ${action} ${adapter} ${result.platform ?? ''} simulator=${simulator?.name ?? 'unknown'} cache=${cache?.status ?? 'unknown'}`);
-    }
-  } else {
-    console.error(`✗ mm-harness provision: ${result.error?.message ?? 'provision failed'}\n  Next: ${result.error?.userAction ?? rerunCommand}`);
-  }
-  return result.exitCode;
-}
-
-function resolveProvisionAdapter(options: CliOptions): { adapter: MetaMaskRecipeAdapter; target: string } {
-  const target = targetPath(options);
-  const adapter = optionString(options, 'adapter') ?? detectAdapter(target);
-  if (!adapter) {
-    throw usageError(`could not detect the MetaMask repo type for ${target}\n  Next: ${ADAPTER_DETECT_NEXT}`);
-  }
-  try {
-    assertAdapter(adapter);
-  } catch (error) {
-    throw usageError(error instanceof Error ? error.message : String(error));
-  }
-  return { adapter, target };
-}
-
-function provisionRerunCommand(rawArgv: string[], options: CliOptions, adapter: MetaMaskRecipeAdapter, target: string): string {
-  const parts = ['mm-harness', 'provision'];
-  for (const positional of provisionPositionals(rawArgv)) parts.push(shellQuoteArg(positional));
-  parts.push('--adapter', adapter, '--target', shellQuote(target));
-  const aliases: Array<[string, string[]]> = [
-    ['platform', ['--platform', '--device-platform']],
-    ['branch', ['--branch']],
-    ['defaultBranch', ['--default-branch']],
-    ['run', ['--run']],
-    ['cacheRoot', ['--cache-root']],
-    ['simulator', ['--simulator', '--device']],
-    ['runtime', ['--runtime']],
-    ['deviceType', ['--device-type']],
-    ['slot', ['--slot']],
-    ['watcherPort', ['--watcher-port']],
-    ['runtimeDir', ['--runtime-dir']],
-  ];
-  for (const [key, flags] of aliases) {
-    const found = findRawOption(rawArgv, flags);
-    const value = found?.value ?? optionString(options, key);
-    if (value) parts.push(found?.flag ?? flags[0], shellQuoteArg(value));
-  }
-  if (optionFlag(options, 'force')) parts.push('--force');
-  if (optionFlag(options, 'resolveOnly')) parts.push('--resolve-only');
-  if (optionFlag(options, 'json')) parts.push('--json');
-  return parts.join(' ');
-}
-
-function provisionPositionals(rawArgv: string[]): string[] {
-  const positionals: string[] = [];
-  const valueFlags = new Set([
-    '--adapter', '--target', '--project-root', '--platform', '--device-platform', '--branch', '--default-branch',
-    '--run', '--cache-root', '--simulator', '--device', '--runtime', '--device-type', '--slot', '--watcher-port',
-    '--runtime-dir',
-  ]);
-  for (let i = 0; i < rawArgv.length; i += 1) {
-    const arg = rawArgv[i];
-    if (!arg.startsWith('--')) {
-      positionals.push(arg);
-      continue;
-    }
-    const key = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
-    if (!arg.includes('=') && valueFlags.has(key)) i += 1;
-  }
-  return positionals;
-}
-
-function findRawOption(rawArgv: string[], flags: string[]): { flag: string; value: string } | undefined {
-  for (let i = 0; i < rawArgv.length; i += 1) {
-    const arg = rawArgv[i];
-    for (const flag of flags) {
-      if (arg === flag) {
-        const value = rawArgv[i + 1];
-        return value && !value.startsWith('--') ? { flag, value } : undefined;
-      }
-      if (arg.startsWith(`${flag}=`)) return { flag, value: arg.slice(flag.length + 1) };
-    }
-  }
-  return undefined;
-}
-
-function shellQuoteArg(value: string): string {
-  return /^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : shellQuote(value);
-}
-
-async function handleRuntimeHealth({ options }: ParsedArgs): Promise<number> {
-  const adapter = adapterOption(options);
-  if (adapter !== 'extension') throw new Error('runtime-health currently applies to the extension adapter.');
-  const target = targetPath(options);
-  const cdpPort = parsePort(
-    optionString(options, 'cdpPort') ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
-    'runtime-health requires --cdp-port <port>.',
-  );
-  const { checkExtensionRuntimeHealth, formatHealthFailure } = await import('./adapters/extension/runtime.ts');
-  const report = await checkExtensionRuntimeHealth(target, cdpPort);
-  if (optionFlag(options, 'json')) console.log(JSON.stringify(report, null, 2));
-  else if (report.status === 'PASS') console.log(`PASS extension runtime cdp=${cdpPort} target=${report.targetUrl}`);
-  else console.error(formatHealthFailure(report, target));
-  return report.status === 'PASS' ? 0 : 1;
-}
-
-
-async function handleRuntimeLaunch({ options }: ParsedArgs): Promise<number> {
-  const adapter = adapterOption(options);
-  const target = targetPath(options);
-  if (adapter !== 'extension') throw new Error('runtime-launch currently applies to the extension adapter.');
-  const cdpPort = parsePort(
-    optionString(options, 'cdpPort') ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
-    'runtime-launch requires --cdp-port <port>.',
-  );
-  const chromeUserDataDir = optionString(options, 'chromeUserDataDir');
-  const artifactsDir = path.resolve(
-    optionString(options, 'artifactsDir') ??
-      recipeHarnessPath(target, 'extension', 'runtime-launch', new Date().toISOString().replace(/[:.]/gu, '')),
-  );
-  const startWatch = optionFlag(options, 'startWatch');
-  const liveScript = recipeHarnessPath(target, 'extension', 'scripts', 'live.sh');
-  const command = [
-    'bash',
-    liveScript,
-    '--target',
-    target,
-    '--cdp-port',
-    String(cdpPort),
-    startWatch ? '--start-watch' : '--launch-existing-dist',
-    '--artifacts-dir',
-    artifactsDir,
-  ];
-  if (chromeUserDataDir) command.push('--chrome-user-data-dir', chromeUserDataDir);
-  // Optional A/B feature-flag pinning. Passed straight through to live.sh, which
-  // patches the ephemeral runtime-dist snapshot manifest before Chrome loads it.
-  // Omitting it leaves the launch byte-identical to the previous behavior.
-  const remoteFlag = optionString(options, 'remoteFlag');
-  if (remoteFlag) command.push('--remote-flag', remoteFlag);
-
-  if (!fs.existsSync(liveScript)) {
-    const report = runtimeLaunchReport('fail', {
-      adapter,
-      target,
-      cdpPort,
-      artifactsDir,
-      reason: 'harness_live_script_missing',
-      fix: `Run mm-harness install --adapter extension --target ${shellQuote(target)}, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir)}`,
-      command,
-    });
-    printRuntimeLaunchReport(report, optionFlag(options, 'json'));
-    return 1;
-  }
-
-  fs.mkdirSync(artifactsDir, { recursive: true });
-  const jsonMode = optionFlag(options, 'json');
-  if (!jsonMode) {
-    console.error(`recipe: runtime-launch starting (cdp=${cdpPort}${startWatch ? ', clean webpack build' : ', existing dist'})`);
-  } else {
-    console.error(JSON.stringify({
-      schemaVersion: 1,
-      type: 'progress',
-      command: 'rebuild',
-      phase: 'runtime-launch',
-      message: startWatch ? 'clean webpack build starting' : 'launching existing dist',
-      cdpPort,
-    }));
-  }
-  const result = spawnSync(command[0], command.slice(1), {
-    cwd: target,
-    encoding: 'utf8',
-    maxBuffer: 5 * 1024 * 1024,
-    // Human launches stream webpack/rsync/verify output live; --json keeps
-    // machine-readable capture for wrappers that pipe the final report.
-    stdio: jsonMode ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-  });
-  const summaryPath = path.join(artifactsDir, 'summary.json');
-  const summary = readJsonIfExists(summaryPath);
-
-  if (result.status === 0 && isRecord(summary) && summary.status === 'pass') {
-    const report = runtimeLaunchReport('pass', {
-      adapter,
-      target,
-      cdpPort,
-      artifactsDir,
-      summaryPath,
-      reason: 'runtime_ready',
-      fix: '',
-      command,
-    });
-    printRuntimeLaunchReport(report, optionFlag(options, 'json'));
-    return 0;
-  }
-
-  const launchLogPath = path.join(artifactsDir, 'launch', 'logs', 'launch.log');
-  const report = runtimeLaunchReport('fail', {
-    adapter,
-    target,
-    cdpPort,
-    artifactsDir,
-    summaryPath: fs.existsSync(summaryPath) ? summaryPath : undefined,
-    launchLogPath: fs.existsSync(launchLogPath) ? launchLogPath : undefined,
-    reason: 'runtime_launch_failed',
-    fix: `Read ${fs.existsSync(launchLogPath) ? launchLogPath : summaryPath}, fix the first error, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, startWatch)}`,
-    command,
-    exitCode: result.status ?? 1,
-  });
-  printRuntimeLaunchReport(report, optionFlag(options, 'json'));
-  return 1;
-}
-
-function runtimeLaunchCommand(target: string, cdpPort: number, chromeUserDataDir?: string, startWatch = false): string {
-  const base = `mm-harness runtime-launch --adapter extension --target ${shellQuote(target)} --cdp-port ${cdpPort}`;
-  const withMode = startWatch ? `${base} --start-watch` : base;
-  return chromeUserDataDir ? `${withMode} --chrome-user-data-dir ${shellQuote(chromeUserDataDir)}` : withMode;
-}
-
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/gu, `'\\''`)}'`;
-}
-
-function runtimeLaunchReport(status: 'pass' | 'fail', fields: Record<string, unknown>): Record<string, unknown> {
-  return {
-    schemaVersion: 1,
-    status,
-    ...fields,
-  };
-}
-
-function printRuntimeLaunchReport(report: Record<string, unknown>, json: boolean): void {
-  if (json) {
-    console.log(JSON.stringify(report, null, 2));
-    return;
-  }
-  const status = String(report.status).toUpperCase();
-  console.log(`${status} runtime-launch ${report.reason}`);
-  if (report.status === 'fail') console.log(`Fix: ${report.fix}`);
-  console.log(`Artifacts: ${report.artifactsDir}`);
-}
-
-function readJsonIfExists(file: string): unknown {
-  if (!fs.existsSync(file)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-async function handleRuntimeDecision({ options }: ParsedArgs): Promise<number> {
-  applyRuntimeDirOption(options);
-  const adapter = adapterOption(options);
-  const target = targetPath(options);
-  if (adapter === 'mobile') {
-    const watcherPortRaw =
-      optionString(options, 'watcherPort') ?? process.env.WATCHER_PORT ?? process.env.METRO_PORT;
-    const watcherPort =
-      watcherPortRaw === undefined
-        ? undefined
-        : parsePort(watcherPortRaw, 'runtime-decision --watcher-port must be a port.');
-    const report = await decideMobileReadiness(target, {
-      watcherPort,
-      metroLog: optionString(options, 'metroLog'),
-      platform: optionString(options, 'platform') ?? process.env.PLATFORM ?? process.env.RECIPE_HARNESS_PLATFORM,
-      record: optionFlag(options, 'record'),
-      preflightMode: optionString(options, 'preflightMode'),
-    });
-    if (optionFlag(options, 'json')) console.log(JSON.stringify(report, null, 2));
-    else console.log(`${report.decision} ${report.reasonCode} — ${report.reasons[0] ?? ''}`);
-    return 0;
-  }
-  if (adapter !== 'extension') {
-    const report = {
-      schemaVersion: 1,
-      adapter,
-      target,
-      decision: 'unknown',
-      clean: false,
-      reasonCode: 'adapter-unsupported',
-      reasons: [`runtime-decision applies to extension and mobile adapters, not ${adapter}.`],
-      checks: {},
-      actions: [],
-    };
-    if (optionFlag(options, 'json')) console.log(JSON.stringify(report, null, 2));
-    else console.log(`unknown adapter-unsupported — ${report.reasons[0]}`);
-    return 0;
-  }
-  const cdpPortRaw = optionString(options, 'cdpPort') ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
-  const cdpPort = cdpPortRaw === undefined ? undefined : parsePort(cdpPortRaw, 'runtime-decision --cdp-port must be a port.');
-  const report = await decideExtensionReadiness(target, {
-    cdpPort,
-    watchLog: optionString(options, 'watchLog'),
-    record: optionFlag(options, 'record'),
-  });
-  if (optionFlag(options, 'json')) console.log(JSON.stringify(report, null, 2));
-  else console.log(`${report.decision}${report.clean ? ' (clean)' : ''} ${report.reasonCode} — ${report.reasons[0] ?? ''}`);
-  return 0;
-}
-
-async function handleResolveExtension({ options }: ParsedArgs): Promise<number> {
-  const adapter = adapterOption(options);
-  if (adapter !== 'extension') throw new Error('resolve-extension currently applies to the extension adapter.');
-  const target = targetPath(options);
-  const cdpPortRaw = optionString(options, 'cdpPort') ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
-  const cdpPort = cdpPortRaw === undefined ? undefined : parsePort(cdpPortRaw, 'resolve-extension --cdp-port must be a port.');
-  const result = await resolveExtensionId(target, { cdpPort });
-  if (optionFlag(options, 'json')) console.log(JSON.stringify(result, null, 2));
-  else if (result.extensionId) console.log(result.extensionId); // bare id: easy `$(... resolve-extension ...)` capture
-  else console.error('Could not resolve a MetaMask extension id (no dist key and no single CDP extension).');
-  return result.extensionId ? 0 : 1;
-}
-
-async function handleEnsureReady({ options }: ParsedArgs): Promise<number> {
-  const adapter = adapterOption(options);
-  if (adapter !== 'extension') throw new Error('ensure-ready currently applies to the extension adapter.');
-  const target = targetPath(options);
-  const cdpPort = parsePort(
-    optionString(options, 'cdpPort') ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
-    'ensure-ready requires --cdp-port <port>.',
-  );
-  const result = await ensureExtensionReady(target, { cdpPort });
-  if (optionFlag(options, 'json')) console.log(JSON.stringify(result, null, 2));
-  else console.log(`${result.ready ? 'READY' : 'NOT-READY'} ${result.reasonCode} — id=${result.extensionId} homeTabs ${result.homeTabs.before}→${result.homeTabs.after} (closed ${result.homeTabs.closed})`);
-  return result.ready ? 0 : 1;
-}
-
-// Exit-code taxonomy (docs/CLI-SPEC.md §5.6) — consistent across commands:
-//   0 ok · 1 recipe/runtime fail (app-logic) · 2 usage / bad args ·
-//   3 infra not auto-healed · 4 bounded / not-retryable ·
-//   5 validation failure (run, run --plan, call — adapter-aware validation errors).
-const EXIT = { ok: 0, runtime: 1, usage: 2, infra: 3, bounded: 4, validation: 5 } as const;
-
-// Typed exit-code error: carries exitCode so both the global catch (mm-harness bin)
-// and the mm-harness delegate() wrapper classify the error correctly rather than always
-// returning 1.  Usage errors (bad args / unsupported flags) carry EXIT.usage (2);
-// validation errors carry EXIT.validation (5).  Never throw a plain new Error() for
-// user-facing bad-args cases — use usageError() so the exit code is preserved.
-class CliError extends Error {
-  readonly exitCode: number;
-  constructor(message: string, exitCode: number) {
-    super(message);
-    this.name = 'CliError';
-    this.exitCode = exitCode;
-  }
-}
-function usageError(message: string): CliError {
-  return new CliError(message, EXIT.usage);
-}
-
-// Shared adapter resolution: explicit --adapter/--platform, else auto-detect from
-// --target/cwd (the exact detect story doctor/verify/install use). Lets `call`,
-// `run --plan`, and `completion-candidates` work in a checkout without a flag.
-function resolveAdapter(options: CliOptions): { adapter: MetaMaskRecipeAdapter; target: string } {
-  const target = targetPath(options);
-  const explicit = optionString(options, 'adapter') ?? optionString(options, 'platform');
-  const adapter = explicit ?? detectAdapter(target);
-  if (!adapter) {
-    throw usageError(`could not detect the MetaMask repo type for ${target}\n  Next: ${ADAPTER_DETECT_NEXT}`);
-  }
-  try {
-    assertAdapter(adapter);
-  } catch (error) {
-    throw usageError(error instanceof Error ? error.message : String(error));
-  }
-  return { adapter, target };
-}
-
-// Adapter-aware recipe validation: schema (validateRecipeDocument) + action
-// existence/platform against the adapter's manifest (validateRecipeWithManifest).
-// When librarySources are provided (resolved from --library / personal / team
-// tiers), external flow IDs from those sources are declared so `call.ref` nodes
-// targeting library-defined flows pass schema validation.
-async function validateRecipeAdapterAware(
-  recipe: unknown,
-  manifest: RecipeActionManifestDocument,
-  librarySources?: MetaMaskLibrarySource[],
-): Promise<RecipeValidationResult> {
-  const { validateRecipeDocument, validateRecipeWithManifest } = await importRecipeProtocol();
-  let externalFlowIds: ReadonlySet<string> | undefined;
-  if (librarySources && librarySources.length > 0) {
-    const harness = await importRecipeHarness();
-    const resolution = await harness.loadRecipeLibraries(librarySources);
-    externalFlowIds = new Set(resolution.flows.keys());
-  }
-  const validationOptions = externalFlowIds !== undefined ? { externalFlowIds } : undefined;
-  const schema = validateRecipeDocument(recipe, validationOptions);
-  const withManifest = validateRecipeWithManifest(recipe, manifest, validationOptions);
-  const findings = [...schema.findings, ...withManifest.findings];
-  const errors = findings.filter((finding) => finding.severity === 'error').length;
-  const warnings = findings.length - errors;
-  return { status: errors > 0 ? 'invalid' : 'valid', findings, summary: { errors, warnings } };
-}
-
-interface PlanItem {
-  step: string;
-  confidence: 'static' | 'conditional';
-  status: 'ok' | 'error' | 'planned';
-  detail: string;
-}
-
-function countRecipeNodes(recipe: unknown): number | undefined {
-  if (!isRecord(recipe)) return undefined;
-  const validate = isRecord(recipe.validate) ? recipe.validate : undefined;
-  const workflow = validate && isRecord(validate.workflow) ? validate.workflow : undefined;
-  const nodes = workflow && isRecord(workflow.nodes) ? workflow.nodes : undefined;
-  return nodes ? Object.keys(nodes).length : undefined;
-}
-
-// Static, adapter-aware recipe validation shared by `run --plan` and the `run`
-// execute path so both "validate first" the same way: read the file (missing /
-// unparseable → usage error, nothing to validate), check the manifest, then run
-// the adapter-aware schema + action-existence validation. Loads library flow IDs
-// from --library (so `call.ref` nodes to external flows resolve correctly), but
-// never emits the engine's "Recipe libraries: …" log — safe to call before the
-// machine-contract JSON is written.
-interface RunRecipeStaticValidation {
-  recipe: unknown;
-  recipeFile: string;
-  findings: RecipeValidationFinding[];
-  errorCount: number;
-  manifestOk: boolean;
-  schemaValid: boolean;
-  usageError?: { code: string; message: string };
-}
-
-async function validateRunRecipeStatic(
-  recipeArg: string,
-  adapter: MetaMaskRecipeAdapter,
-  options: CliOptions,
-): Promise<RunRecipeStaticValidation> {
-  const recipeFile = path.resolve(recipeArg);
-  const empty = { recipe: undefined, recipeFile, findings: [], errorCount: 0, manifestOk: false, schemaValid: false };
-  if (!fs.existsSync(recipeFile)) {
-    return { ...empty, usageError: { code: 'RECIPE_NOT_FOUND', message: `recipe not found: ${recipeFile}` } };
-  }
-  let recipe: unknown;
-  try {
-    recipe = JSON.parse(fs.readFileSync(recipeFile, 'utf8'));
-  } catch (error) {
-    return {
-      ...empty,
-      usageError: {
-        code: 'RECIPE_UNPARSEABLE',
-        message: `recipe is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
-      },
-    };
-  }
-
-  // validate.manifest (static) — manifest well-formedness (same check doctor runs).
-  const findings: RecipeValidationFinding[] = [];
-  const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
-  let manifestOk = true;
-  try {
-    await validateManifest(manifest);
-  } catch (error) {
-    manifestOk = false;
-    findings.push({
-      severity: 'error',
-      code: 'manifest.invalid',
-      path: actionManifestPathOption(options, adapter),
-      message: error instanceof Error ? error.message : String(error),
-    });
-  }
-
-  // validate.schema + validate.actions (static) — adapter-aware recipe validation.
-  // Library sources are resolved here so external `call.ref` flows validate correctly.
-  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, 'library'));
-  const validation = manifestOk
-    ? await validateRecipeAdapterAware(recipe, manifest, librarySources)
-    : { status: 'invalid' as const, findings: [], summary: { errors: 1, warnings: 0 } };
-  findings.push(...validation.findings);
-
-  const errorCount = findings.filter((finding) => finding.severity === 'error').length;
-  return { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid: validation.status === 'valid' };
-}
-
-// `run --plan`: validate (adapter-aware) + print the plan — touches NOTHING (no
-// device, no overlay mutation, no artifacts written). Exit 0 = plan valid; exit 5
-// = validation failed. `--json` = { status, adapter, recipe, findings[], plan[] }.
-async function handleRunPlan(recipeArg: string, options: CliOptions): Promise<number> {
-  const json = optionFlag(options, 'json');
-  const { adapter, target } = resolveAdapter(options);
-
-  const validated = await validateRunRecipeStatic(recipeArg, adapter, options);
-  if (validated.usageError) {
-    return emitPlanUsageError(json, adapter, validated.recipeFile, validated.usageError.code, validated.usageError.message);
-  }
-  const { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid } = validated;
-
-  const status: 'pass' | 'fail' = errorCount === 0 ? 'pass' : 'fail';
-  const nodeCount = countRecipeNodes(recipe);
-  const artifactsDir = optionString(options, 'artifactsDir');
-
-  const plan: PlanItem[] = [
-    { step: 'resolve.recipe', confidence: 'static', status: 'ok', detail: recipeFile },
-    { step: 'resolve.adapter', confidence: 'static', status: 'ok', detail: adapter },
-    {
-      step: 'resolve.artifactsDir',
-      confidence: 'static',
-      status: 'ok',
-      detail: artifactsDir ? path.resolve(artifactsDir) : '(resolved to the slot artifacts dir at run time)',
-    },
-    {
-      step: 'validate.manifest',
-      confidence: 'static',
-      status: manifestOk ? 'ok' : 'error',
-      detail: manifestOk ? 'action manifest is well-formed' : 'action manifest failed validation',
-    },
-    {
-      step: 'validate.schema',
-      confidence: 'static',
-      status: manifestOk && schemaValid ? 'ok' : 'error',
-      detail: 'recipe document schema + action existence/platform vs the adapter manifest',
-    },
-    {
-      step: 'fixture.file',
-      confidence: 'static',
-      status: 'ok',
-      detail: fs.existsSync(walletFixturePath(target)) ? `present: ${walletFixturePath(target)}` : `absent: ${walletFixturePath(target)} (fixtures set to seed)`,
-    },
-    {
-      step: 'overlay.ensure',
-      confidence: 'conditional',
-      status: 'planned',
-      detail: 'would auto-ensure the runtime overlay if missing (install phase)',
-    },
-    ...(adapter === 'core'
-      ? []
-      : [
-          {
-            step: 'launch.app',
-            confidence: 'conditional' as const,
-            status: 'planned' as const,
-            detail: 'would launch/attach the app + heal transport (Metro/Chrome/CDP) before executing',
-          },
-        ]),
-    {
-      step: 'execute.nodes',
-      confidence: 'conditional',
-      status: 'planned',
-      detail: nodeCount === undefined ? 'would execute the recipe nodes' : `would execute ${nodeCount} recipe node(s)`,
-    },
-  ];
-
-  if (json) {
-    const payload: Record<string, unknown> = { schemaVersion: 1, command: 'run', mode: 'plan', status, adapter, recipe: recipeFile, findings, plan };
-    if (status === 'fail') payload.error = { code: 'RECIPE_VALIDATION_FAILED', message: `recipe validation found ${errorCount} error(s)` };
-    console.log(JSON.stringify(payload, null, 2));
-  } else {
-    console.log(`plan ${status} — ${adapter} — ${recipeFile}`);
-    for (const item of plan) {
-      const mark = item.status === 'error' ? '✗' : item.status === 'ok' ? '✓' : '·';
-      console.log(`  ${mark} [${item.confidence}] ${item.step}: ${item.detail}`);
-    }
-    if (findings.length) {
-      console.log('findings:');
-      for (const finding of findings) {
-        console.log(`  ${finding.severity === 'error' ? '✗' : '⚠'} ${finding.code} ${finding.path} — ${finding.message}`);
-      }
-    }
-  }
-  return status === 'pass' ? EXIT.ok : EXIT.validation;
-}
-
-function emitPlanUsageError(
-  json: boolean,
-  adapter: MetaMaskRecipeAdapter,
-  recipeFile: string,
-  code: string,
-  message: string,
-): number {
-  if (json) {
-    console.log(
-      JSON.stringify(
-        { schemaVersion: 1, command: 'run', mode: 'plan', status: 'fail', adapter, recipe: recipeFile, error: { code, message } },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.error(`✗ run --plan: ${message}`);
-  }
-  return EXIT.usage;
-}
-
-// `call <action>`: execute ONE action from the adapter vocabulary AS a single-node
-// recipe through the real engine path — the SAME path `run` uses (write a recipe,
-// hand it to runRecipe). One execution path, two doors: `call` = one node, `run` =
-// a graph. Inherits run semantics: always-validates (adapter-aware, exit 5), same
-// trace/evidence artifacts, same --json contract.
-async function handleStop(argv: string[]): Promise<number> {
-  const { options } = parseArgs(argv, 'stop');
-  const json = optionFlag(options, 'json');
-  const { adapter, target } = resolveAdapter(options);
-  const surface = getAdapterSurface(adapter);
-  // Slot-scope the stop: an explicit --port wins, else resolve the checkout's
-  // own dev-server port so a concurrent slot's server is never signalled.
-  const explicitPort = optionString(options, 'port') ?? optionString(options, 'watcherPort');
-  if (explicitPort) {
-    process.env.WATCHER_PORT = explicitPort;
-    process.env.METRO_PORT = explicitPort;
-  } else {
-    surface.resolveSlotPorts(target);
-  }
-  const stop = surface.devServer.stop(target);
-  if (stop.kind === 'headless') {
-    // core has no dev server — teach the reachable headless path (exit 2).
-    return usageOut(json, 'stop', stop.message, stop.userAction);
-  }
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: 'stop',
-          adapter,
-          target,
-          status: stop.status === 0 ? 'pass' : 'fail',
-          ...(stop.signalled !== undefined ? { signalled: stop.signalled } : {}),
-          exitCode: stop.status,
-          ...(stop.output ? { output: stop.output } : {}),
-        },
-        null,
-        2,
-      ),
-    );
-  } else {
-    // The leaf may have captured its own detail; surface it, then the uniform
-    // outcome line the same way for every platform.
-    if (stop.output) process.stderr.write(`${stop.output}\n`);
-    console.error(`${color(stop.status === 0 ? 'ok' : 'err', stop.status === 0 ? '✓' : '✗')} ${stop.summary}`);
-  }
-  return stop.status;
-}
-
-async function handleCall(argv: string[]): Promise<number> {
-  // Grammar: mm-harness call <action> [--arg k=v ...] [flags].
-  // If the first token is a flag, the action positional is missing — parseCallArgs
-  // would wrongly consume the flag's VALUE as the action name (e.g. `--adapter core`
-  // → action='core'). Catch it early before any parsing so the error is accurate.
-  if (argv.length > 0 && argv[0].startsWith('--')) {
-    const message = 'call requires <action> first: mm-harness call <action> [--arg k=v ...] [flags]';
-    console.error(message);
-    return EXIT.usage;
-  }
-  const { action: shortName, args, rest } = parseCallArgs(argv);
-  const { options } = parseArgs(rest, 'call');
-  const json = optionFlag(options, 'json');
-  if (!shortName) {
-    // Context-aware usage: the example uses the DETECTED adapter and a REAL action
-    // from its manifest — never a hardcoded action/adapter that may not exist in
-    // this checkout — and points at the scoped discovery command.
-    let example = 'mm-harness call <action>';
-    let discovery = 'mm-harness actions';
-    try {
-      const { adapter } = resolveAdapter(options);
-      const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
-      const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
-      const exampleAction = pickCallExampleAction(getRecipeActionManifestActionNames(manifest));
-      example = `mm-harness call ${exampleAction} --adapter ${adapter}`;
-      discovery = `mm-harness actions --adapter ${adapter}`;
-    } catch { /* adapter/manifest unavailable — keep the generic example */ }
-    const message = `call requires <action>. Example: ${example}`;
-    const userAction = `${example}   # see the vocabulary: ${discovery}`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', error: { code: 'USAGE', message, userAction } }, null, 2));
-    else console.error(`${message}\n  See the vocabulary: ${discovery}`);
-    return EXIT.usage;
-  }
-
-  const { adapter, target } = resolveAdapter(options);
-
-  // Pre-execution bound: refuse while another recipe is running. Checked here
-  // (before manifest load) so any action name produces exit 4, not an action
-  // resolution error, when a recipe.lock is present.
-  if (recipeRunning(target)) {
-    const msg = 'a recipe is currently running — refusing to start while another recipe executes.';
-    if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, command: 'call', status: 'fail', recoverable: false, error: { code: 'RECIPE_RUNNING', message: msg } }, null, 2));
-    } else {
-      console.error(`✗ mm-harness call: ${msg}`);
-    }
-    return EXIT.bounded;
-  }
-
-  const actionManifestOverride = optionString(options, 'actionManifest');
-  const manifest = loadActionManifest(adapter, actionManifestOverride);
-  const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
-  const names = getRecipeActionManifestActionNames(manifest);
-
-  const resolution = resolveActionName(shortName, names);
-  if (resolution.status === 'unknown') {
-    const message =
-      `✗ call: unknown action "${shortName}" for the ${adapter} adapter.\n` +
-      `  See the vocabulary: mm-harness actions --adapter ${adapter} --json`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', adapter, action: shortName, error: { code: 'ACTION_UNKNOWN', message } }, null, 2));
-    else console.error(message);
-    return EXIT.usage;
-  }
-  if (resolution.status === 'ambiguous') {
-    const message = `✗ call: "${shortName}" is ambiguous: ${resolution.candidates.join(', ')} — use the full name.`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', adapter, action: shortName, error: { code: 'ACTION_AMBIGUOUS', message, candidates: resolution.candidates } }, null, 2));
-    else console.error(message);
-    return EXIT.usage;
-  }
-  const resolvedAction = resolution.resolved;
-
-  // Synthesize the one-node recipe (entry action → end). This IS the recipe `run`
-  // would execute; call just authored it from the CLI instead of a file.
-  const recipe = synthesizeOneNodeRecipe(resolvedAction, args);
-
-  // Always-validate first (adapter-aware) — exit 5 on validation failure, before
-  // the engine touches anything.
-  const validation = await validateRecipeAdapterAware(recipe, manifest);
-  if (validation.status === 'invalid') {
-    const message = `✗ call ${resolvedAction}: recipe validation failed`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', adapter, action: shortName, resolvedAction, args, findings: validation.findings, error: { code: 'RECIPE_VALIDATION_FAILED', message } }, null, 2));
-    else {
-      console.error(message);
-      for (const finding of validation.findings) console.error(`  ${finding.code} ${finding.path} — ${finding.message}`);
-    }
-    return EXIT.validation;
-  }
-
-  // --heal (call inherits infra-only) + auto-ensure the runtime overlay before
-  // execution. core is headless → no-op.
-  const prepared = await prepareHeal(adapter, target, options, json);
-  if (typeof prepared === 'number') return prepared;
-  const { state, heal } = prepared;
-
-  // Write the synthesized recipe to a temp file and run it through the exact same
-  // engine path `run` uses (runRecipe → runner.run). Evidence lands in artifactsDir.
-  const scratch = await mkdtemp(path.join(os.tmpdir(), 'mm-harness-call-'));
-  const recipeFile = path.join(scratch, 'call.recipe.json');
-  fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}\n`);
-  const artifactsDir = optionString(options, 'artifactsDir') ?? path.join(scratch, 'artifacts');
-
-  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, 'library'));
-  const callRuntimeOptions: RuntimeOptions = {
-    ...runtimeOptionsFromCli(options),
-    ...(librarySources ? { librarySources } : {}),
-    stdoutIsMachineContract: json,
-  };
-  // Failure/retry path wired through the shared checkHealBounds module, identical
-  // to `run`: app-logic verbatim/no-heal, bounded infra recovery, and the
-  // same-recovery-twice refusal.
-  const { result, violation } = await executeWithHealBounds(
-    () => runRecipe(adapter, recipeFile, artifactsDir, target, actionManifestOverride, callRuntimeOptions),
-    adapter,
-    target,
-    heal,
-    state,
-  );
-  if (violation !== null) return emitHealViolation(json, 'call', result, violation, state, adapter);
-
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: 'call',
-          adapter,
-          action: shortName,
-          resolvedAction,
-          args,
-          status: result.status,
-          summaryPath: result.summaryPath,
-          tracePath: result.tracePath,
-          artifactManifestPath: result.artifactManifestPath,
-          recovered: state.recovered,
-          mutations: state.mutations,
-          exitCode: result.status === 'pass' ? EXIT.ok : EXIT.runtime,
-        },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.log(`call ${resolvedAction}: ${result.status}\nArtifacts: ${result.artifactManifestPath}`);
-  }
-  return result.status === 'pass' ? EXIT.ok : EXIT.runtime;
-}
-
-interface CallArgs {
-  action: string | undefined;
-  args: Record<string, string>;
-  rest: string[];
-}
-
-// Pull the positional <action> and repeatable `--arg k=v` out of argv; everything
-// else (--adapter/--json/--target/…) flows to the shared parseArgs.
-function parseCallArgs(argv: string[]): CallArgs {
-  const args: Record<string, string> = {};
-  const rest: string[] = [];
-  let action: string | undefined;
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--arg' || arg.startsWith('--arg=')) {
-      const pair = arg === '--arg' ? argv[(i += 1)] : arg.slice('--arg='.length);
-      if (pair === undefined) throw usageError('--arg requires k=v.');
-      const eq = pair.indexOf('=');
-      if (eq === -1) throw usageError(`--arg must be k=v: ${pair}`);
-      args[pair.slice(0, eq)] = pair.slice(eq + 1);
-      continue;
-    }
-    if (!arg.startsWith('--') && action === undefined) {
-      action = arg;
-      continue;
-    }
-    rest.push(arg);
-  }
-  return { action, args, rest };
-}
-
-interface ActionResolution {
-  status: 'ok' | 'ambiguous' | 'unknown';
-  resolved: string;
-  candidates: string[];
-}
-
-// Fuzzy short-name resolution, most-specific tier first (exact beats substring):
-//   1. exact full action name (`metamask.wallet.ensure_unlocked`);
-//   2. exact final dot-segment (`unlock` → `metamask.wallet.unlock`);
-//   3. unique substring of a final segment (`unlock` ⊂ `ensure_unlocked`).
-// Within the first tier that has any match: 1 → ok, >1 → ambiguous. Only a fully
-// empty tier falls through, so an exact match is never overridden by a substring.
-function resolveActionName(shortName: string, names: string[]): ActionResolution {
-  if (names.includes(shortName)) return { status: 'ok', resolved: shortName, candidates: [shortName] };
-  const finalSegment = (name: string): string => name.split('.').pop() ?? name;
-  const exactSegment = names.filter((name) => finalSegment(name) === shortName);
-  const tier = exactSegment.length > 0 ? exactSegment : names.filter((name) => finalSegment(name).includes(shortName));
-  if (tier.length === 1) return { status: 'ok', resolved: tier[0], candidates: tier };
-  if (tier.length > 1) return { status: 'ambiguous', resolved: '', candidates: tier };
-  return { status: 'unknown', resolved: '', candidates: [] };
-}
-
-// A real action name to show in the `call` usage example, from THIS adapter's
-// manifest: a wallet action when the platform has one, else the universal
-// `command` action, else the first declared name. Never a hardcoded guess.
-function pickCallExampleAction(names: string[]): string {
-  const walletish = names.find((name) => /wallet|unlock/u.test(name));
-  if (walletish) return walletish;
-  if (names.includes('command')) return 'command';
-  return names[0] ?? 'command';
-}
-
-function synthesizeOneNodeRecipe(action: string, args: Record<string, string>): Record<string, unknown> {
-  return {
-    schema_version: 1,
-    title: `mm-harness call ${action}`,
-    description: `Ad-hoc single-action execution of ${action} via the real engine path (mm-harness call).`,
-    validate: {
-      workflow: {
-        entry: 'call',
-        nodes: {
-          call: { action, ...args, next: 'done', intent: `Call ${action} in isolation` },
-          done: { action: 'end', status: 'pass' },
-        },
-      },
-    },
-  };
-}
-
-// Reusable one-node engine path (the same machinery `call` uses), exposed so
-// `fixtures set` can apply the canonical wallet fixture through the real engine on
-// the extension (which has no standalone shell set arm).
-async function runOneNode(
-  adapter: MetaMaskRecipeAdapter,
-  action: string,
-  args: Record<string, string>,
-  target: string,
-  actionManifest: string | undefined,
-): Promise<{ status: 'pass' | 'fail' }> {
-  const manifest = loadActionManifest(adapter, actionManifest);
-  const recipe = synthesizeOneNodeRecipe(action, args);
-  const validation = await validateRecipeAdapterAware(recipe, manifest);
-  if (validation.status === 'invalid') return { status: 'fail' };
-  const scratch = await mkdtemp(path.join(os.tmpdir(), 'mm-harness-fixtures-'));
-  const recipeFile = path.join(scratch, 'set.recipe.json');
-  fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}\n`);
-  const result = await runRecipe(adapter, recipeFile, path.join(scratch, 'artifacts'), target, actionManifest, {
-    librarySources: await resolveMetaMaskLibrarySources(undefined),
-  });
-  return { status: result.status === 'pass' ? 'pass' : 'fail' };
-}
-
-// Pre-execution heal setup shared by `run` and `call` (both default `infra-only`).
-// Parses --heal, then auto-ensures the runtime overlay for the device adapters
-// (mobile/extension). core is headless — its engine path needs no launch overlay.
-// Returns the heal state + policy on success, or an exit code (number) on failure
-// (invalid --heal → usage; overlay install failed → infra) — a typeof-narrowable
-// result so this works regardless of strict-mode settings.
-interface PreparedHeal {
-  state: HealState;
-  heal: HealPolicy;
-}
-
-async function prepareHeal(
-  adapter: MetaMaskRecipeAdapter,
-  target: string,
-  options: CliOptions,
-  json: boolean,
-): Promise<PreparedHeal | number> {
-  // Bound: refuse while another recipe is running (re-entrant run would corrupt
-  // in-flight state). Enforced regardless of --heal policy. Also checked earlier
-  // in handleCall (before action resolution) so the test can use any action name.
-  if (recipeRunning(target)) {
-    const msg = 'a recipe is currently running — refusing to start while another recipe executes.';
-    if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, status: 'fail', recoverable: false, error: { code: 'RECIPE_RUNNING', message: msg } }, null, 2));
-    } else {
-      console.error(`✗ mm-harness: ${msg}`);
-    }
-    return EXIT.bounded;
-  }
-
-  const healValue = optionString(options, 'heal');
-  const healOpts: Record<string, string | boolean> = {};
-  if (healValue !== undefined) healOpts.heal = healValue;
-  const heal = parseHeal(healOpts, 'infra-only');
-  if (typeof heal !== 'string') {
-    console.error((heal as { error: string }).error);
-    return EXIT.usage;
-  }
-  const state = newHealState();
-  const ensured = await ensureOverlay(adapter, target, heal as HealPolicy, state, json);
-  if (!ensured.ok) {
-    if (json) {
-      console.log(
-        JSON.stringify(
-          { schemaVersion: 1, status: 'fail', recoverable: false, mutations: state.mutations, error: { code: 'OVERLAY_INSTALL_FAILED', message: ensured.error } },
-          null,
-          2,
-        ),
-      );
-    } else {
-      console.error(`✗ overlay auto-ensure failed: ${ensured.error}`);
-    }
-    return EXIT.infra;
-  }
-  return { state, heal: heal as HealPolicy };
-}
-
-// Recovery codes for the run/call heal loop — the analog of the launch recovery
-// codes. core is headless (no transport) but still carries a code so the shared
-// same-recovery-twice bound can fire and stop blind retry loops.
-const RUN_RECOVERY_CODE: Record<MetaMaskRecipeAdapter, string> = {
-  mobile: 'metro.restarted',
-  extension: 'chrome.reopened',
-  core: 'runtime.reset',
-};
-
-// Collect the failed nodes' error text from a run's trace.json, verbatim, so the
-// shared checkHealBounds can classify the failure (app-logic vs infra vs wallet)
-// and so the ORIGINAL cause survives into the --json/human output.
-function readRunFailureText(result: RecipeRunResult): string {
-  try {
-    const trace = JSON.parse(fs.readFileSync(result.tracePath, 'utf8')) as {
-      entries?: Array<{ ok?: boolean; error?: unknown }>;
-    };
-    const entries = Array.isArray(trace.entries) ? trace.entries : [];
-    return entries
-      .filter((entry) => entry && entry.ok === false && typeof entry.error === 'string')
-      .map((entry) => entry.error as string)
-      .join('\n')
-      .trim();
-  } catch {
-    return '';
-  }
-}
-
-// Shared run/call failure-and-retry path wired through the same checkHealBounds
-// module launch uses. On failure it classifies the verbatim trace output:
-// app-logic → surface verbatim, no heal (exit 1); wallet → refuse (exit 4);
-// recipe-running → refuse (exit 4). Infra failures get ONE bounded recovery re-run
-// (heal != off); a second failure trips the same-recovery-twice bound (exit 4).
-// `state.recovered[]`/`attemptedRecoveries[]` are mutated for the --json contract.
-// Returns the final result plus the violation (if any) to surface.
-async function executeWithHealBounds(
-  exec: () => Promise<RecipeRunResult>,
-  adapter: MetaMaskRecipeAdapter,
-  target: string,
-  heal: HealPolicy,
-  state: HealState,
-): Promise<{ result: RecipeRunResult; violation: HealBoundViolation | null }> {
-  let result = await exec();
-  for (;;) {
-    if (result.status === 'pass') return { result, violation: null };
-    const violation = checkHealBounds(target, readRunFailureText(result), state);
-    if (violation !== null) return { result, violation };
-    // Unclassified/infra failure. heal=off preserves the exact broken state.
-    if (heal === 'off') return { result, violation: null };
-    // Bounded infra recovery: re-run once. Record BEFORE the retry so the next
-    // checkHealBounds call sees it and refuses a second loop (same-recovery-twice).
-    const recoveryCode = RUN_RECOVERY_CODE[adapter];
-    state.attemptedRecoveries.push(recoveryCode);
-    result = await exec();
-    if (result.status === 'pass') {
-      state.recovered.push(recoveryCode);
-      return { result, violation: null };
-    }
-  }
-}
-
-// Hidden `completion-candidates <actions|flows>` — the source shell completion
-// scripts call it. Reads/writes the per-checkout completion cache so tab
-// completion never blocks on a manifest/library read. `flows` degrades gracefully
-// until @farmslot/recipe-harness >= 0.3.3 exposes the recipe-library API.
-async function handleCompletionCandidates(argv: string[]): Promise<number> {
-  const kind = argv[0];
-  const { options } = parseArgs(argv.slice(1), 'completion-candidates');
-  const json = optionFlag(options, 'json');
-  if (kind !== 'actions' && kind !== 'flows') {
-    console.error('completion-candidates requires <actions|flows>.');
-    return EXIT.usage;
-  }
-  // Actions are adapter-scoped (they come from the adapter manifest); library
-  // flows are adapter-global, so flows completion works even outside a checkout.
-  const target = targetPath(options);
-  let adapter: MetaMaskRecipeAdapter | undefined;
-
-  let candidates: string[] | undefined;
-  if (kind === 'actions') {
-    adapter = resolveAdapter(options).adapter;
-    candidates = readFreshCandidates(target, 'actions');
-    if (!candidates) {
-      const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
-      const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
-      candidates = getRecipeActionManifestActionNames(manifest);
-      writeCompletionCandidates(target, 'actions', candidates);
-    }
-  } else {
-    candidates = readFreshCandidates(target, 'flows');
-    if (!candidates) {
-      const sources = await resolveMetaMaskLibrarySources(undefined).catch(() => undefined);
-      if (!sources) {
-        // recipe-library API absent: return empty (not an error) so the shell
-        // falls back to static completion instead of blocking.
-        candidates = [];
-      } else {
-        const harness = await importRecipeHarness();
-        const resolution = await harness.loadRecipeLibraries(sources);
-        candidates = [...resolution.flows.keys()].sort();
-        writeCompletionCandidates(target, 'flows', candidates);
-      }
-    }
-  }
-
-  if (json) console.log(JSON.stringify({ schemaVersion: 1, kind, adapter, candidates }, null, 2));
-  else for (const candidate of candidates) console.log(candidate);
-  return EXIT.ok;
-}
-
-async function handleRun({ positional, options }: ParsedArgs): Promise<number> {
-  const targetRecipe = positional[0];
-  if (!targetRecipe) throw usageError('run requires <recipe.json>.');
-  // run --plan: validate + print the plan, touch NOTHING (no device, no overlay).
-  if (optionFlag(options, 'plan')) return handleRunPlan(targetRecipe, options);
-  const adapter = adapterOption(options);
-  const json = optionFlag(options, 'json');
-  const target = targetPath(options);
-  const artifactsDir = requiredOption(options, 'artifactsDir', 'run requires --artifacts-dir <dir>.');
-
-  // --heal (default infra-only) + auto-ensure the runtime overlay before
-  // execution. core is headless → no-op. Also enforces the recipe-running bound
-  // (exit 4) before the recipe file is read — that refusal must precede validation.
-  const prepared = await prepareHeal(adapter, target, options, json);
-  if (typeof prepared === 'number') return prepared;
-  const { state, heal } = prepared;
-
-  // Validate first (adapter-aware) — the SAME static path `run --plan` uses, before
-  // launching/executing or resolving libraries. A missing or unparseable recipe is
-  // a usage error (exit 2); validation errors exit 5 with the structured JSON.
-  // Nothing here logs "Recipe libraries: …", so the machine contract on stdout
-  // stays pure on the validation-failure path.
-  const validated = await validateRunRecipeStatic(targetRecipe, adapter, options);
-  if (validated.usageError) {
-    return emitRunUsageError(json, adapter, validated.recipeFile, validated.usageError.code, validated.usageError.message);
-  }
-  if (validated.errorCount > 0) {
-    return emitRunValidationError(json, adapter, validated.recipeFile, validated.findings, validated.errorCount);
-  }
-
-  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, 'library'));
-  const runtimeOptions: RuntimeOptions = {
-    ...runtimeOptionsFromCli(options),
-    ...(librarySources ? { librarySources } : {}),
-    stdoutIsMachineContract: json,
-  };
-  // Failure/retry path wired through the shared checkHealBounds module:
-  // app-logic → verbatim no-heal; wallet/recipe-running → refuse; infra → one
-  // bounded recovery re-run, second failure → same-recovery-twice.
-  const { result, violation } = await executeWithHealBounds(
-    () => runRecipe(adapter, targetRecipe, artifactsDir, target, optionString(options, 'actionManifest'), runtimeOptions),
-    adapter,
-    target,
-    heal,
-    state,
-  );
-  if (violation !== null) return emitHealViolation(json, 'run', result, violation, state, adapter);
-  const exitCode = result.status === 'pass' ? EXIT.ok : EXIT.runtime;
-  if (json) {
-    // mm-harness envelope (matches launch/verify/doctor): the engine's result is
-    // nested under `result`; the heal contract (recovered[]/mutations[]) and the
-    // resolved exitCode ride the envelope regardless of adapter.
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: 'run',
-          adapter,
-          status: result.status,
-          exitCode,
-          recovered: state.recovered,
-          mutations: state.mutations,
-          result,
-        },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.log(`MetaMask recipe run: ${result.status}\nArtifacts: ${result.artifactManifestPath}`);
-  }
-  return exitCode;
-}
-
-// Usage error for the `run` execute path (recipe missing / unparseable — exit 2).
-// Mirrors the plan emitter but carries the run envelope keys, not `mode: 'plan'`.
-function emitRunUsageError(
-  json: boolean,
-  adapter: MetaMaskRecipeAdapter,
-  recipeFile: string,
-  code: string,
-  message: string,
-): number {
-  if (json) {
-    console.log(
-      JSON.stringify(
-        { schemaVersion: 1, command: 'run', adapter, status: 'fail', exitCode: EXIT.usage, recipe: recipeFile, error: { code, message } },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.error(`✗ run: ${message}`);
-  }
-  return EXIT.usage;
-}
-
-// Validation failure for the `run` execute path — exit 5 with the structured
-// finding list, before the app is launched or the recipe executes (parity with
-// `run --plan` and `call`).
-function emitRunValidationError(
-  json: boolean,
-  adapter: MetaMaskRecipeAdapter,
-  recipeFile: string,
-  findings: RecipeValidationFinding[],
-  errorCount: number,
-): number {
-  const message = `recipe validation found ${errorCount} error(s)`;
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: 'run',
-          adapter,
-          status: 'fail',
-          exitCode: EXIT.validation,
-          recovered: [],
-          mutations: [],
-          recipe: recipeFile,
-          findings,
-          error: { code: 'RECIPE_VALIDATION_FAILED', message },
-        },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.error(`✗ run: ${message}`);
-    for (const finding of findings) {
-      if (finding.severity === 'error') console.error(`  ${finding.code} ${finding.path} — ${finding.message}`);
-    }
-  }
-  return EXIT.validation;
-}
-
-// Shared failure emitter for the run/call heal path — surfaces the bound-specific
-// error code, the classification note, and the ORIGINAL failure verbatim in both
-// --json and human modes.
-function emitHealViolation(
-  json: boolean,
-  command: 'run' | 'call',
-  result: RecipeRunResult,
-  violation: HealBoundViolation,
-  state: HealState,
-  adapter?: MetaMaskRecipeAdapter,
-): number {
-  // core is headless: `fixtures set` is blocked. Teach the env-var / recipe-node
-  // path instead so the user has a reachable next step.
-  const userAction =
-    adapter === 'core' && violation.code === 'WALLET_STATE_REQUIRED'
-      ? 'set MM_TEST_ACCOUNT_ADDRESS=<0x…> in env, or add "account": "<0x…>" to the node block in the recipe'
-      : violation.userAction;
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command,
-          status: 'fail',
-          recoverable: false,
-          recovered: state.recovered,
-          mutations: state.mutations,
-          attemptedRecoveries: state.attemptedRecoveries,
-          summaryPath: result.summaryPath,
-          tracePath: result.tracePath,
-          artifactManifestPath: result.artifactManifestPath,
-          exitCode: violation.exitCode,
-          error: {
-            code: violation.code,
-            message: violation.message,
-            retryable: false,
-            userAction: userAction ?? null,
-            originalError: violation.originalError ?? null,
-          },
-        },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.error(
-      `✗ mm-harness ${command}: ${violation.message}` +
-        (violation.originalError ? `\n  --- original failure ---\n${violation.originalError}` : '') +
-        (userAction ? `\n  Next: ${userAction}` : ''),
-    );
-  }
-  return violation.exitCode;
-}
-
-async function handleSelfTest({ options }: ParsedArgs): Promise<number> {
-  const result = await runSelfTest(options);
-  if (optionFlag(options, 'json')) console.log(JSON.stringify(result, null, 2));
-  else console.log(`MetaMask runner self-test: ${result.status}\nArtifacts: ${result.artifactsDir}`);
-  return result.status === 'pass' ? 0 : 1;
-}
-
-function runtimeOptionsFromCli(options: CliOptions): RuntimeOptions {
-  const recordVideo = options.recordVideo;
-  return {
-    cdpPort: optionString(options, 'cdpPort'),
-    watcherPort: optionString(options, 'watcherPort') ?? optionString(options, 'metroPort'),
-    launchExistingDist: optionFlag(options, 'launchExistingDist'),
-    slot: optionString(options, 'slot'),
-    validationRuntimeDir: optionString(options, 'validationRuntimeDir'),
-    recordVideo: recordVideo === 'full-run' ? 'full-run' : false,
-  };
-}
-
-function parsePort(value: string | undefined, errorMessage: string): number {
-  const port = Number(value);
-  if (!Number.isInteger(port) || port <= 0) throw usageError(errorMessage);
-  return port;
-}
-
-/**
- * Resolve the ordered library sources for a run: the developer's explicit
- * entries (or their personal library) first, then this runner's canonical
- * `library/` appended last so personal/team flows win by default. Returns
- * undefined when the installed harness predates recipe libraries.
- */
-async function resolveMetaMaskLibrarySources(
-  libraryEntry: string | undefined,
-): Promise<MetaMaskLibrarySource[] | undefined> {
-  const harness = (await importRecipeHarness()) as RecipeLibraryCapableHarness;
-  if (typeof harness.resolveRecipeLibrarySources !== 'function') {
-    if (libraryEntry) {
-      throw usageError(
-        '--library requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support / resolveRecipeLibrarySources). ' +
-          'The pinned 0.3.0 lacks it, and npm 0.3.2 still does not export it — recipe-library support is PENDING PUBLISH from farmslot.',
-      );
-    }
-    return undefined;
-  }
-  const sources = await harness.resolveRecipeLibrarySources(
-    libraryEntry ? { cliEntries: [libraryEntry] } : undefined,
-  );
-  sources.push({ name: 'metamask', root: path.join(runnerDir, 'library') });
-  return sources;
-}
-
-function serializeLibrarySources(sources: MetaMaskLibrarySource[]): string {
-  return sources
-    .map((source) => (source.name ? `${source.name}=${source.root}` : source.root))
-    .join(':');
-}
-
-// Map a resolved library source to its precedence tier for the flows legend, from
-// the ACTUAL resolution rather than an invented label: the canonical MetaMask
-// library this runner appends last, the personal library the harness names
-// 'personal', and any other configured library in between as the team/shared tier.
-function flowSourceTier(source: MetaMaskLibrarySource, index: number, total: number): string {
-  if (index === total - 1 && source.name === 'metamask') return 'canonical';
-  if (source.name === 'personal') return 'personal';
-  return 'team';
-}
-
-// The engine's flows subcommands (grounded in registerFlowsCommand): a bare
-// `flows` (or one that leads with a flag) means list.
-const FLOWS_SUBCOMMANDS: readonly string[] = ['list', 'promote'];
-
-// --target is a runner-level flag (checkout selection); the engine's flows
-// subcommands do not accept it and flows resolution is adapter-global (the
-// canonical MetaMask library + the personal library), so it has no effect here.
-// Drop it (with its value) before forwarding so the engine never sees an unknown
-// option. Every other flag/positional forwards verbatim.
-function stripTargetFlag(argv: string[]): string[] {
-  const out: string[] = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--target') {
-      i += 1; // skip the value too
-      continue;
-    }
-    if (arg.startsWith('--target=')) continue;
-    out.push(arg);
-  }
-  return out;
-}
-
-// flows delegates to the harness CLI with the resolved MetaMask default sources
-// exported through RECIPE_LIBRARY_PATH, so list/promote behave exactly like a
-// run's resolution.
-async function handleFlows(argv: string[]): Promise<number> {
-  const sources = await resolveMetaMaskLibrarySources(undefined);
-  if (!sources) {
-    throw usageError(
-      'flows requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support; ' +
-        'flows resolve personal > team > canonical). ' +
-        'Next: update the dependency and run yarn install.',
-    );
-  }
-  const forwarded = stripTargetFlag(argv);
-  const jsonMode = forwarded.includes('--json');
-  // Provenance: flows resolve by precedence — the highest-precedence copy of a ref
-  // wins and shadows lower ones, so a LOCAL library outranks canonical. The listing
-  // below prints `source=<name>` per flow; this legend maps each resolved source to
-  // its tier so that source is decodable. --json reserves stdout for the engine
-  // envelope, so the legend rides stderr only.
-  if (!jsonMode) {
-    console.error(color('label', 'flows resolve by precedence (highest wins; local shadows canonical):'));
-    sources.forEach((source, index) => {
-      const name = source.name ?? path.basename(source.root);
-      console.error(`  ${index + 1}. ${color('cmd', name)} ${color('dim', `[${flowSourceTier(source, index, sources.length)}]`)}`);
-    });
-  }
-  // The engine requires an explicit subcommand. Inspect only the FIRST token: a
-  // real subcommand there is passed through; anything else (empty, or a leading
-  // flag whose VALUE must not be mistaken for a subcommand) defaults to list.
-  const withSubcommand = FLOWS_SUBCOMMANDS.includes(forwarded[0])
-    ? forwarded
-    : ['list', ...forwarded];
-  const { runRecipeHarnessCli } = await importRecipeHarnessCli();
-  const previousLibraryPath = process.env.RECIPE_LIBRARY_PATH;
-  process.env.RECIPE_LIBRARY_PATH = serializeLibrarySources(sources);
-  try {
-    await runRecipeHarnessCli(['flows', ...withSubcommand]);
-  } finally {
-    restoreEnv('RECIPE_LIBRARY_PATH', previousLibraryPath);
-  }
-  return 0;
-}
-
-export async function main(argv: string[]): Promise<number> {
-  const command = argv[0];
-  if (!command || command === '-h' || command === '--help') {
-    usage();
-    return command ? 0 : 2;
-  }
-  if (command === 'flows') return handleFlows(argv.slice(1));
-  // call + completion-candidates parse repeatable/positional args of their own, so
-  // they take raw argv rather than the shared Record-based parseArgs.
-  if (command === 'call') return handleCall(argv.slice(1));
-  if (command === 'completion-candidates') return handleCompletionCandidates(argv.slice(1));
-  // Top-level overlay commands route to handleHarness; the command itself is the
-  // action, so forward argv unchanged.
-  if (OVERLAY_COMMANDS.includes(command)) {
-    const code = await handleHarness(argv);
-    // The overlay defines the action/flow vocabulary — a successful install
-    // invalidates the per-checkout completion cache (dynamic-completions contract).
-    if (code === 0 && command === 'install') {
-      try {
-        invalidateCompletionCache(targetPath(parseArgs(argv.slice(1), command).options));
-      } catch {
-        // Cache invalidation is best-effort; never fail an install on it.
-      }
-    }
-    return code;
-  }
-  // launch/logs/debug/fixtures compose adapter scripts directly and own policy,
-  // healing, teaching, and the --json contract.
-  if (command === 'launch') return handleLaunch(argv.slice(1));
-  if (command === 'stop') return handleStop(argv.slice(1));
-  if (command === 'logs') return handleLogs(argv.slice(1));
-  if (command === 'debug') return handleDebug(argv.slice(1));
-  if (command === 'fixtures') return handleFixtures(argv.slice(1), { runOneNode });
-  const handler = COMMANDS[command];
-  if (!handler) throw new Error(`Unknown command: ${command}`);
-  return handler(parseArgs(argv.slice(1), command));
-}
-
-// Auto-run only when this file IS the process entry (bin/mm-harness execs it
-// directly). The commander front (`src/mm-harness-cli.ts`) sets this flag
-// before importing so it can reuse `main` without triggering a second dispatch.
-if (!(globalThis as Record<string, unknown>).__MM_HARNESS_WRAPPER__) {
-  try {
-    process.exit(await main(process.argv.slice(2)));
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(
-      error !== null && typeof error === 'object' && 'exitCode' in error && typeof (error as Record<string, unknown>).exitCode === 'number'
-        ? (error as { exitCode: number }).exitCode
-        : 1,
-    );
-  }
-}