[gwdp]

Why

Cold and warm sessions need the same preview, app startup and cleanup steps.

How

Move cold iOS Simulator session startup into coldIosSession.ts behind the session host's shared preview, app-start and cleanup contract. #4724 supplies the warm implementation. Android keeps its existing startup.

The cold path waits for warm cleanup (#4721) before starting serve-sim. Requires the serve-sim release with port-based adoption.

How the session host and server coordinate

• Session host: owns the shared preview, app installation and launch, recording completion and session teardown.
• Cold server (coldIosSession.ts): supplies the port and startup handle, waits for warm cleanup, then starts a fresh serve-sim. It also supplies Simulator-specific setup such as the apsd attempt.
• Warm server ([build-tools] Claim the warm Simulator and adopt its serve-sim #4724): implements the same contract with the claimed server. It handles adoption and tool preparation before returning control to the host.

The host can use either server without duplicating app and preview handling. Preview opening still overlaps startup. Opening and retirement waits are bounded, late listeners close themselves, and unconfirmed warm tunnel retirement prevents cold fallback. The cleanup wait belongs immediately before cold serve-sim startup because that process boots the Simulator; unrelated session preparation can proceed earlier. Startup rollback attempts server stop and screenshot cleanup; combined startup and cleanup failures retain both causes. Both supported host commands use --require-token. Android keeps its existing startup implementation.

Test Plan

• Local focused tests, build-tools typecheck, scoped lint and formatting pass. CI passes on this head; Devin analysis passed.

• No fresh native run for this review round.

• Earlier verified local launch E2E: Universe-generated steps through build-tools download/install/start to a pinned serve-sim build on a real iOS Simulator; checked one app start, launch arguments and deep link. It used loopback tunnel/reporting adapters and was not rerun for this head. This was local validation, not hosted EAS/API-to-worker acceptance.

Authorship and LLM use

Gabe reviewed the preceding changes. Codex and Claude Code wrote the code and tests. This review round and the updated base still need human review.

Rollback

Revert #4724 and its dependent layers first.

— Codex

[gwdp]

Codex rebased this PR onto main 6f0f90bd9 and restacked its dependencies. Retained main's preview-device policy and adapted four existing test fixtures to the extracted host options.

Current head: c8ca33ab0e8daf3647ff5dbfaf1290773fad491f. Stack-level local checks: 496 focused build-tools tests and 59 worker tests passed on the rebased main stack; 154 artifact-drain/host tests passed on #4750. Build-tools, worker and launcher typechecks, scoped lint and formatting pass. CI passes on this exact head, including Node 22 and Node 24; prior human reviews apply to the earlier heads. Draft states and human review requests are preserved.

Earlier contribution and validation

Codex rebased this layer on the current-boot cleanup guard and updated its real cleanup fixture. The cold host still waits immediately before spawning serve-sim. Preview overlap, bounded retirement and cleanup error handling are retained. Fourteen cleanup/cold-start tests pass. The earlier memfs report remains resolved.

Current head: ce93127. Local typecheck, scoped lint and formatting pass. Devin analysis passed on this exact head; CI passes on this head. Gabe reviewed the preceding changes; this round and the updated base still need human review.

— Codex

[github-actions]

✅ Thank you for adding a changeset!