@deeeed/metamask-harness 0.2.0 → 0.3.0

package/{runner/src → src}/commands/shared.ts

@@ -1,12 +1,11 @@
 // Shared helpers for the mm-harness command modules: flag parsing, adapter
-// resolution, porcelain composition, and the teaching-error emitter. Each command
-// module (launch/logs/debug/fixtures) composes mobile/extension porcelain scripts
-// that live under orchestration/porcelain/; these helpers are the common seam.
+// resolution, script composition, and the teaching-error emitter. Each command
+// module composes adapters/ scripts directly via spawnScript.
 //
-// Composition seams (overridable for CI/agents and contract tests):
-//   MM_HARNESS_MM_RECIPE_BIN  — mobile porcelain (default: <runner>/orchestration/porcelain/mm-recipe)
-//   MM_HARNESS_MME_RECIPE_BIN — extension porcelain (default: <runner>/orchestration/porcelain/mme-recipe)
-// A stub that records argv against one of these paths is the contract-test lever.
+// Composition seam (overridable for contract tests):
+//   MM_HARNESS_SCRIPT_BIN_<STEM>  — override a specific script by its basename.
+//   For node invocations (bin === process.execPath) the stem is derived from the
+//   script path in args[0], e.g. MM_HARNESS_SCRIPT_BIN_OPEN_DEBUG_MJS.
 
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -89,36 +88,37 @@ export function resolveAdapter(
   return detectAdapter(target);
 }
 
-function porcelainBin(adapter: DeviceAdapter): string {
-  if (adapter === 'mobile') {
-    return process.env.MM_HARNESS_MM_RECIPE_BIN ?? path.join(runnerDir, 'orchestration', 'porcelain', 'mm-recipe');
-  }
-  return process.env.MM_HARNESS_MME_RECIPE_BIN ?? path.join(runnerDir, 'orchestration', 'porcelain', 'mme-recipe');
-}
-
-export interface PorcelainResult {
+export interface ScriptResult {
   status: number;
   output: string;
 }
 
-// Compose the porcelain. Output is always captured (needed for heal
-// classification) and, in human mode, forwarded to our stderr so the human still
-// sees it. --json keeps stdout clean for the machine summary.
-export function spawnPorcelain(
-  adapter: DeviceAdapter,
+// Compose an adapters/ script directly. Output is always captured (needed for
+// heal classification) and, in human mode, forwarded to stderr. --json keeps
+// stdout clean for the machine summary.
+export function spawnScript(
+  script: string,
   args: string[],
-  target: string,
+  cwd: string,
   json: boolean,
-): PorcelainResult {
-  const bin = porcelainBin(adapter);
-  const result = spawnSync(bin, args, {
-    cwd: target,
+): ScriptResult {
+  // For node invocations (script === process.execPath) the seam stem is derived
+  // from args[0] so each spawned script has its own override key.
+  const isNodeScript = script === process.execPath && args.length > 0;
+  const stem = isNodeScript
+    ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase()
+    : path.basename(script).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase();
+  const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
+  const bin = override ?? script;
+  const spawnArgs = override !== undefined && isNodeScript ? args.slice(1) : args;
+  const result = spawnSync(bin, spawnArgs, {
+    cwd,
     encoding: 'utf8',
     env: process.env,
     maxBuffer: 64 * 1024 * 1024,
   });
   if (result.error) {
-    return { status: 1, output: `porcelain could not start: ${result.error.message}` };
+    return { status: 1, output: `script could not start (${path.basename(script)}): ${result.error.message}` };
   }
   const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
   if (!json && output) process.stderr.write(output);

package/{runner/src → src}/harness.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 
 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)
@@ -277,11 +278,14 @@ function resolveEntry(base: string, candidates: string[], mode: 'exec' | 'file')
 
 // 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();
-  return value || undefined;
+  if (!value || !fs.existsSync(value)) return undefined;
+  return value;
 }
 
 function isExecutable(file: string): boolean {
@@ -299,15 +303,15 @@ interface HarnessDispatch {
 }
 
 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' },
+  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: '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' },
+  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
@@ -337,7 +341,7 @@ function resolveHarnessDispatch(
   }
 
   if (adapter === 'core' && action === 'verify') {
-    const delegate = path.join(recipeHarnessPath(target, 'core'), 'runner', 'bin', 'metamask-recipe');
+    const delegate = path.join(recipeHarnessPath(target, 'core'), 'runner', 'bin', 'mm-harness');
     if (!isExecutable(delegate)) {
       return {
         error:
@@ -351,19 +355,97 @@ function resolveHarnessDispatch(
   }
 
   // mobile/extension live|verify: prefer the installed helper, else the runner's
-  // own orchestration/runner/scripts helper (first executable candidate wins).
+  // own adapters/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`],
+    [`adapters/${adapter}/${action}.sh`, `scripts/${adapter}/${action}.sh`],
     'exec',
   );
   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})`,
+        }),
+      );
+    } 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 = isExecutable(installedVerify)
+    ? installedVerify
+    : resolveEntry(runnerDir, ['adapters/mobile/verify.sh', 'scripts/mobile/verify.sh'], 'exec');
+
+  const verifyArgs = hasArg(forwardArgs, '--no-auto-start')
+    ? [...forwardArgs]
+    : ['--no-auto-start', ...forwardArgs];
+
+  const result = spawnSync(verifySh, verifyArgs, {
+    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})` },
+      ),
+    );
+  } 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') {
@@ -425,6 +507,11 @@ export async function handleHarness(argv: string[]): Promise<number> {
     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) {

package/src/index.ts

@@ -0,0 +1,15 @@
+// Keep the package entrypoint narrow: runner factory, manifest, doctor, and the
+// path/import helpers that library actions are allowed to consume (R9 — no
+// deep-importing src internals past this file).
+export { createDoctorReport } from './doctor.ts';
+export { loadActionManifest, validateManifest } from './manifest.ts';
+export { createMetaMaskExtensionRunner, createMetaMaskMobileRunner, createMetaMaskRunner } from './runner.ts';
+export type { CreateMetaMaskRunnerOptions, MetaMaskDoctorReport, MetaMaskRecipeAdapter } from './types.ts';
+export {
+  extensionIdPath,
+  importRecipeHarnessRuntimeBrowserExtension,
+  importRecipeHarnessRuntimeCdp,
+  recipeHarnessPath,
+  walletFixturePath,
+} from './paths.ts';
+export { captureActiveRecipeRecordingSnapshot } from './run-recording.ts';

package/{runner/src → src}/live-adapter-contract.ts

@@ -223,7 +223,7 @@ export async function runLiveAdapterScript({ platform, action, node, context }:
   const script = await resolveLiveAdapter(platform, action);
   if (!script) return null;
 
-  const tempDir = await mkdtemp(path.join(os.tmpdir(), 'metamask-recipe-live-adapter-'));
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), 'mm-harness-live-adapter-'));
   const inputPath = path.join(tempDir, 'input.json');
   const outputPath = path.join(tempDir, 'output.json');
   const input = {

package/{runner/src → src}/mm-harness-cli.ts

@@ -12,8 +12,8 @@ import { fileURLToPath } from 'node:url';
 
 import { Command } from 'commander';
 
-// runner root (…/runner) → its parent is the package root that holds scripts/.
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+// …/src → its parent is the package root that holds scripts/.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 // Signal cli.ts NOT to auto-run its own dispatch when we import it below: we
 // reuse its `main` in-process. Must be set BEFORE the dynamic import runs the
@@ -474,7 +474,23 @@ for (const retired of RETIRED) {
     .allowUnknownOption()
     .helpOption(false)
     .argument('[args...]')
-    .action(() => {
+    .action(async () => {
+      // `live --adapter mobile` (or android) is handled in-process via handleMobileLive.
+      // All other `live` invocations still teach the replacement.
+      if (retired.name === 'live') {
+        const adapterIdx = rawArgv.indexOf('--adapter');
+        const aliasIdx = rawArgv.indexOf('-a');
+        const adapterVal =
+          adapterIdx !== -1
+            ? rawArgv[adapterIdx + 1]
+            : aliasIdx !== -1
+              ? rawArgv[aliasIdx + 1]
+              : undefined;
+        if (adapterVal === 'mobile' || adapterVal === 'android') {
+          process.exit(await delegate(rawArgv));
+          return;
+        }
+      }
       console.error(retired.message);
       process.exit(2);
     });

package/{runner/src → src}/paths.ts

@@ -11,7 +11,7 @@ import type {
   MetaMaskRecipeAdapter,
 } from './types.ts';
 
-export const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+export const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const pathDefaults = readPathDefaults();
 export const DEFAULT_RECIPE_RUNTIME_DIR = pathDefaults.recipeRuntimeDir;
 export const DEFAULT_RECIPE_HARNESS_ROOT = pathDefaults.recipeHarnessRoot;
@@ -26,7 +26,7 @@ export function recipeHarnessRoot() {
 
 
 function readPathDefaults(): { recipeRuntimeDir: string; recipeHarnessRoot: string } {
-  const defaultsPath = path.join(runnerDir, 'orchestration/lib/path-defaults.json');
+  const defaultsPath = path.join(runnerDir, 'adapters/shared/path-defaults.json');
   const parsed = JSON.parse(fs.readFileSync(defaultsPath, 'utf8')) as Partial<{ recipeRuntimeDir: string; recipeHarnessRoot: string }>;
   return {
     recipeRuntimeDir: validateRelativeRecipePath('recipeRuntimeDir', parsed.recipeRuntimeDir || ''),

package/{orchestration/lib/progress.mjs → src/progress.ts}

@@ -1,20 +1,29 @@
-#!/usr/bin/env node
 /**
- * progress.mjs — structured progress events for long recipe CLI operations.
+ * progress.ts — structured progress events for long recipe CLI operations.
  *
  * Human mode: short lines on stderr.
  * Machine mode: JSONL on stderr when --json or RECIPE_PROGRESS_JSON=1.
  */
+import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { color } from './cli-color.mjs';
+import { color } from './cli-color.ts';
 
-function shouldEmitJson(explicit) {
+function shouldEmitJson(explicit: boolean): boolean {
   if (explicit) return true;
   const env = process.env.RECIPE_PROGRESS_JSON;
   return env === '1' || env === 'true';
 }
 
-export function emitProgress(event, { json = false } = {}) {
+interface ProgressEvent {
+  command?: string;
+  phase?: string;
+  message?: string;
+  status?: string;
+  elapsedMs?: number;
+  [key: string]: unknown;
+}
+
+export function emitProgress(event: ProgressEvent, { json = false }: { json?: boolean } = {}): void {
   const payload = {
     schemaVersion: 1,
     type: 'progress',
@@ -30,28 +39,28 @@ export function emitProgress(event, { json = false } = {}) {
   if (payload.phase === 'done') {
     const statusStyle = payload.status === 'pass' ? 'ok' : 'err';
     const statusWord = payload.status === 'pass' ? 'done' : 'failed';
-    const verb = payload.verb ? color('cmd', `${payload.verb}`, { stream }) : '';
+    const cmd = payload.command ? color('cmd', `${payload.command}`, { stream }) : '';
     const elapsed = Number.isFinite(payload.elapsedMs)
-      ? color('comment', ` (${Math.round(payload.elapsedMs / 1000)}s)`, { stream })
+      ? color('comment', ` (${Math.round((payload.elapsedMs as number) / 1000)}s)`, { stream })
       : '';
-    process.stderr.write(`${prefix}: ${verb} ${color(statusStyle, statusWord, { stream })} ${payload.message || ''}${elapsed}\n`);
+    process.stderr.write(`${prefix}: ${cmd} ${color(statusStyle, statusWord, { stream })} ${payload.message || ''}${elapsed}\n`);
     return;
   }
-  const verb = payload.verb ? `${color('cmd', payload.verb, { stream })}: ` : '';
+  const cmd = payload.command ? `${color('cmd', payload.command, { stream })}: ` : '';
   const phase = payload.phase ? `${color('accent', `[${payload.phase}]`, { stream })} ` : '';
   const elapsed = Number.isFinite(payload.elapsedMs)
-    ? color('comment', ` (${Math.round(payload.elapsedMs / 1000)}s)`, { stream })
+    ? color('comment', ` (${Math.round((payload.elapsedMs as number) / 1000)}s)`, { stream })
     : '';
-  process.stderr.write(`${prefix}: ${verb}${phase}${payload.message || ''}${elapsed}\n`);
+  process.stderr.write(`${prefix}: ${cmd}${phase}${payload.message || ''}${elapsed}\n`);
 }
 
-function usage() {
+function usage(): void {
   console.error(`Usage:
-  progress.mjs emit --verb <name> --phase <id> --message <text> [--elapsed-ms <n>] [--json]
-  progress.mjs done --verb <name> --status pass|fail --message <text> [--elapsed-ms <n>] [--json]`);
+  progress emit --command <name> --phase <id> --message <text> [--elapsed-ms <n>] [--json]
+  progress done --command <name> --status pass|fail --message <text> [--elapsed-ms <n>] [--json]`);
 }
 
-async function main() {
+async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
   if (!command || command === '--help' || command === '-h') {
     usage();
@@ -61,7 +70,7 @@ async function main() {
   const { values } = parseArgs({
     args: rest,
     options: {
-      verb: { type: 'string' },
+      command: { type: 'string' },
       phase: { type: 'string' },
       message: { type: 'string' },
       status: { type: 'string' },
@@ -76,7 +85,7 @@ async function main() {
 
   if (command === 'emit') {
     emitProgress({
-      verb: values.verb || 'recipe',
+      command: values.command || 'recipe',
       phase: values.phase || 'working',
       message: values.message || '',
       elapsedMs: Number.isFinite(elapsedMs) ? elapsedMs : undefined,
@@ -86,7 +95,7 @@ async function main() {
 
   if (command === 'done') {
     emitProgress({
-      verb: values.verb || 'recipe',
+      command: values.command || 'recipe',
       phase: 'done',
       status: values.status || 'pass',
       message: values.message || '',
@@ -99,9 +108,10 @@ async function main() {
   process.exit(2);
 }
 
-if (import.meta.url === new URL(process.argv[1], 'file:').href) {
-  main().catch((error) => {
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename ?? '');
+if (isMain) {
+  main().catch((error: unknown) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   });
-}
+}

package/docs/extension-runtime-commands.md

@@ -1,60 +0,0 @@
-# Extension runtime lifecycle (internal notes)
-
-Internal implementation notes for the MetaMask Extension runtime lifecycle — the
-self-healing path that gets a checkout from "installed" to "a live, verified
-extension under CDP control". These are **not** a public command surface: the
-probes below are internal functions, composed for you by the daily-loop commands
-(`launch --verify`) and the readiness commands (`doctor --fix`, `verify`). The
-public surface is defined in [CLI-SPEC.md](CLI-SPEC.md); this file explains what
-happens underneath.
-
-The runner is the source of truth for Extension harness injection, readiness
-decisions, extension-id resolution, and live CDP health checks.
-
-## Public entry points
-
-- **`install`** writes the Extension runtime overlay under the configured harness
-  root. CI/agents run it explicitly; the daily-loop commands auto-ensure it.
-- **`verify`** confirms the overlay is present and healthy — a live CDP health
-  probe when a runtime is reachable, no launch.
-- **`launch --verify`** installs the overlay if missing, launches/attaches the
-  extension, and polls CDP until the runtime is ready.
-- **`doctor` / `doctor --fix`** report readiness and (with `--fix`) run the
-  healing steps below WITHOUT starting the app.
-
-## Internal lifecycle stages
-
-The healing path composes these internal functions in order. Each is idempotent
-and reports the cheapest next action, so the composed path converges rather than
-rebuilding from scratch.
-
-### Extension-id resolution
-
-Resolves the deterministic unpacked extension id from
-`dist/chrome/manifest.json`, and can verify it against a live CDP target. Every
-later stage keys off this id, so it runs first.
-
-### Readiness decision
-
-Inspects the checkout + live browser and returns the cheapest next action:
-`install`, `build`, `relaunch`, or `ready`, plus the concrete `actions[]` to
-execute. The healing path branches on this decision instead of always launching.
-
-### Runtime launch
-
-Launches Chrome with the installed harness helper, seeds the wallet fixture, and
-runs live smoke verification. Two tiers: reuse the existing dist (quick relaunch),
-or the clean-build path — clear the webpack cache, start the harness-owned
-watcher, wait for a clean compile, then launch and verify.
-
-### Convergence
-
-Converges the live browser to exactly one healthy `home.html` tab (closing
-strays, reopening if needed) and confirms it with the health probe. This is the
-step that makes "launch" deterministic across a messy pre-existing browser state.
-
-### Health probe
-
-Read-only liveness probe for the running extension over CDP. Used both as the
-final gate of the convergence step and standalone by `verify` to answer "is the
-runtime healthy right now?" without mutating anything.

package/docs/harness-cli.md

@@ -1,43 +0,0 @@
-# `mm-harness` — Command Reference
-
-> This page is a pointer. The full, authoritative command contract lives in
-> [CLI-SPEC.md](CLI-SPEC.md); the before→after overview is in
-> [MENTAL-MODEL.md](MENTAL-MODEL.md). This file exists only so links to
-> `harness-cli.md` keep resolving.
-
-`mm-harness` is the MetaMask recipe harness — the single front door for launching
-the app, proving behavior, and managing the per-checkout **runtime overlay**. It
-is the only bin: platform (`mobile | extension | core`) is auto-detected from the
-checkout, a positional target forces it (`mm-harness launch ios`), and depth lives
-in flags (`--json`, ports, build tiers), never in extra command names.
-
-Naming: **"harness" is the tool** (`mm-harness`) and the generic engine package
-(`@farmslot/recipe-harness`). The files the tool installs into a target checkout
-are the **runtime overlay** — never "the harness".
-
-## Command surface (all shipped)
-
-```
-DAILY LOOP        launch · logs · debug · fixtures       what a teammate runs many times a day
-DISCOVER          actions · call · flows                 compose recipes from the vocabulary + flow library
-PROVE             run · doctor                           run recipes, check readiness
-RUNTIME OVERLAY   install · verify · cleanup             install/verify/clean the per-checkout overlay
-```
-
-Grammar: `mm-harness <command> [target] [flags]`. `--json` is the agent contract on
-every command; the bare command is the human happy path.
-
-- `run` validates first, then executes; `run --plan` validates and prints the plan
-  without touching a device.
-- `call <action>` runs one action from the adapter vocabulary through the same
-  engine path `run` uses.
-- `doctor` is read-only; `doctor --fix` runs the self-healing steps (overlay
-  auto-ensure; never a fixture reseed) without launching the app and reports
-  `fixed[]` / `failed[]`.
-- `flows` lists the recipe library (bare = `flows list`); `flows promote` keeps a
-  proven flow.
-- `install` / `verify` / `cleanup` manage the runtime overlay; the DAILY LOOP
-  commands auto-ensure it.
-
-For flags, exit-code taxonomy, `--json` shapes, and per-command detail, see
-[CLI-SPEC.md](CLI-SPEC.md).

package/orchestration/compat-overlays/mobile/README.md

@@ -1,13 +0,0 @@
-# Mobile historical compatibility overlays
-
-These patch files document temporary source overlays used by Recipe v1 historical
-injection evals when an older MetaMask Mobile checkout cannot boot under the
-current local Xcode/Hermes toolchain.
-
-They are intentionally kept in the external runner repository, not Farmslot root
-scripts, so a `/recipe-harness` skill can apply the same reversible overlay before
-a historical rebuild and record the overlay path in validation evidence.
-
-- `rn81-message-event-source.patch`: adds a read-only `MessageEvent.prototype.source`
-  getter for React Native 0.81 historical checkouts whose bundled polyfill omits
-  it while CDP websocket clients expect browser-compatible `MessageEvent` shape.

package/orchestration/doctor.mjs

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-// doctor.mjs — orchestration feature-surface doctor
-//
-// Purpose:
-//   Verifies orchestration/manifest.json against reality: every entry point
-//   exists; every script entry answers --help with exit 0; and every script
-//   under orchestration/{mobile,extension,core} is listed (no doc drift).
-//
-// Inputs (flags): --json (machine-readable report)
-// Outputs: per-feature lines (or JSON report) on stdout.
-//   Exit 0 — surface healthy; 1 — missing entry, failing --help, or
-//   unlisted script; 2 — bad args.
-// Never touches: anything (read-only + --help subprocesses).
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-let json = false;
-for (const arg of process.argv.slice(2)) {
-  if (arg === '--json') json = true;
-  else if (arg === '-h' || arg === '--help') {
-    console.log('Usage: doctor.mjs [--json]');
-    process.exit(0);
-  } else {
-    console.error(`Unknown arg: ${arg}`);
-    process.exit(2);
-  }
-}
-
-const orchestrationDir = path.dirname(fileURLToPath(import.meta.url));
-const runnerRoot = path.resolve(orchestrationDir, '..');
-const manifest = JSON.parse(fs.readFileSync(path.join(orchestrationDir, 'manifest.json'), 'utf8'));
-
-const results = [];
-for (const feature of manifest.features) {
-  const entryAbs = path.join(runnerRoot, feature.entry);
-  const checks = { exists: fs.existsSync(entryAbs), help: null };
-  if (checks.exists && (feature.kind === 'bash' || feature.kind === 'node')) {
-    const runner = feature.kind === 'bash' ? 'bash' : process.execPath;
-    const run = spawnSync(runner, [entryAbs, '--help'], { encoding: 'utf8', timeout: 30000 });
-    checks.help = run.status === 0;
-  }
-  const ok = checks.exists && (checks.help === null || checks.help === true);
-  results.push({ id: feature.id, entry: feature.entry, kind: feature.kind, ...checks, ok });
-}
-
-// drift guard: every script in the orchestration trees must be listed
-const listed = new Set(manifest.features.map((feature) => feature.entry));
-const unlisted = [];
-for (const platform of ['mobile', 'extension', 'core', 'lib']) {
-  const dir = path.join(orchestrationDir, platform);
-  if (!fs.existsSync(dir)) continue;
-  for (const entry of fs.readdirSync(dir)) {
-    const rel = `orchestration/${platform}/${entry}`;
-    if (!/\.(?:sh|mjs|cjs|json)$/u.test(entry)) continue;
-    if (!listed.has(rel)) unlisted.push(rel);
-  }
-}
-
-const failed = results.filter((result) => !result.ok);
-const status = failed.length === 0 && unlisted.length === 0 ? 'pass' : 'fail';
-if (json) {
-  console.log(JSON.stringify({ status, features: results, unlisted }, null, 2));
-} else {
-  for (const result of results) {
-    console.log(`${result.ok ? 'ok  ' : 'FAIL'} ${result.id} (${result.entry})${result.help === false ? ' [--help failed]' : ''}${result.exists ? '' : ' [missing]'}`);
-  }
-  for (const rel of unlisted) console.log(`FAIL unlisted script not in manifest: ${rel}`);
-  console.log(`orchestration surface: ${status} (${results.length - failed.length}/${results.length} features, ${unlisted.length} unlisted)`);
-}
-process.exit(status === 'pass' ? 0 : 1);