@deeeed/metamask-harness 0.2.0 → 0.3.0

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.0",
   "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

package/src/adapters/mobile/prepare.ts

@@ -0,0 +1,210 @@
+// Mobile runtime prepare — in-process decision-and-action loop.
+//
+// Replaces the retired shell orchestrators (prepare-device.sh + launch.sh).
+// All sequencing is in TypeScript; leaf shell scripts handle single OS ops.
+// Control flows down only: TS → adapters/mobile/{yarn-setup,start-metro,open-device}.sh
+// No leaf script may call back into mm-harness (A1).
+
+import path from 'node:path';
+
+import { EXIT, spawnScript } from '../../commands/shared.ts';
+import type { ScriptResult } from '../../commands/shared.ts';
+import { runnerDir } from '../../paths.ts';
+import {
+  decideMobileReadiness,
+  type MobileRuntimeDecisionReport,
+  type MobileRuntimeDecisionOptions,
+} from './runtime-decision.ts';
+
+export { type MobileRuntimeDecisionReport };
+
+export interface PrepareMobileOptions extends MobileRuntimeDecisionOptions {
+  /** Pass through to leaf-script spawnScript calls so output is suppressed in --json mode. */
+  json?: boolean;
+  /**
+   * Passed to open-device.sh --preflight-mode.
+   * 'fast' = error if not installed; 'auto' = install if missing; 'rebuild-native'/'clean' = always rebuild.
+   * Defaults to 'fast'.
+   */
+  preflightMode?: string;
+  /**
+   * Force --clear on start-metro (reset bundle cache).
+   * Used by the setup-wallet clean-Metro retry path (M3).
+   */
+  clearMetro?: boolean;
+}
+
+/**
+ * Read current runtime readiness without executing any action.
+ * No side effects: just calls decideMobileReadiness and returns the report.
+ */
+export async function mobileRuntimeStatus(
+  target: string,
+  opts: PrepareMobileOptions = {},
+): Promise<MobileRuntimeDecisionReport> {
+  return decideMobileReadiness(target, {
+    watcherPort: opts.watcherPort,
+    metroLog: opts.metroLog,
+    platform: opts.platform,
+    record: opts.record,
+  });
+}
+
+/**
+ * Prepare the mobile runtime: run the readiness decision then execute each
+ * action in sequence via single-purpose leaf shell scripts. Returns a
+ * ScriptResult so the launch heal loop can classify outcomes uniformly.
+ */
+export async function prepareMobile(
+  target: string,
+  opts: PrepareMobileOptions = {},
+): Promise<ScriptResult> {
+  const json = opts.json ?? false;
+  const platform = opts.platform ?? 'ios';
+  const preflightMode = opts.preflightMode ?? 'fast';
+  const clearMetro = opts.clearMetro ?? false;
+
+  const report = await decideMobileReadiness(target, {
+    watcherPort: opts.watcherPort,
+    metroLog: opts.metroLog,
+    platform,
+    record: opts.record,
+  });
+
+  if (report.decision === 'blocked') {
+    const reasons = report.reasons.join(' ');
+    const msg = `mobile prepare blocked: ${reasons}\n  Next: fix the bundle error in app code before retrying recipe up.`;
+    if (!json) process.stderr.write(`${msg}\n`);
+    return { status: EXIT.runtime, output: msg };
+  }
+
+  if (report.decision === 'ready') {
+    return { status: 0, output: '' };
+  }
+
+  if (report.decision === 'unknown') {
+    const msg = 'mobile prepare: runtime state unknown\n  Next: run mm-harness verify --adapter mobile --target <checkout>';
+    if (!json) process.stderr.write(`${msg}\n`);
+    return { status: EXIT.runtime, output: msg };
+  }
+
+  // decision is 'install' or 'launch' — execute each action in sequence.
+  // clearMetro forces --clear on start-metro regardless of what decideMobileReadiness set.
+  const actions = clearMetro
+    ? report.actions.map((a) =>
+        a.id === 'start-metro' && !a.argv?.includes('--clear')
+          ? { ...a, argv: [...(a.argv ?? []), '--clear'] }
+          : a,
+      )
+    : report.actions;
+  for (const action of actions) {
+    const result = dispatchAction(action, target, platform, json, preflightMode);
+    if (result.status !== 0) return result;
+  }
+
+  // After install: re-decide and run appropriate actions.
+  // RECIPE_UP_INSTALL_ATTEMPTED guards against infinite loops if yarn-setup was a no-op.
+  if (report.decision === 'install' && !process.env['RECIPE_UP_INSTALL_ATTEMPTED']) {
+    process.env['RECIPE_UP_INSTALL_ATTEMPTED'] = '1';
+    const postInstall = await decideMobileReadiness(target, {
+      watcherPort: opts.watcherPort,
+      metroLog: opts.metroLog,
+      platform,
+      record: true,
+    });
+    switch (postInstall.decision) {
+      case 'install': {
+        // Yarn setup ran but runtime is still unresolved — teach and fail.
+        const msg =
+          `mobile prepare: dependencies installed but runtime is still unresolved ` +
+          `(${postInstall.reasons.join('; ')})\n` +
+          `  Next: inspect the checkout — node_modules may be incomplete or yarn.lock drifted.`;
+        if (!json) process.stderr.write(`${msg}\n`);
+        return { status: EXIT.runtime, output: msg };
+      }
+      case 'ready': {
+        // Deps resolved and runtime appears ready — still confirm bridge is live.
+        const bridge = dispatchAction({ id: 'wait-for-bridge', cwd: target }, target, platform, json, preflightMode);
+        if (bridge.status !== 0) return bridge;
+        break;
+      }
+      case 'launch': {
+        for (const action of postInstall.actions) {
+          const result = dispatchAction(action, target, platform, json, preflightMode);
+          if (result.status !== 0) return result;
+        }
+        break;
+      }
+      default: {
+        // 'blocked' or 'unknown' after install — surface as error.
+        const msg =
+          `mobile prepare: post-install state is ${postInstall.decision}: ${postInstall.reasons.join('; ')}\n` +
+          `  Next: run mm-harness verify --adapter mobile --target <checkout>`;
+        if (!json) process.stderr.write(`${msg}\n`);
+        return { status: EXIT.runtime, output: msg };
+      }
+    }
+  }
+
+  return { status: 0, output: '' };
+}
+
+function dispatchAction(
+  action: { id: string; argv?: string[]; cwd?: string },
+  target: string,
+  platform: string,
+  json: boolean,
+  preflightMode = 'fast',
+): ScriptResult {
+  const cwd = action.cwd ?? target;
+  switch (action.id) {
+    case 'yarn-setup': {
+      // Leaf: install node_modules (deps missing or stale).
+      const leaf = path.join(runnerDir, 'adapters/mobile/yarn-setup.sh');
+      return spawnScript(leaf, ['--target', cwd], target, json);
+    }
+    case 'start-metro': {
+      // Leaf: ensure Metro is running; argv may carry --clear for cache reset.
+      const leaf = path.join(runnerDir, 'adapters/mobile/start-metro.sh');
+      const extra: string[] = action.argv ?? [];
+      return spawnScript(leaf, ['--target', cwd, ...extra], target, json);
+    }
+    case 'prewarm-bundle': {
+      // Leaf: curl the bundle URL before opening the dev client.
+      const leaf = path.join(runnerDir, 'adapters/mobile/prewarm-bundle.sh');
+      return spawnScript(leaf, ['--platform', platform, '--target', cwd], target, json);
+    }
+    case 'wait-for-bridge': {
+      // Leaf: poll CDP bridge until a route target registers.
+      const leaf = path.join(runnerDir, 'adapters/mobile/wait-for-bridge.sh');
+      return spawnScript(leaf, ['--target', cwd], target, json);
+    }
+    case 'clear-metro-cache': {
+      // Legacy alias for start-metro --clear (kept for backward compat).
+      const leaf = path.join(runnerDir, 'adapters/mobile/start-metro.sh');
+      return spawnScript(leaf, ['--target', cwd, '--clear'], target, json);
+    }
+    case 'launch-mobile-runtime': {
+      // Leaf: open the MetaMask Mobile dev client on the simulator/device.
+      const leaf = path.join(runnerDir, 'adapters/mobile/open-device.sh');
+      return spawnScript(
+        leaf,
+        ['--platform', platform, '--target', cwd, '--preflight-mode', preflightMode],
+        target,
+        json,
+      );
+    }
+    case 'rebuild-native-dev-client': {
+      // Native rebuild required — the dev client binary predates a native Nitro
+      // module. Inform the caller; a full native build is not automated here.
+      const msg =
+        'rebuild-native-dev-client required: native module mismatch detected.\n' +
+        '  Next: yarn start:ios or yarn start:android to rebuild the native dev client, ' +
+        'then re-run mm-harness launch.';
+      if (!json) process.stderr.write(`${msg}\n`);
+      return { status: EXIT.runtime, output: msg };
+    }
+    default:
+      return { status: 0, output: '' };
+  }
+}

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

@@ -86,10 +86,18 @@ const installActions = (target: string): MobileRuntimeDecisionAction[] => [
 
 const launchActions = (target: string, clearMetro = false): MobileRuntimeDecisionAction[] => {
   const actions: MobileRuntimeDecisionAction[] = [];
-  if (clearMetro) {
-    actions.push({ id: 'clear-metro-cache', argv: ['yarn', 'expo', 'start', '--clear'], cwd: target });
-  }
+  // start-metro ensures Metro is running; --clear resets the bundle cache.
+  actions.push({
+    id: 'start-metro',
+    argv: clearMetro ? ['--clear'] : [],
+    cwd: target,
+  });
+  // Prewarm the bundle before opening the dev client so the app connects instantly.
+  actions.push({ id: 'prewarm-bundle', cwd: target });
+  // Open the dev client via the expo-development-client deep link.
   actions.push({ id: 'launch-mobile-runtime' });
+  // Poll the CDP bridge until a route target registers (confirms app is bridged).
+  actions.push({ id: 'wait-for-bridge', cwd: target });
   return actions;
 };