@deeeed/metamask-harness 0.2.0 → 0.3.0

package/src/commands/fixtures.ts

@@ -0,0 +1,196 @@
+// fixtures <sync|set> — manage wallet DATA (never overlay/runtime state). `sync`
+// re-renders the wallet fixture files; `set` applies THE canonical fixture (SRP/
+// password read FROM the fixture, never typed) and always teaches the edit path.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { runnerDir, walletFixturePath } from '../paths.ts';
+import type { MetaMaskRecipeAdapter } from '../types.ts';
+import { EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
+
+// One node injected from cli.ts so `fixtures set` can reuse the real engine path
+// (`call`'s one-node machinery) without a circular import.
+export interface CommandDeps {
+  runOneNode: (
+    adapter: MetaMaskRecipeAdapter,
+    action: string,
+    args: Record<string, string>,
+    target: string,
+    actionManifest: string | undefined,
+  ) => Promise<{ status: 'pass' | 'fail' }>;
+}
+
+const FIXTURES_BOOLEANS = new Set(['json']);
+
+// Patterns indicating setup-wallet failed due to a Metro/bridge issue (not a bad
+// fixture). A clean Metro restart + relaunch is likely to resolve these.
+// Mirrors baseline mm-recipe:820-824 setup_wallet_failure_recoverable patterns.
+const RECOVERABLE_SETUP_WALLET_PATTERNS = [
+  'CDP not reachable',
+  'CDP bridge',
+  'is not installed',
+  'Engine.context.KeyringController not available',
+  'Engine does not exist',
+  "Cannot read property 'transactions'",
+  'bridge-not-ready',
+  'debug-target-missing',
+  'CDP eval failed',
+  'CDP eval-async failed',
+];
+
+function isRecoverableSetupWalletFailure(output: string): boolean {
+  return RECOVERABLE_SETUP_WALLET_PATTERNS.some((p) => output.includes(p));
+}
+
+export async function handleFixtures(argv: string[], deps: CommandDeps): Promise<number> {
+  const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
+  const json = flag(options, 'json');
+  const sub = positional[0];
+  if (sub !== 'sync' && sub !== 'set') {
+    return usageOut(json, 'fixtures', 'fixtures requires a subcommand: mm-harness fixtures <sync|set>\n  Next: mm-harness fixtures sync   or   mm-harness fixtures set');
+  }
+  const target = targetOf(options);
+  const adapter = resolveAdapter(options, target);
+  if (!adapter) {
+    return usageOut(
+      json,
+      'fixtures',
+      `could not detect the MetaMask repo type for ${target}\n  Next: pass --target <checkout>   or   cd into the checkout, then re-run: mm-harness fixtures ${sub}`,
+    );
+  }
+  if (adapter === 'core') return usageOut(json, 'fixtures', 'core is headless; it has no wallet fixture.\n  Next: mm-harness run <recipe>   # run recipes against the headless core');
+
+  const canonicalFixture = walletFixturePath(target);
+
+  if (sub === 'sync') {
+    const exitCode = fixturesSync(adapter, target, json);
+    if (json) {
+      console.log(
+        JSON.stringify(
+          { schemaVersion: 1, command: 'fixtures', action: 'sync', adapter, fixture: canonicalFixture, exitCode },
+          null,
+          2,
+        ),
+      );
+    }
+    return exitCode;
+  }
+
+  // set — apply THE canonical wallet fixture (password read FROM the fixture).
+  // Env-gap resolution (docs/CLI-SPEC.md Part 4): flag > env RECIPE_WALLET_FIXTURE
+  // > the slot's canonical fixture.
+  const fixturePath = path.resolve(str(options, 'fixture') ?? process.env.RECIPE_WALLET_FIXTURE ?? canonicalFixture);
+  let status: 'pass' | 'fail';
+  if (adapter === 'mobile') {
+    // Compose setup-wallet.sh directly (requires bridge to be live).
+    const setupWalletSh = path.join(runnerDir, 'adapters/mobile/bridge-runtime/setup-wallet.sh');
+    const previousAppRoot = process.env.APP_ROOT;
+    process.env.APP_ROOT = target;
+    try {
+      let result = spawnScript(setupWalletSh, ['--fixture', fixturePath], target, json);
+      // One clean-Metro auto-retry on recoverable failures (CDP unreachable, bridge
+      // not installed). RECIPE_SETUP_WALLET_RETRIED guards against infinite loops.
+      if (result.status !== 0 && isRecoverableSetupWalletFailure(result.output) && !process.env['RECIPE_SETUP_WALLET_RETRIED']) {
+        process.env['RECIPE_SETUP_WALLET_RETRIED'] = '1';
+        if (!json) process.stderr.write('  setup-wallet: recoverable failure — restarting Metro and retrying\n  Next: wait for relaunch, then wallet setup will retry automatically\n');
+        const { prepareMobile } = await import('../adapters/mobile/prepare.ts');
+        const platform = str(options, 'platform') ?? process.env['MOBILE_PLATFORM'] ?? 'ios';
+        const relaunchResult = await prepareMobile(target, { platform, json, preflightMode: 'auto', clearMetro: true });
+        if (relaunchResult.status === 0) {
+          result = spawnScript(setupWalletSh, ['--fixture', fixturePath], target, json);
+        }
+      }
+      status = result.status === 0 ? 'pass' : 'fail';
+    } finally {
+      delete process.env['RECIPE_SETUP_WALLET_RETRIED'];
+      if (previousAppRoot === undefined) delete process.env.APP_ROOT;
+      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');
+    }
+  } else {
+    // Extension has no standalone set arm — reuse call's one-node machinery via
+    // the real engine path (metamask.wallet.setup in the manifest).
+    if (!fs.existsSync(fixturePath)) {
+      return usageOut(
+        json,
+        'fixtures',
+        `no wallet fixture at ${fixturePath}.\n  Next: create it (or pass --fixture <path>), then re-run: mm-harness fixtures set`,
+      );
+    }
+    const previousFixtureEnv = process.env.RECIPE_WALLET_FIXTURE;
+    process.env.RECIPE_WALLET_FIXTURE = fixturePath;
+    try {
+      const result = await deps.runOneNode('extension', 'metamask.wallet.setup', {}, target, str(options, 'actionManifest'));
+      status = result.status;
+    } finally {
+      if (previousFixtureEnv === undefined) delete process.env.RECIPE_WALLET_FIXTURE;
+      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');
+    }
+  }
+
+  // Always teach where to customize the wallet.
+  const teaching = `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}`;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: 'fixtures',
+          action: 'set',
+          adapter,
+          fixture: fixturePath,
+          canonicalFixture,
+          status,
+          exitCode: status === 'pass' ? EXIT.ok : EXIT.runtime,
+          message: teaching,
+          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',
+          } : null,
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.error(teaching);
+  }
+  return status === 'pass' ? EXIT.ok : EXIT.runtime;
+}
+
+// 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 {
+  const mmHarnessBin = path.join(runnerDir, 'bin/mm-harness');
+  const installResult = spawnScript(
+    mmHarnessBin,
+    ['install', '--adapter', adapter, '--target', target],
+    target,
+    json,
+  );
+  if (installResult.status !== 0) {
+    if (!json) {
+      console.error(`✗ mm-harness fixtures sync: overlay reinstall failed.\n  Next: mm-harness install --target ${target}   # diagnose the install failure`);
+    }
+    return EXIT.runtime;
+  }
+
+  const syncFixtureSh = path.join(runnerDir, 'adapters/shared/sync-wallet-fixture.sh');
+  const syncArgs = ['--target', target];
+  if (process.env.CDP_PORT) syncArgs.push('--cdp-port', process.env.CDP_PORT);
+  if (process.env.RECIPE_SLOT_ID) syncArgs.push('--slot-id', process.env.RECIPE_SLOT_ID);
+  spawnScript(syncFixtureSh, syncArgs, target, json);
+  // Non-zero from sync-wallet-fixture.sh is informational (no fixture source);
+  // the install succeeded so the overlay is fresh.
+  return EXIT.ok;
+}

package/{runner/src → src}/commands/launch.ts

@@ -1,26 +1,28 @@
 // launch — start the app (Metro/build + surface), auto-ensure the runtime overlay,
 // and heal transport within bounds. Owns launch grammar, build-tier selection,
-// quick-launch change detection, and the --json contract. Device orchestration is
-// not rewritten: each tier composes the same porcelain the standalone bins expose,
-// and --verify reuses the overlay `live` sequence via handleHarness.
+// quick-launch change detection, and the --json contract. Device orchestration
+// composes adapters/ scripts directly; --verify reuses the overlay `live`
+// sequence via handleHarness.
 
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
+import path from 'node:path';
 
 import { handleHarness } from '../harness.ts';
-import { recipeRuntimePath } from '../paths.ts';
+import { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, runnerDir } from '../paths.ts';
 import type { MetaMaskRecipeAdapter } from '../types.ts';
+import { prepareMobile } from '../adapters/mobile/prepare.ts';
 import {
   EXIT,
   flag,
   parseFlags,
   resolveAdapter,
-  spawnPorcelain,
+  spawnScript,
   str,
   targetOf,
   usageOut,
 } from './shared.ts';
-import type { DeviceAdapter } from './shared.ts';
+import type { DeviceAdapter, ScriptResult } from './shared.ts';
 import {
   RECOVERY_CODE,
   checkHealBounds,
@@ -36,7 +38,7 @@ interface LaunchFailure {
   recoverable: boolean;
   userAction?: string;
   exitCode: number;
-  // The original porcelain output, surfaced verbatim (never replaced by the note).
+  // The original script output, surfaced verbatim (never replaced by the note).
   originalError?: string;
 }
 
@@ -112,7 +114,7 @@ export async function handleLaunch(argv: string[]): Promise<number> {
       return usageOut(json, 'launch', `--${portFlag === 'cdpPort' ? 'cdp-port' : 'watcher-port'} must be numeric (got: ${value}).`);
     }
   }
-  applyLaunchEnvOverrides(options, adapter, mobileTarget);
+  applyLaunchEnvOverrides(options, adapter, mobileTarget, target);
 
   const tier = wantVerify ? 'verify' : wantBuild ? 'build' : 'quick';
   const state = newHealState();
@@ -152,9 +154,8 @@ export async function handleLaunch(argv: string[]): Promise<number> {
     return code;
   }
 
-  // Compose the launch tier via the porcelain (same path the porcelain commands use).
-  const launchArgs = launchComposition(adapter, mobileTarget, tier, wantWatch);
-  let attempt = spawnPorcelain(adapter, launchArgs, target, json);
+  // Compose the launch tier: mobile runs in-process; extension spawns adapters/ scripts.
+  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json);
 
   if (attempt.status === 0) {
     return finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state);
@@ -182,12 +183,12 @@ export async function handleLaunch(argv: string[]): Promise<number> {
     });
   }
 
-  // Infra recovery: attempt the SAME launch exactly once (the porcelain restarts
-  // Metro / reopens Chrome). Push recoveryCode BEFORE the attempt so any
-  // subsequent checkHealBounds call sees it and refuses a second loop.
+  // Infra recovery: attempt the SAME launch exactly once (Metro restarts /
+  // Chrome reopens). Push recoveryCode BEFORE the attempt so any subsequent
+  // checkHealBounds call sees it and refuses a second loop.
   const recoveryCode = RECOVERY_CODE[adapter];
   state.attemptedRecoveries.push(recoveryCode);
-  attempt = spawnPorcelain(adapter, launchArgs, target, json);
+  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json);
   if (attempt.status === 0) {
     state.recovered.push(recoveryCode);
     return finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state);
@@ -202,15 +203,70 @@ export async function handleLaunch(argv: string[]): Promise<number> {
   });
 }
 
-// Map the env-gap flags onto the env vars the porcelain reads. Only the canonical
-// var plus its documented aliases are set, and only when the flag is present, so
-// flag > env > config/default holds. --device targets the simulator (ios) or the
-// adb serial (android); ports are set with their runtime aliases.
+// 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
+// win over everything. Extension: flag > env > config/default.
 function applyLaunchEnvOverrides(
   options: Record<string, string | boolean>,
   adapter: DeviceAdapter,
   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);
+
   const device = str(options, 'device');
   if (device && adapter === 'mobile') {
     if (mobileTarget === 'android') {
@@ -261,35 +317,119 @@ function nativeInputsChanged(target: string, adapter: MetaMaskRecipeAdapter): bo
   }
 }
 
-// Map (adapter, tier) → the grounded porcelain sub-command.
-//   mobile quick : mm-recipe <ios|android>       (quick relaunch)
-//   mobile build : mm-recipe up                  (decision-aware full build)
-//   extension quick: mme-recipe rebuild          (snapshot dist + reopen)
-//   extension build: mme-recipe build            (webpack build)
-//   extension watch: mme-recipe watch            (webpack watch)
-function launchComposition(
+// Execute the launch composition for (adapter, tier). Mobile runs prepareMobile()
+// in-process (no shell orchestrator); extension arms spawn adapters/ scripts directly.
+//
+//   mobile quick|build → prepareMobile() in-process → leaf scripts
+//   extension rebuild  → kill watcher + clear rebuild.log + live.sh --start-watch
+//   extension build    → adapters/extension/start-watch.sh
+//   extension watch    → adapters/extension/start-watch.sh
+async function executeComposition(
   adapter: DeviceAdapter,
   mobileTarget: string | undefined,
   tier: 'quick' | 'build' | 'verify',
   wantWatch: boolean,
-): string[] {
+  target: string,
+  json: boolean,
+): Promise<ScriptResult> {
   if (adapter === 'mobile') {
-    if (tier === 'build') return ['up'];
-    return [mobileTarget ?? 'ios'];
+    const platform = mobileTarget ?? 'ios';
+    const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : undefined;
+    const preflightMode = tier === 'build' ? 'auto' : 'fast';
+    return prepareMobile(target, { platform, json, watcherPort, preflightMode });
+  }
+
+  // Extension rebuild (quick relaunch): kill watcher → clear rebuild.log → live.sh --start-watch.
+  if (!wantWatch && tier === 'quick') {
+    return extensionRebuild(target, json);
+  }
+
+  // Extension build or watch: full webpack compile via start-watch.sh.
+  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);
+}
+
+// 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 {
+  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 */ }
+
+  // E1c: Clear the rebuild log (directory must exist for tee).
+  fs.mkdirSync(path.dirname(rebuildLog), { recursive: true });
+  fs.writeFileSync(rebuildLog, '');
+
+  const liveScript = recipeHarnessPath(target, 'extension', 'scripts', 'live.sh');
+  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);
+  // Tee live.sh output into rebuild.log for post-mortem diagnosis.
+  if (result.output) {
+    try { fs.appendFileSync(rebuildLog, result.output); } catch { /* best-effort */ }
   }
-  // extension
-  if (wantWatch) return ['watch'];
-  if (tier === 'build') return ['build'];
-  return ['rebuild'];
+  return result;
 }
 
-// Apply the extension display mode AFTER the base launch succeeded, then emit the
-// pass summary. Fullscreen = the plain rebuild/build/watch launch above (the
-// default popup/home window). Sidepanel additionally drives the chrome.sidePanel
-// mechanism via the porcelain: `mme-recipe sidepanel open`
-// (orchestration/porcelain/mme-recipe → orchestration/extension/sidepanel-toggle.sh `open`), so
-// --sidepanel and --fullscreen compose DIFFERENT porcelain calls and the display
-// mode actually reaches orchestration. Mobile has no side panel, so the flag is a
+// Apply the extension display mode AFTER the base launch succeeded, then emit
+// the pass summary. Fullscreen = the plain rebuild/build/watch launch above
+// (default popup/home window). Sidepanel additionally drives the
+// chrome.sidePanel mechanism via adapters/extension/sidepanel-toggle.sh.
+// --sidepanel and --fullscreen compose DIFFERENT script calls and the display
+// mode actually reaches the browser. Mobile has no side panel; the flag is a
 // no-op there.
 function finishLaunch(
   json: boolean,
@@ -301,12 +441,16 @@ function finishLaunch(
   state: HealState,
 ): number {
   if (adapter === 'extension' && displayMode === 'sidepanel') {
-    const sidepanel = spawnPorcelain('extension', ['sidepanel', 'open'], target, json);
+    const sidepanelSh = path.join(runnerDir, 'adapters/extension/sidepanel-toggle.sh');
+    const sidepanelArgs = ['open'];
+    if (process.env.CDP_PORT) sidepanelArgs.push('--cdp-port', process.env.CDP_PORT);
+    const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, json);
     if (sidepanel.status !== 0) {
       return launchFail(json, adapter, mobileTarget, tier, state, {
         code: 'SIDEPANEL_OPEN_FAILED',
         message: 'app launched but opening the side panel failed.',
         recoverable: false,
+        userAction: `bash adapters/extension/sidepanel-toggle.sh open --cdp-port ${process.env.CDP_PORT ?? '<CDP_PORT>'}`,
         exitCode: EXIT.runtime,
         originalError: sidepanel.output.trim() || undefined,
       });

package/src/commands/logs.ts

@@ -0,0 +1,86 @@
+// logs — tail Metro/webpack + app logs by composing log-tui.mjs (compact) or
+// plain `tail -f` (--full). Teaches (exit 2) when nothing is running for the
+// checkout.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { recipeRuntimePath, runnerDir } from '../paths.ts';
+import { EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
+
+const LOGS_BOOLEANS = new Set(['full', 'json']);
+
+export async function handleLogs(argv: string[]): Promise<number> {
+  const { options } = parseFlags(argv, LOGS_BOOLEANS);
+  const json = flag(options, 'json');
+  const target = targetOf(options);
+  const adapter = resolveAdapter(options, target);
+
+  if (!adapter) {
+    return usageOut(
+      json,
+      'logs',
+      `could not detect the MetaMask repo type for ${target}\n  Next: pass --target <checkout>   or   cd into the checkout, then re-run: mm-harness logs`,
+    );
+  }
+  if (adapter === 'core') {
+    return usageOut(json, 'logs', 'core is headless; there are no app/Metro logs.\n  Next: mm-harness run <recipe>   # run recipes against the headless core');
+  }
+
+  const source = str(options, 'source') ?? 'metro';
+  if (source !== 'metro' && source !== 'app') {
+    return usageOut(json, 'logs', '--source must be metro or app.\n  Next: mm-harness logs --source metro   or   mm-harness logs --source app');
+  }
+
+  // Env-gap flag (docs/CLI-SPEC.md Part 4): --events sets the compact event count
+  // read from RECIPE_LOG_EVENTS. Resolution is flag > env > default: the flag wins
+  // by setting the env; an absent flag leaves the agent/CI env alone.
+  const events = str(options, 'events');
+  if (events !== undefined) {
+    if (!/^\d+$/u.test(events)) {
+      return usageOut(json, 'logs', `--events must be numeric (got: ${events}).\n  Next: mm-harness logs --events 20`);
+    }
+    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';
+    return usageOut(
+      json,
+      'logs',
+      `nothing running for this checkout (no ${path.basename(logFile)}).\n  Next: ${launchHint}`,
+    );
+  }
+
+  const full = flag(options, 'full');
+  if (full) {
+    // Raw follow: the human explicitly wants unfiltered output.
+    const result = spawnScript('tail', ['-n', '+1', '-F', logFile], target, json);
+    return result.status === 0 ? EXIT.ok : EXIT.runtime;
+  }
+
+  // Compact mode: last N events + pointer to full log.
+  const logTui = path.join(runnerDir, 'adapters/shared/log-tui.mjs');
+  const eventCount = process.env.RECIPE_LOG_EVENTS ?? '20';
+  const uiMode = process.env.RECIPE_LOG_UI_MODE ?? 'compact';
+  const result = spawnScript(
+    process.execPath,
+    [logTui, 'tail', '--log', logFile, '--events', eventCount, '--follow', '--mode', uiMode],
+    target,
+    json,
+  );
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: 'logs', adapter, source, logFile, exitCode: result.status === 0 ? EXIT.ok : EXIT.runtime },
+        null,
+        2,
+      ),
+    );
+  }
+  return result.status === 0 ? EXIT.ok : EXIT.runtime;
+}