@deeeed/metamask-harness 0.3.9 → 0.5.0

package/src/commands/launch.ts

@@ -9,10 +9,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { color } from '../cli-color.ts';
-import { handleHarness, readRuntimeContextField, resolveRuntimeContextPath } from '../harness.ts';
+import { handleHarness } from '../harness.ts';
 import { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, runnerDir } from '../paths.ts';
 import type { MetaMaskRecipeAdapter } from '../types.ts';
 import { prepareMobile } from '../adapters/mobile/prepare.ts';
+import { getAdapterSurface } from '../adapters/surface.ts';
+import { stopExtensionWatcher } from '../adapters/slot-ports.ts';
 import {
   ADAPTER_DETECT_NEXT,
   EXIT,
@@ -207,111 +209,6 @@ export async function handleLaunch(argv: string[]): Promise<number> {
   });
 }
 
-// Apply KEY=VALUE lines from slot resolution to process.env.
-// overwrite=true → pool match, always overrides existing env.
-// overwrite=false → formula match, only fills vars that are unset.
-function applyKVLines(output: string, overwrite: boolean): void {
-  for (const line of output.split('\n')) {
-    const m = /^([A-Z_]+)=(.+)$/u.exec(line.trim());
-    if (!m) continue;
-    const [, key, val] = m;
-    switch (key) {
-      case 'WATCHER_PORT':
-        if (overwrite || !process.env['WATCHER_PORT']) {
-          process.env['WATCHER_PORT'] = val;
-          process.env['METRO_PORT'] = val;
-          process.env['RECIPE_WATCHER_PORT'] = val;
-        }
-        break;
-      case 'IOS_SIMULATOR':
-        if (overwrite || !process.env['IOS_SIMULATOR']) process.env['IOS_SIMULATOR'] = val;
-        break;
-      case 'SLOT_ID':
-        if (overwrite || !process.env['RECIPE_SLOT_ID']) process.env['RECIPE_SLOT_ID'] = val;
-        break;
-      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: 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 {
-  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', [
-      '-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 */ }
-}
-
-// 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
@@ -325,9 +222,9 @@ function applyLaunchEnvOverrides(
   // 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);
+  // adapter hard-fails on a value its slot already knows. The surface owns the
+  // per-platform resolution; this command never branches on adapter for it.
+  getAdapterSurface(adapter).resolveSlotPorts(target);
 
   const device = str(options, 'device');
   if (device && adapter === 'mobile') {
@@ -421,56 +318,10 @@ async function executeComposition(
 async function extensionRebuild(target: string, json: boolean): Promise<ScriptResult> {
   const runtimeDirRel = recipeRuntimeDir();
   const runtimeAbs = path.join(target, runtimeDirRel);
-  const webpackPidFile = path.join(runtimeAbs, 'recipe-harness-webpack.pid');
   const rebuildLog = path.join(runtimeAbs, 'rebuild.log');
 
   // E1a: Kill harness-owned watcher via pid file, then ps-scan for orphans.
-  try {
-    const pid = fs.readFileSync(webpackPidFile, 'utf8').trim();
-    if (/^\d+$/u.test(pid)) {
-      try { process.kill(Number(pid), 'SIGTERM'); } catch { /* already dead */ }
-    }
-    fs.rmSync(webpackPidFile, { force: true });
-  } catch { /* no pid file */ }
-  // Scan for any remaining orphan webpack/yarn-start processes in this checkout.
-  try {
-    const psOut = execFileSync('ps', ['-axo', 'pid=,command='], { encoding: 'utf8' });
-    const orphanPids: number[] = [];
-    for (const line of psOut.split('\n')) {
-      const match = /^\s*(\d+)\s+(.*)$/u.exec(line);
-      if (!match) continue;
-      const [, pidStr, cmd] = match;
-      const isWatcher =
-        cmd.includes('yarn start') ||
-        cmd.includes('webpack --watch') ||
-        cmd.includes('development/webpack/launch.ts --watch');
-      if (!isWatcher) continue;
-      if (cmd.includes(target)) {
-        orphanPids.push(Number(pidStr));
-        continue;
-      }
-      // lsof cwd fallback for processes that don't embed the path in argv.
-      try {
-        const cwd = execFileSync('lsof', ['-a', `-p${pidStr}`, '-dcwd', '-Fn'], {
-          encoding: 'utf8',
-          timeout: 2000,
-        });
-        if (cwd.split('\n').some((l) => l.startsWith('n') && l.slice(1) === target)) {
-          orphanPids.push(Number(pidStr));
-        }
-      } catch { /* lsof unavailable or permission denied */ }
-    }
-    if (orphanPids.length > 0) {
-      for (const pid of orphanPids) {
-        try { process.kill(pid, 'SIGTERM'); } catch { /* already dead */ }
-      }
-      // Brief pause then force-kill survivors.
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2000);
-      for (const pid of orphanPids) {
-        try { process.kill(pid, 'SIGKILL'); } catch { /* already dead */ }
-      }
-    }
-  } catch { /* ps not available */ }
+  stopExtensionWatcher(target);
 
   // E1c: Clear the rebuild log (directory must exist for tee).
   fs.mkdirSync(path.dirname(rebuildLog), { recursive: true });

package/src/commands/logs.ts

@@ -5,7 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { recipeRuntimePath, runnerDir } from '../paths.ts';
+import { runnerDir } from '../paths.ts';
+import { getAdapterSurface } from '../adapters/surface.ts';
 import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
 
 const LOGS_BOOLEANS = new Set(['full', 'json']);
@@ -19,13 +20,23 @@ export async function handleLogs(argv: string[]): Promise<number> {
   if (!adapter) {
     return usageOut(json, 'logs', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
-  if (adapter === 'core') {
-    return usageOut(json, 'logs', 'core is headless; there are no app/Metro logs.', 'mm-harness run <recipe>   # run recipes against the headless core');
+  const surface = getAdapterSurface(adapter);
+  if (surface.headless) {
+    return usageOut(json, 'logs', 'core is headless; it has no dev server logs.', surface.hints.launch);
   }
 
-  const source = str(options, 'source') ?? 'metro';
-  if (source !== 'metro' && source !== 'app') {
-    return usageOut(json, 'logs', '--source must be metro or app.', 'mm-harness logs --source metro   or   mm-harness logs --source app');
+  // Source selection is platform-scoped: the valid names and the default come
+  // from THIS adapter's dev-server logs (mobile: metro; extension: webpack), plus
+  // the app-log source. No adapter's vocabulary is hardcoded here — every
+  // non-headless adapter provides at least one log source (headless core returned
+  // above), so the default is that adapter's first source.
+  const logSources = surface.logSources(target);
+  const sourceLabels = logSources.map((entry) => entry.label);
+  const defaultSource = sourceLabels[0];
+  const source = str(options, 'source') ?? defaultSource;
+  const validSources = [...sourceLabels, 'app'];
+  if (!validSources.includes(source)) {
+    return usageOut(json, 'logs', `--source must be one of: ${validSources.join(', ')}.`, `mm-harness logs --source ${defaultSource}`);
   }
 
   // Env-gap flag (docs/CLI-SPEC.md Part 4): --events sets the compact event count
@@ -39,16 +50,21 @@ export async function handleLogs(argv: string[]): Promise<number> {
     process.env.RECIPE_LOG_EVENTS = events;
   }
 
-  // Nothing running → teaching error pointing at launch. The log file is the
-  // signal that Metro/webpack has been started for this checkout.
-  const logFile = recipeRuntimePath(target, adapter === 'mobile' ? 'metro.log' : 'webpack.log');
-  if (!fs.existsSync(logFile)) {
-    const launchHint = adapter === 'mobile' ? 'mm-harness launch ios' : 'mm-harness launch';
+  // Nothing running → teaching error pointing at launch. A dev-server log file is
+  // the signal that the dev server has been started for this checkout; the surface
+  // owns which files a platform writes (mobile: metro.log; extension: webpack +
+  // watcher + rebuild logs). A `--source` naming a specific dev-server log is
+  // preferred; otherwise the most-relevant existing candidate is tailed.
+  const requested = logSources.find((entry) => entry.label === source);
+  const ordered = requested ? [requested, ...logSources.filter((entry) => entry !== requested)] : logSources;
+  const logFile = ordered.find((entry) => fs.existsSync(entry.path))?.path;
+  if (!logFile) {
+    const names = logSources.map((entry) => path.basename(entry.path)).join(' / ');
     return usageOut(
       json,
       'logs',
-      `nothing running for this checkout (no ${path.basename(logFile)}).`,
-      launchHint,
+      `nothing running for this checkout (no ${names}).`,
+      surface.hints.launch,
     );
   }
 

package/src/harness.ts

@@ -16,15 +16,15 @@ import { prepareMobile } from './adapters/mobile/prepare.ts';
 // core delegate, extension runtime-context env, and verbatim arg passthrough —
 // is reproduced exactly so the skill can become a thin caller.
 
-type HarnessAction = 'install' | 'verify' | 'cleanup' | 'live';
+type HarnessAction = 'install' | 'provision' | 'verify' | 'cleanup' | 'live';
 
-const HARNESS_ACTIONS: readonly HarnessAction[] = ['install', 'verify', 'cleanup', 'live'];
+const HARNESS_ACTIONS: readonly HarnessAction[] = ['install', 'provision', 'verify', 'cleanup', 'live'];
 const ADAPTERS: readonly MetaMaskRecipeAdapter[] = ['mobile', 'extension', 'core'];
 
 // Mirror of scripts/lib/cli-common.sh valid_adapter_action, restricted to the
 // subcommands this command exposes (core has no app/live lifecycle).
 function isValidAdapterAction(adapter: MetaMaskRecipeAdapter, action: HarnessAction): boolean {
-  if (adapter === 'core') return action === 'install' || action === 'verify' || action === 'cleanup';
+  if (adapter === 'core') return action === 'install' || action === 'provision' || action === 'verify' || action === 'cleanup';
   return true;
 }
 
@@ -37,6 +37,8 @@ is auto-detected from the repo. Pass --platform only to override.
 Commands (one copy-pasteable example each):
   install   Install the recipe harness runtime overlay into the checkout.
               mm-harness install
+  provision Install the cached Runway mobile dev client (same path as install --runway).
+              mm-harness provision runway ios --adapter mobile
   verify    Check the harness/runtime is present and healthy (no app launch).
               mm-harness verify
   cleanup   Remove the installed harness overlay and restore the checkout.
@@ -83,6 +85,10 @@ function argValue(args: string[], needle: string): string | undefined {
   return undefined;
 }
 
+function shellQuote(value: string): string {
+  return /^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+
 function isAdapter(value: string | undefined): value is MetaMaskRecipeAdapter {
   return value === 'mobile' || value === 'extension' || value === 'core';
 }
@@ -530,6 +536,15 @@ export async function handleHarness(argv: string[]): Promise<number> {
   // Forward args carry --target so the orchestration script resolves the same
   // checkout; inject the resolved path only when the caller omitted it.
   let forwardArgs = hasArg(forward, '--target') ? [...forward] : ['--target', target, ...forward];
+
+  if (harnessAction === 'provision') {
+    return handleRunwayInstall(adapter, target, provisionRunwayForward(forward), json, 'provision');
+  }
+
+  if (harnessAction === 'install' && hasArg(forward, '--runway')) {
+    return handleRunwayInstall(adapter, target, forward, json, 'install');
+  }
+
   if (adapter === 'extension' && (harnessAction === 'live' || harnessAction === 'verify')) {
     forwardArgs = applyExtensionRuntimeEnv(target, harnessAction, forwardArgs);
   }
@@ -631,6 +646,128 @@ export async function handleHarness(argv: string[]): Promise<number> {
   return exitCode;
 }
 
+async function handleRunwayInstall(
+  adapter: MetaMaskRecipeAdapter,
+  target: string,
+  forward: string[],
+  json: boolean,
+  action: 'install' | 'provision',
+): Promise<number> {
+  const { getAdapterSurface } = await import('./adapters/surface.ts');
+  const rerunCommand = action === 'provision'
+    ? runwayProvisionRerunCommand(adapter, target, forward, json)
+    : runwayInstallRerunCommand(adapter, target, forward, json);
+  const surface = getAdapterSurface(adapter);
+  const runtimeDir = argValue(forward, '--runtime-dir');
+  const watcherPort = argValue(forward, '--watcher-port');
+  const result = await surface.runwayProvision.run(target, {
+    json,
+    platform: argValue(forward, '--platform') ?? 'ios',
+    branch: argValue(forward, '--branch'),
+    defaultBranch: argValue(forward, '--default-branch'),
+    run: argValue(forward, '--run'),
+    cacheRoot: argValue(forward, '--cache-root'),
+    simulator: argValue(forward, '--simulator') ?? argValue(forward, '--device'),
+    runtime: argValue(forward, '--runtime'),
+    deviceType: argValue(forward, '--device-type'),
+    slot: argValue(forward, '--slot'),
+    watcherPort,
+    runtimeDir,
+    force: hasArg(forward, '--force'),
+    resolveOnly: hasArg(forward, '--resolve-only'),
+    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 Runway app for ${adapter} ${result.platform ?? ''} run=${artifact?.runId ?? 'unknown'} revision=${artifact?.revision ?? 'unknown'} artifact=${artifact?.artifactName ?? 'unknown'}`);
+    } else {
+      const action = result.skipped ? 'already provisioned' : 'installed Runway app';
+      console.error(`✓ ${action} for ${adapter} ${result.platform ?? ''} simulator=${simulator?.name ?? 'unknown'} cache=${cache?.status ?? 'skip'}`);
+    }
+  } else {
+    const label = action === 'provision' ? 'provision' : 'install --runway';
+    console.error(`✗ mm-harness ${label}: ${result.error?.message ?? 'runway install failed'}\n  Next: ${result.error?.userAction ?? rerunCommand}`);
+  }
+  return result.exitCode;
+}
+
+function provisionRunwayForward(forward: string[]): string[] {
+  const normalized: string[] = [];
+  let index = 0;
+  if (forward[index] === 'runway') index += 1;
+  if (forward[index] && !forward[index].startsWith('-')) {
+    if (!hasArg(forward, '--platform')) normalized.push('--platform', forward[index]);
+    index += 1;
+  }
+  return [...normalized, ...forward.slice(index)];
+}
+
+function runwayInstallRerunCommand(
+  adapter: MetaMaskRecipeAdapter,
+  target: string,
+  forward: string[],
+  json: boolean,
+): string {
+  const parts = ['mm-harness', 'install', '--runway', '--adapter', adapter, '--target', shellQuote(target)];
+  const valueFlags = [
+    '--platform',
+    '--branch',
+    '--default-branch',
+    '--run',
+    '--cache-root',
+    '--simulator',
+    '--device',
+    '--slot',
+    '--watcher-port',
+    '--runtime-dir',
+    '--runtime',
+    '--device-type',
+  ];
+  for (const flag of valueFlags) {
+    const value = argValue(forward, flag);
+    if (value) parts.push(flag, shellQuote(value));
+  }
+  if (hasArg(forward, '--force')) parts.push('--force');
+  if (hasArg(forward, '--resolve-only')) parts.push('--resolve-only');
+  if (json) parts.push('--json');
+  return parts.join(' ');
+}
+
+function runwayProvisionRerunCommand(
+  adapter: MetaMaskRecipeAdapter,
+  target: string,
+  forward: string[],
+  json: boolean,
+): string {
+  const parts = ['mm-harness', 'provision', 'runway', shellQuote(argValue(forward, '--platform') ?? 'ios'), '--adapter', adapter, '--target', shellQuote(target)];
+  const valueFlags = [
+    '--branch',
+    '--default-branch',
+    '--run',
+    '--cache-root',
+    '--simulator',
+    '--device',
+    '--slot',
+    '--watcher-port',
+    '--runtime-dir',
+    '--runtime',
+    '--device-type',
+  ];
+  for (const flag of valueFlags) {
+    const value = argValue(forward, flag);
+    if (value) parts.push(flag, shellQuote(value));
+  }
+  if (hasArg(forward, '--force')) parts.push('--force');
+  if (hasArg(forward, '--resolve-only')) parts.push('--resolve-only');
+  if (json) parts.push('--json');
+  return parts.join(' ');
+}
+
 // userAction is required whenever an error object is present so every --json
 // failure carries a machine-readable escape path — parallel to the `usageOut`
 // enforcement on the CLI layer. Omitting userAction is a compile-time error.

package/src/mm-harness-cli.ts

@@ -61,16 +61,18 @@ Example:
   },
   {
     name: 'stop',
-    summary: 'Stop the dev server this checkout owns (mobile: port-scoped Metro) and close its log window.',
+    summary: 'Stop the dev server this checkout owns (mobile Metro / extension webpack watcher) and close its log window.',
     example: 'mm-harness stop',
     helpText: `mm-harness stop [flags]
 
-  Stop the Metro dev server this checkout owns and close its tmux log-tail window.
-  Port-scoped: only the listener on the checkout's resolved port is signalled, so
-  concurrent slots are untouched. Nothing running = success (idempotent).
-  Extension/core: teaching error (their dev servers are slot-managed).
+  Stop the dev server this checkout owns and close its tmux log-tail window,
+  scoped to this checkout so concurrent slots are untouched. Idempotent —
+  nothing running is success, not an error. Behavior is per platform:
+    mobile     stop the port-scoped Metro dev server
+    extension  stop the checkout's webpack watcher (pid file + orphan scan)
+    core       headless — no dev server to stop (teaching error)
 
-  --port <port>                      Metro port (default: the checkout's slot context)
+  --port <port>                      Dev-server port (default: the checkout's slot context)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output
 
@@ -81,11 +83,13 @@ Example:
   {
     name: 'call',
     summary: 'Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).',
-    example: 'mm-harness call unlock',
+    example: 'mm-harness call ensure_unlocked',
     helpText: `mm-harness call <action> [--arg k=v ...] [flags]
 
   Run one action in isolation as a one-node recipe through the real engine path.
-  Fuzzy short-name: 'unlock' resolves to 'metamask.wallet.unlock' if unique; ambiguous = exit 2.
+  Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
+  if unique; ambiguous = exit 2. Actions differ per adapter — list this checkout's
+  with: mm-harness actions.
 
   --arg k=v                          Action field value (repeatable)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
@@ -95,9 +99,9 @@ Example:
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
 
-Example:
-  mm-harness call unlock --adapter extension
-  mm-harness call command --arg cmd="echo hi" --adapter core --json`,
+Example (real actions; run mm-harness actions for this checkout's full set):
+  mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
+  mm-harness call command --arg cmd="echo hi" --adapter core   # the universal action (all adapters)`,
   },
   {
     name: 'flows',
@@ -155,21 +159,68 @@ Example:
   mm-harness doctor --fix --json
   mm-harness doctor --adapter mobile --target /path/to/checkout`,
   },
+  {
+    name: 'provision',
+    summary: 'Install the cached Runway iOS dev client on a prepared mobile slot (no deps, no Metro).',
+    example: 'mm-harness provision runway ios --adapter mobile',
+    helpText: `mm-harness provision [runway ios] [flags]
+
+  Install the cached Runway iOS dev client on the slot simulator. This is a thin
+  provisioning path only: artifact cache + simulator create + simctl install.
+  JavaScript dependencies and Metro remain dispatch-time launch concerns.
+
+  --adapter <mobile|extension|core>  Target adapter (mobile supported; extension/core teach)
+  --target <path>                    Slot checkout path (default: cwd)
+  --platform <ios>                   Platform (default ios)
+  --simulator <name|udid>            Override agentic-runtime.json simulator (alias: --device)
+  --device <name|udid>               Alias for --simulator
+  --slot <id>                        Farm slot id recorded in the provision baseline
+  --watcher-port <port>              Farm Metro/watcher port carried through context and Next:
+  --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
+  --runtime <id>                     iOS runtime id used if simulator must be created
+  --device-type <id>                 Device type id used if simulator must be created
+  --branch <ref>                     Probe this ref before default branch
+  --default-branch <ref>             Fallback ref (default main)
+  --run <id>                         Exact GitHub Actions run id
+  --cache-root <dir>                 Override shared runway cache root
+  --force                            Reinstall even when the app is already present
+  --resolve-only                     Resolve artifact metadata only; no simulator/cache/install
+  --json                             Machine-readable envelope; progress stays stderr
+
+Example:
+  mm-harness provision runway ios --adapter mobile --target /path/to/slot
+  mm-harness provision runway ios --adapter mobile --slot scratch-1 --runtime-dir temp/recipe/runtime-8081
+  mm-harness provision runway ios --run 28676856835 --resolve-only --json`,
+  },
   {
     name: 'install',
-    summary: 'Install the per-checkout runtime overlay (CI/agents; the everyday commands auto-ensure it).',
+    summary: 'Install the per-checkout runtime overlay, or --runway to install a cached mobile dev client.',
     example: 'mm-harness install',
     helpText: `mm-harness install [flags]
 
   Install the per-checkout runtime overlay (for CI / agents).
-  The everyday commands auto-ensure it on first use.
+  Add --runway on a mobile slot to install the cached Runway iOS dev client only:
+  artifact cache + simulator create + simctl install. JavaScript dependencies
+  and Metro remain dispatch-time launch concerns.
 
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
+  --runway                           Thin mobile Runway artifact install instead of overlay install
+  --platform <ios>                   Runway platform (default ios)
+  --simulator <name|udid>            Override agentic-runtime.json simulator
+  --runtime <id>                     iOS runtime id used if simulator must be created
+  --device-type <id>                 Device type id used if simulator must be created
+  --branch <ref>                     Probe this ref before default branch
+  --default-branch <ref>             Fallback ref (default main)
+  --run <id>                         Exact GitHub Actions run id
+  --cache-root <dir>                 Override shared runway cache root
+  --force                            Reinstall even when the app is already present
+  --resolve-only                     Runway metadata only; no simulator/cache/install
 
 Example:
   mm-harness install
-  mm-harness install --adapter extension --target /path/to/checkout`,
+  mm-harness install --adapter extension --target /path/to/checkout
+  mm-harness install --runway --adapter mobile --target /path/to/slot`,
   },
   {
     name: 'verify',
@@ -241,8 +292,10 @@ Example:
 
   --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
   --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
-  --source <metro|app>               Log source (default metro)
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --source <label>                   Log source per adapter — mobile: metro|app (default metro);
+                                     extension: webpack|watcher|rebuild|app (default webpack).
+                                     Core is headless (teaching error).
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output
 
@@ -380,8 +433,8 @@ const HELP_GROUPS: HelpGroup[] = [
   },
   {
     title: 'RUNTIME OVERLAY',
-    blurb: 'install/verify/clean the per-checkout overlay (the everyday commands auto-ensure it)',
-    commands: ['install', 'verify', 'cleanup'],
+    blurb: 'install/verify/clean the overlay, plus thin mobile slot provisioning',
+    commands: ['provision', 'install', 'verify', 'cleanup'],
   },
   {
     title: 'MAINTAIN',