[build-tools] Run Appium iOS sessions with a headless Simulator

[gwdp]

Why

I tried several Appium iOS sessions and found that the app the session launched was gone once a WebDriver session started, unless the client set appium:isHeadless: true.

Since #4603, serve-sim starts the Simulator and the app while Appium is being set up. With that concurrent startup, XCUITest restarts the Simulator when the WebDriver session starts, which closes the launched app and drops its launch arguments and deep link. Session creation also took 24–28 s instead of 6 s. With appium:isHeadless: true, the session started in 6 s and the app stayed in the foreground.

How

Add appium:isHeadless: true to Appium's --default-capabilities for iOS. Default capabilities apply to every client session, including clients that build their own capabilities instead of using APPIUM_CAPS. A client can still override it. EAS VMs never show the Simulator window, so the capability matches how sessions run. Android is unchanged.

Test Plan

• startAppiumRemoteSession tests: 29 passed. The two iOS default-capability tests fail without the change; the Android test checks that Android does not get the capability.
• build-tools typecheck, oxfmt and oxlint on the changed files pass. CI passes on f94c4f1, and Codecov reports all changed lines covered.
• Hosted sessions (all on the production worker, iOS 26.5, coin-flip build): four sessions on the new path without isHeadless lost the app; one with appium:isHeadless: true passed (app in the foreground, tap worked).
• Planned after merge and worker deploy: full Appium QA on the new path without client-side isHeadless.

Authorship and LLM use

Gabe found the problem and set the direction. Claude Code ran the hosted sessions, narrowed the trigger to WebDriver session start, and wrote this change and its tests. Devin review found no issues. Gabe reviewed the final diff and can answer questions.

Generated with T3 Code, using Claude Code.

[github-actions]

✅ Thank you for adding a changeset!

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.29%. Comparing base (5ec3d84) to head (f94c4f1).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4699      +/-   ##
==========================================
+ Coverage   75.29%   75.29%   +0.01%     
==========================================
  Files        1053     1053              
  Lines       52148    52149       +1     
  Branches    11387    11388       +1     
==========================================
+ Hits        39260    39261       +1     
  Misses      11900    11900              
  Partials      988      988              

☔ 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.