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/ios/device.go

@@ -0,0 +1,129 @@
+package ios
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+// Device is a physical iOS device resolved from devicectl. A device carries two
+// identifiers: HardwareUDID feeds xcodebuild -destination and the usbmux device
+// match, while CoreDeviceID feeds devicectl install/uninstall.
+type Device struct {
+	Name         string
+	HardwareUDID string
+	CoreDeviceID string
+}
+
+// coreDevice mirrors the fields of one entry in devicectl's JSON device list.
+type coreDevice struct {
+	Identifier         string `json:"identifier"`
+	HardwareProperties struct {
+		UDID string `json:"udid"`
+	} `json:"hardwareProperties"`
+	DeviceProperties struct {
+		Name string `json:"name"`
+	} `json:"deviceProperties"`
+}
+
+type coreDeviceList struct {
+	Result struct {
+		Devices []coreDevice `json:"devices"`
+	} `json:"result"`
+}
+
+// listDevices is a seam: overridable in tests so ResolveDevice runs against
+// canned devicectl output without invoking xcrun.
+var listDevices = coreDevices
+
+// ConnectedDevices lists the physical iOS devices devicectl reports. The doctor
+// uses it to confirm at least one device is connected and paired.
+func ConnectedDevices(ctx context.Context) ([]Device, error) {
+	return listDevices(ctx)
+}
+
+// ResolveDevice picks the physical iOS device a run drives. An empty query
+// resolves the single connected device (an error names them all when several
+// are connected). A non-empty query matches a device by name, hardware UDID, or
+// CoreDevice id. No match and an ambiguous match are both errors that list the
+// connected devices so the caller can refine --ios-device.
+func ResolveDevice(ctx context.Context, query string) (Device, error) {
+	devices, err := listDevices(ctx)
+	if err != nil {
+		return Device{}, fmt.Errorf("list devices: %w", err)
+	}
+	if len(devices) == 0 {
+		return Device{}, fmt.Errorf("no connected iOS device found; connect and pair an iPhone, then check `xcrun devicectl list devices`")
+	}
+
+	if query == "" {
+		if len(devices) == 1 {
+			return devices[0], nil
+		}
+		return Device{}, fmt.Errorf("multiple connected iOS devices; pass --ios-device to select one:%s", deviceLines(devices))
+	}
+
+	var matches []Device
+	for _, device := range devices {
+		if device.Name == query || device.HardwareUDID == query || device.CoreDeviceID == query {
+			matches = append(matches, device)
+		}
+	}
+	switch len(matches) {
+	case 1:
+		return matches[0], nil
+	case 0:
+		return Device{}, fmt.Errorf("no connected iOS device matches %q; connected devices:%s", query, deviceLines(devices))
+	default:
+		return Device{}, fmt.Errorf("--ios-device %q matches multiple devices; select by hardware UDID or CoreDevice id:%s", query, deviceLines(matches))
+	}
+}
+
+func deviceLines(devices []Device) string {
+	var lines strings.Builder
+	for _, device := range devices {
+		fmt.Fprintf(&lines, "\n  %s (udid %s, id %s)", device.Name, device.HardwareUDID, device.CoreDeviceID)
+	}
+	return lines.String()
+}
+
+// coreDevices invokes devicectl and parses its JSON device list. devicectl
+// writes the JSON to a file path rather than stdout, so a temp file backs the
+// --json-output flag and is read back after the command runs.
+func coreDevices(ctx context.Context) ([]Device, error) {
+	outputFile, err := os.CreateTemp("", "sanderling-devices-*.json")
+	if err != nil {
+		return nil, err
+	}
+	outputPath := outputFile.Name()
+	outputFile.Close()
+	defer os.Remove(outputPath)
+
+	if err := exec.CommandContext(ctx, "xcrun", "devicectl", "list", "devices", "--json-output", outputPath).Run(); err != nil {
+		return nil, fmt.Errorf("xcrun devicectl list devices: %w", err)
+	}
+	data, err := os.ReadFile(outputPath)
+	if err != nil {
+		return nil, err
+	}
+	return parseDevices(data)
+}
+
+func parseDevices(data []byte) ([]Device, error) {
+	var list coreDeviceList
+	if err := json.Unmarshal(data, &list); err != nil {
+		return nil, err
+	}
+	var devices []Device
+	for _, entry := range list.Result.Devices {
+		devices = append(devices, Device{
+			Name:         entry.DeviceProperties.Name,
+			HardwareUDID: entry.HardwareProperties.UDID,
+			CoreDeviceID: entry.Identifier,
+		})
+	}
+	return devices, nil
+}

internal/ios/device_test.go

@@ -0,0 +1,158 @@
+package ios
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// devicectlJSON mirrors the shape of `xcrun devicectl list devices
+// --json-output` for two connected devices, trimmed to the fields the parser
+// reads.
+const devicectlJSON = `{
+  "info": {"outcome": "success"},
+  "result": {
+    "devices": [
+      {
+        "identifier": "1FB35C36-A358-56F9-AD9F-931DC1C867FF",
+        "hardwareProperties": {"udid": "00008140-00022C4A3E13001C"},
+        "deviceProperties": {"name": "iPhone"}
+      },
+      {
+        "identifier": "2AC46D47-B469-67A0-BE0A-042ED2D978AA",
+        "hardwareProperties": {"udid": "00008110-000A1B2C3D4E5F60"},
+        "deviceProperties": {"name": "Test iPad"}
+      }
+    ]
+  }
+}`
+
+func swapListDevices(t *testing.T, devices []Device, err error) {
+	t.Helper()
+	original := listDevices
+	t.Cleanup(func() { listDevices = original })
+	listDevices = func(context.Context) ([]Device, error) { return devices, err }
+}
+
+func TestParseDevices(t *testing.T) {
+	got, err := parseDevices([]byte(devicectlJSON))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("parsed %d devices, want 2", len(got))
+	}
+	want := Device{Name: "iPhone", HardwareUDID: "00008140-00022C4A3E13001C", CoreDeviceID: "1FB35C36-A358-56F9-AD9F-931DC1C867FF"}
+	if got[0] != want {
+		t.Fatalf("device[0] = %+v, want %+v", got[0], want)
+	}
+}
+
+func TestParseDevices_InvalidJSON(t *testing.T) {
+	if _, err := parseDevices([]byte("not json")); err == nil {
+		t.Fatal("expected error on malformed JSON")
+	}
+}
+
+func TestResolveDevice_MatchByName(t *testing.T) {
+	devices, _ := parseDevices([]byte(devicectlJSON))
+	swapListDevices(t, devices, nil)
+	got, err := ResolveDevice(context.Background(), "iPhone")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.HardwareUDID != "00008140-00022C4A3E13001C" {
+		t.Fatalf("resolved %+v, want the iPhone", got)
+	}
+}
+
+func TestResolveDevice_MatchByHardwareUDID(t *testing.T) {
+	devices, _ := parseDevices([]byte(devicectlJSON))
+	swapListDevices(t, devices, nil)
+	got, err := ResolveDevice(context.Background(), "00008110-000A1B2C3D4E5F60")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Name != "Test iPad" {
+		t.Fatalf("resolved %+v, want Test iPad", got)
+	}
+}
+
+func TestResolveDevice_MatchByCoreDeviceID(t *testing.T) {
+	devices, _ := parseDevices([]byte(devicectlJSON))
+	swapListDevices(t, devices, nil)
+	got, err := ResolveDevice(context.Background(), "1FB35C36-A358-56F9-AD9F-931DC1C867FF")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Name != "iPhone" {
+		t.Fatalf("resolved %+v, want iPhone", got)
+	}
+}
+
+func TestResolveDevice_EmptyQuerySingleDevice(t *testing.T) {
+	swapListDevices(t, []Device{{Name: "iPhone", HardwareUDID: "udid-1", CoreDeviceID: "id-1"}}, nil)
+	got, err := ResolveDevice(context.Background(), "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.HardwareUDID != "udid-1" {
+		t.Fatalf("resolved %+v, want the only device", got)
+	}
+}
+
+func TestResolveDevice_EmptyQueryMultipleErrors(t *testing.T) {
+	devices, _ := parseDevices([]byte(devicectlJSON))
+	swapListDevices(t, devices, nil)
+	_, err := ResolveDevice(context.Background(), "")
+	if err == nil {
+		t.Fatal("expected ambiguity error for multiple devices with no query")
+	}
+	for _, want := range []string{"--ios-device", "iPhone", "Test iPad"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("ambiguity error missing %q: %v", want, err)
+		}
+	}
+}
+
+func TestResolveDevice_NotFound(t *testing.T) {
+	devices, _ := parseDevices([]byte(devicectlJSON))
+	swapListDevices(t, devices, nil)
+	_, err := ResolveDevice(context.Background(), "Pixel")
+	if err == nil {
+		t.Fatal("expected not-found error")
+	}
+	if !strings.Contains(err.Error(), "iPhone") {
+		t.Errorf("not-found error should list candidates: %v", err)
+	}
+}
+
+func TestResolveDevice_NoneConnected(t *testing.T) {
+	swapListDevices(t, nil, nil)
+	_, err := ResolveDevice(context.Background(), "iPhone")
+	if err == nil {
+		t.Fatal("expected error when no device is connected")
+	}
+}
+
+func TestResolveDevice_ListError(t *testing.T) {
+	swapListDevices(t, nil, errors.New("devicectl blew up"))
+	if _, err := ResolveDevice(context.Background(), ""); err == nil {
+		t.Fatal("expected list error to propagate")
+	}
+}
+
+func TestResolveDevice_AmbiguousMatch(t *testing.T) {
+	swapListDevices(t, []Device{
+		{Name: "iPhone", HardwareUDID: "udid-a", CoreDeviceID: "id-a"},
+		{Name: "iPhone", HardwareUDID: "udid-b", CoreDeviceID: "id-b"},
+	}, nil)
+	_, err := ResolveDevice(context.Background(), "iPhone")
+	if err == nil {
+		t.Fatal("expected ambiguous-match error for duplicate names")
+	}
+	if !strings.Contains(err.Error(), "udid-a") || !strings.Contains(err.Error(), "udid-b") {
+		t.Errorf("ambiguous error should list both candidates: %v", err)
+	}
+}

internal/ios/ios.go

@@ -79,8 +79,8 @@ func BootedUDID(ctx context.Context) string {
 // available) resolves to that simulator. With no query, exactly one booted
 // simulator resolves to it; multiple booted simulators is an error that lists
 // them and asks the caller to pass --ios-device. A query that matches no
-// simulator resolves as a physical device (udid = query, simulator false) so
-// the sidecar path drives it.
+// simulator resolves as a physical device (udid = query, simulator false),
+// which the caller then resolves through ResolveDevice for the device driver.
 func ResolveTarget(ctx context.Context, query string) (udid string, isSimulator bool, err error) {
 	if query != "" {
 		booted, err := listBootedAll(ctx)