@deeeed/metamask-harness 0.2.0

package/runner/src/cli.ts

@@ -0,0 +1,1820 @@
+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 { 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 '../../orchestration/extension/ensure-ready.ts';
+import { resolveExtensionId } from '../../orchestration/extension/extension-id.ts';
+import { decideExtensionReadiness } from '../../orchestration/extension/runtime-decision.ts';
+import { decideMobileReadiness } from '../../orchestration/mobile/runtime-decision.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 { usageOut } from './commands/shared.ts';
+
+type CliOptionValue = string | boolean;
+type CliOptions = Record<string, CliOptionValue>;
+
+interface ParsedArgs {
+  positional: string[];
+  options: CliOptions;
+}
+
+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,
+  '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', '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']);
+  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 };
+}
+
+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 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('../../orchestration/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(), 'metamask-recipe-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 = adapterOption(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 = adapterOption(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> {
+  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}\n  Next: pass --adapter mobile|extension|core`,
+    );
+  }
+  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);
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`${result.status} ${adapter} ${result.compatibilityMode} manifest=${actionManifestPath}`);
+    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 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('../../orchestration/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 metamask-recipe extension prepare --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 = `metamask-recipe 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> {
+  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'),
+    });
+    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 (metamask-recipe 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: pass --adapter mobile|extension|core`,
+    );
+  }
+  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).
+// This is the "run validates first" contract, shared by `run --plan` and `call`.
+//
+// NOTE (pinned deps): recipes that reference library flows by `call.ref` need
+// `externalFlowIds` sourced from resolveRecipeLibrarySources, which lands with
+// @farmslot/recipe-harness >= 0.3.3 (pending publish). Until then, self-contained
+// recipes (all in-repo recipes + every one-node `call` recipe) validate fully;
+// library-ref recipes would surface their refs here. Extends when 0.3.3 lands.
+async function validateRecipeAdapterAware(
+  recipe: unknown,
+  manifest: RecipeActionManifestDocument,
+): Promise<RecipeValidationResult> {
+  const { validateRecipeDocument, validateRecipeWithManifest } = await importRecipeProtocol();
+  const schema = validateRecipeDocument(recipe);
+  const withManifest = validateRecipeWithManifest(recipe, manifest);
+  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. Touches nothing and
+// resolves no libraries, so it 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.
+  const validation = manifestOk
+    ? await validateRecipeAdapterAware(recipe, manifest)
+    : { 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 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) {
+    const message = 'call requires <action>. Example: mm-harness call unlock --adapter extension';
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', error: { code: 'USAGE', message } }, null, 2));
+    else console.error(message);
+    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);
+
+  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: [] };
+}
+
+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 porcelain 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);
+  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,
+): number {
+  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: violation.userAction ?? null,
+            originalError: violation.originalError ?? null,
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.error(
+      `✗ mm-harness ${command}: ${violation.message}` +
+        (violation.originalError ? `\n  --- original failure ---\n${violation.originalError}` : '') +
+        (violation.userAction ? `\n  Next: ${violation.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(':');
+}
+
+// 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). ' +
+        'Next: update the dependency and run yarn install.',
+    );
+  }
+  const forwarded = stripTargetFlag(argv);
+  // 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 the porcelain paths and own policy,
+  // healing, teaching, and the --json contract.
+  if (command === 'launch') return handleLaunch(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 (orchestration/porcelain/metamask-recipe
+// execs it directly). The commander front (`runner/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,
+    );
+  }
+}