@deeeed/metamask-harness 0.3.8 → 0.4.0

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/prepare.ts

@@ -7,6 +7,8 @@
 
 import path from 'node:path';
 
+import { recordDepsBaseline } from '@farmslot/recipe-harness/runtime/deps-readiness';
+
 import { EXIT, spawnScriptStreaming } from '../../commands/shared.ts';
 import type { ScriptResult } from '../../commands/shared.ts';
 import { runnerDir } from '../../paths.ts';
@@ -24,7 +26,16 @@ export { type MobileRuntimeDecisionReport };
 // An inherited FORCE_COLOR makes node emit a colorized `undefined`, so VisionCamera
 // misdetects the worklets pod, enables FrameProcessors, and fails on the missing
 // pod. Force plain output for pod-triggering spawns so the probe reads `undefined`.
-const POD_PROBE_ENV: Record<string, string> = { FORCE_COLOR: '0', NO_COLOR: '1' };
+// CocoaPods reads UTF-8 podspecs; a parent env without a locale (gateway/tmux
+// spawns) makes Ruby parse them as US-ASCII and die on the first multibyte byte
+// ('"\xE2" on US-ASCII' in react-native-mmkv.podspec). Pin a UTF-8 locale for
+// pod-triggering spawns when the caller has none.
+const POD_PROBE_ENV: Record<string, string> = {
+  FORCE_COLOR: '0',
+  NO_COLOR: '1',
+  LANG: process.env.LANG?.includes('UTF-8') ? process.env.LANG : 'en_US.UTF-8',
+  LC_ALL: process.env.LC_ALL?.includes('UTF-8') ? process.env.LC_ALL : 'en_US.UTF-8',
+};
 
 export interface PrepareMobileOptions extends MobileRuntimeDecisionOptions {
   /**
@@ -59,6 +70,7 @@ export async function mobileRuntimeStatus(
     metroLog: opts.metroLog,
     platform: opts.platform,
     record: opts.record,
+    preflightMode: opts.preflightMode,
   });
 }
 
@@ -81,11 +93,13 @@ export async function prepareMobile(
     metroLog: opts.metroLog,
     platform,
     record: opts.record,
+    preflightMode,
   });
 
   if (report.decision === 'blocked') {
     const reasons = report.reasons.join(' ');
-    const msg = `mobile prepare blocked: ${reasons}\n  Next: fix the bundle error in app code before retrying recipe up.`;
+    const next = report.userAction ?? 'fix the bundle error in app code before retrying recipe up.';
+    const msg = `mobile prepare blocked: ${reasons}\n  Next: ${next}`;
     if (!json) process.stderr.write(`${msg}\n`);
     return { status: EXIT.runtime, output: msg };
   }
@@ -112,6 +126,11 @@ export async function prepareMobile(
   for (const action of actions) {
     const result = await dispatchAction(action, target, platform, json, preflightMode);
     if (result.status !== 0) return result;
+    // Record the deps baseline the instant a setup/install leaf succeeds, so the
+    // mtime freshness fallback stops firing forever after one good install. This
+    // is unconditional (not gated on a later re-decide or an env flag), so the
+    // baseline lifecycle is self-sustaining regardless of the caller's path.
+    if (action.id === 'yarn-setup') recordDepsBaseline(path.resolve(target));
   }
 
   // After install: re-decide and run appropriate actions.
@@ -122,7 +141,7 @@ export async function prepareMobile(
       watcherPort: opts.watcherPort,
       metroLog: opts.metroLog,
       platform,
-      record: true,
+      preflightMode,
     });
     switch (postInstall.decision) {
       case 'install': {

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/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];
+}