fix(mosaic): stop yolo runtime from leaking runtime name as first user message (#455)

Fixes mosaicstack/stack#454

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

packages/mosaic/src/commands/launch.spec.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
+import { Command } from 'commander';
+import { registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
+
+/**
+ * Tests for the commander wiring between `mosaic <runtime>` / `mosaic yolo <runtime>`
+ * subcommands and the internal `launchRuntime` dispatcher.
+ *
+ * Regression target: see mosaicstack/stack#454 — before the fix, `mosaic yolo claude`
+ * passed the literal string "claude" as an excess positional argument to the
+ * underlying CLI, which Claude Code then interpreted as the first user message.
+ *
+ * The bug existed because Commander.js includes declared positional arguments
+ * (here `<runtime>`) in `cmd.args` alongside any true excess args. The action
+ * handler must slice them off before forwarding.
+ */
+
+function buildProgram(handler: RuntimeLaunchHandler): Command {
+  const program = new Command();
+  program.exitOverride(); // prevent process.exit on parse errors
+  registerRuntimeLaunchers(program, handler);
+  return program;
+}
+
+// `process.exit` returns `never`, so vi.spyOn demands a replacement with the
+// same signature. We throw from the mock to short-circuit into test-land.
+const exitThrows = (): never => {
+  throw new Error('process.exit called');
+};
+
+describe('registerRuntimeLaunchers — non-yolo subcommands', () => {
+  let mockExit: MockInstance<typeof process.exit>;
+
+  beforeEach(() => {
+    // process.exit is called when the yolo action rejects an invalid runtime.
+    // Stub it so the assertion catches the rejection instead of terminating
+    // the test runner.
+    mockExit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
+  });
+
+  afterEach(() => {
+    mockExit.mockRestore();
+  });
+
+  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
+    'forwards %s with empty extraArgs and yolo=false',
+    (runtime) => {
+      const handler = vi.fn();
+      const program = buildProgram(handler);
+      program.parse(['node', 'mosaic', runtime]);
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler).toHaveBeenCalledWith(runtime, [], false);
+    },
+  );
+
+  it('forwards excess args after a non-yolo runtime subcommand', () => {
+    const handler = vi.fn();
+    const program = buildProgram(handler);
+    program.parse(['node', 'mosaic', 'claude', '--print', 'hello']);
+
+    expect(handler).toHaveBeenCalledWith('claude', ['--print', 'hello'], false);
+  });
+});
+
+describe('registerRuntimeLaunchers — yolo <runtime>', () => {
+  let mockExit: MockInstance<typeof process.exit>;
+  let mockError: MockInstance<typeof console.error>;
+
+  beforeEach(() => {
+    mockExit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
+    mockError = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    mockExit.mockRestore();
+    mockError.mockRestore();
+  });
+
+  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
+    'does NOT pass the runtime name as an extra arg (regression #454) for yolo %s',
+    (runtime) => {
+      const handler = vi.fn();
+      const program = buildProgram(handler);
+      program.parse(['node', 'mosaic', 'yolo', runtime]);
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      // The critical assertion: extraArgs must be empty, not [runtime].
+      // Before the fix, cmd.args was [runtime] and the runtime name leaked
+      // through to the underlying CLI as an initial positional argument.
+      expect(handler).toHaveBeenCalledWith(runtime, [], true);
+    },
+  );
+
+  it('forwards true excess args after a yolo runtime', () => {
+    const handler = vi.fn();
+    const program = buildProgram(handler);
+    program.parse(['node', 'mosaic', 'yolo', 'claude', '--print', 'hi']);
+
+    expect(handler).toHaveBeenCalledWith('claude', ['--print', 'hi'], true);
+  });
+
+  it('rejects an unknown runtime under yolo without invoking the handler', () => {
+    const handler = vi.fn();
+    const program = buildProgram(handler);
+
+    expect(() => program.parse(['node', 'mosaic', 'yolo', 'bogus'])).toThrow('process.exit called');
+    expect(handler).not.toHaveBeenCalled();
+    expect(mockExit).toHaveBeenCalledWith(1);
+  });
+});

packages/mosaic/src/commands/launch.ts

@@ -757,8 +757,23 @@ function runUpgrade(args: string[]): never {
 
 // ─── Commander registration ─────────────────────────────────────────────────
 
-export function registerLaunchCommands(program: Command): void {
-  // Runtime launchers
+/**
+ * Handler invoked when a runtime subcommand (`<runtime>` or `yolo <runtime>`)
+ * is parsed. Exposed so tests can exercise the commander wiring without
+ * spawning subprocesses.
+ */
+export type RuntimeLaunchHandler = (
+  runtime: RuntimeName,
+  extraArgs: string[],
+  yolo: boolean,
+) => void;
+
+/**
+ * Wire `<runtime>` and `yolo <runtime>` subcommands onto `program` using a
+ * pluggable launch handler. Separated from `registerLaunchCommands` so tests
+ * can inject a spy and verify argument forwarding.
+ */
+export function registerRuntimeLaunchers(program: Command, handler: RuntimeLaunchHandler): void {
   for (const runtime of ['claude', 'codex', 'opencode', 'pi'] as const) {
     program
       .command(runtime)
@@ -766,11 +781,10 @@ export function registerLaunchCommands(program: Command): void {
       .allowUnknownOption(true)
       .allowExcessArguments(true)
       .action((_opts: unknown, cmd: Command) => {
-        launchRuntime(runtime, cmd.args, false);
+        handler(runtime, cmd.args, false);
       });
   }
 
-  // Yolo mode
   program
     .command('yolo <runtime>')
     .description('Launch a runtime in dangerous-permissions mode (claude|codex|opencode|pi)')
@@ -784,8 +798,21 @@ export function registerLaunchCommands(program: Command): void {
         );
         process.exit(1);
       }
-      launchRuntime(runtime as RuntimeName, cmd.args, true);
+      // Commander includes declared positional arguments (`<runtime>`) in
+      // `cmd.args` alongside any trailing excess args. Slice off the first
+      // element so we forward only true excess args — otherwise the runtime
+      // name leaks into the underlying CLI as an initial positional arg,
+      // which Claude Code interprets as the first user message.
+      // Regression test: launch.spec.ts, issue mosaicstack/stack#454.
+      handler(runtime as RuntimeName, cmd.args.slice(1), true);
     });
+}
+
+export function registerLaunchCommands(program: Command): void {
+  // Runtime launchers + yolo mode wired to the real process-replacing launcher.
+  registerRuntimeLaunchers(program, (runtime, extraArgs, yolo) => {
+    launchRuntime(runtime, extraArgs, yolo);
+  });
 
   // Coord (mission orchestrator)
   program