#3995 fix(cli): guide Xcode 27 simulator recovery

Summary (AI generated)

When Xcode 27 provides Device Hub but Capacitor's installed native-run still expects Simulator.app, the CLI, doctor, and OTA onboarding now report the incompatibility and provide a manual Xcode launch path. MCP onboarding waits until the user confirms the baseline app is running before proceeding to the OTA test.

The check follows the selected Xcode and resolves native-run from the app's installed @capacitor/cli, including hoisted and symlinked installs. It recognizes the upstream package-manager patch and leaves physical-device selection available. CLI help, published usage skills, README, and webdocs include recovery and upgrade guidance.

Motivation (AI generated)

Xcode 27 replaced Simulator.app with Device Hub. The upstream fix is merged, but as of October 29, 2026, npm still publishes native-run 2.0.3 and Capacitor CLI 8.6.0 still depends on it. There is no released minimum Capacitor version to recommend for this fix yet. Recommending a Capacitor upgrade alone would leave users stuck.

Sources: https://github.com/ionic-team/capacitor/issues/8620 and https://github.com/ionic-team/native-run/pull/408.

Business Impact (AI generated)

Users setting up Capgo with a recent Xcode can continue through Xcode or the documented upstream patch instead of repeatedly failing simulator launches. Confirming the baseline app opens prevents onboarding from advancing to an OTA test with no running native app.

Test Plan (AI generated)

• bun run --cwd cli lint
• bun run --cwd cli build
• bun run --cwd cli test:mcp
• bun run --cwd cli test:bundle
• bun run --cwd cli test:onboarding-run-targets, including 16 compatibility tests and compiled CLI/doctor checks
• bun run --cwd cli test:mcp-live-update-onboarding, including the manual-launch confirmation gate
• bun run --cwd cli test:run-device-command
• bun run --cwd cli test:doctor-analytics
• bun run --cwd cli test:cli-help
• git diff --check

Compatibility coverage uses filesystem fixtures for Xcode applications and installed dependencies. A live Xcode 27 simulator session was not run.

Generated with AI

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}