refactor: move Android family behind package exports

[thymikee]

Summary

Moves the Android platform family and its colocated tests from src/platforms/android into @agent-device/platform-android, with explicit package exports for the root, ./mechanics, and root-bound ./adb-host facets. The superseded root tree and compatibility shims are deleted, and root/core/SDK/provider consumers use named-export facades.

Adds the root Android host composition for adb, filesystem, environment, hashing, and helper/IME callbacks. Runtime loaders bind that host before selecting package mechanics while preserving the root cold-start boundary. R11/R13 package-boundary enforcement, affected routing, Fallow paths, exports, and lockfile closure are updated.

Review fixes in 0b9bf462da and 5077d33219:

• Added explicit own:android-package-test-fixture unit ownership for the APK fixture and a planted regression test. The selector was observed red against the pre-fix unknown-path shape and is green after the rule.
• Updated ADR 0019 so mechanics-facet declarations are family-specific rather than Apple-specific.
• Added measured W5 source and CI-size accounting to ADR 0019, including why root shims, a broad barrel, or ambient host access are not smaller valid designs.
• Preserved the iOS workflow ignore for packages/platform-android/src/**; the obsolete src/platforms/android/** ignore is removed.
• Repaired the relocated probe assertion and the rebased W6 web-provider test route.

W6 PR #2116 is now merged into main as 838ed223b5. This branch was rebased with git rebase --onto origin/main b3c8c67e3b, replaying only the three W5 commits (40c311ca4a, 0b9bf462da, 5077d33219) so the squash-merged W6 changes are not duplicated. PR #2118 remains untouched and last in the family order. Refs #2082.

The adversarial review covered the complete W5 diff against the published W6 base: issue scope, production routes, package exports and dependency closure, host-file watchlist, named-facet enforcement, cold-start/layering policy, old-path and shim removal, hidden behavior changes, test validity, superseded code, and touched-file scope. The actionable review findings are addressed.

Validation

• pnpm install --frozen-lockfile
• pnpm format:check, pnpm lint, pnpm typecheck, and pnpm check:layering passed on the rebased tree.
• pnpm build, pnpm check:package, pnpm test:integration:node (90 passed, 9 skipped), and macOS coverage (6 passed) passed.
• The required pnpm check:affected --run selected 56 checks. Every check through package and all related tests passed; Vitest completed 454 files and 3,813 tests, but reported the known 10 post-teardown Apple-runner EnvironmentTeardownError unhandled errors in session-replay-repair-transaction.test.ts, so the aggregate command exited 1. The implicated suite passes in isolation: 17/17.
• git diff --check passed and origin/main is an ancestor of the rebased head.

The PR is published at the rebased head and is currently mergeable against main; fresh exact-head GitHub checks, including native/device/provider lanes, are pending. Local proof and GitHub/native/device proof are kept separate. No merge was performed.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-28 11:02 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.50 MB	2.51 MB	+9.1 kB
JS gzip	840.8 kB	837.2 kB	-3.7 kB
npm tarball	962.6 kB	964.1 kB	+1.6 kB
npm unpacked	3.33 MB	3.34 MB	+9.9 kB

npm unpacked components

Component	Base	Current	Diff
JS / dist source	2.65 MB	2.66 MB	+9.9 kB
Apple runner source/project	581.1 kB	581.1 kB	0 B
macOS helper source	54.8 kB	54.8 kB	0 B
Android helper artifacts	0 B	0 B	0 B
Other package files	45.6 kB	45.6 kB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.8 ms	28.2 ms	+0.4 ms
CLI --help	75.7 ms	75.7 ms	-0.1 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/mechanics.js	+154.2 kB	+46.7 kB
dist/src/session-snapshot.js	+26.0 kB	+8.4 kB
dist/src/platform-runtime-operation-host.js	-558 B	-40 B
dist/src/internal/daemon.js	+10 B	+15 B
dist/src/app-inventory-contract.js	+5 B	+15 B

Top changed packed files

Packed file	Base	Current	Diff
dist/src/mechanics.js	0 B	154.2 kB	+154.2 kB
dist/src/snapshot.js	33.1 kB	2.6 kB	-30.5 kB
dist/src/snapshot-helper.js	25.9 kB	0 B	-25.9 kB
dist/src/sdk-android-adb.js	25.8 kB	0 B	-25.8 kB
dist/src/android.js	26.4 kB	2.4 kB	-24.1 kB
dist/src/perf3.js	20.9 kB	0 B	-20.9 kB
dist/src/perf2.js	4.8 kB	20.9 kB	+16.0 kB
dist/src/perf-native.js	10.2 kB	0 B	-10.2 kB
dist/src/exec.js	0 B	8.2 kB	+8.2 kB
dist/src/ime-lifecycle.js	7.5 kB	0 B	-7.5 kB

[thymikee]

Reviewed 9fa2778 as W5 within the #2082 W4-W6 family. Android's mechanics/host split is directionally coherent, but this head is not ready:

• [P1] packages/platform-android/src/__tests__/test-utils/fixtures/android-helper-apk.fixture has no owner in scripts/check-affected, so Repo Guards correctly fail open as unknown-path. Add the owning affected check and a planted regression test; do not remove the iOS ignore that exposed it.
• [P2] docs/adr/0019-request-bound-platform-runtime.md still says the mechanics-facet declaration is Apple-specific even though this PR adds Android's facet. Update the stale statement.
• CI reports about +9.0 kB npm unpacked. Add ADR 0019 growth accounting and why a materially smaller design was rejected.

Family blocker: the current heads conflict in shared policy/host/test files. Rebase #2117 after #2116, preserve the focused host and injected snapshot seams, then let #2118 rebase last. Rerun the combined family gates. The failing iOS smoke appears to be an unrelated simulator openurl timeout, but it still needs a green exact-head rerun before readiness.

[thymikee]

Addressed the review findings in 474bd0fe71.

• Rebased refactor: move Android family behind package exports #2117 onto the current refactor: move W6 platform families behind package facades #2116 W6 head b5dd30fdd2; refactor: move Apple platform family into package #2118 remains untouched and last in the stack.
• Added own:android-package-test-fixture with unit ownership and a planted regression test. Before the rule, the fixture selected the expected unknown-path fail-open result and the test went red; after the rule, the model test is 31/31 green and pnpm check:affected:test is 63/63 green. The iOS ignore for packages/platform-android/src/** remains.
• Updated ADR 0019 mechanics-facet wording and added measured W5 source/CI-size accounting with the rejected smaller-but-invalid alternatives.
• Fixed the rebased W6 web-provider test import to use the published package facade.

Final local evidence includes green format, lint, typecheck, layering, build, package closure, full unit (1,084 files / 8,295 tests), W5-focused Android/root-route suites (616 + 53 tests), and affected-selector checks. pnpm check:affected --run passed every check and all 618 related files / 4,942 assertions, but Vitest still emitted 10 post-teardown Apple-runner EnvironmentTeardownError unhandled errors in the parallel related phase; the implicated replay-repair test passes in isolation. I am leaving that residual visible.

The PR is published/reported at the rebased head, not claimed merge-ready until fresh exact-head GitHub native/device/provider checks and stacked mergeability settle. No merge performed.

[thymikee]

Re-reviewed new exact head 474bd0f. The prior affected-owner, ADR, and size-rationale findings are fixed. However, this head is stacked on the obsolete b5dd30f W6 lineage rather than published #2116 head 4eec054; merging the published heads conflicts in ios.yml, fallow health, the platform-package policy and request-platform-providers test. Restack #2117 on published #2116, correct the stale #2116 head claim in the body, and rerun fresh combined-family CI/device evidence. Old-head Repo Guards/iOS failures are stale and are not attributed to this head; fresh exact-head CI is still starting. No readiness label yet.

[thymikee]

Re-reviewed exact head 404966d. Range-diff confirms W6/W5 patches are unchanged and there is no new Android mechanics code finding. Two blockers remain. First, this is still not stacked on the exact published #2116 head: the W6 patches were replayed equivalently onto current main, but 4eec054 is not an ancestor. Republish #2116 at the equivalent rebased W6 tip, then keep #2117 directly above it. Second, Repo Guards is genuinely red: scripts/gate/routing.test.ts still expects the moved platform-android probe fixture to fail as ambiguous-path, but its package location now correctly fails closed as unknown-path. Update the planted assertion/message without weakening ownership. Coverage plus Android/iOS remain pending; no readiness label.

[thymikee]

Follow-up after the exact-head gate finding: pushed 1da5da5886, updating the relocated Android probe fixture assertion from the obsolete ambiguous-path classification to the current package-tree unknown-path classification. pnpm gate gate-manifest-model is 51/51 green and pnpm check:affected:test is 63/63 green. The required final pnpm check:affected --run passed all runnable checks before vitest-related; the related run passed 620 files / 4,963 tests and reproduced only the 10 known post-teardown Apple-runner EnvironmentTeardownError errors in session-replay-repair-transaction.test.ts; the isolated test remains 17/17 green.

The prior Repo Guards failure belonged to 404966d and is superseded; a fresh exact-head run for 1da5da5 is now in progress. The W5 head is mergeable against current main 7b8578ec8e, but its equivalent W6 commits are replayed onto current main rather than containing published #2116 head 4eec054598 as an ancestor. I asked the existing W6 task to republish its reviewed W6 lineage on current main so the family can preserve direct stack order; #2118 remains untouched and last. This PR remains published/reported, not claimed merge-ready; no merge performed.

[thymikee]

Follow-up after the final stack repair: the W6 owner published the exact-equivalent reviewed W6 head b3c8c67e3b on current main, and I rebased only the three W5 commits onto it. Current W5 head is 8f2ce36c9a; ancestry and range-diff confirm that PR #2116 is the direct published dependency. PR #2118 remains untouched and last.

The relocated Android probe assertion is corrected in 8f2ce36c9a: the package-tree fixture fails closed as unknown-path, while the APK fixture has explicit unit ownership. pnpm gate gate-manifest-model is 51/51 and pnpm check:affected:test is 63/63. The final pnpm check:affected --run completed with exit 0; all runnable checks passed, including 620 related files and 4,963 related tests.

Fresh exact-head GitHub checks have just started and are currently pending, including Android and iOS smoke. The earlier Android smoke failure was on the superseded head and was a native emulator capture stall (readableCaptures: 0 while waiting for “landscape”), not a code assertion. I will not claim merge-ready until fresh exact-head native/device/provider evidence and stacked-family mergeability settle. No merge performed.

[thymikee]

Rebased after W6 merged: PR #2116 is squash-merged into main as 838ed223b5. I fetched that head and replayed only the three W5 commits with git rebase --onto origin/main b3c8c67e3b, producing 40c311ca4a, 0b9bf462da, and 5077d33219. The W6 changes are inherited from main, not duplicated. The prior GitHub conflict is cleared; there were no remaining conflicts in the W5-only replay.

The rebased head 5077d33219 is pushed, PR #2117 now targets main at 838ed223b5, and GitHub reports it mergeable. The required affected run selected 56 checks: static/build/package checks passed and the related phase ran 454 files / 3,813 passing tests, with the known 10 parallel Apple-runner post-teardown EnvironmentTeardownError residual. The implicated replay-repair suite passes in isolation 17/17. Fresh exact-head GitHub checks, including native/device/provider lanes, are pending. No merge performed.