@deeeed/metamask-harness 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.6.0 - 2026-07-06
+
+Minor release: CLI hardening (decomposed, single-parser, dist-only) plus a
+fresh-slot validation wave — every fix proven live on untouched -2 slots and
+independently cross-reviewed.
+
+### Changed
+- **CLI decomposition + dist-only publish** — `src/cli.ts` is parse+dispatch only;
+  handlers under `src/commands/<verb>.ts`; one commander parser; the npm tarball
+  ships compiled `dist/` without `src/` and `tsx` is a devDependency (plain-node,
+  smaller, faster). Source checkouts keep the tsx dev path (`MM_HARNESS_BIN`).
+- `verify` auto-ensures its own overlay (no refusal on a fresh checkout); every
+  engine execution resolves the slot's ports/device first (call/run/fixtures get
+  the same slot isolation launch has).
+
+### Added
+- **`stop` reaps leaked Metro bundlers by checkout** (port-agnostic, path-
+  boundary matched), `doctor` surfaces any orphan and teaches the reap.
+- **`launch --url <dapp>`** (extension) opens the dapp in the main tab beside the
+  MetaMask sidepanel; `--stop-only` profile release before seed; stable per-checkout
+  Chrome profile + runtime-dist; post-open tab cleanup.
+- DX: run-mode + stale-`dist` warning in `bin`; overlay-delegation notice; docs/CODE-MAP.md.
+
+### Fixed
+- `launch` targets the slot's own simulator (never the `booted` alias) and boots it;
+  slot-port resolution layers rungs so a partial rung never nulls the port; provision
+  resolves the simulator from the pool and boots before install.
+- `call` works from published installs (dist bridge, no type-strip crash);
+  `ensure_unlocked` fails teaching `fixtures set` on an un-onboarded wallet instead
+  of vacuously passing (mobile + extension); `provision --json` usage errors emit the
+  standard envelope; deps-not-ready teaches a command that works on a bare checkout.
 ## 0.5.1 - 2026-07-05
 
 Fresh-install hotfixes found in live validation of 0.5.0.
@@ -11,7 +42,12 @@ Fresh-install hotfixes found in live validation of 0.5.0.
 
 ## Unreleased
 
+### Fixed
+- **`provision --json` adapter-detection failures emit the standard error envelope** — usage errors now match `doctor`/`launch` (envelope on stdout with `error.userAction`; stderr stays human-only). Previously `--json` callers got empty stdout.
+
 ### Changed
+- **CLI decomposition** — `src/cli.ts` is parse+dispatch only; handlers live under `src/commands/<verb>.ts`; `provision` routes through `src/commands/provision.ts` (not overlay harness dispatch); launch composition splits under `src/commands/launch/`; commander owns per-command `--help` (no hand-rolled interception).
+- **Published tarball is dist-only** — `files` no longer ships `src/`; `tsx` is a devDependency; `bin/mm-harness` and overlay leaves resolve `dist/*.js` (teaching error if a published install lacks `dist/`). Library actions keep importing `library/actions/harness-exports.mjs` (dist-preferring narrow bridge from 0.5.1); package exports remain for external consumers (`dist/index.js` published; `src/index.ts` when `--conditions=development` and dist is absent).
 - **resolve-farmslot-ports is TypeScript-first** — pool/context/formula port resolution lives in self-contained `adapters/shared/resolve-farmslot-ports-core.mjs` (works from runner and injected overlay copies); `src/adapters/resolve-farmslot-ports.ts` re-exports it for `slot-ports.ts`. `resolve-farmslot-ports.mjs` is the node leaf; `resolve-farmslot-ports.sh` remains a thin bash-compat wrapper for sourced callers.
 
 ## 0.5.0 - 2026-07-05
@@ -54,20 +90,7 @@ Minor release: the adapter-surface architecture plus the day's feature wave (0.3
 - **Colored grouped help with DEV OVERRIDE banner and SLOT line**; `mmdev-harness` completions; outcome-stating launch summaries with a `[dev]` marker.
 - **docs/UX-PRINCIPLES.md** — the CLI interaction contract (human surface rules; `--json` envelope purity is exempt and inviolable).
 
-## Unreleased
-
-### Added
-- Add `mm-harness provision` for thin mobile Runway artifact provisioning with a shared integrity-checked cache and simulator install path.
-- Add `mm-harness provision runway ios --resolve-only` to return Runway run/revision/artifact metadata without touching simulator, cache, download, install, or baseline state.
-- **Dist publish path** — `npm run build` compiles `src/` to `dist/`; `npm pack` / global install runs the compiled CLI entry (`dist/mm-harness-cli.js`) while a source checkout without `dist/` keeps the tsx+src dev path. Contracts: `packaging-dist-install`, `packaging-dev-checkout`.
-
-### Changed
-- **Leaf stderr hints use mm-harness verbs** — Metro/webpack compact-log prefixes, log-tail hints, and speed-ladder copy now point at `mm-harness logs`, `mm-harness doctor`, `mm-harness launch`, and `mm-harness install` instead of retired `recipe *` commands. Contract: `leaf-branding-retired`.
-
 ### Fixed
-- `mm-harness provision runway ios` now routes through the same Runway provisioning surface as `install --runway`, so overlay dispatch accepts the compatibility command instead of rejecting it as an unsupported harness action.
-- Runway provisioning now accepts farm context flags (`--slot`, `--watcher-port`, `--runtime-dir`), records slot/watcher/runtime-dir baselines correctly, ignores stale provision baselines unless the app is still installed on the simulator, and emits rerunnable `Next:` commands from the actual invocation.
-- Runway iOS artifact extraction now handles the live nested zip layout and app bundle names other than `MetaMask.app` while keeping the cached app directory integrity hash/size contract.
 - **Mobile preflight no longer re-runs `yarn setup` on every launch** — the deps readiness decision escalated an mtime hint to `stale` and ran the FULL `yarn setup` (submodules + inpage bridge + jetify + pods) inside the launch phase on every invocation in orchestrated (farmslot) contexts. `depsCheck` reports `stale` for a no-baseline checkout whenever a manifest is newer than the install markers; the orchestrator's git phase refreshes tracked-file mtimes on every sync while its deps phase leaves `node_modules` untouched, so "manifest newer than markers" is normal and not proof of drift — yet it duplicated the orchestrator's deps work and turned a fast preflight into 15+ minutes (the behavior that also looked like a hang before 0.3.8's streaming). **Presence is now authoritative:** without a recorded baseline an mtime-only `stale` is trusted as `current` (with a one-line stderr warning), so a churned-but-present checkout launches with zero `yarn` in both tiers. Genuine drift is still caught by the recorded-baseline fingerprint. `mm-harness launch` (quick tier / no `--build`) also dropped `preflightMode` before deciding, so the fast contract never took effect; it is threaded through now.
 - **Fast tier never installs; genuine gaps teach the orchestrator** — in the fast tier (quick launch / orchestrated), deps that genuinely need work (absent markers, an absent required package, a fingerprint drift, or Metro unable to resolve a module) return a teaching block naming the orchestrator deps/prepare phase (plus the standalone `yarn setup:expo` / `launch --build` remedies) instead of an implicit setup — deps are the orchestrator's contract. The standalone/full tier still installs.
 - **Deps baseline recorded the instant a setup leaf succeeds** — `prepareMobile` records the deps fingerprint baseline immediately after any successful `yarn-setup`, unconditionally (previously only a later `record: true` re-decide did, gated on the original decision being `install` and on `RECIPE_UP_INSTALL_ATTEMPTED`). Genuine-drift detection is fingerprint-based and self-sustaining after one good install.
@@ -153,7 +176,7 @@ Minor release: the adapter-surface architecture plus the day's feature wave (0.3
 - Core run teaches the correct next step when no account is set.
 - Resolved CodeQL alerts (insecure temp dir, file-access-to-http).
 
-## Unreleased
+## 0.2.0 - 2026-07-03
 
 ### Added
 
@@ -164,12 +187,6 @@ Minor release: the adapter-surface architecture plus the day's feature wave (0.3
 ### 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
-
 - **Docs realigned to the shipped single-bin surface**: `README.md`, `docs/harness-cli.md` (reduced to a pointer at `CLI-SPEC.md`), `docs/recipe-libraries.md`, `docs/extension-runtime-commands.md`, `docs/package-boundaries.md`, and `docs/live-adapter-contract.md` no longer teach the retired `metamask-recipe`/`mm-recipe`/`mme-recipe` names or "planned/stub" daily-loop claims — every command example is `mm-harness`. (`docs/MENTAL-MODEL.md` and `docs/CLI-SPEC.md` retain the old names by design: they are the before→after migration contract.)
 - **Published package trimmed to runtime needs**: the `files` field drops dev-only helpers (`scripts/check.mjs`, `scripts/quality/`, `scripts/link-local-farmslot.mjs`, `scripts/validate-action-e2e-artifacts.mjs`) and repo-dev docs (`AGENTS.md`, `CLAUDE.md`), keeping `bin`, `runner`, `orchestration`, `library`, the runtime completion scripts, `docs`, `README.md`, and `CHANGELOG.md`. The `files` field now also negates `scripts/README.md` (dev-only) so the published tarball no longer ships it alongside the two runtime completion scripts.
 - **Comment-hygiene guard extended**: `scripts/quality/comment-hygiene.mjs` now also fails on presentation vocabulary (`verb`/`daily`) in comments and object-property keys (previously only filenames and declarations), enforced with word boundaries so `verbatim`/`verbose` and user-facing help titles like `DAILY LOOP` stay exempt. Source comments and the `verb: 'rebuild'` progress field were reworded/renamed to `command`.

package/adapters/core/inject.sh

@@ -88,6 +88,7 @@ install_v1_runner_assets() {
     if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
+    printf 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ "$MM_HARNESS_BIN" != %s ]; then echo "mm-harness overlay: %s: %s (reinstall to repoint: mm-harness install)" >&2; fi\n' "$runner_exec_q" 'delegating to the runner pinned at install time' "$runner_exec_q"
     printf 'exec %s "$@"\n' "$runner_exec_q"
   } > "$HARNESS_DIR/runner/bin/mm-harness"
   chmod +x "$HARNESS_DIR/runner/bin/mm-harness"

package/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 '../../src/paths.ts';
+import { recipeHarnessRoot } from '../shared/recipe-harness-root.mjs';
 
 function usage() { console.error('Usage: cleanup-extension-harness.mjs [--target <metamask-extension>]'); }
 let target = process.cwd();

package/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 '../../src/paths.ts';
+import { recipeHarnessRoot } from '../shared/recipe-harness-root.mjs';
 
 function usage() {
   console.error('Usage: inject-extension-harness.mjs [--target <metamask-extension>] [--no-git-exclude]');
@@ -72,6 +72,7 @@ const delegate = [
   '#!/usr/bin/env bash',
   'set -euo pipefail',
   protocolRoot ? `export FARMSLOT_ROOT=\${FARMSLOT_ROOT:-${shellQuote(protocolRoot)}}` : null,
+  `if [ -n "\${MM_HARNESS_BIN:-}" ] && [ "\$MM_HARNESS_BIN" != ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} ]; then echo "mm-harness overlay: delegating to the runner pinned at install time: ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} (reinstall to repoint: mm-harness install)" >&2; fi`,
   `exec ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} "$@"`,
 ].filter(Boolean).join('\n') + '\n';
 fs.writeFileSync(path.join(harnessDir, 'runner/bin/mm-harness'), delegate, { mode: 0o755 });

package/adapters/extension/launch-browser.cjs

@@ -39,9 +39,13 @@ if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
 for (const key of ['chrome-bin', 'profile', 'extension-dir', 'chrome-log', 'chrome-pid']) {
   if (!args[key]) throw new Error(`Missing --${key}`);
 }
-if (!fs.existsSync(args['chrome-bin'])) throw new Error(`Chrome binary not found: ${args['chrome-bin']}`);
-if (!fs.existsSync(path.join(args['extension-dir'], 'manifest.json'))) {
-  throw new Error(`Extension dist manifest not found: ${path.join(args['extension-dir'], 'manifest.json')}`);
+// --stop-only releases the profile before the dist snapshot exists on a first
+// run, so launch-input validation applies only to a real launch.
+if (args['stop-only'] === undefined) {
+  if (!fs.existsSync(args['chrome-bin'])) throw new Error(`Chrome binary not found: ${args['chrome-bin']}`);
+  if (!fs.existsSync(path.join(args['extension-dir'], 'manifest.json'))) {
+    throw new Error(`Extension dist manifest not found: ${path.join(args['extension-dir'], 'manifest.json')}`);
+  }
 }
 
 // Isolation guard: a standalone launch must use a per-checkout profile, never a
@@ -72,6 +76,14 @@ if (previousPid !== null && processLoadsProfile(previousPid, args.profile)) owne
 terminatePids([...ownedPids]);
 removeProfileSingletonLocks(args.profile);
 
+// --stop-only: release the profile (owned Chrome terminated, singleton locks
+// cleared) without launching. The prefill step needs the profile's LevelDB
+// unlocked BEFORE it writes; a prior run's Chrome would hold the lock and the
+// write fails with "Database is not open".
+if (args['stop-only'] !== undefined) {
+  process.exit(0);
+}
+
 const logFd = fs.openSync(args['chrome-log'], 'a');
 let child;
 try {
@@ -88,7 +100,9 @@ try {
     '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
     `--disable-extensions-except=${args['extension-dir']}`,
     `--load-extension=${args['extension-dir']}`,
-    'chrome://extensions/',
+    // Initial tab: the caller's dapp URL when provided (sidepanel demos pair the
+    // extension sidepanel with a dapp in the main tab), else the extensions page.
+    args['start-url'] || 'chrome://extensions/',
   ], {
     detached: true,
     env: {

package/adapters/extension/live.sh

@@ -50,6 +50,7 @@ while [ "$#" -gt 0 ]; do
     --artifacts-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; ARTIFACTS="$2"; shift 2 ;;
     --prepare-cmd) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; PREPARE_CMD="$2"; shift 2 ;;
     --launch-existing-dist) LAUNCH_EXISTING_DIST=true; shift ;;
+    --start-url) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; START_URL="$2"; shift 2 ;;
     --start-watch|--start-test-watch) START_WATCH=true; LAUNCH_EXISTING_DIST=true; shift ;;
     --dist-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; DIST_DIR="$2"; shift 2 ;;
     --chrome-user-data-dir) [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; CHROME_USER_DATA_DIR="$2"; shift 2 ;;
@@ -114,8 +115,15 @@ fi
 
 if $LAUNCH_EXISTING_DIST && [ -z "$PREPARE_CMD" ]; then
   DIST_ABS="$TARGET/$DIST_DIR"
-  RUNTIME_DIST_ABS="$ARTIFACTS/runtime-dist"
-  PROFILE_ABS="${CHROME_USER_DATA_DIR:-$ARTIFACTS/chrome-profile}"
+  # Stable beside the profile: the reused profile registers the unpacked
+  # extension by PATH; a per-run snapshot path gets pruned and the next launch
+  # loads nothing ("No EIP-6963 Provider Detected").
+  RUNTIME_DIST_ABS="$TARGET/temp/recipe/runtime/runtime-dist"
+  # Stable per-checkout profile: successive runs recognize their own Chrome
+  # (ownership guard matches on --user-data-dir), take it over cleanly, and the
+  # seeded wallet persists across relaunches. A per-run profile made every
+  # relaunch "foreign" and let live/ pruning delete profiles still in use.
+  PROFILE_ABS="${CHROME_USER_DATA_DIR:-$TARGET/temp/recipe/runtime/chrome-profile}"
   FIXTURE_STATE_ABS="$ARTIFACTS/fixture-state.json"
   FIXTURE_VALIDATION_ABS="$ARTIFACTS/logs/fixture-account-parity.json"
   # Wallet fixture resolution chain + provenance live in seed-fixture.sh.
@@ -233,6 +241,7 @@ NODE
   if $START_WATCH; then
     prepare_parts+=("bash ${quoted_start_watch} --runtime-dir ${quoted_runtime_dir} --runner-bin ${quoted_runner}")
   fi
+  prepare_parts+=("node ${quoted_chrome_launcher} --stop-only 1 --chrome-bin ${quoted_chrome} --profile ${quoted_profile} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --chrome-log ${quoted_chrome_log} --chrome-pid ${quoted_chrome_pid}")
   prepare_parts+=("bash ${quoted_snapshot_dist} --dist ${quoted_dist} --runtime-dist ${quoted_runtime_dist}")
   # Optional A/B feature-flag pinning: patch the ephemeral snapshot manifest so
   # manifest._flags wins over the fetched ClientConfigApi value. No-op unless
@@ -249,6 +258,9 @@ NODE
     prepare_parts+=("bash ${quoted_seed_fixture} prefill --target ${quoted_target} --fixture ${quoted_wallet_fixture} --state ${quoted_fixture_state} --profile ${quoted_profile} --extension-dir ${quoted_runtime_dist} --extension-id-file ${quoted_extension_id_file}")
   fi
   chrome_launch_cmd="node ${quoted_chrome_launcher} --chrome-bin ${quoted_chrome} --profile ${quoted_profile} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --chrome-log ${quoted_chrome_log} --chrome-pid ${quoted_chrome_pid}"
+  if [ -n "${START_URL:-}" ]; then
+    chrome_launch_cmd="$chrome_launch_cmd --start-url $(printf '%q' "$START_URL")"
+  fi
   prepare_parts+=("$chrome_launch_cmd")
   prepare_parts+=("for i in {1..60}; do curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null 2>&1 && break; sleep 1; done; curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null")
   if [ -n "$WALLET_FIXTURE_ABS" ]; then

package/adapters/extension/sidepanel-toggle.sh

@@ -98,10 +98,12 @@ resolve_ext_id() {
     printf '%s\n' "$EXT_ID"
     return
   fi
-  if [ -f "$AGENT_DIR/extension.id" ]; then
-    tr -d '[:space:]' < "$AGENT_DIR/extension.id"
-    return
-  fi
+  for idf in "$AGENT_DIR/extension.id" "$REPO/temp/recipe/runtime/extension.id"; do
+    if [ -f "$idf" ]; then
+      tr -d '[:space:]' < "$idf"
+      return
+    fi
+  done
   json_list | python3 -c "import json,re,sys; d=json.load(sys.stdin); ids=[]; [ids.extend(re.findall(r'^chrome-extension://([^/]+)/', t.get('url',''))) for t in d]; print(ids[0] if ids else '')"
 }
 
@@ -239,15 +241,34 @@ const { chromium } = require('playwright');
     document.getElementById('__recipe_open_sidepanel__')?.remove();
   });
 
-  if (createdPage) {
+  // The wallet now lives in the sidepanel: leftover extension home tabs would
+  // show it twice and steal the foreground from the dapp tab. Close every
+  // non-sidepanel extension page (not just one this helper created), then
+  // bring the first http(s) tab back to front.
+  for (const candidate of context.pages()) {
+    if (
+      candidate.url().startsWith(`chrome-extension://${extId}/`) &&
+      !candidate.url().includes('/sidepanel.html')
+    ) {
+      try {
+        await candidate.close();
+      } catch (error) {
+        console.warn(
+          `[sidepanel] extension page close failed after successful open: ${
+            error && error.message ? error.message : error
+          }`,
+        );
+      }
+    }
+  }
+  const dappPage = context
+    .pages()
+    .find((candidate) => candidate.url().startsWith('http://') || candidate.url().startsWith('https://'));
+  if (dappPage) {
     try {
-      await page.close();
-    } catch (error) {
-      console.warn(
-        `[sidepanel] helper page close failed after successful open: ${
-          error && error.message ? error.message : error
-        }`,
-      );
+      await dappPage.bringToFront();
+    } catch {
+      // focus is cosmetic; the panel is already open
     }
   }
   await browser.close();

package/adapters/extension/wallet-fixture-state.cjs

@@ -668,8 +668,8 @@ async function detectExtension(context, extensionDir, extensionIdFile) {
       const page = await context.newPage();
       try {
         await page.goto(`chrome-extension://${candidate.id}/home.html`, {
-          waitUntil: 'load',
-          timeout: 10000,
+          waitUntil: 'domcontentloaded',
+          timeout: 30000,
         });
         if (page.url().startsWith('chrome-error://')) {
           throw new Error('candidate resolved to chrome-error page');
@@ -726,34 +726,48 @@ async function waitForWalletScreen(page) {
   return { state: 'unknown', selector: null };
 }
 
+async function attemptUnlock(page, password) {
+  // Selector ladder: current testids first, then the generic selectors the CDP
+  // unlock action uses (proven against the same build). A freshly seeded vault
+  // can also still be initializing, so a single attempt is not conclusive —
+  // the caller retries.
+  const filled = await page.evaluate((pw) => {
+    const input =
+      document.querySelector('[data-testid="unlock-password"]') ??
+      document.querySelector('input[type="password"]');
+    if (!input) return false;
+    const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
+    setter.call(input, pw);
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+    return true;
+  }, password);
+  if (!filled) return false;
+  return page.evaluate(() => {
+    const button =
+      document.querySelector('[data-testid="unlock-submit"]') ??
+      document.querySelector('button[type="submit"]') ??
+      Array.from(document.querySelectorAll('button')).find((candidate) => /unlock/iu.test(candidate.innerText || candidate.textContent || ''));
+    if (!button) return false;
+    button.click();
+    return true;
+  });
+}
+
 async function unlockIfNeeded(page, password) {
   let state = await waitForWalletScreen(page);
-  if (state.state === 'locked') {
-    await page.fill('[data-testid="unlock-password"]', password);
-    try {
-      await page.locator('[data-testid="unlock-submit"]').first().click({ timeout: 15000 });
-    } catch (error) {
-      const message = error && error.message ? error.message : String(error);
-      if (!message.includes('Timeout')) throw error;
-      const clicked = await page.evaluate(() => {
-        const button = document.querySelector('[data-testid="unlock-submit"]');
-        if (!button) return false;
-        button.click();
-        return true;
-      });
-      if (!clicked) throw new Error(`Unlock submit timed out and DOM fallback could not find the button: ${message}`);
-    }
-    const deadline = Date.now() + 45000;
-    while (Date.now() < deadline) {
-      state = await waitForWalletScreen(page);
-      if (state.state === 'unlocked') {
-        break;
-      }
+  const deadline = Date.now() + 90000;
+  while (state.state !== 'unlocked' && state.state !== 'onboarding' && Date.now() < deadline) {
+    if (state.state === 'locked') {
+      await attemptUnlock(page, password);
+      await page.waitForTimeout(1500);
+    } else {
       await page.waitForTimeout(750);
     }
+    state = await waitForWalletScreen(page);
   }
   if (state.state !== 'unlocked') {
-    throw new Error(`Wallet did not reach unlocked home screen after fixture seeding (state=${state.state})`);
+    throw new Error(`Wallet did not reach unlocked home screen after fixture seeding (state=${state.state}). Next: mm-harness call ensure_unlocked   # then relaunch`);
   }
   return state;
 }

package/adapters/manifest.json

@@ -322,6 +322,14 @@
       "inputs": "ESM import from resolve-farmslot-ports.mjs or resolve-farmslot-ports.ts",
       "outputs": "resolveFarmslotPortsByRepo and related functions"
     },
+    {
+      "id": "lib/recipe-harness-root",
+      "entry": "adapters/shared/recipe-harness-root.mjs",
+      "kind": "lib",
+      "purpose": "Resolve RECIPE_HARNESS_ROOT for overlay node leaves without importing src/paths.ts.",
+      "inputs": "ESM import; env RECIPE_HARNESS_ROOT optional override",
+      "outputs": "recipeHarnessRoot() relative path string"
+    },
     {
       "id": "lib/resolve-farmslot-ports-sh",
       "entry": "adapters/shared/resolve-farmslot-ports.sh",
@@ -330,6 +338,11 @@
       "inputs": "source + resolve_* / apply_resolved_* function calls",
       "outputs": "KEY=VALUE lines on stdout; env vars via apply_resolved_*"
     },
+    {
+      "id": "lib/reap-checkout-metros",
+      "entry": "adapters/shared/reap-checkout-metros.sh",
+      "kind": "lib"
+    },
     {
       "id": "lib/sync-wallet-fixture",
       "entry": "adapters/shared/sync-wallet-fixture.sh",

package/adapters/mobile/inject.sh

@@ -187,6 +187,7 @@ install_v1_runner_assets() {
     if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
+    printf 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ "$MM_HARNESS_BIN" != %s ]; then echo "mm-harness overlay: %s: %s (reinstall to repoint: mm-harness install)" >&2; fi\n' "$runner_exec_q" 'delegating to the runner pinned at install time' "$runner_exec_q"
     printf 'exec %s "$@"\n' "$runner_exec_q"
   } > "$HARNESS_DIR/runner/bin/mm-harness"
   chmod +x "$HARNESS_DIR/runner/bin/mm-harness"

package/adapters/mobile/stop-metro.sh

@@ -54,8 +54,23 @@ if [ -n "$pids" ]; then
 else
   printf 'Metro not running on port %s — nothing to stop\n' "$PORT" >&2
 fi
+
+# The stop decision is made; everything below is best-effort cleanup (pid file,
+# leaked-bundler sweep, tmux window). None of it may fail the command — the
+# idempotent-stop contract is already satisfied. Drop set -e for the tail so an
+# incidental non-zero (platform-dependent) can never turn success into exit 1.
+set +e
 rm -f "$PID_FILE"
 
+# Port-scoped stop above misses bundlers a prior launch left on a DIFFERENT port
+# (port drift / missing pid file). Sweep every Metro bound to this checkout so
+# stop fully cleans up — the leak that stacked bundlers across relaunches.
+# Guarded: the reap lib may be absent in a minimal install; skip rather than abort.
+if [ -f "$SCRIPT_DIR/../shared/reap-checkout-metros.sh" ]; then
+  . "$SCRIPT_DIR/../shared/reap-checkout-metros.sh"
+  reap_checkout_metros "$TARGET" || true
+fi
+
 # Close the read-only log-tail window start-metro opened, if it is still there.
 if [ -f "$TMUX_FILE" ] && command -v tmux >/dev/null 2>&1; then
   win="$(cat "$TMUX_FILE" 2>/dev/null || true)"
@@ -64,3 +79,8 @@ if [ -f "$TMUX_FILE" ] && command -v tmux >/dev/null 2>&1; then
   fi
 fi
 rm -f "$TMUX_FILE"
+
+# Reaching here = cleanup done (nothing needed stopping, or it stopped and
+# windows/pids were cleared). The idempotent-stop contract is success; do not
+# leak an incidental non-zero from the last command on any platform.
+exit 0

package/adapters/shared/cli-ux.sh

@@ -26,7 +26,16 @@ recipe_color() {
 }
 
 recipe_progress_script() {
-  printf '%s' "${RECIPE_PROGRESS_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/src/progress.ts}"
+  if [ -n "${RECIPE_PROGRESS_SCRIPT:-}" ]; then
+    printf '%s' "$RECIPE_PROGRESS_SCRIPT"
+    return 0
+  fi
+  local root="${RECIPE_RUNNER_ROOT:?}"
+  if [ -f "$root/dist/progress.js" ]; then
+    printf '%s' "$root/dist/progress.js"
+  else
+    printf '%s' "$root/src/progress.ts"
+  fi
 }
 
 recipe_log_tui_script() {
@@ -34,7 +43,16 @@ recipe_log_tui_script() {
 }
 
 recipe_version_script() {
-  printf '%s' "${RECIPE_VERSION_SCRIPT:-${RECIPE_RUNNER_ROOT:?}/src/cli-version.ts}"
+  if [ -n "${RECIPE_VERSION_SCRIPT:-}" ]; then
+    printf '%s' "$RECIPE_VERSION_SCRIPT"
+    return 0
+  fi
+  local root="${RECIPE_RUNNER_ROOT:?}"
+  if [ -f "$root/dist/cli-version.js" ]; then
+    printf '%s' "$root/dist/cli-version.js"
+  else
+    printf '%s' "$root/src/cli-version.ts"
+  fi
 }
 
 recipe_log_ui_mode() {

package/adapters/shared/ensure-runner-deps.sh

@@ -21,7 +21,32 @@ deps_ready() {
   [ -f "$RUNNER_DIR/node_modules/@farmslot/recipe-harness/package.json" ]
 }
 
+# Library actions import @deeeed/metamask-harness by package name; a source checkout
+# is not npm-installed into its own node_modules, so symlink self for resolution.
+ensure_self_package_link() {
+  local link="$RUNNER_DIR/node_modules/@deeeed/metamask-harness"
+  /bin/mkdir -p "$RUNNER_DIR/node_modules/@deeeed"
+  if [ ! -e "$link" ]; then
+    ln -sf "$RUNNER_DIR" "$link"
+  fi
+}
+
+ensure_dev_package_condition() {
+  if [ -f "$RUNNER_DIR/dist/index.js" ]; then
+    return 0
+  fi
+  if [ ! -f "$RUNNER_DIR/src/index.ts" ]; then
+    return 0
+  fi
+  case " ${NODE_OPTIONS:-} " in
+    *" --conditions=development "*) return 0 ;;
+  esac
+  export NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--conditions=development"
+}
+
 if deps_ready; then
+  ensure_self_package_link
+  ensure_dev_package_condition
   exit 0
 fi
 
@@ -39,6 +64,8 @@ if [ -n "$PROTOCOL_ROOT" ] && [ -f "$RUNNER_DIR/scripts/link-local-farmslot.mjs"
     FARMSLOT_ROOT="$(cd "$PROTOCOL_ROOT" && pwd -P)" \
       node "$RUNNER_DIR/scripts/link-local-farmslot.mjs" >&2 || true
     if deps_ready; then
+      ensure_self_package_link
+      ensure_dev_package_condition
       exit 0
     fi
   fi
@@ -54,3 +81,6 @@ if ! deps_ready; then
   echo "mm-harness: runner dependencies still missing after npm install: $RUNNER_DIR" >&2
   exit 1
 fi
+
+ensure_self_package_link
+ensure_dev_package_condition

package/adapters/shared/reap-checkout-metros.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# reap-checkout-metros.sh — kill EVERY Metro/Expo bundler bound to a given
+# checkout, regardless of port. Port-scoped stop leaks a bundler whenever a
+# launch drifts ports or fails to record its pid; this sweeps them by checkout
+# path so `stop` fully cleans up and `launch` starts from zero.
+#
+#   reap_checkout_metros <checkout-abs-path> [keep-pid]
+# keep-pid (optional): a pid to spare (the bundler just started/handled).
+reap_checkout_metros() {
+  local repo="$1" keep="${2:-}" reaped=""
+  [ -n "$repo" ] || return 0
+  # Match the bundler's argv: `expo start` / metro under this checkout. ps argv
+  # embeds the cwd-launched command; expo/metro run with the repo on the path.
+  local pid args
+  while IFS= read -r pid; do
+    [ -n "$pid" ] || continue
+    [ "$pid" = "$keep" ] && continue
+    args="$(ps -o args= -p "$pid" 2>/dev/null || true)"
+    # Anchor to a path boundary so /repos/mm-1 does not match /repos/mm-10.
+    case "$args" in
+      *"$repo/"*|*"$repo "*) : ;;  # argv references this checkout
+      *) continue ;;
+    esac
+    case "$args" in
+      *"expo start"*|*"metro"*|*"react-native/cli"*|*"@react-native-community/cli"*)
+        kill "$pid" 2>/dev/null && reaped="$reaped $pid" ;;
+    esac
+  done <<LIST
+$(pgrep -f "expo start|metro" 2>/dev/null)
+LIST
+  if [ -n "$reaped" ]; then
+    printf 'Reaped leaked Metro bundler(s) for this checkout:%s\n' "$reaped" >&2
+  fi
+  return 0
+}
+
+# detect_checkout_metros <checkout-abs-path> — print pids of every metro/expo
+# bundler bound to the checkout, one per line, WITHOUT killing. Powers doctor's
+# orphan visibility so leaked bundlers are surfaced without a launch.
+detect_checkout_metros() {
+  local repo="$1" pid args
+  [ -n "$repo" ] || return 0
+  while IFS= read -r pid; do
+    [ -n "$pid" ] || continue
+    args="$(ps -o args= -p "$pid" 2>/dev/null || true)"
+    case "$args" in *"$repo/"*|*"$repo "*) : ;; *) continue ;; esac
+    case "$args" in
+      *"expo start"*|*"metro"*|*"react-native/cli"*|*"@react-native-community/cli"*) printf '%s\n' "$pid" ;;
+    esac
+  done <<LIST
+$(pgrep -f "expo start|metro" 2>/dev/null)
+LIST
+}

package/adapters/shared/recipe-harness-root.mjs

@@ -0,0 +1,23 @@
+// recipe-harness-root.mjs — overlay harness root path for node leaves (no src/ import).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+function validateRelative(name, value) {
+  if (!value || path.isAbsolute(value)) {
+    throw new Error(`${name} must be a non-empty relative path: ${value}`);
+  }
+  return value;
+}
+
+function readDefaults() {
+  const defaultsPath = path.join(runnerDir, 'adapters/shared/path-defaults.json');
+  const parsed = JSON.parse(fs.readFileSync(defaultsPath, 'utf8'));
+  return validateRelative('recipeHarnessRoot', parsed.recipeHarnessRoot || 'temp/recipe/harness');
+}
+
+export function recipeHarnessRoot() {
+  return validateRelative('RECIPE_HARNESS_ROOT', process.env.RECIPE_HARNESS_ROOT || readDefaults());
+}