Physical-device iOS support (#64) (#66)

* feat(companion): add appState, eraseText, pressKey runner handlers

The Go runner transport already calls these methods; the in-device runner
implemented them only latently. They become load-bearing on the device
path, where the hybrid's legacy-companion fallback is absent. Backward
compatible: the simulator hybrid never calls them.

* feat(ios): resolve physical devices from devicectl

ResolveDevice parses xcrun devicectl list devices into Device{Name,
HardwareUDID, CoreDeviceID}: the hardware UDID feeds xcodebuild/iproxy
and the CoreDevice id feeds devicectl install. Matches by name or either
id; errors list candidates on none/ambiguous. Fixes the stale sidecar
comment on ResolveTarget.

* feat(ioscompanion): runner-only device driver mode

NewDevice reuses Driver with d.companion set to the runner dialed over an
iproxy usbmux tunnel, hybrid=false, runnerClient=nil. The existing accessor
seams then route launch/snapshot/text/gesture to the runner with no new
DeviceDriver methods. Device seams swap clear-state to a devicectl
reinstall, container reset to a warn-once no-op, and paste grant to a no-op.
realSpawnDeviceRunner builds and signs the runner at run time via the App
Store Connect API key (no Xcode UI), caching on a source hash.

* test(ioscompanion): cover device wiring, routing, and shell-out argv

Seam-driven NewDevice wiring + gesture/text routing (asserting no keyboard
HID), devicectl/build/test/iproxy argv builders, xctestrun test-target dict
name parsing, signing-credential env checks, and source-hash cache keying.

* feat(testrun): route physical-device iOS runs to the device driver

Execute resolves a non-simulator iOS target through ios.ResolveDevice into
its hardware UDID and CoreDevice id; buildDriver constructs NewDevice via a
seam instead of rejecting the device. Generalizes the --ios-device and
--ios-app-path help to cover the device path; signing stays env-read, never
a flag.

* feat(doctor): device prereqs replace java/sidecar for ios-device

iosDeviceChecks now verifies devicectl, iproxy on PATH, a connected+paired
device (via ios.ConnectedDevices), and App Store Connect signing creds (via
ioscompanion.VerifyDeviceSigning). The retired JVM sidecar checks stay only
under android.

* feat(conformance): device backend uses iphoneos app and tunnel orphan checks

The device backend now builds via just ios-device, points --ios-app-path at
the Debug-iphoneos bundle, and reinstalls each run for clear-state. The G5
orphan scan replaces the retired sidecar.jar check with lingering iproxy and
device test-without-building sessions (destination platform=iOS,id=).

* feat(folio): device build linking the iosArm64 framework

project.yml selects the Kotlin framework slice by SDK (iosArm64 for
iphoneos, iosSimulatorArm64 for simulator) and links via -framework Shared
on the SDK-conditional search path. New ios-device/test-ios-device recipes
mirror ios/test-ios, signing the Debug-iphoneos build with the .env API key.

* docs(cli): document ios-device doctor checks and the device flags

The --ios-device flag now also selects a connected device; --ios-app-path
covers the device install; the doctor gains an ios-device platform whose
checks are devicectl, iproxy, a paired device, and signing credentials.
Corrects the --clear-data default to true.

* fix(ioscompanion): resolve signing key path to absolute

xcodebuild's -authenticationKeyPath requires an absolute path, but .env
files commonly carry a repo-relative one. Resolve it against the working
directory before the stat so a relative ASC_API_KEY_PATH still signs.

* fix(ioscompanion): re-enable signing for the device runner build

companion/project.yml disables code signing for the simulator build, so
the device build inherited it and produced an unsigned runner that the
device rejected at install (0xe8008018). build-for-testing now forces
CODE_SIGNING_ALLOWED/REQUIRED=YES so automatic provisioning signs it.

* fix(ioscompanion): key the device build cache on signing identity

The cache marker hashed only sources, so switching signing team or key
reused a runner signed with the stale identity, which the device rejects at
install (0xe8008018). Fold team + key id into the cache key so a signing
change forces a rebuild.

* docs(getting-started): document physical iOS device setup

Lists the iproxy requirement and the App Store Connect signing env vars
(SANDERLING_IOS_TEAM, ASC_API_*) a device run needs, plus the
test-ios-device recipe and the doctor check.

* feat(ios): native usbmux client and in-process tunnel forwarder

Talk to macOS usbmuxd directly instead of shelling out to iproxy, so the
device path depends on nothing beyond macOS + Xcode.

* refactor(ios): drive device tunnel via io.Closer seam

Replace the tunnelChild *exec.Cmd and spawnTunnel seam with a tunnel
io.Closer and startTunnel seam backed by the in-process usbmux forwarder.

* refactor(ios): remove iproxy spawn from device runner

* test(ios): cover tunnel close via io.Closer not child process

* feat(doctor): check usbmuxd socket instead of iproxy on PATH

* chore(conformance): drop iproxy orphan check; tunnel is in-process

* docs(ios): device tunnel uses native usbmux, nothing to install

* chore: gitignore the signing keys directory

* feat(folio): add Android launcher icon (black bg, white dot)

* feat(folio): add iOS app icon (black bg, white dot)

* feat(folio): add web favicon (black bg, white dot)

* docs(ioscompanion): fix stale const comments

* refactor(ioscompanion): inline single-use devicectl argv builders

* refactor(ioscompanion): inline xcodegenArgs, drop tautological argv tests

* refactor(ioscompanion): inline firstNonEmpty

* refactor(doctor): dedup usbmuxd socket path via ioscompanion seam

* test(doctor): trim redundant signing-check test

* refactor(ioscompanion): deliver COMPANION_PORT via TEST_RUNNER_ env

* fix(testrun): seam preflight so iOS routing tests pass on CI without xcrun

conformance/gates.sh

@@ -7,8 +7,8 @@
 # Backends:
 #   BACKEND=simulator (default)  drive the booted iOS simulator
 #   BACKEND=device               drive an attached physical iPhone via the
-#                                native sidecar; select it with
-#                                IOS_DEVICE="<name>" (passed as --ios-device)
+#                                driver's runner-only device path; select it
+#                                with IOS_DEVICE="<name>" (passed as --ios-device)
 #
 # Usage:
 #   ./gates.sh                          run the simulator gates
@@ -37,7 +37,13 @@ IOS_DEVICE="${IOS_DEVICE:-iPhone 17 Pro}"
 
 bundle_id="app.folio"
 spec_path="${folio_directory}/sanderling/spec.ts"
-ios_app="${folio_directory}/app/iosApp/build/Build/Products/Debug-iphonesimulator/iosApp.app"
+# The built app bundle differs by SDK: the simulator build lands under
+# Debug-iphonesimulator, the device build under Debug-iphoneos.
+if [[ "$BACKEND" == "device" ]]; then
+  ios_app="${folio_directory}/app/iosApp/build/Build/Products/Debug-iphoneos/iosApp.app"
+else
+  ios_app="${folio_directory}/app/iosApp/build/Build/Products/Debug-iphonesimulator/iosApp.app"
+fi
 
 # The companion binary, embedded for simulator runs. Referenced by file name
 # only for the orphan-process check; prose elsewhere says "the companion".
@@ -187,7 +193,8 @@ print(samples[rank - 1])
 
 # G5 orphan check: report any lingering companion, runner session (the hybrid
 # simulator driver hosts an in-simulator runner), and, on the device backend,
-# the XCTest runner java sidecar. Empty output means clean.
+# the device runner session. The usbmux tunnel is an in-process forwarder that
+# dies with sanderling, so it leaves no process to check. Empty output is clean.
 orphan_processes() {
   local found=""
   if pgrep -f "$companion_process_name" >/dev/null 2>&1; then
@@ -200,9 +207,10 @@ orphan_processes() {
     found+="runner-app "
   fi
   if [[ "$BACKEND" == "device" ]]; then
-    # The native sidecar that drives the XCTest runner for physical devices.
-    if pgrep -f "sanderling.*sidecar.jar" >/dev/null 2>&1; then
-      found+="sidecar "
+    # The device test session that hosts the runner. Its destination carries
+    # platform=iOS,id=<udid>.
+    if pgrep -f "xctestrun.*platform=iOS,id=" >/dev/null 2>&1; then
+      found+="device-session "
     fi
   fi
   printf '%s' "$found"
@@ -215,15 +223,11 @@ invoke_sanderling() {
   local output_log="$2"
   local exit_status_file="$3"
 
-  local target_flags=()
-  if [[ "$BACKEND" == "device" ]]; then
-    target_flags=(--ios-device "$IOS_DEVICE")
-  else
-    # Simulator: build + install the current app so each run starts from the
-    # current build, matching the test-ios recipe. clear-state reinstall uses
-    # --ios-app-path. just ios boots IOS_DEVICE if nothing is booted.
-    target_flags=(--ios-device "$IOS_DEVICE" --ios-app-path "$ios_app")
-  fi
+  # Both backends pass --ios-app-path so each run reinstalls the current build
+  # for a clean clear-state start (device install via devicectl, simulator via
+  # simctl). The device backend selects the connected iPhone by name; the
+  # simulator backend boots IOS_DEVICE if nothing is booted.
+  local target_flags=(--ios-device "$IOS_DEVICE" --ios-app-path "$ios_app")
 
   local status=0
   "$SANDERLING" test \
@@ -254,6 +258,9 @@ run_gates() {
   if [[ "$BACKEND" == "simulator" ]]; then
     echo "preparing folio build for the simulator backend"
     ( cd "$folio_directory" && just ios >/dev/null )
+  else
+    echo "preparing folio device build"
+    ( cd "$folio_directory" && just ios-device >/dev/null )
   fi
 
   local timestamp