Skip to content

A worker refuses the iOS modes it does not serve (ios.modes, MODE_UNAVAILABLE) #1651

Open

Description

@V3RON

Part of #1645.

Scope

An operator sets ios.modes on a worker, and from then on the worker refuses at once, with MODE_UNAVAILABLE, every iOS lease whose mode it does not serve. Its warm pool boots no device of that mode, doctor reports a warm target that cannot be met, and simlock catalog shows the served modes. A gateway does not route by them yet.

If this goes wrong, a user on a slim-only worker still gets a full simulator, or a lease of a served mode is refused.

Technical spec

Commit 1cd9315.

Rows

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

Facts

# Fact Source
F1 Today config set ios.modes is refused as an unknown key, exit 2 node dist/cli/main.js config set ios.modes '["slim"]' on main, with a scratch HOME, printed {"error":{"code":"USAGE","message":"Invalid config after setting ios.modes: Unknown config key: \"ios.modes\""}} and exited 2
F2 config set checks a value by loading the whole config, so a cross-key check in loadConfig refuses it too src/cli/commands/config.ts:56-60, src/core/config.ts:202-215
F3 A list config value is passed as JSON on the command line website/src/content/docs/docs/gateway/routing.mdx:51 (config set gateway.admission.command '["bun",…]')
F4 stringArray is the existing list validator src/core/validation.ts:160
F5 The defaults are merged before the checks run, so "ios.defaultMode unset" is read from the file and the overrides, not from the merged config src/core/config.ts:180-193

Modules touched

src/core/ (config-types.ts, config-defaults.ts, config-validators.ts, config.ts, create-core.ts, domain.ts (TargetRefusal), src/core/doctor.ts:543 (passes the served modes to unreachableTarget), doctor-findings.ts, doctor-types.ts, warm-pool/policy.ts, warm-pool/catalog-check.ts, warm-pool/converger.ts, AGENTS.md, warm-pool/AGENTS.md), src/leasing/ (acquisition-spec-resolver.ts, acquisition-errors.ts, create-leasing.ts:57, :160, acquisition-ports.ts:66, the test helpers src/leasing/testing.ts:57 and test-create-leasing.ts:130, AGENTS.md), src/daemon/ (error-code.ts, lease-request-refusal.ts, worker-composition.ts, dispatcher-status.ts, the test helper src/daemon/test-dispatcher.ts:194), src/contract/ (errors.ts, config-schemas.ts, status-schemas.ts, report-schemas.ts, protocol.ts), src/http/lease-declarations.ts, src/cli/commands/catalog.ts, the hand-built CoreConfig and DoctorConfig slices that a new ios field breaks (found by the typecheck), docs/internal/flows/device-selection.md, and the website pages reference/configuration.mdx, reference/errors.mdx, using-devices/errors.mdx, using-devices/choosing-a-device.mdx, worker/capacity.mdx, worker/configuration.mdx, worker/troubleshooting.mdx (the doctor finding). Searches: defaultMode, defaultModes, checkedSpec, baselineSpec, refusalOf, TargetRefusal, warmPoolShortSchema, unreachableTarget, DoctorConfig, CatalogCheck, #withDefaults, ERROR_TABLE.

flowchart LR
  cfg[core config: ios.modes] --> res[leasing resolver]
  cfg --> wp[core warm-pool catalog check]
  cfg --> doc[core doctor]
  res --> err[daemon error code and details]
  cfg --> cat[daemon catalog.get]
  cat --> cli[cli catalog]
Loading

Rules in play

  • ADR 0082 §1–3: the key, the check on the asked and resolved modes, the new code.
  • ADR 0007 §2: the default is still resolved once, in the resolver; §5 stays true (a full request never gets a slim device).
  • ADR 0065: the key is core's, beside defaultMode, so no driver definition file changes.
  • src/contract/AGENTS.md (Protocol version, Adding an operation step 7): I2 and I3 bump max by one in this PR, together; min stays, since an older peer strips the field and relays the code.
  • src/core/AGENTS.md: "A part takes the config sections it reads" (CoreConfig and DoctorConfig gain only ios).
  • Documentation rule 9: the website pages above change in this PR.

Tests

Seam: the worker dispatcher with fake drivers (model: src/daemon/dispatcher-leases-device-mode.test.ts), core with leasing and the warm pool over fake drivers, through the real resolver, for B3 and B4 (model: src/leasing/create-leasing-warm-targets.test.ts; B4 then reads doctor's findings over those figures, as src/core/doctor-warm-pool-targets.test.ts does), config (model: src/core/config-platform-and-driver-settings.test.ts) and the CLI (model: src/cli/index-catalog-components.test.ts).

  • B1: ios.modes loads and config set writes it: every row of the config Examples table; unset (both, default full); ["full"] with the default unset; a gateway's config holding it (warned and ignored)
  • B2: an iOS lease whose resolved mode is not served is refused with I2 and its details: no mode, slim, full, slim below 18.5, no mode below 18.5, full baseline, slim baseline, noWait, --physical, Android, --mode full --allow-download of a missing version (installComponent never called), slim --allow-download below 18.5 (installed, then refused); ["full"] with --mode slim; unset with --mode full (granted)
  • B3: the warm pool without full: full target (short mode-unavailable, nothing booted); mode-less target on iOS 17.5 (short); slim target on 26.1 (filled); learned full kind (forgotten); learned kind of a full baseline (forgotten); ["full"] with a learned slim kind (forgotten); a full idle device from before (not in targeted())
  • B4: doctor with a target the worker cannot meet: full target with ["slim"]; slim target with ["full"]; both with the key unset (no finding)
  • B5: the catalog of a one-mode worker: ["slim"]; ["full"]; unset (no field, Modes served: slim, full); --json; Android entry (no field, no line)

Done when

  • pnpm test:changed passes, with every Tests line above as a test.
  • pnpm check passes, the protocol-bump check included: max is one above the value main holds when this lands.
  • The website build passes: pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs.
  • reference/errors.mdx lists MODE_UNAVAILABLE under exit 12 and in the code table, and reference/configuration.mdx has the ios.modes row.

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 17, 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 17, 2026
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

    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