@deeeed/metamask-harness 0.17.0 → 0.17.2

package/docs/CLI-SPEC.md

@@ -1,1142 +0,0 @@
-# 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.
-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 |
-| `check diff` | Run bounded repo-local validation for the active git diff | 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 `src/commands/launch/`. 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. `init --from` copies an existing secure team/test fixture; explicit `init --dev` creates a disposable public test wallet that must never hold real funds. **Fixture status is reported by `doctor` automatically.**
-
-**Synopsis:** `mm-harness fixtures <init|sync|set|generate|finalize> [flags]` — subcommand required.
-
-| Subcommand | Behavior |
-|---|---|
-| `init` | Create the canonical fixture from `--from <path>` or explicit `--dev`; refuse replacement unless `--force` is supplied |
-| `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 Mobile/Extension; Core validates and reads the same fixture directly for signing |
-| `generate` | Render the extension `fixture-state.json` from a wallet fixture for pre-launch profile prefill (fronts `adapters/extension/wallet-fixture-state.cjs generate`). **Extension-only** (mobile/core teach). Requires `--fixture <wallet-fixture.json>` and `--out <fixture-state.json>`. This is the public surface for farm packs that need the pre-launch fixture-state file, replacing direct reach-in to the internal leaf. |
-| `finalize` | Seed account labels/selection into the **live** extension over CDP and validate import parity (fronts `adapters/extension/wallet-fixture-state.cjs seed-cdp`). **Extension-only, post-launch** (mobile/core teach). Requires `--fixture`, `--state`, `--cdp-port`, `--extension-dir`. This is the public surface for farm packs that finalize account labels after launch, replacing the last direct reach-in to the internal leaf. |
-
-| Flag | Type | Default | ENV (agent) | Audience | Description |
-|---|---|---|---|---|---|
-| `--from <json>` | path | — | — | both | `init`: copy an existing fixture without exposing its values in arguments |
-| `--dev` | bool | false | — | both | `init`: create a disposable public test wallet; never real funds |
-| `--force` | bool | false | — | both | `init`: intentionally replace the canonical fixture |
-| `--fixture <json>` | path | slot's `wallet-fixture.json` (`set`/`sync`); **required** for `generate`/`finalize` (input wallet fixture) | `RECIPE_WALLET_FIXTURE` | **agent** (`set`/`sync`); both (`generate`/`finalize`) | `set`/`sync`: override fixture path (human form = edit the canonical file directly). `generate`/`finalize`: the input wallet fixture. |
-| `--out <json>` | path | `generate`: **required**; `finalize`: leaf default report path | — | both | `generate`: output `fixture-state.json`. `finalize`: optional validation report path. |
-| `--state <json>` | path | — (**required** for `finalize`) | — | both | `finalize` only: the pre-launch `fixture-state.json` to seed into the live wallet |
-| `--cdp-port <port>` | number | — (**required** for `finalize`) | — | both | `finalize` only: CDP port of the running extension |
-| `--extension-dir <path>` | path | — (**required** for `finalize`) | — | both | `finalize` only: the loaded extension dist (e.g. `dist/chrome`) |
-| `--extension-id-file <path>` | path | — | — | agent | `finalize` only: file to read/write the resolved extension id |
-| `--platform <p>` | mobile\|extension | auto | `PLATFORM` | agent | Force platform |
-
-**Exit:** 0 · 1 apply/generate/finalize failed · 2 bad args (incl. missing required flags, or `generate`/`finalize` on a non-extension adapter).
-**`set` teaching output:** always ends with: `Wallet fixture applied.  Want different accounts? Edit: <absolute-path>/wallet-fixture.json`.
-**`generate` --json:** `{ schemaVersion, command:"fixtures", action:"generate", adapter:"extension", fixture, out, status, exitCode, error }` — leaf output stays on stderr; stdout carries only the envelope.
-**`finalize` --json:** `{ schemaVersion, command:"fixtures", action:"finalize", adapter:"extension", fixture, state, cdpPort, extensionDir, out, status, exitCode, error }` — leaf progress streams to stderr; stdout carries only the envelope. A missing packed leaf yields `error.code:"LEAF_MISSING"` (exit 1), matching `generate`.
-**Maps-to:** `sync` ← C:`sync`, D:`sync`,`update\|sync-runtime`; `set` ← C:`setup-wallet\|wallet-setup`,`unlock`,`setup:ios/android`(wallet half); `generate` ← Extension farm `setup/generate-fixture.cjs` (retires the pack's internal-leaf resolver); `finalize` ← Extension farm `setup/preflight.sh` seed-cdp finalization (retires the pack's last `--resolve-script` reach-in).
-**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).
-
-
-## `provision` (REAL → thin mobile setup path)
-
-**Synopsis:** `mm-harness provision [runway ios] [flags]`
-
-Installs the cached Runway iOS dev client onto a prepared mobile slot. It does not install JavaScript dependencies or start Metro; launch owns those at dispatch time. The legacy `install --runway` compatibility path maps to the same adapter surface; new farm callers should use `provision`.
-
-| Flag | Type | Default | ENV (agent) | Audience | Description |
-|---|---|---|---|---|---|
-| `--adapter <mobile\|extension\|core>` | adapter | auto | — | agent | Mobile installs Runway; extension/core teach |
-| `--target <path>` | path | cwd | — | agent | Slot checkout |
-| `--platform <ios>` | string | `ios` | `PLATFORM` | agent | Provisioned platform |
-| `--simulator <name\|udid>` / `--device <name\|udid>` | string | runtime context | `IOS_SIMULATOR` | agent | Target simulator |
-| `--runtime <id>` | string | runtime context | `IOS_RUNTIME` | agent | iOS runtime for simulator creation |
-| `--device-type <id>` | string | runtime context | `IOS_DEVICE_TYPE` | agent | Device type for simulator creation |
-| `--branch <ref>` / `--default-branch <ref>` / `--run <id>` | string | git branch / main | — | agent | Runway artifact selection |
-| `--cache-root <dir>` | path | XDG cache | — | agent | Shared artifact cache |
-| `--slot <id>` | string | runtime context | — | agent | Farm slot id recorded in the provision baseline |
-| `--watcher-port <port>` | number | runtime context | `WATCHER_PORT`/`METRO_PORT` | agent | Metro/watcher port carried through context and rerun hints |
-| `--runtime-dir <dir>` | relative path | `temp/recipe/runtime` | `RECIPE_RUNTIME_DIR` | agent | Runtime directory containing `agentic-runtime.json` and receiving `runway-provision.json` |
-| `--force` | bool | false | — | agent | Reinstall even when the bundle is already present |
-| `--resolve-only` | bool | false | — | agent | Resolve run/revision/artifact metadata only; no simulator creation, cache write, download, install, or baseline write |
-| `--json` | bool | false | — | agent | Machine envelope on stdout; progress/errors on stderr |
-
-## `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.
-
-**Run-scoped diagnostics:** Mobile combines its bounded in-app issue buffer with application-log bytes appended while the recipe executes; Extension owns a CDP console subscription for the run. The bounded, redacted result is written to `diagnostics.json`, indexed as a diagnostic artifact, and summarized as non-blocking `sideFindings`; it never changes recipe pass/fail and does not claim causality. Core is headless, so this is N/A.
-
-> **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`).
-
-**Execution phases:** `resolve → validate → install → healthcheck → execute`, with `recover` emitted only when bounded recovery actually runs. `--json-stream` emits each transition as it occurs.
-
-**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).
-
-## `last` (resumability inspect verb)
-
-**Synopsis:** `mm-harness last [--target <checkout>] [--runtime-dir <dir>] [--json]`
-
-Reads `last-command.json`, the atomic per-checkout journal written before and after significant runtime/proof commands. The record contains redacted args, `running|pass|fail` verdict, exit code, explicit evidence/output paths, and start/finish timestamps. A process killed between writes remains `running`, allowing an agent to inspect rather than repeat side effects. Read-only discovery commands do not replace the record, and `last` never journals itself.
-
-The file is mode `0600`; password, credential, auth, mnemonic, private-key, seed/SRP, secret, and token values are redacted before the first write. `--json` returns `{ command:"last", target, journalPath, status, exitCode, last }`. Missing or invalid state returns `LAST_NOT_FOUND` with an exact `userAction`.
-
-## `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` | `doctor --fix` creates local identity; Farmslot may override |
-| `extensionId` | `RECIPE_HARNESS_EXTENSION_ID` | — | resolved from the built extension |
-| `cdpPort` | `RECIPE_CDP_PORT` / `CDP_PORT` | `--cdp-port` | `doctor --fix` claims one; flag overrides |
-| `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": "doctor --fix creates local identity; Farmslot may override" },
-      "extensionId": { "value": "abc123", "source": "file", "envVar": "RECIPE_HARNESS_EXTENSION_ID", "customize": "resolved from the built extension" },
-      "cdpPort":  { "value": "6663", "source": "file", "envVar": "CDP_PORT", "customize": "doctor --fix claims one; --cdp-port overrides" },
-      "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 | Repair overlay/runtime context and require a usable canonical fixture without launching. Exit 0 = sandbox prerequisites ready; 1 = partial/failed. JSON adds `fixed`, `failed`, and numbered `nextActions`. |
-| `--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.
-
----
-
-## `check diff` (REAL → bounded local validation)
-
-**Synopsis:** `mm-harness check diff [flags]`
-
-Runs bounded validation against the target checkout's active git diff. This is
-for local PR readiness loops and agent templates; it does not launch an app or
-run a recipe.
-
-| Flag | Values | Default | Purpose |
-| --- | --- | --- | --- |
-| `--target <repo>` | path | cwd | MetaMask checkout to inspect |
-| `--adapter <adapter>` / `--platform <adapter>` | mobile\|extension\|core | auto-detect | Adapter label for the report |
-| `--base <ref>` | git ref | GitHub PR base, then remote HEAD, then `origin/develop`/`origin/main`/local fallback | Diff base |
-| `--profile <profile>` | `fast`\|`full` | `fast` | `fast` runs changed-file ESLint/Prettier/Jest; `full` also runs repo typecheck when available |
-| `--artifacts-dir <dir>` | path | `temp/recipe/check-diff/<timestamp>` | Writes summary and per-check logs |
-| `--json` | bool | false | Print the summary envelope to stdout |
-
-**Artifacts:** `validation-summary.json`, `validation-summary.md`, and one log
-per executed check.
-
-**Exit:** 0 pass · 2 bad args / not a git checkout · 5 validation failure.
-
----
-
-## `--device <id>` — first-class mobile device targeting (REAL)
-
-`--device` is the uniform mobile device selector on `run`, `call`, `doctor`, and `fixtures`. Pass the **adb serial** for Android (from `adb devices`) or the **UDID / simulator name** for iOS. The harness resolves the adb serial to the Metro CDP target identity internally — users never need to know or set `ANDROID_DEVICE='Pixel 6 - 16 - API 36'`.
-
-**Internal Android identity mapping**: `ADB_SERIAL` / `ANDROID_SERIAL` carry the raw adb serial. The bridge resolves the device model via `adb -s <serial> shell getprop ro.product.model` and propagates it as `ANDROID_TARGET_DEVICE_NAME`. Target-discovery uses `ANDROID_TARGET_DEVICE_NAME` for Metro `deviceName` prefix matching (e.g. `"Pixel 6"` matches `"Pixel 6 - 16 - API 36"`). When the pinned model cannot be matched to any Metro `/json/list` candidate and multiple candidates exist, the bridge fails fast with a diagnostic listing every candidate's `deviceName` — it never silently selects the wrong device. iOS UDID/simulator name → `IOS_SIMULATOR` (unchanged).
-
-| Verb | `--device` given | `--device` omitted (mobile) |
-|---|---|---|
-| `run` / `call` | resolve id → set serial/simulator env; proceed | **ambiguity gate:** >1 connected mobile device (across both android and ios, counting only targetable ones: android state `device`, iOS state `Booted`) → fail fast (exit 2), listing connected devices and `--device <id>` hints. Exactly one targetable (or zero — existing engine errors speak) → unchanged behavior. |
-| `doctor` | resolve id → set env | no gate — doctor is diagnostic and **reports** the device list (`devices[]`) instead. |
-| `fixtures` | resolve id → set serial/simulator env before sync/set and recovery relaunch | no gate — preserves existing single-device and ambient slot behavior. |
-
-`--device` on the **extension/core** adapter is a teaching usage error (those adapters have no device to target). `run --plan` is static (touches no device) and is exempt from the gate.
-
-## `status` (aliases `health`, `home`) — home dashboard + devices[] (REAL)
-
-`status` is the compact home dashboard for a checkout: the detected adapter, the next command to run (`next`), and — for **mobile** checkouts — a `devices[]` section with live app state. Extension/core checkouts report an empty `devices[]`. Additive envelope:
-
-```json
-{
-  "schemaVersion": 1,
-  "command": "status",
-  "adapter": "mobile",
-  "target": "/path/to/checkout",
-  "devices": [
-    {
-      "platform": "android", "id": "emulator-5554", "name": "Pixel_6",
-      "state": "device", "selected": true,
-      "currentScreen": "Wallet", "walletState": "unlocked",
-      "selectedAccount": { "label": "Account 1", "address": "0xabcd…ef12" },
-      "fixtureStatus": "READY"
-    },
-    {
-      "platform": "ios", "id": "AAAA-BBBB", "name": "iPhone 15",
-      "state": "Booted", "selected": false,
-      "fixtureStatus": "READY", "liveState": "no-bridge"
-    }
-  ],
-  "next": "mm-harness launch ios"
-}
-```
-
-**Per-device live fields** (additive — absent or null when unreachable):
-
-| Field | Type | Description |
-|---|---|---|
-| `currentScreen` | string | Active route/screen in the running app (mobile bridge `status` route field) |
-| `walletState` | `'locked'\|'unlocked'\|'onboarding'` | Derived from bridge status: account present → unlocked; onboarding route → onboarding; else locked |
-| `selectedAccount` | `{ label, address }` | Active account name + address truncated to `0x1234…abcd` form |
-| `fixtureStatus` | `'READY'\|'missing'` | Checkout-level: whether `wallet-fixture.json` is present and well-formed |
-| `liveState` | `'no-bridge'\|'bridge-absent'` | Set when the bridge is unreachable/times out (`no-bridge`) or the target answers but `__AGENTIC__` is absent (`bridge-absent`); live fields omitted in both cases |
-
-**`--fast` flag:** skips all live-state probes. Output is instant (same envelope shape, live fields absent). Safe for scripts and CI where probe latency is unacceptable.
-
-**Human output** is progressive: static info (adapter, device list, next) prints immediately; a `live:` block appends after the ~2s probe window closes. `--fast` suppresses the live block entirely.
-
-`selected` is `true` when the device id matches `ADB_SERIAL`/`ANDROID_SERIAL` (android) or `IOS_SIMULATOR` (ios) env. `doctor --json` carries the same `devices[]` shape (with `selected`) for mobile checkouts.
-
-The mobile bridge probes all connected RN targets in one call and returns an array; each device is matched to its entry by name or platform-uniqueness, so multi-device checkouts (e.g. Android + iOS simulator) receive per-device live state.
-
-`liveState` in the JSON envelope (absent = fully enriched):
-
-| Value | Meaning |
-|---|---|
-| `'no-bridge'` | No matching/responding target on Metro — bridge genuinely unreachable or app not running. |
-| `'bridge-absent'` | Target IS reachable and answered Runtime.evaluate, but `typeof globalThis.__AGENTIC__ === 'undefined'` — the installed build predates the bridge. Reinstall a dev build to get live state. |
-
-Extension/core live-state probing (CDP home-tab route) is V1-pending — use `doctor` for runtime status.
-
-**Exit:** 0 (2 when the repo type cannot be detected).
-
----
-
-## 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 [query] --adapter <p> [--json] [--categories | --category <name> | --action <name>]`
-
-**PRIMARY (agent):** search from the task vocabulary, for example `mm-harness actions positions --adapter mobile --json`, then request one full `--action` schema. Use `--categories` only when the task does not provide a useful search term.
-
-**`--json` output shape** (grounded — `actions --adapter core --json` confirmed):
-```json
-{
-  "adapter": "core",
-  "actions": [
-    {
-      "name": "metamask.perps.read_positions",
-      "kind": "custom",
-      "category": "perps",
-      "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). `category` uses manifest metadata when present, then stable generic groups for protocol primitives and durable action namespaces (`ui.*` → `ui`, `metamask.perps.*` → `perps`). `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 |
-| `--categories` | bool | false | — | agent | Return only sorted category names and action counts |
-| `--category <name>` | string | all | — | agent | Return actions from one namespace-derived category |
-| `--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 |
-
-The optional positional `query` searches names, categories, fields, and descriptions with typo tolerance. A single `--action` detail also returns up to five compact `relatedActions` names. Flow discovery remains separate.
-**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; parses JSON scalars/arrays/objects. Wrap a numeric-looking string as a JSON string, e.g. `--arg 'test_id="12345"'`. |
-| `--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).
-
-**Core-runner install — the public surface for farm packs.** `mm-harness install
---adapter core --target <repo>` is the pack-facing way to install the headless
-core runner into a slot: it fronts `adapters/core/inject.sh` (the same leaf a farm
-pack used to clone-and-run itself) and produces the runner delegate at
-`<harness>/core/runner/bin/mm-harness`. Because the inject leaf ships inside the
-published package, packs no longer clone a runner checkout — they call this command
-and inherit `RECIPE_HARNESS_ROOT` / `FARMSLOT_ROOT` through the environment. There
-is no separate top-level `install-core` command; `--adapter core` on the existing
-`install` is the surface (grounded: `tests/contract/core-install-cli.test.sh`).
-
-## 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); `provision --device` is an alias for `--simulator`
-- `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) · `provision --slot --runtime-dir --watcher-port` accepts farm slot context · `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 |
-
-Successful lifecycle transitions may add a top-level `next` command when exactly
-one follow-up is correct (for example install → verify or stop → relaunch).
-Discovery, read-only, and terminal evidence commands intentionally omit it rather
-than inventing guidance. Agents must therefore treat `next` as optional.
-
-Public command-grammar failures happen before runtime dispatch and always exit 2.
-Their machine envelope is deliberately smaller and stable: agents branch on
-`error.code`, never on prose.
-
-```json
-{
-  "schemaVersion": 1,
-  "command": "actions",
-  "status": "fail",
-  "error": {
-    "code": "CLI_UNKNOWN_OPTION",
-    "message": "unknown option '--categoriez'. Valid options for mm-harness actions: ...",
-    "userAction": "Did you mean '--categories' instead of '--categoriez'? Try: mm-harness actions --adapter mobile"
-  },
-  "exitCode": 2
-}
-```
-
-Stable grammar codes are `CLI_UNKNOWN_COMMAND`, `CLI_UNKNOWN_OPTION`,
-`CLI_MISSING_OPTION_VALUE`, `CLI_INVALID_OPTION_VALUE`,
-`CLI_MISSING_POSITIONAL`, `CLI_INVALID_POSITIONAL`,
-`CLI_EXCESS_POSITIONAL`, and `CLI_UNEXPECTED_PASSTHROUGH`. Every public
-command is tracked in `docs/CLI-ERGONOMICS-AUDIT.md`; private adapter leaves keep
-their own grammar behind explicit `--` passthrough.
-
-## §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
-
-Summary `--json` responses retain their command-specific `phase` field. `--json-stream` emits transitions as they occur, so an agent can distinguish active work from a stalled command.
-
-**`run` phases:**
-```
-resolve → validate → install → healthcheck → execute
-```
-
-**`launch` phases:**
-```
-resolve → install → healthcheck → launch → verify
-```
-
-`recover` is conditional and appears immediately before a bounded recovery attempt; `verify` appears only for `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`)
-
-`run` and `launch` accept `--json-stream`. Each progress event is written as one complete JSON object plus a newline, so a piped reader can parse it before the command finishes. Schema is versioned via `schemaVersion`; every event also carries `command` and `ts`.
-
-Stream mode owns stdout: existing human or subprocess output is routed to stderr. If both `--json` and `--json-stream` are supplied, stream mode wins. The existing summary `--json` bytes are unchanged when stream mode is absent.
-
-```jsonl
-{"schemaVersion":1,"command":"run","event":"phase","phase":"resolve","ts":"2026-07-02T10:00:00.000Z"}
-{"schemaVersion":1,"command":"run","event":"phase","phase":"validate","ts":"2026-07-02T10:00:00.100Z"}
-{"schemaVersion":1,"command":"run","event":"phase","phase":"execute","ts":"..."}
-{"schemaVersion":1,"command":"run","event":"node","nodeId":"unlock","action":"metamask.wallet.unlock","status":"running","ts":"..."}
-{"schemaVersion":1,"command":"run","event":"node","nodeId":"unlock","action":"metamask.wallet.unlock","status":"passed","ts":"..."}
-{"schemaVersion":1,"command":"run","event":"complete","status":"pass","exitCode":0,"reportPath":"/.../report.md","artifactManifestPath":"/.../artifact-manifest.json","recovered":[],"mutations":[],"ts":"..."}
-```
-
-Event types: `phase` · `node` · `mutation` · `recovery` · `error` · `complete`. Node events use stable recipe `nodeId` values rather than an inferred numeric order. Exactly one terminal `complete` event is last on normal success or handled failure, giving agents a clean sentinel and compact evidence paths without repeating the full run result.
-
-## §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.
-
-## Appendix — Extension runtime lifecycle (internal notes)
-
-Internal implementation notes for the 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 `launch --verify` and by
-the readiness commands (`doctor --fix`, `verify`). 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, composed in order (each idempotent, each reporting the
-cheapest next action so the path converges rather than rebuilding from scratch):
-
-- **Extension-id resolution** — resolves the deterministic unpacked extension id
-  from `dist/chrome/manifest.json`, optionally verified against a live CDP target.
-  Runs first; every later stage keys off this id.
-- **Readiness decision** — inspects the checkout + live browser and returns the
-  cheapest next action (`install`, `build`, `relaunch`, or `ready`) plus the
-  concrete `actions[]` to execute.
-- **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 webpack cache,
-  start the harness-owned watcher, wait for a clean compile, then launch + 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.
-- **Health probe** — read-only liveness probe for the running extension over CDP;
-  the final gate of convergence and the standalone answer for `verify`.