@deeeed/metamask-harness 0.3.9 → 0.5.0

package/src/cli.ts

@@ -28,6 +28,8 @@ import { ensureExtensionReady } from './adapters/extension/ensure-ready.ts';
 import { resolveExtensionId } from './adapters/extension/extension-id.ts';
 import { decideExtensionReadiness } from './adapters/extension/runtime-decision.ts';
 import { decideMobileReadiness } from './adapters/mobile/runtime-decision.ts';
+import { getAdapterSurface } from './adapters/surface.ts';
+import type { AdapterRuntimeStatus } from './adapters/surface.ts';
 // NOTE: extension-runtime.ts loads the recipe harness at module scope, so it
 // is imported LAZILY (dynamic import) only inside the handlers that drive a live
 // runtime. Static-import it here and every command — manifest, doctor,
@@ -66,6 +68,7 @@ type CliOptions = Record<string, CliOptionValue>;
 interface ParsedArgs {
   positional: string[];
   options: CliOptions;
+  rawArgv: string[];
 }
 
 interface RuntimeOptions {
@@ -103,6 +106,7 @@ const COMMANDS: Record<string, (args: ParsedArgs) => Promise<number>> = {
   'runtime-health': handleRuntimeHealth,
   'runtime-decision': handleRuntimeDecision,
   'runtime-launch': handleRuntimeLaunch,
+  provision: handleProvision,
   'resolve-extension': handleResolveExtension,
   'ensure-ready': handleEnsureReady,
   run: handleRun,
@@ -112,7 +116,7 @@ const COMMANDS: Record<string, (args: ParsedArgs) => Promise<number>> = {
 // Top-level runtime-overlay commands (the tool installs a runtime overlay).
 // Top-level overlay commands route to handleHarness; the `harness <sub>`
 // subcommand form has been removed from the CLI surface.
-const OVERLAY_COMMANDS: readonly string[] = ['install', 'verify', 'cleanup', 'live'];
+const OVERLAY_COMMANDS: readonly string[] = ['install', 'provision', 'verify', 'cleanup', 'live'];
 
 function usage() {
   // Help is organized by the harness mental model: mm-harness IS the tool; a
@@ -174,7 +178,7 @@ See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).
 function parseArgs(argv: string[], command?: string): ParsedArgs {
   const positional: string[] = [];
   const options: CliOptions = {};
-  const booleanOptions = new Set(['json', 'launchExistingDist', 'startWatch', 'record', 'plan', 'raw', 'fix']);
+  const booleanOptions = new Set(['json', 'launchExistingDist', 'startWatch', 'record', 'plan', 'raw', 'fix', 'force', 'resolveOnly']);
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (!arg.startsWith('--')) {
@@ -214,7 +218,7 @@ function parseArgs(argv: string[], command?: string): ParsedArgs {
     options[key] = argv[i + 1];
     i += 1;
   }
-  return { positional, options };
+  return { positional, options, rawArgv: [...argv] };
 }
 
 function parseRecordVideoMode(value: string | undefined): false | 'full-run' {
@@ -247,6 +251,20 @@ function optionFlag(options: CliOptions, key: string): boolean {
   return value === true;
 }
 
+
+function applyRuntimeDirOption(options: CliOptions): void {
+  const runtimeDir = optionString(options, 'runtimeDir');
+  if (runtimeDir) process.env.RECIPE_RUNTIME_DIR = runtimeDir;
+}
+
+function applyWatcherPortOption(options: CliOptions): void {
+  const watcherPort = optionString(options, 'watcherPort');
+  if (!watcherPort) return;
+  process.env.WATCHER_PORT = watcherPort;
+  process.env.RECIPE_WATCHER_PORT = watcherPort;
+  process.env.METRO_PORT = watcherPort;
+}
+
 function requiredOption(options: CliOptions, key: string, message: string): string {
   const value = optionString(options, key);
   if (!value) throw usageError(message);
@@ -448,6 +466,7 @@ async function handleActions({ options }: ParsedArgs): Promise<number> {
 }
 
 async function handleDoctor({ options }: ParsedArgs): Promise<number> {
+  applyRuntimeDirOption(options);
   const target = targetPath(options);
   // Share the exact detect-from-target logic the overlay commands (verify/install/
   // cleanup) use: when --adapter/--platform is omitted, auto-detect from the
@@ -476,35 +495,33 @@ async function handleDoctor({ options }: ParsedArgs): Promise<number> {
   }
 
   const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
-  // Live runtime state, per platform: mobile reports the same read-only readiness
-  // the launch decision uses (deps currency, Metro on the slot's port, decision +
-  // reasons). Extension/core gain their sections when their readiness probes exist.
-  let runtime: { decision: string; reasonCode?: string; reasons: string[]; deps?: string; metro?: string } | undefined;
-  if (adapter === 'mobile') {
-    try {
-      const { mobileRuntimeStatus } = await import('./adapters/mobile/prepare.ts');
-      const { resolveMobileSlotPorts } = await import('./commands/launch.ts');
-      resolveMobileSlotPorts(target);
-      const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : undefined;
-      const report = await mobileRuntimeStatus(target, { watcherPort });
-      runtime = {
-        decision: report.decision,
-        reasonCode: report.reasonCode,
-        reasons: report.reasons,
-        deps: report.checks?.deps?.status,
-        metro: report.checks?.metro?.status,
-      };
-    } catch { /* readiness probe unavailable — doctor stays useful without it */ }
-  }
+  // Live runtime state, per platform, via the adapter surface: every adapter
+  // reports the same read-only readiness shape (decision + reasons, deps currency,
+  // and its dev server where it has one) so doctor renders one line the same way
+  // for mobile, extension, and core. doctor never branches on adapter for this.
+  let runtime: AdapterRuntimeStatus | undefined;
+  try {
+    const surface = getAdapterSurface(adapter);
+    surface.resolveSlotPorts(target);
+    runtime = await surface.runtimeStatus(target);
+  } catch { /* readiness probe unavailable — doctor stays useful without it */ }
   if (json) console.log(JSON.stringify({ ...result, runtime }, null, 2));
   else {
     const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
     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 provisionedDepsPending = runtime.reasonCode === 'app-installed-deps-pending';
+      const decisionStyle = provisionedDepsPending
+        ? 'info'
+        : runtime.decision === 'ready' ? 'ok' : runtime.decision === 'blocked' ? 'err' : 'warn';
+      const depsStyle = provisionedDepsPending ? 'info' : stateStyle(runtime.deps, 'current');
+      const devServerStyle = provisionedDepsPending ? 'info' : undefined;
+      const devServer = runtime.devServer
+        ? ` ${runtime.devServer.label}=${out(devServerStyle ?? stateStyle(runtime.devServer.status, 'up'), runtime.devServer.status)}`
+        : '';
       console.log(
-        `${out('label', 'runtime:')} decision=${out(decisionStyle, runtime.decision)}${runtime.reasonCode ? ` ${out('dim', `(${runtime.reasonCode})`)}` : ''} deps=${out(stateStyle(runtime.deps, 'current'), runtime.deps ?? 'unknown')} metro=${out(stateStyle(runtime.metro, 'up'), runtime.metro ?? 'unprobed')}`,
+        `${out('label', 'runtime:')} decision=${out(decisionStyle, runtime.decision)}${runtime.reasonCode ? ` ${out('dim', `(${runtime.reasonCode})`)}` : ''} deps=${out(depsStyle, runtime.deps ?? 'unknown')}${devServer}`,
       );
       for (const reason of runtime.reasons) console.log(`  ${out('dim', reason)}`);
     }
@@ -614,6 +631,126 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+async function handleProvision({ positional, options, rawArgv }: ParsedArgs): Promise<number> {
+  applyWatcherPortOption(options);
+  const json = optionFlag(options, 'json');
+  const { adapter, target } = resolveProvisionAdapter(options);
+  const surface = getAdapterSurface(adapter);
+  const rerunCommand = provisionRerunCommand(rawArgv, options, adapter, target);
+  const result = await surface.runwayProvision.run(target, {
+    json,
+    platform: optionString(options, 'platform') ?? optionString(options, 'devicePlatform') ?? (positional[0] === 'runway' ? positional[1] : positional[0]) ?? 'ios',
+    branch: optionString(options, 'branch'),
+    defaultBranch: optionString(options, 'defaultBranch'),
+    run: optionString(options, 'run'),
+    cacheRoot: optionString(options, 'cacheRoot'),
+    simulator: optionString(options, 'simulator') ?? optionString(options, 'device'),
+    runtime: optionString(options, 'runtime'),
+    deviceType: optionString(options, 'deviceType'),
+    slot: optionString(options, 'slot'),
+    watcherPort: optionString(options, 'watcherPort'),
+    runtimeDir: optionString(options, 'runtimeDir'),
+    force: optionFlag(options, 'force'),
+    resolveOnly: optionFlag(options, 'resolveOnly'),
+    rerunCommand,
+  });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.status === 'pass') {
+    const cache = typeof result.cache === 'object' && result.cache ? result.cache as Record<string, unknown> : undefined;
+    const simulator = typeof result.simulator === 'object' && result.simulator ? result.simulator as Record<string, unknown> : undefined;
+    const artifact = typeof result.artifact === 'object' && result.artifact ? result.artifact as Record<string, unknown> : undefined;
+    if (result.resolveOnly) {
+      console.error(`✓ resolved ${adapter} ${result.platform ?? ''} run=${artifact?.runId ?? 'unknown'} revision=${artifact?.revision ?? 'unknown'} artifact=${artifact?.artifactName ?? 'unknown'}`);
+    } else {
+      const action = result.skipped ? 'already provisioned' : 'provisioned';
+      console.error(`✓ ${action} ${adapter} ${result.platform ?? ''} simulator=${simulator?.name ?? 'unknown'} cache=${cache?.status ?? 'unknown'}`);
+    }
+  } else {
+    console.error(`✗ mm-harness provision: ${result.error?.message ?? 'provision failed'}\n  Next: ${result.error?.userAction ?? rerunCommand}`);
+  }
+  return result.exitCode;
+}
+
+function resolveProvisionAdapter(options: CliOptions): { adapter: MetaMaskRecipeAdapter; target: string } {
+  const target = targetPath(options);
+  const adapter = optionString(options, 'adapter') ?? detectAdapter(target);
+  if (!adapter) {
+    throw usageError(`could not detect the MetaMask repo type for ${target}\n  Next: ${ADAPTER_DETECT_NEXT}`);
+  }
+  try {
+    assertAdapter(adapter);
+  } catch (error) {
+    throw usageError(error instanceof Error ? error.message : String(error));
+  }
+  return { adapter, target };
+}
+
+function provisionRerunCommand(rawArgv: string[], options: CliOptions, adapter: MetaMaskRecipeAdapter, target: string): string {
+  const parts = ['mm-harness', 'provision'];
+  for (const positional of provisionPositionals(rawArgv)) parts.push(shellQuoteArg(positional));
+  parts.push('--adapter', adapter, '--target', shellQuote(target));
+  const aliases: Array<[string, string[]]> = [
+    ['platform', ['--platform', '--device-platform']],
+    ['branch', ['--branch']],
+    ['defaultBranch', ['--default-branch']],
+    ['run', ['--run']],
+    ['cacheRoot', ['--cache-root']],
+    ['simulator', ['--simulator', '--device']],
+    ['runtime', ['--runtime']],
+    ['deviceType', ['--device-type']],
+    ['slot', ['--slot']],
+    ['watcherPort', ['--watcher-port']],
+    ['runtimeDir', ['--runtime-dir']],
+  ];
+  for (const [key, flags] of aliases) {
+    const found = findRawOption(rawArgv, flags);
+    const value = found?.value ?? optionString(options, key);
+    if (value) parts.push(found?.flag ?? flags[0], shellQuoteArg(value));
+  }
+  if (optionFlag(options, 'force')) parts.push('--force');
+  if (optionFlag(options, 'resolveOnly')) parts.push('--resolve-only');
+  if (optionFlag(options, 'json')) parts.push('--json');
+  return parts.join(' ');
+}
+
+function provisionPositionals(rawArgv: string[]): string[] {
+  const positionals: string[] = [];
+  const valueFlags = new Set([
+    '--adapter', '--target', '--project-root', '--platform', '--device-platform', '--branch', '--default-branch',
+    '--run', '--cache-root', '--simulator', '--device', '--runtime', '--device-type', '--slot', '--watcher-port',
+    '--runtime-dir',
+  ]);
+  for (let i = 0; i < rawArgv.length; i += 1) {
+    const arg = rawArgv[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    const key = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+    if (!arg.includes('=') && valueFlags.has(key)) i += 1;
+  }
+  return positionals;
+}
+
+function findRawOption(rawArgv: string[], flags: string[]): { flag: string; value: string } | undefined {
+  for (let i = 0; i < rawArgv.length; i += 1) {
+    const arg = rawArgv[i];
+    for (const flag of flags) {
+      if (arg === flag) {
+        const value = rawArgv[i + 1];
+        return value && !value.startsWith('--') ? { flag, value } : undefined;
+      }
+      if (arg.startsWith(`${flag}=`)) return { flag, value: arg.slice(flag.length + 1) };
+    }
+  }
+  return undefined;
+}
+
+function shellQuoteArg(value: string): string {
+  return /^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : shellQuote(value);
+}
+
 async function handleRuntimeHealth({ options }: ParsedArgs): Promise<number> {
   const adapter = adapterOption(options);
   if (adapter !== 'extension') throw new Error('runtime-health currently applies to the extension adapter.');
@@ -774,6 +911,7 @@ function readJsonIfExists(file: string): unknown {
 }
 
 async function handleRuntimeDecision({ options }: ParsedArgs): Promise<number> {
+  applyRuntimeDirOption(options);
   const adapter = adapterOption(options);
   const target = targetPath(options);
   if (adapter === 'mobile') {
@@ -1117,23 +1255,21 @@ async function handleStop(argv: string[]): Promise<number> {
   const { options } = parseArgs(argv, 'stop');
   const json = optionFlag(options, 'json');
   const { adapter, target } = resolveAdapter(options);
-  if (adapter !== 'mobile') {
-    return usageOut(
-      json,
-      'stop',
-      `stop owns the mobile Metro dev server; the ${adapter} dev server is slot-managed`,
-      'stop the extension watcher via its runtime pids: kill $(cat <runtime_dir>/webpack.pid); core runs no dev server',
-    );
+  const surface = getAdapterSurface(adapter);
+  // Slot-scope the stop: an explicit --port wins, else resolve the checkout's
+  // own dev-server port so a concurrent slot's server is never signalled.
+  const explicitPort = optionString(options, 'port') ?? optionString(options, 'watcherPort');
+  if (explicitPort) {
+    process.env.WATCHER_PORT = explicitPort;
+    process.env.METRO_PORT = explicitPort;
+  } else {
+    surface.resolveSlotPorts(target);
+  }
+  const stop = surface.devServer.stop(target);
+  if (stop.kind === 'headless') {
+    // core has no dev server — teach the reachable headless path (exit 2).
+    return usageOut(json, 'stop', stop.message, stop.userAction);
   }
-  const leaf = path.join(runnerDir, 'adapters', 'mobile', 'stop-metro.sh');
-  const args = ['--target', target];
-  const port = optionString(options, 'port') ?? optionString(options, 'watcherPort');
-  if (port) args.push('--port', port);
-  const result = spawnSync('bash', [leaf, ...args], {
-    stdio: json ? 'pipe' : 'inherit',
-    encoding: 'utf8',
-  });
-  const exitCode = result.status ?? 1;
   if (json) {
     console.log(
       JSON.stringify(
@@ -1142,16 +1278,22 @@ async function handleStop(argv: string[]): Promise<number> {
           command: 'stop',
           adapter,
           target,
-          status: exitCode === 0 ? 'pass' : 'fail',
-          exitCode,
-          output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim(),
+          status: stop.status === 0 ? 'pass' : 'fail',
+          ...(stop.signalled !== undefined ? { signalled: stop.signalled } : {}),
+          exitCode: stop.status,
+          ...(stop.output ? { output: stop.output } : {}),
         },
         null,
         2,
       ),
     );
+  } else {
+    // The leaf may have captured its own detail; surface it, then the uniform
+    // outcome line the same way for every platform.
+    if (stop.output) process.stderr.write(`${stop.output}\n`);
+    console.error(`${color(stop.status === 0 ? 'ok' : 'err', stop.status === 0 ? '✓' : '✗')} ${stop.summary}`);
   }
-  return exitCode;
+  return stop.status;
 }
 
 async function handleCall(argv: string[]): Promise<number> {
@@ -1168,9 +1310,23 @@ async function handleCall(argv: string[]): Promise<number> {
   const { options } = parseArgs(rest, 'call');
   const json = optionFlag(options, 'json');
   if (!shortName) {
-    const message = 'call requires <action>. Example: mm-harness call unlock --adapter extension';
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', error: { code: 'USAGE', message } }, null, 2));
-    else console.error(message);
+    // Context-aware usage: the example uses the DETECTED adapter and a REAL action
+    // from its manifest — never a hardcoded action/adapter that may not exist in
+    // this checkout — and points at the scoped discovery command.
+    let example = 'mm-harness call <action>';
+    let discovery = 'mm-harness actions';
+    try {
+      const { adapter } = resolveAdapter(options);
+      const manifest = loadActionManifest(adapter, optionString(options, 'actionManifest'));
+      const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+      const exampleAction = pickCallExampleAction(getRecipeActionManifestActionNames(manifest));
+      example = `mm-harness call ${exampleAction} --adapter ${adapter}`;
+      discovery = `mm-harness actions --adapter ${adapter}`;
+    } catch { /* adapter/manifest unavailable — keep the generic example */ }
+    const message = `call requires <action>. Example: ${example}`;
+    const userAction = `${example}   # see the vocabulary: ${discovery}`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: 'call', error: { code: 'USAGE', message, userAction } }, null, 2));
+    else console.error(`${message}\n  See the vocabulary: ${discovery}`);
     return EXIT.usage;
   }
 
@@ -1340,6 +1496,16 @@ function resolveActionName(shortName: string, names: string[]): ActionResolution
   return { status: 'unknown', resolved: '', candidates: [] };
 }
 
+// A real action name to show in the `call` usage example, from THIS adapter's
+// manifest: a wallet action when the platform has one, else the universal
+// `command` action, else the first declared name. Never a hardcoded guess.
+function pickCallExampleAction(names: string[]): string {
+  const walletish = names.find((name) => /wallet|unlock/u.test(name));
+  if (walletish) return walletish;
+  if (names.includes('command')) return 'command';
+  return names[0] ?? 'command';
+}
+
 function synthesizeOneNodeRecipe(action: string, args: Record<string, string>): Record<string, unknown> {
   return {
     schema_version: 1,
@@ -1794,6 +1960,16 @@ function serializeLibrarySources(sources: MetaMaskLibrarySource[]): string {
     .join(':');
 }
 
+// Map a resolved library source to its precedence tier for the flows legend, from
+// the ACTUAL resolution rather than an invented label: the canonical MetaMask
+// library this runner appends last, the personal library the harness names
+// 'personal', and any other configured library in between as the team/shared tier.
+function flowSourceTier(source: MetaMaskLibrarySource, index: number, total: number): string {
+  if (index === total - 1 && source.name === 'metamask') return 'canonical';
+  if (source.name === 'personal') return 'personal';
+  return 'team';
+}
+
 // The engine's flows subcommands (grounded in registerFlowsCommand): a bare
 // `flows` (or one that leads with a flag) means list.
 const FLOWS_SUBCOMMANDS: readonly string[] = ['list', 'promote'];
@@ -1824,11 +2000,25 @@ async function handleFlows(argv: string[]): Promise<number> {
   const sources = await resolveMetaMaskLibrarySources(undefined);
   if (!sources) {
     throw usageError(
-      'flows requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support). ' +
+      'flows requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support; ' +
+        'flows resolve personal > team > canonical). ' +
         'Next: update the dependency and run yarn install.',
     );
   }
   const forwarded = stripTargetFlag(argv);
+  const jsonMode = forwarded.includes('--json');
+  // Provenance: flows resolve by precedence — the highest-precedence copy of a ref
+  // wins and shadows lower ones, so a LOCAL library outranks canonical. The listing
+  // below prints `source=<name>` per flow; this legend maps each resolved source to
+  // its tier so that source is decodable. --json reserves stdout for the engine
+  // envelope, so the legend rides stderr only.
+  if (!jsonMode) {
+    console.error(color('label', 'flows resolve by precedence (highest wins; local shadows canonical):'));
+    sources.forEach((source, index) => {
+      const name = source.name ?? path.basename(source.root);
+      console.error(`  ${index + 1}. ${color('cmd', name)} ${color('dim', `[${flowSourceTier(source, index, sources.length)}]`)}`);
+    });
+  }
   // The engine requires an explicit subcommand. Inspect only the FIRST token: a
   // real subcommand there is passed through; anything else (empty, or a leading
   // flag whose VALUE must not be mistaken for a subcommand) defaults to list.

package/src/commands/debug.ts

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

package/src/commands/fixtures.ts

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