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

internal/driver/ioscompanion/usbmux_test.go

@@ -0,0 +1,228 @@
+package ioscompanion
+
+import (
+	"context"
+	"io"
+	"net"
+	"testing"
+)
+
+func TestHtonsSwapsBytes(t *testing.T) {
+	// 49200 = 0xC030; network order swaps to 0x30C0 = 12480.
+	if got := htons(49200); got != 12480 {
+		t.Fatalf("htons(49200) = %d, want 12480", got)
+	}
+	if got := htons(0x1234); got != 0x3412 {
+		t.Fatalf("htons(0x1234) = %#x, want 0x3412", got)
+	}
+}
+
+func TestEncodePlistDictRoundTrips(t *testing.T) {
+	encoded, err := encodePlistDict(map[string]any{
+		"MessageType": "Connect",
+		"DeviceID":    7,
+		"PortNumber":  12480,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	dict, err := parsePlistDict(encoded)
+	if err != nil {
+		t.Fatalf("parse round-trip: %v", err)
+	}
+	if dict["MessageType"] != "Connect" {
+		t.Fatalf("MessageType = %v, want Connect", dict["MessageType"])
+	}
+	if dict["DeviceID"] != 7 {
+		t.Fatalf("DeviceID = %v, want 7", dict["DeviceID"])
+	}
+	if dict["PortNumber"] != 12480 {
+		t.Fatalf("PortNumber = %v, want 12480", dict["PortNumber"])
+	}
+}
+
+func TestEncodePlistDictEscapesStrings(t *testing.T) {
+	encoded, err := encodePlistDict(map[string]any{"Name": "a & b <c>"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	dict, err := parsePlistDict(encoded)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if dict["Name"] != "a & b <c>" {
+		t.Fatalf("Name = %q, want the unescaped original", dict["Name"])
+	}
+}
+
+// listDevicesReply is a representative usbmux ListDevices response with one USB
+// device, matching the shape macOS usbmuxd returns.
+const listDevicesReply = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>DeviceList</key>
+  <array>
+    <dict>
+      <key>DeviceID</key>
+      <integer>7</integer>
+      <key>MessageType</key>
+      <string>Attached</string>
+      <key>Properties</key>
+      <dict>
+        <key>ConnectionType</key>
+        <string>USB</string>
+        <key>SerialNumber</key>
+        <string>00008140-00022C4A3E13001C</string>
+      </dict>
+    </dict>
+  </array>
+</dict>
+</plist>`
+
+func TestSelectDeviceIDMatchesDashedSerial(t *testing.T) {
+	list, err := parsePlistDict([]byte(listDevicesReply))
+	if err != nil {
+		t.Fatal(err)
+	}
+	id, err := selectDeviceID(list, "00008140-00022C4A3E13001C")
+	if err != nil {
+		t.Fatalf("select by dashed serial: %v", err)
+	}
+	if id != 7 {
+		t.Fatalf("DeviceID = %d, want 7", id)
+	}
+}
+
+func TestSelectDeviceIDMatchesUndashedSerial(t *testing.T) {
+	list, err := parsePlistDict([]byte(listDevicesReply))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The raw USB serial carries no dash; it must still resolve.
+	id, err := selectDeviceID(list, "0000814000022C4A3E13001C")
+	if err != nil {
+		t.Fatalf("select by undashed serial: %v", err)
+	}
+	if id != 7 {
+		t.Fatalf("DeviceID = %d, want 7", id)
+	}
+}
+
+func TestSelectDeviceIDNotAttached(t *testing.T) {
+	list, err := parsePlistDict([]byte(listDevicesReply))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := selectDeviceID(list, "DEADBEEF-NOTHERE"); err == nil {
+		t.Fatal("a serial not in the list must error")
+	}
+}
+
+func TestParsePlistDictRejectsNonDictRoot(t *testing.T) {
+	arrayRoot := `<?xml version="1.0"?><plist version="1.0"><array></array></plist>`
+	if _, err := parsePlistDict([]byte(arrayRoot)); err == nil {
+		t.Fatal("a non-dict plist root must error")
+	}
+}
+
+// TestForwarderBridgesToDevice drives the forwarder end to end against an
+// in-process echo "device": a host connection through the loopback listener must
+// reach the injected device dialer and round-trip bytes.
+func TestForwarderBridgesToDevice(t *testing.T) {
+	deviceListener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer deviceListener.Close()
+	go func() {
+		for {
+			conn, acceptErr := deviceListener.Accept()
+			if acceptErr != nil {
+				return
+			}
+			go io.Copy(conn, conn)
+		}
+	}()
+
+	localAddress, err := pickLoopbackAddress()
+	if err != nil {
+		t.Fatal(err)
+	}
+	forwarder, err := startForwarder(context.Background(), localAddress, func(ctx context.Context) (net.Conn, error) {
+		return net.Dial("tcp", deviceListener.Addr().String())
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer forwarder.Close()
+
+	hostConn, err := net.Dial("tcp", localAddress)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer hostConn.Close()
+
+	message := []byte("ping\n")
+	if _, err := hostConn.Write(message); err != nil {
+		t.Fatal(err)
+	}
+	buffer := make([]byte, len(message))
+	if _, err := io.ReadFull(hostConn, buffer); err != nil {
+		t.Fatal(err)
+	}
+	if string(buffer) != string(message) {
+		t.Fatalf("round-trip = %q, want %q", buffer, message)
+	}
+}
+
+// TestForwarderClosesHostOnDeviceDialFailure asserts the failure path the runner
+// transport relies on: when the device dial fails (the runner not yet
+// listening), the forwarder closes the host side so the caller sees a dropped
+// connection and retries.
+func TestForwarderClosesHostOnDeviceDialFailure(t *testing.T) {
+	localAddress, err := pickLoopbackAddress()
+	if err != nil {
+		t.Fatal(err)
+	}
+	forwarder, err := startForwarder(context.Background(), localAddress, func(ctx context.Context) (net.Conn, error) {
+		return nil, io.ErrUnexpectedEOF
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer forwarder.Close()
+
+	hostConn, err := net.Dial("tcp", localAddress)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer hostConn.Close()
+
+	// The forwarder closes its side after the failed device dial; the read
+	// returns EOF rather than blocking forever.
+	if _, err := io.ReadFull(hostConn, make([]byte, 1)); err == nil {
+		t.Fatal("read must fail once the forwarder closes the host side")
+	}
+}
+
+func TestForwarderCloseStopsAcceptLoop(t *testing.T) {
+	localAddress, err := pickLoopbackAddress()
+	if err != nil {
+		t.Fatal(err)
+	}
+	forwarder, err := startForwarder(context.Background(), localAddress, func(ctx context.Context) (net.Conn, error) {
+		return nil, io.EOF
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := forwarder.Close(); err != nil {
+		t.Fatal(err)
+	}
+	// After Close the listener is gone, so a dial must fail.
+	if conn, dialErr := net.Dial("tcp", localAddress); dialErr == nil {
+		conn.Close()
+		t.Fatal("dial must fail after the forwarder is closed")
+	}
+}