@deeeed/metamask-harness 0.2.0

package/docs/CLI-SPEC.md

@@ -0,0 +1,915 @@
+# mm-harness — CLI Specification (spec-first)
+
+The detailed contract beneath [MENTAL-MODEL.md](MENTAL-MODEL.md) (skim that first
+for the before→after at a glance). This document defines every capability: Part 1
+inventories everything today; Part 2 specs each end-state verb in full; Part 3
+audits every caller; Part 4 audits every env var. Each verb is fully specified here
+independent of its implementation status.
+
+**`mm-harness` is built for the agent but easy for the human to use and
+understand.** The agent gets full depth (explicit flags, `--json`, ports, build
+tiers — machine-grade determinism); the human gets short verbs, positional
+targets, good defaults, completions, and teaching help/errors. Every table's
+human-form vs agent-form split is the direct expression of that sentence.
+
+Naming: **"harness" is the tool** (`mm-harness`); the engine is
+`@farmslot/recipe-harness`; the injected files are the **runtime overlay**.
+
+**Clean break (no aliases).** End state has exactly one command, `mm-harness`.
+The `metamask-recipe` / `mm-recipe` / `mme-recipe` names and the `harness <verb>`
+subcommand form are REMOVED in the same coordinated wave (Part 3). The draft code
+keeps the old bins working so the tree still builds/tests; the surface documented
+here is end-state only.
+
+---
+
+# Part 1 — Complete inventory of existing capabilities
+
+**Why this exists (Arthur):** to *guarantee no capability is lost* in the
+refactor. **Acceptance rule:** every row MUST have a fate, and the fates are
+exhaustive —
+
+- **ROUTES-NOW** — capability works via `mm-harness` today (this draft),
+- **STUB** — spec'd here, coming (exits 2 with a teaching message today),
+- **ABSORB-LATER** — capability folds into an `mm-harness` verb (spec'd in Part 2 with a maps-to row),
+- **KEEP-INTERNAL** — still reachable, just not a user-facing verb,
+- **REMOVE** — name/bin/subcommand deleted in the wave; **requires a one-line justification** (needs Arthur's sign-off).
+
+**No row may be unmapped.** An unmapped row means the refactor is not allowed to
+proceed. Source of truth: the bins' `case` statements + the naming audit in
+[harness-cli.md](harness-cli.md). Every row is real.
+
+## Surface A — `metamask-recipe` typed CLI (`runner/src/cli.ts`)
+
+Name `metamask-recipe` → **REMOVE** (becomes `mm-harness`; no alias). Capability rows:
+
+| Verb | What it does today | Platforms | Class | Fate |
+|---|---|---|---|---|
+| `manifest` | Print/validate an action manifest | mobile/extension/core | ADVANCED | **REMOVE** — 3 functions rehome: (1) well-formedness validation → `doctor` readiness check; (2) raw protocol dump → `actions --raw` flag; (3) manifest path + protocol version → `doctor` explain-my-setup section. "action manifest" stays as the FILE name in docs; only manifest EDITORS needed this verb (maintainer/CI audience, served by `doctor` + `--raw`). |
+| `actions` | Describe declared actions | all | DISCOVER | ROUTES-NOW |
+| `doctor` | Readiness check (no launch) | all | PROVE | ROUTES-NOW |
+| `runtime-health` | Probe extension CDP runtime health | extension | advanced | **KEEP-INTERNAL** — becomes internal function inside `launch`/`verify` self-healing path |
+| `runtime-decision` | Decide readiness/rebuild need | extension/mobile | advanced | **KEEP-INTERNAL** — becomes internal function inside `launch` self-healing path |
+| `runtime-launch` | Launch extension runtime via live.sh | extension | advanced | **KEEP-INTERNAL** — becomes internal function inside `launch` self-healing path |
+| `resolve-extension` | Resolve the extension id | extension | advanced | **KEEP-INTERNAL** — internal plumbing; called inside `launch`/`launch --verify` |
+| `ensure-ready` | Ensure extension ready (close home tabs) | extension | advanced | **KEEP-INTERNAL** — becomes internal function inside `launch`/`verify` self-healing path |
+| `run` | Run a recipe, write evidence | all | PROVE | ROUTES-NOW |
+| `self-test` | Package-wiring smoke (no device) | mobile+extension | advanced | **KEEP-INTERNAL** — CI smoke test; callable via `package.json` scripts; hidden from `--help` |
+| `flows` | List/promote library flows | all | DISCOVER | ROUTES-NOW |
+| `harness install\|verify\|cleanup\|live` | Runtime overlay lifecycle | all (core: no live) | OVERLAY | ROUTES-NOW (`harness` prefix → top-level); `live` **REMOVE** — dissolved into `launch --verify` |
+| `mobile <...>` | Passthrough to `mm-recipe` | mobile | passthrough | ABSORB-LATER; passthrough REMOVE |
+| `extension <...>` | Passthrough to `mme-recipe` | extension | passthrough | ABSORB-LATER; passthrough REMOVE |
+
+## Surface B — `mm-harness` verbs (this draft)
+
+| Verb | What it does today | Platforms | Class | Fate |
+|---|---|---|---|---|
+| `install\|verify\|cleanup` (top-level) | Overlay lifecycle (final home; `live` dissolved → `launch --verify`) | all | OVERLAY | ROUTES-NOW |
+| `live` | Overlay install + launch + live-verify | all (core: n/a) | OVERLAY | **REMOVE** — dissolved into `launch --verify` (same sequence: install overlay if missing → launch → CDP poll → smoke verify; zero capability lost — `launch --verify` never seeds fixtures) |
+| `launch` | Quick relaunch / `--build` / `--verify`; auto-ensure overlay + heal | mobile/extension (core: teaching error) | DAILY LOOP | STUB → **REAL (wave 3)** |
+| `logs` | Tail Metro/webpack logs (composes porcelain `logs`) | mobile/extension | DAILY LOOP | STUB → **REAL (wave 3)** |
+| `debug` | Open DevTools / RN dev menu (composes porcelain `debug`/`dev-menu`) | mobile/extension | DAILY LOOP | STUB → **REAL (wave 3)** |
+| `fixtures` | `sync` files / `set` the wallet (wallet DATA only) | mobile/extension | DAILY LOOP | STUB → **REAL (wave 3)** |
+| `validate` | Dissolved into `run` (`run` validates first; `run --plan` = plan-only, no device) — `run --plan` **REAL as of wave 2** | all | DISCOVER | **REMOVE** — zero capability lost; rehomed into `run` |
+| `call` | Ad-hoc single-action execution via the real engine path (one-node recipe) — **REAL as of wave 2** (was STUB in wave 1) | all | DISCOVER | STUB → **REAL (wave 2)** |
+
+## Surface C — `bin/mm-recipe` porcelain (mobile) — name REMOVE
+
+| Verb | What it does today | Class | Fate |
+|---|---|---|---|
+| `interactive\|menu` | Interactive TUI menu | setup | ABSORB-LATER |
+| `ports` | Show slot ports/paths | advanced | ABSORB-LATER |
+| `up` | Decision-aware full lifecycle to ready | daily | ABSORB-LATER |
+| `decision` | Print readiness decision | advanced | ABSORB-LATER |
+| `sync` | Sync runtime overlay + fixtures | daily | ABSORB-LATER |
+| `completion\|complete` | Shell completion script | tooling | KEEP-INTERNAL |
+| `prepare` | Prepare runtime (install/build) | setup | ABSORB-LATER |
+| `runtime-status` | Runtime status JSON | advanced | ABSORB-LATER |
+| `ios\|start` | Launch iOS dev client | daily | ABSORB-LATER |
+| `android` | Launch Android dev client | daily | ABSORB-LATER |
+| `setup:ios` | Launch iOS + apply wallet fixture | daily | ABSORB-LATER |
+| `setup:android` | Launch Android + apply wallet fixture | daily | ABSORB-LATER |
+| `refresh\|reload\|relaunch` | Reload running app | daily | ABSORB-LATER |
+| `logs\|tail` | Tail Metro log (`--full` = raw) | daily | ABSORB-LATER |
+| `status\|home` | Status dashboard + next commands | daily | ABSORB-LATER |
+| `app-status\|bridge-status` | Bridge status via `__AGENTIC__` | advanced | ABSORB-LATER |
+| `route\|get-route` | Current route from bridge | advanced | ABSORB-LATER |
+| `navigate` | Navigate to a route via bridge | advanced | ABSORB-LATER |
+| `back\|go-back` | Go back via bridge | advanced | ABSORB-LATER |
+| `unlock` | Unlock wallet with fixture password | daily | ABSORB-LATER |
+| `setup-wallet\|wallet-setup` | Apply wallet fixture (SRP/pw/accounts) | daily | ABSORB-LATER |
+| `accounts\|list-accounts` | List accounts via bridge | advanced | ABSORB-LATER |
+| `select-account\|switch-account` | Switch account via bridge | advanced | ABSORB-LATER |
+| `screenshot` | Capture app screenshot | advanced | ABSORB-LATER |
+| `debug` | Open RN DevTools / Hermes inspector | daily | ABSORB-LATER |
+| `dev-menu\|devmenu\|menu` | Open RN developer menu | daily | ABSORB-LATER |
+| `stop` | Stop Metro | setup | ABSORB-LATER |
+| `actions` | Actions (delegates to typed CLI) | PROVE | ABSORB-LATER |
+| `doctor` | Doctor (delegates to typed CLI) | PROVE | ABSORB-LATER |
+| `run` | Run a recipe (auto adapter+artifacts) | PROVE | ABSORB-LATER |
+
+## Surface D — `bin/mme-recipe` porcelain (extension) — name REMOVE
+
+| Verb | What it does today | Class | Fate |
+|---|---|---|---|
+| `interactive\|menu` | Interactive TUI menu | setup | ABSORB-LATER |
+| `sync` | Sync runtime overlay | daily | ABSORB-LATER |
+| `completion\|complete` | Shell completion script | tooling | KEEP-INTERNAL |
+| `prepare` | Prepare runtime (install/build) | setup | ABSORB-LATER |
+| `status\|health\|home` | Status dashboard | daily | ABSORB-LATER |
+| `ports` | Show slot ports/paths | advanced | ABSORB-LATER |
+| `up` | Full build + launch + fixture | daily | ABSORB-LATER |
+| `runtime-status` | Runtime status JSON | advanced | ABSORB-LATER |
+| `decision\|decide` | Print readiness decision | advanced | ABSORB-LATER |
+| `update\|sync-runtime` | Hot-swap runtime overlay | daily | ABSORB-LATER |
+| `ready\|ensure-ready` | Wait for/ensure runtime ready | daily | ABSORB-LATER |
+| `watch\|start-watch\|watcher` | Start webpack watcher (background) | daily | ABSORB-LATER |
+| `stop\|stop-watch\|stop-watcher` | Stop watcher | setup | ABSORB-LATER |
+| `logs\|tail\|tail-webpack` | Tail webpack log | daily | ABSORB-LATER |
+| `rebuild\|reset\|reopen\|reload\|browser\|launch\|full-launch\|runtime-launch` | Quick relaunch (snapshot dist + reopen Chrome) | daily | ABSORB-LATER |
+| `refresh` | Incremental refresh | daily | ABSORB-LATER |
+| `build` | Incremental rebuild | daily | ABSORB-LATER |
+| `refresh:once\|refresh-once\|build:once\|build-once` | One-shot rebuild | daily | ABSORB-LATER |
+| `debug\|devtools\|inspect` | Open Chrome DevTools (`worker` = SW) | daily | ABSORB-LATER |
+| `sidepanel` | Toggle popup ↔ sidebar via CDP | daily | ABSORB-LATER |
+| `actions` | Actions (delegates to typed CLI) | PROVE | ABSORB-LATER |
+| `doctor` | Doctor (delegates to typed CLI) | PROVE | ABSORB-LATER |
+| `run` | Run a recipe (auto adapter+artifacts) | PROVE | ABSORB-LATER |
+
+## Surface E — `recipe-harness` skill
+
+| Verb | What it does today | Class | Fate |
+|---|---|---|---|
+| `install\|verify\|cleanup\|live` | ~812 lines bash: resolve runner source + dispatch overlay lifecycle | OVERLAY | **REMOVE** — superseded by `mm-harness install/verify/cleanup` + `launch --verify`; skill thins to a caller |
+
+## Surface F — Orchestration entry points (invoked by the overlay verbs)
+
+| Entry | What it does today | Class | Fate |
+|---|---|---|---|
+| `{mobile,core}/inject.sh`, `extension/inject.mjs` | Install overlay into `temp/recipe/harness/<adapter>/` | OVERLAY impl | KEEP-INTERNAL (via `mm-harness install`) |
+| `{mobile,core}/cleanup.sh`, `extension/cleanup.mjs` | Remove overlay | OVERLAY impl | KEEP-INTERNAL (via `mm-harness cleanup`) |
+| `{mobile,extension}/live.sh` | Launch + live-verify | OVERLAY impl | KEEP-INTERNAL (via `mm-harness launch --verify`) |
+| `runner/{mobile,extension}/verify.sh` (+ installed `scripts/verify.sh`) | Verify overlay/runtime health | OVERLAY impl | KEEP-INTERNAL (via `mm-harness verify`) |
+| `orchestration/doctor.mjs` | Orchestration manifest doctor | advanced impl | KEEP-INTERNAL |
+
+## Surface G — Shell completion
+
+| Artifact | What it does today | Fate |
+|---|---|---|
+| `completions/_recipe` (zsh `#compdef recipe mme-recipe mm-recipe`) | Completes the three legacy names + adapters/recipes/flags | **REMOVE** — replaced by bundled `mm-harness` completions (zsh + bash), auto-installed on setup |
+
+## Completeness check
+
+- **Total rows:** 81 (A:14 · B:7 · C:30 · D:23 · E:1 · F:5 · G:1)
+- ROUTES-NOW: 6 · STUB: 5 · ABSORB-LATER: 53 · KEEP-INTERNAL: 13 · REMOVE: 4 (total 82 rows — live split into own row in Surface B)
+- 6 + 5 + 53 + 13 + 4 = 81 rows of capability (live row is REMOVE, not a net-new capability)
+- **Unmapped: 0** ✅ (REMOVE rows: `manifest` A; `live` B dissolved → `launch --verify`; `validate` B dissolved → `run`/`run --plan`; Surface E; Surface G; ADVANCED KEEP-INTERNAL; name-level REMOVE in bin table + Part 3)
+- **Class breakdown:** DAILY LOOP: 4 STUB → **REAL (wave 3)** · DISCOVER: 2 ROUTES-NOW + 1 STUB→REAL (`call`, wave 2) + 1 REMOVE (`validate` dissolved) · PROVE: 3 ROUTES-NOW · OVERLAY: 3 ROUTES-NOW + 1 REMOVE (`live` dissolved → `launch --verify`) · ADVANCED: 6 KEEP-INTERNAL + 1 REMOVE (`manifest`) · passthrough/tooling: rest
+
+---
+
+# Part 2 — Per-verb capability spec (end state)
+
+Grammar: `mm-harness <verb> [target] [flags]`. OPTIONS tables carry an **ENV**
+column — resolution order is **flag > env > config/fixture > built-in default**.
+The human form never needs an env prefix (`VAR=x mm-harness …` is agent/CI only).
+Audience: **human** (daily, ≤1 flag), **agent** (depth), **both**.
+
+> Scope note: `evidence` / `quality` / `review` verbs from the wider DESIGN-mm-harness
+> map are **not** in this repo yet and out of scope; evidence is produced by `run`.
+
+## `launch` (REAL as of wave 3 → main DAILY LOOP verb)
+
+> **Implemented (wave 3):** `handleLaunch` in `runner/src/commands/launch.ts`. The typed
+> layer owns grammar (mobile-target mandatory, core/extension refusals), tier
+> selection, quick-launch change detection, overlay auto-ensure, healing policy +
+> bounds, teaching errors, and the `--json` contract. It does NOT rewrite
+> orchestration: it COMPOSES the same porcelain paths (grounded in bin/mm-recipe +
+> bin/mme-recipe case arms) and, for `--verify`, the overlay `live` sequence via
+> `handleHarness`. Composition seams `MM_HARNESS_MM_RECIPE_BIN` /
+> `MM_HARNESS_MME_RECIPE_BIN` / `MM_HARNESS_INSTALL_BIN` make every path
+> contract-testable without a device (`tests/contract/mm-harness-wave3.test.sh`).
+> Real-device boot + `--verify`/`--runway`/`--sidepanel` toggle land in the Tier B
+> on-device checklist.
+
+**Synopsis:**
+- Mobile: `mm-harness launch <ios|android> [flags]` — **target is MANDATORY**; missing target → teaching error: "specify ios or android"
+- Extension: `mm-harness launch [flags]` — target omitted; display mode via `--sidepanel` | `--fullscreen` (default `--fullscreen`)
+
+Quick relaunch by default. `--build` triggers a full native/webpack build first.
+
+**Per-platform behavior:**
+
+| Platform | Behavior |
+|---|---|
+| extension | Snapshot `dist/chrome`, open Chrome for Testing over CDP (never seeds the wallet fixture — first-run wallet is `fixtures set`). `--build` webpack-builds first; `--watch` starts the persistent watcher; `--sidepanel` opens sidepanel mode (default `--fullscreen`). |
+| mobile (ios\|android) | Start/reuse Metro, prewarm bundle, open iOS or Android dev client. `--build` = decision-aware native rebuild; default quick tier never triggers a native build. `--runway` runs a runway check after launch (mobile only; teaching error on extension). |
+| core | n/a — headless. Exit 2: "core is headless; use `mm-harness verify`". |
+
+**Options:**
+
+| Flag | Type | Default | ENV (agent) | Audience | Description |
+|---|---|---|---|---|---|
+| `<ios\|android>` positional | ios\|android | **required on mobile** | — | human | Target platform — mandatory; teaching error if omitted |
+| `--platform <p>` | mobile\|extension\|ios\|android | = positional / auto | `PLATFORM` | agent | Explicit platform (agent form of the positional) |
+| `--device <udid\|name>` | string | first booted sim | `IOS_SIMULATOR` / `ADB_SERIAL` | both | Target simulator/device |
+| `--build` | bool | false (quick) | `MOBILE_PREFLIGHT_MODE` | both | Full native/webpack build tier (replaces quick relaunch) |
+| `--watch` | bool | false | — | agent | Persistent webpack watcher then relaunch (extension only) |
+| `--verify` | bool | false | — | both | After launch: poll CDP/bridge until ready + run smoke verify (implements the retired `live` sequence: install overlay if missing → launch → poll → verify — never seeds fixtures; a first-run that needs a seeded wallet errors and points at `fixtures set`) |
+| `--sidepanel` | bool | false | — | human | Extension: open in sidepanel mode |
+| `--fullscreen` | bool | true | — | human | Extension: open fullscreen (default; explicit override of --sidepanel) |
+| `--runway` | bool | false | — | both | Post-launch runway check (mobile only; teaching error on extension: "runway is mobile-only") |
+| `--cdp-port <port>` | number | slot/context port | `CDP_PORT`/`RECIPE_CDP_PORT` | agent | Extension CDP port |
+| `--heal` | off\|infra-only\|auto | auto | — | both | Healing policy (see Part 5 §5.7). `auto` = auto-ensure overlay + heal transport (Metro/Chrome/CDP/tabs) silently; NEVER touches wallet state. `infra-only` = heal transport only. `off` = repro-preserving, no healing, also disables auto-install (the only opt-out). Bounds are ALWAYS enforced (recipe running / app-logic failure / same recovery already failed once → `recoverable:false` in `--json`); no flag bypasses them. `--yes` confirms prompts non-interactively. |
+| `--json` | bool | false | — | agent | Machine-readable summary; includes `recovered[]` (stable codes), `mutations[]`, `phase`, `schemaVersion` |
+| `--json-stream` | bool | false | — | agent | JSONL event stream on stdout (one event per line; see Part 5 §5.5) |
+
+**Auto-ensure overlay:** `launch` checks for the runtime overlay before launching (phase: `install`). If missing: installs it inline, then proceeds. **First-install overlay notice:** on the very first install for this checkout, prints `installed mm-harness overlay v<version> → <path>` to **stderr** in human mode; in `--json` it appears solely as `mutations[]` (stdout stays clean for machine output). Use `--heal=off` to disable all auto-install and healing (repro-preserving; use when `mm-harness install` runs explicitly upstream in CI).
+
+**Self-healing (idempotent, controlled by `--heal`):** `launch` detects broken runtime state and recovers — the agent's recovery command is simply re-running `mm-harness launch <target>`. It does NOT silently ignore a bad state; it makes reality match intent:
+
+| Platform | Detected broken state | Recovery action (internalized) |
+|---|---|---|
+| extension | Chrome closed / CDP offline / stale home tabs | reopen Chrome → CDP poll → close stale tabs (was: `runtime-launch` + `ensure-ready` + `runtime-health`) — never touches the wallet fixture |
+| mobile | Metro dead / dev client disconnected / bridge offline | Restart Metro → prewarm bundle → relaunch dev client (was: `runtime-decision` + `runtime-launch`) |
+
+Recovery is silent in human mode. With `--json`: `"recovered": ["metro.restarted", "tabs.cleared"]` (stable codes — see Part 5 §5.2). `recoverable:false` + `attemptedRecoveries` stop agent retry loops when bounds are hit. `--heal=off` disables all recovery (fail fast, exact broken state preserved).
+
+**Quick-launch change detection:** Before a quick launch (no `--build`), `launch` checks whether native build inputs (iOS Podfile.lock, Gradle wrapper, `package.json` native deps) or webpack config have changed since the last build using the farm layer's native-diff heuristic. If changed, refuses quick launch with a teaching error: `✗ native build inputs changed since last build — run: mm-harness launch <target> --build`. Never silently runs on a stale build.
+
+**Exit codes:** 0 launched · 1 launch failed · 2 bad args / core / missing mobile target · 3 infra failure not auto-healed (healing `off` or a bound was hit) · 4 bounded/not-retryable (see Part 5 §5.6).
+**Failure (teaching):** `✗ launch <platform> failed\n  <cause>\n  Next: <exact command>`.
+**Missing mobile target:** `✗ mm-harness launch: target is required for mobile.\n  Run: mm-harness launch ios   or   mm-harness launch android`.
+**Outputs:** running app + Metro/watcher; launch summary/logs under the slot runtime dir; `--json` status object.
+**Maps-to:** C:`ios\|start`,`android`,`up`,`refresh…`,`setup:ios/android`(launch half); D:`rebuild…`,`up`,`watch`+`rebuild`,`build`,`refresh*`,`sidepanel`.
+
+## `logs` (REAL as of wave 3 → main DAILY LOOP verb)
+
+> **Implemented (wave 3):** `handleLogs` in `runner/src/commands/logs.ts` — composes
+> the porcelain `logs` (+ `--full`). Teaching error (exit 2) when nothing is
+> running (no `metro.log`/`webpack.log` for the checkout), pointing at `launch`.
+
+**Synopsis:** `mm-harness logs [flags]` — tail Metro/webpack + app logs.
+
+| Flag | Type | Default | ENV (agent) | Audience | Description |
+|---|---|---|---|---|---|
+| `--full` | bool | false (compact) | `RECIPE_LOG_UI` | both | Raw log tail |
+| `--events <n>` | number | 10 | `RECIPE_LOG_EVENTS` | agent | Compact event count |
+| `--platform <p>` | mobile\|extension | auto | `PLATFORM` | agent | Force platform |
+| `--json` | bool | false | — | agent | Structured events |
+
+**Exit:** 0 · 2 bad args. **Maps-to:** C:`logs\|tail`; D:`logs\|tail\|tail-webpack`.
+
+## `debug` (REAL as of wave 3 → main DAILY LOOP verb)
+
+> **Implemented (wave 3):** `handleDebug` in `runner/src/commands/debug.ts` — extension
+> composes `debug` (`--worker` → `debug worker`); mobile composes `debug`
+> (`--dev-menu` → `dev-menu`). Cross-platform flag misuse teaches (exit 2).
+
+**Synopsis:** `mm-harness debug [flags]` — open the debug console.
+
+| Flag | Type | Default | ENV | Audience | Description |
+|---|---|---|---|---|---|
+| `--worker` | bool | false | — | both | Extension service-worker DevTools |
+| `--dev-menu` | bool | false | — | both | Mobile RN developer menu (folds `dev-menu` into a flag) |
+| `--platform <p>` | mobile\|extension | auto | `PLATFORM` | agent | Force platform |
+
+**Exit:** 0 · 2 bad args. **Maps-to:** C:`debug`,`dev-menu…`; D:`debug\|devtools\|inspect`(+`worker`).
+
+## `fixtures` (REAL as of wave 3 → main DAILY LOOP verb, with subcommands)
+
+> **Implemented (wave 3):** `handleFixtures` in `runner/src/commands/fixtures.ts`.
+> `sync` composes the porcelain `sync` (both adapters). `set` composes the porcelain
+> `setup-wallet <fixture>` on mobile; on the extension (documented GAP — no standalone
+> porcelain arm) it reuses `call`'s one-node engine path (`metamask.wallet.setup`,
+> `runOneNode` in `runner/src/cli.ts`). `set` always prints the fixture edit path;
+> the password is read FROM the fixture, never typed. On-device seed is Tier B.
+
+**One canonical wallet fixture per checkout** — same SSOT model as the farm installer. There is no fixture selection, listing, or bare status verb. **Fixture status is reported by `doctor` automatically** (grounded: `doctor.ts` `fixtureSummary()` already returns `{ status: 'missing'|'ready'|'incomplete'|'invalid', path, accountCount, hasPassword }` and is included in `createDoctorReport()` at line 125). The human edits `wallet-fixture.json` directly; `fixtures set` always teaches where.
+
+**Synopsis:** `mm-harness fixtures <sync|set> [flags]` — subcommand required.
+
+| Subcommand | Behavior |
+|---|---|
+| `sync` | Refresh **wallet fixture files** on the target (wallet DATA only — overlay refresh is `--heal` / `doctor --fix` territory, NOT `fixtures`; they are separate concerns) |
+| `set` | Apply THE canonical fixture (SRP/password/accounts) to the running slot — password read FROM the fixture, never typed; always prints "Want different accounts? Edit: <absolute-path>/wallet-fixture.json" |
+
+| Flag | Type | Default | ENV (agent) | Audience | Description |
+|---|---|---|---|---|---|
+| `--fixture <json>` | path | slot's `wallet-fixture.json` | `RECIPE_WALLET_FIXTURE` | **agent only** | Override fixture path; human form = edit the canonical file directly |
+| `--platform <p>` | mobile\|extension | auto | `PLATFORM` | agent | Force platform |
+
+**Exit:** 0 · 1 apply failed · 2 bad args.
+**`set` teaching output:** always ends with: `Wallet fixture applied.  Want different accounts? Edit: <absolute-path>/wallet-fixture.json`.
+**Maps-to:** `sync` ← C:`sync`, D:`sync`,`update\|sync-runtime`; `set` ← C:`setup-wallet\|wallet-setup`,`unlock`,`setup:ios/android`(wallet half).
+**Extension `set`:** [GAP] no standalone path today — the first-run wallet is seeded by the legacy `mme-recipe up`; the end-state home is `fixtures set` (launch / `launch --verify` never seed).
+
+## `run` (ROUTES-NOW → main PROVE verb)
+
+**Synopsis:** `mm-harness run <recipe.json> [flags]` — validate (adapter-aware) + execute a recipe, write evidence.
+
+| Flag | Type | Default | ENV (agent) | Audience | Description |
+|---|---|---|---|---|---|
+| `--adapter <p>` | mobile\|extension\|core | auto-detect (target) | `RECIPE_HARNESS_PLATFORM` | both | Target adapter · [DEFAULT-GAP] required today |
+| `--artifacts-dir <dir>` | path | slot artifacts dir | — | both | Evidence output · [DEFAULT-GAP] required today · **confirmed** in `cli.ts:415`, `adapters.ts:253` |
+| `--project-root`/`--target <repo>` | path | `$PWD` | — | both | Checkout under test |
+| `--plan` | bool | false | — | both | **REAL as of wave 2.** Plan-only mode: validate adapter-aware (schema + action existence/platform vs the adapter manifest) and print what would happen — touches NO device, writes NO artifacts. Exit 0 = plan valid; exit 5 = plan has errors (exit 2 = recipe missing/unparseable). `--json` = `{ status, adapter, recipe, findings[], plan[] }`; each `plan[]` item carries `confidence: static\|conditional`. |
+| `--action-manifest <path>` | path | bundled | — | agent | Override manifest |
+| `--library <name=path[:…]>` | string | personal/team then canonical | `RECIPE_LIBRARY_PATH` | agent | Recipe library sources |
+| `--cdp-port <port>` | number | context | `CDP_PORT`/`RECIPE_CDP_PORT` | agent | Extension CDP port |
+| `--slot <id>` | string | context | `FARMSLOT_SLOT_ID`/`SLOT_ID` | agent | Slot id (fleet) · **confirmed** in `cli.ts:51,819` (sets both env vars) |
+| `--launch-existing-dist` | bool | false | — | agent | Reuse existing dist (extension) |
+| `--record-video[=full-run]` | enum | off | — | agent | Record full-run video · **confirmed** (`parseRecordVideoMode` in `cli.ts:249`; `proof-window` reserved future mode; extension + iOS confirmed; Android not yet implemented) |
+| `--heal` | off\|infra-only\|auto | infra-only | — | both | Healing policy (see Part 5 §5.7). Default `infra-only` — heals overlay/runtime transport but NEVER touches wallet state. Use `off` for repro-preserving behavior. Bounds are always enforced. If the failure requires a wallet write → the verb stops with `recoverable:false` exit 4 and `userAction: "run mm-harness fixtures set"`. |
+| `--json` | bool | false | — | agent | Machine-readable result; includes `recovered[]` (stable codes), `mutations[]`, `plan[]` (with `--plan`), `schemaVersion` |
+| `--json-stream` | bool | false | — | agent | JSONL event stream on stdout (one event per line; see Part 5 §5.5) |
+
+**Pacing/slowMo:** No step-level pacing or slowMo flag exists on `run`. All CDP settle delays are hardcoded within orchestration scripts. `--settle-ms` exists only in `orchestration/extension/sidepanel-toggle.sh` (internal sidepanel CDP settle, not exposed on `run`). **[GAP — pacing option candidate]**: a `--step-delay-ms` or `--settle-ms` flag on `run` would let agents/CI slow down recipe execution for flaky-step debugging; not implemented today.
+
+**Validates first (adapter-aware):** Before touching any device, `run` validates the recipe: action existence in the adapter's manifest, platform support for each action, and fixture preconditions. Validation errors exit 5 with a structured error list. `--plan` stops here — prints the plan and exits, no device touched. Without `--plan`, validation failures are fatal before any execution begins.
+
+> **Wave-2 status:** adapter-aware validation (`validateRecipeDocument` +
+> `validateRecipeWithManifest`, shared helper `validateRecipeAdapterAware`) is
+> wired for **`run --plan`** and **`call`** at the pinned deps (`@farmslot/protocol`
+> `validateRecipeWithManifest` is available today). Two extensions land when
+> `@farmslot/recipe-harness >= 0.3.3` publishes: (1) `externalFlowIds` for recipes
+> that reference library flows by `call.ref` (needs `resolveRecipeLibrarySources`),
+> and (2) making the `run` **execute** path always-validate with those external ids.
+> Until then, self-contained recipes (all in-repo recipes + every one-node `call`
+> recipe) validate fully; the execute path relies on the engine's own manifest
+> validation. Tagged in code (`runner/src/cli.ts` `validateRecipeAdapterAware`).
+
+**Phase state-machine:** `resolve → install → healthcheck → recover → validate → launch → execute` (phase reported in `--json` as `phase`; `--json-stream` emits one event per phase transition).
+
+**Auto-ensure overlay:** `run` checks for the runtime overlay before executing (phase: `install`). If missing: installs it inline with a one-line notice, then proceeds. **First-install overlay notice:** on the very first install for this checkout, prints `installed mm-harness overlay v<version> → <path>` to stderr in human mode; in `--json` it appears solely as `mutations[]`. Use `--heal=off` to disable all auto-install and healing.
+
+**Self-healing (idempotent, controlled by `--heal`, default `infra-only`):** Before executing the recipe, `run` checks runtime health and heals broken infra state (Metro dead → restart; CDP offline → reopen Chrome) — but NEVER touches wallet state in `infra-only` mode. The agent re-runs `mm-harness run recipe.json` to recover from any mid-session failure — no separate recovery verb needed. `--json` gains `"recovered": ["metro.restarted", ...]` (stable codes; see Part 5 §5.2). `recoverable:false` + `attemptedRecoveries[]` stop agent retry loops when bounds are hit. `--heal=off` disables all recovery (fail fast, exact broken state preserved).
+
+**Exit:** 0 pass · 1 recipe fail/error · 2 bad args · 3 infra failure not auto-healed (healing `off` / bound hit) · 4 bounded/not-retryable · 5 validation failure (adapter-aware validation found errors; same code for `run`, `run --plan`, and `call`).
+**Outputs:** `summary.json`, `trace.json`, `artifact-manifest.json`, screenshots/logs under `--artifacts-dir`.
+**Maps-to:** A:`run` (ROUTES-NOW); C/D:`run` (ABSORB-LATER — supply the auto adapter+artifacts defaults the typed CLI lacks).
+
+## `doctor` (ROUTES-NOW → PROVE inspect verb)
+
+Readiness check for a checkout without launching the app. Doctor is the single place to understand the full slot context — **no hunting for files**. It also absorbs the retired `manifest` verb's validation function: the readiness checks include manifest well-formedness (schema valid, no unknown action references) and report the manifest path + protocol version in the explain-my-setup section. It includes three grounded sub-sections:
+
+**1. Fixture section** — grounded: `runner/src/doctor.ts` `fixtureSummary()` (line 69) returns `{ status: 'missing'|'ready'|'incomplete'|'invalid', path, accountCount, hasPassword }`, included in `createDoctorReport()` at line 125.
+
+**2. Runtime-context section (spec addition)** — reads `agentic-runtime.json` from `{target}/{runtimeDir}/agentic-runtime.json` (override: `RECIPE_RUNTIME_CONTEXT` env; grounded in `runner/src/harness.ts:206-244`) and prints every field with its current value, source, and how to customize:
+
+| Field | Env var set by harness | Flag override | How to customize |
+|---|---|---|---|
+| `slotId` | `RECIPE_SLOT_ID` | `--slot` | farmslot dispatch writes it |
+| `extensionId` | `RECIPE_HARNESS_EXTENSION_ID` | — | auto-resolved; edit file to pin |
+| `cdpPort` | `RECIPE_CDP_PORT` / `CDP_PORT` | `--cdp-port` | edit file or pass flag |
+| `runtimeStart.approved` | `RECIPE_RUNTIME_START_APPROVED` | — | edit file (`true`/`false`) |
+| `runtimeStart.command` | — | — | edit file |
+| `runtimeStart.readyUrl` | `RECIPE_RUNTIME_READY_URL` | — | edit file |
+
+**`--json` output shape** (end-state; includes both sections):
+```json
+{
+  "status": "pass",
+  "adapter": "extension",
+  "checks": [{ "id": "manifest", ... }],
+  "fixture": { "status": "ready", "path": "temp/recipe/.../wallet-fixture.json", "accountCount": 1, "hasPassword": true },
+  "runtimeContext": {
+    "file": "temp/recipe/.../agentic-runtime.json",
+    "fileExists": true,
+    "envOverride": null,
+    "fields": {
+      "slotId":   { "value": "slot-1", "source": "file", "envVar": "RECIPE_SLOT_ID", "customize": "farmslot dispatch writes this" },
+      "extensionId": { "value": "abc123", "source": "file", "envVar": "RECIPE_HARNESS_EXTENSION_ID", "customize": "auto-resolved; edit file to pin" },
+      "cdpPort":  { "value": "6663", "source": "file", "envVar": "CDP_PORT", "customize": "edit file or pass --cdp-port" },
+      "runtimeStart.approved": { "value": "true", "source": "file", "envVar": "RECIPE_RUNTIME_START_APPROVED", "customize": "edit file (true/false)" },
+      "runtimeStart.command": { "value": null, "source": "default", "envVar": null, "customize": "edit file" },
+      "runtimeStart.readyUrl": { "value": null, "source": "default", "envVar": "RECIPE_RUNTIME_READY_URL", "customize": "edit file" }
+    }
+  }
+}
+```
+
+| Flag | Type | Default | ENV | Audience | Description |
+|---|---|---|---|---|---|
+| `--adapter <p>` | mobile\|extension\|core | auto-detect | `RECIPE_HARNESS_PLATFORM` | both | Target · [DEFAULT-GAP] required today |
+| `--target <repo>` | path | `$PWD` | — | both | Checkout to probe |
+| `--action-manifest <path>` | path | bundled | — | agent | Override manifest (the file; `manifest` verb is retired) |
+| `--fix` | bool | false | — | both | Run healing steps WITHOUT launching — repair overlay, runtime context, and validate manifest; no app started. Exit 0 = all healed; 1 = partial/failed. `--json` adds `"fixed": [...]` and `"failed": [...]` arrays. |
+| `--json` | bool | false | — | agent | Machine-readable (includes fixture + runtimeContext sections; with `--fix`: adds fixed/failed arrays) |
+
+**`--fix` framing:** `doctor --fix` runs the same healing checks as `launch`/`verify`'s self-healing path but stops short of starting the app. Use it when the agent detects a broken state and wants to repair before the next `run` — or when CI needs to repair without a launch side-effect. `doctor` without `--fix` is always pure read-only.
+
+**Exit:** 0/1.
+**Maps-to:** A:`doctor` (ROUTES-NOW); C/D:`doctor` (ABSORB-LATER); retired `manifest` validation → absorbed here.
+
+---
+
+## DISCOVER — agent composition input
+
+> **Decided (Arthur):** DISCOVER is a distinct group, not a sub-PROVE. The audience
+> moment differs — composing before running — and `do` (try one action) makes the
+> group's value self-evident in `--help`.
+
+> **General rule:** a verb's most common action is its default. `mm-harness flows`
+> lists flows; `mm-harness flows promote` is the explicit subcommand. Never force
+> the user to type `list` when listing is what the verb does.
+
+The DISCOVER verbs are the agent's composition layer. The loop is:
+`actions --json` (vocabulary) → `call <action>` (try one action via real engine path) → `flows --json` (reusable flows) →
+compose `recipe.json` → `run --plan` (adapter-aware plan + validate, no device) → `run` (execute).
+`--json` is the **PRIMARY** form for every DISCOVER verb — the human form is the
+pretty-printed fallback. `manifest` is **RETIRED**: raw protocol dump rehomes to
+`actions --raw` (same JSON as `manifest --json` today); validation moves into
+`run --plan` / `doctor`. `validate` verb **DISSOLVED** into `run` (`run` validates first; `run --plan` = plan-only). **DISCOVER final shape: `actions` · `call` · `flows`.**
+
+### `actions` (ROUTES-NOW → DISCOVER verb)
+
+**Synopsis:** `mm-harness actions --adapter <p> [--json] [--action <name>] [--kind official|custom]`
+
+**PRIMARY (agent):** `mm-harness actions --adapter mobile --json`
+
+**`--json` output shape** (grounded — `actions --adapter core --json` confirmed):
+```json
+{
+  "adapter": "core",
+  "actions": [
+    {
+      "name": "metamask.perps.read_positions",
+      "kind": "custom",
+      "description": "Read live Perps positions...",
+      "fields": ["account", "action", "market", "markets", "mode", "selector", "side", "symbol", "symbols", "timeout_ms"],
+      "examples": [{ "node": { "action": "metamask.perps.read_positions", "account": "...", "symbol": "BTC" } }]
+    }
+  ]
+}
+```
+`kind` is `"official"` (engine built-ins) or `"custom"` (MetaMask adapter actions). `fields` lists every accepted parameter name. `examples[].node` is a copy-pasteable recipe node.
+
+**Human form:** `mm-harness actions --adapter mobile` — one line per action: `<name> (<kind>) <description>  fields=<f1,f2,...>`.
+
+| Flag | Type | Default | ENV | Audience | Description |
+|---|---|---|---|---|---|
+| `--adapter <p>` | mobile\|extension\|core | auto-detect | `RECIPE_HARNESS_PLATFORM` | both | Target adapter · [DEFAULT-GAP] required today |
+| `--action <name>` | string | all | — | agent | Filter to one action; full schema + all examples |
+| `--kind <k>` | official\|custom | all | — | agent | Filter by action kind |
+| `--action-manifest <path>` | path | bundled | — | agent | Override manifest |
+| `--raw` | bool | false | — | agent | Dump the underlying action manifest JSON (protocol version, registry version, all entries in raw registry format — same output as `manifest --json` today; replaces the retired `manifest` verb) |
+| `--json` | bool | false | — | **agent PRIMARY** | Full schema + fields + examples per action |
+
+**[DISCOVERY-GAP]:** No `--action <name>` single-action filter today (all or nothing). No `--kind` filter. No keyword search across descriptions or fields.
+**Exit:** 0 / non-zero on engine error.
+**Maps-to:** A:`actions` (ROUTES-NOW); C/D:`actions` (ABSORB-LATER).
+
+### `call <action>` (REAL as of wave 2 → DISCOVER verb; one-node recipe via real engine path)
+
+> **Implemented (wave 2):** `handleCall` in `runner/src/cli.ts` synthesizes a
+> single-node recipe and hands it to `runRecipe` — the SAME path `run` uses — so
+> `call` writes the same `summary.json` / `trace.json` / `artifact-manifest.json`
+> evidence. Fuzzy resolution, `--arg k=v` mapping, adapter-aware validation
+> (exit 5), and the `--json` shape are covered by `tests/contract/mm-harness-wave2.test.sh`.
+
+> Direct top-level actions (`mm-harness unlock`) are **REJECTED**: an open action
+> vocabulary would collide with the verb namespace; hot actions get deliberately
+> promoted to real verbs instead.
+
+**Synopsis:** `mm-harness call <action> [--arg k=v …] [--adapter <p>] [--json]`
+
+**What it does:** Execute ONE action from the adapter vocabulary as a single-node recipe through the **real engine path** — same trace/evidence shape as `run`, same phase state-machine, same `--json` contract. This is NOT a shortcut; it is one door into the same execution engine. The distinction: `call` = one node, `run` = a graph. Grounded in the hook layer's existing `run-action` concept (e.g., `run-action app.unlock`).
+
+**One execution path, two doors:** `call <action>` internally synthesizes a single-node recipe `{"nodes":[{"action":"<resolved>","args":{...}}]}` and hands it to the run engine. The result (`--json`) carries the same `trace[]`, `evidence`, `recovered[]`, `mutations[]`, and `schemaVersion` fields as `run --json`.
+
+**Fuzzy short-name resolution:** an unambiguous short name resolves to the full action name (`unlock` → `metamask.wallet.unlock`). If ambiguous, exit 2 and list candidates: `✗ "unlock" is ambiguous: metamask.wallet.unlock, metamask.session.unlock — use the full name`.
+
+**Human example:** `mm-harness call unlock` → resolves unambiguously to `metamask.wallet.unlock`
+
+**Agent example:** `mm-harness call metamask.perps.read_positions --arg symbol=BTC --arg side=long --adapter core --json`
+
+| Flag | Type | Default | ENV | Audience | Description |
+|---|---|---|---|---|---|
+| `<action>` positional | string | required | — | both | Full action name or unambiguous short name (fuzzy resolved from adapter vocabulary) |
+| `--arg <k=v>` | string (repeatable) | — | — | both | Action field value; repeatable: `--arg symbol=BTC --arg side=long` |
+| `--adapter <p>` | mobile\|extension\|core | auto-detect | `RECIPE_HARNESS_PLATFORM` | both | Target adapter |
+| `--json` | bool | false | — | **agent PRIMARY** | `{ action, resolvedAction, args, trace, evidence, recovered, mutations, exitCode, schemaVersion }` — same shape as `run --json` (one-node subset) |
+
+**Exit:** 0 success · 1 action failure · 2 bad args / ambiguous / unknown action · 5 validation failure (the one-node recipe failed adapter-aware validation).
+**Maps-to:** hook layer `run-action` (grounded); `handleCall` wired in `runner/src/cli.ts` (wave 2).
+
+### `flows` / `flows promote` (ROUTES-NOW → DISCOVER verb)
+
+**What `flows` is:** the **reusable flow library** — pre-built, verified building blocks composed into recipes for efficiency and reuse. A recipe is mostly library-flow references plus a few unique steps; it is not rewritten from scratch each time. `flows promote` publishes a proven flow up a tier (personal → team → canonical), capturing it as a durable artifact. This is the composition story: discover what the library covers, compose from it, only author the delta.
+
+**Synopsis:** `mm-harness flows [--library <name=path>] [--json]` (bare = list; most common action is the default)
+
+**PRIMARY (agent):** `mm-harness flows --json`
+
+**`--json` output shape** (grounded — `flows-command.ts` `flowsListDocument()`):
+```json
+{
+  "sources": [
+    { "name": "personal", "root": "/home/user/.farmslot/recipe-library" },
+    { "name": "team", "root": "/path/to/project/recipe-library" }
+  ],
+  "flows": [
+    {
+      "ref": "perps/open-long",
+      "source": "personal",
+      "file": "perps/open-long.json",
+      "description": "Open a long position on HL testnet",
+      "requiredParams": ["symbol", "amount"],
+      "shadows": ["team/perps/open-long"],
+      "lastVerified": "2025-06-14T10:00:00Z"
+    }
+  ]
+}
+```
+`source` is the library name whose copy wins (personal > domain > canonical). `shadows` lists lower-precedence entries that this flow overrides. `lastVerified` stamps from `flows promote --run <artifacts>`.
+
+**Human form:** `mm-harness flows` (bare = list, no subcommand needed) — text table: `<ref>  source=<s>  file=<f>  [lastVerified=<t>]  [shadows=<s,...>]`; description + `params:` line if present.
+
+| Flag | Type | Default | ENV | Audience | Description |
+|---|---|---|---|---|---|
+| `--library <name=path>` | string (repeatable) | personal/team then canonical | `RECIPE_LIBRARY_PATH` | agent | Library sources, precedence first |
+| `--json` | bool | false | — | **agent PRIMARY** | Full catalog with source, shadows, lastVerified |
+
+**[DISCOVERY-GAP]:**
+- No `--filter <keyword>` to search across refs/descriptions — cannot efficiently find flows covering a given screen or user story **[DISCOVERY-GAP]**
+- No `--platform <p>` filter — platform-specific flows not discoverable without scanning all refs **[DISCOVERY-GAP]**
+- No `--flow <ref>` to fetch a single flow's full body before composing — agent must read the file directly **[DISCOVERY-GAP]**
+- `shadows` is present in JSON but no human-readable "what would override what" summary **[DISCOVERY-GAP]**
+- Domain/coverage metadata absent — no way to ask "which flows cover the swap screen?" without scanning **[DISCOVERY-GAP]**
+
+**Exit:** 0 / 1 (no sources found) / non-zero on engine error.
+**Maps-to:** A:`flows` (ROUTES-NOW).
+
+### `validate` — DISSOLVED into `run`
+
+**`mm-harness validate` is REMOVED as a standalone verb.** Zero capability lost.
+
+**Rehome:** `run` now validates first (adapter-aware: action existence, platform support, fixture preconditions) on every invocation. For plan-only validation without touching a device, use:
+
+```
+mm-harness run recipe.json --plan [--json]
+```
+
+`--plan` exits 0 if the plan is valid (exit 5 on errors). `--json` includes `plan[]` array + `validation` object with findings — same or richer than the former `validate --json` shape, plus adapter cross-check (the former [DISCOVERY-GAP] is gone: `run --plan --adapter <p>` validates action names against the specific adapter's manifest).
+
+**Implementation note:** `@farmslot/recipe-harness` `validate-command.ts` is called internally by the `run` phase state-machine (phase: `validate`). No external wiring of `handleValidate` is needed; the capability is subsumed. The old stub teaching message for `mm-harness validate` should be updated to point at `mm-harness run <recipe> --plan`.
+
+## Runtime overlay: `install` · `verify` · `cleanup` (ROUTES-NOW → OVERLAY verbs)
+
+**Synopsis:** `mm-harness install|verify|cleanup [target] [flags]` — manage the
+per-checkout runtime overlay. Final home is top-level (no `harness` prefix). `live` is **REMOVED** — dissolved into `launch --verify` (same sequence: install overlay if missing → launch → CDP poll → smoke verify; zero capability lost — `launch --verify` never seeds fixtures).
+
+> **Auto-ensure note:** `launch` and `run` auto-install the overlay if
+> missing (with a one-line notice; `--heal=off` to disable). `install` is
+> the explicit form for CI, agents, and deterministic setup where the install step
+> must be auditable and separate. Human daily users need never call `install`
+> explicitly — daily verbs handle it.
+
+> **Self-healing note:** `verify` heals the overlay if missing (re-installs before probing health) and reports runtime state (Metro/Chrome/CDP) but does not restart it — use `launch` for that, or `doctor --fix` to repair without launching. `--json` gains `"recovered": [...]` when healing occurs.
+
+**Per-platform behavior:**
+
+| Verb | extension | mobile | core |
+|---|---|---|---|
+| `install` | `node inject.mjs` overlay → `temp/recipe/harness/extension/`; writes `.runner-source` | `inject.sh` overlay → `.../mobile/` | `inject.sh` overlay → `.../core/` |
+| `verify` | overlay/CDP/bridge health (prefers installed `scripts/verify.sh`) | Metro + JS bridge health | delegates to installed `mm-harness doctor --adapter core` |
+| `cleanup` | remove overlay (respects `.runner-source`) | remove overlay | remove overlay |
+
+**Options:**
+
+| Flag | Type | Default | ENV (agent) | Audience | Description |
+|---|---|---|---|---|---|
+| `[target]` positional | mobile\|extension\|core | auto-detected | — | human | Force adapter without a flag |
+| `--platform`/`--adapter <p>` | mobile\|extension\|core | = positional / auto (git remote / markers) | `RECIPE_HARNESS_PLATFORM` | agent | Explicit adapter; a later `--platform ios\|android` is forwarded to the script |
+| `--target <repo>` | path | `$PWD` | — | both | Checkout to operate on |
+| `--json` | bool | false | — | agent | One JSON summary on stdout (child output → stderr) |
+| `-- <args>` | passthrough | — | — | agent | Forwarded verbatim (e.g. `-- --cdp-port 6665`) |
+
+**Exit:** 0 pass · 1 orchestration error / missing delegate · 2 bad args / unsupported (`live` on core).
+**Failure (teaching):**
+```
+✗ verify core failed
+  core recipe harness not installed: missing delegate <path>.
+  Next: mm-harness install --platform core --target <repo>
+```
+**JSON:** `{ schemaVersion, command:"harness", action, adapter, target, autoDetected, status, exitCode }`.
+**Maps-to:** A:`harness <verb>` (ROUTES-NOW); E: skill (REMOVE); F: orchestration entry points (KEEP-INTERNAL); C/D:`prepare`,`ready\|ensure-ready` (ABSORB-LATER).
+
+## Advanced (collapsed → KEEP-INTERNAL)
+
+**All six ADVANCED verbs are removed from the CLI surface and `--help`** — their logic
+moves inside the self-healing daily verbs and internal plumbing. No user-facing verb
+remains in this group.
+
+| Verb | Fate | Rehomed inside |
+|---|---|---|
+| `runtime-health` | KEEP-INTERNAL | `launch`/`verify` self-healing — extension CDP health probe |
+| `runtime-decision` | KEEP-INTERNAL | `launch` self-healing — quick vs full build decision; mobile bridge health |
+| `runtime-launch` | KEEP-INTERNAL | `launch` self-healing — extension runtime launch sequence (snapshot dist → Chrome → CDP poll; never touches the wallet fixture) |
+| `resolve-extension` | KEEP-INTERNAL | `launch`/`launch --verify` internal plumbing — extension id resolution at attach time |
+| `ensure-ready` | KEEP-INTERNAL | `launch`/`verify` self-healing — stale tab cleanup + CDP readiness wait |
+| `self-test` | KEEP-INTERNAL | CI smoke test; callable via `package.json` scripts (`yarn self-test`); not in `--help` |
+
+`manifest` is **REMOVED** (see Surface A fate mapping): (1) validation → `doctor` readiness check; (2) raw dump → `actions --raw`; (3) path + protocol version → `doctor` explain-my-setup. The raw JSON shape previously returned by `manifest --json` is now `mm-harness actions --raw`.
+
+Porcelain infra (`ports`, `runtime-status`, `decision`, `status`, `stop`) folds into
+`mm-harness` status/`--json` flags (ABSORB-LATER).
+
+## Implementation notes (spec-only; draft code stays hand-rolled)
+
+- **CLI library:** the refactor implementation adopts **`commander`** — the same
+  library `@farmslot/recipe-harness` uses for its CLI (confirmed:
+  `packages/recipe-harness/package.json` deps `"commander": "^12.0.0"`, bin
+  `bin/farmslot-recipe.mjs`). Use it for grouped help, positionals, subcommands,
+  and completion generation, replacing the hand-rolled parser in `runner/src/cli.ts`.
+- **Positional grammar:** `mm-harness <verb> [target] [flags]`; target is the
+  human form, `--platform` the agent form, wired via commander positionals.
+- **Completions (dynamic, sourced from DISCOVER layer — SHIPPED):** `mm-harness`
+  ships zsh + bash completions in the npm package (`scripts/completions.sh`) with an
+  install command (`mm-harness completions install` → `scripts/install-completions.sh`,
+  prints the `source` line to add to `~/.zshrc` / `~/.bashrc`; the farm installer
+  companion can auto-source it later — precedent: farmslot's `compdef` flow).
+  Completions are **dynamic**, not static:
+  - **Commands + targets + flags:** static (from the mm-harness surface): commands,
+    the `launch` positional (`ios|android`), `fixtures` (`sync|set`), and per-command flags.
+  - **Action names for `call`:** completed live from
+    `mm-harness completion-candidates actions` (adapter manifest, cache-backed).
+  - **Flow refs for `run`:** completed live from `mm-harness completion-candidates flows`
+    (recipe library) alongside recipe-file completion. **REAL** on
+    `@farmslot/recipe-harness >= 0.3.3` — `completion-candidates flows` enumerates the
+    resolved library flows (`loadRecipeLibraries`) instead of degrading to empty.
+  - **Cache:** per-checkout cache file (`{runtimeDir}/.completion-cache.json`),
+    invalidated on `mm-harness install` (overlay change). TTL: short (60 s fallback),
+    refreshed lazily on first tab-complete after invalidation. Cache miss = silent
+    static fallback; never blocks the shell.
+  - **Principle:** DISCOVER feeds the agent (compose), the shell (complete), and the
+    docs (cheatsheet) — one source of truth for what actions and flows exist.
+  Replaces `completions/_recipe` (removed).
+- **Resolution order everywhere:** flag > env > config/fixture > built-in default.
+
+---
+
+# Part 3 — Caller audit (0 unmapped)
+
+Every place that invokes a removed name today → what it calls after the wave.
+An unlisted caller = the wave can't ship. Grounded in `grep` over this repo +
+the sibling `farmslot` repo.
+
+## In-repo (metamask-recipe-runner)
+
+| Caller (path) | Invokes today | After |
+|---|---|---|
+| `orchestration/{core,mobile}/inject.sh`, `orchestration/extension/inject.mjs` | Writes delegate `runner/bin/metamask-recipe` into the installed overlay | Write `runner/bin/mm-harness` delegate |
+| `orchestration/mobile/{launch,live}.sh`, `orchestration/extension/{live,launch,ensure-browser}.sh` | `RUNNER_BIN=…/runner/bin/metamask-recipe`; human hints "Run metamask-recipe … prepare / runtime-launch" | `mm-harness` bin path + updated hint text |
+| `orchestration/extension/runtime.ts` (`runtime-launch` help block) | Prints `bin/metamask-recipe run … --adapter extension …` | `mm-harness run …` |
+| `orchestration/extension/live.sh` (`display_args`, `easyCommand`) | resolved — prints `mm-harness launch --verify …` | done |
+| `orchestration/mobile/live.sh` (`easyCommand`, echo) | resolved — prints `mm-harness launch <target> --verify` | done |
+| `orchestration/{core,mobile,extension,lib}/*` error prefixes `metamask-recipe: …` | cosmetic name in messages | `mm-harness: …` |
+| `completions/_recipe` | zsh completion for `recipe`/`mm-recipe`/`mme-recipe` | Removed; replaced by bundled `mm-harness` completions |
+| `bin/metamask-recipe` `mobile`/`extension` passthrough | execs `bin/mm-recipe` / `bin/mme-recipe` | Absorbed — `mm-harness` verbs; passthrough removed |
+| `package.json` `bin`, `scripts` (`self-test`, `manifest:*`) | `bin/metamask-recipe …` | `bin/mm-harness …`; `manifest:*` scripts → `mm-harness actions --raw` (protocol dump) or removed if CI-only |
+
+## Sibling repo (farmslot) — updated in the same wave
+
+| Caller (path) | Invokes today | After |
+|---|---|---|
+| `projects/metamask-extension-farm/project.json`, `projects/metamask-core-farm/project.json` | farm hooks / commands calling the runner bin + skill | `mm-harness` verbs |
+| `projects/metamask-extension-farm/setup/*.sh` (`launch-browser.sh`, `health-check.sh`, `ensure-runtime-ready.sh`, `preflight.sh`) | `metamask-recipe` / `mme-recipe` invocations | `mm-harness` verbs |
+| `projects/metamask-extension-farm/setup/generate-fixture.cjs` | fixture generation referencing the runner | `mm-harness fixtures …` where applicable |
+| `projects/metamask-core-farm/scripts/check-core-farm.mjs`, `fixtures/README.md`, `AGENTS.md` | `metamask-recipe` verbs | `mm-harness` verbs |
+| `projects/*/templates/worker/*.md`, `fixtures/**/*.md`, `learnings/LEARNINGS.md`, architecture docs | documented `metamask-recipe`/`mm-recipe`/`mme-recipe` commands | rewritten to `mm-harness` |
+| farm project-shortcut hooks (the slot-bound "same verb name" bindings) | wrap runner/skill invocations | wrap `mm-harness` (one verb vocabulary, three bindings) |
+
+**Completeness:** every grep hit above is mapped; **0 unmapped**. Any new caller
+discovered before the wave must be added here first.
+
+---
+
+# Part 4 — Env-var audit (0 unmapped)
+
+Env vars a human is told to type today become flags with config/fixture defaults.
+`[ENV-GAP]` = a human types it today; end state = flag + stored default, zero
+prefix. Agent/CI may still set the env (resolution: flag > env > config > default).
+
+| Env var (today) | Human-typed? | End-state flag | Config/fixture default | Tag |
+|---|---|---|---|---|
+| `MOBILE_PREFLIGHT_MODE` / `RECIPE_HARNESS_MOBILE_PREFLIGHT_MODE` | yes | `launch --build` (tier) | quick tier default | [ENV-GAP] |
+| `MM_PASSWORD` (unlock) | yes | none — `fixtures set` reads the fixture | wallet fixture password | [ENV-GAP] — the canonical anti-pattern |
+| `RECIPE_WALLET_FIXTURE` | yes | `fixtures set --fixture` | slot `wallet-fixture.json` | [ENV-GAP] |
+| `RECIPE_LIBRARY_PATH` | yes | `run/flows --library` | personal/team then canonical | [ENV-GAP] |
+| `IOS_SIMULATOR` / `ADB_SERIAL` / `ANDROID_SERIAL` / `ANDROID_DEVICE` | yes | `launch --device` | first booted sim / slot config | [ENV-GAP] |
+| `CDP_PORT` / `RECIPE_CDP_PORT` | yes | `--cdp-port` | slot/runtime context | [ENV-GAP] (agent flag ok) |
+| `WATCHER_PORT` / `METRO_PORT` / `RECIPE_WATCHER_PORT` | yes | `--watcher-port` | slot/runtime context | [ENV-GAP] |
+| `RECIPE_LOG_UI` / `RECIPE_LOG_EVENTS` | yes | `logs --full` / `--events` | compact, 10 | [ENV-GAP] |
+| `RECIPE_HARNESS_ROOT` / `RECIPE_RUNTIME_DIR` | rarely | `--harness-root` (agent) | `path-defaults.json` | KEEP-INTERNAL |
+| `FARMSLOT_SLOT_ID` / `RECIPE_SLOT_ID` / `SLOT_ID` | fleet only | `--slot` | dispatch context | KEEP-INTERNAL (agent/fleet) |
+| `PLATFORM` / `RECIPE_HARNESS_PLATFORM` | agent | `--platform` / positional target | auto-detect | KEEP-INTERNAL (agent) |
+| `MOBILE_METRO_CLEAR` / `MOBILE_BUNDLE_PREWARM*` / `METRO_MAX_WORKERS` / `RECIPE_UP_INSTALL_ATTEMPTED` / `METAMASK_RECIPE_*` | internal | internal knobs of `launch` | built-in | KEEP-INTERNAL |
+
+**Completeness:** every human-typed env prefix in the current surface is mapped to
+a flag + default (`[ENV-GAP]`); internal/agent-only vars are KEEP-INTERNAL;
+**0 unmapped**.
+
+**Implemented:** the `[ENV-GAP]` flags exist with resolution order **flag > env >
+config/default** (the flag sets the env var the porcelain reads, so it wins; an
+absent flag leaves the agent/CI env untouched):
+- `launch --device` (`IOS_SIMULATOR` for ios · `ADB_SERIAL`/`ANDROID_SERIAL`/`ANDROID_DEVICE` for android)
+- `launch --cdp-port` (`CDP_PORT`/`RECIPE_CDP_PORT`) · `launch --watcher-port` (`WATCHER_PORT`/`METRO_PORT`/`RECIPE_WATCHER_PORT`) — numeric, teaching error otherwise
+- `launch --build` covers `MOBILE_PREFLIGHT_MODE` (tier) · `logs --full`/`--events` cover `RECIPE_LOG_UI`/`RECIPE_LOG_EVENTS`
+- `fixtures set --fixture` (`RECIPE_WALLET_FIXTURE`) · `run`/`flows --library` (`RECIPE_LIBRARY_PATH`)
+- `MM_PASSWORD` stays flag-less by design — `fixtures set` reads the password FROM the fixture.
+
+Precedence is contract-tested in `tests/contract/mm-harness-wave5.test.sh`.
+
+---
+
+# Part 5 — Agent Error Contract
+
+Agents (orchestrators, CI, LLM tool-callers) need machine-grade signals to decide: retry, escalate, or abort. This section defines the complete contract: structured errors, stable codes, exit taxonomy, event stream, and healing policy. All `--json` output from every verb conforms to this contract.
+
+## §5.1 Structured error object
+
+Every failure in `--json` mode produces an `error` field at the top level:
+
+```json
+{
+  "error": {
+    "code": "METRO_START_FAILED",
+    "message": "Metro bundler failed to start within 60s",
+    "cause": "port 8081 already in use by pid 12345",
+    "retryable": true,
+    "userAction": "Free port 8081 (kill pid 12345), then re-run: mm-harness launch ios"
+  }
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `code` | string (UPPER_SNAKE) | Stable machine code — never changes; safe to `switch` on in agent code |
+| `message` | string | Human-readable summary |
+| `cause` | string \| null | Root cause detail (OS error, process output, etc.) |
+| `retryable` | boolean | `true` = same command may succeed on retry; `false` = agent must change inputs or escalate |
+| `userAction` | string \| null | Exact next command or manual step |
+
+## §5.2 Stable recovery codes (`recovered[]`)
+
+`recovered[]` in `--json` output lists what was healed. These are stable enum values — not prose, safe to match in agent code:
+
+| Code | What happened |
+|---|---|
+| `overlay.reinstalled` | Runtime overlay was missing or corrupted; reinstalled inline |
+| `metro.restarted` | Metro bundler was dead; restarted and bundle prewarmed |
+| `chrome.reopened` | Chrome was closed or crashed; reopened with correct profile/flags |
+| `cdp.reconnected` | CDP websocket was stale/disconnected; reconnected and verified |
+| `tabs.cleared` | Stale home/onboarding tabs were open; closed before proceeding |
+
+All recovery codes are **infra-only**. Healing never touches wallet state: a missing/invalid fixture is not "recovered" — the verb stops with `recoverable:false` and `userAction: "run mm-harness fixtures set"` (the only path that mutates wallet data).
+
+## §5.3 `mutations[]` — side-effect manifest
+
+Every `--json` response includes `mutations[]` listing all side effects the command produced on the system. Agent can diff pre/post state or verify cleanup:
+
+```json
+{
+  "mutations": [
+    { "type": "file",    "path": "/path/to/temp/recipe/harness/extension/inject.js", "action": "created" },
+    { "type": "process", "name": "metro",   "pid": 45678, "action": "started" },
+    { "type": "port",    "port": 8081,      "action": "bound" },
+    { "type": "fixture", "path": "/path/to/wallet-fixture.json", "action": "seeded" },
+    { "type": "tab",     "url": "chrome-extension://abc/home.html", "action": "closed" }
+  ]
+}
+```
+
+| `type` | `action` values | When emitted |
+|---|---|---|
+| `file` | `created` / `deleted` / `modified` | Overlay install/cleanup; fixture write |
+| `process` | `started` / `killed` | Metro start/stop; Chrome open/close |
+| `port` | `bound` / `freed` | Metro/CDP port lifecycle |
+| `fixture` | `seeded` / `cleared` | Wallet fixture apply/reset |
+| `tab` | `opened` / `closed` | Chrome tab lifecycle (extension CDP) |
+
+## §5.4 Phase state-machine
+
+Every `--json` response includes a `phase` field reflecting the last completed phase. `--json-stream` emits one event per transition. Agents can detect exactly where a failure occurred.
+
+**`run` phases:**
+```
+resolve → install → healthcheck → recover → validate → launch → execute
+```
+
+**`launch` phases:**
+```
+resolve → install → healthcheck → recover → launch → verify
+```
+
+| Phase | What happens |
+|---|---|
+| `resolve` | Recipe/target/adapter resolved; library sources loaded |
+| `install` | Overlay auto-ensure check; install if missing (overlay install notice to stderr on first install) |
+| `healthcheck` | Probe runtime state (Metro/CDP/bridge) |
+| `recover` | Apply `--heal` policy; execute recovery actions; emit `recovered[]` |
+| `validate` | Adapter-aware recipe validation (action existence, platform support, fixture preconditions). `run --plan` exits here. |
+| `launch` | Start/attach to app (Metro prewarm, Chrome open, CDP attach) |
+| `execute` | Run recipe nodes; collect trace/evidence (`run` only) |
+| `verify` | Smoke verify after launch (`launch --verify` only) |
+
+## §5.5 JSONL event stream (`--json-stream`)
+
+`--json-stream` emits one JSON object per line on stdout as the command progresses. Parseable with `jq -R 'fromjson?'`. Schema is versioned via `schemaVersion`.
+
+```jsonl
+{"schemaVersion":1,"event":"phase","phase":"resolve","ts":"2026-07-02T10:00:00.000Z"}
+{"schemaVersion":1,"event":"phase","phase":"install","ts":"2026-07-02T10:00:00.100Z"}
+{"schemaVersion":1,"event":"mutation","mutation":{"type":"file","path":"/...","action":"created"},"ts":"..."}
+{"schemaVersion":1,"event":"phase","phase":"validate","ts":"..."}
+{"schemaVersion":1,"event":"phase","phase":"execute","ts":"..."}
+{"schemaVersion":1,"event":"node","index":0,"action":"metamask.wallet.unlock","status":"running","ts":"..."}
+{"schemaVersion":1,"event":"node","index":0,"action":"metamask.wallet.unlock","status":"passed","ts":"..."}
+{"schemaVersion":1,"event":"complete","status":"pass","exitCode":0,"recovered":[],"mutations":[...],"ts":"..."}
+```
+
+Event types: `phase` · `node` · `mutation` · `recovery` · `error` · `complete`. The terminal `complete` event always appears (even on failure) so agents have a clean sentinel.
+
+## §5.6 Exit code taxonomy
+
+Consistent across all verbs. Agents must not retry on exit 2 or 4.
+
+| Code | Meaning | Agent action |
+|---|---|---|
+| 0 | Success | Proceed |
+| 1 | Recipe/operation failed (app-logic: assertion, action error, fixture mismatch) | Diagnose; do NOT auto-retry blindly |
+| 2 | Bad args / unsupported platform / missing required input | Fix command; do NOT retry |
+| 3 | Infra failure not auto-healed (healing `off`, or a recovery bound was hit) | Re-run with default healing; escalate if still 3 |
+| 4 | Bounded / not-retryable (same recovery already failed once; failure needs a wallet fixture write — run `fixtures set`; recipe running) | Escalate; do NOT retry |
+| 5 | Validation failure (`run`, `run --plan`, `call`): adapter-aware validation found errors | Fix recipe; do NOT retry |
+
+**Bound-specific `error.code` values.** When a recovery bound fires, `error.code` names the exact bound (not a generic `LAUNCH_FAILED`) so agents branch on the cause. Every bound also carries `error.originalError` — the original failure output verbatim — so the real cause is never replaced by the classification note. Shared by `launch`, `run`, and `call`:
+
+| `error.code` | Fires when | Exit |
+|---|---|---|
+| `APP_LOGIC_FAILURE` | Failure is app-logic (assertion, wrong route) — healing cannot help; surfaced verbatim | 1 |
+| `WALLET_STATE_REQUIRED` | Recovery would need a seeded wallet — healing never touches fixtures (`userAction: "run mm-harness fixtures set"`) | 4 |
+| `RECIPE_RUNNING` | A recipe is executing — recovery refused to avoid corrupting mid-run state | 4 |
+| `SAME_RECOVERY_TWICE` | The same recovery already failed once this invocation — refused to avoid a loop | 4 |
+
+**Stopping agent retry loops:** when `recoverable:false` appears in `--json` alongside `attemptedRecoveries[]`, the agent MUST NOT retry. The harness already attempted recovery and it failed or hit a bound.
+
+```json
+{
+  "recoverable": false,
+  "attemptedRecoveries": ["metro.restarted"],
+  "error": { "code": "SAME_RECOVERY_TWICE", "retryable": false, "originalError": "...", ... }
+}
+```
+
+## §5.7 Healing policy (`--heal`)
+
+Controls what the harness is allowed to repair autonomously. Defaults differ by verb: `launch` defaults `auto`; `run` and `call` default `infra-only`.
+
+| Value | Behavior |
+|---|---|
+| `off` | No healing, no auto-install. Fail fast with a teaching error; exact broken state preserved (repro-preserving). |
+| `infra-only` | Heal overlay/runtime transport (Metro, Chrome, CDP, tabs) only. NEVER touches wallet state. `run`/`call` default. If a wallet write is needed → `recoverable:false` exit 4, `userAction: "run mm-harness fixtures set"`. |
+| `auto` | Auto-ensure the overlay + heal transport silently. Still NEVER touches wallet state (that is `fixtures set`, explicit only). `launch` default. |
+
+`--yes` confirms any prompt non-interactively (CI/agent safe). The three `--heal` values above are the ONLY opt-out mechanism: healing bounds are ALWAYS enforced and no flag bypasses them, and wallet state is mutated only by the explicit `fixtures set`.
+
+**Recovery bounds (always enforced regardless of `--heal`):**
+- Recipe currently executing → refuse all recovery (would corrupt mid-run state)
+- Failure is app-logic (assertion failure, wrong route) → refuse infra recovery (wrong tool)
+- Same recovery already failed once in this invocation → refuse (avoid infinite loops)
+
+---
+
+## Considered and rejected
+
+**Teaching-tombstone stub bins (`mm-harness-legacy`, `metamask-recipe-stub`, etc.):** Rejected. Installing stub binaries that print "this command moved to mm-harness" before any user has adopted the new surface creates pre-adoption debt with zero payoff. The coordinated wave (Part 3) updates all callers atomically. No tombstone bins needed; no user is mid-flight on the old surface at wave time.
+
+---
+
+# Part 6 — How farmslot calls mm-harness (preflight & the fleet binding)
+
+"Preflight" survives as a **capability, not an exposed concept**: it is what `launch`
+does before returning (readiness: Metro/bundle → app → health/bridge poll), with
+`launch --verify` as the prove-it tier and `doctor` as the read-only view.
+`FARMSLOT_MOBILE_PREFLIGHT_MODE` is an `[ENV-GAP]` row that dies (Part 4).
+
+The fleet is just another agent-grade caller:
+
+- farmslot prepare profiles keep their phases (git / fixtures / deps = farm-level
+  checkout management, NOT harness work); the preflight/health hooks become one
+  call: `mm-harness launch <target> --verify --heal=auto --json`.
+- The farm's `preflight.sh` / `runway-preflight.sh` step-2 logic thins to that call
+  (already Part-3 caller-audit rows; updated in the caller sweep wave). The Runway
+  artifact install remains a farm vehicle invoked before the harness call.
+- **Same-capability guarantee is by construction:** the machine contract (`--json`
+  schemas, `--heal`, exit-code taxonomy, `recovered[]` / `mutations[]` /
+  `recoverable:false`) is the same one agents use — gateway slot-tracking /
+  gate-summary consume structured output instead of scraping bash logs, strictly
+  richer than today.
+- **Three bindings, one verb:** the engineer types `mm-harness launch ios`; the
+  slot's prepare hook calls the same verb with slot context; dispatch scales it
+  across the fleet.
+