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/companionassets/embed.go

@@ -0,0 +1,140 @@
+// Package companionassets embeds the simulator companion binary and its
+// frameworks, and extracts the bundle to disk at runtime.
+package companionassets
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// companionBinaryName is the file name inside bin/ fixed by the vendored
+// layout. The binary resolves its frameworks through @rpath relative to this
+// path, so it must not be renamed.
+const companionBinaryName = "idb_companion"
+
+// EmbeddedSize returns the size in bytes of the embedded companion archive.
+func EmbeddedSize() int { return len(embeddedArchive) }
+
+// EmbeddedSHA256 returns the hex-encoded SHA-256 of the embedded archive.
+func EmbeddedSHA256() string {
+	sum := sha256.Sum256(embeddedArchive)
+	return hex.EncodeToString(sum[:])
+}
+
+// Extract unpacks the embedded companion archive into dir, preserving the
+// bin/ and Frameworks/ layout and any symlinks. A .sha256 marker next to the
+// extracted tree gates re-extraction: if it already matches, no rewrite
+// happens. Returns the absolute path to the companion binary.
+func Extract(dir string) (string, error) {
+	if len(embeddedArchive) == 0 {
+		return "", errors.New("companion: binary built without -tags withcompanion; rebuild with `make sanderling`")
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return "", fmt.Errorf("mkdir %s: %w", dir, err)
+	}
+
+	binaryPath, err := filepath.Abs(filepath.Join(dir, "bin", companionBinaryName))
+	if err != nil {
+		return "", err
+	}
+	checksumPath := filepath.Join(dir, "companion.sha256")
+	checksum := EmbeddedSHA256()
+
+	if existing, err := os.ReadFile(checksumPath); err == nil && string(existing) == checksum {
+		if _, err := os.Stat(binaryPath); err == nil {
+			return binaryPath, nil
+		}
+	}
+
+	if err := unpack(dir); err != nil {
+		return "", err
+	}
+	if err := os.Chmod(binaryPath, 0o755); err != nil {
+		return "", fmt.Errorf("chmod companion binary: %w", err)
+	}
+	if err := os.WriteFile(checksumPath, []byte(checksum), 0o644); err != nil {
+		return "", fmt.Errorf("write checksum: %w", err)
+	}
+	return binaryPath, nil
+}
+
+func unpack(dir string) error {
+	gzipReader, err := gzip.NewReader(bytes.NewReader(embeddedArchive))
+	if err != nil {
+		return fmt.Errorf("open companion archive: %w", err)
+	}
+	defer gzipReader.Close()
+
+	tarReader := tar.NewReader(gzipReader)
+	for {
+		header, err := tarReader.Next()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			return fmt.Errorf("read companion archive: %w", err)
+		}
+
+		if strings.HasPrefix(filepath.Base(header.Name), "._") {
+			continue
+		}
+
+		target, err := safeJoin(dir, header.Name)
+		if err != nil {
+			return err
+		}
+
+		switch header.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(target, 0o755); err != nil {
+				return err
+			}
+		case tar.TypeSymlink:
+			if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+				return err
+			}
+			os.Remove(target)
+			if err := os.Symlink(header.Linkname, target); err != nil {
+				return err
+			}
+		case tar.TypeReg:
+			if err := writeFile(target, tarReader, os.FileMode(header.Mode)); err != nil {
+				return err
+			}
+		}
+	}
+}
+
+func writeFile(path string, src io.Reader, mode os.FileMode) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	file, err := os.OpenFile(path, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, mode)
+	if err != nil {
+		return err
+	}
+	if _, err := io.Copy(file, src); err != nil {
+		file.Close()
+		return err
+	}
+	return file.Close()
+}
+
+// safeJoin rejects archive entries that would escape dir.
+func safeJoin(dir, name string) (string, error) {
+	target := filepath.Join(dir, name)
+	relative, err := filepath.Rel(dir, target)
+	if err != nil || relative == ".." || strings.HasPrefix(relative, ".."+string(os.PathSeparator)) {
+		return "", fmt.Errorf("archive entry escapes destination: %s", name)
+	}
+	return target, nil
+}

internal/driver/ioscompanion/companionassets/embed_real.go

@@ -0,0 +1,12 @@
+//go:build withcompanion
+
+package companionassets
+
+import _ "embed"
+
+//go:embed assets/companion-1.1.8.tar.gz
+var embeddedArchive []byte
+
+// IsPlaceholder reports whether the binary was built without the real
+// companion archive embedded. -tags withcompanion builds always return false.
+func IsPlaceholder() bool { return false }

internal/driver/ioscompanion/companionassets/embed_stub.go

@@ -0,0 +1,10 @@
+//go:build !withcompanion
+
+package companionassets
+
+var embeddedArchive []byte
+
+// IsPlaceholder reports whether the binary was built without the real
+// companion archive embedded. Build with `make sanderling` (which passes
+// -tags withcompanion) to embed the real companion bundle.
+func IsPlaceholder() bool { return true }

internal/driver/ioscompanion/companionassets/embed_stub_test.go

@@ -0,0 +1,27 @@
+//go:build !withcompanion
+
+package companionassets
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestStubBuild_IsPlaceholder(t *testing.T) {
+	if !IsPlaceholder() {
+		t.Error("default build (no -tags withcompanion) must report a placeholder")
+	}
+	if EmbeddedSize() != 0 {
+		t.Errorf("placeholder build must embed no archive, got %d bytes", EmbeddedSize())
+	}
+}
+
+func TestStubBuild_ExtractErrors(t *testing.T) {
+	_, err := Extract(t.TempDir())
+	if err == nil {
+		t.Fatal("Extract must fail when no archive is embedded")
+	}
+	if !strings.Contains(err.Error(), "withcompanion") {
+		t.Errorf("error should tell the user to rebuild with -tags withcompanion, got %v", err)
+	}
+}

internal/driver/ioscompanion/companionassets/embed_withcompanion_test.go

@@ -0,0 +1,146 @@
+//go:build withcompanion
+
+package companionassets
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestEmbeddedNonZero(t *testing.T) {
+	if EmbeddedSize() == 0 {
+		t.Errorf("expected embedded companion archive to be non-empty")
+	}
+	if IsPlaceholder() {
+		t.Errorf("withcompanion build should not be a placeholder")
+	}
+}
+
+func TestEmbeddedSHA256Matches(t *testing.T) {
+	sum := sha256.Sum256(embeddedArchive)
+	if hex.EncodeToString(sum[:]) != EmbeddedSHA256() {
+		t.Errorf("EmbeddedSHA256 does not match a fresh hash of the archive")
+	}
+}
+
+func TestExtract_WritesBinaryAndChecksum(t *testing.T) {
+	directory := t.TempDir()
+	path, err := Extract(directory)
+	if err != nil {
+		t.Fatal(err)
+	}
+	expected, err := filepath.Abs(filepath.Join(directory, "bin", companionBinaryName))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if path != expected {
+		t.Errorf("unexpected binary path: got %s want %s", path, expected)
+	}
+	checksum, err := os.ReadFile(filepath.Join(directory, "companion.sha256"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(checksum) != EmbeddedSHA256() {
+		t.Errorf("checksum file content wrong: %q", checksum)
+	}
+}
+
+func TestExtract_LayoutAndSymlinks(t *testing.T) {
+	directory := t.TempDir()
+	binaryPath, err := Extract(directory)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	info, err := os.Stat(binaryPath)
+	if err != nil {
+		t.Fatalf("companion binary missing: %v", err)
+	}
+	if info.Mode().Perm()&0o111 == 0 {
+		t.Errorf("companion binary is not executable, mode=%v", info.Mode())
+	}
+
+	frameworksDir := filepath.Join(directory, "Frameworks")
+	if stat, err := os.Stat(frameworksDir); err != nil || !stat.IsDir() {
+		t.Fatalf("Frameworks directory missing: %v", err)
+	}
+
+	expectedFrameworks := []string{
+		"FBControlCore.framework",
+		"FBDeviceControl.framework",
+		"FBSimulatorControl.framework",
+		"IDBCompanionUtilities.framework",
+		"IDBGRPCSwift.framework",
+		"XCTestBootstrap.framework",
+	}
+	for _, name := range expectedFrameworks {
+		if stat, err := os.Stat(filepath.Join(frameworksDir, name)); err != nil || !stat.IsDir() {
+			t.Errorf("expected framework %s missing: %v", name, err)
+		}
+	}
+
+	// The Versions/Current symlink must resolve to a real directory, proving
+	// symlinks survived extraction.
+	current := filepath.Join(frameworksDir, "FBControlCore.framework", "Versions", "Current")
+	linkInfo, err := os.Lstat(current)
+	if err != nil {
+		t.Fatalf("Versions/Current missing: %v", err)
+	}
+	if linkInfo.Mode()&os.ModeSymlink == 0 {
+		t.Errorf("Versions/Current is not a symlink")
+	}
+	resolved, err := os.Stat(current)
+	if err != nil || !resolved.IsDir() {
+		t.Errorf("Versions/Current does not resolve to a directory: %v", err)
+	}
+
+	// A runtime dylib that must be preserved inside FBControlCore Resources.
+	dylib := filepath.Join(frameworksDir, "FBControlCore.framework", "Versions", "A", "Resources", "libMaculator.dylib")
+	if _, err := os.Stat(dylib); err != nil {
+		t.Errorf("expected runtime dylib preserved: %v", err)
+	}
+}
+
+func TestExtract_ReusesWhenChecksumMatches(t *testing.T) {
+	directory := t.TempDir()
+	binaryPath, err := Extract(directory)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sentinel := []byte("SENTINEL-do-not-rewrite")
+	if err := os.WriteFile(binaryPath, sentinel, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := Extract(directory); err != nil {
+		t.Fatal(err)
+	}
+
+	after, err := os.ReadFile(binaryPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(after) != string(sentinel) {
+		t.Errorf("second extract rewrote the binary; reuse branch should have skipped extraction")
+	}
+}
+
+func TestExtract_RewritesIfChecksumMissing(t *testing.T) {
+	directory := t.TempDir()
+	if _, err := Extract(directory); err != nil {
+		t.Fatal(err)
+	}
+	checksumPath := filepath.Join(directory, "companion.sha256")
+	if err := os.Remove(checksumPath); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Extract(directory); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(checksumPath); err != nil {
+		t.Errorf("checksum should have been rewritten: %v", err)
+	}
+}

internal/driver/ioscompanion/companionassets/prepare.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# Builds the embeddable simulator companion tarball.
+#
+# Copies the runtime files from a local install, preserving the bin/ and
+# Frameworks/ layout (the binary resolves frameworks through @rpath, so the
+# two directories must stay siblings). Build-time metadata that is never
+# needed at runtime is stripped to keep the embedded payload small. The
+# stripped layout is re-signed ad-hoc and proven to execute before it is
+# packaged.
+#
+# Output: assets/companion-1.1.8.tar.gz next to this script.
+
+set -euo pipefail
+
+# Keep the archiver from emitting AppleDouble (._name) sidecar entries that
+# would otherwise duplicate extended attributes into the payload.
+export COPYFILE_DISABLE=1
+
+VERSION="1.1.8"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ASSETS_DIR="${SCRIPT_DIR}/assets"
+OUTPUT="${ASSETS_DIR}/companion-${VERSION}.tar.gz"
+
+# Default source is the local formula install. Resolve the symlink so the
+# rsync below copies real files rather than a dangling link.
+SOURCE="${COMPANION_SOURCE:-/opt/homebrew/opt/idb-companion}"
+if [ ! -e "${SOURCE}" ]; then
+  echo "source not found: ${SOURCE}" >&2
+  echo "set COMPANION_SOURCE to the install prefix" >&2
+  exit 1
+fi
+SOURCE="$(cd "${SOURCE}" && pwd -P)"
+
+if [ ! -x "${SOURCE}/bin/idb_companion" ]; then
+  echo "no companion binary at ${SOURCE}/bin/idb_companion" >&2
+  exit 1
+fi
+
+STAGE="$(mktemp -d)"
+PROOF="$(mktemp -d)"
+trap 'rm -rf "${STAGE}" "${PROOF}"' EXIT
+
+echo "staging from ${SOURCE}"
+
+# Copy the runtime layout. -a preserves symlinks (the macOS framework
+# Versions/Current links must survive intact).
+mkdir -p "${STAGE}/bin"
+cp -a "${SOURCE}/bin/idb_companion" "${STAGE}/bin/idb_companion"
+cp -aR "${SOURCE}/Frameworks" "${STAGE}/Frameworks"
+
+# Strip build-time metadata from every framework. The framework binary, its
+# Info.plist, the code signature, and any runtime dylibs are kept; headers and
+# the Swift module/source-info artifacts are not loaded at runtime.
+for framework in "${STAGE}"/Frameworks/*.framework; do
+  version_dir="${framework}/Versions/A"
+  [ -d "${version_dir}" ] || continue
+
+  rm -rf "${version_dir}/Headers" "${version_dir}/PrivateHeaders"
+  rm -rf "${version_dir}/Modules"
+  rm -f "${framework}/Headers" "${framework}/PrivateHeaders" "${framework}/Modules"
+
+  find "${version_dir}" -name '*.swiftmodule' -prune -exec rm -rf {} + 2>/dev/null || true
+  find "${version_dir}" \( -name '*.swiftdoc' -o -name '*.swiftsourceinfo' \) -delete 2>/dev/null || true
+done
+
+# Re-sign each framework and the main binary ad-hoc. Removing files breaks the
+# existing signature seal, which the loader rejects on arm64 macOS.
+for framework in "${STAGE}"/Frameworks/*.framework; do
+  codesign --force --sign - --timestamp=none "${framework}" >/dev/null 2>&1
+done
+codesign --force --sign - --timestamp=none "${STAGE}/bin/idb_companion" >/dev/null 2>&1
+
+# Prove the stripped, re-signed layout still loads and runs. tar stores
+# symlinks as symlinks so the extracted copy mirrors the embedded payload.
+# --version dynamically links every framework and exits zero on success,
+# which fails if a strip or re-sign broke a load command or the seal.
+STRIPPED_BYTES="$(find "${STAGE}" -type f -exec stat -f%z {} + | awk '{sum += $1} END {print sum}')"
+
+PROOF_TAR="${PROOF}/payload.tar.gz"
+tar -czf "${PROOF_TAR}" -C "${STAGE}" .
+tar -xzf "${PROOF_TAR}" -C "${PROOF}"
+
+if ! "${PROOF}/bin/idb_companion" --version >/dev/null 2>&1; then
+  echo "stripped companion failed to execute" >&2
+  exit 1
+fi
+echo "stripped layout executes"
+
+mkdir -p "${ASSETS_DIR}"
+tar -czf "${OUTPUT}" -C "${STAGE}" .
+
+SHA="$(shasum -a 256 "${OUTPUT}" | awk '{print $1}')"
+
+echo "wrote ${OUTPUT}"
+echo "stripped uncompressed size: ${STRIPPED_BYTES} bytes"
+echo "sha256: ${SHA}"