@deeeed/metamask-harness 0.5.0 → 0.6.0

package/src/harness.ts

@@ -1,797 +0,0 @@
-import { execFileSync, spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { resolveLeafInvoke, shellLeafMissing, missingShellLeafMessage } from './leaf-invoke.ts';
-import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from './paths.ts';
-import type { MetaMaskRecipeAdapter } from './types.ts';
-import { prepareMobile } from './adapters/mobile/prepare.ts';
-
-// The `harness` command moves the recipe-harness skill's runner-locate + dispatch
-// bash (resolve-runner-source.sh + recipe-harness.sh dispatch_adapter_action)
-// into typed runner code. The skill resolved an *external* runner source; inside
-// the runner the root is known, so "resolve runner root" collapses to runnerDir.
-// Everything else — the per-subcommand/platform orchestration file mapping,
-// candidate search order, installed-overlay/installed-script preference, the
-// core delegate, extension runtime-context env, and verbatim arg passthrough —
-// is reproduced exactly so the skill can become a thin caller.
-
-type HarnessAction = 'install' | 'provision' | 'verify' | 'cleanup' | 'live';
-
-const HARNESS_ACTIONS: readonly HarnessAction[] = ['install', 'provision', 'verify', 'cleanup', 'live'];
-const ADAPTERS: readonly MetaMaskRecipeAdapter[] = ['mobile', 'extension', 'core'];
-
-// Mirror of scripts/lib/cli-common.sh valid_adapter_action, restricted to the
-// subcommands this command exposes (core has no app/live lifecycle).
-function isValidAdapterAction(adapter: MetaMaskRecipeAdapter, action: HarnessAction): boolean {
-  if (adapter === 'core') return action === 'install' || action === 'provision' || action === 'verify' || action === 'cleanup';
-  return true;
-}
-
-function harnessUsage(): void {
-  console.error(`mm-harness — install and validate the MetaMask recipe runtime in a checkout.
-
-Run it from inside a MetaMask checkout; the platform (mobile | extension | core)
-is auto-detected from the repo. Pass --platform only to override.
-
-Commands (one copy-pasteable example each):
-  install   Install the recipe harness runtime overlay into the checkout.
-              mm-harness install
-  provision Install the cached Runway mobile dev client (same path as install --runway).
-              mm-harness provision runway ios --adapter mobile
-  verify    Check the harness/runtime is present and healthy (no app launch).
-              mm-harness verify
-  cleanup   Remove the installed harness overlay and restore the checkout.
-              mm-harness cleanup
-
-Options:
-  --platform <mobile|extension|core>   Override auto-detection (alias: --adapter).
-  --target <repo>                      Checkout to operate on (default: current dir).
-  --json                               Machine-readable summary for agents/scripts.
-  -- <args>                            Forward the rest verbatim to the underlying
-                                       script, e.g. -- --platform ios --preflight-mode fast
-                                       (mobile) or -- --cdp-port 6665 (extension).
-
-Examples:
-  mm-harness install                          # inside a checkout, auto-detected
-  mm-harness verify --platform extension
-  mm-harness cleanup --target ../metamask-mobile
-
-core supports install, verify, and cleanup (headless; no live).`);
-}
-
-function failureHint(adapter: MetaMaskRecipeAdapter, action: HarnessAction): string {
-  if (adapter === 'core') {
-    if (action === 'verify') {
-      return `Install the core harness first: mm-harness install --platform core`;
-    }
-    return 'Read the error above for the specific cause, then re-run this command.';
-  }
-  const helper = adapter === 'mobile' ? 'mm-harness launch ios   # or launch android' : 'mm-harness launch';
-  return `Read the error above for the specific cause. To (re)start the runtime, run: ${helper}`;
-}
-
-// has_arg: matches an exact flag or its `flag=value` form.
-function hasArg(args: string[], needle: string): boolean {
-  return args.some((arg) => arg === needle || arg.startsWith(`${needle}=`));
-}
-
-// arg_value: value for `flag value` or `flag=value`, else undefined.
-function argValue(args: string[], needle: string): string | undefined {
-  for (let i = 0; i < args.length; i += 1) {
-    if (args[i] === needle) return args[i + 1];
-    if (args[i].startsWith(`${needle}=`)) return args[i].slice(needle.length + 1);
-  }
-  return undefined;
-}
-
-function shellQuote(value: string): string {
-  return /^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : `'${value.replace(/'/gu, `'\\''`)}'`;
-}
-
-function isAdapter(value: string | undefined): value is MetaMaskRecipeAdapter {
-  return value === 'mobile' || value === 'extension' || value === 'core';
-}
-
-interface ParsedHarnessArgs {
-  // Kept as raw string so invalid values (e.g. --adapter garbage) are not silently
-  // cast to MetaMaskRecipeAdapter; narrowed via isAdapter() at the validation site.
-  adapter?: string;
-  json: boolean;
-  forward: string[];
-}
-
-// Split the adapter selector and --json out of the remaining argv so they are not
-// forwarded to the orchestration script (the .sh/.mjs scripts reject unknown
-// flags; Mobile's live/verify use --platform ios|android, so only the first
-// --platform whose value is an adapter is consumed here and a later --platform is
-// passed through). `--` forces everything after it to passthrough.
-function parseHarnessArgs(args: string[]): ParsedHarnessArgs {
-  const forward: string[] = [];
-  let adapter: string | undefined;
-  let json = false;
-  let separator = false;
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    // POSIX: everything after `--` is literal; check separator FIRST so that
-    // --json appearing after `--` is forwarded verbatim to the delegate.
-    if (separator) {
-      forward.push(arg);
-      continue;
-    }
-    if (arg === '--') {
-      separator = true;
-      continue;
-    }
-    if (arg === '--json') {
-      json = true;
-      continue;
-    }
-    if (arg === '--adapter' || arg === '--platform') {
-      const value = args[i + 1];
-      if (arg === '--adapter') {
-        adapter = value;
-        i += 1;
-        continue;
-      }
-      if (adapter === undefined && isAdapter(value)) {
-        adapter = value;
-        i += 1;
-        continue;
-      }
-      forward.push(arg);
-      continue;
-    }
-    if (arg.startsWith('--adapter=')) {
-      adapter = arg.slice('--adapter='.length);
-      continue;
-    }
-    if (arg.startsWith('--platform=')) {
-      const value = arg.slice('--platform='.length);
-      if (adapter === undefined && isAdapter(value)) {
-        adapter = value;
-        continue;
-      }
-      forward.push(arg);
-      continue;
-    }
-    forward.push(arg);
-  }
-  return { adapter, json, forward };
-}
-
-// Mirror of scripts/lib/cli-common.sh detect_adapter for the auto-detect path.
-// Exported so `doctor` shares the exact same detect-from-target logic as the
-// overlay commands (verify/install/cleanup) — one auto-detect story, no drift.
-// Both escapes from a failed repo-type detection: where to run it (checkout/target)
-// and how to force it (adapter). A single source so every detect-failure teaches
-// the same reachable next step.
-export const ADAPTER_DETECT_NEXT =
-  'cd into a MetaMask checkout or pass --target <path>, or force it with --adapter <mobile|extension|core>';
-
-export function detectAdapter(target: string): MetaMaskRecipeAdapter | undefined {
-  let remote = '';
-  try {
-    remote = execFileSync('git', ['-C', target, 'config', '--get', 'remote.origin.url'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-  } catch {
-    remote = '';
-  }
-  if (remote.includes('metamask-extension')) return 'extension';
-  if (remote.includes('metamask-mobile')) return 'mobile';
-
-  const exists = (rel: string): boolean => fs.existsSync(path.join(target, rel));
-  const isDir = (rel: string): boolean => {
-    try {
-      return fs.statSync(path.join(target, rel)).isDirectory();
-    } catch {
-      return false;
-    }
-  };
-
-  if (exists('development/skills-sync.ts') || (isDir('ui') && isDir('app/scripts'))) return 'extension';
-  if (exists('scripts/skills-sync.mts') || (isDir('ios') && isDir('android') && isDir('app/core'))) return 'mobile';
-  if (isDir('packages/perps-controller') && exists('yarn.lock')) return 'core';
-  return undefined;
-}
-
-// Resolve the agentic-runtime.json path for a checkout: the RECIPE_RUNTIME_CONTEXT
-// override wins, else the per-checkout runtime dir. Single source shared by the
-// extension pre-dispatch hydration and doctor's runtime-context report.
-export function resolveRuntimeContextPath(target: string): string {
-  return process.env.RECIPE_RUNTIME_CONTEXT ?? path.join(target, recipeRuntimeDir(), 'agentic-runtime.json');
-}
-
-// read_runtime_context_field: dotted lookup returning the value only when it is a
-// present, non-empty scalar; undefined when the file/field is missing.
-export function readRuntimeContextField(contextPath: string, field: string): string | undefined {
-  let data: unknown;
-  try {
-    data = JSON.parse(fs.readFileSync(contextPath, 'utf8'));
-  } catch {
-    return undefined;
-  }
-  let node: unknown = data;
-  for (const key of field.split('.')) {
-    if (node === undefined || node === null || typeof node !== 'object') return undefined;
-    node = (node as Record<string, unknown>)[key];
-  }
-  if (node === undefined || node === null || node === '') return undefined;
-  return String(node);
-}
-
-// Port of recipe-harness.sh's extension pre-dispatch block: hydrate runtime env
-// from agentic-runtime.json and append --cdp-port / --prepare-cmd to the args
-// exactly as the skill did (extension launch/live/verify; here live/verify).
-function applyExtensionRuntimeEnv(target: string, action: HarnessAction, args: string[]): string[] {
-  const contextPath = resolveRuntimeContextPath(target);
-  const contextExists = fs.existsSync(contextPath);
-
-  if (contextExists) {
-    process.env.RECIPE_RUNTIME_CONTEXT = contextPath;
-    if (!process.env.RECIPE_SLOT_ID) {
-      const slotId = readRuntimeContextField(contextPath, 'slotId');
-      if (slotId) process.env.RECIPE_SLOT_ID = slotId;
-    }
-    if (!process.env.RECIPE_HARNESS_EXTENSION_ID) {
-      const extensionId = readRuntimeContextField(contextPath, 'extensionId');
-      if (extensionId) process.env.RECIPE_HARNESS_EXTENSION_ID = extensionId;
-    }
-    if (process.env.RECIPE_RUNTIME_START_APPROVED === undefined) {
-      const approved = readRuntimeContextField(contextPath, 'runtimeStart.approved');
-      if (approved === 'true' || approved === 'True' || approved === '1') process.env.RECIPE_RUNTIME_START_APPROVED = '1';
-      else if (approved === 'false' || approved === 'False' || approved === '0') process.env.RECIPE_RUNTIME_START_APPROVED = '0';
-    }
-    if (!process.env.RECIPE_RUNTIME_START_CMD) {
-      const command = readRuntimeContextField(contextPath, 'runtimeStart.command');
-      if (command) process.env.RECIPE_RUNTIME_START_CMD = command;
-    }
-    if (!process.env.RECIPE_RUNTIME_READY_URL) {
-      const readyUrl = readRuntimeContextField(contextPath, 'runtimeStart.readyUrl');
-      if (readyUrl) process.env.RECIPE_RUNTIME_READY_URL = readyUrl;
-    }
-  }
-
-  let result = [...args];
-  if (!hasArg(result, '--cdp-port')) {
-    const contextPort = contextExists ? readRuntimeContextField(contextPath, 'cdpPort') : undefined;
-    const cdpPort = contextPort ?? process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
-    if (cdpPort) {
-      process.env.RECIPE_CDP_PORT = cdpPort;
-      process.env.CDP_PORT = cdpPort;
-      result = [...result, '--cdp-port', cdpPort];
-    }
-  }
-  if (action === 'live' && !hasArg(result, '--prepare-cmd')) {
-    if (process.env.RECIPE_RUNTIME_START_APPROVED === '1' && process.env.RECIPE_RUNTIME_START_CMD) {
-      result = [...result, '--prepare-cmd', process.env.RECIPE_RUNTIME_START_CMD];
-    }
-  }
-  return result;
-}
-
-// runner_executable_entry / runner_file_entry: first candidate that exists (as an
-// executable, or as any file) wins; otherwise the first candidate is returned so
-// the exec error names it.
-function resolveEntry(base: string, candidates: string[], mode: 'exec' | 'file'): string {
-  for (const candidate of candidates) {
-    const full = path.join(base, candidate);
-    try {
-      const stat = fs.statSync(full);
-      if (!stat.isFile()) continue;
-      if (mode === 'file' || (stat.mode & 0o111) !== 0) return full;
-    } catch {
-      // missing candidate; try the next one
-    }
-  }
-  return path.join(base, candidates[0]);
-}
-
-// Content of an installed overlay's runner source pointer, if present. Command
-// substitution in the skill stripped trailing newlines, so trim here too.
-// Validates the path exists so stale stamps (e.g. from a renamed package dir)
-// fall back to the current runnerDir rather than producing ENOENT at cleanup.
-function installedRunnerSource(target: string, adapter: MetaMaskRecipeAdapter): string | undefined {
-  const pointer = path.join(recipeHarnessPath(target, adapter), 'runner', '.runner-source');
-  if (!fs.existsSync(pointer)) return undefined;
-  const value = fs.readFileSync(pointer, 'utf8').trim();
-  if (!value || !fs.existsSync(value)) return undefined;
-  return value;
-}
-
-function isExecutable(file: string): boolean {
-  try {
-    const stat = fs.statSync(file);
-    return stat.isFile() && (stat.mode & 0o111) !== 0;
-  } catch {
-    return false;
-  }
-}
-
-interface HarnessDispatch {
-  command: string;
-  prefixArgs: string[];
-}
-
-const INJECT_CANDIDATES: Record<MetaMaskRecipeAdapter, { entry: string; fallback: string }> = {
-  mobile: { entry: 'adapters/mobile/inject.sh', fallback: 'scripts/inject-mobile-harness.sh' },
-  extension: { entry: 'adapters/extension/inject.mjs', fallback: 'scripts/inject-extension-harness.mjs' },
-  core: { entry: 'adapters/core/inject.sh', fallback: 'scripts/inject-core-harness.sh' },
-};
-
-const CLEANUP_CANDIDATES: Record<MetaMaskRecipeAdapter, { entry: string; fallback: string }> = {
-  mobile: { entry: 'adapters/mobile/cleanup.sh', fallback: 'scripts/cleanup-mobile-harness.sh' },
-  extension: { entry: 'adapters/extension/cleanup.mjs', fallback: 'scripts/cleanup-extension-harness.mjs' },
-  core: { entry: 'adapters/core/cleanup.sh', fallback: 'scripts/cleanup-core-harness.sh' },
-};
-
-// Resolve the exact command + fixed prefix args to exec, mirroring
-// recipe-harness.sh dispatch_adapter_action. forwardArgs are appended by the
-// caller. Returns a string message for the one fail-fast case (missing core
-// delegate) that the skill handled inline.
-function resolveHarnessDispatch(
-  adapter: MetaMaskRecipeAdapter,
-  action: HarnessAction,
-  target: string,
-): HarnessDispatch | { error: string } {
-  if (action === 'install') {
-    const { entry, fallback } = INJECT_CANDIDATES[adapter];
-    if (adapter === 'extension') {
-      return { command: process.execPath, prefixArgs: [resolveEntry(runnerDir, [entry, fallback], 'file')] };
-    }
-    // Shell leaves are invoked through bash; file existence is the only requirement.
-    return { command: resolveEntry(runnerDir, [entry, fallback], 'file'), prefixArgs: [] };
-  }
-
-  if (action === 'cleanup') {
-    const { entry, fallback } = CLEANUP_CANDIDATES[adapter];
-    const base = installedRunnerSource(target, adapter) ?? runnerDir;
-    if (adapter === 'extension') {
-      return { command: process.execPath, prefixArgs: [resolveEntry(base, [entry, fallback], 'file')] };
-    }
-    return { command: resolveEntry(base, [entry, fallback], 'file'), prefixArgs: [] };
-  }
-
-  if (adapter === 'core' && action === 'verify') {
-    const delegate = path.join(recipeHarnessPath(target, 'core'), 'runner', 'bin', 'mm-harness');
-    if (!isExecutable(delegate)) {
-      return {
-        error:
-          `core recipe harness not installed: missing delegate ${delegate}.\n` +
-          `Next: mm-harness install --platform core --target ${target}`,
-      };
-    }
-    // --target is carried in forwardArgs (injected when the caller omits it), so
-    // the delegate still receives `doctor --adapter core --target <t>`.
-    return { command: delegate, prefixArgs: ['doctor', '--adapter', 'core'] };
-  }
-
-  // mobile/extension live|verify: prefer the installed helper (any mode), else
-  // the runner's own adapters/scripts candidate. Bash invocation makes +x irrelevant.
-  const installedScript = path.join(recipeHarnessPath(target, adapter), 'scripts', `${action}.sh`);
-  if (fs.existsSync(installedScript)) {
-    return { command: installedScript, prefixArgs: [] };
-  }
-  const command = resolveEntry(
-    runnerDir,
-    [`adapters/${adapter}/${action}.sh`, `scripts/${adapter}/${action}.sh`],
-    'file',
-  );
-  return { command, prefixArgs: [] };
-}
-
-// Mobile live: prepare device in-process then run the verify leaf.
-// Replaces the retired live.sh → launch.sh → mm-harness-mobile-prepare chain.
-// Control flows down only: TS calls prepareMobile(), then spawns verify.sh.
-async function handleMobileLive(
-  target: string,
-  forwardArgs: string[],
-  json: boolean,
-  autoDetected: boolean,
-): Promise<number> {
-  const platform = argValue(forwardArgs, '--platform') ?? 'ios';
-  const watcherPortStr = argValue(forwardArgs, '--watcher-port') ?? process.env.WATCHER_PORT;
-  const watcherPort = watcherPortStr ? parseInt(watcherPortStr, 10) : undefined;
-  const start = Date.now();
-
-  if (!json) {
-    const detected = autoDetected ? ', auto-detected' : '';
-    console.error(`→ live (mobile${detected}) — target: ${target}`);
-  }
-
-  const prepResult = await prepareMobile(target, { platform, json, watcherPort });
-  if (prepResult.status !== 0) {
-    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
-    if (json) {
-      console.log(
-        harnessSummary('live', 'mobile', target, 'fail', prepResult.status, autoDetected, {
-          code: 'MOBILE_PREPARE_FAILED',
-          message: `mobile prepare failed (exit ${prepResult.status})`,
-          userAction: failureHint('mobile', 'live'),
-        }),
-      );
-    } else {
-      console.error(
-        `✗ live mobile failed (exit ${prepResult.status}, ${elapsed}s)\n  ${failureHint('mobile', 'live')}`,
-      );
-    }
-    return prepResult.status;
-  }
-
-  // Verify leaf: --no-auto-start because launch already started the app.
-  const installedVerify = path.join(recipeHarnessPath(target, 'mobile'), 'scripts', 'verify.sh');
-  const verifySh = fs.existsSync(installedVerify)
-    ? installedVerify
-    : resolveEntry(runnerDir, ['adapters/mobile/verify.sh', 'scripts/mobile/verify.sh'], 'file');
-
-  const verifyArgs = hasArg(forwardArgs, '--no-auto-start')
-    ? [...forwardArgs]
-    : ['--no-auto-start', ...forwardArgs];
-
-  if (shellLeafMissing(verifySh)) {
-    const message = missingShellLeafMessage(verifySh);
-    if (json) {
-      console.log(
-        harnessSummary('live', 'mobile', target, 'fail', 1, autoDetected, {
-          code: 'HARNESS_SPAWN_FAILED',
-          message,
-          userAction: failureHint('mobile', 'live'),
-        }),
-      );
-    } else {
-      console.error(`✗ ${message}`);
-    }
-    return 1;
-  }
-
-  const { bin: verifyBin, args: verifySpawnArgs } = resolveLeafInvoke(verifySh, verifyArgs);
-  const result = spawnSync(verifyBin, verifySpawnArgs, {
-    stdio: json ? ['inherit', 2, 'inherit'] : 'inherit',
-    env: process.env,
-  });
-  const elapsed = ((Date.now() - start) / 1000).toFixed(1);
-  const exitCode = result.status ?? 1;
-
-  if (json) {
-    console.log(
-      harnessSummary(
-        'live',
-        'mobile',
-        target,
-        exitCode === 0 ? 'pass' : 'fail',
-        exitCode,
-        autoDetected,
-        exitCode === 0
-          ? undefined
-          : { code: 'MOBILE_VERIFY_FAILED', message: `mobile live verify failed (exit ${exitCode})`, userAction: failureHint('mobile', 'live') },
-      ),
-    );
-  } else if (exitCode === 0) {
-    console.error(`✓ live mobile passed (${elapsed}s)`);
-  } else {
-    console.error(
-      `✗ live mobile failed (exit ${exitCode}, ${elapsed}s)\n  ${failureHint('mobile', 'live')}`,
-    );
-  }
-  return exitCode;
-}
-
-export async function handleHarness(argv: string[]): Promise<number> {
-  const action = argv[0];
-  if (!action || action === '-h' || action === '--help') {
-    harnessUsage();
-    return action ? 0 : 2;
-  }
-  if (!HARNESS_ACTIONS.includes(action as HarnessAction)) {
-    harnessUsage();
-    console.error(`unsupported harness subcommand: ${action}`);
-    return 2;
-  }
-  const harnessAction = action as HarnessAction;
-
-  const { adapter: parsedAdapter, json, forward } = parseHarnessArgs(argv.slice(1));
-  const rawTarget = argValue(forward, '--target');
-  const target = path.resolve(rawTarget ?? process.cwd());
-
-  const adapter = parsedAdapter ?? detectAdapter(target);
-  // isAdapter() narrows adapter to MetaMaskRecipeAdapter for all code below.
-  if (!adapter || !isAdapter(adapter)) {
-    if (json) {
-      // parsedAdapter is string|undefined here; not yet validated as a real
-      // adapter, so pass undefined rather than forwarding a garbage string.
-      const detectError = adapter
-        ? { code: 'UNSUPPORTED_PLATFORM', message: `unsupported platform: ${adapter}`, userAction: 'pass --adapter <mobile|extension|core> to specify a supported adapter' }
-        : { code: 'ADAPTER_DETECTION_FAILED', message: `could not detect the MetaMask repo type for ${target}`, userAction: ADAPTER_DETECT_NEXT };
-      console.log(harnessSummary(harnessAction, undefined, target, 'fail', 2, false, detectError));
-    } else {
-      harnessUsage();
-      console.error(
-        adapter
-          ? `\n✗ unsupported platform: ${adapter}`
-          : `\n✗ could not detect the MetaMask repo type for ${target}\n  Next: ${ADAPTER_DETECT_NEXT}`,
-      );
-    }
-    return 2;
-  }
-  if (!isValidAdapterAction(adapter, harnessAction)) {
-    if (json) {
-      console.log(
-        harnessSummary(harnessAction, adapter, target, 'fail', 2, parsedAdapter === undefined, {
-          code: 'UNSUPPORTED_ACTION',
-          message: `${harnessAction} is not supported for ${adapter} (core supports install, verify, cleanup).`,
-          userAction: 'run mm-harness doctor to see which actions are supported for this adapter',
-        }),
-      );
-    } else {
-      console.error(
-        `✗ ${harnessAction} is not supported for ${adapter} (core supports install, verify, cleanup).`,
-      );
-    }
-    return 2;
-  }
-  const autoDetected = parsedAdapter === undefined;
-
-  // Forward args carry --target so the orchestration script resolves the same
-  // checkout; inject the resolved path only when the caller omitted it.
-  let forwardArgs = hasArg(forward, '--target') ? [...forward] : ['--target', target, ...forward];
-
-  if (harnessAction === 'provision') {
-    return handleRunwayInstall(adapter, target, provisionRunwayForward(forward), json, 'provision');
-  }
-
-  if (harnessAction === 'install' && hasArg(forward, '--runway')) {
-    return handleRunwayInstall(adapter, target, forward, json, 'install');
-  }
-
-  if (adapter === 'extension' && (harnessAction === 'live' || harnessAction === 'verify')) {
-    forwardArgs = applyExtensionRuntimeEnv(target, harnessAction, forwardArgs);
-  }
-
-  // Mobile live is orchestrated in-process (prepareMobile → verify.sh leaf).
-  if (adapter === 'mobile' && harnessAction === 'live') {
-    return handleMobileLive(target, forwardArgs, json, autoDetected);
-  }
-
-  const dispatch = resolveHarnessDispatch(adapter, harnessAction, target);
-  if ('error' in dispatch) {
-    if (json) {
-      console.log(
-        harnessSummary(harnessAction, adapter, target, 'fail', 1, autoDetected, {
-          code: 'DISPATCH_UNAVAILABLE',
-          message: dispatch.error,
-          // The dispatch error embeds "Next: <hint>" — extract it so --json consumers
-          // get a clean programmatic escape without parsing the human message.
-          userAction: dispatch.error.split('\nNext: ')[1] ?? 'run mm-harness install to complete setup, then retry',
-        }),
-      );
-    } else {
-      console.error(`✗ ${harnessAction} ${adapter} failed\n  ${dispatch.error.replace(/\n/gu, '\n  ')}`);
-    }
-    return 1;
-  }
-
-  if (!json) {
-    const detected = autoDetected ? ', auto-detected' : '';
-    console.error(`→ ${harnessAction} (${adapter}${detected}) — target: ${target}`);
-  }
-
-  const start = Date.now();
-
-  // Shell leaves need bash invocation; bash exits 127 (not ENOENT) for missing files.
-  if (shellLeafMissing(dispatch.command)) {
-    const message = missingShellLeafMessage(dispatch.command);
-    if (json) {
-      console.log(
-        harnessSummary(harnessAction, adapter, target, 'fail', 1, autoDetected, {
-          code: 'HARNESS_SPAWN_FAILED',
-          message,
-          userAction: failureHint(adapter, harnessAction),
-        }),
-      );
-    } else {
-      console.error(`✗ ${message}`);
-    }
-    return 1;
-  }
-
-  const { bin: dispatchBin, args: dispatchArgs } = resolveLeafInvoke(dispatch.command, [
-    ...dispatch.prefixArgs,
-    ...forwardArgs,
-  ]);
-  const result = spawnSync(dispatchBin, dispatchArgs, {
-    // Default: stream child output verbatim (byte-identical to the skill path).
-    // --json: route child output to our stderr so stdout carries only the summary.
-    stdio: json ? ['inherit', 2, 'inherit'] : 'inherit',
-    env: process.env,
-  });
-  const seconds = ((Date.now() - start) / 1000).toFixed(1);
-
-  if (result.error) {
-    if (json) {
-      console.log(
-        harnessSummary(harnessAction, adapter, target, 'fail', 1, autoDetected, {
-          code: 'HARNESS_SPAWN_FAILED',
-          message: `${harnessAction} ${adapter} could not start: ${result.error.message}`,
-          userAction: failureHint(adapter, harnessAction),
-        }),
-      );
-    } else {
-      console.error(`✗ ${harnessAction} ${adapter} could not start: ${result.error.message}\n  ${failureHint(adapter, harnessAction)}`);
-    }
-    return 1;
-  }
-
-  const exitCode = result.status ?? 1;
-  if (json) {
-    console.log(
-      harnessSummary(
-        harnessAction,
-        adapter,
-        target,
-        exitCode === 0 ? 'pass' : 'fail',
-        exitCode,
-        autoDetected,
-        exitCode === 0
-          ? undefined
-          : { code: 'HARNESS_FAILED', message: `${harnessAction} ${adapter} failed (exit ${exitCode})`, userAction: failureHint(adapter, harnessAction) },
-      ),
-    );
-  } else if (exitCode === 0) {
-    console.error(`✓ ${harnessAction} ${adapter} passed (${seconds}s)`);
-  } else {
-    console.error(`✗ ${harnessAction} ${adapter} failed (exit ${exitCode}, ${seconds}s)\n  ${failureHint(adapter, harnessAction)}`);
-  }
-  return exitCode;
-}
-
-async function handleRunwayInstall(
-  adapter: MetaMaskRecipeAdapter,
-  target: string,
-  forward: string[],
-  json: boolean,
-  action: 'install' | 'provision',
-): Promise<number> {
-  const { getAdapterSurface } = await import('./adapters/surface.ts');
-  const rerunCommand = action === 'provision'
-    ? runwayProvisionRerunCommand(adapter, target, forward, json)
-    : runwayInstallRerunCommand(adapter, target, forward, json);
-  const surface = getAdapterSurface(adapter);
-  const runtimeDir = argValue(forward, '--runtime-dir');
-  const watcherPort = argValue(forward, '--watcher-port');
-  const result = await surface.runwayProvision.run(target, {
-    json,
-    platform: argValue(forward, '--platform') ?? 'ios',
-    branch: argValue(forward, '--branch'),
-    defaultBranch: argValue(forward, '--default-branch'),
-    run: argValue(forward, '--run'),
-    cacheRoot: argValue(forward, '--cache-root'),
-    simulator: argValue(forward, '--simulator') ?? argValue(forward, '--device'),
-    runtime: argValue(forward, '--runtime'),
-    deviceType: argValue(forward, '--device-type'),
-    slot: argValue(forward, '--slot'),
-    watcherPort,
-    runtimeDir,
-    force: hasArg(forward, '--force'),
-    resolveOnly: hasArg(forward, '--resolve-only'),
-    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 Runway app for ${adapter} ${result.platform ?? ''} run=${artifact?.runId ?? 'unknown'} revision=${artifact?.revision ?? 'unknown'} artifact=${artifact?.artifactName ?? 'unknown'}`);
-    } else {
-      const action = result.skipped ? 'already provisioned' : 'installed Runway app';
-      console.error(`✓ ${action} for ${adapter} ${result.platform ?? ''} simulator=${simulator?.name ?? 'unknown'} cache=${cache?.status ?? 'skip'}`);
-    }
-  } else {
-    const label = action === 'provision' ? 'provision' : 'install --runway';
-    console.error(`✗ mm-harness ${label}: ${result.error?.message ?? 'runway install failed'}\n  Next: ${result.error?.userAction ?? rerunCommand}`);
-  }
-  return result.exitCode;
-}
-
-function provisionRunwayForward(forward: string[]): string[] {
-  const normalized: string[] = [];
-  let index = 0;
-  if (forward[index] === 'runway') index += 1;
-  if (forward[index] && !forward[index].startsWith('-')) {
-    if (!hasArg(forward, '--platform')) normalized.push('--platform', forward[index]);
-    index += 1;
-  }
-  return [...normalized, ...forward.slice(index)];
-}
-
-function runwayInstallRerunCommand(
-  adapter: MetaMaskRecipeAdapter,
-  target: string,
-  forward: string[],
-  json: boolean,
-): string {
-  const parts = ['mm-harness', 'install', '--runway', '--adapter', adapter, '--target', shellQuote(target)];
-  const valueFlags = [
-    '--platform',
-    '--branch',
-    '--default-branch',
-    '--run',
-    '--cache-root',
-    '--simulator',
-    '--device',
-    '--slot',
-    '--watcher-port',
-    '--runtime-dir',
-    '--runtime',
-    '--device-type',
-  ];
-  for (const flag of valueFlags) {
-    const value = argValue(forward, flag);
-    if (value) parts.push(flag, shellQuote(value));
-  }
-  if (hasArg(forward, '--force')) parts.push('--force');
-  if (hasArg(forward, '--resolve-only')) parts.push('--resolve-only');
-  if (json) parts.push('--json');
-  return parts.join(' ');
-}
-
-function runwayProvisionRerunCommand(
-  adapter: MetaMaskRecipeAdapter,
-  target: string,
-  forward: string[],
-  json: boolean,
-): string {
-  const parts = ['mm-harness', 'provision', 'runway', shellQuote(argValue(forward, '--platform') ?? 'ios'), '--adapter', adapter, '--target', shellQuote(target)];
-  const valueFlags = [
-    '--branch',
-    '--default-branch',
-    '--run',
-    '--cache-root',
-    '--simulator',
-    '--device',
-    '--slot',
-    '--watcher-port',
-    '--runtime-dir',
-    '--runtime',
-    '--device-type',
-  ];
-  for (const flag of valueFlags) {
-    const value = argValue(forward, flag);
-    if (value) parts.push(flag, shellQuote(value));
-  }
-  if (hasArg(forward, '--force')) parts.push('--force');
-  if (hasArg(forward, '--resolve-only')) parts.push('--resolve-only');
-  if (json) parts.push('--json');
-  return parts.join(' ');
-}
-
-// userAction is required whenever an error object is present so every --json
-// failure carries a machine-readable escape path — parallel to the `usageOut`
-// enforcement on the CLI layer. Omitting userAction is a compile-time error.
-function harnessSummary(
-  action: HarnessAction,
-  adapter: MetaMaskRecipeAdapter | undefined,
-  target: string,
-  status: 'pass' | 'fail',
-  exitCode: number,
-  autoDetected: boolean,
-  error?: { code: string; message: string; userAction: string },
-): string {
-  return JSON.stringify({
-    schemaVersion: 1,
-    command: 'harness',
-    action,
-    adapter: adapter ?? null,
-    target,
-    autoDetected,
-    status,
-    exitCode,
-    // Error contract: every --json failure carries a stable machine code + human
-    // message (CLI-SPEC.md §5.1). userAction is included when present so callers
-    // can surface the reachable escape without parsing the human message.
-    ...(status === 'fail' && error ? { error } : {}),
-  });
-}