refactor(apple): colocate the XCUITest runner client into packages/platform-apple (#2040) (#2050)

* refactor(apple): colocate the XCUITest runner client into packages/platform-apple (#2040)

Moves src/platforms/apple/core/runner/ (34 modules + apple-runner-platform.ts and
the 30 runner test suites) into packages/platform-apple/src/runner/ — Apple
mechanics live in the Apple package. Host capabilities (exec, diagnostics,
retry, process probes, locks, Apple tooling, physical-device control) enter
through the package-owned AppleRunnerHost port; the root composition module
src/platforms/apple/core/runner-client.ts constructs the client exactly once
and re-exposes the bound operations under their historical names.

R13 admits the transitional state deliberately: the family exports its root
façade plus exactly the enumerated ./runner, ./runner/client, and
./runner/test-host subpaths; the ./runner façade subpath is the recorded #1983
seam for unmigrated root consumers; ./runner/client has one composition root
and ./runner/test-host one vitest installer; the runner subtree may own its
cache files and sockets while raw process primitives stay banned. When #1983
completes, the subpaths and every subtree exemption are deleted and the family
returns to a single implementation-lazy façade export.

* docs(adr): model the runner subtree as a durable platform-owned facet

Review correction on #2050: the sunset story attributed the runner-consumer
migration to #1983, which owns snapshot/presentation vocabulary — not the
runner's daemon/root consumers — so that event cannot delete the ./runner
subpaths or the subtree exemptions. Reword ADR-0019, R13, and the gate
comments: the facet is the intended ownership model, its seam is enumerated
and pinned (exact export list, one client composition root, one test-host
installer, raw-process ban, eager-closure pins), and the seam narrows only
if a real runner-consumer migration retires the direct consumers. The
declaration mechanism stays apple-specific until another family needs a
mechanics facet. No behavior change; identifiers and comments only.

Author: thymikee

.github/actions/setup-apple-runner-build/action.yml

@@ -44,7 +44,7 @@ runs:
       id: source-hash
       run: |
         set -euo pipefail
-        echo "value=${{ hashFiles('apple/runner/**', 'scripts/build-xcuitest-apple.sh', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'src/platforms/apple/core/apple-runner-platform.ts', 'src/platforms/apple/core/runner/runner-cache-metadata.ts', 'src/platforms/apple/core/runner/runner-icon.ts', 'src/platforms/apple/core/runner/runner-xctestrun.ts', 'src/platforms/apple/core/runner/runner-xctestrun-products.ts', '.github/actions/setup-apple-runner-build/action.yml', 'package.json', 'pnpm-lock.yaml') }}" >> "$GITHUB_OUTPUT"
+        echo "value=${{ hashFiles('apple/runner/**', 'scripts/build-xcuitest-apple.sh', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'packages/platform-apple/src/runner/apple-runner-platform.ts', 'packages/platform-apple/src/runner/runner-cache-metadata.ts', 'packages/platform-apple/src/runner/runner-icon.ts', 'packages/platform-apple/src/runner/runner-xctestrun.ts', 'packages/platform-apple/src/runner/runner-xctestrun-products.ts', '.github/actions/setup-apple-runner-build/action.yml', 'package.json', 'pnpm-lock.yaml') }}" >> "$GITHUB_OUTPUT"
       shell: bash
 
     - name: Resolve Apple runner build variant

.github/workflows/xctest-nightly.yml

@@ -123,7 +123,7 @@ jobs:
       # `RunnerTests/testCommand` is not a test. It is the runner's server entry point: it
       # opens an NWListener and blocks in `XCTWaiter.wait(timeout: 24 * 60 * 60)` until a
       # client closes the session, which is exactly how production drives it
-      # (src/platforms/apple/core/runner/runner-session.ts always passes it as the sole
+      # (packages/platform-apple/src/runner/runner-session.ts always passes it as the sole
       # `-only-testing:`). It compiles unconditionally — the `#if AGENT_DEVICE_RUNNER_UNIT_TESTS`
       # block ends well above it — so an unfiltered run reaches it in alphabetical order and
       # hangs the job until `timeout-minutes`. Its one escape hatch,

AGENTS.md

@@ -112,7 +112,7 @@ cross-language rules change through golden tables under `contracts/fixtures/`.
 
 ## Runtime and diagnostics seams
 
-The OS-neutral Apple runner lives under `src/platforms/apple/core/runner/`. For connection errors,
+The OS-neutral Apple runner lives under `packages/platform-apple/src/runner/`. For connection errors,
 retry policy, or command typing, start at `runner-contract.ts`; transport stays below session/client
 behavior, and xctestrun build/cache logic stays outside request execution.
 

apple/runner/README.md

@@ -15,7 +15,7 @@ Current internal runner for iOS, tvOS, and macOS desktop automation.
 Protocol and maintenance references:
 
 - Protocol overview: [`RUNNER_PROTOCOL.md`](RUNNER_PROTOCOL.md)
-- TypeScript client: [`../../src/platforms/apple/core/runner/runner-client.ts`](../../src/platforms/apple/core/runner/runner-client.ts)
+- TypeScript client: [`../../packages/platform-apple/src/runner/runner-client.ts`](../../packages/platform-apple/src/runner/runner-client.ts)
 - Swift wire models: [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
 
 ## UITest Runner File Map

apple/runner/RUNNER_PROTOCOL.md

@@ -64,7 +64,7 @@ than silently applied:
 
 The current command names are defined in:
 
-- [`../../src/platforms/apple/core/runner/runner-client.ts`](../../src/platforms/apple/core/runner/runner-client.ts)
+- [`../../packages/platform-apple/src/runner/runner-client.ts`](../../packages/platform-apple/src/runner/runner-client.ts)
 - [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
 
 ## Response Shape

docs/adr/0019-request-bound-platform-runtime.md

@@ -129,6 +129,21 @@ platform-common package, and it preserves the package façades' implementation-l
 Its introduction carries the normal workspace-package compliance surface: `check:affected`
 selection, R11/R13 package enumeration, and the composite typecheck project list.
 
+The Apple XCUITest runner client is a durable platform-owned implementation facet colocated
+inside `packages/platform-apple` as the `src/runner/` subtree (#2040) — Apple mechanics belong to
+the Apple package. R13 models the facet by enumeration rather than by exception sprawl: the family
+exports its root façade plus exactly the `./runner`, `./runner/client`, and `./runner/test-host`
+subpaths; the `./runner` façade subpath is the seam through which daemon and root consumers reach
+runner mechanics directly today; the host-bound `./runner/client` factory has one composition root
+and `./runner/test-host` one vitest installer; the facet owns its cache files and usbmux sockets
+(the ambient-host rule exempts exactly that subtree), while raw process primitives stay banned —
+host authority still enters through one focused injected port (`AppleRunnerHost`: process
+execution, diagnostics, retry, probes, locks, foreground Apple tooling, physical-device control)
+constructed by exactly one composition root. No current issue owns migrating the runner's direct
+consumers behind the composition gateway; if such a migration retires them, the `./runner` seam
+narrows with it, but the facet itself is the intended ownership model, not a temporary exception.
+The declaration mechanism stays apple-specific until another family needs a mechanics facet.
+
 Canonical family, `AppleOS`, public-leaf, and selector identity remain declared in
 `@agent-device/kernel/device`. Platform-module metadata references one canonical family; during
 coexistence the legacy plugin registry derives its family identity from the same declaration rather

fallow-baselines/health.json

@@ -374,11 +374,6 @@
         "count": 1
       }
     },
-    "src/platforms/apple/core/runner/runner-startup-transport.ts": {
-      "crap_high": {
-        "count": 1
-      }
-    },
     "src/platforms/apple/core/screenshot-status-bar.ts": {
       "complexity_moderate": {
         "count": 1
@@ -557,6 +552,11 @@
       "crap_moderate": {
         "count": 1
       }
+    },
+    "packages/platform-apple/src/runner/runner-startup-transport.ts": {
+      "crap_high": {
+        "count": 1
+      }
     }
   },
   "runtime_coverage_findings": [],

packages/platform-apple/package.json

@@ -7,12 +7,25 @@
   "dependencies": {
     "@agent-device/capture-kit": "workspace:*",
     "@agent-device/contracts": "workspace:*",
-    "@agent-device/kernel": "workspace:*"
+    "@agent-device/kernel": "workspace:*",
+    "@agent-device/xml": "workspace:*"
   },
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./runner": {
+      "types": "./src/runner/index.ts",
+      "default": "./src/runner/index.ts"
+    },
+    "./runner/client": {
+      "types": "./src/runner/client.ts",
+      "default": "./src/runner/client.ts"
+    },
+    "./runner/test-host": {
+      "types": "./src/runner/test-host.ts",
+      "default": "./src/runner/test-host.ts"
     }
   }
 }

…/__tests__/apple-runner-platform.test.ts …/__tests__/apple-runner-platform.test.tssrc/platforms/apple/core/__tests__/apple-runner-platform.test.ts renamed to packages/platform-apple/src/runner/__tests__/apple-runner-platform.test.ts src/platforms/apple/core/__tests__/apple-runner-platform.test.ts renamed to packages/platform-apple/src/runner/__tests__/apple-runner-platform.test.ts

@@ -0,0 +1,41 @@
+import type { DeviceInfo } from '@agent-device/kernel/device';
+
+// Apple-family device fixtures for runner tests; the package owns its own
+// test data rather than reaching into root test-utils.
+
+export const IOS_SIMULATOR: DeviceInfo = {
+  platform: 'apple',
+  id: 'sim-1',
+  name: 'iPhone 17 Pro',
+  kind: 'simulator',
+  appleOs: 'ios',
+  booted: true,
+};
+
+export const IOS_DEVICE: DeviceInfo = {
+  platform: 'apple',
+  id: 'ios-device-1',
+  name: 'iPhone',
+  kind: 'device',
+  appleOs: 'ios',
+  booted: true,
+};
+
+export const MACOS_DEVICE: DeviceInfo = {
+  platform: 'apple',
+  id: 'host-macos-local',
+  name: 'Mac',
+  kind: 'device',
+  target: 'desktop',
+  appleOs: 'macos',
+  booted: true,
+};
+
+export const TVOS_SIMULATOR: DeviceInfo = {
+  platform: 'apple',
+  id: 'tv-sim-1',
+  name: 'Apple TV',
+  kind: 'simulator',
+  target: 'tv',
+  appleOs: 'tvos',
+};