@deeeed/metamask-harness 0.17.0 → 0.17.2

package/docs/architecture.md

@@ -1,398 +1,88 @@
-# MetaMask Recipe Runner Architecture
+# Architecture
 
-**Control flows DOWN only — a DAG, never a loop.**
-
-```
-  bin/mm-harness          ← entry (thin bootstrap)
-        │
-        ▼
-  ┌───────────────────────────────────────────────┐
-  │  src/   THE BRAIN — all TypeScript             │
-  │  CLI · decisions · state machines · run        │
-  │  engine · healing/errors · evidence            │
-  └───────────────────────────────────────────────┘
-        │ spawns                    │ reads
-        ▼                           ▼
-  adapters/<platform>/        library/
-  DEVICE LEAVES (shell)       VOCABULARY (data)
-  one op · args in ·          recipes · actions ·
-  result out · exit           flows — pure JSON/mjs
-  (yarn-setup, start-metro,
-   open-device, xcrun, adb,
-   webpack, chrome)
-```
-
-| dir | is | rule |
-|---|---|---|
-| `bin/` | entry | one thin bootstrap |
-| `src/` | the brain | ALL TypeScript, ALL decisions/sequencing |
-| `adapters/<platform>/` | device leaves | one op each · never orchestrates · **never calls `mm-harness`** |
-| `library/` | vocabulary | pure recipe/action/flow data |
-
-**The one rule everything follows:** nothing under `adapters/` or `library/` ever calls `mm-harness`. TS orchestrates and spawns leaves; leaves do one device op and exit; vocabulary is data. (External callers — farm hooks, skills, overlay delegate — invoking `mm-harness` at the top level is fine; the ban is on the harness's OWN scripts calling back in.)
-
-**Why:** every past mess (half-wired porcelain, commands referenced-but-unbuilt, stub tests faking the thing under test) came from control looping back up. Down-only makes that class of bug unrepresentable — and means less code.
-
----
-
-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
-`adapters/<platform>/{inject,cleanup}.{sh,mjs}` — `.sh` for Mobile/Core,
-`.mjs` for Extension); the fix is a
-[`mm-harness <install|verify|cleanup|live>`](CLI-SPEC.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` | `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/**`, `adapters/**`, `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/`, `adapters/{mobile,extension,core}/`, `adapters/shared/` | 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
-`src/**` *imports* the generic contracts rather than forking them:
-
-- `src/cli.ts` imports `RecipeRunResult` from `@farmslot/recipe-harness`
-  and delegates library `flows` to the harness CLI (`importRecipeHarnessCli`).
-- `src/runner.ts` wires `metamask.*` adapters INTO the farmslot
-  `RecipeRunner`; it does not implement graph execution.
-- `src/manifest.ts` loads *MetaMask* manifests typed by the *farmslot*
-  protocol document type.
-- `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 [CLI-SPEC.md](CLI-SPEC.md).
-
-## One-minute model
+`mm-harness` is the MetaMask adapter and CLI over the generic Recipe Protocol
+engine. Control flows downward only:
 
 ```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
+bin/mm-harness
+  → src/                         typed CLI, decisions, orchestration, evidence
+    → @farmslot/recipe-harness  generic graph execution and transports
+    → @farmslot/protocol        recipe, manifest, trace, artifact schemas
+    → adapters/                 focused OS, browser, simulator, and device leaves
+    → library/                  MetaMask actions, flows, recipes, manifests
+      → MetaMask checkout       app under test
 ```
 
-Dependency direction is one-way. Wrappers call the runner; the runner calls the
-shared harness/protocol packages; product apps are only driven at runtime.
+Nothing under `adapters/` or `library/` calls back into `mm-harness`. TypeScript
+owns sequencing; a leaf performs one platform operation and exits; the library
+defines composable behavior.
 
-## Package shape
+## Ownership
 
-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/`, `src/runner.ts`, `src/adapters.ts`, `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?” | `adapters/porcelain/`, `adapters/{mobile,extension,core}/`, `adapters/shared/` | 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 |
+| Layer | Owns | Does 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 |
+| `@farmslot/protocol` | Recipe and evidence schemas | execution or product behavior |
+| `@farmslot/recipe-harness` | graph execution, generic `ui.*`, traces and artifacts | MetaMask behavior |
+| this package | MetaMask actions, runtime control, CLI, diagnostics | task acceptance criteria or copied engine logic |
+| skills/checklists | task workflow and proof expectations | runtime or runner implementation |
+| product checkout | application and explicit debug hooks | harness scripts or 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.
+A capability reusable without MetaMask belongs in the generic engine. A durable
+MetaMask operation belongs here. Ticket-specific assertions stay in the task's
+recipe or checklist.
 
-## Key files and directories
+## Repository layout
 
 | Path | Responsibility |
 |---|---|
-| `src/cli.ts` | Typed command handlers: manifests, actions, doctor, runtime health/decision/launch, `run`. |
-| `src/runner.ts` | Creates the Recipe runner by combining shared core/ui adapters with MetaMask live adapters. Enables the Recipe HUD metadata. |
-| `src/adapters.ts` | MetaMask adapter binding and `ui.*` transport selection for Mobile vs Extension. Refuses static placeholders for live-only proof actions. |
-| `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. |
-| `adapters/mobile/inject.sh` | Installs/syncs the Mobile runtime overlay under the configured harness root and protects cleanup/git-exclude behavior. |
-| `adapters/extension/inject.mjs` | Installs/syncs Extension runtime helpers under the configured harness root. |
-| `adapters/mobile/` | Runner-owned Mobile launch/live/inject/cleanup and verify helpers copied into installed harnesses. |
-| `adapters/extension/` | Runner-owned Extension launch/live/watch/windows/wallet-state/readiness helpers (orchestration) and verify (recipe) copied into installed harnesses. |
-| `adapters/shared/path-defaults.json` | Single source for default `recipeHarnessRoot` and `recipeRuntimeDir`. |
-| `adapters/shared/harness-path.sh`, `src/paths.ts` | Shell and TypeScript accessors for those defaults plus validation. |
-| `library/recipes/` | Reusable smoke/runner.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 `adapters/shared/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:
+| `bin/mm-harness` | one public executable |
+| `src/commands/` | public command behavior |
+| `src/adapters/` | typed product decisions and orchestration |
+| `adapters/<platform>/` | focused shell/Node runtime leaves |
+| `adapters/shared/` | cross-platform OS glue |
+| `adapters/*/overlay/` | the only files installed or patched into a checkout |
+| `library/actions/` | executable MetaMask action adapters |
+| `library/flows/` | reusable parameterized behavior |
+| `library/recipes/` | reusable proof recipes |
+| `library/manifests/` | declared capability surface |
+| `scripts/` | repository development checks only |
+
+All TypeScript belongs under `src/`. New standalone runtime helpers use ESM
+unless their host runtime requires CommonJS. Shell remains limited to operations
+that genuinely need shell/device tools.
+
+## Runtime isolation
+
+Each checkout owns its runtime state:
 
 ```text
-<target>/<recipeHarnessRoot>/<adapter>/
-  manifest.json              installed source/revision/cleanup metadata
-  action-manifest.json        snapshot of the adapter manifest
-  runner/bin/mm-harness       delegate back to the resolved runner source
-  runner/recipes/             reusable recipe snapshot
-  scripts/                    adapter runtime helpers copied from this repo
+temp/recipe/runtime/   ports, processes, fixture, logs, runtime identity
+temp/recipe/harness/   installed runtime overlay
 ```
 
-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 (`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/`, `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 `adapters/{mobile,extension,core}/`.
-
-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 `adapters/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-harness launch ios|android
-      │ prepareMobile() in-process → yarn-setup / start-metro / open-device leaves
-      ▼
-adapters/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 / adapters/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 `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
+Defaults live in `adapters/shared/path-defaults.json`. Every browser profile,
+simulator/device selection, port, watcher, and evidence directory must resolve
+from the current checkout so parallel slots do not share state.
 
-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/runner.action-validation recipes only when the capability is reusable.
+Extension uses an isolated Chrome profile and CDP port. Its normal watcher builds
+to product `dist/chrome`, then synchronizes successful output into the isolated
+runtime extension. Mobile owns an isolated Metro/device identity. Core remains
+headless.
 
-## Standalone use first; farm later
+## Proof boundary
 
-This runner should make sense without any slot farm:
+`launch` prepares the runtime. `run` validates and executes a recipe through the
+generic engine. Runtime setup may seed declared fixtures before proof begins;
+proof actions must not mutate hidden product state to fabricate a result.
 
-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>`.
+Each run produces a summary, trace, diagnostics where applicable, and an artifact
+manifest. Application warnings/errors are side findings unless a recipe assertion
+turns them into a proof failure.
 
-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.
+## Change checks
 
-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.
+- Put the change in the owning layer; do not duplicate behavior in a skill or leaf.
+- Keep actions parameterized and manifests honest.
+- Validate the machine contract and the visible human outcome.
+- Exercise affected platforms on real checkouts when runtime behavior changes.
+- Run `yarn check` and update `CHANGELOG.md` for user-visible changes.

package/docs/live-adapter-contract.md

@@ -19,7 +19,9 @@ $METAMASK_RECIPE_LIVE_ADAPTER_DIR/shared/<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:
+Action adapters are grouped `.mjs` modules. Flat files, CommonJS, and shell
+adapters are not part of the contract. Do not add `ui.*` files here; official UI
+actions go through shared base transports. Examples:
 
 ```text
 library/actions/extension/perps/ensure_positions.mjs

package/library/actions/core/perps/_controller.mjs

@@ -90,12 +90,7 @@ function buildInfrastructure(stubbed) {
 // The fixture has the standard { accounts: [{ type, value, name }] } shape from
 // wallet-fixture.json.sample. The recipe node selects an account by name via
 // `account_name` (default "dev1"). The viem account derived from the fixture
-// entry is the authoritative source for both the address AND the signing key —
-// no separate MM_TEST_ACCOUNT_ADDRESS env var needed.
-//
-// Env-var fallback: if no fixture is present (e.g. direct CLI invocation),
-// MM_TEST_ACCOUNT_SRP / MM_TEST_ACCOUNT_PRIVATE_KEY + MM_TEST_ACCOUNT_ADDRESS
-// are still accepted for backward compatibility.
+// entry is the authoritative source for both the address and signing key.
 
 /**
  * Load wallet-fixture.json and return the named account entry.
@@ -155,26 +150,6 @@ function viemAccountFromFixtureEntry(entry) {
   return privateKeyToAccount(normalized);
 }
 
-// Env-var fallback constants (used only when wallet-fixture.json is absent).
-const SIGNER_PRIVATE_KEY_ENV = 'MM_TEST_ACCOUNT_PRIVATE_KEY';
-const SIGNER_MNEMONIC_ENV = 'MM_TEST_ACCOUNT_SRP';
-
-function signerFromEnv() {
-  const pk = process.env[SIGNER_PRIVATE_KEY_ENV]?.trim();
-  if (pk && pk.length > 0) {
-    const normalized = pk.startsWith('0x') ? pk : `0x${pk}`;
-    if (!/^0x[0-9a-fA-F]{64}$/u.test(normalized)) {
-      throw new Error(`${SIGNER_PRIVATE_KEY_ENV} is not a 32-byte hex private key.`);
-    }
-    return privateKeyToAccount(normalized);
-  }
-  const mnemonic = process.env[SIGNER_MNEMONIC_ENV]?.trim();
-  if (mnemonic && mnemonic.split(/\s+/u).length >= 12) {
-    return mnemonicToAccount(mnemonic, { addressIndex: 0 });
-  }
-  return null;
-}
-
 /**
  * Resolve the account name to use for signing.
  * Precedence: node.account_name → node.account (if not an address) → "dev1".
@@ -198,9 +173,7 @@ function resolveAccountName(input) {
 
 /**
  * Resolve the viem signer and EVM address for writes.
- * Primary: wallet-fixture.json account selected by name.
- * Fallback: MM_TEST_ACCOUNT_PRIVATE_KEY / MM_TEST_ACCOUNT_SRP env vars
- *           (requires MM_TEST_ACCOUNT_ADDRESS for address verification).
+ * The wallet fixture account selected by name is the only signing source.
  *
  * @param input - Adapter input (context.projectRoot, node.account_name).
  * @returns { account: ViemAccount, address: string }
@@ -209,7 +182,6 @@ async function resolveSignerFromFixture(input) {
   const projectRoot = input.context?.projectRoot;
   const accountName = resolveAccountName(input);
 
-  // Primary: fixture
   if (projectRoot) {
     const entry = await loadFixtureAccount(projectRoot, accountName);
     if (entry) {
@@ -218,32 +190,15 @@ async function resolveSignerFromFixture(input) {
     }
   }
 
-  // Fallback: env vars (no fixture present — direct CLI use)
-  const account = signerFromEnv();
-  if (!account) {
-    throw new Error(
-      `core perps writes require a wallet-fixture.json with account "${accountName}", ` +
-      `or env vars ${SIGNER_PRIVATE_KEY_ENV} / ${SIGNER_MNEMONIC_ENV} + MM_TEST_ACCOUNT_ADDRESS.`,
-    );
-  }
-  const envAddress = String(process.env.MM_TEST_ACCOUNT_ADDRESS ?? '').trim();
-  if (!/^0x[0-9a-fA-F]{40}$/u.test(envAddress)) {
-    throw new Error(
-      `Env-var fallback requires MM_TEST_ACCOUNT_ADDRESS (a 0x EVM address) to verify the signer.`,
-    );
-  }
-  if (account.address.toLowerCase() !== envAddress.toLowerCase()) {
-    throw new Error(
-      `Env-var signer derives ${account.address} but MM_TEST_ACCOUNT_ADDRESS is ${envAddress}; signatures would be invalid.`,
-    );
-  }
-  return { account, address: envAddress };
+  throw new Error(
+    `core perps writes require wallet-fixture.json account "${accountName}". ` +
+    `Next: run mm-harness fixtures set`,
+  );
 }
 
 /**
  * Resolve the account address for reads (no signing required).
- * Primary: wallet-fixture.json account selected by name (address derived from key).
- * Fallback: node.account / node.address / MM_TEST_ACCOUNT_ADDRESS env var.
+ * Prefer the wallet fixture account; explicit node addresses support read-only calls.
  */
 async function requireAccountAddress(input) {
   const projectRoot = input.context?.projectRoot;
@@ -261,13 +216,13 @@ async function requireAccountAddress(input) {
     }
   }
 
-  // Fallback: explicit address from node or env
+  // Read-only calls may name an address directly.
   const fromNode = input.node?.account ?? input.node?.address ?? input.node?.userAddress;
-  const address = String(fromNode ?? process.env.MM_TEST_ACCOUNT_ADDRESS ?? '').trim();
+  const address = String(fromNode ?? '').trim();
   if (!/^0x[0-9a-fA-F]{40}$/u.test(address)) {
     throw new Error(
       `core perps reads require a wallet-fixture.json with account "${accountName}", ` +
-      `or a 0x EVM address via node.account / MM_TEST_ACCOUNT_ADDRESS.`,
+      `or a 0x EVM address via node.account.`,
     );
   }
   return address;

package/library/manifests/mobile.action-manifest.json

@@ -156,7 +156,7 @@
       ]
     },
     "ui.press": {
-      "description": "Press a React Native component by exact testID/test_id, a legacy selector identifier, or contained visible text.",
+      "description": "Press a React Native component by exact testID/test_id, selector identifier, or contained visible text.",
       "schema": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -71,4 +71,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}