iOS simulator driver: Go-native companion-backed backend (#62)

* perf(ios): use prebuilt XCTest runner to cut startup

* chore(ioscompanion): add companion asset prepare script

* feat(ioscompanion): embed and extract simulator companion bundle

* test(ioscompanion): cover companion stub and embedded extraction

* docs: add third party notices for vendored companion

* chore: ignore vendored companion bundle artifact

* build(proto): pin simulator companion proto v1.1.8

* build(proto): add dedicated buf module and gen template for pinned proto

* build(proto): exclude pinned companion proto from root buf workspace

* feat(ioscompanion): commit generated companion gRPC stubs

* feat(ioscompanion): map flat companion describe dump to TreeNode JSON

* test(ioscompanion): add hierarchy-map golden and unit tests

* feat(ioscompanion): port screen-settle stability polling to Go

* test(ioscompanion): cover settle transitional, hash, streak, and cap rules

* feat(ioscompanion): add USB HID keymap module

* test(ioscompanion): cover keymap branches and paste-chord constants

* build: embed companion assets via withcompanion tag

* feat(ioscompanion): add transport companion interface

* feat(ioscompanion): add HID event wrapper and builders

* feat(ioscompanion): wire gRPC companion client and Dial

* test(ioscompanion): cover HID builders and unit conversions

* test(ioscompanion): cover Dial, process-state mapping, and install archive

* test(ioscompanion): add gated simulator integration smoke test

* feat(ioscompanion): text input and gesture HID composition with pasteboard fallback

* test(ioscompanion): cover input composers, paste dialog loop, and pure helpers

* feat(ioscompanion): add Describe to companion transport

* feat(ioscompanion): implement DeviceDriver with companion supervision

* test(ioscompanion): unit tests with fake companion transport

* test(ioscompanion): gated companion smoke test

* feat(ios): add ResolveTarget for simulator vs physical-device routing

* feat(testrun): route iOS simulators through the native companion driver

* refactor(testrun): defer the java preflight check to the physical-device path

* feat(cli): add --ios-app-path flag

* feat(doctor): split iOS checks into simulator and physical-device paths

* test(folio): add gate-analyzer fixtures for G1-G5

* feat(folio): add iOS conformance gate script

* chore(folio): wire gates recipe, app path, and ignore gate output

* style: gofmt struct alignment drift

* fix(doctor): probe simctl via xcrun instead of PATH lookup

* fix(ioscompanion): spawn companion under driver-lifetime context

* test(ioscompanion): prove companion child outlives startup context

* fix(ioscompanion): chunk install payload under companion message cap

* test(ioscompanion): cover install payload chunking

* fix(ioscompanion): reinstall via simctl and sanitize companion env

* fix(ioscompanion): wait out unresolved accessibility values after launch

* perf(ioscompanion): paste long text for atomic landing

* test(ioscompanion): cover paste threshold, retry flow, and sentinel detection

* fix(ioscompanion): treat unresolved bridge values as transitional, never as content

* fix(ioscompanion): accept masked secure-field values as paste landing

* test(ioscompanion): cover sentinel mapping and masked-field landing

* fix(ioscompanion): atomic erase and single-send paste to prevent doubling

* test(ioscompanion): cover atomic erase, single chord, unverifiable field

* fix(ioscompanion): verify paste on a time budget that outlasts the bridge blackout

* test(ioscompanion): cover bridge-blackout paste verification

* fix(ioscompanion): drop unresolved-value settle gate that never let empty-field screens settle

* refactor(ioscompanion): name the empty-editable-field sentinel for what it is

* perf(ioscompanion): tighten settle streak for the fast companion transport

* feat(ioscompanion): pre-grant pasteboard access so unicode input skips the OS prompt

* refactor(ioscompanion): drop paste warm-up now that the grant suppresses the prompt

* test(ioscompanion): cover pasteboard grant on launch, drop warm-up tests

* fix(ioscompanion): retry describe past transient collapsed accessibility dumps

* test(ioscompanion): cover collapsed-dump detection

* perf(ioscompanion): split raw and retrying describe so settle does not double-wait collapses

* perf(ioscompanion): tighten settle now that collapses are handled separately

* fix(ioscompanion): replace field content on input so blackout-skipped erase cannot accumulate text

* test(ioscompanion): cover replace-on-input and TextReplacer capability

* refactor(ioscompanion): neutralize HID events behind the transport seam

* feat(companion): add simulator runner project skeleton

* feat(companion): serve accessibility snapshots over the wire protocol

* feat(companion): synthesize timestamped touch gestures

* feat(companion): type text with replace semantics

* feat(companion): serve the wire protocol from a parked runner

* feat(ioscompanion): add TextEditor capability and unavailable sentinel to the transport seam

* feat(ioscompanion): route text input through a text-editing companion when available

* fix(companion): bind listener by port and source screen size from snapshot

* feat(ioscompanion): add runner companion JSON transport

* test(ioscompanion): cover runner transport protocol mapping

* fix(companion): synthesize gestures synchronously to avoid the async completion crash

* fix(companion): type on the main thread and recover from focus assertions

* fix(companion): keep serving after an automation failure

* refactor(companion): tidy snapshot serialization

* fix(companion): honor sequential tap gaps and survive synthesis exceptions

* feat(ioscompanion): expose native typing with an explicit replace flag

* chore(companion): add runner asset prepare script

* feat(ioscompanion): embed and extract the runner test bundle

* test(ioscompanion): cover runner asset extraction

* build(ioscompanion): commit runner asset archive

* feat(ioscompanion): pair the legacy companion with the in-simulator runner

* test(ioscompanion): cover hybrid routing, paste-grant skip, and port binding

* fix(ioscompanion): reconnect after interrupted runner calls instead of restarting

* fix(ioscompanion): route hybrid lifecycle through the runner and harden restarts

* feat(companion): launch and terminate apps through the automation session

* build(ioscompanion): refresh runner asset with session lifecycle

* fix(ioscompanion): classify connection deadline expiry as caller budget

* fix(companion): capture snapshots on the main thread inside the catch bridge

* build(ioscompanion): refresh runner asset with main-thread snapshots

* perf(ioscompanion): count read spans toward settle and capture snapshots concurrently

* feat(ioscompanion): make the hybrid simulator companion the default

* test(folio): cover runner-session orphans in the gate harness

* test(ioscompanion): pin the child-lifetime test to the legacy path

* fix(ioscompanion): keep mappable text on one HID stream and verify unicode clears

* fix(ioscompanion): pause the clear chord so selection applies before the delete

* fix(companion): prune the keyboard subtree from snapshots

* build(ioscompanion): refresh runner asset without keyboard elements

* fix(ioscompanion): capture the screenshot transport before a recovery can reassign it

* fix(companion): pin the runner listener to loopback

* fix(companion): size the replace delete prefix to cover any focused field

* build(ioscompanion): refresh runner asset with loopback bind and replace fix

* fix(cli): cancel the run context on SIGINT so spawned children are reaped

* fix(testrun): point the device java preflight hint at the ios-device doctor

* fix(folio): word-bound the G2 ERROR scan and drop the dead objc allowlist glob

* test(ioscompanion): cover stopProcess, restart, and failed bring-up supervision

* chore: add test-companion target for the withcompanion-tagged suite

* chore(ioscompanion): stop tracking the runner archive build artifact

* build: produce the runner archive from source like the companion bundle

* refactor(conformance): move the gate harness out of examples/folio

* chore(folio): drop the gate harness wiring from the example app

internal/driver/ioscompanion/transport/grpc.go

@@ -0,0 +1,295 @@
+package transport
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+
+	pb "github.com/priyanshujain/sanderling/internal/driver/ioscompanion/companionpb"
+)
+
+// maxReceiveBytes is generous because screenshots can be large.
+const maxReceiveBytes = 64 * 1024 * 1024
+
+type grpcCompanion struct {
+	conn   *grpc.ClientConn
+	client pb.CompanionServiceClient
+}
+
+// Dial connects to the companion listening at address and returns a Companion.
+func Dial(address string) (Companion, error) {
+	conn, err := grpc.NewClient(address,
+		grpc.WithTransportCredentials(insecure.NewCredentials()),
+		grpc.WithDefaultCallOptions(grpc.MaxCallRecvMsgSize(maxReceiveBytes)))
+	if err != nil {
+		return nil, err
+	}
+	return &grpcCompanion{conn: conn, client: pb.NewCompanionServiceClient(conn)}, nil
+}
+
+func (c *grpcCompanion) Close() error { return c.conn.Close() }
+
+func (c *grpcCompanion) AccessibilityInfo(ctx context.Context) (string, error) {
+	resp, err := c.client.AccessibilityInfo(ctx, &pb.AccessibilityInfoRequest{
+		Format: pb.AccessibilityInfoRequest_LEGACY,
+	})
+	if err != nil {
+		return "", err
+	}
+	return resp.GetJson(), nil
+}
+
+func (c *grpcCompanion) Describe(ctx context.Context) (ScreenDescription, error) {
+	resp, err := c.client.Describe(ctx, &pb.TargetDescriptionRequest{})
+	if err != nil {
+		return ScreenDescription{}, err
+	}
+	return screenDescriptionFrom(resp), nil
+}
+
+// screenDescriptionFrom extracts the point dimensions and scale from a describe
+// response. The generated getters are nil-safe, so a response missing the
+// nested messages yields a zero-valued ScreenDescription rather than panicking.
+func screenDescriptionFrom(resp *pb.TargetDescriptionResponse) ScreenDescription {
+	dimensions := resp.GetTargetDescription().GetScreenDimensions()
+	return ScreenDescription{
+		WidthPoints:  int(dimensions.GetWidthPoints()),
+		HeightPoints: int(dimensions.GetHeightPoints()),
+		Scale:        dimensions.GetDensity(),
+	}
+}
+
+func (c *grpcCompanion) SendHID(ctx context.Context, events ...HIDEvent) error {
+	stream, err := c.client.Hid(ctx)
+	if err != nil {
+		return err
+	}
+	for _, e := range events {
+		message, err := hidEventToProto(e)
+		if err != nil {
+			return err
+		}
+		if err := stream.Send(message); err != nil {
+			return err
+		}
+	}
+	_, err = stream.CloseAndRecv()
+	return err
+}
+
+// hidEventToProto encodes a neutral HID event as this companion's wire event.
+// The companion measures delays and swipe durations in seconds.
+func hidEventToProto(e HIDEvent) (*pb.HIDEvent, error) {
+	switch e.Kind {
+	case HIDKindTouchDown:
+		return touchProto(e.X, e.Y, pb.HIDEvent_DOWN), nil
+	case HIDKindTouchUp:
+		return touchProto(e.X, e.Y, pb.HIDEvent_UP), nil
+	case HIDKindKeyDown:
+		return keyProto(e.Usage, pb.HIDEvent_DOWN), nil
+	case HIDKindKeyUp:
+		return keyProto(e.Usage, pb.HIDEvent_UP), nil
+	case HIDKindDelay:
+		return &pb.HIDEvent{Event: &pb.HIDEvent_Delay{
+			Delay: &pb.HIDEvent_HIDDelay{Duration: e.Milliseconds / 1000.0},
+		}}, nil
+	case HIDKindSwipe:
+		return &pb.HIDEvent{Event: &pb.HIDEvent_Swipe{Swipe: &pb.HIDEvent_HIDSwipe{
+			Start:    &pb.Point{X: e.FromX, Y: e.FromY},
+			End:      &pb.Point{X: e.ToX, Y: e.ToY},
+			Duration: e.Seconds,
+		}}}, nil
+	}
+	return nil, fmt.Errorf("unknown HID event kind %d", e.Kind)
+}
+
+func touchProto(x, y float64, direction pb.HIDEvent_HIDDirection) *pb.HIDEvent {
+	return &pb.HIDEvent{Event: &pb.HIDEvent_Press{Press: &pb.HIDEvent_HIDPress{
+		Direction: direction,
+		Action: &pb.HIDEvent_HIDPressAction{Action: &pb.HIDEvent_HIDPressAction_Touch{
+			Touch: &pb.HIDEvent_HIDTouch{Point: &pb.Point{X: x, Y: y}},
+		}},
+	}}}
+}
+
+func keyProto(usage uint32, direction pb.HIDEvent_HIDDirection) *pb.HIDEvent {
+	return &pb.HIDEvent{Event: &pb.HIDEvent_Press{Press: &pb.HIDEvent_HIDPress{
+		Direction: direction,
+		Action: &pb.HIDEvent_HIDPressAction{Action: &pb.HIDEvent_HIDPressAction_Key{
+			Key: &pb.HIDEvent_HIDKey{Keycode: uint64(usage)},
+		}},
+	}}}
+}
+
+func (c *grpcCompanion) Screenshot(ctx context.Context) ([]byte, string, error) {
+	resp, err := c.client.Screenshot(ctx, &pb.ScreenshotRequest{})
+	if err != nil {
+		return nil, "", err
+	}
+	return resp.GetImageData(), resp.GetImageFormat(), nil
+}
+
+func (c *grpcCompanion) Launch(ctx context.Context, bundleID string, foregroundIfRunning bool) error {
+	stream, err := c.client.Launch(ctx)
+	if err != nil {
+		return err
+	}
+	err = stream.Send(&pb.LaunchRequest{Control: &pb.LaunchRequest_Start_{Start: &pb.LaunchRequest_Start{
+		BundleId:            bundleID,
+		ForegroundIfRunning: foregroundIfRunning,
+	}}})
+	if err != nil {
+		return err
+	}
+	if _, err := stream.Recv(); err != nil && err != io.EOF {
+		return err
+	}
+	return stream.CloseSend()
+}
+
+func (c *grpcCompanion) Terminate(ctx context.Context, bundleID string) error {
+	_, err := c.client.Terminate(ctx, &pb.TerminateRequest{BundleId: bundleID})
+	return err
+}
+
+func (c *grpcCompanion) Uninstall(ctx context.Context, bundleID string) error {
+	_, err := c.client.Uninstall(ctx, &pb.UninstallRequest{BundleId: bundleID})
+	return err
+}
+
+func (c *grpcCompanion) ListApps(ctx context.Context) ([]InstalledApp, error) {
+	resp, err := c.client.ListApps(ctx, &pb.ListAppsRequest{})
+	if err != nil {
+		return nil, err
+	}
+	apps := make([]InstalledApp, 0, len(resp.GetApps()))
+	for _, a := range resp.GetApps() {
+		apps = append(apps, InstalledApp{
+			BundleID:          a.GetBundleId(),
+			Name:              a.GetName(),
+			InstallType:       a.GetInstallType(),
+			ProcessState:      processStateFromProto(a.GetProcessState()),
+			Debuggable:        a.GetDebuggable(),
+			ProcessIdentifier: a.GetProcessIdentifier(),
+		})
+	}
+	return apps, nil
+}
+
+// installChunkBytes keeps each install payload frame comfortably under the
+// companion's 16MiB incoming-message cap.
+const installChunkBytes = 4 * 1024 * 1024
+
+func (c *grpcCompanion) Install(ctx context.Context, appPath string) error {
+	info, err := os.Stat(appPath)
+	if err != nil {
+		return err
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("install: %s is not an app bundle directory", appPath)
+	}
+
+	stream, err := c.client.Install(ctx)
+	if err != nil {
+		return err
+	}
+
+	// First message sets the destination, then the payload carries the bundle
+	// as a gzip-compressed tar archive the companion unpacks.
+	if err := stream.Send(&pb.InstallRequest{Value: &pb.InstallRequest_Destination_{
+		Destination: pb.InstallRequest_APP,
+	}}); err != nil {
+		return err
+	}
+
+	archive, err := tarGzipDirectory(appPath)
+	if err != nil {
+		return err
+	}
+	// The companion caps incoming messages at 16MiB, so the archive streams in
+	// chunks; the companion concatenates consecutive data payloads.
+	for _, chunk := range payloadChunks(archive, installChunkBytes) {
+		if err := stream.Send(&pb.InstallRequest{Value: &pb.InstallRequest_Payload{
+			Payload: &pb.Payload{Source: &pb.Payload_Data{Data: chunk}},
+		}}); err != nil {
+			return err
+		}
+	}
+
+	if err := stream.CloseSend(); err != nil {
+		return err
+	}
+	for {
+		if _, err := stream.Recv(); err != nil {
+			if err == io.EOF {
+				return nil
+			}
+			return err
+		}
+	}
+}
+
+// payloadChunks splits data into consecutive slices of at most chunkBytes.
+func payloadChunks(data []byte, chunkBytes int) [][]byte {
+	var chunks [][]byte
+	for offset := 0; offset < len(data); offset += chunkBytes {
+		end := min(offset+chunkBytes, len(data))
+		chunks = append(chunks, data[offset:end])
+	}
+	return chunks
+}
+
+// tarGzipDirectory packs dir into a gzip-compressed tar archive. Entry paths are
+// relative to the parent of dir so the bundle directory itself is preserved.
+func tarGzipDirectory(dir string) ([]byte, error) {
+	var buffer bytes.Buffer
+	gzipWriter := gzip.NewWriter(&buffer)
+	tarWriter := tar.NewWriter(gzipWriter)
+
+	base := filepath.Dir(dir)
+	walkErr := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		relative, err := filepath.Rel(base, path)
+		if err != nil {
+			return err
+		}
+		header, err := tar.FileInfoHeader(info, "")
+		if err != nil {
+			return err
+		}
+		header.Name = filepath.ToSlash(relative)
+		if err := tarWriter.WriteHeader(header); err != nil {
+			return err
+		}
+		if info.IsDir() {
+			return nil
+		}
+		file, err := os.Open(path)
+		if err != nil {
+			return err
+		}
+		defer file.Close()
+		_, err = io.Copy(tarWriter, file)
+		return err
+	})
+	if walkErr != nil {
+		return nil, walkErr
+	}
+	if err := tarWriter.Close(); err != nil {
+		return nil, err
+	}
+	if err := gzipWriter.Close(); err != nil {
+		return nil, err
+	}
+	return buffer.Bytes(), nil
+}

internal/driver/ioscompanion/transport/grpc_test.go

@@ -0,0 +1,158 @@
+package transport
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	pb "github.com/priyanshujain/sanderling/internal/driver/ioscompanion/companionpb"
+)
+
+// grpcCompanion must satisfy Companion.
+var _ Companion = (*grpcCompanion)(nil)
+
+func TestDialReturnsCompanion(t *testing.T) {
+	companion, err := Dial("127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("Dial: %v", err)
+	}
+	defer companion.Close()
+	if companion == nil {
+		t.Fatal("Dial returned nil companion")
+	}
+}
+
+func TestProcessStateFromProto(t *testing.T) {
+	cases := []struct {
+		in   pb.InstalledAppInfo_AppProcessState
+		want ProcessState
+	}{
+		{pb.InstalledAppInfo_RUNNING, ProcessStateRunning},
+		{pb.InstalledAppInfo_NOT_RUNNING, ProcessStateNotRunning},
+		{pb.InstalledAppInfo_UNKNOWN, ProcessStateUnknown},
+	}
+	for _, c := range cases {
+		if got := processStateFromProto(c.in); got != c.want {
+			t.Errorf("processStateFromProto(%v) = %v, want %v", c.in, got, c.want)
+		}
+	}
+}
+
+func TestScreenDescriptionFrom(t *testing.T) {
+	resp := &pb.TargetDescriptionResponse{
+		TargetDescription: &pb.TargetDescription{
+			ScreenDimensions: &pb.ScreenDimensions{
+				Width:        828,
+				Height:       1792,
+				Density:      2,
+				WidthPoints:  414,
+				HeightPoints: 896,
+			},
+		},
+	}
+	got := screenDescriptionFrom(resp)
+	want := ScreenDescription{WidthPoints: 414, HeightPoints: 896, Scale: 2}
+	if got != want {
+		t.Errorf("screenDescriptionFrom = %+v, want %+v", got, want)
+	}
+}
+
+func TestScreenDescriptionFromNilSafe(t *testing.T) {
+	if got := screenDescriptionFrom(&pb.TargetDescriptionResponse{}); got != (ScreenDescription{}) {
+		t.Errorf("screenDescriptionFrom(empty) = %+v, want zero", got)
+	}
+}
+
+func TestTarGzipDirectory(t *testing.T) {
+	root := t.TempDir()
+	bundle := filepath.Join(root, "Sample.app")
+	if err := os.MkdirAll(filepath.Join(bundle, "PlugIns"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(bundle, "Info.plist"), []byte("plist"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(bundle, "PlugIns", "ext"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	archive, err := tarGzipDirectory(bundle)
+	if err != nil {
+		t.Fatalf("tarGzipDirectory: %v", err)
+	}
+
+	names := tarEntryNames(t, archive)
+	want := map[string]bool{
+		"Sample.app":             true,
+		"Sample.app/Info.plist":  true,
+		"Sample.app/PlugIns":     true,
+		"Sample.app/PlugIns/ext": true,
+	}
+	for name := range want {
+		if !names[name] {
+			t.Errorf("archive missing entry %q; got %v", name, names)
+		}
+	}
+}
+
+func tarEntryNames(t *testing.T, archive []byte) map[string]bool {
+	t.Helper()
+	gzipReader, err := gzip.NewReader(bytes.NewReader(archive))
+	if err != nil {
+		t.Fatalf("gzip reader: %v", err)
+	}
+	defer gzipReader.Close()
+	tarReader := tar.NewReader(gzipReader)
+	names := map[string]bool{}
+	for {
+		header, err := tarReader.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatalf("tar next: %v", err)
+		}
+		names[filepath.ToSlash(filepath.Clean(header.Name))] = true
+	}
+	return names
+}
+
+func TestPayloadChunks(t *testing.T) {
+	cases := []struct {
+		name       string
+		dataLength int
+		chunkBytes int
+		wantSizes  []int
+	}{
+		{name: "empty", dataLength: 0, chunkBytes: 4, wantSizes: nil},
+		{name: "under one chunk", dataLength: 3, chunkBytes: 4, wantSizes: []int{3}},
+		{name: "exact multiple", dataLength: 8, chunkBytes: 4, wantSizes: []int{4, 4}},
+		{name: "remainder", dataLength: 10, chunkBytes: 4, wantSizes: []int{4, 4, 2}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			data := make([]byte, c.dataLength)
+			for i := range data {
+				data[i] = byte(i)
+			}
+			chunks := payloadChunks(data, c.chunkBytes)
+			if len(chunks) != len(c.wantSizes) {
+				t.Fatalf("got %d chunks, want %d", len(chunks), len(c.wantSizes))
+			}
+			var rejoined []byte
+			for i, chunk := range chunks {
+				if len(chunk) != c.wantSizes[i] {
+					t.Fatalf("chunk %d size %d, want %d", i, len(chunk), c.wantSizes[i])
+				}
+				rejoined = append(rejoined, chunk...)
+			}
+			if !bytes.Equal(rejoined, data) {
+				t.Fatal("rejoined chunks differ from input")
+			}
+		})
+	}
+}

internal/driver/ioscompanion/transport/hid.go

@@ -0,0 +1,63 @@
+package transport
+
+// HIDEventKind discriminates the neutral HID event variants.
+type HIDEventKind int
+
+const (
+	HIDKindTouchDown HIDEventKind = iota
+	HIDKindTouchUp
+	HIDKindKeyDown
+	HIDKindKeyUp
+	HIDKindDelay
+	HIDKindSwipe
+)
+
+// HIDEvent is one input event in a HID stream, expressed in transport-neutral
+// terms so each companion transport encodes it for its own wire format. Build
+// one with a builder below; only the fields for the event's kind are set.
+type HIDEvent struct {
+	Kind HIDEventKind
+
+	// X, Y is the touch point for TouchDown and TouchUp.
+	X, Y float64
+
+	// Usage is the USB HID usage identifier for KeyDown and KeyUp.
+	Usage uint32
+
+	// Milliseconds is the pause length for Delay.
+	Milliseconds float64
+
+	// FromX through Seconds describe a Swipe.
+	FromX, FromY float64
+	ToX, ToY     float64
+	Seconds      float64
+}
+
+// TouchDown presses a finger down at screen point (x, y).
+func TouchDown(x, y float64) HIDEvent { return HIDEvent{Kind: HIDKindTouchDown, X: x, Y: y} }
+
+// TouchUp lifts the finger at screen point (x, y).
+func TouchUp(x, y float64) HIDEvent { return HIDEvent{Kind: HIDKindTouchUp, X: x, Y: y} }
+
+// KeyDown presses the key with the given USB HID usage identifier.
+func KeyDown(usage uint32) HIDEvent { return HIDEvent{Kind: HIDKindKeyDown, Usage: usage} }
+
+// KeyUp releases the key with the given USB HID usage identifier.
+func KeyUp(usage uint32) HIDEvent { return HIDEvent{Kind: HIDKindKeyUp, Usage: usage} }
+
+// Delay pauses the HID stream for the given duration.
+func Delay(milliseconds float64) HIDEvent {
+	return HIDEvent{Kind: HIDKindDelay, Milliseconds: milliseconds}
+}
+
+// SwipeEvent drags from (fromX, fromY) to (toX, toY) over durationSeconds.
+func SwipeEvent(fromX, fromY, toX, toY float64, durationSeconds float64) HIDEvent {
+	return HIDEvent{
+		Kind:    HIDKindSwipe,
+		FromX:   fromX,
+		FromY:   fromY,
+		ToX:     toX,
+		ToY:     toY,
+		Seconds: durationSeconds,
+	}
+}

internal/driver/ioscompanion/transport/hid_test.go

@@ -0,0 +1,137 @@
+package transport
+
+import (
+	"testing"
+
+	pb "github.com/priyanshujain/sanderling/internal/driver/ioscompanion/companionpb"
+)
+
+func TestBuildersSetKindAndFields(t *testing.T) {
+	cases := []struct {
+		name  string
+		event HIDEvent
+		want  HIDEvent
+	}{
+		{"touch down", TouchDown(12, 34), HIDEvent{Kind: HIDKindTouchDown, X: 12, Y: 34}},
+		{"touch up", TouchUp(12, 34), HIDEvent{Kind: HIDKindTouchUp, X: 12, Y: 34}},
+		{"key down", KeyDown(225), HIDEvent{Kind: HIDKindKeyDown, Usage: 225}},
+		{"key up", KeyUp(225), HIDEvent{Kind: HIDKindKeyUp, Usage: 225}},
+		{"delay", Delay(250), HIDEvent{Kind: HIDKindDelay, Milliseconds: 250}},
+		{"swipe", SwipeEvent(1, 2, 3, 4, 0.5), HIDEvent{
+			Kind: HIDKindSwipe, FromX: 1, FromY: 2, ToX: 3, ToY: 4, Seconds: 0.5,
+		}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if c.event != c.want {
+				t.Errorf("event = %+v, want %+v", c.event, c.want)
+			}
+		})
+	}
+}
+
+func TestTouchEventsToProto(t *testing.T) {
+	cases := []struct {
+		name      string
+		event     HIDEvent
+		direction pb.HIDEvent_HIDDirection
+	}{
+		{"down", TouchDown(12, 34), pb.HIDEvent_DOWN},
+		{"up", TouchUp(12, 34), pb.HIDEvent_UP},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			message, err := hidEventToProto(c.event)
+			if err != nil {
+				t.Fatalf("hidEventToProto: %v", err)
+			}
+			press := message.GetPress()
+			if press == nil {
+				t.Fatalf("expected press event, got %#v", message.GetEvent())
+			}
+			if press.GetDirection() != c.direction {
+				t.Errorf("direction = %v, want %v", press.GetDirection(), c.direction)
+			}
+			touch := press.GetAction().GetTouch()
+			if touch == nil {
+				t.Fatalf("expected touch action")
+			}
+			if got := touch.GetPoint(); got.GetX() != 12 || got.GetY() != 34 {
+				t.Errorf("point = (%v, %v), want (12, 34)", got.GetX(), got.GetY())
+			}
+		})
+	}
+}
+
+func TestKeyEventsToProto(t *testing.T) {
+	cases := []struct {
+		name      string
+		event     HIDEvent
+		direction pb.HIDEvent_HIDDirection
+	}{
+		{"down", KeyDown(225), pb.HIDEvent_DOWN},
+		{"up", KeyUp(225), pb.HIDEvent_UP},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			message, err := hidEventToProto(c.event)
+			if err != nil {
+				t.Fatalf("hidEventToProto: %v", err)
+			}
+			press := message.GetPress()
+			if press == nil {
+				t.Fatalf("expected press event")
+			}
+			if press.GetDirection() != c.direction {
+				t.Errorf("direction = %v, want %v", press.GetDirection(), c.direction)
+			}
+			key := press.GetAction().GetKey()
+			if key == nil {
+				t.Fatalf("expected key action")
+			}
+			if key.GetKeycode() != 225 {
+				t.Errorf("keycode = %d, want 225", key.GetKeycode())
+			}
+		})
+	}
+}
+
+func TestDelayToProtoConvertsToSeconds(t *testing.T) {
+	message, err := hidEventToProto(Delay(250))
+	if err != nil {
+		t.Fatalf("hidEventToProto: %v", err)
+	}
+	delay := message.GetDelay()
+	if delay == nil {
+		t.Fatalf("expected delay event")
+	}
+	if delay.GetDuration() != 0.25 {
+		t.Errorf("duration = %v seconds, want 0.25", delay.GetDuration())
+	}
+}
+
+func TestSwipeEventToProto(t *testing.T) {
+	message, err := hidEventToProto(SwipeEvent(1, 2, 3, 4, 0.5))
+	if err != nil {
+		t.Fatalf("hidEventToProto: %v", err)
+	}
+	swipe := message.GetSwipe()
+	if swipe == nil {
+		t.Fatalf("expected swipe event")
+	}
+	if s := swipe.GetStart(); s.GetX() != 1 || s.GetY() != 2 {
+		t.Errorf("start = (%v, %v), want (1, 2)", s.GetX(), s.GetY())
+	}
+	if e := swipe.GetEnd(); e.GetX() != 3 || e.GetY() != 4 {
+		t.Errorf("end = (%v, %v), want (3, 4)", e.GetX(), e.GetY())
+	}
+	if swipe.GetDuration() != 0.5 {
+		t.Errorf("duration = %v, want 0.5", swipe.GetDuration())
+	}
+}
+
+func TestUnknownKindToProtoErrors(t *testing.T) {
+	if _, err := hidEventToProto(HIDEvent{Kind: HIDEventKind(99)}); err == nil {
+		t.Fatal("expected error for unknown event kind")
+	}
+}

internal/driver/ioscompanion/transport/integration_test.go

@@ -0,0 +1,105 @@
+package transport
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"os"
+	"os/exec"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestIntegrationAccessibilityInfo spawns a local companion against a booted
+// simulator and exercises a real AccessibilityInfo call. It is gated behind
+// SANDERLING_IOS_INTEGRATION so it never runs by default.
+func TestIntegrationAccessibilityInfo(t *testing.T) {
+	if os.Getenv("SANDERLING_IOS_INTEGRATION") == "" {
+		t.Skip("set SANDERLING_IOS_INTEGRATION=1 to run the integration smoke test")
+	}
+
+	udid := bootedSimulatorUDID(t)
+	port := freePort(t)
+
+	companionBinary := "/opt/homebrew/bin/idb_companion"
+	command := exec.Command(companionBinary, "--udid", udid, "--grpc-port", strconv.Itoa(port))
+	if err := command.Start(); err != nil {
+		t.Fatalf("start companion: %v", err)
+	}
+	defer func() {
+		_ = command.Process.Kill()
+		_, _ = command.Process.Wait()
+	}()
+
+	address := net.JoinHostPort("127.0.0.1", strconv.Itoa(port))
+	waitForListener(t, address)
+
+	companion, err := Dial(address)
+	if err != nil {
+		t.Fatalf("Dial: %v", err)
+	}
+	defer companion.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	info, err := companion.AccessibilityInfo(ctx)
+	if err != nil {
+		t.Fatalf("AccessibilityInfo: %v", err)
+	}
+	if strings.TrimSpace(info) == "" {
+		t.Fatal("AccessibilityInfo returned empty json")
+	}
+}
+
+func bootedSimulatorUDID(t *testing.T) string {
+	t.Helper()
+	output, err := exec.Command("xcrun", "simctl", "list", "devices", "booted", "--json").Output()
+	if err != nil {
+		t.Fatalf("simctl list: %v", err)
+	}
+	var parsed struct {
+		Devices map[string][]struct {
+			UDID  string `json:"udid"`
+			State string `json:"state"`
+		} `json:"devices"`
+	}
+	if err := json.Unmarshal(output, &parsed); err != nil {
+		t.Fatalf("parse simctl json: %v", err)
+	}
+	for _, devices := range parsed.Devices {
+		for _, device := range devices {
+			if device.State == "Booted" {
+				return device.UDID
+			}
+		}
+	}
+	t.Skip("no booted simulator available")
+	return ""
+}
+
+func freePort(t *testing.T) int {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("reserve port: %v", err)
+	}
+	port := listener.Addr().(*net.TCPAddr).Port
+	_ = listener.Close()
+	return port
+}
+
+func waitForListener(t *testing.T, address string) {
+	t.Helper()
+	deadline := time.Now().Add(20 * time.Second)
+	for time.Now().Before(deadline) {
+		conn, err := net.DialTimeout("tcp", address, time.Second)
+		if err == nil {
+			_ = conn.Close()
+			return
+		}
+		time.Sleep(200 * time.Millisecond)
+	}
+	t.Fatalf("companion did not listen on %s", address)
+}

internal/driver/ioscompanion/transport/runner.go

@@ -0,0 +1,342 @@
+package transport
+
+import (
+	"bufio"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"os/exec"
+	"sync"
+	"time"
+)
+
+// deadlineImmediate is a deadline already in the past, used to interrupt a
+// blocked read or write when the context is cancelled.
+var deadlineImmediate = time.Unix(1, 0)
+
+// runnerCompanion speaks newline-delimited JSON over a single persistent TCP
+// connection to the in-simulator runner. One request is in flight at a time:
+// the mutex serializes call/response pairs over the shared connection.
+type runnerCompanion struct {
+	uniqueDeviceIdentifier string
+	bundleID               string
+	address                string
+
+	mutex  sync.Mutex
+	conn   net.Conn
+	reader *bufio.Reader
+	nextID int
+
+	// dirty marks the connection desynced: a call was interrupted before its
+	// response was read, so the next call reconnects to the still-running
+	// server instead of misreading the stale response.
+	dirty bool
+}
+
+// DialRunner opens one persistent TCP connection to the simulator runner at
+// address and returns a Companion that also implements TextEditor. The
+// uniqueDeviceIdentifier targets simctl shell-outs; bundleID is the app the
+// snapshot and app-state queries default to.
+func DialRunner(address, uniqueDeviceIdentifier, bundleID string) (Companion, error) {
+	conn, err := net.Dial("tcp", address)
+	if err != nil {
+		return nil, fmt.Errorf("runner transport: %w: dial %s: %v", ErrCompanionUnavailable, address, err)
+	}
+	return &runnerCompanion{
+		uniqueDeviceIdentifier: uniqueDeviceIdentifier,
+		bundleID:               bundleID,
+		address:                address,
+		conn:                   conn,
+		reader:                 bufio.NewReader(conn),
+	}, nil
+}
+
+func (c *runnerCompanion) Close() error { return c.conn.Close() }
+
+// runnerRequest and runnerResponse are the wire envelopes. A response carries
+// either result or error, never both.
+type runnerRequest struct {
+	ID     int            `json:"id"`
+	Method string         `json:"method"`
+	Params map[string]any `json:"params"`
+}
+
+type runnerResponse struct {
+	ID     int             `json:"id"`
+	Result json.RawMessage `json:"result"`
+	Error  string          `json:"error"`
+}
+
+// call sends one request and returns its result payload. Transport-level
+// failures wrap ErrCompanionUnavailable; a server-reported error does not.
+func (c *runnerCompanion) call(ctx context.Context, method string, params map[string]any) (json.RawMessage, error) {
+	c.mutex.Lock()
+	defer c.mutex.Unlock()
+
+	if c.dirty {
+		if err := c.reconnect(); err != nil {
+			return nil, fmt.Errorf("runner transport: %w: reconnect: %v", ErrCompanionUnavailable, err)
+		}
+	}
+
+	if params == nil {
+		params = map[string]any{}
+	}
+	c.nextID++
+	id := c.nextID
+
+	// A blocked read or write cannot observe context cancellation directly, so
+	// AfterFunc trips an immediate deadline to interrupt it. The deadline is
+	// cleared once the call returns so the next call starts fresh.
+	stop := context.AfterFunc(ctx, func() {
+		c.conn.SetDeadline(deadlineImmediate)
+	})
+	// Clearing the deadline must happen after stop() so a late-firing AfterFunc
+	// cannot re-arm the deadline once the call has completed. Defers run LIFO.
+	defer c.conn.SetDeadline(time.Time{})
+	defer stop()
+	if deadline, ok := ctx.Deadline(); ok {
+		c.conn.SetDeadline(deadline)
+	}
+
+	payload, err := json.Marshal(runnerRequest{ID: id, Method: method, Params: params})
+	if err != nil {
+		return nil, fmt.Errorf("runner transport: %w: marshal %s request: %v", ErrCompanionUnavailable, method, err)
+	}
+	payload = append(payload, '\n')
+	if _, err := c.conn.Write(payload); err != nil {
+		return nil, c.wrapTransport(ctx, "write", method, err)
+	}
+
+	line, err := c.reader.ReadBytes('\n')
+	if err != nil {
+		return nil, c.wrapTransport(ctx, "read", method, err)
+	}
+
+	var response runnerResponse
+	if err := json.Unmarshal(line, &response); err != nil {
+		return nil, fmt.Errorf("runner transport: %w: decode %s response: %v", ErrCompanionUnavailable, method, err)
+	}
+	if response.ID != id {
+		return nil, fmt.Errorf("runner transport: %w: response id %d does not match request id %d", ErrCompanionUnavailable, response.ID, id)
+	}
+	if response.Error != "" {
+		return nil, fmt.Errorf("runner %s: %s", method, response.Error)
+	}
+	return response.Result, nil
+}
+
+// wrapTransport classifies a read/write failure. A caller-imposed cancel or
+// deadline is the caller's slowness budget, not a connection loss, so it does
+// not carry the unavailable sentinel: a child restart would not make the call
+// faster. The connection's own deadline is only ever set from the caller's
+// context, so a deadline-exceeded network error is the same budget expiry
+// even when it beats the context's done flag by a hair. Either way the
+// connection is desynced and reconnects on the next call.
+func (c *runnerCompanion) wrapTransport(ctx context.Context, stage, method string, err error) error {
+	c.dirty = true
+	if ctxErr := ctx.Err(); ctxErr != nil {
+		return fmt.Errorf("runner %s interrupted (%s): %w", method, stage, ctxErr)
+	}
+	if errors.Is(err, os.ErrDeadlineExceeded) {
+		return fmt.Errorf("runner %s interrupted (%s): %w", method, stage, err)
+	}
+	return fmt.Errorf("runner transport: %w: %s %s: %v", ErrCompanionUnavailable, stage, method, err)
+}
+
+// reconnect replaces the desynced connection with a fresh one to the same
+// still-running server.
+func (c *runnerCompanion) reconnect() error {
+	_ = c.conn.Close()
+	conn, err := net.Dial("tcp", c.address)
+	if err != nil {
+		return err
+	}
+	c.conn = conn
+	c.reader = bufio.NewReader(conn)
+	c.dirty = false
+	return nil
+}
+
+func (c *runnerCompanion) AccessibilityInfo(ctx context.Context) (string, error) {
+	result, err := c.call(ctx, "snapshot", map[string]any{"bundleId": c.bundleID})
+	if err != nil {
+		return "", err
+	}
+	var payload struct {
+		Elements []json.RawMessage `json:"elements"`
+	}
+	if err := json.Unmarshal(result, &payload); err != nil {
+		return "", fmt.Errorf("runner transport: %w: decode snapshot elements: %v", ErrCompanionUnavailable, err)
+	}
+	elements, err := json.Marshal(payload.Elements)
+	if err != nil {
+		return "", fmt.Errorf("runner transport: %w: re-marshal snapshot elements: %v", ErrCompanionUnavailable, err)
+	}
+	return string(elements), nil
+}
+
+func (c *runnerCompanion) Describe(ctx context.Context) (ScreenDescription, error) {
+	result, err := c.call(ctx, "describe", nil)
+	if err != nil {
+		return ScreenDescription{}, err
+	}
+	var payload struct {
+		WidthPoints  int     `json:"widthPoints"`
+		HeightPoints int     `json:"heightPoints"`
+		Scale        float64 `json:"scale"`
+	}
+	if err := json.Unmarshal(result, &payload); err != nil {
+		return ScreenDescription{}, fmt.Errorf("runner transport: %w: decode describe response: %v", ErrCompanionUnavailable, err)
+	}
+	return ScreenDescription{
+		WidthPoints:  payload.WidthPoints,
+		HeightPoints: payload.HeightPoints,
+		Scale:        payload.Scale,
+	}, nil
+}
+
+func (c *runnerCompanion) SendHID(ctx context.Context, events ...HIDEvent) error {
+	encoded := make([]map[string]any, 0, len(events))
+	for _, event := range events {
+		object, err := hidEventToObject(event)
+		if err != nil {
+			return err
+		}
+		encoded = append(encoded, object)
+	}
+	_, err := c.call(ctx, "gesture", map[string]any{"events": encoded})
+	return err
+}
+
+// hidEventToObject encodes a neutral HID event as a runner gesture event. The
+// runner edits text natively, so keyboard HID events are rejected with an
+// ordinary error rather than a connection-level one.
+func hidEventToObject(event HIDEvent) (map[string]any, error) {
+	switch event.Kind {
+	case HIDKindTouchDown:
+		return map[string]any{"kind": "touchDown", "x": event.X, "y": event.Y}, nil
+	case HIDKindTouchUp:
+		return map[string]any{"kind": "touchUp", "x": event.X, "y": event.Y}, nil
+	case HIDKindDelay:
+		return map[string]any{"kind": "delay", "milliseconds": event.Milliseconds}, nil
+	case HIDKindSwipe:
+		return map[string]any{
+			"kind":    "swipe",
+			"fromX":   event.FromX,
+			"fromY":   event.FromY,
+			"toX":     event.ToX,
+			"toY":     event.ToY,
+			"seconds": event.Seconds,
+		}, nil
+	case HIDKindKeyDown, HIDKindKeyUp:
+		return nil, errors.New("runner companion does not synthesize keyboard HID events; route text through the text editor")
+	}
+	return nil, fmt.Errorf("unknown HID event kind %d", event.Kind)
+}
+
+func (c *runnerCompanion) Screenshot(ctx context.Context) ([]byte, string, error) {
+	result, err := c.call(ctx, "screenshot", nil)
+	if err != nil {
+		return nil, "", err
+	}
+	var payload struct {
+		PNGBase64 string `json:"pngBase64"`
+	}
+	if err := json.Unmarshal(result, &payload); err != nil {
+		return nil, "", fmt.Errorf("runner transport: %w: decode screenshot response: %v", ErrCompanionUnavailable, err)
+	}
+	data, err := base64.StdEncoding.DecodeString(payload.PNGBase64)
+	if err != nil {
+		return nil, "", fmt.Errorf("runner transport: %w: decode screenshot png: %v", ErrCompanionUnavailable, err)
+	}
+	return data, "png", nil
+}
+
+func (c *runnerCompanion) Launch(ctx context.Context, bundleID string, foregroundIfRunning bool) error {
+	_, err := c.call(ctx, "launch", map[string]any{
+		"bundleId":            bundleID,
+		"foregroundIfRunning": foregroundIfRunning,
+	})
+	return err
+}
+
+func (c *runnerCompanion) Terminate(ctx context.Context, bundleID string) error {
+	_, err := c.call(ctx, "terminate", map[string]any{"bundleId": bundleID})
+	return err
+}
+
+func (c *runnerCompanion) ListApps(ctx context.Context) ([]InstalledApp, error) {
+	result, err := c.call(ctx, "appState", map[string]any{"bundleId": c.bundleID})
+	if err != nil {
+		return nil, err
+	}
+	var payload struct {
+		State string `json:"state"`
+	}
+	if err := json.Unmarshal(result, &payload); err != nil {
+		return nil, fmt.Errorf("runner transport: %w: decode appState response: %v", ErrCompanionUnavailable, err)
+	}
+	return []InstalledApp{{
+		BundleID:     c.bundleID,
+		InstallType:  "user",
+		ProcessState: processStateFromAppState(payload.State),
+	}}, nil
+}
+
+func processStateFromAppState(state string) ProcessState {
+	switch state {
+	case "foreground", "background":
+		return ProcessStateRunning
+	case "notRunning":
+		return ProcessStateNotRunning
+	default:
+		return ProcessStateUnknown
+	}
+}
+
+// Install and Uninstall shell out to simctl. The driver does not call these
+// today; they complete the Companion interface.
+func (c *runnerCompanion) Install(ctx context.Context, appPath string) error {
+	command := exec.CommandContext(ctx, "xcrun", "simctl", "install", c.uniqueDeviceIdentifier, appPath)
+	if output, err := command.CombinedOutput(); err != nil {
+		return fmt.Errorf("simctl install: %v: %s", err, output)
+	}
+	return nil
+}
+
+func (c *runnerCompanion) Uninstall(ctx context.Context, bundleID string) error {
+	command := exec.CommandContext(ctx, "xcrun", "simctl", "uninstall", c.uniqueDeviceIdentifier, bundleID)
+	if output, err := command.CombinedOutput(); err != nil {
+		return fmt.Errorf("simctl uninstall: %v: %s", err, output)
+	}
+	return nil
+}
+
+func (c *runnerCompanion) InputText(ctx context.Context, text string) error {
+	return c.TypeText(ctx, text, true)
+}
+
+func (c *runnerCompanion) TypeText(ctx context.Context, text string, replace bool) error {
+	_, err := c.call(ctx, "typeText", map[string]any{"text": text, "replace": replace})
+	return err
+}
+
+func (c *runnerCompanion) EraseText(ctx context.Context, characterCount int) error {
+	_, err := c.call(ctx, "eraseText", map[string]any{"count": characterCount})
+	return err
+}
+
+func (c *runnerCompanion) PressKey(ctx context.Context, key string) error {
+	switch key {
+	case "enter", "return", "Enter", "Return":
+		_, err := c.call(ctx, "pressKey", map[string]any{"key": "return"})
+		return err
+	default:
+		return fmt.Errorf("runner companion cannot press key %q; only return is supported", key)
+	}
+}

internal/driver/ioscompanion/transport/runner_test.go

@@ -0,0 +1,556 @@
+package transport
+
+import (
+	"bufio"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"net"
+	"reflect"
+	"strconv"
+	"sync"
+	"testing"
+	"time"
+)
+
+var (
+	_ Companion  = (*runnerCompanion)(nil)
+	_ TextEditor = (*runnerCompanion)(nil)
+)
+
+// scriptedReply maps a method name to the raw JSON object the fake server writes
+// back as the "result" field. A method absent from the script gets an empty
+// object result.
+type scriptedReply map[string]string
+
+// fakeServer is an in-process runner stand-in. It accepts a single connection,
+// records every decoded request, and answers from a scripted table.
+type fakeServer struct {
+	listener net.Listener
+	address  string
+
+	mutex    sync.Mutex
+	requests []runnerRequest
+}
+
+func startFakeServer(t *testing.T, script scriptedReply) *fakeServer {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	server := &fakeServer{listener: listener, address: listener.Addr().String()}
+	go server.serve(script)
+	t.Cleanup(func() { listener.Close() })
+	return server
+}
+
+func (s *fakeServer) serve(script scriptedReply) {
+	conn, err := s.listener.Accept()
+	if err != nil {
+		return
+	}
+	defer conn.Close()
+	reader := bufio.NewReader(conn)
+	for {
+		line, err := reader.ReadBytes('\n')
+		if err != nil {
+			return
+		}
+		var request runnerRequest
+		if err := json.Unmarshal(line, &request); err != nil {
+			return
+		}
+		s.mutex.Lock()
+		s.requests = append(s.requests, request)
+		s.mutex.Unlock()
+
+		result := script[request.Method]
+		if result == "" {
+			result = "{}"
+		}
+		response := `{"id":` + strconv.Itoa(request.ID) + `,"result":` + result + "}\n"
+		if _, err := conn.Write([]byte(response)); err != nil {
+			return
+		}
+	}
+}
+
+func (s *fakeServer) recorded() []runnerRequest {
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+	out := make([]runnerRequest, len(s.requests))
+	copy(out, s.requests)
+	return out
+}
+
+func dialFake(t *testing.T, server *fakeServer, bundleID string) Companion {
+	t.Helper()
+	companion, err := DialRunner(server.address, "UDID-1234", bundleID)
+	if err != nil {
+		t.Fatalf("DialRunner: %v", err)
+	}
+	t.Cleanup(func() { companion.Close() })
+	return companion
+}
+
+func TestSnapshotReMarshalsElements(t *testing.T) {
+	server := startFakeServer(t, scriptedReply{
+		"snapshot": `{"elements":[{"role":"button"},{"role":"text"}]}`,
+	})
+	companion := dialFake(t, server, "com.example.app")
+
+	got, err := companion.AccessibilityInfo(context.Background())
+	if err != nil {
+		t.Fatalf("AccessibilityInfo: %v", err)
+	}
+	want := `[{"role":"button"},{"role":"text"}]`
+	if got != want {
+		t.Fatalf("elements = %s, want %s", got, want)
+	}
+
+	requests := server.recorded()
+	if len(requests) != 1 {
+		t.Fatalf("recorded %d requests, want 1", len(requests))
+	}
+	if requests[0].Method != "snapshot" {
+		t.Fatalf("method = %s, want snapshot", requests[0].Method)
+	}
+	if requests[0].Params["bundleId"] != "com.example.app" {
+		t.Fatalf("bundleId = %v, want com.example.app", requests[0].Params["bundleId"])
+	}
+}
+
+func TestGestureEncodesDoubleTapStream(t *testing.T) {
+	server := startFakeServer(t, nil)
+	companion := dialFake(t, server, "com.example.app")
+
+	err := companion.SendHID(context.Background(),
+		TouchDown(10, 20),
+		TouchUp(10, 20),
+		Delay(60),
+		TouchDown(10, 20),
+		TouchUp(10, 20),
+	)
+	if err != nil {
+		t.Fatalf("SendHID: %v", err)
+	}
+
+	requests := server.recorded()
+	if len(requests) != 1 || requests[0].Method != "gesture" {
+		t.Fatalf("requests = %+v, want one gesture", requests)
+	}
+	events, ok := requests[0].Params["events"].([]any)
+	if !ok {
+		t.Fatalf("events not an array: %T", requests[0].Params["events"])
+	}
+	want := []map[string]any{
+		{"kind": "touchDown", "x": 10.0, "y": 20.0},
+		{"kind": "touchUp", "x": 10.0, "y": 20.0},
+		{"kind": "delay", "milliseconds": 60.0},
+		{"kind": "touchDown", "x": 10.0, "y": 20.0},
+		{"kind": "touchUp", "x": 10.0, "y": 20.0},
+	}
+	if len(events) != len(want) {
+		t.Fatalf("got %d events, want %d", len(events), len(want))
+	}
+	for index, event := range events {
+		if !reflect.DeepEqual(event, map[string]any(want[index])) {
+			t.Fatalf("event %d = %v, want %v", index, event, want[index])
+		}
+	}
+}
+
+func TestSendHIDRejectsKeyEvents(t *testing.T) {
+	server := startFakeServer(t, nil)
+	companion := dialFake(t, server, "com.example.app")
+
+	err := companion.SendHID(context.Background(), KeyDown(4), KeyUp(4))
+	if err == nil {
+		t.Fatal("expected error for key HID events")
+	}
+	if errors.Is(err, ErrCompanionUnavailable) {
+		t.Fatalf("key rejection should not be a transport error: %v", err)
+	}
+	if requests := server.recorded(); len(requests) != 0 {
+		t.Fatalf("expected nothing sent, got %+v", requests)
+	}
+}
+
+func TestScreenshotBase64RoundTrip(t *testing.T) {
+	original := []byte{0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a}
+	encoded := base64.StdEncoding.EncodeToString(original)
+	server := startFakeServer(t, scriptedReply{
+		"screenshot": `{"pngBase64":"` + encoded + `"}`,
+	})
+	companion := dialFake(t, server, "com.example.app")
+
+	data, format, err := companion.Screenshot(context.Background())
+	if err != nil {
+		t.Fatalf("Screenshot: %v", err)
+	}
+	if format != "png" {
+		t.Fatalf("format = %s, want png", format)
+	}
+	if !reflect.DeepEqual(data, original) {
+		t.Fatalf("data = %v, want %v", data, original)
+	}
+}
+
+func TestDescribeMapsScreenDescription(t *testing.T) {
+	server := startFakeServer(t, scriptedReply{
+		"describe": `{"widthPoints":390,"heightPoints":844,"scale":3.0}`,
+	})
+	companion := dialFake(t, server, "com.example.app")
+
+	description, err := companion.Describe(context.Background())
+	if err != nil {
+		t.Fatalf("Describe: %v", err)
+	}
+	want := ScreenDescription{WidthPoints: 390, HeightPoints: 844, Scale: 3.0}
+	if description != want {
+		t.Fatalf("description = %+v, want %+v", description, want)
+	}
+}
+
+func TestTextEditorMethods(t *testing.T) {
+	server := startFakeServer(t, nil)
+	companion := dialFake(t, server, "com.example.app")
+	editor := companion.(TextEditor)
+
+	if err := editor.InputText(context.Background(), "hello"); err != nil {
+		t.Fatalf("InputText: %v", err)
+	}
+	if err := editor.EraseText(context.Background(), 3); err != nil {
+		t.Fatalf("EraseText: %v", err)
+	}
+	if err := editor.PressKey(context.Background(), "Enter"); err != nil {
+		t.Fatalf("PressKey: %v", err)
+	}
+
+	requests := server.recorded()
+	if len(requests) != 3 {
+		t.Fatalf("recorded %d requests, want 3", len(requests))
+	}
+	if requests[0].Method != "typeText" || requests[0].Params["text"] != "hello" || requests[0].Params["replace"] != true {
+		t.Fatalf("typeText request = %+v", requests[0])
+	}
+	if requests[1].Method != "eraseText" || requests[1].Params["count"] != 3.0 {
+		t.Fatalf("eraseText request = %+v", requests[1])
+	}
+	if requests[2].Method != "pressKey" || requests[2].Params["key"] != "return" {
+		t.Fatalf("pressKey request = %+v", requests[2])
+	}
+}
+
+func TestPressKeyRejectsUnknownKey(t *testing.T) {
+	server := startFakeServer(t, nil)
+	companion := dialFake(t, server, "com.example.app")
+	editor := companion.(TextEditor)
+
+	err := editor.PressKey(context.Background(), "home")
+	if err == nil {
+		t.Fatal("expected error for unsupported key")
+	}
+	if errors.Is(err, ErrCompanionUnavailable) {
+		t.Fatalf("unsupported key should not be a transport error: %v", err)
+	}
+	if requests := server.recorded(); len(requests) != 0 {
+		t.Fatalf("expected nothing sent, got %+v", requests)
+	}
+}
+
+func TestLaunchTerminateMapping(t *testing.T) {
+	server := startFakeServer(t, nil)
+	companion := dialFake(t, server, "com.example.app")
+
+	if err := companion.Launch(context.Background(), "com.example.target", true); err != nil {
+		t.Fatalf("Launch: %v", err)
+	}
+	if err := companion.Terminate(context.Background(), "com.example.target"); err != nil {
+		t.Fatalf("Terminate: %v", err)
+	}
+
+	requests := server.recorded()
+	if len(requests) != 2 {
+		t.Fatalf("recorded %d requests, want 2", len(requests))
+	}
+	if requests[0].Method != "launch" ||
+		requests[0].Params["bundleId"] != "com.example.target" ||
+		requests[0].Params["foregroundIfRunning"] != true {
+		t.Fatalf("launch request = %+v", requests[0])
+	}
+	if requests[1].Method != "terminate" || requests[1].Params["bundleId"] != "com.example.target" {
+		t.Fatalf("terminate request = %+v", requests[1])
+	}
+}
+
+func TestListAppsStateMapping(t *testing.T) {
+	cases := []struct {
+		state string
+		want  ProcessState
+	}{
+		{"foreground", ProcessStateRunning},
+		{"background", ProcessStateRunning},
+		{"notRunning", ProcessStateNotRunning},
+		{"unknown", ProcessStateUnknown},
+	}
+	for _, testCase := range cases {
+		server := startFakeServer(t, scriptedReply{
+			"appState": `{"state":"` + testCase.state + `"}`,
+		})
+		companion := dialFake(t, server, "com.example.app")
+
+		apps, err := companion.ListApps(context.Background())
+		if err != nil {
+			t.Fatalf("ListApps(%s): %v", testCase.state, err)
+		}
+		if len(apps) != 1 {
+			t.Fatalf("ListApps(%s) returned %d apps, want 1", testCase.state, len(apps))
+		}
+		app := apps[0]
+		if app.BundleID != "com.example.app" || app.InstallType != "user" {
+			t.Fatalf("app fields = %+v", app)
+		}
+		if app.ProcessState != testCase.want {
+			t.Fatalf("state %s -> %v, want %v", testCase.state, app.ProcessState, testCase.want)
+		}
+
+		requests := server.recorded()
+		if len(requests) != 1 || requests[0].Method != "appState" || requests[0].Params["bundleId"] != "com.example.app" {
+			t.Fatalf("appState request = %+v", requests)
+		}
+	}
+}
+
+func TestServerErrorIsNotSentinel(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	t.Cleanup(func() { listener.Close() })
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		reader := bufio.NewReader(conn)
+		line, err := reader.ReadBytes('\n')
+		if err != nil {
+			return
+		}
+		var request runnerRequest
+		json.Unmarshal(line, &request)
+		conn.Write([]byte(`{"id":` + strconv.Itoa(request.ID) + `,"error":"field not focused"}` + "\n"))
+	}()
+
+	companion, err := DialRunner(listener.Addr().String(), "UDID", "com.example.app")
+	if err != nil {
+		t.Fatalf("DialRunner: %v", err)
+	}
+	t.Cleanup(func() { companion.Close() })
+
+	_, err = companion.Describe(context.Background())
+	if err == nil {
+		t.Fatal("expected server error")
+	}
+	if errors.Is(err, ErrCompanionUnavailable) {
+		t.Fatalf("server error must not wrap the sentinel: %v", err)
+	}
+}
+
+func TestServerClosesMidCallIsSentinel(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	t.Cleanup(func() { listener.Close() })
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			return
+		}
+		// Read the request, then drop the connection without replying.
+		bufio.NewReader(conn).ReadBytes('\n')
+		conn.Close()
+	}()
+
+	companion, err := DialRunner(listener.Addr().String(), "UDID", "com.example.app")
+	if err != nil {
+		t.Fatalf("DialRunner: %v", err)
+	}
+	t.Cleanup(func() { companion.Close() })
+
+	_, err = companion.Describe(context.Background())
+	if err == nil {
+		t.Fatal("expected error when server closes mid-call")
+	}
+	if !errors.Is(err, ErrCompanionUnavailable) {
+		t.Fatalf("dropped connection must wrap the sentinel: %v", err)
+	}
+}
+
+func TestContextCancellationUnblocksCall(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	t.Cleanup(func() { listener.Close() })
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			return
+		}
+		// Accept and hold the connection open, never replying.
+		bufio.NewReader(conn).ReadBytes('\n')
+		<-make(chan struct{})
+	}()
+
+	companion, err := DialRunner(listener.Addr().String(), "UDID", "com.example.app")
+	if err != nil {
+		t.Fatalf("DialRunner: %v", err)
+	}
+	t.Cleanup(func() { companion.Close() })
+
+	ctx, cancel := context.WithCancel(context.Background())
+	time.AfterFunc(50*time.Millisecond, cancel)
+
+	done := make(chan error, 1)
+	go func() {
+		_, callErr := companion.Describe(ctx)
+		done <- callErr
+	}()
+
+	select {
+	case callErr := <-done:
+		if callErr == nil {
+			t.Fatal("expected cancellation error")
+		}
+		// A caller-imposed cancel is the caller's budget, not a connection
+		// loss: it must NOT wrap the sentinel, or a slow call would trigger a
+		// pointless child restart.
+		if !errors.Is(callErr, context.Canceled) {
+			t.Fatalf("cancellation error must carry the context error: %v", callErr)
+		}
+		if errors.Is(callErr, ErrCompanionUnavailable) {
+			t.Fatalf("cancellation error must not wrap the sentinel: %v", callErr)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("cancelled call did not return within 2s")
+	}
+}
+
+func TestInterruptedCallReconnectsOnNextCall(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	t.Cleanup(func() { listener.Close() })
+
+	// The server holds "describe" hostage and answers everything else, on
+	// every connection it accepts. A late reply to the interrupted request
+	// must never be misread by the following call.
+	accepted := make(chan net.Conn, 4)
+	go func() {
+		for {
+			conn, acceptErr := listener.Accept()
+			if acceptErr != nil {
+				return
+			}
+			accepted <- conn
+			go func(c net.Conn) {
+				reader := bufio.NewReader(c)
+				for {
+					line, readErr := reader.ReadBytes('\n')
+					if readErr != nil {
+						return
+					}
+					var request runnerRequest
+					if json.Unmarshal(line, &request) != nil {
+						return
+					}
+					if request.Method == "describe" {
+						continue
+					}
+					response := `{"id":` + strconv.Itoa(request.ID) + `,"result":{"ok":true}}` + "\n"
+					if _, writeErr := c.Write([]byte(response)); writeErr != nil {
+						return
+					}
+				}
+			}(conn)
+		}
+	}()
+
+	companion, err := DialRunner(listener.Addr().String(), "UDID", "com.example.app")
+	if err != nil {
+		t.Fatalf("DialRunner: %v", err)
+	}
+	t.Cleanup(func() { companion.Close() })
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	if _, err := companion.Describe(ctx); err == nil {
+		t.Fatal("expected the held call to time out")
+	}
+
+	// The next call must transparently reconnect and succeed.
+	if err := companion.Terminate(context.Background(), "com.example.app"); err != nil {
+		t.Fatalf("call after interrupt: %v", err)
+	}
+	if len(accepted) != 2 {
+		t.Fatalf("accepted %d connections, want 2 (reconnect)", len(accepted))
+	}
+}
+
+func TestResponseIDMismatchIsSentinel(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	t.Cleanup(func() { listener.Close() })
+	go func() {
+		conn, err := listener.Accept()
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		bufio.NewReader(conn).ReadBytes('\n')
+		// Reply with an id that cannot match any request.
+		conn.Write([]byte(`{"id":9999,"result":{}}` + "\n"))
+	}()
+
+	companion, err := DialRunner(listener.Addr().String(), "UDID", "com.example.app")
+	if err != nil {
+		t.Fatalf("DialRunner: %v", err)
+	}
+	t.Cleanup(func() { companion.Close() })
+
+	_, err = companion.Describe(context.Background())
+	if err == nil {
+		t.Fatal("expected id-mismatch error")
+	}
+	if !errors.Is(err, ErrCompanionUnavailable) {
+		t.Fatalf("id mismatch must wrap the sentinel: %v", err)
+	}
+}
+
+func TestTypeTextAppendsWithoutReplace(t *testing.T) {
+	server := startFakeServer(t, nil)
+	companion := dialFake(t, server, "com.example.app")
+	typer := companion.(TextTyper)
+
+	if err := typer.TypeText(context.Background(), "héllo 🌟", false); err != nil {
+		t.Fatalf("TypeText: %v", err)
+	}
+
+	requests := server.recorded()
+	if len(requests) != 1 {
+		t.Fatalf("recorded %d requests, want 1", len(requests))
+	}
+	request := requests[0]
+	if request.Method != "typeText" || request.Params["text"] != "héllo 🌟" || request.Params["replace"] != false {
+		t.Fatalf("typeText request = %+v", request)
+	}
+}

internal/driver/ioscompanion/transport/transport.go

@@ -0,0 +1,116 @@
+// Package transport is the only layer that touches the generated companion
+// gRPC stubs. Everything above it speaks the brand-free Companion interface,
+// so the companion binary stays swappable behind this boundary.
+package transport
+
+import (
+	"context"
+	"errors"
+
+	pb "github.com/priyanshujain/sanderling/internal/driver/ioscompanion/companionpb"
+)
+
+// Companion drives a single booted iOS simulator through the companion.
+// Callers own per-call deadlines by passing a context.
+type Companion interface {
+	// AccessibilityInfo returns the describe-all accessibility tree as the
+	// raw flat-format JSON string the companion emits.
+	AccessibilityInfo(ctx context.Context) (string, error)
+
+	// Describe reports the target's screen dimensions in points, along with
+	// the pixel scale when the companion supplies one.
+	Describe(ctx context.Context) (ScreenDescription, error)
+
+	// SendHID opens the HID stream, sends every event in order, then closes.
+	SendHID(ctx context.Context, events ...HIDEvent) error
+
+	// Screenshot captures the current screen, returning the encoded image
+	// bytes and the image format string the companion reports.
+	Screenshot(ctx context.Context) (imageData []byte, imageFormat string, err error)
+
+	// Launch brings the app to the foreground, starting it if needed.
+	Launch(ctx context.Context, bundleID string, foregroundIfRunning bool) error
+
+	// Terminate stops the running app with the given bundle identifier.
+	Terminate(ctx context.Context, bundleID string) error
+
+	// ListApps reports every installed app and its current process state.
+	ListApps(ctx context.Context) ([]InstalledApp, error)
+
+	// Install installs a .app bundle directory by streaming it to the
+	// companion.
+	Install(ctx context.Context, appPath string) error
+
+	// Uninstall removes the app with the given bundle identifier.
+	Uninstall(ctx context.Context, bundleID string) error
+
+	// Close releases the underlying connection.
+	Close() error
+}
+
+// TextEditor is an optional companion capability: the transport edits text
+// natively on the device instead of the driver composing keyboard HID streams.
+// The driver routes text input through it when the companion implements it.
+type TextEditor interface {
+	// InputText replaces the focused field's content with text.
+	InputText(ctx context.Context, text string) error
+
+	// EraseText deletes characterCount characters from the focused field.
+	EraseText(ctx context.Context, characterCount int) error
+
+	// PressKey presses the named logical key (currently only return/enter).
+	PressKey(ctx context.Context, key string) error
+}
+
+// TextTyper is an optional companion capability: the transport types text
+// natively into whatever holds keyboard focus. Unlike TextEditor it exposes
+// the replace flag, so a caller can clear the field through another channel
+// and append with replace false.
+type TextTyper interface {
+	TypeText(ctx context.Context, text string, replace bool) error
+}
+
+// ErrCompanionUnavailable marks a connection-level failure that a companion
+// restart can recover from. Transports wrap dropped-connection errors with it.
+var ErrCompanionUnavailable = errors.New("companion connection unavailable")
+
+// ScreenDescription carries the target screen geometry. Width and Height are
+// in points (the coordinate space HID events and the accessibility frames use).
+// Scale is the pixel-per-point density, or 0 when the companion did not report
+// one.
+type ScreenDescription struct {
+	WidthPoints  int
+	HeightPoints int
+	Scale        float64
+}
+
+// ProcessState mirrors the companion's notion of whether an app is running.
+type ProcessState int
+
+const (
+	ProcessStateUnknown ProcessState = iota
+	ProcessStateNotRunning
+	ProcessStateRunning
+)
+
+// InstalledApp describes one installed app. ProcessState and ProcessIdentifier
+// together answer whether the app is currently running and in the foreground.
+type InstalledApp struct {
+	BundleID          string
+	Name              string
+	InstallType       string
+	ProcessState      ProcessState
+	Debuggable        bool
+	ProcessIdentifier uint64
+}
+
+func processStateFromProto(s pb.InstalledAppInfo_AppProcessState) ProcessState {
+	switch s {
+	case pb.InstalledAppInfo_RUNNING:
+		return ProcessStateRunning
+	case pb.InstalledAppInfo_NOT_RUNNING:
+		return ProcessStateNotRunning
+	default:
+		return ProcessStateUnknown
+	}
+}