@deeeed/metamask-harness 0.3.7 → 0.3.9

package/src/adapters/mobile/runtime-decision.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -43,6 +44,9 @@ export interface MobileRuntimeDecisionReport {
   decision: MobileReadinessDecision;
   reasonCode: string;
   reasons: string[];
+  // A single teaching escape for the caller's actual situation, set on decisions
+  // the runner deliberately refuses to auto-resolve (e.g. fast-mode deps gaps).
+  userAction?: string;
   checks: {
     deps: DepsCheck;
     metroLog: MetroLogCheck;
@@ -56,6 +60,9 @@ export interface MobileRuntimeDecisionOptions {
   metroLog?: string;
   platform?: string;
   record?: boolean;
+  // 'fast' (quick launch / no --build) makes deps readiness a presence check only:
+  // freshness is the orchestrator's deps-phase contract, never re-decided here.
+  preflightMode?: string;
 }
 
 const BUNDLE_ERR = /Bundling failed|Unable to resolve /u;
@@ -128,38 +135,38 @@ function missingRequiredDeps(target: string): string[] {
   }
 }
 
-// Returns true when any manifest input (package.json or yarn.lock) is newer than
-// the install markers written by yarn on a successful install. A reliable signal
-// that deps changed since the last install, even when depsCheck found no recorded
-// baseline drift (e.g. git checkout preserved an old author-date mtime on the
-// manifest, then a new dep was committed, making the manifest newer than markers).
-function depsStaleByMtime(target: string): boolean {
-  // Use the same install markers as depsCheck: the files yarn writes on install.
-  const INSTALL_MARKERS = ['node_modules/.yarn-state.yml', '.yarn/install-state.gz'];
-  let markerMtime = 0;
-  for (const rel of INSTALL_MARKERS) {
-    try {
-      const mt = fs.statSync(path.join(target, rel)).mtimeMs;
-      if (mt > markerMtime) markerMtime = mt;
-    } catch {
-      // marker absent; keep searching
-    }
-  }
-  if (markerMtime === 0) return false; // no markers → depsCheck already handles via 'missing'
-  for (const file of ['package.json', 'yarn.lock']) {
-    try {
-      if (fs.statSync(path.join(target, file)).mtimeMs > markerMtime) return true;
-    } catch {
-      // manifest absent; skip
-    }
-  }
-  return false;
-}
-
 const installActions = (target: string): MobileRuntimeDecisionAction[] => [
   { id: 'yarn-setup', argv: ['yarn', 'setup'], cwd: target },
 ];
 
+// True when a MetaMask dev client process is alive on the target device
+// (IOS_SIMULATOR / ADB_SERIAL, falling back to the booted simulator). Probe
+// failures count as not-running: the worst case is an idempotent relaunch,
+// while failing open would declare a dead app "ready".
+function appRunningOnDevice(platform?: string): boolean {
+  try {
+    if (platform === 'android') {
+      const serial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL;
+      const args = serial ? ['-s', serial] : [];
+      const out = execFileSync('adb', [...args, 'shell', 'ps', '-A'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 5_000,
+      });
+      return out.includes('io.metamask');
+    }
+    const device = process.env.IOS_SIMULATOR || 'booted';
+    const out = execFileSync('xcrun', ['simctl', 'spawn', device, 'launchctl', 'list'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5_000,
+    });
+    return out.toLowerCase().includes('io.metamask');
+  } catch {
+    return false;
+  }
+}
+
 const launchActions = (target: string, clearMetro = false): MobileRuntimeDecisionAction[] => {
   const actions: MobileRuntimeDecisionAction[] = [];
   // start-metro ensures Metro is running; --clear resets the bundle cache.
@@ -184,22 +191,60 @@ export async function decideMobileReadiness(
   const resolved = path.resolve(target);
   if (options.record) recordDepsBaseline(resolved);
 
+  const fast = options.preflightMode === 'fast';
+  const report = await computeMobileReadiness(resolved, options, fast);
+
+  // mtime churn is already neutralized above, so a fast-mode 'install' verdict
+  // means deps genuinely need work (absent markers, an absent required package, a
+  // fingerprint-baseline drift, or Metro unable to resolve a module). In an
+  // orchestrated run the deps phase owns installation; having the runner install
+  // mid-launch is inverted authority. Surface a teaching block, not an implicit
+  // setup, so a runway preflight never re-does the orchestrator's deps work.
+  if (fast && report.decision === 'install') {
+    return {
+      ...report,
+      decision: 'blocked',
+      reasonCode: 'deps-not-ready',
+      reasons: [
+        'Fast preflight found dependencies not ready and does not install them (the orchestrator deps phase owns installation).',
+        ...report.reasons,
+      ],
+      userAction:
+        'run the slot deps/prepare phase; standalone: `yarn setup:expo --no-build-ios --no-build-android` in the checkout, or `mm-harness launch <platform> --build` to install and build',
+      actions: [],
+    };
+  }
+  return report;
+}
+
+async function computeMobileReadiness(
+  resolved: string,
+  options: MobileRuntimeDecisionOptions,
+  fast: boolean,
+): Promise<MobileRuntimeDecisionReport> {
   const rawDeps = depsCheck(resolved, {
     productMarkers: mobileProductMarkers(options.platform),
   });
-  // Mtime-based fallback: when depsCheck found no recorded baseline, supplement
-  // with a direct mtime comparison — if package.json or yarn.lock is newer than
-  // node_modules, a dep change landed after the last install. Fail fast at
-  // pre-flight rather than launching a doomed Metro bundle. Skip when a baseline
-  // was found (hasBaseline=true) so fingerprint-verified 'current' is trusted.
-  let deps: DepsCheck =
-    rawDeps.status === 'current' && !rawDeps.hasBaseline && depsStaleByMtime(resolved)
-      ? { installed: rawDeps.installed, status: 'stale', hasBaseline: rawDeps.hasBaseline }
-      : rawDeps;
-  // Required-dep absence: even when fingerprint + mtime reports 'current', a
-  // top-level dependency could be absent from node_modules (e.g. added in a
-  // branch merge but install not re-run). Catch at pre-flight before Metro
-  // discovers it during a 249s bundle run.
+  // Presence is authoritative; mtime is only a hint. Without a recorded baseline
+  // the only way depsCheck reports 'stale' is mtime drift (a manifest newer than
+  // the install markers). In a managed checkout the orchestrator's git phase
+  // refreshes tracked-file mtimes on every sync while its deps phase leaves
+  // node_modules untouched, so "manifest newer than markers" is normal and NOT
+  // proof of drift — treating it as stale re-ran the full yarn setup inside every
+  // launch. Trust the installed node_modules and warn; genuine drift is caught by
+  // the recorded-baseline fingerprint when one exists (hasBaseline=true stays 'stale').
+  let deps: DepsCheck = rawDeps;
+  if (rawDeps.status === 'stale' && !rawDeps.hasBaseline) {
+    deps = { installed: rawDeps.installed, status: 'current', hasBaseline: false };
+    process.stderr.write(
+      '[runtime-decision] manifest is newer than install markers (no recorded baseline); ' +
+        'trusting installed node_modules — run yarn setup manually if deps truly changed.\n',
+    );
+  }
+  // Required-dep absence is a presence check (both modes): a top-level dependency
+  // can be absent from node_modules even when markers + fingerprint report
+  // 'current' (e.g. added in a branch merge but install not re-run). Catch at
+  // pre-flight before Metro discovers it during a long bundle run.
   if (deps.status === 'current') {
     const absent = missingRequiredDeps(resolved);
     if (absent.length > 0) {
@@ -373,13 +418,29 @@ export async function decideMobileReadiness(
   }
 
   if (metro.status === 'up' && metroLog.status === 'ok') {
+    // Metro health alone is not runtime readiness: the dev client may be
+    // installed but not running on the target device (launch must launch).
+    // Probe the device before declaring ready; a healthy Metro with a dead
+    // app relaunches the client without touching Metro.
+    if (!appRunningOnDevice(options.platform)) {
+      return {
+        schemaVersion: 1,
+        adapter: 'mobile',
+        target: resolved,
+        decision: 'launch',
+        reasonCode: 'app-not-running',
+        reasons: ['Metro is healthy but the dev client is not running on the target device; launching it.'],
+        checks,
+        actions: launchActions(resolved),
+      };
+    }
     return {
       schemaVersion: 1,
       adapter: 'mobile',
       target: resolved,
       decision: 'ready',
       reasonCode: 'healthy',
-      reasons: ['Dependencies are current and Metro reports a successful bundle. Verify bridge before replay.'],
+      reasons: ['Dependencies are current, Metro reports a successful bundle, and the dev client is running. Verify bridge before replay.'],
       checks,
       actions: [],
     };

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,
@@ -420,7 +421,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 +431,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 +476,38 @@ 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: 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 */ }
+  }
+  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';
+      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')}`,
+      );
+      for (const reason of runtime.reasons) console.log(`  ${out('dim', reason)}`);
+    }
     console.log(renderRuntimeContext(result.runtimeContext));
   }
   return result.status === 'pass' ? 0 : 1;
@@ -758,6 +788,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 +1113,47 @@ 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);
+  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 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(
+        {
+          schemaVersion: 1,
+          command: 'stop',
+          adapter,
+          target,
+          status: exitCode === 0 ? 'pass' : 'fail',
+          exitCode,
+          output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim(),
+        },
+        null,
+        2,
+      ),
+    );
+  }
+  return exitCode;
+}
+
 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
@@ -1803,6 +1875,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/launch.ts

@@ -8,7 +8,8 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { handleHarness } from '../harness.ts';
+import { color } from '../cli-color.ts';
+import { handleHarness, readRuntimeContextField, resolveRuntimeContextPath } from '../harness.ts';
 import { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, runnerDir } from '../paths.ts';
 import type { MetaMaskRecipeAdapter } from '../types.ts';
 import { prepareMobile } from '../adapters/mobile/prepare.ts';
@@ -19,6 +20,7 @@ import {
   parseFlags,
   resolveAdapter,
   spawnScript,
+  spawnScriptStreaming,
   str,
   targetOf,
   usageOut,
@@ -227,15 +229,33 @@ function applyKVLines(output: string, overwrite: boolean): void {
       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 from the farmslot pool (pool-wins-over-env)
-// or from the slot-suffix formula (only fills unset vars). Called before explicit
+// 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.
-function resolveMobileSlotPorts(target: string): void {
+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', [
@@ -255,6 +275,43 @@ function resolveMobileSlotPorts(target: string): void {
   } 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
@@ -265,9 +322,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.
+  // 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);
 
   const device = str(options, 'device');
   if (device && adapter === 'mobile') {
@@ -346,17 +406,19 @@ 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');
@@ -418,7 +480,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 +554,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/shared.ts

@@ -7,7 +7,7 @@
 //   For node invocations (bin === process.execPath) the stem is derived from the
 //   script path in args[0], e.g. MM_HARNESS_SCRIPT_BIN_OPEN_DEBUG_MJS.
 
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import path from 'node:path';
 
 import { detectAdapter } from '../harness.ts';
@@ -151,6 +151,67 @@ export function spawnScript(
   return { status: result.status ?? 1, output };
 }
 
+// Streaming variant of spawnScript for long-running leaves (mobile prepare:
+// native build + Metro + health-bridge poll, minutes long). spawnScript buffers
+// via spawnSync and, in --json mode, suppresses output entirely — so those leaves
+// run with zero feedback until exit. This tees the child's stdout+stderr to the
+// parent's STDERR live (so the --json envelope on stdout stays clean) while still
+// capturing the combined output for heal classification. Same seam, leaf-invoke
+// resolution, missing-leaf pre-check, and spawn-error contract as spawnScript.
+export function spawnScriptStreaming(
+  script: string,
+  args: string[],
+  cwd: string,
+  env?: Record<string, string>,
+): Promise<ScriptResult> {
+  const isNodeScript = script === process.execPath && args.length > 0;
+  const stem = isNodeScript
+    ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase()
+    : path.basename(script).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase();
+  const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
+  const bin = override ?? script;
+  const directArgs = override !== undefined && isNodeScript ? args.slice(1) : args;
+
+  if (shellLeafMissing(bin)) {
+    const message =
+      `leaf could not start: ${path.basename(bin)} (ENOENT)\n` +
+      `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`;
+    process.stderr.write(`${message}\n`);
+    return Promise.resolve({ status: 1, output: message });
+  }
+
+  const { bin: invokeBin, args: spawnArgs } = resolveLeafInvoke(bin, directArgs);
+  return new Promise<ScriptResult>((resolve) => {
+    const child = spawn(invokeBin, spawnArgs, {
+      cwd,
+      env: env ? { ...process.env, ...env } : process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let output = '';
+    // Route BOTH child streams to the parent's stderr, live: stdout is reserved
+    // for the harness --json envelope, so all human/leaf progress goes to stderr.
+    const tee = (chunk: Buffer): void => {
+      const text = chunk.toString('utf8');
+      output += text;
+      process.stderr.write(text);
+    };
+    child.stdout?.on('data', tee);
+    child.stderr?.on('data', tee);
+    child.on('error', (error: NodeJS.ErrnoException) => {
+      const leaf = isNodeScript ? path.basename(args[0]) : path.basename(script);
+      const code = error.code ?? 'ESPAWN';
+      const message =
+        `leaf could not start: ${leaf} (${code})\n` +
+        `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`;
+      process.stderr.write(`${message}\n`);
+      resolve({ status: 1, output: message });
+    });
+    child.on('close', (status) => {
+      resolve({ status: status ?? 1, output });
+    });
+  });
+}
+
 // Both escapes from a failed repo-type detection (defined at the detection source
 // in harness.ts): where to run it (checkout/target) and how to force it (adapter).
 export { ADAPTER_DETECT_NEXT } from '../harness.ts';

package/src/doctor.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { color } from './cli-color.ts';
 import { readRuntimeContextField, resolveRuntimeContextPath } from './harness.ts';
 import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from './paths.ts';
 import type {
@@ -100,26 +101,32 @@ const RUNTIME_CONTEXT_FIELDS: ReadonlyArray<{
   envVars: readonly string[];
   envVar: string | null;
   customize: string;
+  adapters: readonly MetaMaskRecipeAdapter[];
 }> = [
-  { key: 'slotId', envVars: ['RECIPE_SLOT_ID'], envVar: 'RECIPE_SLOT_ID', customize: 'farmslot dispatch writes this' },
-  { key: 'extensionId', envVars: ['RECIPE_HARNESS_EXTENSION_ID'], envVar: 'RECIPE_HARNESS_EXTENSION_ID', customize: 'auto-resolved; edit file to pin' },
-  { key: 'cdpPort', envVars: ['RECIPE_CDP_PORT', 'CDP_PORT'], envVar: 'CDP_PORT', customize: 'edit file or pass --cdp-port' },
-  { key: 'runtimeStart.approved', envVars: ['RECIPE_RUNTIME_START_APPROVED'], envVar: 'RECIPE_RUNTIME_START_APPROVED', customize: 'edit file (true/false)' },
-  { key: 'runtimeStart.command', envVars: [], envVar: null, customize: 'edit file' },
-  { key: 'runtimeStart.readyUrl', envVars: ['RECIPE_RUNTIME_READY_URL'], envVar: 'RECIPE_RUNTIME_READY_URL', customize: 'edit file' },
+  { key: 'slotId', envVars: ['RECIPE_SLOT_ID'], envVar: 'RECIPE_SLOT_ID', customize: 'farmslot dispatch writes this', adapters: ['mobile', 'extension', 'core'] },
+  { key: 'extensionId', envVars: ['RECIPE_HARNESS_EXTENSION_ID'], envVar: 'RECIPE_HARNESS_EXTENSION_ID', customize: 'auto-resolved; edit file to pin', adapters: ['extension'] },
+  { key: 'cdpPort', envVars: ['RECIPE_CDP_PORT', 'CDP_PORT'], envVar: 'CDP_PORT', customize: 'edit file or pass --cdp-port', adapters: ['extension'] },
+  { key: 'runtimeStart.approved', envVars: ['RECIPE_RUNTIME_START_APPROVED'], envVar: 'RECIPE_RUNTIME_START_APPROVED', customize: 'edit file (true/false)', adapters: ['mobile', 'extension'] },
+  { key: 'runtimeStart.command', envVars: [], envVar: null, customize: 'edit file', adapters: ['mobile', 'extension'] },
+  { key: 'runtimeStart.readyUrl', envVars: ['RECIPE_RUNTIME_READY_URL'], envVar: 'RECIPE_RUNTIME_READY_URL', customize: 'edit file', adapters: ['mobile', 'extension'] },
 ];
 
 // Report every runtime-context field with its current value and where it came from
 // (live env override > file > unset default), reusing the harness's own file reader
 // so doctor and dispatch agree on resolution. Absent file → fileExists:false and
 // every field falls back to env or default; the path shows where it WOULD live.
-export function runtimeContextSummary(target: string): MetaMaskRuntimeContextReport {
+// An adapter scopes the report to that platform's fields — an extension-only row
+// (cdpPort, extensionId) is noise on a mobile or core slot.
+export function runtimeContextSummary(target: string, adapter?: MetaMaskRecipeAdapter): MetaMaskRuntimeContextReport {
   const contextPath = resolveRuntimeContextPath(target);
   const envOverride = process.env.RECIPE_RUNTIME_CONTEXT ?? null;
   const fileExists = fs.existsSync(contextPath);
   const file = envOverride ?? path.relative(target, contextPath);
   const fields: Record<string, MetaMaskRuntimeContextField> = {};
-  for (const spec of RUNTIME_CONTEXT_FIELDS) {
+  const specs = adapter
+    ? RUNTIME_CONTEXT_FIELDS.filter((spec) => spec.adapters.includes(adapter))
+    : RUNTIME_CONTEXT_FIELDS;
+  for (const spec of specs) {
     const envValue = spec.envVars
       .map((name) => process.env[name])
       .find((value) => value !== undefined && value !== '');
@@ -137,16 +144,21 @@ export function runtimeContextSummary(target: string): MetaMaskRuntimeContextRep
 
 // Human-readable runtime-context section for `doctor` without --json.
 export function renderRuntimeContext(runtimeContext: MetaMaskRuntimeContextReport): string {
+  // Human render: set values read bright with their provenance highlighted;
+  // unset defaults read dim so the eye lands on what is actually configured.
+  const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
   const lines: string[] = [];
   lines.push(
     runtimeContext.fileExists
-      ? `runtime-context: ${runtimeContext.file} (present)`
-      : `runtime-context: ${runtimeContext.file} (absent — written by farmslot prepare/dispatch)`,
+      ? `${out('label', 'runtime-context:')} ${runtimeContext.file} ${out('ok', '(present)')}`
+      : `${out('label', 'runtime-context:')} ${runtimeContext.file} ${out('dim', '(absent — written by farmslot prepare/dispatch)')}`,
   );
   for (const [key, field] of Object.entries(runtimeContext.fields)) {
-    const value = field.value ?? '(unset)';
+    const isSet = field.value !== undefined && field.value !== null && field.value !== '';
+    const value = isSet ? out('ok', String(field.value)) : out('dim', '(unset)');
     const origin = field.source === 'env' && field.envVar ? `env ${field.envVar}` : field.source;
-    lines.push(`  ${key.padEnd(22)} ${value}  [${origin}] — ${field.customize}`);
+    const originTag = isSet ? out('accent', `[${origin}]`) : out('dim', `[${origin}]`);
+    lines.push(`  ${key.padEnd(22)} ${value}  ${originTag} ${out('dim', `— ${field.customize}`)}`);
   }
   return lines.join('\n');
 }
@@ -189,7 +201,7 @@ export function createDoctorReport(
     compatibilityMode: mode,
     shape: repoShape(target),
     fixture: fixtureSummary(target),
-    runtimeContext: runtimeContextSummary(target),
+    runtimeContext: runtimeContextSummary(target, adapter),
     manifestValidation: manifestValidation.summary,
   };
 }