[build-tools] Add serve-sim Simulator startup helpers

[gwdp]

Why

Share the Simulator and app-control code needed for serve-sim to own startup.

How

• Add app-control requests, app staging, Simulator selection and guard boot settings.
• Read app metadata in iosAppArtifact.ts, separately from serve-sim requests. Generic EAS boot/install functions stay unchanged; no session caller uses the new startup helpers here. Existing guard-log polling starts earlier during guard setup.

Test Plan

• Codex added eight cases for startup inputs, guard logs, WebSocket failures and staging cleanup. Local coverage of added executable lines rose from 93.0% to 99.3% (133/143 → 142/143); Codecov's CI measurement is separate.
• 163 focused tests, TypeScript, lint and formatting passed. Opus review strengthened the duplicate-relay test; it fails when duplicate-start protection is removed.
• Previous CI and Devin review passed on ff255a5. Fresh CI and Devin review are pending for this test-only follow-up.
• Earlier local launch E2E passed: Universe-generated steps through build-tools download/install/start to pinned serve-sim on a real iOS Simulator. Verified one app start, arguments and deep link. Cloud calls used loopback adapters; hosted and current-head device runs remain pending.

Startup benchmark

These helpers have no session caller in this PR. The table measures the completed activation stack, rather than a speedup from merging this foundation alone.

Session	Main median	Stack median	Median paired saving
agent-device	34.80s	33.87s	0.37s (1.1%)
argent	41.61s	32.59s	8.84s (21.2%)
appium	48.34s	34.29s	11.64s (25.4%)

Codex measured four alternating pairs per type on an initialized iPhone 17 Pro Simulator (iOS 26.4, Tart 6 CPU / 8 GiB), starting shut down with the app absent and packages cached. Timing runs from worker entry to local session reporting, using real controllers and native boot/install/launch with loopback cloud adapters.

This compares the completed startup stack e0b7462 against main 4aca8b1, with the same pinned local serve-sim #260 build; it does not isolate this PR's contribution. Hosted dispatch and first browser frame were not measured.

Savings are the median of paired differences, not the difference between the two arm medians. Agent-device varied from 1.51s slower to 5.29s faster; it has no consistent speedup in this sample. Argent and Appium were faster in all four pairs.

Authorship and LLM use

Gabe wrote the initial implementation and guided the design. Codex extracted the helpers and separated app metadata, session preparation and serve-sim requests. AI review moved orchestration tests and docs beside their first caller. Gabe reviewed the implementation through #4601, including this prerequisite. Codex added this test-only follow-up and iterated with Opus review. Gabe reviewed the added tests.

[gwdp]

Codex extracted the startup prerequisite under Gabe's direction. Gabe reviewed the implementation through #4601. The test-only follow-up at 5214b04 adds eight cases for startup inputs, guard logging, WebSocket failures and staging cleanup, and improves existing authentication/dedup assertions. Runtime code is unchanged; human inspection of the added tests is pending.

Local added-line coverage rose from 93.0% to 99.3% (142/143). The foundation's 163 focused tests and the tip's 294 startup/action tests pass, along with TypeScript, lint and formatting. Opus review found a weak duplicate-relay assertion; it now fails when protection is removed, and the final review is clean.

— Codex

[codecov]

Codecov Report

❌ Patch coverage is 98.79518% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.55%. Comparing base (255be36) to head (6026bec).

Files with missing lines	Patch %	Lines
...es/build-tools/src/steps/utils/localEgressGuard.ts	97.15%	1 Missing ⚠️
...ges/build-tools/src/steps/utils/serveSimActions.ts	98.22%	1 Missing ⚠️

Additional details and impacted files

@@                      Coverage Diff                       @@
##           gwdp/serve-sim-argent-logs    #4605      +/-   ##
==============================================================
+ Coverage                       74.48%   74.55%   +0.08%     
==============================================================
  Files                            1029     1032       +3     
  Lines                           50391    50538     +147     
  Branches                        10893    10929      +36     
==============================================================
+ Hits                            37527    37673     +146     
- Misses                          11874    11875       +1     
  Partials                          990      990              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[douglowder]

eas-cli now uses changesets for changelogs (#4580). The required "Check for a changeset" check fails on PRs that edit CHANGELOG.md.

To update this PR:

1. Revert the changes to CHANGELOG.md.
2. Run yarn changeset, select the changed packages and the bump type, and write the summary.
3. Commit the new file in .changeset/.

The release adds the PR link and the author to the entry. If this PR needs no changelog entry, revert the CHANGELOG.md changes and add the "no changelog" label.

[gwdp]

Rebased this layer onto gwdp/serve-sim-argent-logs and moved its release note from CHANGELOG.md into its own changeset. Current-main behavior was preserved.

Validation: focused build-tools tests, changeset validation, changed-file lint/format and build-tools typecheck passed. No new native or hosted acceptance was run for this restack.

Published head: 17286327dee9cb15497a167ec4a3c8a81df0453e.

— Codex

[github-actions]

✅ Thank you for adding a changeset!