@deeeed/metamask-harness 0.2.0

package/runner/src/harness.ts

@@ -0,0 +1,516 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from './paths.ts';
+import type { MetaMaskRecipeAdapter } from './types.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' | 'verify' | 'cleanup' | 'live';
+
+const HARNESS_ACTIONS: readonly HarnessAction[] = ['install', '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 === '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
+  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 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.
+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.
+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();
+  return value || undefined;
+}
+
+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: 'orchestration/mobile/inject.sh', fallback: 'scripts/inject-mobile-harness.sh' },
+  extension: { entry: 'orchestration/extension/inject.mjs', fallback: 'scripts/inject-extension-harness.mjs' },
+  core: { entry: 'orchestration/core/inject.sh', fallback: 'scripts/inject-core-harness.sh' },
+};
+
+const CLEANUP_CANDIDATES: Record<MetaMaskRecipeAdapter, { entry: string; fallback: string }> = {
+  mobile: { entry: 'orchestration/mobile/cleanup.sh', fallback: 'scripts/cleanup-mobile-harness.sh' },
+  extension: { entry: 'orchestration/extension/cleanup.mjs', fallback: 'scripts/cleanup-extension-harness.mjs' },
+  core: { entry: 'orchestration/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')] };
+    }
+    return { command: resolveEntry(runnerDir, [entry, fallback], 'exec'), 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], 'exec'), prefixArgs: [] };
+  }
+
+  if (adapter === 'core' && action === 'verify') {
+    const delegate = path.join(recipeHarnessPath(target, 'core'), 'runner', 'bin', 'metamask-recipe');
+    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, else the runner's
+  // own orchestration/runner/scripts helper (first executable candidate wins).
+  const installedScript = path.join(recipeHarnessPath(target, adapter), 'scripts', `${action}.sh`);
+  if (isExecutable(installedScript)) {
+    return { command: installedScript, prefixArgs: [] };
+  }
+  const command = resolveEntry(
+    runnerDir,
+    [`orchestration/${adapter}/${action}.sh`, `runner/${adapter}/${action}.sh`, `scripts/${adapter}/${action}.sh`],
+    'exec',
+  );
+  return { command, prefixArgs: [] };
+}
+
+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}` }
+        : { code: 'ADAPTER_DETECTION_FAILED', message: `could not detect the MetaMask repo type for ${target}` };
+      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: pass --platform mobile|extension|core`,
+      );
+    }
+    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).`,
+        }),
+      );
+    } 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 (adapter === 'extension' && (harnessAction === 'live' || harnessAction === 'verify')) {
+    forwardArgs = applyExtensionRuntimeEnv(target, harnessAction, forwardArgs);
+  }
+
+  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,
+        }),
+      );
+    } 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();
+  const result = spawnSync(dispatch.command, [...dispatch.prefixArgs, ...forwardArgs], {
+    // 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}`,
+        }),
+      );
+    } 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})` },
+      ),
+    );
+  } 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;
+}
+
+function harnessSummary(
+  action: HarnessAction,
+  adapter: MetaMaskRecipeAdapter | undefined,
+  target: string,
+  status: 'pass' | 'fail',
+  exitCode: number,
+  autoDetected: boolean,
+  error?: { code: string; message: 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).
+    ...(status === 'fail' && error ? { error } : {}),
+  });
+}

package/runner/src/heal-bounds.ts

@@ -0,0 +1,179 @@
+// Healing policy + recovery bounds — shared by launch, run, and call (policy, not
+// per-command). Owns: overlay auto-ensure, failure classification, the recovery
+// bounds that stop blind retry loops, and the --heal parser.
+//
+// Overlay auto-ensure seam (overridable for CI/agents and contract tests):
+//   MM_HARNESS_INSTALL_BIN — overlay installer (default: handleHarness install)
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+
+import { handleHarness } from './harness.ts';
+import { recipeHarnessPath, recipeRuntimePath } from './paths.ts';
+import type { MetaMaskRecipeAdapter } from './types.ts';
+import { EXIT } from './commands/shared.ts';
+import type { DeviceAdapter } from './commands/shared.ts';
+
+export type HealPolicy = 'off' | 'infra-only' | 'auto';
+
+interface Mutation {
+  type: string;
+  action: string;
+  [key: string]: unknown;
+}
+
+export interface HealState {
+  recovered: string[];
+  mutations: Mutation[];
+  attemptedRecoveries: string[];
+}
+
+export function newHealState(): HealState {
+  return { recovered: [], mutations: [], attemptedRecoveries: [] };
+}
+
+export function parseHeal(
+  options: Record<string, string | boolean>,
+  fallback: HealPolicy,
+): HealPolicy | { error: string } {
+  const value = options.heal;
+  if (value === undefined) return fallback;
+  if (value === 'off' || value === 'infra-only' || value === 'auto') return value;
+  return { error: `--heal must be off, infra-only, or auto (got "${String(value)}").` };
+}
+
+function overlayDir(target: string, adapter: MetaMaskRecipeAdapter): string {
+  return recipeHarnessPath(target, adapter);
+}
+
+function overlayPresent(target: string, adapter: MetaMaskRecipeAdapter): boolean {
+  try {
+    return fs.statSync(overlayDir(target, adapter)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Auto-ensure the runtime overlay (install phase). Missing + heal != off →
+// install inline, emit a first-install notice to stderr, and record the mutation.
+// heal === off disables auto-install (repro-preserving); we proceed and let the
+// porcelain surface any missing-overlay failure itself.
+export async function ensureOverlay(
+  adapter: MetaMaskRecipeAdapter,
+  target: string,
+  heal: HealPolicy,
+  state: HealState,
+  json: boolean,
+): Promise<{ ok: boolean; error?: string }> {
+  // core is headless — the engine path used by run/call needs no launch overlay.
+  if (adapter === 'core') return { ok: true };
+  if (overlayPresent(target, adapter)) return { ok: true };
+  if (heal === 'off') return { ok: true };
+
+  const installBin = process.env.MM_HARNESS_INSTALL_BIN;
+  let code: number;
+  if (installBin) {
+    const result = spawnSync(installBin, ['install', '--platform', adapter, '--target', target], {
+      cwd: target,
+      stdio: ['ignore', 2, 'inherit'],
+      env: process.env,
+    });
+    code = result.status ?? 1;
+  } else {
+    code = await handleHarness(['install', '--platform', adapter, '--target', target, ...(json ? ['--json'] : [])]);
+  }
+  if (code !== 0 || !overlayPresent(target, adapter)) {
+    return { ok: false, error: `runtime overlay install failed (exit ${code})` };
+  }
+  const dir = overlayDir(target, adapter);
+  state.mutations.push({ type: 'file', action: 'created', path: dir });
+  // First-install notice → stderr (human) / mutations[] only (json; stdout clean).
+  if (!json) process.stderr.write(`installed mm-harness overlay → ${dir}\n`);
+  return { ok: true };
+}
+
+// A recovery that would need a seeded wallet is NEVER auto-performed (healing
+// never touches fixtures). Only POSITIVELY-IDENTIFIED infra transport failures
+// are healable. Unknown/unclassified failures → 'app' (safe default: no healing
+// attempted, failure surfaced verbatim). Defaulting to 'infra' would cause
+// self-healing to mask real app-logic breakage.
+export function classifyFailure(output: string): 'wallet' | 'infra' | 'app' {
+  if (/wallet|fixture|keyring|not seeded|\bsrp\b|password|onboard/iu.test(output)) return 'wallet';
+  if (/metro|cdp|chrome|bundle|packager|port\b|econnrefused|not reachable|watcher|dev client|websocket/iu.test(output)) {
+    return 'infra';
+  }
+  return 'app';
+}
+
+// Refuse ALL recovery while a recipe is executing (mid-run recovery would corrupt
+// state). Signalled by a lock file or MM_HARNESS_RECIPE_RUNNING=1.
+export function recipeRunning(target: string): boolean {
+  if (process.env.MM_HARNESS_RECIPE_RUNNING === '1') return true;
+  return fs.existsSync(recipeRuntimePath(target, 'recipe.lock'));
+}
+
+// Stable recovery codes for the launch infra retry (surfaced in recovered[]).
+export const RECOVERY_CODE: Record<DeviceAdapter, string> = {
+  mobile: 'metro.restarted',
+  extension: 'chrome.reopened',
+};
+
+export interface HealBoundViolation {
+  code: string;
+  exitCode: number;
+  message: string;
+  userAction?: string;
+  // The ORIGINAL failure output that drove this classification, carried verbatim.
+  // The classification `message` accompanies it — it NEVER replaces it: an
+  // app-logic assertion like "expected balance 10, got 7" must survive so the
+  // human/agent sees the real cause, not just the note.
+  originalError?: string;
+}
+
+// Returns null (ok to proceed) or a violation descriptor when a bound is hit.
+// Using null instead of { ok: true } keeps the return typeof-narrowable without
+// relying on discriminated-union narrowing (avoids strict-mode tsconfig issues).
+export function checkHealBounds(
+  target: string,
+  output: string,
+  state: HealState,
+): HealBoundViolation | null {
+  // Carry the original failure output verbatim on every violation so the caller
+  // can surface it (--json + human) alongside the classification note.
+  const originalError = output.trim() || undefined;
+  if (recipeRunning(target)) {
+    return {
+      code: 'RECIPE_RUNNING',
+      exitCode: EXIT.bounded,
+      message: 'a recipe is currently running — refusing recovery to avoid corrupting mid-run state.',
+      originalError,
+    };
+  }
+  const failureClass = classifyFailure(output);
+  if (failureClass === 'wallet') {
+    return {
+      code: 'WALLET_STATE_REQUIRED',
+      exitCode: EXIT.bounded,
+      message: 'recovery would require a seeded wallet — healing never touches fixtures.',
+      userAction: 'run mm-harness fixtures set',
+      originalError,
+    };
+  }
+  if (failureClass === 'app') {
+    return {
+      code: 'APP_LOGIC_FAILURE',
+      exitCode: EXIT.runtime,
+      message: 'failure looks like app-logic — healing cannot help; surface verbatim.',
+      originalError,
+    };
+  }
+  if (state.attemptedRecoveries.length > 0) {
+    return {
+      code: 'SAME_RECOVERY_TWICE',
+      exitCode: EXIT.bounded,
+      message: 'same recovery already failed once this invocation — refusing to loop.',
+      originalError,
+    };
+  }
+  return null;
+}