feat(run): support visible mobile launches

What changed

This adds a --visible option to once run and threads that request through graph analysis as ctx["run"]["visible"] so target kinds can decide how to expose a visible runtime interface.

Apple application targets now open Simulator for visible simulator runs before installing and launching the app. Android binary targets can declare an emulator_device and Once will start that Android Virtual Device before waiting for the device, installing the app, and launching the activity.

The agent run tool also accepts the same visible request, and the command reference plus mobile graph guides document the new behavior.

Why

Coding harnesses need a way to run mobile apps in a visible interface, not only through a headless install and launch path. Keeping this as an explicit run option preserves the current default while giving harnesses and developers a clear opt-in path.

Root cause

The existing mobile run capabilities launched apps through command-line device tooling only. That was enough to install and start the app process, but it did not reliably open a visible simulator or emulator window for the user.

The Android smoke test also exposed two run-path issues that had to be fixed for visible launches to work end to end: generated helper class directories were declared directly as action inputs, and the install step could run before Android’s package service was ready.

Approach

The command-line and agent surfaces pass a visible flag into the generic analysis context instead of hardcoding mobile logic in Rust. Apple and Android target kinds consume that context in Starlark, which keeps toolchain-specific behavior inside the target kinds.

For Android, the visible emulator launcher avoids a supervised launchd job so closing the emulator does not cause macOS to reopen it. The run action now writes marker outputs for device readiness, install completion, and launch completion, which gives the executor explicit ordering between those side-effecting steps.

Impact

Existing once run behavior is unchanged unless --visible is passed. Android targets that want Once to start an emulator need to set emulator_device; otherwise visible runs use an already-connected physical device or emulator.

Validation

• mise exec -- cargo build -p once-cli
• mise exec -- cargo check -p once-cli -p once-frontend
• mise exec -- cargo test -p once-frontend visible
• mise exec -- cargo test -p once-frontend prelude_android
• mise exec -- cargo test -p once-frontend --test examples
• mise exec -- cargo test -p once-cli graph_target_runner_invokes_cli_and_parses_json_record
• mise exec -- cargo fmt --all -- --check
• git diff --check
• Manual Apple smoke test: once run --visible apps/Hello/Hello opened Simulator and launched the sample app.
• Manual Android smoke test: once run --visible apps/hello/Hello started the configured Android Virtual Device, launched the sample app in the emulator, and left no dev.once launchd job behind.

No GitHub comments yet.