@deeeed/metamask-harness 0.4.0 → 0.5.0

package/src/cli-commands.ts

@@ -33,7 +33,7 @@ export const SPEC: CommandSpecMap = {
     { name: 'logs', aliases: ['tail'], desc: 'Compact build events or full log', flags: ['--full', '-f'] },
     { name: 'debug', aliases: ['devtools', 'inspect'], desc: 'Open DevTools UI', flags: ['--json', '--no-open'] },
     { name: 'actions', desc: 'List runnable recipe actions', flags: ['--json'] },
-    { name: 'doctor', desc: 'Check harness/orchestration health', flags: ['--json'] },
+    { name: 'doctor', desc: 'Check harness/orchestration health', flags: ['--json', '--target', '--adapter', '--runtime-dir'] },
     { name: 'run', desc: 'Execute a proof recipe', args: ['recipe.json'] },
     { name: 'interactive', aliases: ['menu'], desc: 'Interactive command menu' },
     { name: 'prepare', desc: 'Install harness (+ optional validate)', flags: ['--target', '--runtime-dir', '--json'] },

package/src/cli.ts

@@ -68,6 +68,7 @@ type CliOptions = Record<string, CliOptionValue>;
 interface ParsedArgs {
   positional: string[];
   options: CliOptions;
+  rawArgv: string[];
 }
 
 interface RuntimeOptions {
@@ -105,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,
@@ -114,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
@@ -176,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('--')) {
@@ -216,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' {
@@ -249,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);
@@ -450,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
@@ -494,12 +511,17 @@ async function handleDoctor({ options }: ParsedArgs): Promise<number> {
     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(stateStyle(runtime.devServer.status, 'up'), runtime.devServer.status)}`
+        ? ` ${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')}${devServer}`,
+        `${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)}`);
     }
@@ -609,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.');
@@ -769,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') {

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

@@ -159,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',
@@ -386,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',