Repository navigation
Description
Part of #1589.
Scope
After this PR, an operator sets android.networkDevices: true on a worker. simlock device add --platform android <host:port>, or a paired wireless-debugging phone's mDNS name, then enrols a phone the worker's adb server reaches over the network. Agents lease it like a USB phone. The worker connects an enrolled host:port phone again when adb loses it. A different phone at the address is never granted or cleaned up. Emulators stay refused on any transport. With devices.autoEnroll on too, network phones are enrolled by themselves. With the key off, nothing changes.
If this goes wrong, an operator would see a network phone refused or absent while adb lists it, another phone's apps uninstalled after an address changed hands, grants on the worker stalling behind unreachable phones, or an emulator enrolled as a phone.
Technical spec
Commit 5e639b4.
Rows
- Behaviours: B1, B2, B3, B4, B5, B10, B11, B12
- Interfaces: I1, I5, I6
- Existing code: X1, X2, X3, X4, X5, X6, X7, X8, X15, X17, X18 (all but
reference/errors.mdx), X19, X20, X21, X22, X23, X25 (the handler'sreclaim), X26
Facts
| # | Fact | Source |
|---|---|---|
| F1 | The handler's scripted adb is PhoneAdb in test-physical-handler.ts; it can hang a call and records each call's options, timeoutMs included |
src/drivers/android/test-physical-handler.ts:102-123 |
| F2 | The slow lane's rig() takes only execTimeoutMs and builds configOverrides inside it, so the network case adds a rig option; the file's skip gate keys on SIMLOCK_PHYSICAL_ANDROID and SIMLOCK_PHYSICAL_ANDROID_APK |
e2e/slow-android-physical.test.ts:26-31, :85-88 |
| F3 | An android.* key is declared with its default and validator in androidDriverConfig |
src/drivers/android/definition.ts:37-54 |
Modules touched
Searches: parseDevices, unenrollable, listPresentPhysical, listAttachedPhysical, reclaim( in physical-handler.ts, AndroidPhysicalHandler(, androidDriverConfig, network-only, usb:, Phones are USB transports only, SIMLOCK_PHYSICAL_ANDROID.
Android driver (definition.ts, index.ts, physical-handler.ts and their tests), e2e/slow-android-physical.test.ts, docs/internal/agent-rules/safety.md, docs/internal/agent-rules/toolchain.md, src/drivers/android/AGENTS.md, the website pages in X18.
Rules in play
- Safety rules 1, 7 and 8: the text names ADR 0080 §5's three exceptions under the key, in this PR.
- Safety rule 9 and ADR 0022 §5: every
adb connectand every new getprop passesDefaultAdbServerGate.checkfirst; the 5037 server is never started, stopped or adopted on purpose. - Drivers manual "Opaque to core": the key is read by the driver only.
- ADR 0073 §2 and §3: auto-enrolment of network phones keeps the hold-out and logging rules.
- Documentation rule 9: the configuration, enrolment and physical-devices pages change with the behaviour.
- ADR 0080 §1–§5.
Retired words
Phones are USB transports only: underandroid.networkDevicesa phone may be a network transport (Android manual).only USB-connected devices can be enrolled: still thenetwork-onlymessage with the key off; the docs' remedy fornetwork-onlynames the key next to "connect it by USB".
Tests
The seam is AndroidPhysicalHandler with the scripted PhoneAdb, modelled on src/drivers/android/physical-handler-inspect-list.test.ts; B11's lease paths on AndroidDriver, modelled on src/drivers/android/index-device-tcp.test.ts.
- B1:
device addof a network phone under the key:host:portand mDNS name enrolled withhardwareSerial;unauthorized;offlineor not listed (noconnect); key offnetwork-only;host:portwithusb:as USB; emptyro.serialnounreadable; Windowshost:port - B2: an emulator refused
unsupported-kind:emulator-5554;ro.boot.qemu1;ro.kernel.qemu1; both empty enrollable; key offnetwork-only - B3: presence of a network phone: same serial present; another serial not present and nothing after the getprop;
unauthorized; serial read failing; a USB record with no serial read; key off - B4: reconnect: one
connectper missinghost:port, all started together,timeoutMs10 000, then one more listing; exit 0failed to connectjudged by the listing; no connect for listed, mDNS or USB IDs; protocol mismatch; a timed-out connect - B5: the host-level list under the key:
host:portand mDNS names in any state; noemulator-N; USB as today; duplicates once; key off USB only - B10:
android.networkDevicestrue,false, absent,"yes"refused; reaches the handler - B11: a leased network phone:
leaseEnvironment,passthroughscoping, refused transport subcommands, screen target serial; slow lanee2e/slow-android-physical.test.tsnetwork case underSIMLOCK_PHYSICAL_ANDROID_NETWORK - B12: reclaim of a network phone: same serial uninstalls; another serial throws before any
pm; a failed serial read throws; a USB record reads no serial. Core turning that throw intoabsent (not-present)is today's rule, pinned bysrc/core/reclaim-coordinator.test.ts:721and:733; no core test is added
Done when
pnpm test:changedpasses, with a test per B1–B5 and B10–B12 case above (B12's core case excepted, already pinned), and today'snetwork-onlytests (X19) pass unchanged.- The website build and its HTTP API check pass (
definition.tschanges). website/src/content/docs/docs/reference/configuration.mdxhas theandroid.networkDevicesrow;worker/enrolling-physical-devices.mdxandusing-devices/physical-devices.mdxdescribe network phones, reconnects, the address as the ID, moving a phone, and the warning that with both keys on any network phone connected on the worker is enrolled.safety.mdrules 1, 7 and 8 andsrc/drivers/android/AGENTS.mdname the exceptions;toolchain.md's Physical Android row namesSIMLOCK_PHYSICAL_ANDROID_NETWORKbesideSIMLOCK_PHYSICAL_ANDROID_APK.- Slow lane:
scripts/slow-e2e.sh --physical e2e/slow-android-physical.test.tspasses its network case on a phone connected byadb connector wireless debugging (SIMLOCK_PHYSICAL_ANDROID_NETWORKandSIMLOCK_PHYSICAL_ANDROID_APKset).
Out of scope
- Pairing, discovery,
adb tcpip, iOS over the network (feature Non-goals). - Re-reading the hardware serial before
device.exec, screen or tunnel commands (feature Decisions).
Depends on
Written by an agent.
Activity
test: an emulator is refused unsupported-kind whatever its transport (#…
feat(android): a network transport whose qemu flags say emulator is r…
test: an enrolled network phone reads present only with its recorded …
feat(android): a network phone reads present only when its hardware s…
test: the worker connects an enrolled host:port phone the adb server …
feat(android): the worker connects an enrolled host:port phone adb no…
test: with the key on the host-level list includes network phones and…
feat(android): the host-level list includes network phones under andr…
test: a reclaim of a network phone uninstalls nothing unless the phon…
feat(android): a reclaim of a network phone checks its hardware seria…
test: android.networkDevices takes true or false, defaults to false a…
feat(android): the worker config key android.networkDevices (#1605)
test: a leased network phone gets its address as the serial, scoped p…
docs: network phones under android.networkDevices in the safety rules…
refactor(android): one emulator refusal (#1605)
test: a network phone's unreadable hardware serial at reclaim names i…
docs: trim the Android manual under its cap, safety rules 1 and 7 nam…
V3RON commentedon Nov 16, 2026
Handoff
Done: PR #1627 (stacked on #1622, stack #1594 → #1622 → #1627) builds every B1–B5 and B10–B12 case; audit probed 10/10; review passed in round 2 (3 findings fixed at c3a3c2f). PR is ready and labelled
needs-hardware.Not done: the slow-lane network case and the three #1589 completion conditions that need a phone reached over the network.
Findings: none open. Base flakes #1613, #1628 seen in
pnpm test:changed.Blocked on: a host with a phone connected by
adb connector wireless debugging, withSIMLOCK_PHYSICAL_ANDROID_NETWORKandSIMLOCK_PHYSICAL_ANDROID_APKset in.slow-lane.env. Then runscripts/slow-e2e.sh --physical e2e/slow-android-physical.test.ts, tick the lines, and merge the stack (ADR 0080 flip first).Written by an agent.
V3RON commentedon Nov 16, 2026
Delivery run
Merged: none
Parked: #1605 — needs-hardware: the slow-lane network case needs a phone reached over the network (PR #1627 ready in stack #1594 → #1622 → #1627)
Waiting: none
Decided: none
Written by an agent.