@deeeed/metamask-harness 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.3.1 - 2026-07-03
+
+### Fixed
+- **Customization compose-by-ref**: recipes with `{action:"call",ref:"<lib>.<flow>"}` + `--library <lib>=<dir>` now pass pre-run schema validation AND execute at runtime. `validateRecipeAdapterAware` threads `externalFlowIds` into both `validateRecipeDocument` and `validateRecipeWithManifest`; library resolution also runs at `run` time.
+- **IMP-14: stale metro.log guard** — if `metro.log` is older than the install markers (`node_modules/.yarn-state.yml`, `.yarn/install-state.gz`), it is treated as absent so a stale log cannot drive a false native-module-mismatch decision at launch.
+- **IMP-15: stale overlay shim auto-repair (two modes)** — `ensureOverlay` detects (1) a `.runner-source` pointing to a nonexistent runner dir, and (2) a `.runner-source` whose dir exists but whose `bin/mm-harness` was removed. Both re-install automatically before launch.
+- **IMP-17: deps-staleness fallback (two-layer)** — (1) mtime comparison when no baseline exists: manifest files newer than install markers → `install`; (2) required-dep absence: a top-level `package.json` dep absent from `node_modules` is caught at pre-flight as `deps-partial` → `install`, before Metro discovers it during a long bundle run.
+- **IMP-18: iOS sim scheme-approval pre-write** — `open-device.sh` writes `com.apple.launchservices.schemeapproval` via `xcrun simctl spawn … defaults write` before the first `openurl`, eliminating the "Open in \<App\>?" dialog hang. Scheme derives from `DEV_CLIENT_SCHEME` (overridable via `IOS_DEV_CLIENT_SCHEME`).
+
+## 0.3.0 - 2026-07-03
+
+### Changed
+- Porcelain layer eliminated: the legacy `mm-recipe`/`mme-recipe`/`metamask-recipe` bins are gone; launch/logs/debug/fixtures compose the adapter scripts directly in TypeScript. Repository reorganized into `src/` (all TS), `adapters/` (per-platform runtime glue), `library/` (recipe/action/flow vocabulary).
+
+### Fixed
+- Extension `launch` opens the app directly (composes `live.sh`) instead of a retired command.
+- Mobile `cleanup` resilient to a stale runner-source path.
+- Core run teaches the correct next step when no account is set.
+- Resolved CodeQL alerts (insecure temp dir, file-access-to-http).
+
+## Unreleased
+
+### Added
+
+- **`mm-harness update`**: checks the npm registry `dist-tags.latest` for `@deeeed/metamask-harness` and, when newer, runs `npm i -g @deeeed/metamask-harness@latest` and prints `old → new`; already-current exits 0. `--check` reports only (exit 0 up-to-date, exit 1 update available); `--json` carries `{ current, latest, updateAvailable }`. Every failure path (no npm, registry unreachable, permission-denied global dir) exits 3 with the exact escape.
+- **Passive update nudge**: on invocation (throttled to once/day via a cache file, bounded fetch, skipped in CI and when `MM_HARNESS_NO_UPDATE_CHECK=1`), a single `stderr` line announces a newer published version — never on stdout, never blocking, never auto-updating.
+- **`MM_HARNESS_BIN` dev/prod switch**: the entrypoint honors `MM_HARNESS_BIN` as the single override point — when set, the invocation is handed to that dev checkout's `bin/mm-harness`; unset resolves the installed/global bin (prod). A self-path guard prevents an exec loop, and a non-executable value teaches its fix. Documented in `--help` and README.
+
+### Changed
+
+- **Teaching errors are type-enforced**: `usageOut` now requires a `userAction` escape argument, so a teaching error without a reachable next step no longer compiles. The repo-type detection failure teaches BOTH escapes (`cd into a checkout / pass --target <path>` and `--adapter <mobile|extension|core>`) consistently across `doctor`, `launch`, `verify`, and the overlay path.
+- **Repository reorganized into `src/`, `adapters/`, `library/` domains**: all TypeScript now lives under `src/` (shared CLI/core plus typed per-adapter logic in `src/adapters/<adapter>/`); everything that executes against or is injected into the app runtime lives under `adapters/` (`adapters/<adapter>/` per-app glue, `adapters/shared/` cross-adapter OS-glue, `adapters/porcelain/` composed entrypoints, `adapters/*/overlay/` the only injected payload); `library/` holds composable vocabulary only. The `runner/` and `orchestration/` trees no longer exist. The surface doctor moved to `scripts/adapter-surface-doctor.mjs` with its index at `adapters/manifest.json`. Placement rules (R1–R11) are documented in `AGENTS.md`. This is a path-only reorganization; runtime behavior is unchanged.
+
 ## 0.2.0 - 2026-07-03
 
 ### Changed

package/README.md

@@ -1,5 +1,7 @@
 # MetaMask Recipe Runner — `mm-harness`
 
+Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+
 **`mm-harness` is built for the agent but easy for the human to use and
 understand.** It is the MetaMask recipe harness: one front door to launch the app,
 prove behavior with recipes, and manage the per-checkout runtime overlay. It is a
@@ -26,8 +28,7 @@ completions (zsh + bash) for commands, targets, and flags.
 Naming: **"harness" is the tool** (`mm-harness`) and the generic engine package
 (`@farmslot/recipe-harness`); the files it installs into a checkout are the
 **runtime overlay**. Read [MENTAL-MODEL.md](docs/MENTAL-MODEL.md) first (the
-before→after map), then [CLI-SPEC.md](docs/CLI-SPEC.md) for the full contract
-([harness-cli.md](docs/harness-cli.md) is a short pointer to it).
+before→after map), then [CLI-SPEC.md](docs/CLI-SPEC.md) for the full contract.
 
 One package, two responsibilities:
 
@@ -60,8 +61,8 @@ mm-harness run      # runner/proof: actions execute and evidence is saved
 ```
 
 Do not mix those layers. library/ = what recipes ARE (recipes, actions,
-manifests — the content). runner/ = what EXECUTES them (engine, verify,
-evidence). orchestration/ = what CONTROLS the app and its instances (start,
+manifests — the content). src/ = what EXECUTES them (TypeScript CLI/engine glue,
+typed adapters). adapters/ = what CONTROLS the app and its instances (start,
 windows, wallet state, health, ports, parallel).
 
 ## Useful commands
@@ -83,28 +84,39 @@ mm-harness launch ios                           # launch (mobile: ios | android)
 mm-harness logs                                 # tail Metro/webpack + app logs
 mm-harness debug                                # open the debug console
 mm-harness fixtures sync                        # sync fixtures; `fixtures set` seeds the wallet
+
+# Keep the install current
+mm-harness update                               # upgrade to the published latest (prints old → new)
+mm-harness update --check --json                # report only — { current, latest, updateAvailable }
 ```
 
+A passive once-a-day nudge prints one `stderr` line when a newer version is
+published (`mm-harness <cur> → <latest> available · run: mm-harness update`). It
+never blocks and never auto-updates. Silence it with `MM_HARNESS_NO_UPDATE_CHECK=1`
+(auto-off in CI).
+
 Set `RECIPE_LOG_UI=compact|full|quiet` (default `compact`) and `RECIPE_LOG_EVENTS=10`
 to tune the compact log view during launch and Metro/webpack startup.
 
 ## Layout
 
 ```text
-bin/            CLI and platform convenience commands
-runner/         what EXECUTES recipes: engine glue (runner/src) +
-                per-platform verify (engine, verify, evidence)
-orchestration/  what CONTROLS the app and its instances: launch/live/
+bin/            the mm-harness entrypoint
+src/            what EXECUTES recipes: TypeScript CLI/engine glue +
+                typed per-adapter logic (src/adapters/)
+adapters/       what CONTROLS the app and its instances: launch/live/
                 watch/windows/wallet state/health/inject/cleanup per
-                platform, shared lib, manifest.json + doctor.mjs
+                platform, shared glue, porcelain, overlay payload +
+                manifest.json
 library/        what recipes ARE: recipes/ (recipe JSONs), actions/
                 (per-platform implementations), manifests/ (capability)
-scripts/        dev tooling (yarn check, local farmslot link, e2e validation)
+scripts/        dev tooling (yarn check, local farmslot link, e2e
+                validation, adapter-surface-doctor)
 docs/           details when this README is not enough
 ```
 
 Defaults for installed harness/runtime paths live in
-`orchestration/lib/path-defaults.json`.
+`adapters/shared/path-defaults.json`.
 
 ## Runtime-readiness ownership
 
@@ -114,12 +126,30 @@ Generic readiness mechanics live in `@farmslot/recipe-harness` (0.3+):
 - `@farmslot/recipe-harness/runtime/log-analysis` — bundle-log boundaries, unresolved-module scoping
 - `@farmslot/recipe-harness/runtime/metro-probe` — Metro `/status` reachability
 
-This repo adds **MetaMask adapters only**: `orchestration/mobile/deps-markers.ts`,
-`orchestration/mobile/runtime-decision.ts`, `orchestration/extension/runtime-decision.ts`,
-and shell launch in `orchestration/porcelain/mm-recipe` / `orchestration/porcelain/mme-recipe`. Do not re-copy harness
-primitives into `orchestration/lib/`. CI installs harness from npm — publish
+This repo adds **MetaMask adapters only**: `adapters/mobile/deps-markers.ts`,
+`adapters/mobile/runtime-decision.ts`, `adapters/extension/runtime-decision.ts`,
+and shell launch in `adapters/porcelain/mm-recipe` / `adapters/porcelain/mme-recipe`. Do not re-copy harness
+primitives into `adapters/shared/`. CI installs harness from npm — publish
 `@farmslot/recipe-harness` before bumping the dependency here.
 
+## Dev/prod harness (`MM_HARNESS_BIN`)
+
+The global npm install owns the `mm-harness` on `PATH` — that is the **prod**
+harness. To run a **dev** checkout with active pre-release changes alongside it,
+set `MM_HARNESS_BIN` to that checkout's `bin/mm-harness`:
+
+```bash
+export MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # dev: this checkout owns the run
+unset MM_HARNESS_BIN                                       # prod: the installed/global bin
+```
+
+`MM_HARNESS_BIN` is the single override point: when set, the entrypoint hands the
+whole invocation to that path before doing any dependency work; when unset it
+resolves the installed bin. A dev checkout is never installed globally, so there is
+no `PATH` collision — dev is reached only through `MM_HARNESS_BIN` (or a shell
+alias). A per-farm environment can export it so the dev farm dispatches through the
+dev harness while the prod farm leaves it unset.
+
 ## Runtime notes
 
 - `tmux` is recommended for long-lived Metro/webpack processes; standalone use
@@ -133,8 +163,8 @@ primitives into `orchestration/lib/`. CI installs harness from npm — publish
 
 ```bash
 yarn check
-bash -n bin/mm-harness orchestration/porcelain/{metamask-recipe,mm-recipe,mme-recipe} orchestration/{mobile,extension,core}/*.sh runner/{mobile,extension}/verify.sh
-node --check orchestration/extension/inject.mjs orchestration/extension/cleanup.mjs orchestration/extension/readiness.mjs orchestration/extension/launch-browser.cjs orchestration/lib/open-debug.mjs orchestration/lib/cli-home.mjs orchestration/lib/log-tui.mjs orchestration/lib/progress.mjs orchestration/lib/recipe-paths.mjs scripts/check.mjs
+bash -n bin/mm-harness adapters/porcelain/{metamask-recipe,mm-recipe,mme-recipe} adapters/{mobile,extension,core}/*.sh
+node --check adapters/extension/inject.mjs adapters/extension/cleanup.mjs adapters/extension/readiness.mjs adapters/extension/launch-browser.cjs adapters/shared/open-debug.mjs adapters/shared/cli-home.mjs adapters/shared/log-tui.mjs adapters/shared/progress.mjs adapters/shared/recipe-paths.mjs scripts/check.mjs
 ```
 
 More detail: [Architecture](docs/architecture.md), [Package boundaries](docs/package-boundaries.md), [Runtime file conventions](docs/runtime-file-conventions.md).

package/{orchestration → adapters}/core/cleanup.sh

@@ -23,12 +23,12 @@ done
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET="$(cd "$TARGET" && pwd)"
 # shellcheck disable=SC1091
-for _hp in "$SCRIPT_DIR/../lib/harness-path.sh"; do
+for _hp in "$SCRIPT_DIR/../shared/harness-path.sh"; do
   [ -f "$_hp" ] && { . "$_hp"; break; }
 done
 unset _hp
 if ! command -v harness_root >/dev/null 2>&1; then
-  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  echo "mm-harness: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
 fi
 HARNESS_DIR="$(harness_dir "$TARGET" core)"

package/{orchestration → adapters}/core/inject.sh

@@ -27,12 +27,12 @@ done
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 RUNNER_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd -P)"
 # shellcheck disable=SC1091
-for _hp in "$SCRIPT_DIR/../lib/harness-path.sh"; do
+for _hp in "$SCRIPT_DIR/../shared/harness-path.sh"; do
   [ -f "$_hp" ] && { . "$_hp"; break; }
 done
 unset _hp
 if ! command -v harness_root >/dev/null 2>&1; then
-  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  echo "mm-harness: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
 fi
 TARGET="$(cd "$TARGET" && pwd)"
@@ -81,7 +81,7 @@ install_v1_runner_assets() {
   # break the generated wrapper or inject at runtime.
   local runner_protocol_root_q runner_exec_q
   runner_protocol_root_q="$(printf '%q' "$METAMASK_RUNNER_PROTOCOL_ROOT")"
-  runner_exec_q="$(printf '%q' "$METAMASK_RUNNER_DIR/orchestration/porcelain/metamask-recipe")"
+  runner_exec_q="$(printf '%q' "$METAMASK_RUNNER_DIR/bin/mm-harness")"
   {
     printf '%s\n' '#!/usr/bin/env bash'
     printf '%s\n' 'set -euo pipefail'
@@ -89,8 +89,8 @@ install_v1_runner_assets() {
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
     printf 'exec %s "$@"\n' "$runner_exec_q"
-  } > "$HARNESS_DIR/runner/bin/metamask-recipe"
-  chmod +x "$HARNESS_DIR/runner/bin/metamask-recipe"
+  } > "$HARNESS_DIR/runner/bin/mm-harness"
+  chmod +x "$HARNESS_DIR/runner/bin/mm-harness"
   if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
     printf '%s\n' "$METAMASK_RUNNER_PROTOCOL_ROOT" > "$HARNESS_DIR/runner/.farmslot-root"
   fi
@@ -113,7 +113,7 @@ install_v1_runner_assets() {
   if [ -f "$METAMASK_RUNNER_DIR/library/library.json" ]; then
     cp "$METAMASK_RUNNER_DIR/library/library.json" "$HARNESS_DIR/runner/library.json"
   fi
-  if [ ! -x "$HARNESS_DIR/runner/bin/metamask-recipe" ]; then
+  if [ ! -x "$HARNESS_DIR/runner/bin/mm-harness" ]; then
     echo "Refusing core recipe harness install: failed to make runner executable." >&2
     return 1
   fi
@@ -121,7 +121,7 @@ install_v1_runner_assets() {
 
 install_v1_runner_assets
 
-ENSURE_DEPS="$SCRIPT_DIR/../lib/ensure-runner-deps.sh"
+ENSURE_DEPS="$SCRIPT_DIR/../shared/ensure-runner-deps.sh"
 if [ -f "$ENSURE_DEPS" ]; then
   bash "$ENSURE_DEPS" "$RUNNER_DIR"
 fi
@@ -142,7 +142,7 @@ node -e '
     target,
     protocolVersion: "v1",
     actionManifestPath: harnessRel + "/action-manifest.json",
-    runnerEntrypoint: harnessRel + "/runner/bin/metamask-recipe",
+    runnerEntrypoint: harnessRel + "/runner/bin/mm-harness",
     runtimeHelpers: {},
     installedPaths: [harnessRel + "/runner"],
     patchedFiles: [],

package/{orchestration → adapters}/extension/cleanup.mjs

@@ -18,7 +18,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import process from 'node:process';
-import { recipeHarnessRoot } from '../lib/recipe-paths.mjs';
+import { recipeHarnessRoot } from '../../src/paths.ts';
 
 function usage() { console.error('Usage: cleanup-extension-harness.mjs [--target <metamask-extension>]'); }
 let target = process.cwd();

package/{orchestration → adapters}/extension/console-tail.mjs

@@ -62,6 +62,9 @@ const attached = new Map();
 // before ever connecting, so a dead/non-debuggable target is not retried every poll).
 const cooldown = new Map();
 
+// Writes formatted console-event strings (never raw HTTP response bodies) to
+// stdout and optionally to a caller-supplied log file. The source is the local
+// Chrome CDP WebSocket (127.0.0.1:<cdpPort>) — a trusted-local endpoint.
 function out(line) {
   process.stdout.write(`${line}\n`);
   if (args.log) appendFileSync(args.log, `${line}\n`);

package/{orchestration → adapters}/extension/ensure-browser.sh

@@ -58,12 +58,12 @@ done
 # Script lives at <repo>/<runtime_dir>/reopen-browser.sh
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck disable=SC1091
-for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
   [ -f "$_hp" ] && { . "$_hp"; break; }
 done
 unset _hp
 if ! command -v harness_root >/dev/null 2>&1; then
-  echo "reopen-browser: shared lib orchestration/lib/harness-path.sh missing; reinstall the harness." >&2
+  echo "reopen-browser: shared lib adapters/shared/harness-path.sh missing; reinstall the harness." >&2
   exit 1
 fi
 if [[ -z "$RUNTIME_DIR" ]]; then
@@ -118,7 +118,7 @@ WALLET_FIXTURE="${AGENT_DIR}/wallet-fixture.json"
 # single source of truth (deterministic id from the loaded dist's manifest key).
 # Honor the configured recipe harness root.
 HARNESS_ROOT="$(harness_root)"
-RUNNER_BIN="${REPO}/${HARNESS_ROOT}/extension/runner/bin/metamask-recipe"
+RUNNER_BIN="${REPO}/${HARNESS_ROOT}/extension/runner/bin/mm-harness"
 
 # --- Preflight checks ---
 if [ ! -f "${EXTENSION}/manifest.json" ]; then
@@ -134,7 +134,7 @@ fi
 
 if [ ! -f "${PROFILE}/Default/Preferences" ]; then
   echo "FAIL: existing browser profile not found at ${PROFILE}"
-  echo "  Reopen only reuses an already-prepared profile. Run: metamask-recipe runtime-launch --adapter extension --target ${REPO} --cdp-port ${CDP_PORT} --chrome-user-data-dir ${PROFILE} --json"
+  echo "  Reopen only reuses an already-prepared profile. Run: mm-harness runtime-launch --adapter extension --target ${REPO} --cdp-port ${CDP_PORT} --chrome-user-data-dir ${PROFILE} --json"
   exit 1
 fi
 

package/{orchestration → adapters}/extension/inject.mjs

@@ -23,7 +23,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import process from 'node:process';
-import { recipeHarnessRoot } from '../lib/recipe-paths.mjs';
+import { recipeHarnessRoot } from '../../src/paths.ts';
 
 function usage() {
   console.error('Usage: inject-extension-harness.mjs [--target <metamask-extension>] [--no-git-exclude]');
@@ -72,9 +72,9 @@ const delegate = [
   '#!/usr/bin/env bash',
   'set -euo pipefail',
   protocolRoot ? `export FARMSLOT_ROOT=\${FARMSLOT_ROOT:-${shellQuote(protocolRoot)}}` : null,
-  `exec ${shellQuote(path.join(runnerDir, 'orchestration/porcelain/metamask-recipe'))} "$@"`,
+  `exec ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} "$@"`,
 ].filter(Boolean).join('\n') + '\n';
-fs.writeFileSync(path.join(harnessDir, 'runner/bin/metamask-recipe'), delegate, { mode: 0o755 });
+fs.writeFileSync(path.join(harnessDir, 'runner/bin/mm-harness'), delegate, { mode: 0o755 });
 if (protocolRoot) fs.writeFileSync(path.join(harnessDir, 'runner/.farmslot-root'), `${protocolRoot}\n`);
 fs.writeFileSync(path.join(harnessDir, 'runner/.runner-source'), `${runnerDir}\n`);
 copyFile(path.join(runnerDir, 'library/manifests/mobile.action-manifest.json'), path.join(harnessDir, 'runner/manifests/mobile.action-manifest.json'));
@@ -89,36 +89,32 @@ copyDir(path.join(runnerDir, 'library/flows'), path.join(harnessDir, 'runner/flo
 // Installed-layout back-compat (INTENTIONAL): targets keep a flat
 // <harness>/scripts/ subtree assembled from the runner trees, so installed
 // consumers are unaffected by runner-repo layout changes.
-copyFile(path.join(runnerDir, 'orchestration/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-browser.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-browser.cjs'));
 // installed back-compat alias: callers of the pre-rename installed name
-copyFile(path.join(runnerDir, 'orchestration/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-chrome-detached.cjs'));
-copyFile(path.join(runnerDir, 'orchestration/extension/console-tail.mjs'), path.join(harnessDir, 'scripts/console-tail.mjs'));
-copyFile(path.join(runnerDir, 'orchestration/extension/launch.sh'), path.join(harnessDir, 'scripts/launch.sh'));
-copyFile(path.join(runnerDir, 'orchestration/extension/live.sh'), path.join(harnessDir, 'scripts/live.sh'));
-copyFile(path.join(runnerDir, 'orchestration/extension/start-watch.sh'), path.join(harnessDir, 'scripts/start-watch.sh'));
-copyFile(path.join(runnerDir, 'orchestration/extension/snapshot-dist.sh'), path.join(harnessDir, 'scripts/snapshot-dist.sh'));
-copyFile(path.join(runnerDir, 'orchestration/extension/pin-remote-flags.cjs'), path.join(harnessDir, 'scripts/pin-remote-flags.cjs'));
-copyFile(path.join(runnerDir, 'orchestration/extension/seed-fixture.sh'), path.join(harnessDir, 'scripts/seed-fixture.sh'));
-copyFile(path.join(runnerDir, 'orchestration/extension/sidepanel-toggle.sh'), path.join(harnessDir, 'scripts/sidepanel-toggle.sh'));
-copyFile(path.join(runnerDir, 'orchestration/extension/readiness.mjs'), path.join(harnessDir, 'scripts/readiness.mjs'));
-copyFile(path.join(runnerDir, 'orchestration/extension/wallet-fixture-state.cjs'), path.join(harnessDir, 'scripts/wallet-fixture-state.cjs'));
-copyFile(path.join(runnerDir, 'runner/extension/verify.sh'), path.join(harnessDir, 'scripts/verify.sh'));
-copyFile(path.join(runnerDir, 'orchestration/extension/refresh-build.sh'), path.join(harnessDir, 'scripts/refresh-build.sh'));
-copyFile(path.join(runnerDir, 'orchestration/extension/ensure-browser.sh'), path.join(harnessDir, 'scripts/reopen-browser.sh'));
-copyFile(path.join(runnerDir, 'orchestration/lib/harness-path.sh'), path.join(harnessDir, 'scripts/lib/harness-path.sh'));
-copyFile(path.join(runnerDir, 'orchestration/lib/activate-repo-node.sh'), path.join(harnessDir, 'scripts/lib/activate-repo-node.sh'));
-copyFile(path.join(runnerDir, 'orchestration/lib/resolve-farmslot-ports.sh'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports.sh'));
-copyFile(path.join(runnerDir, 'orchestration/lib/path-defaults.json'), path.join(harnessDir, 'scripts/lib/path-defaults.json'));
-copyFile(path.join(runnerDir, 'orchestration/lib/recipe-paths.mjs'), path.join(harnessDir, 'scripts/lib/recipe-paths.mjs'));
-copyFile(path.join(runnerDir, 'orchestration/lib/json-field.sh'), path.join(harnessDir, 'scripts/lib/json-field.sh'));
-copyFile(path.join(runnerDir, 'orchestration/lib/cli-color.mjs'), path.join(harnessDir, 'scripts/lib/cli-color.mjs'));
-copyFile(path.join(runnerDir, 'orchestration/lib/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
-copyFile(path.join(runnerDir, 'orchestration/lib/progress.mjs'), path.join(harnessDir, 'scripts/lib/progress.mjs'));
-copyFile(path.join(runnerDir, 'orchestration/lib/cli-version.mjs'), path.join(harnessDir, 'scripts/lib/cli-version.mjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-chrome-detached.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/console-tail.mjs'), path.join(harnessDir, 'scripts/console-tail.mjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/launch.sh'), path.join(harnessDir, 'scripts/launch.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/live.sh'), path.join(harnessDir, 'scripts/live.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/start-watch.sh'), path.join(harnessDir, 'scripts/start-watch.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/snapshot-dist.sh'), path.join(harnessDir, 'scripts/snapshot-dist.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/pin-remote-flags.cjs'), path.join(harnessDir, 'scripts/pin-remote-flags.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/seed-fixture.sh'), path.join(harnessDir, 'scripts/seed-fixture.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/sidepanel-toggle.sh'), path.join(harnessDir, 'scripts/sidepanel-toggle.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/readiness.mjs'), path.join(harnessDir, 'scripts/readiness.mjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/wallet-fixture-state.cjs'), path.join(harnessDir, 'scripts/wallet-fixture-state.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/verify.sh'), path.join(harnessDir, 'scripts/verify.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/refresh-build.sh'), path.join(harnessDir, 'scripts/refresh-build.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/ensure-browser.sh'), path.join(harnessDir, 'scripts/reopen-browser.sh'));
+copyFile(path.join(runnerDir, 'adapters/shared/harness-path.sh'), path.join(harnessDir, 'scripts/lib/harness-path.sh'));
+copyFile(path.join(runnerDir, 'adapters/shared/activate-repo-node.sh'), path.join(harnessDir, 'scripts/lib/activate-repo-node.sh'));
+copyFile(path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports.sh'));
+copyFile(path.join(runnerDir, 'adapters/shared/path-defaults.json'), path.join(harnessDir, 'scripts/lib/path-defaults.json'));
+copyFile(path.join(runnerDir, 'adapters/shared/json-field.sh'), path.join(harnessDir, 'scripts/lib/json-field.sh'));
+copyFile(path.join(runnerDir, 'adapters/shared/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
 makeExecutableTree(path.join(harnessDir, 'scripts'));
 fs.writeFileSync(path.join(harnessDir, 'installed-scripts.sha256'), `${dirContentHash(path.join(harnessDir, 'scripts'))}\n`);
 
-const cleanupScript = path.join(runnerDir, 'orchestration/extension/cleanup.mjs');
+const cleanupScript = path.join(runnerDir, 'adapters/extension/cleanup.mjs');
 const cleanupCommand = `RECIPE_HARNESS_ROOT=${harnessRoot} ${shellQuote(cleanupScript)} --target ${shellQuote(target)}`;
 const manifest = {
   adapter: 'extension',
@@ -132,7 +128,7 @@ const manifest = {
   target,
   protocolVersion: 'v1',
   actionManifestPath: `${harnessRel}/action-manifest.json`,
-  runnerEntrypoint: `${harnessRel}/runner/bin/metamask-recipe`,
+  runnerEntrypoint: `${harnessRel}/runner/bin/mm-harness`,
   installedPaths: [`${harnessRel}/scripts`, `${harnessRel}/runner`, `${harnessRel}/action-manifest.json`, `${harnessRel}/manifest.json`],
   runtimeHelpers: {
     live: `${harnessRel}/scripts/live.sh`,
@@ -149,7 +145,7 @@ fs.writeFileSync(path.join(harnessDir, 'manifest.json'), `${JSON.stringify(manif
 
 if (gitExclude) addGitExclude(target, `${harnessRoot}/`, harnessDir);
 
-const ensureDeps = path.join(runnerDir, 'orchestration/lib/ensure-runner-deps.sh');
+const ensureDeps = path.join(runnerDir, 'adapters/shared/ensure-runner-deps.sh');
 if (fs.existsSync(ensureDeps)) {
   const ensured = spawnSync('bash', [ensureDeps, runnerDir], { stdio: 'inherit' });
   if (ensured.status !== 0) process.exit(ensured.status ?? 1);

package/{orchestration → adapters}/extension/launch.sh

@@ -45,12 +45,12 @@ fi
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
-for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
   [ -f "$_hp" ] && { . "$_hp"; break; }
 done
 unset _hp
 if ! command -v harness_root >/dev/null 2>&1; then
-  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  echo "mm-harness: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
 fi
 READINESS_MJS="$SCRIPT_DIR/readiness.mjs"
@@ -64,12 +64,12 @@ ARTIFACTS="${ARTIFACTS:-$HARNESS_DIR/launch/$(date -u +%Y%m%dT%H%M%SZ)}"
 mkdir -p "$ARTIFACTS/logs"
 
 if [ ! -f "$HARNESS_DIR/manifest.json" ]; then
-  echo "Extension recipe harness is not installed in $TARGET. Run metamask-recipe extension prepare --target $TARGET first." >&2
+  echo "Extension recipe harness is not installed in $TARGET. Run mm-harness install --adapter extension --target $TARGET first." >&2
   exit 1
 fi
 
 LIB_DIR=""
-for _lib in "$SCRIPT_DIR/lib" "$SCRIPT_DIR/../lib"; do
+for _lib in "$SCRIPT_DIR/lib" "$SCRIPT_DIR/../shared"; do
   [ -f "$_lib/log-tui.mjs" ] && LIB_DIR="$_lib" && break
 done
 unset _lib

package/{orchestration → adapters}/extension/live.sh

@@ -68,18 +68,18 @@ esac
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
-for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
   [ -f "$_hp" ] && { . "$_hp"; break; }
 done
 unset _hp
 if ! command -v harness_root >/dev/null 2>&1; then
-  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  echo "mm-harness: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
 fi
 # verify.sh is a recipe-tree feature: co-located in installed copies, under
-# runner/extension in a repo checkout.
+# adapters/extension in a repo checkout.
 VERIFY_SH=""
-for _v in "$SCRIPT_DIR/verify.sh" "$SCRIPT_DIR/../../runner/extension/verify.sh"; do
+for _v in "$SCRIPT_DIR/verify.sh" "$SCRIPT_DIR/../../adapters/extension/verify.sh"; do
   [ -f "$_v" ] && { VERIFY_SH="$_v"; break; }
 done
 unset _v
@@ -92,7 +92,7 @@ RUNTIME_DIR="$(recipe_runtime_dir)"
 # Runner bin (installed wrapper → source runner). Used by the watch prepare path
 # to defer the cache-clear DECISION to `runtime-decision` (single source) and to
 # record the deps/cache baseline after a confirmed-good build.
-RUNNER_BIN="$(harness_dir "$TARGET" extension)/runner/bin/metamask-recipe"
+RUNNER_BIN="$(harness_dir "$TARGET" extension)/runner/bin/mm-harness"
 OUT="${OUT:-$(harness_root)/extension/runner/recipes}"
 ARTIFACTS="${ARTIFACTS:-$(harness_dir "$TARGET" extension)/live/$(date -u +%Y%m%dT%H%M%SZ)}"
 mkdir -p "$ARTIFACTS/logs"

package/{orchestration → adapters}/extension/readiness.mjs

@@ -26,8 +26,8 @@ const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 function pathDefault(key) {
   for (const candidate of [
     path.join(scriptDir, 'lib/path-defaults.json'),
-    path.join(scriptDir, '../lib/path-defaults.json'),
-    path.join(scriptDir, '../../orchestration/lib/path-defaults.json'),
+    path.join(scriptDir, '../shared/path-defaults.json'),
+    path.join(scriptDir, '../../adapters/shared/path-defaults.json'),
   ]) {
     if (!fs.existsSync(candidate)) continue;
     const value = JSON.parse(fs.readFileSync(candidate, 'utf8'))[key];
@@ -110,7 +110,16 @@ function writeExtensionId(target, extensionId) {
   return true;
 }
 
+// All callers target the local Chrome CDP endpoint (127.0.0.1:<cdpPort>).
+// Validate before requesting so file-derived data cannot redirect to a remote host.
+function assertLocalUrl(url) {
+  if (!/^http:\/\/127\.0\.0\.1:\d+\//u.test(url)) {
+    throw new Error(`readiness: refusing non-local URL: ${url}`);
+  }
+}
+
 function httpJson(url, timeoutMs = 3000) {
+  assertLocalUrl(url);
   return new Promise((resolve, reject) => {
     const req = http.get(url, (res) => {
       let data = '';
@@ -134,6 +143,7 @@ function httpJson(url, timeoutMs = 3000) {
 }
 
 function httpJsonRequest(method, url, timeoutMs = 3000) {
+  assertLocalUrl(url);
   return new Promise((resolve, reject) => {
     const req = http.request(url, { method }, (res) => {
       let data = '';

package/{orchestration → adapters}/extension/refresh-build.sh

@@ -85,7 +85,7 @@ fi
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
-for _arn in "$SCRIPT_DIR/lib/activate-repo-node.sh" "$SCRIPT_DIR/../lib/activate-repo-node.sh"; do
+for _arn in "$SCRIPT_DIR/lib/activate-repo-node.sh" "$SCRIPT_DIR/../shared/activate-repo-node.sh"; do
   [ -f "$_arn" ] && { . "$_arn"; break; }
 done
 unset _arn

package/{orchestration → adapters}/extension/seed-fixture.sh

@@ -115,7 +115,7 @@ resolve_fixture_script() {
 if [ "$SUBCOMMAND" = resolve ]; then
   RUNTIME_DIR=""
   # shellcheck disable=SC1091
-  for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+  for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
     [ -f "$_hp" ] && { . "$_hp"; break; }
   done
   unset _hp

package/{orchestration → adapters}/extension/start-watch.sh

@@ -9,7 +9,7 @@
 #
 # Inputs (flags / env):
 #   --target <metamask-extension> (default $PWD; becomes the working dir)
-#   --runtime-dir <rel> (default from orchestration/lib path-defaults)
+#   --runtime-dir <rel> (default from adapters/shared path-defaults)
 #   --watcher-port <port> (default env WATCHER_PORT/RECIPE_WATCHER_PORT,
 #     runtime json, or slot suffix e.g. metamask-extension-1 => 9011)
 #   --runner-bin <path> (optional; records deps/cache baseline best-effort)
@@ -48,18 +48,18 @@ done
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
-for _arn in "$SCRIPT_DIR/lib/activate-repo-node.sh" "$SCRIPT_DIR/../lib/activate-repo-node.sh"; do
+for _arn in "$SCRIPT_DIR/lib/activate-repo-node.sh" "$SCRIPT_DIR/../shared/activate-repo-node.sh"; do
   [ -f "$_arn" ] && { . "$_arn"; break; }
 done
 unset _arn
 if [ -z "$RUNTIME_DIR" ]; then
   # shellcheck disable=SC1091
-  for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../lib/harness-path.sh"; do
+  for _hp in "$SCRIPT_DIR/lib/harness-path.sh" "$SCRIPT_DIR/../shared/harness-path.sh"; do
     [ -f "$_hp" ] && { . "$_hp"; break; }
   done
   unset _hp
   if ! command -v recipe_runtime_dir >/dev/null 2>&1; then
-    echo "start-watch: shared lib orchestration/lib/harness-path.sh not found; pass --runtime-dir." >&2
+    echo "start-watch: shared lib adapters/shared/harness-path.sh not found; pass --runtime-dir." >&2
     exit 1
   fi
   RUNTIME_DIR="$(recipe_runtime_dir)"
@@ -67,7 +67,7 @@ fi
 
 cd "$TARGET"
 REPO_NODE_PATH_PREFIX=""
-for _arn in "$SCRIPT_DIR/lib/activate-repo-node.sh" "$SCRIPT_DIR/../lib/activate-repo-node.sh"; do
+for _arn in "$SCRIPT_DIR/lib/activate-repo-node.sh" "$SCRIPT_DIR/../shared/activate-repo-node.sh"; do
   [ -f "$_arn" ] && { # shellcheck disable=SC1090
     . "$_arn"
     break
@@ -182,7 +182,7 @@ slot_number() {
 
 # Explicit clean-build path: clear the target-scoped webpack cache before
 # starting the harness-owned watcher. Faster incremental refresh stays on
-# `mme-recipe refresh`; this script is for proving a clean build works.
+# `mm-harness refresh`; this script is for proving a clean build works.
 echo '[recipe-harness] clean build: clearing webpack cache + harness watcher'
 rm -rf node_modules/.cache/webpack
 killed_harness_pid=""
@@ -228,7 +228,7 @@ watch_log="$RUNTIME_DIR/recipe-harness-webpack.log"
 rm -f "$watch_pid_file"
 : > "$watch_log"
 LIB_DIR=""
-for _lib in "$SCRIPT_DIR/lib" "$SCRIPT_DIR/../lib"; do
+for _lib in "$SCRIPT_DIR/lib" "$SCRIPT_DIR/../shared"; do
   [ -f "$_lib/log-tui.mjs" ] && LIB_DIR="$_lib" && break
 done
 unset _lib