refactor: move Android family behind package exports (#2117)

* refactor: move Android family behind package exports

* fix: address Android W5 review feedback

* fix: update relocated routing fixture assertion

Author: thymikee

.fallowrc.json

@@ -66,7 +66,7 @@
   "ignoreExports": [
     {
       "comment": "Android perf mechanics are selected through the lazy platform host so importing agent-device does not eagerly load adb mechanics. Fallow cannot follow the dynamic property read in src/platform-runtime-perf-host.ts.",
-      "file": "src/platforms/android/perf.ts",
+      "file": "packages/platform-android/src/perf.ts",
       "exports": ["sampleAndroidMemoryPerf"]
     },
     {
@@ -174,6 +174,11 @@
         "createAppLogLiveHandle"
       ]
     },
+    {
+      "comment": "Android mechanics facet: the package exports the complete named implementation seam for root/core/SDK consumers and package-owned tests; Fallow's production graph does not follow workspace subpath imports through the package exports map.",
+      "file": "packages/platform-android/src/mechanics.ts",
+      "exports": ["*"]
+    },
     {
       "comment": "Deliberately kept off the @agent-device/maestro façade (index.test.ts asserts its absence) and consumed only by the conformance harness under packages/maestro/test/.",
       "file": "packages/maestro/src/internal/program-ir-command-parser.ts",
@@ -376,6 +381,13 @@
       "rules": {
         "unused-types": "off"
       }
+    },
+    {
+      "comment": "Android mechanics facet types are named explicitly for the same package-subpath public seam; unused-exports remains governed by the facet entry above.",
+      "files": ["packages/platform-android/src/mechanics.ts"],
+      "rules": {
+        "unused-types": "off"
+      }
     }
   ],
   "production": {

.github/workflows/ios.yml

@@ -28,7 +28,10 @@ on:
       - 'src/**/__tests__/**/*.ts'
       - 'packages/*/src/**/*.test.ts'
       - 'packages/*/src/**/__tests__/**/*.ts'
-      - 'src/platforms/android/**'
+      - 'src/platforms/harmonyos/**'
+      - 'src/platforms/linux/**'
+      - 'src/platforms/vega/**'
+      - 'src/platforms/web/**'
       - 'packages/platform-android/src/**'
       - 'packages/platform-harmonyos/src/**'
       - 'packages/platform-linux/src/**'

android/ime-helper/README.md

@@ -79,6 +79,6 @@ security boundary): if present and it doesn't match, the broadcast is dropped an
 Switching the active IME is machine-global, not session-scoped. A crashed daemon that switched the
 IME and never restored it leaves the device with an invisible keyboard -- on a real device, this
 means the user cannot type anywhere until they manually reset their IME in Settings. The TS-side
-lifecycle (`src/platforms/android/ime-lifecycle.ts`) persists the previously active IME to disk
+lifecycle (`packages/platform-android/src/ime-lifecycle.ts`) persists the previously active IME to disk
 before switching, restores it on session close/teardown, and best-effort restores any orphaned
 switch left behind by a previous crashed daemon on startup.

docs/adr/0012-interactive-replay.md

@@ -407,10 +407,10 @@ target-binding divergences reported before the device action. This is not genera
 > for the wait keep-poll loop (`isUnreadableCaptureContentError`): the non-throwing `sparse-snapshot`
 > verdict always retries (it is already a content-quality signal), but a thrown `capture-failed` only
 > retries when the underlying error's `androidSnapshotHelperFailureReason` is one of the three literal
-> codes `rejectAndroidHelperContentUnavailable` (`platforms/android/snapshot.ts`) attaches to a
+> codes `rejectAndroidHelperContentUnavailable` (`packages/platform-android/src/snapshot.ts`) attaches to a
 > content-poor/system-window-only rejection — `empty-helper-output`, `system-window-only`,
 > `content-poor-app-window` (mirroring `AndroidHelperContentRecoveryDecision['reason']`,
-> `platforms/android/snapshot-content-recovery.ts`). This is deliberately narrower than the error's own
+> `packages/platform-android/src/snapshot-content-recovery.ts`). This is deliberately narrower than the error's own
 > generic `retriable` flag: Android's adb layer separately marks true mechanism failures retriable too
 > (`connection_dropped`, `device_offline`, `server_version_mismatch` — an unchanged retry of the SAME adb
 > command can succeed there), and a helper artifact permanently missing

docs/adr/0013-unified-gesture-plans.md

@@ -74,7 +74,7 @@ Platform adapters consume the canonical plan:
 - Android's `executeAndroidTouchPlan` adapter seam sends planned touch, including gesture plans plus
   the physical movement for scroll and long-press, to provider-native touch injection when
   available, otherwise to the bundled instrumentation helper. One-contact endpoint plans lower in
-  `src/platforms/android/touch-plan.ts` to 16 ms linear transport samples before either injection
+  `packages/platform-android/src/touch-plan.ts` to 16 ms linear transport samples before either injection
   path; two-contact plans retain their exact planned samples. Transport samples are typed as
   strictly denser than the canonical endpoint pair, so skipping that lowering is a type error at
   the injection seams instead of a silently sparse gesture. A stationary long-press needs no

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

@@ -114,14 +114,13 @@ process primitives outside the shared host-command port. R13 applies these rules
 dynamic, and re-export edges; package-owned tests may import their own public façade. Contracts may
 depend on kernel vocabulary but never on concrete platform packages or daemon implementation types.
 
-Transitional exception (#2041): the Android adb/IME transport cluster (`adb-executor`,
-`ime-lifecycle`, `ime-helper`) lives in `@agent-device/platform-android` behind four registered
-subpaths, with its raw host primitives injected through the package's `adb-host` port by root
-composition wiring. Live root runtime, core interactor, SDK, and test-support consumers still import
-the old root paths, so R13 names an explicit shim table: each subpath is importable only by its root
-re-export shim (plus the host-binding, the helper-install module the binding reaches, and the
-cluster's own tests under `src/platforms/android/__tests__/`). Delete the shims and narrow this table
-only after those consumers move; the table growing is drift, not precedent.
+The Android family mechanics now live entirely in `@agent-device/platform-android`. Its root façade
+remains metadata-only and lazy; the package exports exactly two implementation facets: `./mechanics`
+for named Android behavior consumed by root/core/SDK code and package-owned tests, and `./adb-host`
+for the host port bound only by `src/platform-runtime-android-adb-host.ts`. The old
+`src/platforms/android` family tree and root shims are deleted. R13 enumerates these two facets and
+rejects any additional Android subpath or daemon production import, so package closure and host
+authority stay explicit rather than being restored through compatibility paths.
 
 Durable-capture mechanics shared by more than one implementation live in the private
 `@agent-device/capture-kit` workspace package, with the enforced direction
@@ -184,7 +183,9 @@ execution, diagnostics, retry, probes, locks, foreground Apple tooling, physical
 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.
+Mechanics-facet declarations are explicit per family: the Apple runner and Android mechanics/host
+facets are enumerated above, and a new family adds its own named facet only with an owning consumer
+and evidence.
 
 Canonical family, `AppleOS`, public-leaf, and selector identity remain declared in
 `@agent-device/kernel/device`. Platform-module metadata references one canonical family; during
@@ -679,6 +680,31 @@ removed against package bytes added; net growth is exceptional and each contribu
 named and justified individually. Contract modules stay vocabulary-thin under the existing
 capture-kit rule; per-unit type inflation is size growth and is reviewed as such.
 
+#### W5 Android family accounting (PR #2117)
+
+The W5 exact-head size report at `9fa2778` against `437465f37` reported these rounded CI values:
+
+| Metric             | Original baseline | W5 head | W5 delta |
+| ------------------ | ----------------: | ------: | -------: |
+| Raw JavaScript     |          2.48 MB | 2.49 MB | +8.2 kB  |
+| Gzipped JavaScript |         835.0 kB | 831.2 kB | -3.9 kB |
+| npm tarball        |         958.5 kB | 959.6 kB | +1.1 kB |
+| npm unpacked       |          3.32 MB | 3.33 MB | +9.0 kB  |
+
+At source level, the moved Android production tree accounts for 456,492 B removed from
+`src/platforms/android` versus 475,413 B in changed package targets, a +18,921 B relocation
+delta; the new root host/facade seam adds 19,978 B. The published +9.0 kB unpacked result is the
+package result, not a source-byte estimate. The increase is attributable to the named `mechanics`
+closure, the injected root host composition, and preserving deferred helper loading while root
+chunks are removed or repartitioned. The largest packed increase is the mechanics chunk; it is
+offset by deletion or shrinkage of the superseded root Android chunks.
+
+A smaller design that retained root re-export shims, a broad barrel, or ambient filesystem/process
+access would reduce gross source movement but violate this ADR's package-closure,
+no-compatibility-shim, named-facet, host-injection, and implementation-lazy constraints. This is
+exceptional W5 accounting, not reusable checkpoint headroom; after rebasing on #2116, the
+combined-family CI size result remains the authoritative current measurement.
+
 Raw per-unit parity, planted-red, and size evidence belongs in #1739 and its PRs; this ADR retains
 the decision, the evidence tiers, and the rule that each unit must justify exceptional growth
 without treating checkpoint budget as an allowance.

fallow-baselines/health.json

@@ -336,22 +336,17 @@
         "count": 2
       }
     },
-    "src/platforms/android/app-parsers.ts": {
+    "packages/platform-android/src/app-parsers.ts": {
       "crap_moderate": {
         "count": 1
       }
     },
-    "src/platforms/android/manifest.ts": {
+    "packages/platform-android/src/manifest.ts": {
       "crap_moderate": {
         "count": 1
       }
     },
-    "src/platforms/android/scroll-hints.ts": {
-      "complexity_moderate": {
-        "count": 1
-      }
-    },
-    "src/platforms/android/ui-hierarchy.ts": {
+    "packages/platform-android/src/ui-hierarchy.ts": {
       "crap_moderate": {
         "count": 2
       }
@@ -592,7 +587,7 @@
     "src/daemon/daemon-process.ts:high impact",
     "src/utils/screenshot-result.ts:high impact",
     "packages/platform-web/src/json-utils.ts:high impact",
-    "src/platforms/android/settings.ts:complexity",
+    "packages/platform-android/src/settings.ts:complexity",
     "src/utils/text-surface.ts:high impact",
     "src/daemon/handlers/session-test-sharding.ts:high impact",
     "src/daemon/handlers/session-replay-runtime.ts:complexity",
@@ -612,10 +607,10 @@
     "src/replay/test/reporters/format.ts:high impact",
     "src/daemon/handlers/session-test-infrastructure.ts:high impact",
     "src/daemon/handlers/session-test-artifacts.ts:high impact",
-    "src/platforms/android/app-parsers.ts:high impact",
+    "packages/platform-android/src/app-parsers.ts:high impact",
     "src/daemon/server/http-server.ts:complexity",
-    "src/platforms/android/ui-hierarchy.ts:high impact",
-    "src/platforms/android/sdk.ts:high impact",
+    "packages/platform-android/src/ui-hierarchy.ts:high impact",
+    "packages/platform-android/src/sdk.ts:high impact",
     "src/daemon/client/daemon-client-lifecycle.ts:complexity",
     "src/client/client-companion-tunnel-worker.ts:complexity"
   ]

packages/contracts/src/android-system-chrome.ts

@@ -3,7 +3,7 @@ import type { SnapshotNode } from '@agent-device/kernel/snapshot';
 /**
  * Android status-bar/navigation-bar chrome identity, shared by the settle-chrome
  * classifier (`core/snapshot-chrome.ts`) and the helper content classifier
- * (`platforms/android/snapshot-content-recovery.ts`). SystemUI also hosts actionable
+ * (`packages/platform-android/src/snapshot-content-recovery.ts`). SystemUI also hosts actionable
  * overlays — volume panel, media pickers, the shade itself — so chrome is never a
  * package-level fact: only the status/nav-bar container's subtree is chrome.
  */

packages/contracts/src/snapshot-scope.test.ts

@@ -6,7 +6,7 @@ import { matchesSnapshotScope, normalizeSnapshotScope } from './facades/snapshot
 
 // Golden scope-policy table (#1797 / #1832 C2): the SAME JSON is asserted against every runtime
 // that resolves `--scope` — this predicate, the Android platform projection
-// (src/platforms/android/__tests__/ui-hierarchy-scope.test.ts), and the Swift runner twin.
+// (packages/platform-android/src/__tests__/ui-hierarchy-scope.test.ts), and the Swift runner twin.
 // This file proves the PREDICATE + first-document-order-match rule; subtree slicing is proved by
 // the runtime legs.
 

packages/contracts/src/snapshot-viewport-root.test.ts

@@ -73,7 +73,7 @@ const IOS_EMITTED_TYPES = [
   'Element(72)',
 ] as const;
 
-// src/platforms/android/ui-hierarchy.ts — `type` is the uiautomator `class`
+// packages/platform-android/src/ui-hierarchy.ts — `type` is the uiautomator `class`
 // attribute verbatim, a fully-qualified Java class name.
 const ANDROID_EMITTED_TYPES = [
   'android.view.View',