CLI shape: make physical iOS devices a first-class target (listing, device-kind field, top-level + daemon routing)

[onevcat]

Problem inventory before we design the CLI shape. This issue only catalogues the current state and the inconsistencies; the actual design is deferred to follow-up discussion.

The theme: sim-use ios-device is currently an appendage, not a first-class target. If we commit to physical iOS support, it should behave like every other target (with some capabilities legitimately restricted), rather than living off to the side.

Current state

1. sim-use devices listing coverage

Target	Listed by sim-use devices?	Source
iOS Simulator	✅	simctl list devices
iOS physical device	❌ blind spot	would need FBDeviceControl (what ios-device devices already uses)
Android emulator	✅	adb devices
Android physical device	✅	adb devices

simctl only knows simulators, so sim-use devices never shows a plugged-in iPhone — even though sim-use ios-device devices lists it fine through a different code path. Android, by contrast, shows both emulators and physical devices. So the listing is asymmetric: Android physical is visible, iOS physical is not.

2. No device-kind field

Device (the sim-use devices row / --json schema) carries platform ∈ {ios, android}, plus free-form state, runtime, name, deviceId. There is no field distinguishing simulator / emulator / physical:

• Android emulator vs physical device is only inferable from the serial shape (emulator-5554 prefix), not a structured field.
• iOS simulator vs physical has no field either (and physical isn't listed at all today).

The PLATFORM column answers "ios or android" but not "simulator, emulator, or real device", which is exactly the distinction that determines available capabilities.

3. Physical iOS is not routed like other targets

Surface	iOS Simulator	Android	iOS physical
Top-level verbs (ui, tap, screenshot, …)	✅ routed by UDID shape (PlatformRouter)	✅	❌ rejected — must use the ios-device namespace
Per-UDID daemon (auto-spawn, amortised init)	✅	✅	❌ — every ios-device call opens its own DTX session
Namespace	sim-use ios <verb> (iOS-only extras)	sim-use android <verb>	sim-use ios-device <verb> (the whole surface)

• PlatformRouter has only .iOSSim / .android cases; a physical iOS UDID resolves to neither and top-level verbs reject it (pointing at ios-device).
• The ios-device subcommands are plain AsyncParsableCommands that call DeviceSession.withClient directly — they do not implement SimUseExecutableCommand, so they bypass the daemon entirely.

This contradicts sim-use's stated design: "one command surface; the UDID shape decides the backend." A physical iOS device is the only target you address through a wholly separate command tree.

Problems to solve (design deferred)

1. Listing parity — sim-use devices should surface physical iOS devices (~~probably opt-in given FBDeviceControl discovery cost; see the ~5 s attachment-quiescence wait~~), so discovery is uniform across every target. (Edit 2026-08-27: the opt-in rationale is retracted — measured discovery is ~0.4 s with a device attached, and fix: bail fast from ios-device discovery when no device is attached #117 cut the no-device path to ~1 s, so default-on is plausible; see the measurement comments below.)
2. Device-kind field — add a structured field distinguishing simulator / emulator / physical (name TBD), orthogonal to platform. Lets the table and --json say "ios physical" vs "ios simulator" vs "android emulator" explicitly, and lets callers reason about which capabilities apply.
3. First-class routing — decide whether physical iOS joins PlatformRouter + top-level verb forwarding + the daemon, so sim-use ui / sim-use tap work against a plugged-in iPhone (with the restricted capability set), instead of requiring ios-device. This is the biggest question and where "first-class citizen vs restricted appendage" is actually decided.
4. Capability model — with physical iOS routed through the top level, unsupported verbs (coordinate tap, swipe, gesture, screenshot, --json, …) need a consistent "capability not available on this target" contract rather than today's hard namespace split. (Edit 2026-08-27: screenshot moved to the supported column — shipped over CoreDevice in feat: add ios-device screenshot backed by devicectl #118. The contract also needs to express "supported by the tool, refused by this device" — CoreDevice screen recording is capability-gated per device.)

Constraints / facts that bound the design

• Physical iOS has no geometry and no coordinate input — coordinate tap / swipe / gesture / screenshot cannot be supported (channel limitation, confirmed on-device). Any first-class routing must degrade these cleanly. (Edit 2026-08-27: screenshot is supported over a second channel — CoreDevice xcrun devicectl device capture screenshot, no dev-signing requirement, shipped as ios-device screenshot in feat: add ios-device screenshot backed by devicectl #118. The audit-channel limitation stands for coordinate input; see the correction comment below.)
• Physical-iOS element handles expire between processes, so @N cannot be a cached-coordinate replay (tracked separately in ios-device: preserve the @N ergonomic via fingerprint re-resolution (and a feedback path to harden simulator @N) #113).
• Discovery cost: ~~FBDeviceControl attachment discovery pumps the run loop up to ~5 s, so unconditionally adding it to every sim-use devices call would regress the common simulator/Android path — hence "opt-in" above.~~ (Edit 2026-08-27: superseded — ~0.4 s with a device attached, ~1 s no-device after fix: bail fast from ios-device discovery when no device is attached #117's empty-grace bail; see the measurement comments below.)

Non-goals for this issue

No implementation, no chosen design — this is the problem catalogue we align on first. Follow-ups will design (a) the device-kind field + listing parity, and (b) the routing/daemon integration, likely as separate changes.

[onevcat]

Measured: physical-iOS discovery cost (correcting the estimate above)

The "~5 s worst case" for FBDeviceControl discovery in the constraints section was a guess from the code's timeout: 5. Measured on this host with one iPhone attached (fix/ios-device-navbar-dedup build):

Command	real time
sim-use ios-device devices (FBDeviceControl)	5.50 / 5.06 / 5.09 s
sim-use devices (simctl + adb)	0.77 / 0.52 s

So ~5 s is the typical cost here, not a worst case — each run hits the full 5 s deadline. That is ~7–10× the current devices latency, which strengthens the case for keeping physical-iOS listing opt-in.

It also surfaces a separate perf question: DeviceSession.attachedDevices is meant to return early once the attachment set stays unchanged for 0.25 s (the AttachmentQuiescence window), but in practice it runs the whole 5 s timeout even with a device already connected — the early-return isn't firing. If listing parity is pursued, investigating why discovery never quiesces (and whether it can settle in ~0.3 s) could remove the opt-in tension entirely.

[onevcat]

Correction: the ~5 s measurement above is invalid — no device was attached

I mis-stated "with one iPhone attached". It was not: devicectl list devices showed the iPhone as available (paired), not connected, and sim-use ios-device devices returned "No physical iOS devices connected." So the 5.0–5.5 s I measured is the no-device discovery timeout, not the cost of discovering an attached device.

That also retracts the "early-return isn't firing" observation: AttachmentQuiescence returns true only when the attachment set is non-empty and unchanged for 0.25 s; with no device the set is always empty, so it correctly never settles and runs the full 5 s deadline. That is the expected no-device path, not a bug.

The real questions remain open and unmeasured:

• discovery latency with a device actually attached (expected ~0.3 s if quiescence settles as designed — to be measured), and
• whether the no-device path should fail faster than 5 s when sim-use devices is extended to include physical iOS (a plain sim-use devices on a host with no iPhone should not eat a 5 s timeout).

Will re-measure with the device reconnected and post real numbers.

[onevcat]

Real numbers, device attached over USB — this overturns the "opt-in because ~5 s" rationale

Re-measured with iPhone One actually attached via USB (ios-device devices returns it):

Command	real time
sim-use ios-device devices — device attached	0.40 / 0.39 / 0.40 s
sim-use ios-device devices — no device (earlier)	~5.0–5.5 s (full timeout)
sim-use devices (simctl + adb) baseline	0.42 / 0.37 s

So with a device present, FBDeviceControl discovery is ~0.4 s — on par with the simctl+adb baseline, and the AttachmentQuiescence early-return works as designed. The 5 s only happens on the no-device path (an empty attachment set never satisfies "non-empty and unchanged", so it runs the full deadline).

Corrected design implication: including physical iOS in sim-use devices is not inherently expensive — when an iPhone is attached it costs ~0.4 s. The opt-in argument I gave earlier is retracted. The only real cost is the no-device timeout: a plain sim-use devices on a host with no iPhone attached should not eat 5 s. So the tractable sub-problem is a fast no-device bail (short initial-probe timeout, or a cheap usbmux presence check before the 5 s quiescence wait) — after which physical-iOS listing could plausibly be on by default rather than gated behind a flag.

[onevcat]

Correction: screenshot IS supportable on physical devices — via CoreDevice, not the audit channel

The constraints section above states coordinate tap / swipe / gesture / screenshot "cannot be supported (channel limitation, confirmed on-device)". That is accurate for the accessibility audit channel, but screenshot has a second channel: xcrun devicectl device capture screenshot (CoreDevice). Verified live (iPhone 15 Pro Max, iOS 26.6, USB): a valid 1290×2796 PNG in ~2.6 s, and with fewer restrictions than ui/tap — it captures any screen, SpringBoard and system apps included, with no development-signing requirement.

Shipped as sim-use ios-device screenshot in #118. Two knock-on facts for the capability-model design (problem 4):

• The physical-iOS "unsupported verb" list shrinks to: coordinate input (tap/swipe/gesture/multi-touch/type), @N (ios-device: preserve the @N ergonomic via fingerprint re-resolution (and a feedback path to harden simulator @N) #113), --json, and recording. Screenshot moves to the supported column.
• Screen recording exists on the same channel (devicectl device capture screen-record, with --duration/--codec) but is capability-gated per device: this iPhone reports The capability "Screen Recording" is not supported by this device (com.apple.coredevice.feature.screenrecording). So a future ios-device record-video is feasible in principle but needs capable hardware to verify, and the capability model needs to express "supported by the tool, refused by this device".

Note both installed Xcodes (26.6.0, 27.0.0 Beta 5) ship the same devicectl 642.9.1 with capture support, so no version gate was needed.

[onevcat]

Agreed design direction (recorded from offline discussion)

The follow-up design this issue deferred is now aligned. Sequenced as four independent changes, smallest risk first; the body's stale claims (screenshot, discovery cost) have been annotated in place.

PR 0 — DONE (#118): ios-device screenshot over CoreDevice. Shipped first because it corrected this issue's fact base before the capability model freezes it.

PR A — device-kind field + listing parity. Device.kind ∈ {simulator, emulator, physical}, orthogonal to platform (which stays {ios, android} — the Viewer and --platform contract don't move). Android populates from the existing-but-discarded Adb.Device.isEmulator; Devices.execute() gains a third listPhysicalIOS() side using the existing SideResult degradation pattern. Default on, no flag — post-#117 the no-device cost is ~1 s and runs parallel to simctl+adb. Known limitation to document: AMDevice may expose only an ECID until a session opens, so a listed id is not guaranteed UDID-shaped.

PR B — SimUseExecutableCommand conformance for the ios-device verbs. Structural alignment only: they gain --json, the execute()/format() split, and the shared hint machinery; simulatorUDIDForDaemon stays nil (in-process). Prerequisite for top-level forwarding.

PR C — first-class routing (the real decision). Add Platform.iOSDevice to PlatformRouter.resolve — every one of the 14 top-level verb switches goes non-exhaustive, so the compiler enumerates exactly the per-verb capability decisions. DeviceOptions.resolve()'s PhysicalIOSDeviceError hard reject is retired; rejection moves into each verb's .iOSDevice arm via a shared TargetCapabilityError (conforming to HintProviding, modelled on HIDKeyCommandHelp.androidUnsupportedMessage: why it can't work + the equivalent on this target). Supported at the top level: ui/describe-ui, tap (#id/label forms only), screenshot. The ios-device namespace stays, demoted to peer of ios/android.

PR D — daemon session persistence (follow-up, riskiest, reviewed on its own). The per-UDID daemon holds the DTX session across requests: amortises prepare()/finish(), and element handles stay valid for the daemon's lifetime — which largely dissolves #113's @N problem (the fingerprint becomes a drift-detection layer). Hazards: AXAuditClient.finish()'s mandatory teardown must move to daemon shutdown (idle timeout / SIGTERM), wedge recovery after a daemon crash needs live verification, and Daemon.Start's livenessProbe + staleSimulatorOutcome binary android/sim forks need a third arm.

Non-goals: ECID-shape routing (shape-based routing can't see it; document), Wi-Fi devices (#98), migrating existing Android capability strings to TargetCapabilityError (opportunistic only), screen-record until capable hardware is available.

[onevcat]

Design finalised — scope, decisions, and PR split

Decisions from the follow-up design review:

1. Scope of this issue: closes with PRs A–C below (CLI shape + user-facing behaviour). The daemon integration ("PR D") is extracted to daemon: hold the physical-device DTX session across invocations (amortised setup, live element handles) #120 — different risk class, and it interacts with ios-device: preserve the @N ergonomic via fingerprint re-resolution (and a feedback path to harden simulator @N) #113 rather than with anything here.
2. Device model: platform stays {ios, android}; new orthogonal kind ∈ {simulator, emulator, physical} (table column + additive --json field). Android's kind falls out of the existing Adb.Device.isEmulator. No --kind filter flag until a real need shows.
3. Listing default: physical-iOS discovery is on by default in sim-use devices — measured cost is ~0.4 s attached / ~1 s no-device (post-fix: bail fast from ios-device discovery when no device is attached #117), parallel with simctl+adb. No usbmux pre-probe for now; it remains a purely additive optimisation if the ~1 s ever matters.
4. Docs flip with routing: once top-level verbs route physical UDIDs, the docs/skill point there as the primary surface (ios-device becomes a peer namespace like ios/android) — with an explicit verb × target capability matrix so agents never assume capability parity on physical iOS. "Experimental" branding stays until the capability set grows (scroll ios-device: expose scroll actions (AXAction 2006/2007) #104, type ios-device: spike — text input via settable attributes #109).

PR split:

• PR A — kind field + listing parity (closes devices: list connected physical iOS devices in the cross-platform listing #111): Device.kind, third discovery side in devices with the existing degradation pattern. Known limitation documented: AMDevice may expose only an ECID until a session opens.
• PR B — SimUseExecutableCommand conformance for ios-device verbs (closes ios-device: add --json output #108): --json envelopes, execute()/format() split, shared hint machinery; still in-process (simulatorUDIDForDaemon = nil).
• PR C — first-class routing + capability model (closes this issue): Platform.iOSDevice in PlatformRouter (the 14 top-level switches go non-exhaustive — the compiler enumerates every capability decision); DeviceOptions.resolve()'s blanket PhysicalIOSDeviceError retired in favour of per-verb decisions via a shared TargetCapabilityError: HintProviding (modelled on HIDKeyCommandHelp.androidUnsupportedMessage); routed: describe-ui/ui, tap (#id/label forms), screenshot; everything else rejects with the reason and the nearest alternative. Docs flip + capability matrix land here.

Sequencing: A and B are independent (A: Device model + Devices.swift; B: iOSDeviceBackend verbs); C depends on both.

Housekeeping done today: #103 closed (shipped via #118, devicectl channel), #105 closed (fixed by #114; escape-action side-quest folded into #107), #120 opened for the daemon work. Capability tickets (#104 scroll, #106 attributes, #107 custom actions, #109 type, #110 first-read race, #112 selector nit) are orthogonal: each one that lands later flips its verb's .iOSDevice arm from reject to route, with no change to the shape built here.