Skip to content

A worker serves only enrolled devices on a platform whose virtualDevices is false #1598

Closed

Description

@V3RON

Part of #1588.

Scope

An operator sets android.virtualDevices or ios.virtualDevices to false and restarts the worker. From then on the worker serves only enrolled physical devices on that platform:

  • a lease without --physical (or physical: true) is refused at once with UNKNOWN_MODEL and a message naming the key and how to ask for a physical device;
  • the warm pool boots nothing on that platform;
  • idle simulators or emulators of that platform are deleted at start;
  • simlock catalog and catalog.get say virtual devices are off;
  • simlock doctor names the key for a warm target it can no longer meet.

Phone leases, the other platform and components work as today.

A user would notice: an emulator still booting on a phones-only worker, a --physical lease refused or stuck, an idle device of the other platform deleted, or a worker that fails to start after the change.

Technical spec

Commit 5e639b4.

Rows

Behaviours: B1, B2, B3, B4, B5, B6, B7, B10
Stored state: S1
Interfaces: I1, I2, I4, I5, I6, I7, I8, I9
Existing code: X1, X2, X3, X4, X5, X6, X7, X8, X9, X10, X14, X15, X16, X17 (the worker pages), X18

Facts

# Fact Source
F1 Today config set refuses an unknown key and a non-boolean with exit 2 and these texts node dist/cli/main.js config set android.virtualDevices false on main printed Invalid config after setting android.virtualDevices: Unknown config key: "android.virtualDevices"; config set devices.autoEnroll no printed Invalid config value for "devices.autoEnroll": expected a boolean
F2 ManagedDeviceLifecycle.shutdown and destroy take the initiator from the caller, and destroy claims only provisioning, shutdown or quarantined devices, so a ready one is shut down first src/core/managed-device-lifecycle.ts:168, :190-201
F3 A top-level ios or android key in a gateway's config is warned about and ignored, since neither is in the gateway's key list src/core/config-role-checks.ts:64-72, :95-96
F4 Leasing's resolver reads the catalog through core.drivers (the DriverCatalog) src/leasing/create-leasing.ts:153, src/leasing/acquisition-ports.ts:62

Modules touched

src/core/ (config-types.ts, config-defaults.ts, config-validators.ts, core-ports.ts (CatalogReader), driver-catalog.ts, create-core.ts, startup-converger.ts, doctor.ts, doctor-findings.ts, doctor-types.ts, warm-pool/policy.ts, warm-pool/converger.ts (passes the key into the policy view, :662-667), AGENTS.md, warm-pool/AGENTS.md), src/leasing/ (acquisition-spec-resolver.ts, acquisition-errors.ts, acquisition-ports.ts, AGENTS.md), src/contract/ (status-schemas.ts, protocol.ts), src/cli/commands/catalog.ts, the hand-built config slices that CoreConfig and DoctorConfig gaining ios and android breaks (src/leasing/test-create-leasing.ts:50, test-physical-device-watcher.ts:45, test-lease-end-participants.ts:106, src/core/test-doctor.ts:118, src/core/nuke.test.ts:305, src/core/reaper.test.ts:60, src/leasing/physical-leasing.test.ts:43), docs/internal/EVENTS.md, docs/internal/flows/device-selection.md, docs/internal/flows/startup.md (B5's step, :63-72), and the website pages reference/configuration.mdx, using-devices/physical-devices.mdx, using-devices/errors.mdx, reference/errors.mdx, reference/events.mdx, worker/troubleshooting.mdx (the doctor finding), worker/capacity.mdx (unknown-model at :222, and the off platform's reserve). Searches: listCatalog\(, resolveSpec\(, UnknownModelError, platformCatalogSchema, StartupConverger, unreachableTarget, DoctorConfig, defaultModels in src/core/config-*.

flowchart LR
  cfg[core config: virtualDevices] --> dc[core DriverCatalog]
  dc --> res[leasing resolver]
  dc --> st[core startup converger]
  dc --> cat[contract catalog entry]
  cat --> cli[cli catalog]
  cfg --> doc[core doctor]
Loading

Rules in play

  • ADR 0084 §1–3: core keys, refused in the one resolve step, empty catalog entry with the field.
  • ADR 0065: the key is core's, so no driver definition file changes.
  • ADR 0022: a --physical request skips resolution and stays as it is (X4).
  • src/contract/AGENTS.md (Protocol version): I5 bumps max by one in this PR; min stays, since an older peer strips the field.
  • src/core/AGENTS.md: "Warm pool and startup never install"; "Destroy only what the registry holds" (B5 deletes registry devices only, through ManagedDeviceLifecycle).
  • Documentation rule 9: the website pages above change in this PR.

Tests

Seam: the worker dispatcher with fake drivers (model: src/daemon/dispatcher-leases.test.ts, src/daemon/dispatcher-components.test.ts), StartupConverger (model: src/core/startup-converger.test.ts), the warm-pool converger (model: src/core/warm-pool/converger-targets-passes.test.ts), doctor (model: src/core/doctor-warm-pool-targets.test.ts), config (model: src/core/config-platform-and-driver-settings.test.ts) and the CLI (model: src/cli/index-catalog-components.test.ts).

  • B1: <platform>.virtualDevices loads and config set writes it: android false; ios false; unset (true); no (refused, expected a boolean); 0 (refused); a gateway's config holding it (warned and ignored)
  • B2: a plain lease on a phones-only platform is admitted, then refused with I2: no model; named model; OS range; image tag; allowDownload; baseline; noWait; iOS slim with except; the other platform still granted; the fake driver's resolveSpec, listCatalog and installComponent never called
  • B3: a --physical lease on a phones-only platform: free phone (granted); every match leased (waits); same with noWait (NO_CAPACITY); no enrolled match (UNKNOWN_MODEL, today's message)
  • B4: the warm pool on a phones-only platform: configured target (short unknown-model, no boot); learned kind from before (forgotten); reserveRunning.android: 2 (counts as 0: an iOS target on a tight global budget fills, and doctor's room leaves it out); iOS target (filled)
  • B5: startup on a phones-only platform: ready idle (shutdown then deleted, initiator virtual-devices-off); shutdown idle (deleted); leased (kept, deleted at release, lease-end); claimed (left); enrolled phone; iOS idle device (kept); a saved baseline (still listed); destroy throws (I6, shutdown); shutdown throws (I6, ready)
  • B6: the catalog of a phones-only worker: --platform android; no platform (both entries, iOS full); --json; the driver's listCatalog never called for Android
  • B7: components on a phones-only platform: install an Android image; list; remove
  • B10: doctor with a warm target on a phones-only platform: Android target, key false (I8); same target, key true, unknown model (today's text); iOS target with Android off (today's findings)

Done when

Out of scope

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. 2 remaining items

  5. added a commit that references this issue on Nov 17, 2026
    e9595de
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

task:readySpec checked. An agent may implement it once its Depends on allow.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions