@deeeed/metamask-harness 0.17.3 → 0.17.5

package/CHANGELOG.md

@@ -2,99 +2,12 @@
 
 ## Unreleased
 
-## 0.17.3 - 2026-07-15
-
-### Added
-
-- Added a real-checkout human-outcome gate covering live readiness, runtime verification, debugger target resolution, smoke evidence, and unchanged tracked product source across Extension, Mobile, and Core.
-- Added generic Core runner smoke and fixture-backed wallet smoke recipes so the reusable examples are not tied to Perps.
-- Added nine-slot isolation coverage for platform ports, runtime files, logs, and headless Core behavior.
-
-### Changed
-
-- `doctor` now reports CDP or simulator/ADB screenshot fallback when `capture-helper` is absent or unhealthy, while identifying video as unavailable separately.
-- Action, flow, and recipe discovery/documentation now use one concise scope model; the default recipe-library and adapter-surface references were reduced to current behavior.
-- Fixture discovery now uses one canonical checkout path instead of legacy fallback locations.
-
-### Fixed
-
-- Mobile launch now waits for two consecutive platform-matched agentic bridge snapshots, preventing a transient startup route from being reported ready before an immediate verify.
-- `verify --json` keeps stdout to one machine-readable JSON document even when the platform harness must first be installed.
-- Mobile install metadata safely preserves checkout paths containing shell-significant characters.
-- Cleanup discovery no longer advertises a removed compatibility flag, and Core recovery guidance now points to the canonical wallet fixture.
-- Mobile console forwarding now uses canonical checkout paths, readiness rejects impossible one-poll stability checks, and Extension debug handles malformed WebSocket frames without crashing.
-- Extension watch refreshes remove stale runtime files, delay file replacement until transfer completion, allow slower console attachment, and stop the detached webpack process group.
-
-## 0.17.2 - 2026-07-15
-
-### Fixed
-
-- Passive update discovery now runs in a detached, once-daily registry probe, so fast commands populate the cache without adding latency or contaminating machine output.
-
-## 0.17.1 - 2026-07-15
-
-### Fixed
-
-- Extension `debug` now uses Chrome's native DevTools command for the active slot target and opens directly on Console; `debug --worker` targets the service worker without creating a frontend browser tab.
-- Extension webpack watchers now launch in their own process group, so they remain alive for incremental rebuilds after the initial `launch --build` command exits.
-- Successful Extension watch rebuilds now update the isolated loaded runtime in place, so a normal refresh of the current fullscreen or sidepanel UI shows source edits without another harness build or relaunch.
-- Extension slot titles are stamped into the isolated runtime after snapshots and successful rebuilds, preserving the slot identifier across an operator's normal browser refresh without changing product source.
-- Extension sidepanel opening no longer waits for the harness-owned user-gesture button to pass visual actionability checks; occluded wallet loading surfaces cannot block the trusted click.
-- Human recipe results now print an absolute-path artifact inventory and expand run-scoped application diagnostics inline; single-action calls show the same `CLEAN`/`REVIEW` diagnostics instead of requiring another query.
-- Extension console collection now starts after every successful public launch path, including quick reattach, and persists as one checkout-scoped process until `stop`. MetaMask UI/service-worker events and dapp-page events are routed to separate `extension-console.log` and `dapp-console.log` files; bare `logs` defaults to MetaMask while `--source dapp` and `--source webpack` remain explicit.
-- Mobile CDP-forwarded app events now write to `app-console.log`, so `logs --source app` and run diagnostics are no longer mixed with Metro bundler output; warm and cold launches start a process-group-detached collector only after bridge readiness so capture remains live after the launch command exits.
-- Extension `debug` now opens Chrome's local DevTools frontend inside the exact slot-owned profile, targets the MetaMask extension page rather than the dapp, and verifies the debugging connection before reporting success.
-- Mobile fixture application now fails immediately when the checkout fixture is absent, rejects the misplaced `fixtures set --dev` flag with the correct initialization command, and never prints a success message after failure.
-
-### Changed
-
-- Current documentation now teaches the auto-detected workflow and verified human outcomes only: launch, incremental refresh, target-specific debugging/logs, fixture setup, capability discovery, and proof evidence.
-- Mobile fixture setup now requires the current multichain account-tree path, and Core signing requires the canonical checkout wallet fixture.
-
-### Removed
-
-- Removed compatibility-only runtime-start fields, hidden `live` execution, removed-command handlers, undomained recipe aliases, flat/non-ESM action lookup, old port-resolver filenames, duplicate Extension launcher naming, obsolete fixture search locations, and the alternate Mobile product-source bridge. Mobile install now requires the current product-owned bridge and writes metadata only.
-- Removed the historical CLI migration/spec documents; current behavior is documented in the README, cheatsheet, architecture, and human QA checklist.
-
-## 0.17.0 - 2026-07-14
-
-### Added
-
-- Command-specific JSON failures now preserve a structured `userAction` across device targeting, action calls, recipe validation/execution, checks, and dev-server stop. Successful install/verify/cleanup, provision, and stop transitions add `next` only when one truthful follow-up exists; discovery and terminal evidence results remain quiet.
-- `run` and `launch` now implement the documented `--json-stream` contract: line-flushed JSONL phase/progress events, per-node recipe status, compact evidence paths, and one terminal `complete` event. Stream mode keeps stdout machine-clean and takes precedence when combined with `--json`; existing `--json` output is unchanged.
-- Interactive Mobile launch, Runway provisioning, and recipe execution now print contextual intent before their first potentially slow readiness or validation probe. The new lines are suppressed for `--json` and non-TTY stdout.
-- `last --json` reads an atomic, mode-`0600`, per-checkout resumability journal for significant runtime/proof commands, including redacted args, verdict, evidence paths, and timestamps. Interrupted commands remain `running`; discovery commands do not overwrite the record.
-- `actions <query>` now searches action names, categories, fields, and descriptions with typo tolerance, while single-action detail includes compact related-action names.
-
-### Changed
-
-- Action categories now group protocol primitives into useful `assertion`, `control`, `evidence`, and `runtime` domains instead of exposing one category per unnamespaced action.
-- Public commands now reject unknown commands/options, missing values and positionals, invalid enums, and excess positionals before dispatch. Human errors include valid command-local options, a closest match when available, and a runnable example; `--json` returns stable `CLI_*` codes with `error.message` and `error.userAction`.
-- `docs/CLI-ERGONOMICS-AUDIT.md` is generated from the public command contract so every command remains covered by the shared bad-flag and JSON usage-error policy as the surface evolves.
-
-## 0.16.0 - 2026-07-14
-
-### Added
-
-- Mobile and Extension recipe runs now write bounded, redacted, non-blocking side findings to `diagnostics.json`: Mobile combines its in-app issue buffer with run-scoped log bytes, while Extension owns a CDP console subscription for the run. Core remains N/A because it is headless.
-- `actions --categories` now lists compact category counts, and `actions --category <name>` returns a bounded action/schema view so agents can discover capabilities without loading the complete adapter catalog.
-
-## 0.15.2 - 2026-07-13
-
-### Fixed
-
-- Mobile `ui.press text=<visible text>` now invokes the app bridge's text-content press path, while `test_id`, `testID`, and `selector` continue to use exact testID matching; ambiguous target combinations fail before bridge execution.
-
-## 0.15.1 - 2026-07-13
-
-### Fixed
-
-- `doctor --fix` recovery `nextActions` (numbered fixture choices, overlay install, runtime-context retry) now embed the resolved `--adapter` and absolute `--target`, shell-quoted, so each command works verbatim from any cwd. They are also prefixed with the resolved `bin/mm-harness` executable path, so they work in task-local installs where `mm-harness` is not on PATH.
-
-## 0.15.0 - 2026-07-13
+## 0.17.5 - 2026-07-16
 
 ### Changed
 
+- Mobile proof preflight now waits for the requested platform's bridge target after an automatic source-change restart; a bridge transition fails with a typed `MOBILE_BRIDGE_NOT_READY` result instead of letting the recipe race into `NO_TARGET`.
+- Extension proof recovery now gives the checkout-owned runtime-dist synchronizer a short bounded handoff window after reattach, avoiding a false stale-runtime failure while still surfacing a real unhealthy build.
 - Extension `status` and `doctor` now report the webpack dev server as `up` only when a target-owned watcher is alive; historical successful build logs no longer imply liveness after `stop`.
 - Mobile overlay freshness no longer reports `pass` when every checkable runner overlay file is absent from the target; missing or drifted files are classified before the empty-overlay success case.
 - Mobile live verification now compares AgenticService/HUD freshness against the canonical `app/dev-tools/AgenticService` runner and product paths instead of skipping the check through the obsolete `app/core/AgenticService` layout.
@@ -116,6 +29,8 @@
 - Public Extension `stop` now tears down the checkout-owned watcher, Chrome/CDP profile processes, viewer tails/windows, and stale runtime PID/lock markers; explicit `--port` overrides only the watcher port and no longer hides the runtime-context CDP owner.
 - Tmux log viewers now require an explicit `RECIPE_TMUX_SESSION` or checkout `agentic-runtime.json` session; merely running from another tmux session never creates, sweeps, or marker-closes windows there, while stale markers are discarded and file logs remain available.
 - Extension `run`/`call --heal auto` now rebuild or reload before proof when source, `dist/chrome`, and the loaded runtime snapshot are out of sync; healing-off runs stop before execution with the exact `launch --build --verify` recovery command.
+- Extension slots now launch with `--remote-allow-origins=http://127.0.0.1:<cdpPort>` (scoped to the slot's own debug origin, never `*`) so the local DevTools frontend can attach; without it Chrome 403s every browser DevTools WebSocket on the debug port. The debug-port flag trio (address + port + allow-origins) is declared once in a shared `chrome-args.cjs` and consumed by both the fresh launcher and the reopen path, so the origin allow-list can never drift away from the port.
+- Extension `launch` now refreshes a slot's injected harness overlay from the runner whenever they diverge: `inject` stamps a source fingerprint into the slot manifest and each launch re-injects on mismatch (or when never installed). A runner change — e.g. a launcher flag — reaches every slot on the next launch instead of silently running a stale injected copy.
 - Extension launch, readiness, reattach, actions, and screenshots preserve the operator's keyboard focus by default while retaining a headed, isolated CDP browser; macOS app launch uses Launch Services in the background, and explicit window focus remains available with `MM_HARNESS_FOCUS_BROWSER=1`.
 - `mm-harness check diff --fix` now repairs only changed files with the checkout's direct ESLint and oxfmt/Prettier binaries, then runs the normal bounded validation, so agents do not need to guess repository lint scripts.
 - Recipe-run infra healing now performs the adapter's runtime recovery before retrying instead of only recording a recovery label and immediately rerunning the recipe.
@@ -130,12 +45,7 @@
 - `fixtures init --from <path>|--dev` initializes the canonical checkout wallet fixture explicitly; `--dev` is a disposable public test wallet and is never suitable for real funds.
 
 ### Fixed
-- Missing checkout targets now return the structured usage envelope before lock acquisition in `run` and `doctor`; recovery bounds distinguish a consumed successful repair, adapter helpers preserve explicit runtime/device pins, checklist-only runtime resolution is lazy, and fixture finalization is time-bounded.
-- Checkout contention now uses one bounded JSON contract across `call`, `launch`, `doctor --fix`, `fixtures`, and `run`: exit 4 with `SANDBOX_BUSY` and an actionable lock path.
-- Extension loaded-snapshot checks now use size/mtime comparison instead of full checksums, fall back to an in-process comparison when `rsync` is unavailable, and report comparison failures without forcing a misleading relaunch.
-- Mobile Perps environment repair now publishes `.js.env` atomically without following destination symlinks, and Mobile source preflight returns an actionable `MOBILE_SOURCE_UNAVAILABLE` error for non-Git targets.
-- Mobile no longer translates the Extension-only `visible=true` wait alias into an unsupported enum; `call --arg` accepts quoted JSON strings for numeric-looking string values.
-- Timed streaming leaves now settle as soon as a SIGTERM-terminated direct child exits, reap SIGTERM-ignoring descendants, and forward Ctrl+C/SIGTERM to detached child trees before the harness exits.
+- Extension `debug` now opens a working, offline DevTools console attached to the running slot's extension page: it launches the locally-served bundled DevTools frontend in its own window inside the slot's Chromium instead of Chrome's hosted `chrome-devtools-frontend.appspot.com` URL, which Chrome's WebSocket origin check rejected (the console showed "Debugging connection was closed"). A slot launched before this change fails a pre-open origin probe and reports the exact relaunch command instead of opening a dead console.
 - `doctor --fix` now schema-validates, quarantines, and recreates malformed, semantically invalid, or cross-adapter-contaminated checkout runtime context without touching product data; wallet-fixture recovery commands use `--force` only for invalid or incomplete existing fixtures, while a missing fixture retains the safe unforced initialization command.
 - `logs --source app` now resolves the adapter-owned application console (`extension-console.log` on Extension and the CDP-forwarded `metro.log` on Mobile); an absent console returns `APP_LOG_UNAVAILABLE` instead of falling back to a dev-server log or reporting a usage error.
 - Doctor JSON now retains runtime probe failures, marks every diagnostic check as required or optional, derives its status from required checks, and reports runtime readiness separately.

package/README.md

@@ -1,137 +1,177 @@
-# mm-harness
+# MetaMask Recipe Runner — `mm-harness`
 
-`mm-harness` gives people and agents one CLI for operating MetaMask Mobile,
-Extension, and Core. Run it inside a checkout; the product is auto-detected.
+Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 
-It has two jobs:
+**`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
+thin MetaMask adapter over the generic `@farmslot/recipe-harness` engine — the
+runner never re-implements graph execution, it binds to it. The agent gets full
+depth (explicit flags, `--json`, ports, build tiers); the human gets short
+commands, positional targets, good defaults, completions, and teaching
+help/errors. Run it from inside a MetaMask Mobile/Extension/Core checkout and the
+platform is auto-detected.
 
-- operate the app with the same controls a developer needs: launch, logs, debug,
-  fixtures, actions, and reusable flows;
-- execute deterministic recipes and save reviewable proof.
-
-The generic graph engine lives in `@farmslot/recipe-harness`. This package owns
-only MetaMask-specific actions and runtime control.
+```
+DAILY LOOP        launch · logs · debug · fixtures     what a teammate runs many times a day
+DISCOVER          actions · call · flows               compose recipes from the vocabulary + flow library
+PROVE             run · doctor                         run recipes, check readiness
+RUNTIME OVERLAY   install · verify · cleanup           manage the per-checkout runtime overlay
+```
 
-One mental model:
+**One bin, no per-platform binaries.** `mm-harness` is the only command. Grammar:
+`mm-harness <command> [target] [flags]` — the human types the bare command
+(platform auto-detected) or a positional target (`mm-harness launch ios`); depth
+lives in FLAGS with good defaults, never in extra command names. It ships shell
+completions (zsh + bash) for commands, targets, and flags.
 
-- **Action** — one typed operation, such as reading wallet state.
-- **Flow** — a reusable, parameterized sequence of actions.
-- **Recipe** — the complete executable proof for a task or regression.
+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.
 
-## Install
+One package, two responsibilities:
 
-```bash
-npm install -g @deeeed/metamask-harness@latest
-mm-harness --version
-mm-harness doctor
-```
+- **Recipe layer:** manifests, recipes, Mobile/Extension adapters, proof output.
+- **Runtime layer:** start/reuse Metro or Chrome, seed fixtures, wait for readiness.
 
-Use `mm-harness update` to install the latest published version.
+Farmslot and skills are wrappers around this CLI; they should not copy runner
+logic.
 
-## Daily workflow
+## Quick start
 
-From a MetaMask checkout:
+Run from inside a MetaMask checkout (platform auto-detected):
 
 ```bash
-# Extension
-mm-harness launch              # starts/reuses Chrome and the incremental watcher
-mm-harness launch --sidepanel  # open the sidepanel surface
-
-# Mobile
-mm-harness launch ios
-mm-harness launch android
-
-# Any product
-mm-harness status
-mm-harness logs
-mm-harness debug
-mm-harness fixtures set
-```
+# 1) Launch the app (installs the runtime overlay on first use, boots Metro/build)
+mm-harness launch ios                    # mobile: ios | android; extension: just `launch`
 
-`launch` installs the checkout-local runtime overlay when needed. On Extension,
-the normal launch keeps `yarn start` running after the command exits. Source
-edits compile incrementally into the isolated runtime; refresh the active page or
-sidepanel to see them. Use `launch --build` only when a clean rebuild is needed.
+# 2) Run a recipe and write evidence
+mm-harness run recipe.json --adapter mobile --artifacts-dir /tmp/recipe-artifacts --json
+```
 
-`debug` opens DevTools for the active Extension target in that checkout's Chrome
-profile. Mobile opens the React Native developer surface.
+Outputs: `summary.json`, `trace.json`, screenshots, logs, and an artifact
+manifest.
 
-Filter logs when needed:
+## Mental model
 
-```bash
-mm-harness logs --source extension  # Extension console
-mm-harness logs --source dapp       # active dapp console
-mm-harness logs --source webpack    # Extension compiler
-mm-harness logs --source app        # Mobile app events
-mm-harness logs --source metro      # Mobile bundler
+```text
+mm-harness launch   # runtime/orchestration: the app is ready
+mm-harness run      # runner/proof: actions execute and evidence is saved
 ```
 
-## Build and run proof
+Do not mix those layers. library/ = what recipes ARE (recipes, actions,
+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
 
 ```bash
-mm-harness actions positions
-mm-harness actions --action metamask.wallet.ensure_unlocked
-mm-harness call metamask.wallet.ensure_unlocked
-mm-harness flows
-
-mm-harness run path/to/recipe.json --plan
-mm-harness run path/to/recipe.json --artifacts-dir temp/recipe-proof
-mm-harness run wallet.smoke --artifacts-dir temp/wallet-proof
+# Capabilities (compose recipes from the vocabulary + flow library)
+mm-harness actions --adapter mobile --json      # the action vocabulary
+mm-harness actions --adapter mobile --raw       # raw action-manifest dump
+mm-harness call unlock --adapter extension      # run one action via the real engine path
+mm-harness flows --json                         # reusable library flows, with provenance
+
+# Readiness + proof
+mm-harness doctor                               # read-only readiness check (no launch)
+mm-harness doctor --fix                         # heal the overlay without launching
+mm-harness run recipe.json --plan --adapter mobile   # validate + plan, touch nothing
+
+# Daily loop (run from inside a checkout)
+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 }
 ```
 
-`call` exercises one action. A recipe composes actions and flows into a
-deterministic proof.
+### Human validation rule
+
+An exit code or `--json` result is not sufficient for a UI/debug command. After
+`launch --verify`, confirm the debugger is visibly connected to the current
+slot's app/profile. Repeat this check on every slot/platform that will be used
+before release.
+
+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/            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 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, adapter-surface-doctor)
+docs/           details when this README is not enough
+```
 
-A run prints its findings, diagnostics, and absolute evidence paths. The artifact
-directory contains the executed recipe, summary, trace, diagnostics when
-applicable, screenshots/logs, and `artifact-manifest.json`. Core is headless, so
-browser/device diagnostics do not apply.
+Defaults for installed harness/runtime paths live in
+`adapters/shared/path-defaults.json`.
 
-Use `mm-harness last --json` to resume after interruption without repeating a
-side-effecting command.
+## Runtime-readiness ownership
 
-## Team recipe libraries
+Generic readiness mechanics live in `@farmslot/recipe-harness` (0.3+):
 
-Add a named shared directory with `RECIPE_LIBRARY_PATH`:
+- `@farmslot/recipe-harness/runtime/deps-readiness` — install fingerprint + baseline
+- `@farmslot/recipe-harness/runtime/log-analysis` — bundle-log boundaries, unresolved-module scoping
+- `@farmslot/recipe-harness/runtime/metro-probe` — Metro `/status` reachability
 
-```bash
-export RECIPE_LIBRARY_PATH="team=$HOME/shared-library/team-recipes"
-mm-harness flows
-```
+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.
 
-Team flows can wrap repeated product behavior while each checklist or task keeps
-its own acceptance criteria. See [recipe libraries](docs/recipe-libraries.md).
+## Dev/prod harness (`MM_HARNESS_BIN`)
 
-## Health and recovery
+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
-mm-harness doctor        # inspect; does not launch
-mm-harness doctor --fix  # repair local harness setup; does not launch
-mm-harness verify        # verify the installed runtime overlay
-mm-harness cleanup       # remove the runtime overlay
+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
 ```
 
-Human output gives a next command. `--json` gives stable machine-readable errors
-and keeps stdout free of decoration. `--json-stream` emits line-delimited progress
-for long recipe runs.
+`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.
 
-## Development
-
-Use a source checkout without replacing the global install:
-
-```bash
-export MM_HARNESS_BIN=/path/to/metamask-harness/bin/mm-harness
-mm-harness --version
-```
+## Runtime notes
 
-Unset `MM_HARNESS_BIN` to return to the published install.
+- `tmux` is recommended for long-lived Metro/webpack processes; standalone use
+  falls back to detached `nohup` where possible.
+- Mobile may inject a local development bridge/HUD into older checkouts. Do not
+  commit those product patches.
+- Extension does not patch product source; it drives `dist/chrome` through Chrome
+  CDP.
 
-Validate changes with:
+## Validate changes
 
 ```bash
 yarn check
+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
 ```
 
-Current references: [cheatsheet](docs/CHEATSHEET.md), [recipe libraries](docs/recipe-libraries.md),
-and [human QA](docs/CLI-ERGONOMICS-HUMAN-QA.md). Maintainers also have the
-[architecture](docs/architecture.md) and [video gate](docs/VIDEO-DEMO-VALIDATION.md).
+More detail: [Architecture](docs/architecture.md), [Package boundaries](docs/package-boundaries.md), [Runtime file conventions](docs/runtime-file-conventions.md).

package/adapters/extension/console-tail.mjs

@@ -8,7 +8,7 @@
 // the tab shows live extension logs (the equivalent of the Metro/webpack tabs).
 //
 // Usage:
-//   console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>]
+//   console-tail.mjs --cdp-port <port> [--log <file>]
 //
 // Resilience: MV3 service workers cycle on idle and UI pages open/close, so we
 // re-poll /json/list every ~2s and (re)attach to any extension target that is
@@ -19,10 +19,9 @@
 'use strict';
 
 import { appendFileSync } from 'node:fs';
-import path from 'node:path';
 
 function parseArgs(argv) {
-  const args = { cdpPort: null, extensionLog: null, dappLog: null };
+  const args = { cdpPort: null, log: null };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     switch (arg) {
@@ -30,16 +29,12 @@ function parseArgs(argv) {
         args.cdpPort = argv[++i];
         break;
       case '--log':
-      case '--extension-log':
-        args.extensionLog = argv[++i];
-        break;
-      case '--dapp-log':
-        args.dappLog = argv[++i];
+        args.log = argv[++i];
         break;
       case '-h':
       case '--help':
         process.stdout.write(
-          'Usage: console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>]\n',
+          'Usage: console-tail.mjs --cdp-port <port> [--log <file>]\n',
         );
         process.exit(0);
         break;
@@ -56,9 +51,6 @@ if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
   throw new Error('console-tail requires a numeric --cdp-port.');
 }
 const HOST = `127.0.0.1:${cdpPort}`;
-if (args.extensionLog && !args.dappLog) {
-  args.dappLog = path.join(path.dirname(path.resolve(args.extensionLog)), 'dapp-console.log');
-}
 
 if (typeof WebSocket === 'undefined') {
   throw new Error('console-tail requires Node 22+ with a global WebSocket.');
@@ -73,9 +65,9 @@ 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, destination = null) {
+function out(line) {
   process.stdout.write(`${line}\n`);
-  if (destination) appendFileSync(destination, `${line}\n`);
+  if (args.log) appendFileSync(args.log, `${line}\n`);
 }
 
 function stamp() {
@@ -103,22 +95,6 @@ function isExtensionTarget(target) {
   return String(target.url || '').startsWith('chrome-extension://');
 }
 
-function isDappTarget(target) {
-  if (!target || !target.webSocketDebuggerUrl || target.type !== 'page') return false;
-  try {
-    const url = new URL(String(target?.url || ''));
-    return url.protocol === 'http:' || url.protocol === 'https:';
-  } catch {
-    return false;
-  }
-}
-
-function targetStream(target) {
-  if (isExtensionTarget(target)) return { kind: 'extension', log: args.extensionLog };
-  if (isDappTarget(target)) return { kind: 'dapp', log: args.dappLog };
-  return null;
-}
-
 function previewArg(arg) {
   if (!arg || typeof arg !== 'object') return String(arg);
   if ('value' in arg && arg.value !== undefined) {
@@ -132,29 +108,29 @@ function previewArg(arg) {
   return arg.subtype || arg.type || '?';
 }
 
-function emitConsole(label, params, destination) {
+function emitConsole(label, params) {
   const level = String(params.type || 'log').toUpperCase();
   const text = (params.args || []).map(previewArg).join(' ');
-  out(`${stamp()} [${label}] ${level}  ${text}`, destination);
+  out(`${stamp()} [${label}] ${level}  ${text}`);
 }
 
-function emitException(label, params, destination) {
+function emitException(label, params) {
   const d = params.exceptionDetails || {};
   const text =
     d.exception?.description ||
     d.exception?.value ||
     d.text ||
     'uncaught exception';
-  out(`${stamp()} [${label}] EXCEPTION  ${text}`, destination);
+  out(`${stamp()} [${label}] EXCEPTION  ${text}`);
 }
 
-function emitLogEntry(label, params, destination) {
+function emitLogEntry(label, params) {
   const e = params.entry || {};
   const level = String(e.level || 'log').toUpperCase();
-  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`, destination);
+  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`);
 }
 
-function handleMessage(label, destination, data) {
+function handleMessage(label, data) {
   let message;
   try {
     message = JSON.parse(data);
@@ -165,13 +141,13 @@ function handleMessage(label, destination, data) {
   if (message.id != null) return; // command ack, not an event
   switch (message.method) {
     case 'Runtime.consoleAPICalled':
-      emitConsole(label, message.params || {}, destination);
+      emitConsole(label, message.params || {});
       break;
     case 'Runtime.exceptionThrown':
-      emitException(label, message.params || {}, destination);
+      emitException(label, message.params || {});
       break;
     case 'Log.entryAdded':
-      emitLogEntry(label, message.params || {}, destination);
+      emitLogEntry(label, message.params || {});
       break;
     default:
       break;
@@ -179,11 +155,9 @@ function handleMessage(label, destination, data) {
 }
 
 function attach(target) {
-  const stream = targetStream(target);
-  if (!stream) return;
-  const label = `${stream.kind}:${shortLabel(target)}`;
+  const label = shortLabel(target);
   const ws = new WebSocket(target.webSocketDebuggerUrl);
-  const entry = { ws, label, destination: stream.log, opened: false };
+  const entry = { ws, label, opened: false };
   attached.set(target.id, entry);
 
   ws.addEventListener('open', () => {
@@ -192,16 +166,16 @@ function attach(target) {
     for (const method of ['Runtime.enable', 'Log.enable']) {
       ws.send(JSON.stringify({ id: ++id, method, params: {} }));
     }
-    out(`${stamp()} [${label}] [attached]`, stream.log);
+    out(`${stamp()} [${label}] [attached]`);
   });
   ws.addEventListener('message', (event) => {
-    handleMessage(label, stream.log, typeof event.data === 'string' ? event.data : '');
+    handleMessage(label, typeof event.data === 'string' ? event.data : '');
   });
   const drop = () => {
     if (attached.get(target.id) !== entry) return;
     attached.delete(target.id);
     if (entry.opened) {
-      out(`${stamp()} [${label}] [reconnect] target detached; will re-attach`, stream.log);
+      out(`${stamp()} [${label}] [reconnect] target detached; will re-attach`);
     } else {
       // Never connected (target gone / not debuggable yet): back off so a dead
       // target is not retried — and logged — on every 2s poll.
@@ -222,9 +196,8 @@ async function poll() {
     // CDP not reachable this tick (browser starting/restarting); retry next poll.
     return;
   }
-  const targetList = Array.isArray(targets) ? targets : [];
-  for (const target of targetList) {
-    if (!targetStream(target)) continue;
+  for (const target of Array.isArray(targets) ? targets : []) {
+    if (!isExtensionTarget(target)) continue;
     if (attached.has(target.id)) continue;
     const until = cooldown.get(target.id);
     if (until !== undefined) {
@@ -253,6 +226,6 @@ function shutdown() {
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
 
-out(`${stamp()} [console-tail] streaming extension and dapp consoles via cdp ${cdpPort}`);
+out(`${stamp()} [console-tail] streaming extension console via cdp ${cdpPort}`);
 await poll();
 setInterval(poll, 2000);

package/adapters/extension/ensure-browser.sh

@@ -277,6 +277,7 @@ const fs = require('fs');
 const http = require('http');
 const { execSync, execFileSync } = require('child_process');
 let chromium; try { chromium = require('@playwright/test').chromium; } catch { chromium = require('playwright').chromium; }
+const { remoteDebuggingArgs } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
 
 const SLOT_ID = '${SLOT_ID}';
 const AGENT_DIR = '${AGENT_DIR}';
@@ -309,7 +310,12 @@ const resumeWebpack = () => {
     '--no-default-browser-check',
     '--window-size=420,800',
   ];
-  if (CDP_PORT) args.push('--remote-debugging-port=' + CDP_PORT);
+  // Debug-port trio (address + port + scoped allow-origins) from the shared module
+  // so the DevTools origin allow-list can never drift away from the port; without
+  // it Chrome 403s every browser DevTools WebSocket and mm-harness debug can't attach.
+  if (CDP_PORT) {
+    args.push(...remoteDebuggingArgs(CDP_PORT));
+  }
 
   const chromiumApp = path.dirname(path.dirname(path.dirname(chromium.executablePath())));
   execFileSync('open', ['-g', '-n', '-a', chromiumApp, '--args', ...args], { stdio: 'ignore' });