@deeeed/metamask-harness 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,13 +1,60 @@
 # Changelog
 
-## 0.5.0 - 2026-07-05
+## 0.6.0 - 2026-07-06
 
-Minor release: thin Runway provisioning (harness-owned slot provisioning with a shared artifact cache) plus compiled-dist packaging.
+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.
+
+### Fixed
+- **First launch on a provisioned slot targets the slot's own simulator** — the mobile resolution ladder now reads the `runway-provision.json` baseline (simulator name/udid, watcher port, slot id) when `agentic-runtime.json` doesn't exist yet, and boots that simulator. Previously a provisioned-but-unprepared slot degraded to the simctl `booted` alias, missed the installed dev client, and guessed the wrong Metro port.
+- **`call` works from published installs** — library actions load harness helpers through a dist-preferring bridge instead of importing `src/index.ts` (node refuses to type-strip `.ts` under `node_modules`). The bridge is deliberately narrow (paths + run-recording) to avoid an import cycle through `adapters.ts`.
+- **deps-not-ready guidance matches the caller's state** — on a checkout without node_modules the taught command now leads with `yarn install --immutable` (yarn cannot run scripts at all on a bare checkout), and always ends with the launch re-run.
+
+## 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
+Minor release: thin Runway provisioning (harness-owned slot provisioning with a shared artifact cache) plus compiled-dist packaging.
 ### Added
 - **`mm-harness provision runway`** — provisions a mobile slot with exactly: resolve the latest Runway (expo-dev-build) artifact, download it ONCE into a shared machine cache (`~/.cache/metamask-harness/runway/<runId>/`, sha256+size integrity, corrupt entries re-downloaded, never a slot failure), create the simulator if missing, install the dev client on it. Zero yarn/deps/Metro — those stay dispatch-time (lazy, presence-authoritative readiness unchanged). `install --runway` is the overlay-path equivalent (covered by its own contract test). Baseline recorded so doctor reports provisioned-but-deps-pending as a normal state.
 - **Compiled `dist/` for published installs** — the npm tarball ships esbuild-compiled JS; `npm i -g` installs run the dist entry (~0.21s cold vs ~0.37s tsx). Source checkouts without `dist/` keep the tsx dev path; `bin/mm-harness` prefers dist when present. Packaging contract test (pack → global install → dist entry runs).
-
 ### Changed
 - Runway provisioning callers (farm installer, mobile-farm `runway` prepare profile) delegate to the harness; the profile no longer runs a deps phase and a contract test enforces that.
 
@@ -43,17 +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`.
-
 ### 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.
@@ -139,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
 
@@ -150,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 });
@@ -108,6 +109,8 @@ copyFile(path.join(runnerDir, 'adapters/extension/ensure-browser.sh'), path.join
 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/resolve-farmslot-ports.mjs'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports.mjs'));
+copyFile(path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports-core.mjs'), path.join(harnessDir, 'scripts/lib/resolve-farmslot-ports-core.mjs'));
 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'));

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/refresh-build.sh

@@ -97,7 +97,7 @@ elif command -v activate_repo_node >/dev/null 2>&1; then
     exit 1
   }
 else
-  echo "[refresh] activate-repo-node.sh missing from harness; run: recipe sync" >&2
+  echo "[refresh] activate-repo-node.sh missing from harness; run: mm-harness install" >&2
   exit 1
 fi
 
@@ -186,5 +186,5 @@ kill "$BUILD_PID" 2>/dev/null || true
 wait "$BUILD_PID" 2>/dev/null || true
 trap - EXIT
 
-echo "[refresh] Build refreshed and frozen — run: recipe reopen"
+echo "[refresh] Build refreshed and frozen — run: mm-harness launch"
 echo "[refresh] Log kept at: $LOG"

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/start-watch.sh

@@ -82,7 +82,7 @@ elif command -v activate_repo_node >/dev/null 2>&1; then
     exit 1
   }
 else
-  echo "[recipe-harness] activate-repo-node.sh missing from harness; run: recipe sync" >&2
+  echo "[recipe-harness] activate-repo-node.sh missing from harness; run: mm-harness install" >&2
   exit 1
 fi
 if [ -z "$WATCHER_PORT" ]; then
@@ -233,7 +233,7 @@ for _lib in "$SCRIPT_DIR/lib" "$SCRIPT_DIR/../shared"; do
 done
 unset _lib
 echo "[recipe-harness] Starting yarn start (watcher-port=${WATCHER_PORT:-default})"
-echo "[recipe-harness] compact build view - full log: $watch_log (recipe logs --full)"
+echo "[recipe-harness] compact build view - full log: $watch_log (mm-harness logs --full)"
 started_pid=""
 # Launch the watcher detached writing to the log; the tmux window is a read-only tail viewer.
 path_prefix="${REPO_NODE_PATH_PREFIX:-}"

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

@@ -308,12 +308,41 @@
     },
     {
       "id": "lib/resolve-farmslot-ports",
-      "entry": "adapters/shared/resolve-farmslot-ports.sh",
-      "kind": "lib",
+      "entry": "adapters/shared/resolve-farmslot-ports.mjs",
+      "kind": "node",
       "purpose": "Resolve CDP + watcher ports from farmslot pool JSON by repo path, else 6660+N / 9010+N.",
-      "inputs": "resolve_extension_runtime_ports <repo>",
+      "inputs": "resolve-farmslot-ports.mjs resolve_extension_runtime_ports <repo>",
       "outputs": "CDP_PORT / WATCHER_PORT / SLOT_ID lines on stdout"
     },
+    {
+      "id": "lib/resolve-farmslot-ports-core",
+      "entry": "adapters/shared/resolve-farmslot-ports-core.mjs",
+      "kind": "lib",
+      "purpose": "Self-contained pool/context/formula port resolution imported by the node leaf and TS surface.",
+      "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",
+      "kind": "lib",
+      "purpose": "Bash-compat sourced wrapper over resolve-farmslot-ports.mjs for stop-metro and legacy callers.",
+      "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/start-metro.sh

@@ -102,7 +102,7 @@ CLEAR_SUFFIX=""
 
 printf 'Starting Metro on port %s (workers=%s%s)\n' \
   "$PORT" "$METRO_WORKERS" "${CLEAR:+, clear}" >&2
-printf '(Full log: %s — recipe logs | recipe logs --full)\n' "$LOG_FILE" >&2
+printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FILE" >&2
 
 # Metro runs detached, writing to the log. The tmux window is a read-only tail.
 (

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/mobile/verify.sh

@@ -296,7 +296,7 @@ if (checked === 0) {
   const parts = [];
   if (drifted.length) parts.push('behind runner: ' + drifted.join(', '));
   if (missing.length) parts.push('absent in repo: ' + missing.join(', '));
-  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun mm-harness install --force-overlay or recipe sync to refresh the in-repo HUD/AgenticService from the runner' }));
+  process.stdout.write(JSON.stringify({ name, status: 'warn', detail: parts.join('; ') + ' — rerun mm-harness install --force-overlay or mm-harness fixtures sync to refresh the in-repo HUD/AgenticService from the runner' }));
 } else {
   process.stdout.write(JSON.stringify({ name, status: 'pass' }));
 }

package/adapters/shared/activate-repo-node.sh

@@ -134,7 +134,7 @@ activate_repo_node() {
 require_repo_node() {
   local target="${1:-.}"
   if ! command -v activate_repo_node >/dev/null 2>&1; then
-    echo "[env] activate-repo-node.sh is not sourced; reinstall the harness (recipe sync)" >&2
+    echo "[env] activate-repo-node.sh is not sourced; reinstall the harness (mm-harness install)" >&2
     return 1
   fi
   activate_repo_node "$target" || {