feat: add public --launch-args CLI flag for iOS open

main already has internal launchArgs support for iOS simulators (from
the Maestro work). This change makes it a first-class CLI flag and
fills in the gaps:

- Add `--launch-args <arg>` to the schema, allowed flags on `open`,
  and the CLI handler. Mirrors `--header`'s shape (repeatable string
  flag, parsed to `string[]`).
- Plumb `launchArgs` through `AppOpenOptions`, the client
  normalizer, and the standalone `daemon-client.openApp` request
  builder so programmatic callers see the same surface.
- Forward `launchArgs` to iOS device launches via
  `launchIosDeviceProcess`, inserting an explicit `--` end-of-options
  marker before the user's args so devicectl (Swift ArgumentParser)
  can't reparse leading-dash launch args as its own options.
- Reject `launchArgs` explicitly on macOS rather than silently
  dropping them through the existing macOS launch path.
- Reject `launchArgs` combined with an iOS simulator URL open (which
  goes through `simctl openurl`, ignoring launch arguments) with an
  INVALID_ARGS pointing the caller at the two-step flow.

Android remains explicitly rejected in dispatch.ts as already on main;
adding Android support is a separate decision and out of scope here.

Tests:

- `src/utils/__tests__/args.test.ts`: parser/help coverage for
  `--launch-args` including `-FeatureFlag`-style values and
  `--es KEY VALUE`-style values, plus the rejection on unrelated
  commands.
- `src/platforms/ios/__tests__/index.test.ts`: device launch with
  args, device deep-link launch with args (`--` separator after
  `--payload-url`), simulator URL reject, macOS reject.

Author: mikegarfinkle

src/client-normalizers.ts

@@ -276,6 +276,7 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     surface: options.surface,
     activity: options.activity,
     launchConsole: options.launchConsole,
+    launchArgs: options.launchArgs,
     relaunch: options.relaunch,
     shutdown: options.shutdown,
     saveScript: options.saveScript,

src/client-types.ts

@@ -175,6 +175,7 @@ export type AppOpenOptions = AgentDeviceRequestOverrides &
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
     activity?: string;
     launchConsole?: string;
+    launchArgs?: string[];
     relaunch?: boolean;
     saveScript?: boolean | string;
     noRecord?: boolean;
@@ -844,6 +845,7 @@ export type InternalRequestOptions = AgentDeviceClientConfig &
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
     activity?: string;
     launchConsole?: string;
+    launchArgs?: string[];
     relaunch?: boolean;
     shutdown?: boolean;
     saveScript?: boolean | string;

src/commands/cli-grammar/apps.ts

@@ -36,6 +36,7 @@ export const appCliReaders = {
     surface: flags.surface,
     activity: flags.activity,
     launchConsole: flags.launchConsole,
+    launchArgs: flags.launchArgs,
     relaunch: flags.relaunch,
     saveScript: flags.saveScript,
     noRecord: flags.noRecord,

src/commands/client-command-contracts.ts

@@ -81,6 +81,9 @@ export const clientCommandDefinitions = [
       surface: enumField(SURFACE_VALUES),
       activity: stringField('Android activity name.'),
       launchConsole: stringField('Launch console mode.'),
+      launchArgs: stringArrayField(
+        'iOS-only launch arguments forwarded to the app; Android and macOS reject this field.',
+      ),
       relaunch: booleanField('Force relaunch.'),
       saveScript: jsonSchemaField<boolean | string>({ oneOf: [booleanSchema(), stringSchema()] }),
       noRecord: booleanField('Do not record this action.'),

src/daemon-client.ts

@@ -45,6 +45,7 @@ export type OpenAppOptions = {
   serial?: NonNullable<DaemonRequest['flags']>['serial'];
   activity?: NonNullable<DaemonRequest['flags']>['activity'];
   launchConsole?: NonNullable<DaemonRequest['flags']>['launchConsole'];
+  launchArgs?: NonNullable<DaemonRequest['flags']>['launchArgs'];
   out?: NonNullable<DaemonRequest['flags']>['out'];
   saveScript?: NonNullable<DaemonRequest['flags']>['saveScript'];
   relaunch?: boolean;
@@ -203,6 +204,7 @@ export async function openApp(options: OpenAppOptions = {}): Promise<DaemonRespo
     serial,
     activity,
     launchConsole,
+    launchArgs,
     out,
     saveScript,
     relaunch,
@@ -224,6 +226,7 @@ export async function openApp(options: OpenAppOptions = {}): Promise<DaemonRespo
       ...(serial !== undefined ? { serial } : {}),
       ...(activity !== undefined ? { activity } : {}),
       ...(launchConsole !== undefined ? { launchConsole } : {}),
+      ...(launchArgs !== undefined ? { launchArgs } : {}),
       ...(out !== undefined ? { out } : {}),
       ...(saveScript !== undefined ? { saveScript } : {}),
       ...(relaunch ? { relaunch: true } : {}),

src/platforms/ios/__tests__/index.test.ts

@@ -76,6 +76,7 @@ import { AppError } from '../../../utils/errors.ts';
 import { runCmd } from '../../../utils/exec.ts';
 import { retryWithPolicy } from '../../../utils/retry.ts';
 import { parseIosDeviceAppsPayload, parseIosDeviceProcessesPayload } from '../devicectl.ts';
+import { withAppleToolProvider } from '../tool-provider.ts';
 
 const IOS_TEST_DEVICE: DeviceInfo = {
   platform: 'ios',
@@ -203,6 +204,20 @@ async function withMockedXcrun(
   }
 }
 
+async function withCapturedXcrunArgs(run: (calls: string[][]) => Promise<void>): Promise<void> {
+  const calls: string[][] = [];
+  await withAppleToolProvider(
+    async (cmd, args) => {
+      assert.equal(cmd, 'xcrun');
+      calls.push(args);
+      return { exitCode: 0, stdout: '', stderr: '' };
+    },
+    async () => {
+      await run(calls);
+    },
+  );
+}
+
 function injectDefaultPrivacyHelp(script: string): string {
   if (script.includes('AGENT_DEVICE_CUSTOM_PRIVACY_HELP')) return script;
   const helpBlock = `if [ "$1" = "simctl" ] && [ "$2" = "privacy" ] && [ "$3" = "help" ]; then
@@ -925,6 +940,127 @@ test('openIosApp captures iOS simulator launch console output when requested', a
   }
 });
 
+test('openIosApp emits a clean simctl launch when launchArgs is an empty array', async () => {
+  await withCapturedXcrunArgs(async (calls) => {
+    mockEnsureBootedSimulator.mockResolvedValue();
+    await openIosApp(IOS_TEST_SIMULATOR, 'MyApp', {
+      appBundleId: 'com.example.app',
+      launchArgs: [],
+    });
+    assert.deepEqual(calls, [['simctl', 'launch', 'sim-1', 'com.example.app']]);
+  });
+});
+
+test('openIosApp forwards dash-prefixed launchArgs after the bundle id on iOS simulator', async () => {
+  await withCapturedXcrunArgs(async (calls) => {
+    mockEnsureBootedSimulator.mockResolvedValue();
+    await openIosApp(IOS_TEST_SIMULATOR, 'MyApp', {
+      appBundleId: 'com.example.app',
+      launchArgs: ['-FeatureFlag', 'YES'],
+    });
+    assert.deepEqual(calls, [
+      ['simctl', 'launch', 'sim-1', 'com.example.app', '-FeatureFlag', 'YES'],
+    ]);
+  });
+});
+
+test('openIosApp inserts the devicectl delimiter before the bundle id for iOS device launchArgs', async () => {
+  await withCapturedXcrunArgs(async (calls) => {
+    await openIosApp(IOS_TEST_DEVICE, 'MyApp', {
+      appBundleId: 'com.example.app',
+      launchArgs: ['-FeatureFlag', 'YES'],
+    });
+    assert.deepEqual(calls, [
+      [
+        'devicectl',
+        'device',
+        'process',
+        'launch',
+        '--device',
+        'ios-device-1',
+        '--',
+        'com.example.app',
+        '-FeatureFlag',
+        'YES',
+      ],
+    ]);
+  });
+});
+
+test('openIosApp inserts the devicectl delimiter after --payload-url for iOS device deep links', async () => {
+  await withCapturedXcrunArgs(async (calls) => {
+    await openIosApp(IOS_TEST_DEVICE, 'myapp://item/42', {
+      appBundleId: 'com.example.app',
+      launchArgs: ['-Tracking', 'NO'],
+    });
+    assert.deepEqual(calls, [
+      [
+        'devicectl',
+        'device',
+        'process',
+        'launch',
+        '--device',
+        'ios-device-1',
+        '--payload-url',
+        'myapp://item/42',
+        '--',
+        'com.example.app',
+        '-Tracking',
+        'NO',
+      ],
+    ]);
+  });
+});
+
+test('openIosApp rejects launchArgs combined with URL deep link on iOS simulator', async () => {
+  mockEnsureBootedSimulator.mockResolvedValue();
+  const launchArgsCases: string[][] = [['-FeatureFlag', 'YES'], []];
+  for (const launchArgs of launchArgsCases) {
+    await assert.rejects(
+      () =>
+        openIosApp(IOS_TEST_SIMULATOR, 'myapp://item/42', {
+          launchArgs,
+        }),
+      (error: unknown) => {
+        assert.ok(error instanceof AppError);
+        assert.equal(error.code, 'INVALID_ARGS');
+        assert.match(String(error.message), /simctl openurl/);
+        return true;
+      },
+    );
+    await assert.rejects(
+      () =>
+        openIosApp(IOS_TEST_SIMULATOR, 'MyApp', {
+          appBundleId: 'com.example.app',
+          url: 'https://example.com/path',
+          launchArgs,
+        }),
+      (error: unknown) => {
+        assert.ok(error instanceof AppError);
+        assert.equal(error.code, 'INVALID_ARGS');
+        return true;
+      },
+    );
+  }
+});
+
+test('openIosApp rejects launchArgs on macOS', async () => {
+  for (const launchArgs of [['-FeatureFlag', 'YES'], []]) {
+    await assert.rejects(
+      () =>
+        openIosApp(MACOS_TEST_DEVICE, 'TextEdit', {
+          launchArgs,
+        }),
+      (error: unknown) => {
+        assert.ok(error instanceof AppError);
+        assert.equal(error.code, 'UNSUPPORTED_OPERATION');
+        assert.match(String(error.message), /macOS/);
+        return true;
+      },
+    );
+  }
+});
+
 test('readIosClipboardText rejects physical devices', async () => {
   await assert.rejects(
     () => readIosClipboardText(IOS_TEST_DEVICE),

src/platforms/ios/apps.ts

@@ -67,6 +67,11 @@ const ALIASES: Record<string, string> = {
 };
 const IOS_SIMULATOR_CONSOLE_CAPTURE_MS = 25_000;
 
+const IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE =
+  '--launch-args is not supported with iOS simulator URL opens (simctl openurl ignores launch args). Launch the app first with --launch-args, then issue the URL open in a separate call.';
+const MACOS_LAUNCH_ARGS_UNSUPPORTED_MESSAGE =
+  '--launch-args is not supported on macOS; launch arguments are currently iOS-only.';
+
 const iosAppResolutionCache = createAppResolutionCache<string>();
 let cachedSimctlPrivacyServices: Set<string> | null = null;
 let cachedSimctlPrivacyServicesCacheKey: string | undefined;
@@ -132,10 +137,14 @@ export async function openIosApp(
   options?: { appBundleId?: string; launchConsole?: string; launchArgs?: string[]; url?: string },
 ): Promise<void> {
   const launchConsole = options?.launchConsole?.trim();
+  const launchArgs = options?.launchArgs;
   if (launchConsole && (device.platform !== 'ios' || device.kind !== 'simulator')) {
     throw new AppError('UNSUPPORTED_OPERATION', LAUNCH_CONSOLE_IOS_SIMULATOR_ONLY_MESSAGE);
   }
   if (device.platform === 'macos') {
+    if (launchArgs !== undefined) {
+      throw new AppError('UNSUPPORTED_OPERATION', MACOS_LAUNCH_ARGS_UNSUPPORTED_MESSAGE);
+    }
     await openMacOsApp(device, app, options);
     return;
   }
@@ -148,6 +157,9 @@ export async function openIosApp(
       throw new AppError('INVALID_ARGS', 'open <app> <url> requires a valid URL target');
     }
     if (device.kind === 'simulator') {
+      if (launchArgs !== undefined) {
+        throw new AppError('INVALID_ARGS', IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE);
+      }
       await ensureBootedSimulator(device);
       await runSimctl(device, ['openurl', device.id, explicitUrl]);
       return;
@@ -160,7 +172,7 @@ export async function openIosApp(
         'Deep link open on iOS devices requires an active app bundle ID. Open the app first, then open the URL.',
       );
     }
-    await launchIosDeviceProcess(device, bundleId, { payloadUrl: explicitUrl });
+    await launchIosDeviceProcess(device, bundleId, { payloadUrl: explicitUrl, launchArgs });
     return;
   }
 
@@ -170,6 +182,9 @@ export async function openIosApp(
       throw new AppError('INVALID_ARGS', LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE);
     }
     if (device.kind === 'simulator') {
+      if (launchArgs !== undefined) {
+        throw new AppError('INVALID_ARGS', IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE);
+      }
       await ensureBootedSimulator(device);
       await runSimctl(device, ['openurl', device.id, deepLinkTarget]);
       return;
@@ -181,20 +196,20 @@ export async function openIosApp(
         'Deep link open on iOS devices requires an active app bundle ID. Open the app first, then open the URL.',
       );
     }
-    await launchIosDeviceProcess(device, bundleId, { payloadUrl: deepLinkTarget });
+    await launchIosDeviceProcess(device, bundleId, { payloadUrl: deepLinkTarget, launchArgs });
     return;
   }
 
   const bundleId = options?.appBundleId ?? (await resolveIosApp(device, app));
   if (device.kind === 'simulator') {
     await launchIosSimulatorApp(device, bundleId, {
       ...(launchConsole ? { launchConsole } : {}),
-      ...(options?.launchArgs ? { launchArgs: options.launchArgs } : {}),
+      ...(launchArgs ? { launchArgs } : {}),
     });
     return;
   }
 
-  await launchIosDeviceProcess(device, bundleId);
+  await launchIosDeviceProcess(device, bundleId, { launchArgs });
 }
 
 export async function openIosDevice(device: DeviceInfo): Promise<void> {
@@ -1005,7 +1020,10 @@ function buildIosSimulatorLaunchArgs(
   const args = ['launch'];
   if (options?.launchConsole) args.push('--console-pty');
   args.push(deviceId, bundleId);
-  if (options?.launchArgs) args.push(...options.launchArgs);
+  if (options?.launchArgs && options.launchArgs.length > 0) {
+    // simctl launch treats args after <device> <bundle id> as app argv.
+    args.push(...options.launchArgs);
+  }
   return args;
 }
 
@@ -1062,11 +1080,23 @@ function joinProcessOutput(stdout: string, stderr: string): string {
 async function launchIosDeviceProcess(
   device: DeviceInfo,
   bundleId: string,
-  options?: { payloadUrl?: string },
+  options?: { payloadUrl?: string; launchArgs?: string[] },
 ): Promise<void> {
-  const args = ['device', 'process', 'launch', '--device', device.id, bundleId];
-  if (options?.payloadUrl) {
-    args.push('--payload-url', options.payloadUrl);
+  const args = ['device', 'process', 'launch', '--device', device.id];
+  if (options?.launchArgs && options.launchArgs.length > 0) {
+    if (options?.payloadUrl) {
+      args.push('--payload-url', options.payloadUrl);
+    }
+    // `devicectl` uses Swift ArgumentParser; without `--` a leading-dash app
+    // arg can be re-interpreted as a devicectl option. The marker must come
+    // before the positional bundle id so it is consumed by devicectl instead
+    // of being forwarded to the app as argv[1].
+    args.push('--', bundleId, ...options.launchArgs);
+  } else {
+    args.push(bundleId);
+    if (options?.payloadUrl) {
+      args.push('--payload-url', options.payloadUrl);
+    }
   }
   await runIosDevicectl(args, { action: 'launch iOS app', deviceId: device.id });
 }