@deeeed/metamask-harness 0.2.0

package/docs/architecture.md

@@ -0,0 +1,367 @@
+# MetaMask Recipe Runner Architecture
+
+This repo is the MetaMask-specific adapter layer for Recipe Protocol v1. It is
+not the protocol engine, not a skills repo, not a slot farm, and not product
+code. Its job is to publish reviewable MetaMask capabilities and run them
+against a local Mobile or Extension checkout without committing harness runtime
+into that checkout.
+
+The core model is standalone: install or check out this runner, point it at a
+MetaMask checkout, and run `mm-harness`. Farm/slot orchestration is only a
+way to scale the same loop across many checkouts, machines, ports, and agents;
+it is not required to understand or use the runner.
+
+## TL;DR
+
+The four questions that come up whenever this repo needs explaining.
+
+**Responsibility split.** This runner owns the logic; skills and farms are a
+minimum overlay that call its CLI. Rule of thumb: if a skill's shell script is
+doing more than parsing flags and calling `mm-harness`, that logic
+belongs in this runner instead. Concrete example in flight: the
+`recipe-harness` skill currently locates and execs runner internals in
+hundreds of lines of bash (resolve runner source, dispatch to
+`orchestration/<platform>/{inject,cleanup}.{sh,mjs}` — `.sh` for Mobile/Core,
+`.mjs` for Extension); the fix is a
+[`mm-harness <install|verify|cleanup|live>`](harness-cli.md) command here, so the
+skill thins to a few lines that call it. Same pattern applies to every other
+`recipe-*` skill over time.
+
+**Language policy — bash vs ts vs mjs vs cjs.** Current mix: 65 `.sh`, 62
+`.mjs`, 17 `.ts`, 9 `.cjs` (excluding `node_modules`).
+
+| Extension | Where | Use for | Why |
+|---|---|---|---|
+| `.ts` | `runner/src/**` | CLI parsing, manifests, adapter binding, runtime decisions — typed/testable/shared logic | Compiled and typed; the maintainable core that everything else should grow into |
+| `.mjs` | `library/actions/**`, `orchestration/**`, `scripts/**` | Standalone action adapters and injected runtime helpers | Run-anywhere with zero build step, whether invoked from a published package or a raw checkout |
+| `.cjs` | scattered, quarantined | Compatibility islands: portable `require()` from shell, bridge code for older runtime contexts | Only when the runtime context makes ESM brittle — not a default choice |
+| `.sh` | `bin/`, `orchestration/{mobile,extension,core}/`, `runner/{mobile,extension}/`, `orchestration/lib/` | Thin OS/device glue at the edge: `simctl`, `adb`, Chrome process flags, git-exclude, filesystem setup | Must run before/without Node business logic; never recipe graph execution or MetaMask domain semantics |
+
+The mix is bash-heavy today because sandbox setup crosses OS/device boundaries
+(see "Why there are shell scripts" below) — that is current reality, not the
+target ratio. The direction is less bash over time: when a shell helper starts
+accumulating domain behavior, move it into `.ts` or a focused `.mjs` adapter
+(see [Runtime File Conventions](runtime-file-conventions.md) for the full
+rule).
+
+**Packaging — one package, not several.** This stays one npm package while the
+runtime API is still moving; see [Package Boundaries](package-boundaries.md)
+for the full rationale. Splitting now would force every wrapper (skills,
+farmslot) to pin two coordinated versions before the boundary between "recipe
+execution" and "runtime lifecycle" has stabilized — coordination cost for no
+current benefit. Split when the runtime CLI contract is stable, all wrappers
+call it exclusively (no copied adapter scripts), and the two areas have gone
+several releases without a change that touches both.
+
+## Layer map (front door → engine → schema)
+
+The whole stack is three layers with a strictly one-way dependency. `mm-harness`
+is the MetaMask-facing **front door**; underneath it the runner is a thin
+**adapter layer** over a fat generic **engine** (`@farmslot/recipe-harness`) and
+**schema** (`@farmslot/protocol`). The runner never re-implements engine logic —
+it imports it.
+
+```text
+mm-harness (the one bin — no per-platform binaries)    ← front door: one verb vocabulary
+        │  launch · logs · debug · fixtures (daily loop) · run/flows/doctor/actions/manifest (prove)
+        │  install/verify/cleanup/live (runtime overlay lifecycle)
+        ▼
+metamask-recipe-runner (MetaMask ADAPTER layer)         ← this repo
+        │  MetaMask action manifests, metamask.* live adapters, Mobile/Extension
+        │  runtime overlay install, runtime health/decision probes
+        ▼
+@farmslot/recipe-harness  (GENERIC engine)              ← npm dependency
+        │  recipe graph execution, official ui.* transports, RecordingTarget
+        │  evidence framework, runtime modules, generic run/flows/validate CLI
+        ▼
+@farmslot/protocol        (GENERIC schema)              ← npm dependency
+        │  Recipe v1 schema, action-manifest document, artifact contract
+        ▼
+MetaMask app under test
+        │  local debug runtime only; product source should not own runner logic
+        ▼
+summary.json · trace.json · artifact-manifest.json · screenshots/logs
+```
+
+**Dependency direction is one-way and provable.** The runner *depends on*
+`@farmslot/recipe-harness` + `@farmslot/protocol` (see `package.json`), and
+`runner/src/**` *imports* the generic contracts rather than forking them:
+
+- `runner/src/cli.ts` imports `RecipeRunResult` from `@farmslot/recipe-harness`
+  and delegates library `flows` to the harness CLI (`importRecipeHarnessCli`).
+- `runner/src/runner.ts` wires `metamask.*` adapters INTO the farmslot
+  `RecipeRunner`; it does not implement graph execution.
+- `runner/src/manifest.ts` loads *MetaMask* manifests typed by the *farmslot*
+  protocol document type.
+- `runner/src/recording-target.ts` is a MetaMask provider over the farmslot
+  `RecordingTarget` contract.
+
+**The invariant both repos assert:** farmslot stays MetaMask-free; the runner
+never re-implements engine logic, only binds to it. Decision lens for placing any
+new capability: *would a non-MetaMask project reuse this unchanged?* → yes =
+generic (farmslot); encodes MetaMask app knowledge = runner.
+
+> Note on naming: "harness" refers to the tool (`mm-harness`) and the generic
+> engine package (`@farmslot/recipe-harness`). The per-checkout files the tool
+> installs into a target are the **runtime overlay** (`install`/`verify`/
+> `cleanup`/`live`), never "the harness" — see [harness-cli.md](harness-cli.md).
+
+## One-minute model
+
+```text
+human CLI / optional skill wrapper
+        │ resolve + invoke
+        ▼
+metamask-recipe-runner
+        │ MetaMask action manifests, live adapters, runtime overlay install, runtime probes
+        ▼
+Recipe harness package
+        │ generic graph execution, official ui.* transports, traces, artifacts
+        ▼
+Recipe protocol package
+        │ Recipe v1 schema, manifest contract, artifact contract
+        ▼
+MetaMask app under test
+        │ local debug runtime only; product source should not own runner logic
+        ▼
+summary.json · trace.json · artifact-manifest.json · screenshots/logs
+```
+
+Dependency direction is one-way. Wrappers call the runner; the runner calls the
+shared harness/protocol packages; product apps are only driven at runtime.
+
+## Package shape
+
+This repo remains one npm package for now, but it has two internal areas: recipe execution and runtime lifecycle. See [Package Boundaries](package-boundaries.md) for the stability policy and why we are not splitting packages yet.
+
+## The two subsystems
+
+This repo has two intentionally different kinds of code. Keeping them separate
+is the main way to understand the repository.
+
+| Subsystem | Question it answers | Primary files | Should contain | Should not contain |
+|---|---|---|---|---|
+| Recipe capability/execution | “What can a MetaMask recipe do, and how does a node execute?” | `library/manifests/`, `library/recipes/`, `runner/src/runner.ts`, `runner/src/adapters.ts`, `runner/src/live-adapter-contract.ts`, `library/actions/` | action manifests, domain actions, UI transport binding, adapter outputs, proof semantics | Metro startup, Chrome process flags, simulator boot, git-exclude/rsync cleanup |
+| Runtime lifecycle / sandbox helpers | “How do I give an agent an isolated app session that is ready to inspect or run recipes?” | `bin/mm-recipe`, `bin/mme-recipe`, `orchestration/{mobile,extension,core}/`, `runner/{mobile,extension}/`, `orchestration/lib/` | install/sync harness, start/reuse Metro or Chrome, prewarm bundles, open Extension full-screen or popup-style, prepare dedicated profiles/fixtures, check build/runtime health, cleanup local files | new recipe schema, graph traversal, MetaMask business semantics, task-specific proof logic |
+
+When reviewing a change, first decide which subsystem it touches. Recipe changes
+should be validated against manifests and action artifacts. Runtime lifecycle changes should be validated by install/launch/live/verify
+behavior on a real checkout. Some commands cross the boundary, but they should
+do so by delegating: sandbox helpers get the runtime ready, then
+`mm-harness run` executes the recipe.
+
+## Ownership boundaries
+
+| Layer | Owns | Must not own |
+|---|---|---|
+| Human CLI / optional wrapper | Target selection, runner invocation, evidence handoff | Copied adapter scripts, recipe graph execution, product runtime logic |
+| This runner | MetaMask action manifests, `metamask.*` adapters, Mobile/Extension harness install, runtime health/decision commands | Shared Recipe v1 schema, generic `ui.*` semantics, task-specific acceptance criteria |
+| `Recipe harness package` | Recipe graph execution, standard core/ui adapters, trace/summary/artifact writing | MetaMask wallet/Perps behavior |
+| `Recipe protocol package` | Recipe/manifest/artifact schemas | Runtime control or product-specific actions |
+| Product checkout | App code and debug hooks exposed by the app | Harness scripts, runner copy, skills, private workflow logic |
+
+Rule of thumb: if code describes **what MetaMask can do**, it belongs here. If it
+describes **how Recipe v1 works**, it belongs in the shared protocol/runtime packages. If it
+describes **how an agent should work**, it belongs in skills.
+
+## Key files and directories
+
+| Path | Responsibility |
+|---|---|
+| `bin/metamask-recipe` | Public binary. Dispatches to typed CLI and platform convenience commands. |
+| `bin/mm-recipe` | Mobile convenience/runtime UX: start/reuse Metro, prewarm bundle, launch app, query bridge, setup wallet, screenshot. |
+| `bin/mme-recipe` | Extension convenience/runtime UX: install, health, decision, ready, watch/refresh/reopen, run recipes. |
+| `runner/src/cli.ts` | Typed command handlers: manifests, actions, doctor, runtime health/decision/launch, `run`, self-test. |
+| `runner/src/runner.ts` | Creates the Recipe runner by combining shared core/ui adapters with MetaMask live adapters. Enables the Recipe HUD metadata. |
+| `runner/src/adapters.ts` | MetaMask adapter binding and `ui.*` transport selection for Mobile vs Extension. Refuses static placeholders for live-only proof actions. |
+| `runner/src/live-adapter-contract.ts` | Script adapter contract and lookup rules for `library/actions/<platform>/<domain>/*.mjs`. |
+| `library/manifests/*.action-manifest.json` | Reviewable capability contract. A recipe may only call declared actions. |
+| `library/actions/mobile/` | Mobile action implementations. Talks to the runner bridge and app-exposed `globalThis.__AGENTIC__` hooks. |
+| `library/actions/extension/` | Extension action implementations. Talks to Chrome/extension pages over CDP. |
+| `orchestration/mobile/inject.sh` | Installs/syncs the Mobile runtime overlay under the configured harness root and protects cleanup/git-exclude behavior. |
+| `orchestration/extension/inject.mjs` | Installs/syncs Extension runtime helpers under the configured harness root. |
+| `orchestration/mobile/` + `runner/mobile/` | Runner-owned Mobile launch/live/inject/cleanup and verify helpers copied into installed harnesses. |
+| `orchestration/extension/` + `runner/extension/` | Runner-owned Extension launch/live/watch/windows/wallet-state/readiness helpers (orchestration) and verify (recipe) copied into installed harnesses. |
+| `orchestration/lib/path-defaults.json` | Single source for default `recipeHarnessRoot` and `recipeRuntimeDir`. |
+| `orchestration/lib/harness-path.sh`, `orchestration/lib/recipe-paths.mjs`, `runner/src/paths.ts` | Shell, standalone Node, and TypeScript accessors for those defaults plus validation. |
+| `library/recipes/` | Reusable smoke/action-validation recipes only. Task-specific proof recipes stay task-local. |
+| `library/library.json`, `library/flows/` | Canonical recipe library: minimal, stable flows recipes can `call`. Personal/team libraries shadow it by default — see [Recipe Libraries](recipe-libraries.md). |
+| `docs/` | Runner architecture, contracts, and operational conventions. |
+
+## Runtime paths and installed harnesses
+
+Defaults are centralized in `orchestration/lib/path-defaults.json`:
+
+```json
+{
+  "recipeHarnessRoot": "temp/recipe/harness",
+  "recipeRuntimeDir": "temp/recipe/runtime"
+}
+```
+
+All shell, standalone Node, and TypeScript code must read these through the
+shared helpers instead of hardcoding defaults. Environment overrides are allowed
+through `RECIPE_HARNESS_ROOT` and `RECIPE_RUNTIME_DIR`, but they must stay safe
+relative paths.
+
+Install commands write a small runtime package into the target checkout:
+
+```text
+<target>/<recipeHarnessRoot>/<adapter>/
+  manifest.json              installed source/revision/cleanup metadata
+  action-manifest.json        snapshot of the adapter manifest
+  runner/bin/metamask-recipe  delegate back to the resolved runner source
+  runner/recipes/             reusable recipe snapshot
+  scripts/                    adapter runtime helpers copied from this repo
+```
+
+The installed harness exists so a running slot has stable helper paths even when
+called from skills, orchestration hooks, or a human shell. The source of truth remains
+this runner.
+
+## Recipe execution vs sandbox lifecycle
+
+`mm-harness run <recipe.json> --adapter ...` is the recipe path. It creates
+a shared Recipe runner (`runner/src/runner.ts`), validates the recipe against the
+manifest, executes nodes, and writes artifacts. If a bug is about action fields,
+trace output, adapter semantics, or whether a recipe proves a claim, start in
+`library/manifests/`, `runner/src/`, `library/actions/`, and `library/recipes/`.
+
+`prepare`, `launch`, `live`, `verify`, `status`, `decision`, and `ready` are
+sandbox lifecycle paths. They give the agent a reproducible local app session:
+Mobile with Metro/dev-client/simulator and the bridge online; Extension with an
+isolated browser profile, unpacked extension loaded, and a known home/popup-style
+UI target. If a bug is about Metro, bundle prewarm, simulator launch, Chrome CDP,
+Extension full-screen vs popup presentation, build freshness, wallet fixture
+placement, git-exclude, or cleanup, start in `bin/mm-recipe`, `bin/mme-recipe`,
+`orchestration/{mobile,extension,core}/` and `runner/{mobile,extension}/`.
+
+Do not put recipe graph traversal into shell scripts. Shell scripts may prepare
+or inspect the sandboxed runtime, then delegate graph execution to
+`mm-harness run`.
+
+## HUD vs bridge vs product hooks
+
+These names are easy to mix up; they are different concerns.
+
+| Term | What it is | Why it exists |
+|---|---|---|
+| Recipe HUD | A visual overlay driven by Recipe runner metadata (`intent`, current node, status). | Makes screenshots/videos explain what the recipe is doing without exposing secrets. |
+| Mobile bridge | Runner-side CDP/Hermes bridge process under `library/actions/mobile/bridge-runtime/`. | Lets the runner call app-exposed commands, read state, press UI targets, and capture status from React Native. |
+| `globalThis.__AGENTIC__` | Development-only in-app command surface exposed by the Mobile overlay/patch. | Gives the bridge a stable API for route/status/wallet/UI operations when the app lacks a built-in automation API. |
+| Extension CDP hooks | Chrome DevTools Protocol access to extension pages/background state hooks. | Lets the runner inspect/drive the unpacked Extension without patching product source. |
+
+The HUD does not control the app. The bridge/CDP control the app. The HUD only
+renders proof context.
+
+## Mobile runtime shape
+
+Mobile has the most moving parts because React Native does not expose a browser
+DOM by default.
+
+```text
+mm-recipe / orchestration/mobile/*.sh
+      │ starts/reuses Metro, prewarms bundle, launches iOS/Android dev client
+      ▼
+library/actions/mobile/bridge-runtime/cdp-bridge.cjs
+      │ connects to Hermes / RN debug runtime
+      ▼
+globalThis.__AGENTIC__ inside the app
+      │ route/status/wallet/ui commands + optional HUD rendering
+      ▼
+library/actions/mobile/{wallet,perps,ui,platform}/*.mjs
+```
+
+Ideally the app would expose a product-owned debug automation surface directly,
+so the runner would not need to patch or inject Mobile client files at all. The
+current injection exists as a compatibility bridge: it lets recipes run against
+older Mobile versions, historical PR branches, and eval/replay runs that do not yet include that
+client-side automation surface.
+
+The Mobile injection currently may touch development-only product files on older
+checkouts to install the `AgenticService`, navigation hook, and HUD mount. That
+is the fragile compatibility path, not the desired long-term product contract.
+Those product patches are local runtime state: never commit them to MetaMask
+Mobile. The runner also installs ignored helper files under
+`temp/recipe/harness/mobile`.
+
+Mobile `ensure_*` actions must be idempotent: if the wallet is already unlocked,
+`metamask.wallet.ensure_unlocked` should report success or converge cheaply, not
+fail because the starting state differed.
+
+## Extension runtime shape
+
+Extension does not need an in-product source patch. The runner works through an
+unpacked `dist/chrome` build and Chrome CDP.
+
+```text
+mme-recipe / orchestration/extension/*.sh
+      │ checks dist freshness, build health, fixture/profile state
+      ▼
+Chrome for Testing with --load-extension=<runtime-dist>
+      │ CDP target discovery + deterministic extension id
+      ▼
+library/actions/extension/{wallet,perps,ui,platform}/*.mjs
+      │ extension page/background hooks and UI events
+```
+
+`runtime-launch --start-watch` is the clean-build path. Without `--start-watch`,
+verify can prove the existing runtime is reachable but may fail `dist-freshness`
+if `dist/chrome` does not match `HEAD`. That failure is intentional: it prevents
+silently proving stale product code.
+
+## Why there are shell scripts
+
+The shell scripts are large because sandbox setup crosses OS/device boundaries:
+`simctl`, `adb`, Metro, Watchman, Chrome process flags, isolated browser
+profiles, git exclude files, symlink safety checks, and cleanup all live outside
+Node's typed domain logic. Their purpose is to give an agent a reliable app
+session, not to define recipe semantics.
+
+Allowed in shell:
+
+- parsing CLI flags for lifecycle commands;
+- calling OS/device tools;
+- copying/removing installed harness files;
+- starting/stopping/reusing local dev servers;
+- writing small runtime summaries from command results.
+
+Not allowed in shell:
+
+- Recipe v1 graph execution;
+- MetaMask domain semantics that can live in `runner/src/**/*.ts` or `library/actions/**/*.mjs`;
+- duplicated action manifest logic;
+- product-specific business decisions beyond runtime boot/health checks.
+
+When a shell helper starts accumulating domain behavior, move that behavior into
+TypeScript or a focused `.mjs` adapter and keep shell as the launcher.
+
+## Adding or changing capabilities
+
+1. Add/adjust the shared capability in both Mobile and Extension manifests when
+   the concept exists on both platforms.
+2. Implement durable behavior under `library/actions/<platform>/<domain>/`.
+3. Keep parameterized actions instead of multiplying action names.
+4. Ensure every `ensure_*` action proves a postcondition.
+5. Use official `ui.*` actions and screenshot claims for visible acceptance
+   criteria; do not add task-specific `metamask.*` actions for exact copy,
+   styling, ticket IDs, or one-off selectors.
+6. Update smoke/action-validation recipes only when the capability is reusable.
+
+## Standalone use first; farm later
+
+This runner should make sense without any slot farm:
+
+1. choose a local MetaMask Mobile or Extension checkout;
+2. run `mm-harness launch <platform>` (or `mm-harness install` for the overlay only);
+3. run `mm-harness doctor` (or the advanced `runtime-health`);
+4. run `mm-harness run <recipe.json> --adapter <platform> --artifacts-dir <dir>`.
+
+Skills are optional workflow wrappers around that same CLI. A wrapper may resolve
+the runner source and package evidence, but it should dispatch `install`,
+`launch`, `live`, `verify`, and `cleanup` to this repo or to the installed
+harness helper. It should not carry Mobile or Extension adapter scripts.
+
+Farm/slot orchestration belongs one layer outside this runner. It can scale the
+standalone loop by choosing checkouts, machines, ports, simulators, and agents,
+but it should not change the runner contract or copy runner implementation.

package/docs/extension-runtime-commands.md

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

package/docs/harness-cli.md

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

package/docs/live-adapter-contract.md

@@ -0,0 +1,188 @@
+# Live Adapter Contract
+
+The MetaMask runner implements Recipe Protocol v1 through the shared recipe
+harness package. Project-specific live behavior is supplied by
+manifest-declared action adapters.
+
+Official `ui.*` semantics are implemented by
+`createStandardUiAdapters({ transport })` plus shared CDP/React Native base
+transports. The MetaMask runner supplies only tiny runtime bindings that point
+those base transports at the Extension CDP page or Mobile React Native bridge.
+MetaMask-specific actions remain separate manifest-declared live adapters.
+
+For actions that must prove real product behavior, especially `metamask.perps.*`, static placeholders are refused by default. A live adapter script must exist in one of these locations. Domain-grouped paths are preferred so code ownership stays obvious:
+
+```text
+$METAMASK_RECIPE_LIVE_ADAPTER_DIR/<platform>/<domain>/<action-local-name>.mjs
+$METAMASK_RECIPE_LIVE_ADAPTER_DIR/shared/<domain>/<action-local-name>.mjs
+<runner>/library/actions/<platform>/<domain>/<action-local-name>.mjs
+<runner>/library/actions/shared/<domain>/<action-local-name>.mjs
+```
+
+Legacy external `.js` adapters are still resolved for compatibility, and `.sh` remains available for edge orchestration. New committed adapter code should use grouped `.mjs` modules. Fully-qualified flat filenames are still searched after grouped paths, but new adapter code should use grouped modules. Do not add `ui.*` files here; official UI actions go through shared base transports. Examples:
+
+```text
+library/actions/extension/perps/ensure_positions.mjs
+library/actions/extension/perps/close_positions.mjs
+library/actions/extension/perps/close_orders.mjs
+library/actions/mobile/perps/place_order.mjs
+library/actions/mobile/wallet/ensure_unlocked.mjs
+```
+
+The runner invokes the script with one argument: a JSON input file path. The same path is also available as `METAMASK_RECIPE_ADAPTER_INPUT`. The script must write JSON to `outputPath` from the input document, or print JSON to stdout.
+
+Input shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "platform": "mobile|extension",
+  "action": "metamask.perps.ensure_positions",
+  "node": {},
+  "context": {
+    "nodeId": "ensure-clean",
+    "projectRoot": "/path/to/product",
+    "artifactsDir": "/path/to/artifacts"
+  },
+  "outputPath": "/tmp/.../output.json"
+}
+```
+
+Output shape is action-specific, but must be redacted and suitable for `trace.json`. If the adapter captures evidence files, write them under `context.artifactsDir` and return relative artifact paths for the runner adapter to index in a follow-up implementation.
+
+Proof rule: live adapters must drive real supported app/API paths. They must not write directly into UI state, DOM state, React/Redux/MobX state, local storage, controller internals, or any mid-recipe state that fabricates the proof condition.
+
+## Controller/API calls vs visible UI proof
+
+Recipe authors should choose the layer based on what must be proven:
+
+| Need | Use | Rule |
+|---|---|---|
+| Fast reproducible setup/teardown before or after the proof window | `metamask.*` domain actions such as `start_state`, `ensure_positions`, `close_orders` | May use supported product/controller APIs, but must read/assert the final state. |
+| Read-only state proof | `metamask.*.read_*` or `metamask.*.assert_*` | Must return redacted live state in trace output. |
+| Human-visible acceptance criterion | official `ui.*` actions | Drive the actual visible path: press/tap, input/keypad, scroll into view, screenshot. Do not replace it with a controller call. |
+| Ticket-specific visual detail | task-local recipe assertions/evidence | Do not add a reusable action only for one ticket. |
+
+## Shared action-surface boundaries
+
+The manifest is a durable capability contract, not a place to encode one
+ticket's acceptance criteria. Do not add shared `metamask.*` actions for ticket
+IDs, POCs, exact test IDs, exact copy, styling, placement, or other one-off UI
+proof needs.
+
+Use:
+
+- official `ui.*` actions for reusable presence, input, scroll, and screenshot
+  behavior;
+- screenshot `claims` for visual, copy, and layout proof;
+- task-local composed flows under the task artifact directory when a ticket
+  needs a reusable helper for that ticket only;
+- safe direct CDP/controller calls for read/assert or supported setup paths,
+  never state fabrication.
+
+Add or keep a shared action only when it represents a durable parameterized
+domain capability useful across many tasks, such as `metamask.perps.start_state`,
+`metamask.perps.place_order`, `metamask.perps.close_positions`, or
+`metamask.perps.assert_positions`.
+
+`ui.scroll` is part of the current executable contract and action-validation must
+prove both normal scrolling and `scroll_into_view` before screenshot capture.
+`ui.gesture` is intentionally not advertised yet; drag/swipe proof must wait
+until the shared runtime and this runner expose and validate that action on both
+platforms.
+
+
+
+## Flow catalog follow-up
+
+Action adapters fulfill one manifest-declared operation. Production recipes should also be able to call domain flow catalogs that compose these operations into idempotent `ensure_*` start states. These flows are owned by this runner/domain layer, not by shared runtime packages or wrapper glue.
+
+For Perps, recipes should use the runner-provided `metamask.perps.start_state({ network, provider, page, market, positions, orders })` and `metamask.perps.teardown_state(...)` actions as the default reproducibility boundary. These actions compose primitive bulk operations such as `close_positions({ mode: "all" })` and `close_orders({ mode: "all" })` instead of multiplying one-off cleanup actions.
+
+## Built-in Extension live adapters
+
+The first Extension adapter set is bundled under `library/actions/extension/` and talks directly to the Chrome extension page target over CDP. It does not execute a second recipe graph. The v1 runner still owns workflow traversal; each script only fulfills one manifest-declared action.
+
+Runtime input:
+
+```text
+node.cdp_port | CDP_PORT | RECIPE_CDP_PORT
+```
+
+Optional autolaunch input for existing Extension builds:
+
+```text
+METAMASK_RECIPE_EXTENSION_AUTOLAUNCH=1
+METAMASK_RECIPE_EXTENSION_LAUNCH_EXISTING_DIST=1
+node.launch_existing_dist=true
+```
+
+When enabled, the adapter reuses the requested CDP port if a compatible extension target exists; otherwise it launches Chrome from the target checkout's existing `dist/chrome` without rebuilding the product. The runtime copy, profile, logs, and `runtime.json` are written under `context.artifactsDir/extension-runtime/`.
+
+CLI equivalent:
+
+```bash
+mm-harness run <recipe.json> --adapter extension --cdp-port 6664 --launch-existing-dist --artifacts-dir <dir>
+```
+
+The CLI maps `--cdp-port` to `CDP_PORT`/`RECIPE_CDP_PORT` and maps `--launch-existing-dist` to `METAMASK_RECIPE_EXTENSION_AUTOLAUNCH=1` for the duration of the recipe run.
+
+Currently implemented Extension actions:
+
+```text
+ui.navigate                  # extension: page alias or hash/path/url
+metamask.perps.read_positions
+metamask.perps.read_orders
+metamask.perps.close_positions # primitive bulk close selected positions
+metamask.perps.close_orders    # primitive bulk cancel selected orders
+metamask.perps.place_order
+metamask.perps.assert_positions
+metamask.perps.assert_orders
+metamask.perps.ensure_positions # high-level read/close/place/assert wrapper
+metamask.perps.ensure_orders    # high-level read/cancel/assert wrapper
+ui.press
+ui.scroll
+ui.wait_for
+ui.screenshot
+```
+
+Navigation supports a small discoverable `page` alias set (`home`, `perps`, `perps-market`) plus raw extension hash/url fallback. Check the action manifest before hardcoding routes.
+
+Task-specific UI styling checks, such as one ticket proving a banner color or placement, must not be implemented as reusable `metamask.perps.*` actions. Use official `ui.wait_for` for reusable presence/absence checks plus screenshot/task-local validation evidence for that ticket.
+
+Read-only position checks use `stateHooks.submitRequestToBackground('perpsGetPositions', [{ skipCache: true }])`. State-changing actions prefer UI interaction through CDP mouse/keyboard events. Bulk cleanup primitives may call product background APIs such as `perpsClosePositions` or `perpsCancelOrders` when the UI control is unavailable; this is a supported app/API path, not direct state mutation. Adapters must not mutate Redux/React state, DOM state, local storage, or controller internals to fabricate proof.
+
+## Built-in Mobile live adapters
+
+The Mobile adapter is bundled under `library/actions/mobile/`. Its CDP bridge, wallet setup, target discovery, and screenshot helpers run from the runner runtime; the Mobile checkout must not own harness control scripts. The app still needs a development-only in-app bridge/HUD overlay when a historical checkout does not expose the required `globalThis.__AGENTIC__` hooks.
+
+Runtime input:
+
+```text
+node.watcher_port | node.metro_port | node.cdp_port | WATCHER_PORT | CDP_PORT | RECIPE_CDP_PORT
+node.simulator | node.ios_simulator | IOS_SIMULATOR
+node.android_device | ANDROID_DEVICE
+```
+
+Currently implemented Mobile actions:
+
+```text
+ui.navigate                  # mobile: page alias or route/screen + params
+metamask.perps.read_positions
+metamask.perps.read_orders
+metamask.perps.close_positions # primitive bulk close selected positions
+metamask.perps.close_orders    # primitive bulk cancel selected orders
+metamask.perps.place_order
+metamask.perps.assert_positions
+metamask.perps.assert_orders
+metamask.perps.ensure_positions # high-level read/close/place/assert wrapper
+metamask.perps.ensure_orders    # high-level read/cancel/assert wrapper
+ui.press
+ui.scroll
+ui.wait_for
+ui.screenshot
+```
+
+Navigation supports a small discoverable `page` alias set (`home`, `perps`, `perps-market`) plus raw React Navigation route/params fallback. Check the action manifest before hardcoding routes.
+
+Read-only position checks use `Engine.context.PerpsController.getPositions()` through Hermes CDP. State-changing Perps actions use supported controller APIs (`placeOrder`, `closePositions`) through the same app bridge rather than mutating Redux/React/local storage. UI actions delegate to existing bridge capabilities such as `press-test-id` and `scroll-view`. Screenshot capture uses `xcrun simctl io <simulator> screenshot` for iOS simulator proof.