Skip to content

An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605

Open

Description

@V3RON

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's reclaim), 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 connect and every new getprop passes DefaultAdbServerGate.check first; 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: under android.networkDevices a phone may be a network transport (Android manual).
  • only USB-connected devices can be enrolled: still the network-only message with the key off; the docs' remedy for network-only names 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 add of a network phone under the key: host:port and mDNS name enrolled with hardwareSerial; unauthorized; offline or not listed (no connect); key off network-only; host:port with usb: as USB; empty ro.serialno unreadable; Windows host:port
  • B2: an emulator refused unsupported-kind: emulator-5554; ro.boot.qemu 1; ro.kernel.qemu 1; both empty enrollable; key off network-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 connect per missing host:port, all started together, timeoutMs 10 000, then one more listing; exit 0 failed to connect judged 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:port and mDNS names in any state; no emulator-N; USB as today; duplicates once; key off USB only
  • B10: android.networkDevices true, false, absent, "yes" refused; reaches the handler
  • B11: a leased network phone: leaseEnvironment, passthrough scoping, refused transport subcommands, screen target serial; slow lane e2e/slow-android-physical.test.ts network case under SIMLOCK_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 into absent (not-present) is today's rule, pinned by src/core/reclaim-coordinator.test.ts:721 and :733; no core test is added

Done when

  • pnpm test:changed passes, with a test per B1–B5 and B10–B12 case above (B12's core case excepted, already pinned), and today's network-only tests (X19) pass unchanged.
  • The website build and its HTTP API check pass (definition.ts changes).
  • website/src/content/docs/docs/reference/configuration.mdx has the android.networkDevices row; worker/enrolling-physical-devices.mdx and using-devices/physical-devices.mdx describe 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.md rules 1, 7 and 8 and src/drivers/android/AGENTS.md name the exceptions; toolchain.md's Physical Android row names SIMLOCK_PHYSICAL_ANDROID_NETWORK beside SIMLOCK_PHYSICAL_ANDROID_APK.
  • Slow lane: scripts/slow-e2e.sh --physical e2e/slow-android-physical.test.ts passes its network case on a phone connected by adb connect or wireless debugging (SIMLOCK_PHYSICAL_ANDROID_NETWORK and SIMLOCK_PHYSICAL_ANDROID_APK set).

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

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 16, 2026
  2. added
    task:readySpec checked. An agent may implement it once its Depends on allow.
    and removed
    task:draftScope written; technical spec or its spec check missing.
    on Nov 16, 2026
  3. self-assigned this
    on Nov 16, 2026
  4. V3RON commented on Nov 16, 2026

    @V3RON
    ContributorAuthor

    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 connect or wireless debugging, with SIMLOCK_PHYSICAL_ANDROID_NETWORK and SIMLOCK_PHYSICAL_ANDROID_APK set in .slow-lane.env. Then run scripts/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.

  5. added
    task:blockedAgent stopped on a blocker in its handoff. Maintainer re-adds the label it came from.
    and removed
    task:readySpec checked. An agent may implement it once its Depends on allow.
    on Nov 16, 2026
  6. removed their assignment
    on Nov 16, 2026
  7. V3RON commented on Nov 16, 2026

    @V3RON
    ContributorAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    platform:androidAndroid emulators or devicestask:blockedAgent stopped on a blocker in its handoff. Maintainer re-adds the label it came from.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions