@deeeed/metamask-harness 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## Unreleased
 
+### 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.
+
+### 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.1 - 2026-07-14
+
+### Fixed
+
+- 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.
+
+## 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

package/README.md

@@ -1,178 +1,131 @@
-# MetaMask Recipe Runner — `mm-harness`
+# mm-harness
 
-Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+`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.
 
-**`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.
+It has two jobs:
 
-```
-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
-```
+- 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.
 
-**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.
+The generic graph engine lives in `@farmslot/recipe-harness`. This package owns
+only MetaMask-specific actions and runtime control.
 
-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:
-
-- **Recipe layer:** manifests, recipes, Mobile/Extension adapters, proof output.
-- **Runtime layer:** start/reuse Metro or Chrome, seed fixtures, wait for readiness.
+```bash
+npm install -g @deeeed/metamask-harness@latest
+mm-harness --version
+mm-harness doctor
+```
 
-Farmslot and skills are wrappers around this CLI; they should not copy runner
-logic.
+Use `mm-harness update` to install the latest published version.
 
-## Quick start
+## Daily workflow
 
-Run from inside a MetaMask checkout (platform auto-detected):
+From a MetaMask checkout:
 
 ```bash
-# 1) Launch the app (installs the runtime overlay on first use, boots Metro/build)
-mm-harness launch ios                    # mobile: ios | android; extension: just `launch`
-
-# 2) Run a recipe and write evidence
-mm-harness run recipe.json --adapter mobile --artifacts-dir /tmp/recipe-artifacts --json
+# 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
 ```
 
-Mobile and Extension runs also write `diagnostics.json` from application events
-emitted during that run. Mobile combines its bounded in-app issue buffer with
-run-scoped log bytes; Extension owns a CDP console subscription for the run.
-These redacted warnings/errors are non-blocking side findings: they help spot
-adjacent bugs without claiming the recipe or current change caused them. Core
-is headless, so this is N/A there.
+`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.
 
-Outputs: `summary.json`, `trace.json`, screenshots, logs, and an artifact
-manifest.
+`debug` opens DevTools for the active Extension target in that checkout's Chrome
+profile. Mobile opens the React Native developer surface.
 
-## Mental model
+Filter logs when needed:
 
-```text
-mm-harness launch   # runtime/orchestration: the app is ready
-mm-harness run      # runner/proof: actions execute and evidence is saved
+```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
 ```
 
-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
+## Build and run proof
 
 ```bash
-# Capabilities (compose recipes from the vocabulary + flow library)
-mm-harness actions --adapter mobile --categories --json # compact discovery
-mm-harness actions --adapter mobile --category ui --json # bounded 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 }
-```
+mm-harness actions positions
+mm-harness actions --action metamask.wallet.ensure_unlocked
+mm-harness call metamask.wallet.ensure_unlocked
+mm-harness flows
 
-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
+mm-harness run path/to/recipe.json --plan
+mm-harness run path/to/recipe.json --artifacts-dir temp/recipe-proof
 ```
 
-Defaults for installed harness/runtime paths live in
-`adapters/shared/path-defaults.json`.
+`actions` is the executable vocabulary. `call` exercises one action. `flows`
+lists reusable parameterized behavior from personal, team, and bundled recipe
+libraries. A recipe connects those capabilities into a deterministic proof.
+
+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.
 
-## Runtime-readiness ownership
+Use `mm-harness last --json` to resume after interruption without repeating a
+side-effecting command.
 
-Generic readiness mechanics live in `@farmslot/recipe-harness` (0.3+):
+## Team recipe libraries
 
-- `@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
+Add a named shared directory with `RECIPE_LIBRARY_PATH`:
 
-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.
+```bash
+export RECIPE_LIBRARY_PATH="team=$HOME/shared-library/team-recipes"
+mm-harness flows
+```
 
-## Dev/prod harness (`MM_HARNESS_BIN`)
+Team flows can wrap repeated product behavior while each checklist or task keeps
+its own acceptance criteria. See [recipe libraries](docs/recipe-libraries.md).
 
-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`:
+## Health and recovery
 
 ```bash
-export MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # dev: this checkout owns the run
-unset MM_HARNESS_BIN                                       # prod: the installed/global bin
+mm-harness 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
 ```
 
-`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.
+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.
 
-## Runtime notes
+## 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
+```
 
-- `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.
+Unset `MM_HARNESS_BIN` to return to the published install.
 
-## Validate changes
+Validate changes with:
 
 ```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
 ```
 
-More detail: [Architecture](docs/architecture.md), [Package boundaries](docs/package-boundaries.md), [Runtime file conventions](docs/runtime-file-conventions.md).
+Current references: [cheatsheet](docs/CHEATSHEET.md), [architecture](docs/architecture.md),
+[recipe libraries](docs/recipe-libraries.md), [human QA](docs/CLI-ERGONOMICS-HUMAN-QA.md),
+and the checked [video demo validation](docs/VIDEO-DEMO-VALIDATION.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> [--log <file>]
+//   console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-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,9 +19,10 @@
 'use strict';
 
 import { appendFileSync } from 'node:fs';
+import path from 'node:path';
 
 function parseArgs(argv) {
-  const args = { cdpPort: null, log: null };
+  const args = { cdpPort: null, extensionLog: null, dappLog: null };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     switch (arg) {
@@ -29,12 +30,16 @@ function parseArgs(argv) {
         args.cdpPort = argv[++i];
         break;
       case '--log':
-        args.log = argv[++i];
+      case '--extension-log':
+        args.extensionLog = argv[++i];
+        break;
+      case '--dapp-log':
+        args.dappLog = argv[++i];
         break;
       case '-h':
       case '--help':
         process.stdout.write(
-          'Usage: console-tail.mjs --cdp-port <port> [--log <file>]\n',
+          'Usage: console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>]\n',
         );
         process.exit(0);
         break;
@@ -51,6 +56,9 @@ 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.');
@@ -65,9 +73,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) {
+function out(line, destination = null) {
   process.stdout.write(`${line}\n`);
-  if (args.log) appendFileSync(args.log, `${line}\n`);
+  if (destination) appendFileSync(destination, `${line}\n`);
 }
 
 function stamp() {
@@ -95,6 +103,22 @@ 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) {
@@ -108,29 +132,29 @@ function previewArg(arg) {
   return arg.subtype || arg.type || '?';
 }
 
-function emitConsole(label, params) {
+function emitConsole(label, params, destination) {
   const level = String(params.type || 'log').toUpperCase();
   const text = (params.args || []).map(previewArg).join(' ');
-  out(`${stamp()} [${label}] ${level}  ${text}`);
+  out(`${stamp()} [${label}] ${level}  ${text}`, destination);
 }
 
-function emitException(label, params) {
+function emitException(label, params, destination) {
   const d = params.exceptionDetails || {};
   const text =
     d.exception?.description ||
     d.exception?.value ||
     d.text ||
     'uncaught exception';
-  out(`${stamp()} [${label}] EXCEPTION  ${text}`);
+  out(`${stamp()} [${label}] EXCEPTION  ${text}`, destination);
 }
 
-function emitLogEntry(label, params) {
+function emitLogEntry(label, params, destination) {
   const e = params.entry || {};
   const level = String(e.level || 'log').toUpperCase();
-  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`);
+  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`, destination);
 }
 
-function handleMessage(label, data) {
+function handleMessage(label, destination, data) {
   let message;
   try {
     message = JSON.parse(data);
@@ -141,13 +165,13 @@ function handleMessage(label, data) {
   if (message.id != null) return; // command ack, not an event
   switch (message.method) {
     case 'Runtime.consoleAPICalled':
-      emitConsole(label, message.params || {});
+      emitConsole(label, message.params || {}, destination);
       break;
     case 'Runtime.exceptionThrown':
-      emitException(label, message.params || {});
+      emitException(label, message.params || {}, destination);
       break;
     case 'Log.entryAdded':
-      emitLogEntry(label, message.params || {});
+      emitLogEntry(label, message.params || {}, destination);
       break;
     default:
       break;
@@ -155,9 +179,11 @@ function handleMessage(label, data) {
 }
 
 function attach(target) {
-  const label = shortLabel(target);
+  const stream = targetStream(target);
+  if (!stream) return;
+  const label = `${stream.kind}:${shortLabel(target)}`;
   const ws = new WebSocket(target.webSocketDebuggerUrl);
-  const entry = { ws, label, opened: false };
+  const entry = { ws, label, destination: stream.log, opened: false };
   attached.set(target.id, entry);
 
   ws.addEventListener('open', () => {
@@ -166,16 +192,16 @@ function attach(target) {
     for (const method of ['Runtime.enable', 'Log.enable']) {
       ws.send(JSON.stringify({ id: ++id, method, params: {} }));
     }
-    out(`${stamp()} [${label}] [attached]`);
+    out(`${stamp()} [${label}] [attached]`, stream.log);
   });
   ws.addEventListener('message', (event) => {
-    handleMessage(label, typeof event.data === 'string' ? event.data : '');
+    handleMessage(label, stream.log, 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`);
+      out(`${stamp()} [${label}] [reconnect] target detached; will re-attach`, stream.log);
     } else {
       // Never connected (target gone / not debuggable yet): back off so a dead
       // target is not retried — and logged — on every 2s poll.
@@ -196,8 +222,9 @@ async function poll() {
     // CDP not reachable this tick (browser starting/restarting); retry next poll.
     return;
   }
-  for (const target of Array.isArray(targets) ? targets : []) {
-    if (!isExtensionTarget(target)) continue;
+  const targetList = Array.isArray(targets) ? targets : [];
+  for (const target of targetList) {
+    if (!targetStream(target)) continue;
     if (attached.has(target.id)) continue;
     const until = cooldown.get(target.id);
     if (until !== undefined) {
@@ -226,6 +253,6 @@ function shutdown() {
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
 
-out(`${stamp()} [console-tail] streaming extension console via cdp ${cdpPort}`);
+out(`${stamp()} [console-tail] streaming extension and dapp consoles via cdp ${cdpPort}`);
 await poll();
 setInterval(poll, 2000);

package/adapters/extension/inject.mjs

@@ -94,16 +94,16 @@ copyDir(path.join(runnerDir, 'library/recipes'), path.join(harnessDir, 'runner/r
 copyFile(path.join(runnerDir, 'library/library.json'), path.join(harnessDir, 'runner/library.json'));
 fs.mkdirSync(path.join(harnessDir, 'runner/flows'), { recursive: true });
 copyDir(path.join(runnerDir, 'library/flows'), path.join(harnessDir, 'runner/flows'));
-// Installed-layout back-compat (INTENTIONAL): targets keep a flat
-// <harness>/scripts/ subtree assembled from the runner trees, so installed
-// consumers are unaffected by runner-repo layout changes.
+// The installed overlay has a flat scripts/ runtime API independent of the
+// package's source layout.
 copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-browser.cjs'));
-// installed back-compat alias: callers of the pre-rename installed name
-copyFile(path.join(runnerDir, 'adapters/extension/launch-browser.cjs'), path.join(harnessDir, 'scripts/launch-chrome-detached.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/console-tail.mjs'), path.join(harnessDir, 'scripts/console-tail.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/launch.sh'), path.join(harnessDir, 'scripts/launch.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/live.sh'), path.join(harnessDir, 'scripts/live.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/start-watch.sh'), path.join(harnessDir, 'scripts/start-watch.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/launch-webpack.cjs'), path.join(harnessDir, 'scripts/launch-webpack.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/sync-webpack-dist.cjs'), path.join(harnessDir, 'scripts/sync-webpack-dist.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/stamp-runtime-title.cjs'), path.join(harnessDir, 'scripts/stamp-runtime-title.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/stop-viewers.sh'), path.join(harnessDir, 'scripts/stop-viewers.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/snapshot-dist.sh'), path.join(harnessDir, 'scripts/snapshot-dist.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/pin-remote-flags.cjs'), path.join(harnessDir, 'scripts/pin-remote-flags.cjs'));
@@ -120,10 +120,6 @@ copyFile(path.join(runnerDir, 'adapters/shared/activate-repo-node.sh'), path.joi
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports.sh'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports.mjs'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports.mjs'));
 copyFile(path.join(runnerDir, 'adapters/shared/resolve-slot-ports-core.mjs'), path.join(harnessDir, 'scripts/lib/resolve-slot-ports-core.mjs'));
-// Back-compat shims (one release) so an overlay consumer using the old leaf names still resolves.
-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/tmux-session.sh'), path.join(harnessDir, 'scripts/lib/tmux-session.sh'));

package/adapters/extension/launch-webpack.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = {};
+for (let index = 2; index < process.argv.length; index += 1) {
+  const key = process.argv[index];
+  if (key === '--help' || key === '-h') {
+    process.stdout.write('Usage: launch-webpack.cjs --target <path> --log <path> --pid-file <path> --sync-script <path> --sync-pid-file <path> --sync-log <path> --dist <path> --runtime-dist <path> [--port <port>] [--path-prefix <path>]\n');
+    process.exit(0);
+  }
+  if (!key.startsWith('--') || index + 1 >= process.argv.length) throw new Error(`invalid argument: ${key}`);
+  args[key.slice(2)] = process.argv[++index];
+}
+
+async function main() {
+  for (const required of ['target', 'log', 'pid-file', 'sync-script', 'sync-pid-file', 'sync-log', 'dist', 'runtime-dist']) {
+    if (!args[required]) throw new Error(`--${required} is required`);
+  }
+
+  const target = path.resolve(args.target);
+  const log = path.resolve(args.log);
+  const pidFile = path.resolve(args['pid-file']);
+  const syncScript = path.resolve(args['sync-script']);
+  const syncPidFile = path.resolve(args['sync-pid-file']);
+  const syncLog = path.resolve(args['sync-log']);
+  fs.mkdirSync(path.dirname(log), { recursive: true });
+  fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+  fs.mkdirSync(path.dirname(syncLog), { recursive: true });
+  if (!fs.existsSync(syncScript)) throw new Error(`sync script not found: ${syncScript}`);
+  const logFd = fs.openSync(log, 'a');
+  const syncLogFd = fs.openSync(syncLog, 'a');
+  const env = { ...process.env };
+  if (args.port) env.PORT = String(args.port);
+  if (args['path-prefix']) env.PATH = `${args['path-prefix']}${env.PATH || ''}`;
+
+  try {
+    const child = spawn('yarn', ['start'], {
+      cwd: target,
+      detached: true,
+      env,
+      stdio: ['ignore', logFd, logFd],
+    });
+    await new Promise((resolve, reject) => {
+      child.once('spawn', resolve);
+      child.once('error', reject);
+    });
+    fs.writeFileSync(pidFile, `${child.pid}\n`);
+    const syncChild = spawn(process.execPath, [
+      syncScript,
+      '--watcher-pid', String(child.pid),
+      '--watch-log', log,
+      '--target', target,
+      '--dist', path.resolve(args.dist),
+      '--runtime-dist', path.resolve(args['runtime-dist']),
+      '--pid-file', syncPidFile,
+    ], {
+      cwd: target,
+      detached: true,
+      env,
+      stdio: ['ignore', syncLogFd, syncLogFd],
+    });
+    await new Promise((resolve, reject) => {
+      syncChild.once('spawn', resolve);
+      syncChild.once('error', reject);
+    });
+    fs.writeFileSync(syncPidFile, `${syncChild.pid}\n`);
+    process.stdout.write(`${child.pid}\n`);
+    syncChild.unref();
+    child.unref();
+  } finally {
+    fs.closeSync(logFd);
+    fs.closeSync(syncLogFd);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`launch-webpack: ${error.message}\n`);
+  process.exit(1);
+});