Repository navigation
Description
Request: #1250
Problem
In the reporter's words: "We have a rack of Android phones wired by Ethernet, with adb over TCP on (adb connect <ip>:5555). The phones' USB ports are taken by their network adapters, so none of them has a USB path to a worker. In 0.5.0, simlock device add --platform android <ip>:5555 refuses each one: "only USB-connected devices can be enrolled" (reason network-only). That's by design since #441 ("The transport decides; the serial's shape never does"), but it leaves a whole phone farm outside the pool unless every phone is re-cabled to one host by USB."
Today they patch Simlock's driver to count an IPv4:port serial as attached, and run a timer that calls adb connect and simlock device add for every phone.
Who it is for
An operator with a farm or rack of real Android phones reached over the network: wired or Wi-Fi adb, older phones put on TCP with adb tcpip, or Android 11+ wireless debugging. For the reporter, it is coding agents that need real Samsung phones (their own OEM quirks, which emulators don't have) and lease them through the gateway the same way they lease emulators.
Outcome
- The operator turns on one worker config key. From then on
simlock device add --platform android <host:port>enrols a phone the worker's adb server reaches over the network, and so does a paired wireless-debugging phone under the name adb lists it by. - Agents lease such a phone like a USB phone: lease,
device.exec, the screen, tunnels, and app cleanup on release. - The worker connects an enrolled
host:portphone again when adb loses it, for example after the adb server restarts. Nobody runs a script. - A different phone that turns up at an enrolled phone's address is never leased or cleaned up. One phone never gets two records.
- With
devices.autoEnrollon too, the operator runsadb connectonce per phone and the worker does the rest.
How it works for the user
flowchart TD
K["operator: android.networkDevices: true, restart"] --> C["operator: adb connect 192.168.1.5:5555, once"]
C --> A["simlock device add --platform android 192.168.1.5:5555<br/>(or the worker, under devices.autoEnroll)"]
A --> I{"listed in state device, not an emulator,<br/>hardware serial not enrolled?"}
I -->|no| R["refused, with a reason"]
I -->|yes| E["enrolled: ID 192.168.1.5:5555, hardware serial kept"]
E --> W{"every probe interval: listed?"}
W -->|no| X["worker runs adb connect again"]
X --> W2{"listed now, same hardware serial?"}
W -->|yes| W2
W2 -->|yes| P["present: leasable"]
W2 -->|"no, stableObservations times"| B["absent (not-present); a lease on it ends device-lost"]
Before:
$ adb connect 192.168.1.5:5555
connected to 192.168.1.5:5555
$ simlock device add --platform android 192.168.1.5:5555
{"error":{"code":"DEVICE_NOT_ENROLLABLE","message":"only USB-connected devices can be enrolled"}} # exit 12
After, with { "android": { "networkDevices": true } } in the worker's config.json:
$ simlock device add --platform android 192.168.1.5:5555
Enrolled SM-G965F (Android 29) as 192.168.1.5:5555, 12 user apps recorded.
$ simlock device add --platform android adb-R58Y61A60HN-r7wg2G._adb-tls-connect._tcp
Enrolled SM-A165F (Android 36) as adb-R58Y61A60HN-r7wg2G._adb-tls-connect._tcp, 3 user apps recorded.
$ simlock device add --platform android R58Y61A60HN # the same A16, now also on USB
{"error":{"code":"DEVICE_NOT_ENROLLABLE","message":"this phone (hardware serial R58Y61A60HN) is enrolled as adb-R58Y61A60HN-r7wg2G._adb-tls-connect._tcp; remove that record first"}} # exit 12
The Enrolled line is today's (src/cli/commands/device.ts:100); an error is today's one JSON line on stderr with exit code 12. Only the reason enrolled-under-other-id and its message are new.
Examples
device add --platform android <id> on a worker. "Key on" is android.networkDevices: true.
| Input | Today (main, key absent) | After, key off | After, key on |
|---|---|---|---|
R58M123ABC, phone on USB, state device |
enrolled | enrolled | enrolled |
192.168.1.5:5555, listed device, no usb: field |
refused network-only |
refused network-only |
enrolled under 192.168.1.5:5555 |
adb-R58Y61A60HN-r7wg2G._adb-tls-connect._tcp, paired, listed device |
refused network-only |
refused network-only |
enrolled under that name |
192.168.1.5:5555, listed unauthorized |
refused network-only |
refused network-only |
refused untrusted |
192.168.1.5:5555, listed offline, or not listed |
refused network-only / not-connected |
same as today | refused not-connected (Simlock runs no adb connect for an address that is not enrolled) |
192.168.1.5:5555 with a usb: field (a USB phone whose serial looks like an address) |
enrolled | enrolled | enrolled, as a USB phone |
emulator-5554 on the default server |
refused network-only |
refused network-only |
refused unsupported-kind: an emulator is not a phone |
127.0.0.1:5555, an emulator reached by adb connect |
refused network-only |
refused network-only |
refused unsupported-kind |
192.168.1.6:5555, a phone whose hardware serial is enrolled under R58M123ABC (USB) |
refused network-only |
refused network-only |
refused enrolled-under-other-id |
R58M123ABC on USB, while 192.168.1.6:5555 is enrolled with hardware serial R58M123ABC (enrolled while the key was on) |
— (no network record can exist today) | refused enrolled-under-other-id |
refused enrolled-under-other-id |
192.168.1.5:5555 again, already enrolled, same phone |
— (no network record can exist today) | refused network-only |
re-enrolled (apps read again) |
192.168.1.5:5555 again, enrolled, now a different phone at that address, free |
— (no network record can exist today) | refused network-only |
re-enrolled as the new phone: its hardware serial and apps replace the old ones |
192.168.1.5:5555 again, enrolled, now phone B, whose hardware serial is enrolled as 192.168.1.6:5555 |
— (no network record can exist today) | refused network-only |
refused enrolled-under-other-id; the record is unchanged |
Presence of an enrolled network phone, read every health.probeIntervalMs:
| Situation | After, key on | After, key turned off later |
|---|---|---|
listed device, same hardware serial |
present | absent (not-present) |
| not listed (adb server restarted, phone rebooted) | worker runs adb connect; present if listed then with the same serial |
absent (not-present), no adb connect |
listed device, another hardware serial (DHCP gave the address to another phone) |
not present | absent (not-present) |
listed unauthorized |
absent (untrusted) |
absent (not-present) |
| an mDNS name not listed | not present; adb reconnects it itself, Simlock runs no adb connect |
absent (not-present) |
What could go wrong
- An operator turns the key on and a developer's own Wi-Fi phone, connected to that worker, gets enrolled by auto-enrol and leased to agents. Likely only where both keys are on; the docs warn next to the key.
- A phone gets a new IP after a router reboot and stays absent until the operator removes it and adds it at its new address. Likely in farms without DHCP reservations.
- In the seconds between a phone losing its address and the watcher seeing it, a
device.execon its lease could reach another phone that took the address. Unlikely: it needs a DHCP change during a lease. - A slow or unreachable phone makes every presence read wait for its
adb connecttime limit, delaying grants of other Android phones on that worker by up to that limit.
Words used
- network transport: an adb connection to a phone over TCP, listed by
adb devices -lwith nousb:field, e.g.192.168.1.5:5555 device product:star2ltexx model:SM_G965F transport_id:4. - address: the name adb lists a network phone under, and what
adb -stakes:host:port(e.g.192.168.1.5:5555), or an mDNS service name for a paired wireless-debugging phone (e.g.adb-R58Y61A60HN-r7wg2G._adb-tls-connect._tcp). - hardware serial: the phone's own serial,
getprop ro.serialno, e.g.R58Y61A60HN. It is whatadb deviceslists a USB phone under, and it does not change with the address. - reconnect: the worker running
adb connect <host:port>for an enrolled phone the adb server does not list. - default adb server: the adb server on port 5037 that plain
adband Android Studio use; Simlock reaches phones through it. - wireless debugging: Android 11+'s adb over Wi-Fi with TLS, set up once with
adb pair <host:port> <code>.
Non-goals
- Pairing: Simlock never runs
adb pairand never handles a pairing code. - Following a phone to a new address: a phone that moves is removed and added again.
- Discovering phones on the network (scanning a subnet, mDNS browsing beyond what adb does itself).
adb tcpip: Simlock never moves a USB phone onto TCP.- iOS over the network: iPhones keep needing USB.
- Securing adb over TCP: whoever reaches a phone's port with an authorized key drives it; that is the operator's network to secure.
- Agents managing transports:
device.execkeeps refusingconnect,disconnect,pair,tcpipandusb.
Completion conditions
- On a worker with
android.networkDevices: true,simlock device add --platform android <ip>:5555enrols a phone connected byadb connect, andsimlock lease --platform android --physicalgrants it withANDROID_SERIAL=<ip>:5555. - After
adb kill-serveron that worker, the enrolled phone is present again within two probe intervals with no command typed. - A different phone answering at an enrolled address reads absent, and a release of a lease on that address uninstalls nothing on it.
device addof a phone already enrolled under another ID is refusedenrolled-under-other-id.- With the key off, every row of the Examples tables answers as its key-off column says, and a worker that has no network record answers every
device addexactly as today. - With
devices.autoEnrollon too, a phone connected byadb connectis enrolled within one probe interval.
Open questions
none
Decisions
- ADR 0080 — An Android worker may enrol phones reached over the network (Proposed, PR docs(adr): propose 0079, an Android worker may enrol phones reached over the network (#1589) #1594): the opt-in key, the address as the ID, the hardware-serial check, reconnecting enrolled
host:portphones, auto-enrolment under both keys, and the safety exceptions. - ADR 0022 — A physical device is a second device type the core knows: narrowed by 0080 at §6 and §7; everything else (the protocol check before every command, never stopping the default server, the reclaim rules) holds for network phones unchanged.
- ADR 0073 — A worker may enrol the phones plugged into it: narrowed by 0080 at §2 and §5; its hold-out and logging rules apply to network phones unchanged.
- Decided in the session: the key is the Android driver's own key
android.networkDevices(boolean, defaultfalse), read at start likeandroid.emulator.*, because only the Android driver acts on it and a driver key is no contract shape change. - Decided in the session: an emulator is refused
unsupported-kindwhatever its transport, judged bygetprop ro.boot.qemuorro.kernel.qemubeing1, becauseadb connect 127.0.0.1:5555makes an emulator look like a network phone. - Decided in the session: reconnects run inside the Android presence read, for each enrolled
host:portID the listing lacks, all at once, each limited to 10 seconds, then the list is read again, because every presence read (watcher, grant, reclaim, quarantine) needs the same answer and the driver alone knows the transport. - Decided in the session: a USB phone keeps no separate hardware serial; its ID is its hardware serial, so the duplicate check compares a new phone's hardware serial with every live record's ID and recorded hardware serial.
- Decided in the session: re-enrolling an enrolled address that now answers with a different phone takes the new phone's hardware serial and apps, because
device addis the operator's word for what that record is. - Decided in the session: turning the key off leaves network records enrolled; they read absent (
not-present) and are not reconnected, because ownership is the record and the key only says what the driver may reach. - Decided in the session (maintainer): the duplicate refusal holds whatever the key says, because one phone keeps one record, two records would uninstall each other's apps, and the core never reads a driver key.
- Decided in the session: a reclaim of a network phone reads its hardware serial first and runs no
pmcommand on another phone, because a lease can end before the watcher has seen the address change hands. - Decided in the session:
device.exec, the screen and tunnels on a leased network phone do not re-read the hardware serial before each command; the watcher ends the leasedevice-lostonce the address answers with another phone, because a getprop before every command doubles each command's cost and those commands do not delete anything Simlock cannot put back. - Decided in the session: the hardware serial is not sent on the wire (status, worker view, events), because nobody asked to see it and keeping it in the registry needs no contract change.
- Decided in the session: the new refusal is a new reason
enrolled-under-other-idofDEVICE_NOT_ENROLLABLE, because no existing reason says "this phone already has a record under another ID", and an operator must know which record to remove.
Behaviours
| Id | Behaviour (invoker, action, what it sees) | Seam | Cases | Task |
|---|---|---|---|---|
| B1 | An operator runs device add for a network phone on a worker whose key is on, and it is enrolled under its address with its hardware serial kept; key off, it is refused as today |
AndroidPhysicalHandler.inspectPhysical with a scripted ProcessRunner (test-physical-handler.ts), driver config from I1 |
host:port device → enrollable, driverDeviceId the address, hardwareSerial ro.serialno; mDNS name device → enrollable; unauthorized → untrusted; offline / not listed → not-connected, no connect run; key off → network-only (today's test physical-handler-inspect-list.test.ts:88 keeps passing); a host:port with usb: → USB phone, hardwareSerial absent; empty ro.serialno → unreadable naming "the hardware serial (getprop ro.serialno)"; Windows host:port with key on → enrollable |
#1605 |
| B2 | An operator runs device add for an emulator reached over the default server, and it is refused as not a phone |
same as B1 | emulator-5554 key on → unsupported-kind, no getprop run; 127.0.0.1:5555 with ro.boot.qemu 1 → unsupported-kind; with ro.kernel.qemu 1 → unsupported-kind; both props empty → enrollable; key off → network-only as today |
#1605 |
| B3 | The watcher, a grant or a reclaim reads an enrolled network phone's presence, and a phone with the recorded hardware serial reads present; another phone at the address reads not present | AndroidPhysicalHandler.listPresentPhysical with a scripted ProcessRunner |
listed device, same serial → present with osVersion; another serial → not-present, and no command after the getprop; unauthorized → untrusted; serial read fails or times out → not-present; a USB record (no hardware serial) → today's rule, no serial read; key off → not-present for a network ID, no connect |
#1605 |
| B4 | The worker connects an enrolled host:port phone that the adb server does not list, and the phone reads present on the same read |
AndroidPhysicalHandler.listPresentPhysical with a scripted ProcessRunner (test-physical-handler.ts) |
not listed → adb -P 5037 connect <host:port> with a 10 s limit, then one more devices -l; listed after it → present; still not listed → not-present; connect exits 0 printing failed to connect … → judged by the second listing only; three missing addresses → three connects started before any finishes, one second listing; a listed host:port → no connect; an mDNS name not listed → no connect; a USB ID not listed → no connect; protocol mismatch → no connect, every ID not-present; the runner is given timeoutMs 10 000 for each connect, and a scripted timed-out connect → the ID reads not-present (the limit is the runner's, no timer of the handler's own) |
#1605 |
| B5 | With devices.autoEnroll on, the worker's host-level list includes network phones when the key is on |
AndroidPhysicalHandler.listAttachedPhysical with a scripted ProcessRunner |
key on: host:port and mDNS name listed in any state → listed; emulator-5554 → not listed; USB phones → listed as today; the same serial on two lines → once; key off → USB only, as today (existing tests keep passing) |
#1605 |
| B6 | The worker auto-enrols a network phone it lists, through the same device add path |
PhysicalAutoEnrollment tick with the fake driver scripted to list a network ID |
listed network ID with no record → enrolled initiator: "auto"; its hardware serial already enrolled → refused enrolled-under-other-id, logged once, no event (ADR 0073 §2's logging rule) |
#1604 |
| B7 | An operator runs device add for a phone whose hardware serial is already enrolled under another ID, and it is refused naming that record; one phone keeps one record |
PhysicalEnrollment.add with the fake driver (fake-driver.ts) |
new network ID whose hardwareSerial equals a live record's ID → refused enrolled-under-other-id; equals a live record's hardwareSerial → refused; new USB ID equal to a live record's hardwareSerial → refused; a deleted record with that serial → enrolled; same ID re-added → re-enrolled as today; re-enrol where the new read carries another hardwareSerial → record takes it; the clash appears between inspection and commit → refused at commit, no record written; re-enrol whose second inspection returns a serial another live record holds → refused at the second commit, the record unchanged; #inspect passes hardwareSerial through to PhysicalEnrollmentInput; the fake driver's FakePhysicalDevice scripts hardwareSerial and inspectPhysical returns it |
#1604 |
| B8 | A record's hardware serial survives a restart and reaches every presence read | Registry over a real state.db (registry tests), then readPhysicalPresence / readPhysicalPresenceDetail with a fake driver recording its argument |
enrolled with hardwareSerial → read back after reopen; enrolled without → absent after reopen; a v6 database → migrates, every physical row without it; the watcher, a grant, a reclaim's failure read and a quarantine retry each pass each record's driverDeviceId and hardwareSerial to listPresentPhysical; toDriverDevice of a record with a hardware serial carries it to driver.reclaim (I7) |
#1604 |
| B9 | A client sees the new refusal reason on every transport | DEVICE_NOT_ENROLLABLE through the dispatcher (device.add), CLI output, HTTP error body |
reason enrolled-under-other-id with its message and canonicalId the ID the record holds; the protocol range moves by one |
#1604 |
| B10 | An operator sets android.networkDevices in the worker's config.json |
androidDriverConfig validators and loadConfig |
true / false → accepted; absent → false; "yes" → refused naming android.networkDevices as a boolean; reaches the physical handler at construction |
#1605 |
| B11 | An agent leases a network phone and runs exec, screen and tunnels on it | AndroidDriver with a physical network device, scripted runner |
leaseEnvironment → ANDROID_SERIAL=<address>, ANDROID_ADB_SERVER_PORT=5037; passthrough shell getprop → -P 5037 -s <address> shell getprop; connect/disconnect/pair/tcpip/usb still refused; screen target serial is the address; real phone over the network: lease, exec, screen frame, reverse tunnel, release uninstalls an app (slow lane, e2e/slow-android-physical.test.ts network case, run when SIMLOCK_PHYSICAL_ANDROID_NETWORK names an address adb devices -l lists in state device with no usb: field and SIMLOCK_PHYSICAL_ANDROID_APK names an APK; a new rig option sets android.networkDevices: true in the lane's worker config; skipped, with its own gate, when either is unset) |
#1605 |
| B12 | A lease on a network phone ends and the worker reclaims it, and nothing is uninstalled unless the phone answering at the address has the recorded hardware serial | AndroidPhysicalHandler.reclaim with a scripted ProcessRunner, then ReclaimCoordinator with the fake driver |
same serial → user apps listed and uninstalled as today; another serial → throws the phone at <address> is not the enrolled one (hardware serial <read>, enrolled <recorded>) before any pm command; serial read fails → throws, no pm command; a USB record (no hardware serial) → no serial read, as today; in core, that throw → the failure presence read → absent (not-present), reclaim runs again when the phone is back (today's rule, reclaim-coordinator.ts:116, :399-412, already pinned by src/core/reclaim-coordinator.test.ts:721 and :733; no new core test) |
#1605 |
Stored state
| Id | What and where | Created, changed, deleted by | Listed or swept by | A restart mid-step leaves | Schema step | Task | Used by |
|---|---|---|---|---|---|---|---|
| S1 | devices.hardware_serial TEXT (nullable) in state.db, and PhysicalDevice.hardwareSerial?: string in memory: a network phone's ro.serialno, absent for USB phones and virtual devices |
written by Registry.enrollPhysical and Registry.reenrollPhysical from PhysicalEnrollmentInput.hardwareSerial in the enrolment commit; the row goes with the record (unenrollPhysical, deleted retention) |
read at load by registry-rows.ts; passed to every presence read (I3) |
nothing: written in the one enrolment transaction or not at all | registry +1 | #1604 | #1605 |
Interfaces
| Id | What | Shape and bounds | Errors and limits | Where | Task | Used by |
|---|---|---|---|---|---|---|
| I1 | Worker key android.networkDevices |
boolean, optional, default false; read at driver construction, never from a lease request |
a non-boolean refuses the config load like any android.* key |
src/drivers/android/definition.ts AndroidDriverConfig, androidDriverConfig; website reference/configuration.mdx row |
#1605 | — |
| I2 | PhysicalInspection (enrollable) gains hardwareSerial?: string; PhysicalEnrollmentInput gains hardwareSerial?: string |
1 to 64 characters of [A-Za-z0-9._-]; set by a driver only for a network transport; a value out of bounds is a refusal unreadable in the driver |
— | src/core/driver.ts, src/core/registry-types.ts |
#1604 | #1605 |
| I3 | Driver.listPresentPhysical(enrolled) takes readonly { driverDeviceId: string; hardwareSerial?: string }[] instead of IDs; readPhysicalPresence and readPhysicalPresenceDetail take the same entries |
answers only for the IDs given, as today; iOS and the fake driver ignore hardwareSerial |
as today | src/core/driver.ts, src/core/physical-presence.ts, src/drivers/ios/index.ts, src/drivers/android/index.ts, src/core/fake-driver.ts, e2e/fake-driver/fake-driver.ts:607; test helpers that read the argument: src/leasing/test-physical-device-watcher.ts:261-264, e2e/helpers/physical-presence.ts:285-298; callers src/leasing/physical-device-watcher.ts, src/leasing/acquisition-workflow.ts, src/core/reclaim-coordinator.ts, src/core/quarantine-coordinator.ts |
#1604 | #1605 |
| I4 | DEVICE_NOT_ENROLLABLE reason enrolled-under-other-id |
message: this phone (hardware serial <serial>) is enrolled as <id>; remove that record first; canonicalId is <id>; bumps the protocol by one |
— | src/contract/errors.ts DEVICE_NOT_ENROLLABLE_REASONS, src/core/physical-enrollment.ts DeviceNotEnrollableReason; website reference/errors.mdx, worker/enrolling-physical-devices.mdx reasons table |
#1604 | #1605 |
| I7 | PhysicalDriverDevice gains hardwareSerial?: string, set by toDriverDevice from the record |
as I2 | — | src/core/driver.ts:51-54, :72-79 |
#1604 | #1605 |
| I5 | adb -P 5037 connect <host:port> from the Android physical handler |
only for an enrolled ID matching ^[^\s:]+:\d{1,5}$ with no ._tcp; behind DefaultAdbServerGate.check; with the handler's stripped environment |
10 s limit from its spawn; its exit code and output are ignored; the outcome is the next devices -l |
src/drivers/android/physical-handler.ts |
#1605 | — |
| I6 | adb -P 5037 -s <address> shell getprop ro.serialno, ro.boot.qemu, ro.kernel.qemu |
read at inspection (all three), and ro.serialno alone at each presence read and before each reclaim of a record with a hardware serial |
30 s read limit, as every physical read (ADR 0022 §5) | src/drivers/android/physical-handler.ts |
#1605 | — |
Existing code
Commit 5e639b4.
Searches: network-only (9 files), listPresentPhysical( (8 hits, 3 implementations, 4 callers through physical-presence.ts), listAttachedPhysical (driver, auto-enrolment, fake driver), usb: in src/ (physical handler only), enrolledApps / device_enrolled_apps (registry rows), registryOwner (schema version 6), android.emulator (definition, docs).
| Id | Code (path:line) | Today | With this feature | Handled by |
|---|---|---|---|---|
| X1 | src/drivers/android/physical-handler.ts:356-366 parseDevices |
a transport is USB when it carries usb:, or on Windows when its serial is not host:port, ._tcp or emulator-N |
also tells a network transport (no usb:, not emulator-N) for the key-on paths |
B1, B5 |
| X2 | src/drivers/android/physical-handler.ts:380-399 unenrollable |
no USB entry but some entry → network-only; none → not-connected |
key on: a network entry in device passes to the reads; unauthorized → untrusted; emulator-N → unsupported-kind |
B1, B2 |
| X3 | src/drivers/android/physical-handler.ts:162-182 #readDevice |
reads model, API level, user id, apps | for a network ID also reads ro.boot.qemu, ro.kernel.qemu (refuse 1) and ro.serialno into hardwareSerial |
B1, B2 |
| X4 | src/drivers/android/physical-handler.ts:185-213 listPresentPhysical |
counts only USB entries; one getprop of the API level | takes I3's entries; key on: reconnects missing host:port IDs (I5), reads ro.serialno for a record with a hardware serial and compares |
B3, B4 |
| X5 | src/drivers/android/physical-handler.ts:215-225 listAttachedPhysical |
USB serials only | key on: network serials too, never emulator-N |
B5 |
| X6 | src/drivers/android/physical-handler.ts:30-43, :414 refused subcommands and message |
refuses connect, disconnect, pair, tcpip, usb for agents, "or take the phone off USB" |
unchanged; agents never manage a transport | B11 |
| X7 | src/drivers/android/index.ts:231-238 handler construction; :509-512 leaseEnvironment |
handler gets no config; ANDROID_SERIAL is deviceId |
handler gets networkDevices from I1; ANDROID_SERIAL is the address, unchanged code |
B10, B11 |
| X8 | src/drivers/android/definition.ts:25-54 AndroidDriverConfig, defaults, validators |
bootTimeoutMs, emulator |
gains networkDevices |
B10 |
| X9 | src/core/physical-enrollment.ts:89-145 add, :209-215 #enrolled |
an existing record matches by driverDeviceId only |
under the lock, also refuses a live record whose ID or hardwareSerial equals the read's hardware serial (or, for a USB read, whose hardwareSerial equals the read's ID) |
B6, B7 |
| X10 | src/core/registry.ts:571-636 enrollPhysical, reenrollPhysical; src/core/registry-rows.ts:290-330, :500-520 |
write and load a physical record with no hardware serial | write and load S1 | B8 |
| X11 | src/core/registry-schema.ts:143-147 registryOwner version 6 |
six migrations | a seventh: ALTER TABLE devices ADD COLUMN hardware_serial TEXT |
B8 |
| X12 | src/core/physical-presence.ts:26-64 |
passes IDs to listPresentPhysical, remembers the answer by ID |
passes I3's entries; still remembers by ID | B8 |
| X13 | src/leasing/physical-device-watcher.ts:149-163, src/leasing/acquisition-workflow.ts:172, src/core/reclaim-coordinator.ts:404, src/core/quarantine-coordinator.ts:278 |
pass driverDeviceIds |
pass each record's driverDeviceId and hardwareSerial |
B8 |
| X14 | src/drivers/ios/index.ts:459, src/core/fake-driver.ts:601, e2e/fake-driver/fake-driver.ts:607; src/leasing/test-physical-device-watcher.ts:261-264, e2e/helpers/physical-presence.ts:285-298 |
take or read IDs | take or read I3's entries, ignore hardwareSerial |
B8 |
| X24 | src/core/fake-driver.ts:74-81 FakePhysicalDevice, :663-672 inspectPhysical; e2e/fake-driver/types.ts:48 ScriptedPhysicalDevice, e2e/fake-driver/fake-driver.ts:634-648 inspectPhysical; src/core/physical-enrollment.ts:193-199 #inspect |
no hardware serial; both fakes and #inspect copy only the fields they name |
both fakes script and return hardwareSerial; #inspect passes it |
B6, B7 |
| X25 | src/core/reclaim-coordinator.ts:108-117 #purge; src/drivers/android/physical-handler.ts:227-256 reclaim; src/core/driver.ts:72-79 toDriverDevice |
reclaim runs with no presence read first; the handler lists and uninstalls on -s <id> |
toDriverDevice carries hardwareSerial; the handler reads ro.serialno first for a record that has one |
B12 |
| X26 | docs/internal/agent-rules/toolchain.md:215 Physical Android lane row; e2e/slow-android-physical.test.ts:15 SIMLOCK_PHYSICAL_ANDROID |
the lane needs a phone on USB; rig() takes only execTimeoutMs and builds configOverrides itself (:85-88); the skip gate keys on SIMLOCK_PHYSICAL_ANDROID and SIMLOCK_PHYSICAL_ANDROID_APK (:26-31) |
the row gains SIMLOCK_PHYSICAL_ANDROID_NETWORK beside the APK; the test gains a rig option for the key and a network case with its own gate |
B11 |
| X15 | src/core/physical-auto-enrollment.ts:126, :157-167 |
enrols what listAttachedPhysical lists through enrollment.add |
unchanged code; lists network phones under the key (X5) and meets B7's refusal | B6 |
| X16 | src/contract/errors.ts:3-14 DEVICE_NOT_ENROLLABLE_REASONS |
ten reasons | gains enrolled-under-other-id; protocol +1 |
B9 |
| X17 | docs/internal/agent-rules/safety.md:17-25 (rule 1), :100-103 (rule 7), :111-115 (rule 8); src/drivers/android/AGENTS.md:3, :46 |
USB-only wording | name ADR 0080's exceptions under the key | #1605 |
| X18 | website worker/enrolling-physical-devices.mdx:19, :101, :172; using-devices/physical-devices.mdx:21; reference/configuration.mdx:218 (a row after it); reference/errors.mdx |
USB only; network-only says "Connect it by USB" |
network phones under the key, the security note, the new reason, the key row | #1604 (errors), #1605 (the rest) |
| X19 | src/drivers/android/physical-handler-inspect-list.test.ts:88, physical-handler-windows.test.ts:70, e2e/physical-enrollment.test.ts:26 |
pin network-only |
keep passing with the key off | B1 |
| X20 | src/drivers/android/physical-handler-inspect-list.test.ts:106 |
a host:port serial with usb: is a USB phone |
unchanged | B1 |
| X21 | adb 1.0.41 (platform-tools 36.0.0), run on this machine: adb connect 127.0.0.1:5999 → failed to connect to '127.0.0.1:5999': Connection refused, exit 0; adb connect 192.0.2.1:5555 → Operation timed out, exit 0 |
— | I5 ignores the exit code | B4 |
| X22 | A Galaxy A16 (Android 16, API 36) paired by wireless debugging, run on the maintainer's machine: adb devices -l → adb-R58Y61A60HN-r7wg2G._adb-tls-connect._tcp device product:a16nseea model:SM_A165F device:a16 transport_id:5 (no usb:); adb -s <that> shell getprop ro.serialno → R58Y61A60HN; ro.product.model → SM-A165F; am get-current-user → 0; pm list packages -3 --user 0 lists packages; reverse --list exits 0; ro.boot.qemu prints nothing and ro.kernel.qemu prints 0 |
— | I6 works over a network transport; the mDNS name holds the hardware serial | B1, B3 |
| X23 | adb help (same adb): $ADB_MDNS_AUTO_CONNECT … (default adb-tls-connect) |
the default server reconnects paired wireless-debugging phones itself | no Simlock connect for an mDNS name | B4 |
Tasks
flowchart LR
A["#1604 core: hardware serial on the record, one phone one record"] --> B["#1605 Android: network phones under android.networkDevices"]
- A phone's hardware serial is kept on its record, and one phone keeps one record #1604 A phone's hardware serial is kept on its record, and one phone keeps one record — after it,
device addrefuses a phone already enrolled under another ID (enrolled-under-other-id), and every presence read and reclaim gets the record's hardware serial. Risk: an enrolled phone's record or presence lost across the upgrade. - An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605 An Android worker enrols, checks and reconnects phones reached over the network under
android.networkDevices— after it, an operator enrols network phones, agents lease them, the worker reconnects them, and a phone at a taken-over address is never granted or cleaned up. Risk: another phone's apps uninstalled, or grants stalling behind unreachable phones.
Completion conditions:
device add <ip>:5555enrols and a lease grants it: An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605.- Present again after
adb kill-serverwith no command: An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605. - A different phone at an enrolled address reads absent and loses no app: An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605 (its reclaim and presence guard), on A phone's hardware serial is kept on its record, and one phone keeps one record #1604's serial plumbing.
enrolled-under-other-id: A phone's hardware serial is kept on its record, and one phone keeps one record #1604.- Key off answers as the key-off column: An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605 (key paths), A phone's hardware serial is kept on its record, and one phone keeps one record #1604 (the duplicate rule).
- Auto-enrol of a connected network phone: An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605 (the list), A phone's hardware serial is kept on its record, and one phone keeps one record #1604 (the refusal).
Open work in the same area:
- Android leases that name no image tag get the worker's android.defaultImageTag where it fits #1595 and A worker's catalog names its default image tag, and a gateway ranks and shows it #1596 (task:ready, android default image tag) — each bumps the protocol: A phone's hardware serial is kept on its record, and one phone keeps one record #1604 depends on both, since two contract-shape changes overlap whatever files they touch.
- A worker can serve enrolled phones only, and never boots a simulator or emulator #1588 (feature:spec, ADR 0078 in PR docs(adr): propose 0080, a worker may serve a platform's enrolled phones only (#1588) #1592) — its tasks A worker serves only enrolled devices on a platform whose virtualDevices is false #1598 and Through a gateway, a plain lease that only phones-only workers could serve gets the phones-only refusal #1599 are
task:draft. A worker serves only enrolled devices on a platform whose virtualDevices is false #1598 bumps the protocol and editsreference/errors.mdx,reference/configuration.mdxandusing-devices/physical-devices.mdx, as A phone's hardware serial is kept on its record, and one phone keeps one record #1604 and An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605 do. A draft cannot be delivered, so no Depends on here; A worker serves only enrolled devices on a platform whose virtualDevices is false #1598's own session orders it against A phone's hardware serial is kept on its record, and one phone keeps one record #1604 and An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605. - Console: enrol a phone and remove an enrolled one #1133 (task:draft, console enrol and remove) — edits
worker/enrolling-physical-devices.mdxin other sections than A phone's hardware serial is kept on its record, and one phone keeps one record #1604 and An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605; no Depends on. - Draft PRs feat(backends): register local backend modules #1497, feat(backends): persist device backend ownership #1499, feat(backends): preserve saved baseline ownership #1500 (backend registry and ownership, ADR 0072) — touch
registry-schema.ts,registry.ts,driver.ts,fake-driver.ts, the reclaim and quarantine coordinators and the Android driver. No issue istask:readybehind them, so no Depends on; whichever lands second takes the next registry migration number and protocol step. - PR feat(ios): lease --label names the leased simulator #1243 (A lease's label is its device's window title: lease --label #1240,
lease --label) — bumps the protocol; a rebase moves the number, no Depends on.
Written by an agent.
Activity
V3RON commentedon Nov 16, 2026
Design posted: business sections, Decisions (ADR 0079 in #1594 and the session's own), Behaviours B1–B11, Stored state S1, Interfaces I1–I6, Existing code X1–X23.
Written by an agent.
docs(adr): 0079 checks the serial before a reclaim, reconnects inside…
docs(adr): accept 0079, not yet implemented (#1589)
V3RON commentedon Nov 16, 2026
Spec updated: tasks #1604 and #1605 written; task cells and the Tasks section filled in. ADR 0079 is Accepted — not yet implemented on #1594.
Written by an agent.
docs(adr): renumber the network-phones ADR to 0080 and list its phone…