@deeeed/metamask-harness 0.2.0 → 0.3.1

package/adapters/shared/sync-wallet-fixture.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# sync-wallet-fixture.sh — copy the wallet fixture to the canonical runtime slot.
+#
+# Purpose:
+#   After a successful overlay install, ensures the canonical wallet fixture is
+#   present in the checkout's runtime dir. Non-zero exit is informational (no
+#   fixture source found); the install already succeeded, so the overlay is fresh.
+#
+# Inputs (flags / env):
+#   --target <checkout>     (default $PWD)
+#   --slot-id <id>          (env FARMSLOT_SLOT_ID, SLOT_ID — farmslot sync source)
+#   --cdp-port <port>       (env CDP_PORT — extension fixture seeding port)
+#
+# Outputs:
+#   Copies wallet-fixture.json to <target>/<RECIPE_RUNTIME_DIR>/wallet-fixture.json
+#   when a source is found. Exit 0 always (non-zero only when no source found;
+#   callers treat this as informational).
+#
+# OS-glue only: file copy and farmslot delegation; decision logic lives in
+# src/commands/fixtures.ts.
+set -uo pipefail
+
+TARGET="$PWD"
+SLOT_ID="${FARMSLOT_SLOT_ID:-${SLOT_ID:-}}"
+CDP_PORT="${CDP_PORT:-}"
+
+require_value() { [ "$#" -ge 2 ] || { printf 'Missing value for %s\n' "$1" >&2; exit 2; }; }
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)   require_value "$@"; TARGET="$2";   shift 2 ;;
+    --slot-id)  require_value "$@"; SLOT_ID="$2";  shift 2 ;;
+    --cdp-port) require_value "$@"; CDP_PORT="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: sync-wallet-fixture.sh [--target <dir>] [--slot-id <id>] [--cdp-port <port>]\n'
+      exit 0
+      ;;
+    *) printf 'Unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+TARGET="$(cd "$TARGET" && pwd)"
+RUNTIME_DIR="${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}"
+CANONICAL="$TARGET/$RUNTIME_DIR/wallet-fixture.json"
+
+mkdir -p "$(dirname "$CANONICAL")"
+
+# Already present — nothing to do.
+if [ -f "$CANONICAL" ]; then
+  exit 0
+fi
+
+# RECIPE_WALLET_FIXTURE env points at a fixture directly.
+if [ -n "${RECIPE_WALLET_FIXTURE:-}" ] && [ -f "${RECIPE_WALLET_FIXTURE}" ]; then
+  cp "${RECIPE_WALLET_FIXTURE}" "$CANONICAL"
+  chmod 600 "$CANONICAL" 2>/dev/null || true
+  printf 'sync-wallet-fixture: linked wallet-fixture.json from RECIPE_WALLET_FIXTURE\n' >&2
+  exit 0
+fi
+
+# Farmslot slot sync (requires farmslot root and sync-fixtures.sh).
+if [ -n "$SLOT_ID" ]; then
+  FARMSLOT_ROOT="${FARMSLOT_ROOT:-}"
+  for candidate in "$HOME/dev/farmslot" "$HOME/farmslot"; do
+    [ -d "$candidate/scripts" ] || continue
+    FARMSLOT_ROOT="$candidate"
+    break
+  done
+  if [ -n "$FARMSLOT_ROOT" ] && [ -f "$FARMSLOT_ROOT/scripts/sync-fixtures.sh" ]; then
+    if bash "$FARMSLOT_ROOT/scripts/sync-fixtures.sh" --slot "$SLOT_ID" 2>/dev/null; then
+      [ -f "$CANONICAL" ] && exit 0
+    fi
+  fi
+fi
+
+# No fixture source found — informational non-zero (callers tolerate this).
+printf 'sync-wallet-fixture: no wallet fixture source found for %s\n' "$TARGET" >&2
+exit 1

package/bin/mm-harness

@@ -1,10 +1,9 @@
 #!/usr/bin/env bash
 # mm-harness — the single front door for the MetaMask recipe loop.
 #
-# Same node/tsx resolution mechanism as bin/metamask-recipe, but the entry is the
-# commander-based CLI (runner/src/mm-harness-cli.ts) that presents only the
-# validated end-state surface. Legacy names (metamask-recipe/mm-recipe/mme-recipe,
-# manifest/live/runtime-*) stay reachable via their own bins until the caller sweep.
+# The entry is the commander-based CLI (src/mm-harness-cli.ts) that presents the
+# end-state surface; it resolves node/tsx/dist the same way whether the package is
+# installed as a dependency or run from a source checkout.
 set -euo pipefail
 SOURCE="${BASH_SOURCE[0]}"
 while [ -L "$SOURCE" ]; do
@@ -19,13 +18,45 @@ done
 SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" && pwd -P)"
 RUNNER_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
-ENSURE_DEPS="$RUNNER_DIR/orchestration/lib/ensure-runner-deps.sh"
+# Dev/prod switch (the single override point). MM_HARNESS_BIN, when set, is the
+# authoritative path to a dev checkout's bin/mm-harness with active pre-release
+# changes; unset resolves the installed/global mm-harness (prod). Handing the
+# invocation over here, before any dependency work, lets the dev checkout fully
+# own the run. The self-path guard prevents an exec loop when MM_HARNESS_BIN
+# already points at this script — including via a symlink (both sides are resolved
+# to their real paths before comparing).
+if [ -n "${MM_HARNESS_BIN:-}" ]; then
+  self_real="$SCRIPT_DIR/$(basename "$SOURCE")"
+  # Resolve MM_HARNESS_BIN through any symlink chain so a symlink-to-self is caught.
+  mm_bin_src="$MM_HARNESS_BIN"
+  while [ -L "$mm_bin_src" ]; do
+    mm_bin_dir="$(cd "$(dirname "$mm_bin_src")" && pwd -P)"
+    mm_bin_target="$(readlink "$mm_bin_src")"
+    if [[ "$mm_bin_target" == /* ]]; then
+      mm_bin_src="$mm_bin_target"
+    else
+      mm_bin_src="$mm_bin_dir/$mm_bin_target"
+    fi
+  done
+  bin_real_dir="$(cd "$(dirname "$mm_bin_src")" 2>/dev/null && pwd -P || true)"
+  bin_real="${bin_real_dir:+$bin_real_dir/$(basename "$mm_bin_src")}"
+  if [ "$bin_real" != "$self_real" ]; then
+    if [ ! -x "$MM_HARNESS_BIN" ]; then
+      echo "mm-harness: MM_HARNESS_BIN is not an executable: $MM_HARNESS_BIN" >&2
+      echo "  Next: point MM_HARNESS_BIN at a checkout's bin/mm-harness, or unset it to use the global install" >&2
+      exit 1
+    fi
+    exec "$MM_HARNESS_BIN" "$@"
+  fi
+fi
+
+ENSURE_DEPS="$RUNNER_DIR/adapters/shared/ensure-runner-deps.sh"
 if [ -f "$ENSURE_DEPS" ]; then
   # shellcheck disable=SC1090
   bash "$ENSURE_DEPS" "$RUNNER_DIR"
 fi
 
-ENTRY_TS="$RUNNER_DIR/runner/src/mm-harness-cli.ts"
+ENTRY_TS="$RUNNER_DIR/src/mm-harness-cli.ts"
 ENTRY_DIST="$RUNNER_DIR/dist/mm-harness-cli.js"
 
 find_protocol_root() {

package/docs/CLI-SPEC.md

@@ -36,8 +36,8 @@ exhaustive —
 - **REMOVE** — name/bin/subcommand deleted in the wave; **requires a one-line justification** (needs Arthur's sign-off).
 
 **No row may be unmapped.** An unmapped row means the refactor is not allowed to
-proceed. Source of truth: the bins' `case` statements + the naming audit in
-[harness-cli.md](harness-cli.md). Every row is real.
+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`)
 
@@ -913,3 +913,42 @@ The fleet is just another agent-grade caller:
   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`.
+

package/docs/architecture.md

@@ -1,5 +1,40 @@
 # MetaMask Recipe Runner 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
@@ -21,9 +56,9 @@ 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,
+`adapters/<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
+[`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.
 
@@ -32,10 +67,10 @@ skill thins to a few lines that call it. Same pattern applies to every other
 
 | 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 |
+| `.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/`, `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 |
+| `.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
@@ -85,15 +120,15 @@ 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:
+`src/**` *imports* the generic contracts rather than forking them:
 
-- `runner/src/cli.ts` imports `RecipeRunResult` from `@farmslot/recipe-harness`
+- `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
+- `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*
+- `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
+- `src/recording-target.ts` is a MetaMask provider over the farmslot
   `RecordingTarget` contract.
 
 **The invariant both repos assert:** farmslot stays MetaMask-free; the runner
@@ -104,7 +139,7 @@ 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).
+> `cleanup`/`live`), never "the harness" — see [CLI-SPEC.md](CLI-SPEC.md).
 
 ## One-minute model
 
@@ -141,8 +176,8 @@ 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 |
+| 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
@@ -168,29 +203,26 @@ describes **how an agent should work**, it belongs in skills.
 
 | 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`. |
+| `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. |
-| `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. |
+| `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/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`:
+Defaults are centralized in `adapters/shared/path-defaults.json`:
 
 ```json
 {
@@ -210,7 +242,7 @@ Install commands write a small runtime package into the target checkout:
 <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/bin/mm-harness       delegate back to the resolved runner source
   runner/recipes/             reusable recipe snapshot
   scripts/                    adapter runtime helpers copied from this repo
 ```
@@ -222,10 +254,10 @@ 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
+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/`, `runner/src/`, `library/actions/`, and `library/recipes/`.
+`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:
@@ -233,8 +265,7 @@ 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}/`.
+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
@@ -247,7 +278,7 @@ 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. |
+| 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. |
 
@@ -260,10 +291,10 @@ 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
+mm-harness launch ios|android
+      │ prepareMobile() in-process → yarn-setup / start-metro / open-device leaves
       ▼
-library/actions/mobile/bridge-runtime/cdp-bridge.cjs
+adapters/mobile/bridge-runtime/cdp-bridge.cjs
       │ connects to Hermes / RN debug runtime
       ▼
 globalThis.__AGENTIC__ inside the app
@@ -295,7 +326,7 @@ 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
+mme-recipe / adapters/extension/*.sh
       │ checks dist freshness, build health, fixture/profile state
       ▼
 Chrome for Testing with --load-extension=<runtime-dist>
@@ -329,7 +360,7 @@ Allowed in shell:
 Not allowed in shell:
 
 - Recipe v1 graph execution;
-- MetaMask domain semantics that can live in `runner/src/**/*.ts` or `library/actions/**/*.mjs`;
+- 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.
 

package/docs/runtime-file-conventions.md

@@ -6,9 +6,9 @@ package without requiring target app builds to transpile runner code.
 
 ## Extension rules
 
-- `runner/src/**/*.ts` — typed runner core: CLI parsing, manifests, adapter binding,
+- `src/**/*.ts` — typed runner core: CLI parsing, manifests, adapter binding,
   runtime decisions, and shared helper logic.
-- `library/actions/**/*.mjs`, `orchestration/**/*.mjs`, and `scripts/**/*.mjs` —
+- `library/actions/**/*.mjs`, `adapters/**/*.mjs`, and `scripts/**/*.mjs` —
   standalone ESM modules that Node executes directly with no build step. Use
   these for action adapters and small injected/runtime helpers.
 - `*.cjs` — compatibility islands only. Keep these quarantined for helper code
@@ -31,6 +31,6 @@ The mix is intentional only when the boundary is clear:
 4. Shell stays at the edge for host/device commands.
 
 If a file crosses those boundaries, move the logic inward: shell should call a
-Node module, standalone `.mjs` should become typed `runner/src/**/*.ts` when it grows
+Node module, standalone `.mjs` should become typed `src/**/*.ts` when it grows
 shared domain logic, and new compatibility needs should be documented before
 adding another `.cjs` file.

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

@@ -8,7 +8,7 @@ import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 // this adapter under the bundled tsx (see commandFor/importsSourceTypescript in
 // src/live-adapter-contract.ts). The core adapter dynamic-imports the perps
 // controller TypeScript at runtime, so it MUST run under tsx, not plain node.
-import { walletFixturePath } from '../../../../runner/src/paths.ts';
+import { walletFixturePath } from '../../../../src/index.ts';
 
 // Shared headless instantiation for the MetaMask `core` adapter.
 //

package/library/actions/extension/platform/cdp.mjs

@@ -10,8 +10,8 @@ import {
   extensionIdPath,
   recipeHarnessPath,
   walletFixturePath,
-} from '../../../../runner/src/paths.ts';
-import { captureActiveRecipeRecordingSnapshot } from '../../../../runner/src/run-recording.ts';
+  captureActiveRecipeRecordingSnapshot,
+} from '../../../../src/index.ts';
 
 // Resolve the Farmslot harness through normal package dependencies by default.
 // Local Farmslot source is only a dev override handled by src/paths.ts.

package/library/actions/extension/wallet/ensure_unlocked.mjs

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
-import { walletFixturePath } from '../../../../runner/src/paths.ts';
+import { walletFixturePath } from '../../../../src/index.ts';
 
 async function fixturePassword(projectRoot) {
   const candidates = [

package/library/actions/mobile/platform/bridge.mjs

@@ -31,7 +31,7 @@ function bridgeScript(input) {
 }
 
 function runtimeDir() {
-  return fileURLToPath(new URL('../bridge-runtime', import.meta.url));
+  return fileURLToPath(new URL('../../../../adapters/mobile/bridge-runtime', import.meta.url));
 }
 
 export function bridgeEnv(input) {

package/library/actions/mobile/wallet/ensure_unlocked.mjs

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
-import { walletFixturePath } from '../../../../runner/src/paths.ts';
+import { walletFixturePath } from '../../../../src/index.ts';
 
 async function fixturePassword(projectRoot) {
   const candidates = [

package/library/actions/mobile/wallet/setup.mjs

@@ -3,7 +3,7 @@ import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bridgeCommand, bridgeEnv, runAdapter } from '../platform/bridge.mjs';
-import { walletFixturePath } from '../../../../runner/src/paths.ts';
+import { walletFixturePath } from '../../../../src/index.ts';
 
 async function fixtureProfile(projectRoot) {
   const candidates = [
@@ -109,7 +109,7 @@ function setupWalletScript() {
   if (process.env.METAMASK_RECIPE_MOBILE_SETUP_WALLET_SCRIPT) {
     return process.env.METAMASK_RECIPE_MOBILE_SETUP_WALLET_SCRIPT;
   }
-  return fileURLToPath(new URL('../bridge-runtime/setup-wallet.sh', import.meta.url));
+  return fileURLToPath(new URL('../../../../adapters/mobile/bridge-runtime/setup-wallet.sh', import.meta.url));
 }
 
 function runSetupWallet(input, fixture) {

package/library/library.json

@@ -2,6 +2,6 @@
   "kind": "recipe-library",
   "schema_version": 1,
   "name": "metamask",
-  "owner": "metamask-recipe-runner",
+  "owner": "mm-harness-runner",
   "description": "Canonical MetaMask recipe library: minimal, stable flows every recipe can compose. Team and personal libraries layer on top and win resolution by default."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -8,7 +8,7 @@
   "scripts": {
     "dev:link-farmslot": "node scripts/link-local-farmslot.mjs",
     "check": "node scripts/check.mjs",
-    "self-test": "orchestration/porcelain/metamask-recipe self-test",
+    "self-test": "bin/mm-harness self-test",
     "manifest:mobile": "bin/mm-harness actions --raw --adapter mobile --json",
     "manifest:extension": "bin/mm-harness actions --raw --adapter extension --json",
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
@@ -24,12 +24,12 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0"
   },
-  "main": "./runner/src/index.ts",
-  "types": "./runner/src/index.ts",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
     ".": {
-      "types": "./runner/src/index.ts",
-      "import": "./runner/src/index.ts"
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
     }
   },
   "publishConfig": {
@@ -37,8 +37,8 @@
   },
   "files": [
     "bin",
-    "runner",
-    "orchestration",
+    "src",
+    "adapters",
     "library",
     "scripts/completions.sh",
     "scripts/install-completions.sh",

package/{orchestration → src/adapters}/extension/runtime-decision.ts

@@ -3,7 +3,6 @@
 import { execFileSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   depsCheck,
@@ -11,7 +10,7 @@ import {
   recordDepsBaseline,
   type DepsCheck,
 } from '@farmslot/recipe-harness/runtime/deps-readiness';
-import { recipeWatchLogCandidates } from '../../runner/src/paths.ts';
+import { recipeHarnessPath, recipeWatchLogCandidates } from '../../paths.ts';
 
 /**
  * Deterministic runtime-readiness decision for the MetaMask Extension.
@@ -181,10 +180,11 @@ function webpackFingerprint(target: string): { gitHead: string; fingerprint: str
   return { gitHead: git(target, ['rev-parse', 'HEAD']) ?? 'unknown', fingerprint: hash.digest('hex') };
 }
 
-// ── per-checkout baseline store (machine-local; never written into the repo) ──
+// ── per-checkout baseline store (checkout-local; not written into the repo) ──
+// State lives under the checkout's own harness dir so it is scoped to the
+// checkout, survives /tmp cleanup, and is not in a world-writable directory.
 function stateDir(target: string): string {
-  const key = crypto.createHash('sha1').update(path.resolve(target)).digest('hex').slice(0, 16);
-  return path.join(os.tmpdir(), 'metamask-recipe-decision', key);
+  return recipeHarnessPath(target, 'extension', 'decision-state');
 }
 
 function readBaseline(target: string, name: string): Record<string, unknown> | null {

package/{orchestration → src/adapters}/extension/runtime.ts

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, recipeRuntimeDir, resolveLocalProtocolRoot, resolveRequiredLocalProtocolRoot, runnerDir } from '../../runner/src/paths.ts';
+import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, recipeRuntimeDir, resolveLocalProtocolRoot, resolveRequiredLocalProtocolRoot, runnerDir } from '../../paths.ts';
 
 // Runtime health uses package dependencies. Launching a host-managed validation
 // browser remains a dev-only path because it needs pool/project scripts from a