@deeeed/metamask-harness 0.3.8 → 0.4.0

package/src/cli.ts

@@ -4,6 +4,7 @@ import { mkdtemp } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
+import { color } from './cli-color.ts';
 import { createDoctorReport, renderRuntimeContext } from './doctor.ts';
 import {
   invalidateCompletionCache,
@@ -27,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,
@@ -420,7 +423,7 @@ async function runSelfTest(options: CliOptions) {
 }
 
 async function handleManifest({ options }: ParsedArgs): Promise<number> {
-  const adapter = adapterOption(options);
+  const { adapter } = resolveAdapter(options);
   const actionManifestPath = actionManifestPathOption(options, adapter);
   const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
   await validateManifest(manifest);
@@ -430,7 +433,7 @@ async function handleManifest({ options }: ParsedArgs): Promise<number> {
 }
 
 async function handleActions({ options }: ParsedArgs): Promise<number> {
-  const adapter = adapterOption(options);
+  const { adapter } = resolveAdapter(options);
   const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
   await validateManifest(manifest);
   const action = optionString(options, 'action');
@@ -475,9 +478,31 @@ async function handleDoctor({ options }: ParsedArgs): Promise<number> {
   }
 
   const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-  if (json) console.log(JSON.stringify(result, null, 2));
+  // 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 {
-    console.log(`${result.status} ${adapter} ${result.compatibilityMode} manifest=${actionManifestPath}`);
+    const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
+    const stateStyle = (value: string | undefined, good: string) => (value === good ? 'ok' : 'warn');
+    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')}${devServer}`,
+      );
+      for (const reason of runtime.reasons) console.log(`  ${out('dim', reason)}`);
+    }
     console.log(renderRuntimeContext(result.runtimeContext));
   }
   return result.status === 'pass' ? 0 : 1;
@@ -758,6 +783,7 @@ async function handleRuntimeDecision({ options }: ParsedArgs): Promise<number> {
       metroLog: optionString(options, 'metroLog'),
       platform: optionString(options, 'platform') ?? process.env.PLATFORM ?? process.env.RECIPE_HARNESS_PLATFORM,
       record: optionFlag(options, 'record'),
+      preflightMode: optionString(options, 'preflightMode'),
     });
     if (optionFlag(options, 'json')) console.log(JSON.stringify(report, null, 2));
     else console.log(`${report.decision} ${report.reasonCode} — ${report.reasons[0] ?? ''}`);
@@ -1082,6 +1108,51 @@ function emitPlanUsageError(
 // hand it to runRecipe). One execution path, two doors: `call` = one node, `run` =
 // a graph. Inherits run semantics: always-validates (adapter-aware, exit 5), same
 // trace/evidence artifacts, same --json contract.
+async function handleStop(argv: string[]): Promise<number> {
+  const { options } = parseArgs(argv, 'stop');
+  const json = optionFlag(options, 'json');
+  const { adapter, target } = resolveAdapter(options);
+  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);
+  }
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: 'stop',
+          adapter,
+          target,
+          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 stop.status;
+}
+
 async function handleCall(argv: string[]): Promise<number> {
   // Grammar: mm-harness call <action> [--arg k=v ...] [flags].
   // If the first token is a flag, the action positional is missing — parseCallArgs
@@ -1096,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;
   }
 
@@ -1268,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,
@@ -1722,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'];
@@ -1752,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.
@@ -1803,6 +1922,7 @@ export async function main(argv: string[]): Promise<number> {
   // launch/logs/debug/fixtures compose adapter scripts directly and own policy,
   // healing, teaching, and the --json contract.
   if (command === 'launch') return handleLaunch(argv.slice(1));
+  if (command === 'stop') return handleStop(argv.slice(1));
   if (command === 'logs') return handleLogs(argv.slice(1));
   if (command === 'debug') return handleDebug(argv.slice(1));
   if (command === 'fixtures') return handleFixtures(argv.slice(1), { runOneNode });

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

@@ -8,10 +8,13 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { color } from '../cli-color.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,
@@ -19,6 +22,7 @@ import {
   parseFlags,
   resolveAdapter,
   spawnScript,
+  spawnScriptStreaming,
   str,
   targetOf,
   usageOut,
@@ -205,56 +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;
-    }
-  }
-}
-
-// Resolve mobile slot port/simulator from the farmslot pool (pool-wins-over-env)
-// or from the slot-suffix formula (only fills unset vars). Called before explicit
-// CLI flag overrides so flags always win at the top.
-function resolveMobileSlotPorts(target: string): void {
-  const resolveScript = path.join(runnerDir, 'adapters/shared/resolve-farmslot-ports.sh');
-  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 */ }
-}
-
 // 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
@@ -265,9 +219,12 @@ function applyLaunchEnvOverrides(
   mobileTarget: string | undefined,
   target: string,
 ): void {
-  // Mobile slot isolation: resolve WATCHER_PORT / IOS_SIMULATOR / SLOT_ID from
-  // the farmslot pool or directory-suffix formula BEFORE applying explicit flags.
-  if (adapter === 'mobile') resolveMobileSlotPorts(target);
+  // 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. 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') {
@@ -346,69 +303,25 @@ async function executeComposition(
     return extensionRebuild(target, json);
   }
 
-  // Extension build or watch: full webpack compile via start-watch.sh.
+  // Extension build or watch: full webpack compile via start-watch.sh. Streams
+  // live — a webpack compile is minutes long and must never look hung.
   const startWatchSh = path.join(runnerDir, 'adapters/extension/start-watch.sh');
   const watchArgs = ['--target', target];
   if (process.env.WATCHER_PORT) watchArgs.push('--watcher-port', process.env.WATCHER_PORT);
-  return spawnScript(startWatchSh, watchArgs, target, json);
+  console.error(`→ extension ${wantWatch ? 'watch' : 'build'} — webpack :${process.env.WATCHER_PORT ?? 'default'} (output streams below)`);
+  return spawnScriptStreaming(startWatchSh, watchArgs, target);
 }
 
 // Extension rebuild: kill the harness-owned webpack watcher (pid file + ps-scan
 // for orphans), clear the rebuild log, then drive the installed overlay's
 // live.sh --start-watch and tee its output into the rebuild log.
-function extensionRebuild(target: string, json: boolean): ScriptResult {
+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 });
@@ -418,7 +331,10 @@ function extensionRebuild(target: string, json: boolean): ScriptResult {
   const liveArgs = ['--target', target, '--start-watch'];
   if (process.env.CDP_PORT) liveArgs.push('--cdp-port', process.env.CDP_PORT);
   if (process.env.WATCHER_PORT) liveArgs.push('--watcher-port', process.env.WATCHER_PORT);
-  const result = spawnScript(liveScript, liveArgs, target, json);
+  // Streams live: the watcher restart + Chromium boot runs for minutes and the
+  // command must show progress immediately, not a silent prompt.
+  console.error(`→ extension quick relaunch — webpack :${process.env.WATCHER_PORT ?? 'default'} · CDP :${process.env.CDP_PORT ?? 'default'} (output streams below)`);
+  const result = await spawnScriptStreaming(liveScript, liveArgs, target);
   // Tee live.sh output into rebuild.log for post-mortem diagnosis.
   if (result.output) {
     try { fs.appendFileSync(rebuildLog, result.output); } catch { /* best-effort */ }
@@ -489,7 +405,18 @@ function launchPass(
       ),
     );
   } else {
-    console.error(`✓ launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ''} (${tier}) ready`);
+    // The summary must say what actually happened where: the target device,
+    // what the tier meant, and that the app+bridge are up — "(quick) ready"
+    // alone reads as a no-op even when a launch occurred.
+    const device =
+      adapter === 'mobile'
+        ? process.env.IOS_SIMULATOR || process.env.ADB_SERIAL || 'booted device'
+        : displayMode;
+    const tierNote = tier === 'quick' ? 'quick relaunch, no native build' : tier;
+    const devNote = process.env.MM_HARNESS_BIN ? ` ${color('dim', '[dev: MM_HARNESS_BIN]')}` : '';
+    console.error(
+      `${color('ok', '✓')} launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ''} — ${color('ok', String(device))} · ${tierNote} · app + bridge ready${devNote}`,
+    );
   }
   return EXIT.ok;
 }

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,
     );
   }