@deeeed/metamask-harness 0.3.9 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.4.0 - 2026-07-04
+
+Minor release: the adapter-surface architecture plus the day's feature wave (0.3.6-0.3.9 shipped fixes as they were validated live; this cut marks the surface additions honestly).
+
+### Added
+- **AdapterSurface** — one per-platform surface behind a common interface (`src/adapters/surface.ts`: resolveSlotPorts, runtimeStatus, devServer, logSources, hints); doctor/launch/stop/logs/debug/fixtures are surface-backed, so no verb hand-rolls platform branching. Contract: `docs/ADAPTER-SURFACE.md` (never-branch rule, add-a-platform checklist, migration table).
+- **Platform-adaptive `stop` on every adapter** — extension: kills this checkout's webpack watcher (pid file + orphan scan, slot-scoped) and closes its tail window; mobile: port-scoped Metro; core: headless teaching error. Idempotent, outcome-stating summaries.
+- **Doctor reports live runtime state on every adapter** — mobile Metro, extension webpack (via the extension readiness decision), core deps-only — one uniform shape, adapter-scoped colored context rows.
+- **`logs` is multi-source per adapter** — sources and the `--source` default come from the adapter's logSources (extension: webpack/watcher/rebuild/app).
+- **Context-aware examples and tier-visible flows** — `call` usage/help examples use the detected adapter's real manifest actions; `flows` prints a precedence legend decoding each source into personal > team > canonical.
+
+### Changed
+- **BREAKING (agent contract)**: `doctor --json` `runtime.metro` (string) is now `runtime.devServer` `{label, status}` and is absent for core.
+
+### Feature wave recap (0.3.6-0.3.9)
+- `mm-harness stop`; live-streamed mobile AND extension launches with upfront intent lines; presence-authoritative readiness (no setup-on-every-launch) with the dev-client running probe; slot-context-first device/port resolution; UTF-8 locale for pod spawns; DEV OVERRIDE banner + SLOT line + colored help; `mmdev-harness` completions; hermetic tmux-stubbed contract suite (now gating CI) + ESLint in `npm run check`; `docs/UX-PRINCIPLES.md` interaction contract.
+
 ## 0.3.9 - 2026-07-04
 
 ### Fixed
@@ -26,11 +43,19 @@
 - **Metro log-tail window no longer leaks into an unrelated tmux session** — running `start-metro` outside a tmux client fell back to `tmux display-message` (the last-attached session, e.g. the user's own) and created its `metro-<port>` window — with a `tail -F` — there, outliving the run. The viewer now opens a window only in a session that belongs to this run (a named slot session that exists, or the current session when actually inside tmux) and otherwise skips it; Metro still runs detached to the log. Extracted to `adapters/mobile/lib/tmux-viewer.sh` so the rule is unit-tested; contract tests stub tmux hermetically so no suite run can create a real window.
 
 ### Added
-- **`mm-harness stop`** — stop the port-scoped Metro dev server this mobile checkout owns and close its log-tail window (idempotent; extension/core are slot-managed and get a teaching error). Slot-context-aware port resolution.
+- **Adapter surface — one seam for per-platform behavior** — `src/adapters/surface.ts` defines `AdapterSurface` + a `getAdapterSurface(adapter)` registry that owns the behavior commands used to hand-roll with `if (adapter === …)` ladders (slot-port resolution, read-only runtime status, dev-server describe/stop, log sources, and platform-phrased Next: hints), with thin `mobile`/`extension`/`core` implementations that delegate to the existing readiness/port plumbing (re-homed to `src/adapters/slot-ports.ts`). `doctor`, `launch`, `stop`, `logs`, `debug`, and `fixtures` now resolve platform behavior through the surface instead of branching. This closes the platform-blind class of bug (a platform handled in one command but forgotten in another). Documented in `docs/ADAPTER-SURFACE.md`; enforces `docs/UX-PRINCIPLES.md` principle 1.
+- **`doctor` reports a runtime section for every adapter** — the live runtime readiness line (decision + reasons, deps currency, dev server) now renders for extension (webpack watcher via `decideExtensionReadiness`) and core (deps-presence-only), not just mobile; the render is one uniform shape sourced from the surface.
+- **`mm-harness stop` is adaptive per platform** — mobile stops its port-scoped Metro and closes the log-tail window; extension stops the checkout's webpack watcher (pid file + orphan ps-scan, slot-scoped) and closes its tail window; core teaches the headless path. All idempotent (nothing-to-stop is success), with a uniform summary and `--json` envelope.
+- **`logs` resolves dev-server log sources through the surface** — extension now recognizes the webpack, watcher, and rebuild logs (ordered), not only `webpack.log`; each platform's "nothing running" teaches its own launch hint. `--source` default and valid set come from the adapter's own log sources (extension defaults to `webpack`, not `metro`), and core teaches with platform-neutral wording (no Metro vocabulary). `--source <label>` now prefers that dev-server log.
+- **`call` with no action gives a context-aware example** — the usage error shows the DETECTED adapter and a REAL action from its manifest (a wallet action where one exists, else the universal `command`) plus the scoped `mm-harness actions --adapter <detected>` discovery hint. The static `call --help` example now uses real actions (`ensure_unlocked` / `command`) and points at `mm-harness actions`, instead of a hardcoded `call unlock --adapter extension` naming a non-existent `metamask.wallet.unlock`.
+- **`flows` surfaces the resolution tier per source** — `flows` prints a precedence legend mapping each resolved library source to its tier (`personal` / `team` / `canonical`), derived from the actual resolution, so the engine's `source=<name>` per flow is decodable and LOCAL libraries read as first-class; the tier is also named in the recipe-library-unavailable teaching error.
+- **`stop --help` matches the adaptive behavior** — the help text now describes mobile Metro / extension webpack watcher / core headless, instead of the stale "Metro dev server … extension/core: teaching error".
 - **Slot-context device/port detection** — `resolve-farmslot-ports.sh` reads `agentic-runtime.json` (the mapping the orchestrator's prepare wrote into the checkout) first, so device/port resolution survives pool renames that break any naming formula.
 - **CLI help surface** — grouped/colored `mm-harness` help, a `DEV OVERRIDE ACTIVE` banner when `MM_HARNESS_BIN` is set, and a `SLOT` line when the checkout is a prepared slot; `mmdev-harness` completion alias.
 
 ### Changed
+- **`doctor --json` runtime dev-server shape is normalized** — the mobile-only `runtime.metro` string is replaced by a platform-labelled `runtime.devServer: { label, status }` (`metro` for mobile, `webpack` for extension; absent for headless core), so agents read one shape across platforms.
+- **`yarn check` runs ESLint** — flat-config ESLint (typescript-eslint recommended on `src/**/*.ts`, `@eslint/js` recommended on the `.mjs`/`.cjs` library) runs after typecheck and comment-hygiene. Dev-only (not in the published `files`); the baseline is zero-warning by config scoping.
 - **Deps install uses a scoped `setup:expo` variant when native isn't wanted** — `adapters/mobile/yarn-setup.sh` gains `--mode full|expo`. `expo` runs `yarn setup:expo --no-build-ios --no-build-android` (JS deps + prebuild, no native — native builds come from `open-device.sh`, never doubled); the full `yarn setup` runs only for a native build (`launch --build`). This is also the standalone Metro-only remedy taught by the fast-tier deps block.
 - **`mm-harness runtime-decision --adapter mobile` accepts `--preflight-mode`** — surfaces the fast (presence, blocks on a genuine gap) vs full (installs) decision for inspection and callers.
 

package/docs/ADAPTER-SURFACE.md

@@ -0,0 +1,119 @@
+# The adapter surface — one seam for per-platform behavior
+
+`mm-harness` runs against three platforms (mobile | extension | core). The
+danger is that every command re-derives "what does this platform do?" with its
+own `if (adapter === 'mobile') … else if (adapter === 'extension') …` ladder.
+When it does, a platform gets forgotten in one command but not another — the
+class of bug where `doctor` reported a live runtime section for mobile only,
+`stop` refused every non-mobile adapter, and `logs` knew a single extension log
+file instead of all three. Those are *platform-blind* commands.
+
+The **adapter surface** is the fix: one interface per platform, resolved through
+a registry, that owns the behavior a command would otherwise branch on.
+
+## The interface
+
+`src/adapters/surface.ts` defines `AdapterSurface` and the registry
+`getAdapterSurface(adapter)`. Each platform ships one implementation:
+
+- `src/adapters/mobile/surface.ts`
+- `src/adapters/extension/surface.ts`
+- `src/adapters/core/surface.ts`
+
+```ts
+interface AdapterSurface {
+  readonly adapter: MetaMaskRecipeAdapter;
+  readonly headless: boolean;                       // core runs no app/dev server
+  resolveSlotPorts(target: string): void;           // context > pool > formula (no-op for core)
+  runtimeStatus(target: string): Promise<AdapterRuntimeStatus>; // read-only readiness for doctor
+  devServer: {
+    describe(): string;                             // "Metro" | "webpack watcher" | "no dev server (headless)"
+    stop(target: string): AdapterDevServerStop;     // idempotent, slot-scoped; headless = teach
+  };
+  logSources(target: string): AdapterLogSource[];   // ordered candidate log files (empty for core)
+  hints: { launch: string; relaunch: string };      // platform-phrased Next: hints
+}
+```
+
+`runtimeStatus` returns a normalized shape so `doctor` renders one line the same
+way for every platform:
+
+```ts
+interface AdapterRuntimeStatus {
+  decision: string;
+  reasonCode?: string;
+  reasons: string[];
+  deps?: string;
+  devServer?: { label: string; status: string };    // absent for headless core
+}
+```
+
+The implementations are thin: they delegate to the readiness/port plumbing that
+already existed (`decideExtensionReadiness`, `mobileRuntimeStatus`, the slot-port
+resolvers and the webpack-watcher stop, all re-homed to
+`src/adapters/slot-ports.ts`). The surface is an organizing seam, not a rewrite.
+
+## The rule
+
+**A command never branches on adapter for behavior the surface owns.**
+
+- Do not write `if (adapter === 'core')` — ask `surface.headless`.
+- Do not write `adapter === 'mobile' ? metroPorts() : extensionPorts()` — call
+  `surface.resolveSlotPorts(target)`.
+- Do not print `adapter === 'mobile' ? 'mm-harness launch ios' : 'mm-harness
+  launch'` — use `surface.hints.launch`.
+
+A new platform behavior is added by **extending the surface** (a new member on
+the interface plus its three implementations), never by adding another branch to
+a command. TypeScript then makes it impossible to ship a platform that forgot the
+new member, because each implementation is annotated `: AdapterSurface`.
+
+What the surface deliberately does **not** own: a command may still branch on
+adapter for a *mechanism* that is genuinely platform-specific and not part of the
+interface — e.g. `fixtures set` uses a shell arm on mobile and the engine path on
+extension. Those branches select a mechanism; they never re-derive readiness,
+ports, log locations, dev-server lifecycle, or Next: phrasing, which are the
+surface's responsibility.
+
+## Migration status
+
+Every command that used to branch on adapter now resolves through the surface:
+
+| command | surface-backed | uses |
+| --- | --- | --- |
+| `doctor` | yes | `resolveSlotPorts` + `runtimeStatus` (mobile/extension/core runtime section) |
+| `launch` | yes | `resolveSlotPorts` |
+| `stop` | yes | `resolveSlotPorts` + `devServer.stop` (+ headless teaching) |
+| `logs` | yes | `logSources` + `hints.launch` + `headless` |
+| `debug` | yes | `headless` + `hints.relaunch` (core teaching); flag semantics stay per-command |
+| `fixtures` | yes | `headless` + `hints` (retry/launch); the set *mechanism* stays per-platform |
+| `run` / `call` | n/a | engine path; core-headless is handled by the heal contract, not the surface |
+| `flows` | no (by design) | recipe-library flows are adapter-global; not a platform-owned behavior |
+| `completion-candidates` | partial | `actions` scope to the detected checkout adapter; `flows` are adapter-global |
+
+`flows` is intentionally not surface-backed: a recipe-library flow can compose
+actions across platforms, so flows are adapter-global by design rather than a
+platform-blind gap. `completion-candidates actions` already resolves the adapter
+from the checkout context (cwd/`--target`); only the adapter-global `flows`
+candidates are unscoped, matching the flows model.
+
+## How this composes with the UX principles
+
+`docs/UX-PRINCIPLES.md` principle 1 (*Context-aware by default* — "output is
+scoped to the platform… help, flag lists, and completion candidates shrink to
+what applies here") states the intent. The adapter surface is its **enforcement
+mechanism**: a command that resolves platform behavior through the surface is
+context-aware by construction, and one that hand-rolls an adapter ladder is the
+exact failure principle 1 warns against. When adding a command or output path,
+satisfy principle 1 by going through the surface.
+
+## Adding a platform behavior — checklist
+
+1. Add the member to `AdapterSurface` in `src/adapters/surface.ts`.
+2. Implement it in all three `src/adapters/*/surface.ts` (TypeScript will not
+   compile until you do).
+3. Have the command call `getAdapterSurface(adapter).<member>` instead of
+   branching.
+4. Cover the closed blind spot with a contract test (see
+   `tests/contract/adapter-surface.test.sh`), and keep the registry-completeness
+   assertion green.

package/docs/UX-PRINCIPLES.md

@@ -19,6 +19,9 @@ The CLI answers relative to the checkout it is standing in.
   hardcode pool prefixes (they go stale on rename).
 - Output is scoped to the platform: an extension-only field is noise on a mobile
   slot; help, flag lists, and completion candidates shrink to what applies here.
+- Enforcement: platform-specific behavior is resolved through the adapter surface
+  (`getAdapterSurface(adapter)`), never a per-command `if (adapter === …)` ladder —
+  that ladder is how commands go platform-blind. See docs/ADAPTER-SURFACE.md.
 
 ## 2. Never silent, never opaque
 Long operations show intent immediately and progress continuously.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -26,8 +26,12 @@
     "ws": "8.21.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9",
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "eslint": "^9",
+    "globals": "^17.7.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8"
   },
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/adapters/core/surface.ts

@@ -0,0 +1,56 @@
+// Core surface: headless. No app, no dev server — dependency presence is the
+// only runtime signal, and lifecycle commands teach the reachable headless path.
+import path from 'node:path';
+
+import { depsCheck } from '@farmslot/recipe-harness/runtime/deps-readiness';
+
+import type {
+  AdapterDevServerStop,
+  AdapterLogSource,
+  AdapterRuntimeStatus,
+  AdapterSurface,
+} from '../surface.ts';
+
+export const coreSurface: AdapterSurface = {
+  adapter: 'core',
+  headless: true,
+
+  resolveSlotPorts(): void {
+    // Headless: no ports or device to resolve.
+  },
+
+  async runtimeStatus(target: string): Promise<AdapterRuntimeStatus> {
+    const deps = depsCheck(path.resolve(target));
+    const ready = deps.status === 'current';
+    return {
+      decision: ready ? 'ready' : 'install',
+      reasonCode: ready ? 'deps-present' : `deps-${deps.status}`,
+      reasons: [
+        ready
+          ? 'Core is headless; dependencies are installed. Run recipes with mm-harness run.'
+          : 'Core is headless; dependencies are not fully installed.',
+      ],
+      deps: deps.status,
+    };
+  },
+
+  devServer: {
+    describe: () => 'no dev server (headless)',
+    stop(): AdapterDevServerStop {
+      return {
+        kind: 'headless',
+        message: 'core is headless — no dev server runs for a core checkout',
+        userAction: 'use mm-harness verify (readiness) or mm-harness run (execute a recipe)',
+      };
+    },
+  },
+
+  logSources(): AdapterLogSource[] {
+    return [];
+  },
+
+  hints: {
+    launch: 'mm-harness run <recipe>   # run recipes against the headless core',
+    relaunch: 'mm-harness verify',
+  },
+};

package/src/adapters/extension/surface.ts

@@ -0,0 +1,71 @@
+// Extension surface: delegates to the existing extension readiness/port plumbing
+// and the webpack watcher stop.
+import { spawnSync } from 'node:child_process';
+
+import { recipeRuntimePath } from '../../paths.ts';
+import { resolveExtensionSlotPorts, stopExtensionWatcher } from '../slot-ports.ts';
+import { decideExtensionReadiness } from './runtime-decision.ts';
+import type {
+  AdapterDevServerStop,
+  AdapterLogSource,
+  AdapterRuntimeStatus,
+  AdapterSurface,
+} from '../surface.ts';
+
+// Map the webpack watch-log health onto a dev-server up/down/building/errors
+// status doctor renders the same way as mobile's Metro line.
+function watcherStatus(buildLog: string): string {
+  if (buildLog === 'ok') return 'up';
+  if (buildLog === 'no-watch') return 'down';
+  return buildLog; // 'building' | 'errors'
+}
+
+export const extensionSurface: AdapterSurface = {
+  adapter: 'extension',
+  headless: false,
+
+  resolveSlotPorts(target: string): void {
+    resolveExtensionSlotPorts(target);
+  },
+
+  async runtimeStatus(target: string): Promise<AdapterRuntimeStatus> {
+    const cdpPort = process.env.CDP_PORT ? parseInt(process.env.CDP_PORT, 10) : undefined;
+    const report = await decideExtensionReadiness(target, { cdpPort });
+    return {
+      decision: report.decision,
+      reasonCode: report.reasonCode,
+      reasons: report.reasons,
+      deps: report.checks.deps.status,
+      devServer: { label: 'webpack', status: watcherStatus(report.checks.buildLog.status) },
+    };
+  },
+
+  devServer: {
+    describe: () => 'webpack watcher',
+    stop(target: string): AdapterDevServerStop {
+      const signalled = stopExtensionWatcher(target);
+      // Best-effort: close the webpack tail window this checkout's watcher owned.
+      const port = process.env.WATCHER_PORT ?? 'default';
+      spawnSync('tmux', ['kill-window', '-t', `webpack-${port}`], { stdio: 'ignore', timeout: 2000 });
+      const summary = signalled > 0
+        ? `stopped webpack watcher (${signalled} process${signalled === 1 ? '' : 'es'}) for ${target}`
+        : `webpack watcher not running for ${target} — nothing to stop`;
+      return { kind: 'stopped', status: 0, summary, signalled };
+    },
+  },
+
+  logSources(target: string): AdapterLogSource[] {
+    // Most-relevant first: the live webpack log, the harness-owned watcher log,
+    // then the quick-relaunch rebuild log. `logs` tails the first that exists.
+    return [
+      { label: 'webpack', path: recipeRuntimePath(target, 'webpack.log') },
+      { label: 'watcher', path: recipeRuntimePath(target, 'recipe-harness-webpack.log') },
+      { label: 'rebuild', path: recipeRuntimePath(target, 'rebuild.log') },
+    ];
+  },
+
+  hints: {
+    launch: 'mm-harness launch',
+    relaunch: 'mm-harness launch --build',
+  },
+};

package/src/adapters/mobile/surface.ts

@@ -0,0 +1,59 @@
+// Mobile surface: delegates to the existing mobile readiness/port plumbing.
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import { recipeRuntimePath, runnerDir } from '../../paths.ts';
+import { resolveMobileSlotPorts } from '../slot-ports.ts';
+import { mobileRuntimeStatus } from './prepare.ts';
+import type {
+  AdapterDevServerStop,
+  AdapterLogSource,
+  AdapterRuntimeStatus,
+  AdapterSurface,
+} from '../surface.ts';
+
+export const mobileSurface: AdapterSurface = {
+  adapter: 'mobile',
+  headless: false,
+
+  resolveSlotPorts(target: string): void {
+    resolveMobileSlotPorts(target);
+  },
+
+  async runtimeStatus(target: string): Promise<AdapterRuntimeStatus> {
+    const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : undefined;
+    const report = await mobileRuntimeStatus(target, { watcherPort });
+    return {
+      decision: report.decision,
+      reasonCode: report.reasonCode,
+      reasons: report.reasons,
+      deps: report.checks?.deps?.status,
+      devServer: { label: 'metro', status: report.checks?.metro?.status ?? 'unprobed' },
+    };
+  },
+
+  devServer: {
+    describe: () => 'Metro dev server',
+    stop(target: string): AdapterDevServerStop {
+      const leaf = path.join(runnerDir, 'adapters', 'mobile', 'stop-metro.sh');
+      const args = ['--target', target];
+      if (process.env.WATCHER_PORT) args.push('--port', process.env.WATCHER_PORT);
+      const result = spawnSync('bash', [leaf, ...args], { encoding: 'utf8' });
+      const status = result.status ?? 1;
+      const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();
+      const summary = status === 0
+        ? `stopped Metro dev server for ${target}`
+        : `failed to stop Metro for ${target}`;
+      return { kind: 'stopped', status, summary, output };
+    },
+  },
+
+  logSources(target: string): AdapterLogSource[] {
+    return [{ label: 'metro', path: recipeRuntimePath(target, 'metro.log') }];
+  },
+
+  hints: {
+    launch: 'mm-harness launch ios',
+    relaunch: 'mm-harness launch ios',
+  },
+};

package/src/adapters/slot-ports.ts

@@ -0,0 +1,165 @@
+// Slot-port + dev-server process plumbing shared by the per-platform surfaces.
+// Re-homed here (out of commands/launch.ts) so the surface implementations own
+// port/device resolution and the extension watcher-stop without launch.ts and
+// the surface registry forming an import cycle.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readRuntimeContextField, resolveRuntimeContextPath } from '../harness.ts';
+import { recipeRuntimeDir, runnerDir } from '../paths.ts';
+
+// Apply KEY=VALUE lines from slot resolution to process.env.
+// overwrite=true → pool/context match, always overrides existing env.
+// overwrite=false → formula match, only fills vars that are unset.
+export function applyKVLines(output: string, overwrite: boolean): void {
+  for (const line of output.split('\n')) {
+    const m = /^([A-Z_]+)=(.+)$/u.exec(line.trim());
+    if (!m) continue;
+    const [, key, val] = m;
+    switch (key) {
+      case 'WATCHER_PORT':
+        if (overwrite || !process.env['WATCHER_PORT']) {
+          process.env['WATCHER_PORT'] = val;
+          process.env['METRO_PORT'] = val;
+          process.env['RECIPE_WATCHER_PORT'] = val;
+        }
+        break;
+      case 'IOS_SIMULATOR':
+        if (overwrite || !process.env['IOS_SIMULATOR']) process.env['IOS_SIMULATOR'] = val;
+        break;
+      case 'SLOT_ID':
+        if (overwrite || !process.env['RECIPE_SLOT_ID']) process.env['RECIPE_SLOT_ID'] = val;
+        break;
+      case 'CDP_PORT':
+        if (overwrite || !process.env['CDP_PORT']) {
+          process.env['CDP_PORT'] = val;
+          process.env['RECIPE_CDP_PORT'] = val;
+        }
+        break;
+    }
+  }
+}
+
+function sourceResolve(fn: string, target: string): string {
+  const resolveScript = path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh');
+  try {
+    return execFileSync('bash', ['-c', `source "${resolveScript}" && ${fn} "${target}"`], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return '';
+  }
+}
+
+// Resolve mobile slot port/simulator: the slot context the orchestrator wrote
+// into the checkout wins first, then the farmslot pool (both overwrite env),
+// then the slot-suffix formula (only fills unset vars). Called before explicit
+// CLI flag overrides so flags always win at the top.
+export function resolveMobileSlotPorts(target: string): void {
+  // The checkout's own runtime context is authoritative — it names the exact
+  // simulator/port this slot was prepared with, surviving pool renames.
+  const ctxOut = sourceResolve('resolve_mobile_runtime_context', target);
+  if (ctxOut.trim()) {
+    applyKVLines(ctxOut, true);
+    return;
+  }
+  // Pool match always wins — overwrite whatever is in the environment.
+  const poolOut = sourceResolve('resolve_farmslot_ports_by_repo', target);
+  if (poolOut.trim()) {
+    applyKVLines(poolOut, true);
+    return;
+  }
+  // Formula match only fills unset vars (never overrides explicit env/pool).
+  const defOut = sourceResolve('resolve_mobile_slot_defaults', target);
+  if (defOut.trim()) applyKVLines(defOut, false);
+}
+
+// Resolve extension slot ports the same way as mobile: the checkout's runtime
+// context first (cdpPort/devServerPort written by the orchestrator's prepare),
+// then the farmslot pool, then the directory-suffix formula (fills unset only).
+export function resolveExtensionSlotPorts(target: string): void {
+  // The prepared checkout's context OVERWRITES inherited env (same authority as
+  // mobile's context/pool resolution): a stale CDP_PORT from the shell must not
+  // hijack the slot's browser. Explicit CLI flags are applied after and win.
+  const contextPath = resolveRuntimeContextPath(target);
+  const cdp = readRuntimeContextField(contextPath, 'cdpPort');
+  if (cdp) {
+    process.env['CDP_PORT'] = cdp;
+    process.env['RECIPE_CDP_PORT'] = cdp;
+  }
+  const dev = readRuntimeContextField(contextPath, 'devServerPort');
+  if (dev) {
+    process.env['WATCHER_PORT'] = dev;
+    process.env['RECIPE_WATCHER_PORT'] = dev;
+  }
+  if (process.env['CDP_PORT']) return;
+  const poolOut = sourceResolve('resolve_farmslot_ports_by_repo', target);
+  if (poolOut.trim()) {
+    applyKVLines(poolOut, true);
+    return;
+  }
+  const defOut = sourceResolve('resolve_default_extension_ports', target);
+  if (defOut.trim()) applyKVLines(defOut, false);
+}
+
+// Kill the harness-owned webpack watcher for this checkout: pid file first,
+// then a ps-scan for orphans (argv or lsof-cwd match), TERM then KILL. Scoped
+// to the target checkout — watchers of other slots are never touched. Returns
+// how many processes were signalled so callers can state the outcome.
+export function stopExtensionWatcher(target: string): number {
+  const runtimeAbs = path.join(target, recipeRuntimeDir());
+  const webpackPidFile = path.join(runtimeAbs, 'recipe-harness-webpack.pid');
+  let signalled = 0;
+  try {
+    const pid = fs.readFileSync(webpackPidFile, 'utf8').trim();
+    if (/^\d+$/u.test(pid)) {
+      try { process.kill(Number(pid), 'SIGTERM'); signalled += 1; } catch { /* already dead */ }
+    }
+    fs.rmSync(webpackPidFile, { force: true });
+  } catch { /* no pid file */ }
+  // Scan for any remaining orphan webpack/yarn-start processes in this checkout.
+  try {
+    const psOut = execFileSync('ps', ['-axo', 'pid=,command='], { encoding: 'utf8' });
+    const orphanPids: number[] = [];
+    for (const line of psOut.split('\n')) {
+      const match = /^\s*(\d+)\s+(.*)$/u.exec(line);
+      if (!match) continue;
+      const [, pidStr, cmd] = match;
+      const isWatcher =
+        cmd.includes('yarn start') ||
+        cmd.includes('webpack --watch') ||
+        cmd.includes('development/webpack/launch.ts --watch');
+      if (!isWatcher) continue;
+      if (cmd.includes(target)) {
+        orphanPids.push(Number(pidStr));
+        continue;
+      }
+      // lsof cwd fallback for processes that don't embed the path in argv.
+      try {
+        const cwd = execFileSync('lsof', ['-a', `-p${pidStr}`, '-dcwd', '-Fn'], {
+          encoding: 'utf8',
+          timeout: 2000,
+        });
+        if (cwd.split('\n').some((l) => l.startsWith('n') && l.slice(1) === target)) {
+          orphanPids.push(Number(pidStr));
+        }
+      } catch { /* lsof unavailable or permission denied */ }
+    }
+    if (orphanPids.length > 0) {
+      for (const pid of orphanPids) {
+        try { process.kill(pid, 'SIGTERM'); } catch { /* already dead */ }
+      }
+      // Brief pause then force-kill survivors.
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2000);
+      for (const pid of orphanPids) {
+        try { process.kill(pid, 'SIGKILL'); } catch { /* already dead */ }
+      }
+      signalled += orphanPids.length;
+    }
+  } catch { /* ps not available */ }
+  return signalled;
+}

package/src/adapters/surface.ts

@@ -0,0 +1,82 @@
+// The per-platform surface: one interface every command resolves platform
+// behavior through, so no command hand-rolls `if (adapter === …)` for behavior a
+// platform owns. A command NEVER branches on adapter for behavior this interface
+// owns; a new platform behavior extends the surface (a new member here + its
+// three implementations), not the command. This is the enforcement mechanism for
+// UX-PRINCIPLES.md principle 1 (context-aware by default). See
+// docs/ADAPTER-SURFACE.md.
+
+import type { MetaMaskRecipeAdapter } from '../types.ts';
+import { coreSurface } from './core/surface.ts';
+import { extensionSurface } from './extension/surface.ts';
+import { mobileSurface } from './mobile/surface.ts';
+
+// Read-only runtime readiness, normalized across platforms so `doctor` renders
+// one line the same way regardless of adapter. Device platforms fill deps +
+// devServer; core (headless) reports deps presence only (no devServer).
+export interface AdapterRuntimeStatus {
+  decision: string;
+  reasonCode?: string;
+  reasons: string[];
+  deps?: string;
+  // The platform's dev server (Metro for mobile, webpack watcher for extension),
+  // labelled so the render names the right thing. Absent for headless core.
+  devServer?: { label: string; status: string };
+}
+
+// One log file a platform writes, most-relevant first. `logs` tails the first
+// candidate that exists.
+export interface AdapterLogSource {
+  label: string;
+  path: string;
+}
+
+// Result of stopping the platform's dev server. `headless` is the core case —
+// there is nothing to stop, so `stop` teaches instead. `stopped` carries the
+// exit status plus, when the platform counts them, how many processes were
+// signalled and the raw leaf output for the --json envelope.
+export type AdapterDevServerStop =
+  | { kind: 'headless'; message: string; userAction: string }
+  | { kind: 'stopped'; status: number; summary: string; signalled?: number; output?: string };
+
+export interface AdapterDevServer {
+  // One noun for the dev server this platform runs ("Metro", "webpack watcher").
+  describe(): string;
+  // Stop the dev server this checkout owns, port/pid-scoped. Idempotent:
+  // nothing-to-stop is success, never an error.
+  stop(target: string): AdapterDevServerStop;
+}
+
+// Platform-phrased Next: hints so no command prints another platform's vocabulary.
+// `launch` (re)starts the app + dev server; `relaunch` rebuilds first (the
+// fixtures-set retry). core has no app, so its hints teach the headless path.
+export interface AdapterHints {
+  launch: string;
+  relaunch: string;
+}
+
+export interface AdapterSurface {
+  readonly adapter: MetaMaskRecipeAdapter;
+  // core runs no app/dev server; device adapters (mobile/extension) do. Commands
+  // ask this instead of testing `adapter === 'core'`.
+  readonly headless: boolean;
+  // Resolve slot ports/device into the environment (checkout context > pool >
+  // formula). No-op for core.
+  resolveSlotPorts(target: string): void;
+  // Read-only readiness for `doctor`. Never launches or mutates.
+  runtimeStatus(target: string): Promise<AdapterRuntimeStatus>;
+  devServer: AdapterDevServer;
+  // Ordered candidate log files for `logs`. Empty for core.
+  logSources(target: string): AdapterLogSource[];
+  hints: AdapterHints;
+}
+
+const SURFACES: Record<MetaMaskRecipeAdapter, AdapterSurface> = {
+  mobile: mobileSurface,
+  extension: extensionSurface,
+  core: coreSurface,
+};
+
+export function getAdapterSurface(adapter: MetaMaskRecipeAdapter): AdapterSurface {
+  return SURFACES[adapter];
+}

package/src/cli.ts

@@ -28,6 +28,8 @@ import { ensureExtensionReady } from './adapters/extension/ensure-ready.ts';
 import { resolveExtensionId } from './adapters/extension/extension-id.ts';
 import { decideExtensionReadiness } from './adapters/extension/runtime-decision.ts';
 import { decideMobileReadiness } from './adapters/mobile/runtime-decision.ts';
+import { getAdapterSurface } from './adapters/surface.ts';
+import type { AdapterRuntimeStatus } from './adapters/surface.ts';
 // NOTE: extension-runtime.ts loads the recipe harness at module scope, so it
 // is imported LAZILY (dynamic import) only inside the handlers that drive a live
 // runtime. Static-import it here and every command — manifest, doctor,
@@ -476,26 +478,16 @@ async function handleDoctor({ options }: ParsedArgs): Promise<number> {
   }
 
   const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-  // Live runtime state, per platform: mobile reports the same read-only readiness
-  // the launch decision uses (deps currency, Metro on the slot's port, decision +
-  // reasons). Extension/core gain their sections when their readiness probes exist.
-  let runtime: { decision: string; reasonCode?: string; reasons: string[]; deps?: string; metro?: string } | undefined;
-  if (adapter === 'mobile') {
-    try {
-      const { mobileRuntimeStatus } = await import('./adapters/mobile/prepare.ts');
-      const { resolveMobileSlotPorts } = await import('./commands/launch.ts');
-      resolveMobileSlotPorts(target);
-      const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : undefined;
-      const report = await mobileRuntimeStatus(target, { watcherPort });
-      runtime = {
-        decision: report.decision,
-        reasonCode: report.reasonCode,
-        reasons: report.reasons,
-        deps: report.checks?.deps?.status,
-        metro: report.checks?.metro?.status,
-      };
-    } catch { /* readiness probe unavailable — doctor stays useful without it */ }
-  }
+  // Live runtime state, per platform, via the adapter surface: every adapter
+  // reports the same read-only readiness shape (decision + reasons, deps currency,
+  // and its dev server where it has one) so doctor renders one line the same way
+  // for mobile, extension, and core. doctor never branches on adapter for this.
+  let runtime: AdapterRuntimeStatus | undefined;
+  try {
+    const surface = getAdapterSurface(adapter);
+    surface.resolveSlotPorts(target);
+    runtime = await surface.runtimeStatus(target);
+  } catch { /* readiness probe unavailable — doctor stays useful without it */ }
   if (json) console.log(JSON.stringify({ ...result, runtime }, null, 2));
   else {
     const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
@@ -503,8 +495,11 @@ async function handleDoctor({ options }: ParsedArgs): Promise<number> {
     console.log(`${out(result.status === 'pass' ? 'ok' : 'err', result.status)} ${out('bold', adapter)} ${result.compatibilityMode} ${out('dim', `manifest=${actionManifestPath}`)}`);
     if (runtime) {
       const decisionStyle = runtime.decision === 'ready' ? 'ok' : runtime.decision === 'blocked' ? 'err' : 'warn';
+      const devServer = runtime.devServer
+        ? ` ${runtime.devServer.label}=${out(stateStyle(runtime.devServer.status, 'up'), runtime.devServer.status)}`
+        : '';
       console.log(
-        `${out('label', 'runtime:')} decision=${out(decisionStyle, runtime.decision)}${runtime.reasonCode ? ` ${out('dim', `(${runtime.reasonCode})`)}` : ''} deps=${out(stateStyle(runtime.deps, 'current'), runtime.deps ?? 'unknown')} metro=${out(stateStyle(runtime.metro, 'up'), runtime.metro ?? 'unprobed')}`,
+        `${out('label', 'runtime:')} decision=${out(decisionStyle, runtime.decision)}${runtime.reasonCode ? ` ${out('dim', `(${runtime.reasonCode})`)}` : ''} deps=${out(stateStyle(runtime.deps, 'current'), runtime.deps ?? 'unknown')}${devServer}`,
       );
       for (const reason of runtime.reasons) console.log(`  ${out('dim', reason)}`);
     }
@@ -1117,23 +1112,21 @@ async function handleStop(argv: string[]): Promise<number> {
   const { options } = parseArgs(argv, 'stop');
   const json = optionFlag(options, 'json');
   const { adapter, target } = resolveAdapter(options);
-  if (adapter !== 'mobile') {
-    return usageOut(
-      json,
-      'stop',
-      `stop owns the mobile Metro dev server; the ${adapter} dev server is slot-managed`,
-      'stop the extension watcher via its runtime pids: kill $(cat <runtime_dir>/webpack.pid); core runs no dev server',
-    );
+  const surface = getAdapterSurface(adapter);
+  // Slot-scope the stop: an explicit --port wins, else resolve the checkout's
+  // own dev-server port so a concurrent slot's server is never signalled.
+  const explicitPort = optionString(options, 'port') ?? optionString(options, 'watcherPort');
+  if (explicitPort) {
+    process.env.WATCHER_PORT = explicitPort;
+    process.env.METRO_PORT = explicitPort;
+  } else {
+    surface.resolveSlotPorts(target);
+  }
+  const stop = surface.devServer.stop(target);
+  if (stop.kind === 'headless') {
+    // core has no dev server — teach the reachable headless path (exit 2).
+    return usageOut(json, 'stop', stop.message, stop.userAction);
   }
-  const leaf = path.join(runnerDir, 'adapters', 'mobile', 'stop-metro.sh');
-  const args = ['--target', target];
-  const port = optionString(options, 'port') ?? optionString(options, 'watcherPort');
-  if (port) args.push('--port', port);
-  const result = spawnSync('bash', [leaf, ...args], {
-    stdio: json ? 'pipe' : 'inherit',
-    encoding: 'utf8',
-  });
-  const exitCode = result.status ?? 1;
   if (json) {
     console.log(
       JSON.stringify(
@@ -1142,16 +1135,22 @@ async function handleStop(argv: string[]): Promise<number> {
           command: 'stop',
           adapter,
           target,
-          status: exitCode === 0 ? 'pass' : 'fail',
-          exitCode,
-          output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim(),
+          status: stop.status === 0 ? 'pass' : 'fail',
+          ...(stop.signalled !== undefined ? { signalled: stop.signalled } : {}),
+          exitCode: stop.status,
+          ...(stop.output ? { output: stop.output } : {}),
         },
         null,
         2,
       ),
     );
+  } else {
+    // The leaf may have captured its own detail; surface it, then the uniform
+    // outcome line the same way for every platform.
+    if (stop.output) process.stderr.write(`${stop.output}\n`);
+    console.error(`${color(stop.status === 0 ? 'ok' : 'err', stop.status === 0 ? '✓' : '✗')} ${stop.summary}`);
   }
-  return exitCode;
+  return stop.status;
 }
 
 async function handleCall(argv: string[]): Promise<number> {
@@ -1168,9 +1167,23 @@ async function handleCall(argv: string[]): Promise<number> {
   const { options } = parseArgs(rest, 'call');
   const json = optionFlag(options, 'json');
   if (!shortName) {
-    const message = 'call requires <action>. Example: mm-harness call unlock --adapter extension';
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', error: { code: 'USAGE', message } }, null, 2));
-    else console.error(message);
+    // Context-aware usage: the example uses the DETECTED adapter and a REAL action
+    // from its manifest — never a hardcoded action/adapter that may not exist in
+    // this checkout — and points at the scoped discovery command.
+    let example = 'mm-harness call <action>';
+    let discovery = 'mm-harness actions';
+    try {
+      const { adapter } = resolveAdapter(options);
+      const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
+      const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+      const exampleAction = pickCallExampleAction(getRecipeActionManifestActionNames(manifest));
+      example = `mm-harness call ${exampleAction} --adapter ${adapter}`;
+      discovery = `mm-harness actions --adapter ${adapter}`;
+    } catch { /* adapter/manifest unavailable — keep the generic example */ }
+    const message = `call requires <action>. Example: ${example}`;
+    const userAction = `${example}   # see the vocabulary: ${discovery}`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', error: { code: 'USAGE', message, userAction } }, null, 2));
+    else console.error(`${message}\n  See the vocabulary: ${discovery}`);
     return EXIT.usage;
   }
 
@@ -1340,6 +1353,16 @@ function resolveActionName(shortName: string, names: string[]): ActionResolution
   return { status: 'unknown', resolved: '', candidates: [] };
 }
 
+// A real action name to show in the `call` usage example, from THIS adapter's
+// manifest: a wallet action when the platform has one, else the universal
+// `command` action, else the first declared name. Never a hardcoded guess.
+function pickCallExampleAction(names: string[]): string {
+  const walletish = names.find((name) => /wallet|unlock/u.test(name));
+  if (walletish) return walletish;
+  if (names.includes('command')) return 'command';
+  return names[0] ?? 'command';
+}
+
 function synthesizeOneNodeRecipe(action: string, args: Record<string, string>): Record<string, unknown> {
   return {
     schema_version: 1,
@@ -1794,6 +1817,16 @@ function serializeLibrarySources(sources: MetaMaskLibrarySource[]): string {
     .join(':');
 }
 
+// Map a resolved library source to its precedence tier for the flows legend, from
+// the ACTUAL resolution rather than an invented label: the canonical MetaMask
+// library this runner appends last, the personal library the harness names
+// 'personal', and any other configured library in between as the team/shared tier.
+function flowSourceTier(source: MetaMaskLibrarySource, index: number, total: number): string {
+  if (index === total - 1 && source.name === 'metamask') return 'canonical';
+  if (source.name === 'personal') return 'personal';
+  return 'team';
+}
+
 // The engine's flows subcommands (grounded in registerFlowsCommand): a bare
 // `flows` (or one that leads with a flag) means list.
 const FLOWS_SUBCOMMANDS: readonly string[] = ['list', 'promote'];
@@ -1824,11 +1857,25 @@ async function handleFlows(argv: string[]): Promise<number> {
   const sources = await resolveMetaMaskLibrarySources(undefined);
   if (!sources) {
     throw usageError(
-      'flows requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support). ' +
+      'flows requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support; ' +
+        'flows resolve personal > team > canonical). ' +
         'Next: update the dependency and run yarn install.',
     );
   }
   const forwarded = stripTargetFlag(argv);
+  const jsonMode = forwarded.includes('--json');
+  // Provenance: flows resolve by precedence — the highest-precedence copy of a ref
+  // wins and shadows lower ones, so a LOCAL library outranks canonical. The listing
+  // below prints `source=<name>` per flow; this legend maps each resolved source to
+  // its tier so that source is decodable. --json reserves stdout for the engine
+  // envelope, so the legend rides stderr only.
+  if (!jsonMode) {
+    console.error(color('label', 'flows resolve by precedence (highest wins; local shadows canonical):'));
+    sources.forEach((source, index) => {
+      const name = source.name ?? path.basename(source.root);
+      console.error(`  ${index + 1}. ${color('cmd', name)} ${color('dim', `[${flowSourceTier(source, index, sources.length)}]`)}`);
+    });
+  }
   // The engine requires an explicit subcommand. Inspect only the FIRST token: a
   // real subcommand there is passed through; anything else (empty, or a leading
   // flag whose VALUE must not be mistaken for a subcommand) defaults to list.

package/src/commands/debug.ts

@@ -5,6 +5,7 @@
 import path from 'node:path';
 
 import { runnerDir } from '../paths.ts';
+import { getAdapterSurface } from '../adapters/surface.ts';
 import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, targetOf, usageOut } from './shared.ts';
 
 const DEBUG_BOOLEANS = new Set(['worker', 'devMenu', 'json']);
@@ -16,7 +17,8 @@ export async function handleDebug(argv: string[]): Promise<number> {
   const adapter = resolveAdapter(options, target);
 
   if (!adapter) return usageOut(json, 'debug', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
-  if (adapter === 'core') return usageOut(json, 'debug', 'core is headless; there is no debug console.', 'mm-harness verify');
+  const surface = getAdapterSurface(adapter);
+  if (surface.headless) return usageOut(json, 'debug', 'core is headless; there is no debug console.', surface.hints.relaunch);
 
   const worker = flag(options, 'worker');
   const devMenu = flag(options, 'devMenu');

package/src/commands/fixtures.ts

@@ -6,6 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { runnerDir, walletFixturePath } from '../paths.ts';
+import { getAdapterSurface } from '../adapters/surface.ts';
 import type { MetaMaskRecipeAdapter } from '../types.ts';
 import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
 
@@ -55,9 +56,13 @@ export async function handleFixtures(argv: string[], deps: CommandDeps): Promise
   if (!adapter) {
     return usageOut(json, 'fixtures', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
-  if (adapter === 'core') return usageOut(json, 'fixtures', 'core is headless; it has no wallet fixture.', 'mm-harness run <recipe>   # run recipes against the headless core');
+  const surface = getAdapterSurface(adapter);
+  if (surface.headless) return usageOut(json, 'fixtures', 'core is headless; it has no wallet fixture.', surface.hints.launch);
 
   const canonicalFixture = walletFixturePath(target);
+  // Platform-phrased retry hint on a setup-wallet failure: the surface owns the
+  // (re)build/relaunch command; this command never spells out another platform's.
+  const retryHint = `${surface.hints.relaunch}   # relaunch, then retry: mm-harness fixtures set`;
 
   if (sub === 'sync') {
     const exitCode = fixturesSync(adapter, target, json);
@@ -104,7 +109,7 @@ export async function handleFixtures(argv: string[], deps: CommandDeps): Promise
       else process.env.APP_ROOT = previousAppRoot;
     }
     if (!json && status === 'fail') {
-      console.error('  Next: mm-harness launch ios   # relaunch the dev client, then retry: mm-harness fixtures set');
+      console.error(`  Next: ${retryHint}`);
     }
   } else {
     // Extension has no standalone set arm — reuse call's one-node machinery via
@@ -127,7 +132,7 @@ export async function handleFixtures(argv: string[], deps: CommandDeps): Promise
       else process.env.RECIPE_WALLET_FIXTURE = previousFixtureEnv;
     }
     if (!json && status === 'fail') {
-      console.error('  Next: mm-harness launch --build   # rebuild and relaunch, then retry: mm-harness fixtures set');
+      console.error(`  Next: ${retryHint}`);
     }
   }
 
@@ -149,9 +154,7 @@ export async function handleFixtures(argv: string[], deps: CommandDeps): Promise
           error: status === 'fail' ? {
             code: 'SETUP_WALLET_FAILED',
             message: 'wallet fixture setup failed',
-            userAction: adapter === 'mobile'
-              ? 'mm-harness launch ios   # relaunch the dev client, then retry: mm-harness fixtures set'
-              : 'mm-harness launch --build   # rebuild and relaunch, then retry: mm-harness fixtures set',
+            userAction: retryHint,
           } : null,
         },
         null,
@@ -166,8 +169,10 @@ export async function handleFixtures(argv: string[], deps: CommandDeps): Promise
 
 // Sync the overlay installation + wallet fixture for the checkout.
 // Re-runs the adapter inject to refresh patched files, then copies the wallet
-// fixture to the canonical runtime location via sync-wallet-fixture.sh.
-function fixturesSync(adapter: 'mobile' | 'extension', target: string, json: boolean): number {
+// fixture to the canonical runtime location via sync-wallet-fixture.sh. Reached
+// only for device adapters (headless core returns earlier); the adapter is
+// forwarded verbatim to `install`.
+function fixturesSync(adapter: MetaMaskRecipeAdapter, target: string, json: boolean): number {
   const mmHarnessBin = path.join(runnerDir, 'bin/mm-harness');
   const installResult = spawnScript(
     mmHarnessBin,

package/src/commands/launch.ts

@@ -9,10 +9,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { color } from '../cli-color.ts';
-import { handleHarness, readRuntimeContextField, resolveRuntimeContextPath } from '../harness.ts';
+import { handleHarness } from '../harness.ts';
 import { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, runnerDir } from '../paths.ts';
 import type { MetaMaskRecipeAdapter } from '../types.ts';
 import { prepareMobile } from '../adapters/mobile/prepare.ts';
+import { getAdapterSurface } from '../adapters/surface.ts';
+import { stopExtensionWatcher } from '../adapters/slot-ports.ts';
 import {
   ADAPTER_DETECT_NEXT,
   EXIT,
@@ -207,111 +209,6 @@ export async function handleLaunch(argv: string[]): Promise<number> {
   });
 }
 
-// Apply KEY=VALUE lines from slot resolution to process.env.
-// overwrite=true → pool match, always overrides existing env.
-// overwrite=false → formula match, only fills vars that are unset.
-function applyKVLines(output: string, overwrite: boolean): void {
-  for (const line of output.split('\n')) {
-    const m = /^([A-Z_]+)=(.+)$/u.exec(line.trim());
-    if (!m) continue;
-    const [, key, val] = m;
-    switch (key) {
-      case 'WATCHER_PORT':
-        if (overwrite || !process.env['WATCHER_PORT']) {
-          process.env['WATCHER_PORT'] = val;
-          process.env['METRO_PORT'] = val;
-          process.env['RECIPE_WATCHER_PORT'] = val;
-        }
-        break;
-      case 'IOS_SIMULATOR':
-        if (overwrite || !process.env['IOS_SIMULATOR']) process.env['IOS_SIMULATOR'] = val;
-        break;
-      case 'SLOT_ID':
-        if (overwrite || !process.env['RECIPE_SLOT_ID']) process.env['RECIPE_SLOT_ID'] = val;
-        break;
-      case 'CDP_PORT':
-        if (overwrite || !process.env['CDP_PORT']) {
-          process.env['CDP_PORT'] = val;
-          process.env['RECIPE_CDP_PORT'] = val;
-        }
-        break;
-    }
-  }
-}
-
-// Resolve mobile slot port/simulator: the slot context the orchestrator wrote
-// into the checkout wins first, then the farmslot pool (both overwrite env),
-// then the slot-suffix formula (only fills unset vars). Called before explicit
-// CLI flag overrides so flags always win at the top.
-export function resolveMobileSlotPorts(target: string): void {
-  const resolveScript = path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh');
-  try {
-    // The checkout's own runtime context is authoritative — it names the exact
-    // simulator/port this slot was prepared with, surviving pool renames.
-    const ctxOut = execFileSync('bash', [
-      '-c', `source "${resolveScript}" && resolve_mobile_runtime_context "${target}"`,
-    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
-    if (ctxOut.trim()) {
-      applyKVLines(ctxOut, true);
-      return;
-    }
-  } catch { /* no runtime context — fall through to pool */ }
-  try {
-    // Pool match always wins — overwrite whatever is in the environment.
-    const poolOut = execFileSync('bash', [
-      '-c', `source "${resolveScript}" && resolve_farmslot_ports_by_repo "${target}"`,
-    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
-    if (poolOut.trim()) {
-      applyKVLines(poolOut, true);
-      return;
-    }
-  } catch { /* no pool match — fall through to formula */ }
-  try {
-    // Formula match only fills unset vars (never overrides explicit env/pool).
-    const defOut = execFileSync('bash', [
-      '-c', `source "${resolveScript}" && resolve_mobile_slot_defaults "${target}"`,
-    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
-    if (defOut.trim()) applyKVLines(defOut, false);
-  } catch { /* no slot suffix in dir name — stays at env defaults */ }
-}
-
-// Resolve extension slot ports the same way as mobile: the checkout's runtime
-// context first (cdpPort/devServerPort written by the orchestrator's prepare),
-// then the farmslot pool, then the directory-suffix formula (fills unset only).
-function resolveExtensionSlotPorts(target: string): void {
-  // The prepared checkout's context OVERWRITES inherited env (same authority as
-  // mobile's context/pool resolution): a stale CDP_PORT from the shell must not
-  // hijack the slot's browser. Explicit CLI flags are applied after and win.
-  const contextPath = resolveRuntimeContextPath(target);
-  const cdp = readRuntimeContextField(contextPath, 'cdpPort');
-  if (cdp) {
-    process.env['CDP_PORT'] = cdp;
-    process.env['RECIPE_CDP_PORT'] = cdp;
-  }
-  const dev = readRuntimeContextField(contextPath, 'devServerPort');
-  if (dev) {
-    process.env['WATCHER_PORT'] = dev;
-    process.env['RECIPE_WATCHER_PORT'] = dev;
-  }
-  if (process.env['CDP_PORT']) return;
-  const resolveScript = path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh');
-  try {
-    const poolOut = execFileSync('bash', [
-      '-c', `source "${resolveScript}" && resolve_farmslot_ports_by_repo "${target}"`,
-    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
-    if (poolOut.trim()) {
-      applyKVLines(poolOut, true);
-      return;
-    }
-  } catch { /* no pool match — fall through to formula */ }
-  try {
-    const defOut = execFileSync('bash', [
-      '-c', `source "${resolveScript}" && resolve_default_extension_ports "${target}"`,
-    ], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
-    if (defOut.trim()) applyKVLines(defOut, false);
-  } catch { /* no slot suffix in dir name — stays at env defaults */ }
-}
-
 // Map the env-gap flags onto the env vars the leaf scripts read. For mobile, slot
 // port/simulator defaults are resolved first (pool-wins, then formula-fills-empty)
 // so that the harness respects slot isolation; explicit CLI flags applied below
@@ -325,9 +222,9 @@ function applyLaunchEnvOverrides(
   // Slot isolation: resolve ports/device from the checkout's own slot context,
   // the farmslot pool, or the directory-suffix formula BEFORE applying explicit
   // flags — extension needs this as much as mobile (CDP_PORT), so neither
-  // adapter hard-fails on a value its slot already knows.
-  if (adapter === 'mobile') resolveMobileSlotPorts(target);
-  if (adapter === 'extension') resolveExtensionSlotPorts(target);
+  // adapter hard-fails on a value its slot already knows. The surface owns the
+  // per-platform resolution; this command never branches on adapter for it.
+  getAdapterSurface(adapter).resolveSlotPorts(target);
 
   const device = str(options, 'device');
   if (device && adapter === 'mobile') {
@@ -421,56 +318,10 @@ async function executeComposition(
 async function extensionRebuild(target: string, json: boolean): Promise<ScriptResult> {
   const runtimeDirRel = recipeRuntimeDir();
   const runtimeAbs = path.join(target, runtimeDirRel);
-  const webpackPidFile = path.join(runtimeAbs, 'recipe-harness-webpack.pid');
   const rebuildLog = path.join(runtimeAbs, 'rebuild.log');
 
   // E1a: Kill harness-owned watcher via pid file, then ps-scan for orphans.
-  try {
-    const pid = fs.readFileSync(webpackPidFile, 'utf8').trim();
-    if (/^\d+$/u.test(pid)) {
-      try { process.kill(Number(pid), 'SIGTERM'); } catch { /* already dead */ }
-    }
-    fs.rmSync(webpackPidFile, { force: true });
-  } catch { /* no pid file */ }
-  // Scan for any remaining orphan webpack/yarn-start processes in this checkout.
-  try {
-    const psOut = execFileSync('ps', ['-axo', 'pid=,command='], { encoding: 'utf8' });
-    const orphanPids: number[] = [];
-    for (const line of psOut.split('\n')) {
-      const match = /^\s*(\d+)\s+(.*)$/u.exec(line);
-      if (!match) continue;
-      const [, pidStr, cmd] = match;
-      const isWatcher =
-        cmd.includes('yarn start') ||
-        cmd.includes('webpack --watch') ||
-        cmd.includes('development/webpack/launch.ts --watch');
-      if (!isWatcher) continue;
-      if (cmd.includes(target)) {
-        orphanPids.push(Number(pidStr));
-        continue;
-      }
-      // lsof cwd fallback for processes that don't embed the path in argv.
-      try {
-        const cwd = execFileSync('lsof', ['-a', `-p${pidStr}`, '-dcwd', '-Fn'], {
-          encoding: 'utf8',
-          timeout: 2000,
-        });
-        if (cwd.split('\n').some((l) => l.startsWith('n') && l.slice(1) === target)) {
-          orphanPids.push(Number(pidStr));
-        }
-      } catch { /* lsof unavailable or permission denied */ }
-    }
-    if (orphanPids.length > 0) {
-      for (const pid of orphanPids) {
-        try { process.kill(pid, 'SIGTERM'); } catch { /* already dead */ }
-      }
-      // Brief pause then force-kill survivors.
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2000);
-      for (const pid of orphanPids) {
-        try { process.kill(pid, 'SIGKILL'); } catch { /* already dead */ }
-      }
-    }
-  } catch { /* ps not available */ }
+  stopExtensionWatcher(target);
 
   // E1c: Clear the rebuild log (directory must exist for tee).
   fs.mkdirSync(path.dirname(rebuildLog), { recursive: true });

package/src/commands/logs.ts

@@ -5,7 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { recipeRuntimePath, runnerDir } from '../paths.ts';
+import { runnerDir } from '../paths.ts';
+import { getAdapterSurface } from '../adapters/surface.ts';
 import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
 
 const LOGS_BOOLEANS = new Set(['full', 'json']);
@@ -19,13 +20,23 @@ export async function handleLogs(argv: string[]): Promise<number> {
   if (!adapter) {
     return usageOut(json, 'logs', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
-  if (adapter === 'core') {
-    return usageOut(json, 'logs', 'core is headless; there are no app/Metro logs.', 'mm-harness run <recipe>   # run recipes against the headless core');
+  const surface = getAdapterSurface(adapter);
+  if (surface.headless) {
+    return usageOut(json, 'logs', 'core is headless; it has no dev server logs.', surface.hints.launch);
   }
 
-  const source = str(options, 'source') ?? 'metro';
-  if (source !== 'metro' && source !== 'app') {
-    return usageOut(json, 'logs', '--source must be metro or app.', 'mm-harness logs --source metro   or   mm-harness logs --source app');
+  // Source selection is platform-scoped: the valid names and the default come
+  // from THIS adapter's dev-server logs (mobile: metro; extension: webpack), plus
+  // the app-log source. No adapter's vocabulary is hardcoded here — every
+  // non-headless adapter provides at least one log source (headless core returned
+  // above), so the default is that adapter's first source.
+  const logSources = surface.logSources(target);
+  const sourceLabels = logSources.map((entry) => entry.label);
+  const defaultSource = sourceLabels[0];
+  const source = str(options, 'source') ?? defaultSource;
+  const validSources = [...sourceLabels, 'app'];
+  if (!validSources.includes(source)) {
+    return usageOut(json, 'logs', `--source must be one of: ${validSources.join(', ')}.`, `mm-harness logs --source ${defaultSource}`);
   }
 
   // Env-gap flag (docs/CLI-SPEC.md Part 4): --events sets the compact event count
@@ -39,16 +50,21 @@ export async function handleLogs(argv: string[]): Promise<number> {
     process.env.RECIPE_LOG_EVENTS = events;
   }
 
-  // Nothing running → teaching error pointing at launch. The log file is the
-  // signal that Metro/webpack has been started for this checkout.
-  const logFile = recipeRuntimePath(target, adapter === 'mobile' ? 'metro.log' : 'webpack.log');
-  if (!fs.existsSync(logFile)) {
-    const launchHint = adapter === 'mobile' ? 'mm-harness launch ios' : 'mm-harness launch';
+  // Nothing running → teaching error pointing at launch. A dev-server log file is
+  // the signal that the dev server has been started for this checkout; the surface
+  // owns which files a platform writes (mobile: metro.log; extension: webpack +
+  // watcher + rebuild logs). A `--source` naming a specific dev-server log is
+  // preferred; otherwise the most-relevant existing candidate is tailed.
+  const requested = logSources.find((entry) => entry.label === source);
+  const ordered = requested ? [requested, ...logSources.filter((entry) => entry !== requested)] : logSources;
+  const logFile = ordered.find((entry) => fs.existsSync(entry.path))?.path;
+  if (!logFile) {
+    const names = logSources.map((entry) => path.basename(entry.path)).join(' / ');
     return usageOut(
       json,
       'logs',
-      `nothing running for this checkout (no ${path.basename(logFile)}).`,
-      launchHint,
+      `nothing running for this checkout (no ${names}).`,
+      surface.hints.launch,
     );
   }
 

package/src/mm-harness-cli.ts

@@ -61,16 +61,18 @@ Example:
   },
   {
     name: 'stop',
-    summary: 'Stop the dev server this checkout owns (mobile: port-scoped Metro) and close its log window.',
+    summary: 'Stop the dev server this checkout owns (mobile Metro / extension webpack watcher) and close its log window.',
     example: 'mm-harness stop',
     helpText: `mm-harness stop [flags]
 
-  Stop the Metro dev server this checkout owns and close its tmux log-tail window.
-  Port-scoped: only the listener on the checkout's resolved port is signalled, so
-  concurrent slots are untouched. Nothing running = success (idempotent).
-  Extension/core: teaching error (their dev servers are slot-managed).
+  Stop the dev server this checkout owns and close its tmux log-tail window,
+  scoped to this checkout so concurrent slots are untouched. Idempotent —
+  nothing running is success, not an error. Behavior is per platform:
+    mobile     stop the port-scoped Metro dev server
+    extension  stop the checkout's webpack watcher (pid file + orphan scan)
+    core       headless — no dev server to stop (teaching error)
 
-  --port <port>                      Metro port (default: the checkout's slot context)
+  --port <port>                      Dev-server port (default: the checkout's slot context)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output
 
@@ -81,11 +83,13 @@ Example:
   {
     name: 'call',
     summary: 'Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).',
-    example: 'mm-harness call unlock',
+    example: 'mm-harness call ensure_unlocked',
     helpText: `mm-harness call <action> [--arg k=v ...] [flags]
 
   Run one action in isolation as a one-node recipe through the real engine path.
-  Fuzzy short-name: 'unlock' resolves to 'metamask.wallet.unlock' if unique; ambiguous = exit 2.
+  Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
+  if unique; ambiguous = exit 2. Actions differ per adapter — list this checkout's
+  with: mm-harness actions.
 
   --arg k=v                          Action field value (repeatable)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
@@ -95,9 +99,9 @@ Example:
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
 
-Example:
-  mm-harness call unlock --adapter extension
-  mm-harness call command --arg cmd="echo hi" --adapter core --json`,
+Example (real actions; run mm-harness actions for this checkout's full set):
+  mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
+  mm-harness call command --arg cmd="echo hi" --adapter core   # the universal action (all adapters)`,
   },
   {
     name: 'flows',
@@ -241,8 +245,10 @@ Example:
 
   --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
   --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
-  --source <metro|app>               Log source (default metro)
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --source <label>                   Log source per adapter — mobile: metro|app (default metro);
+                                     extension: webpack|watcher|rebuild|app (default webpack).
+                                     Core is headless (teaching error).
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output