Configurable boot deadlines for full iOS simulators and Android emulators

Part of #1311.

Scope

An operator sets how long a full iOS simulator boot (ios.full.bootTimeoutMs) and an Android emulator boot (android.bootTimeoutMs) may take. Both default to 300 s, up from today's fixed 120 s (iOS, F1) and 180 s (Android, F8). The whole feature in one PR: two config keys, the two drivers, the daemon wiring, config.get, the docs.

In short

A full iOS boot now waits ios.full.bootTimeoutMs (300 000 ms unless set, counted from the end of simctl boot) and an Android boot waits android.bootTimeoutMs (300 000 ms unless set, counted from the emulator's spawn) before giving up. A slim iOS boot keeps ios.slim.bootTimeoutMs. The timeout's message stays Timed out waiting for device to boot: <device id> (F13).

flowchart LR
  A[config.json] --> B[loadConfig]
  B --> C[discoverDrivers]
  C --> D[iOS driver]
  C --> E[Android driver]
  D --> F["full boot, recovery boot, seed boot: ios.full.bootTimeoutMs (changed)"]
  D --> G[slim boot: ios.slim.bootTimeoutMs]
  E --> H["every emulator boot: android.bootTimeoutMs (changed)"]
  E --> I[emulator exit wait at shutdown and delete: 180 s fixed]

If this goes wrong, a user sees one kind of boot (a seed, a recovery, an Android copy) still fail at the old deadline.

Technical spec

Facts

Commit 85944c1f6.

Modules touched

Searches: BOOTSTATUS_TIMEOUT_MS (5 hits, one file), readinessTimeoutMs (src, non-test: android/index.ts, emulator.ts, testing.ts), bootTimeoutMs (src, non-test: core/config.ts, contract/schemas.ts, drivers/ios/index.ts, daemon/main.ts), SEED_MAKE_CEILING_MS (one file).

• src/core/config.ts: type, defaults, validators for ios.full.bootTimeoutMs and android.bootTimeoutMs.
• src/contract/schemas.ts: configSchema gains both.
• src/daemon/main.ts: passes both to the drivers.
• src/drivers/ios/index.ts: the full deadline comes from the option.
• src/drivers/android/index.ts, emulator.ts, seeds.ts: the boot deadline comes from the option; the exit waits keep 180 s; the seed make ceiling covers two boots.
• Docs: F20 pages, F21 manuals.

flowchart LR
  config["core/config.ts (changed)"] --> main["daemon/main.ts (changed)"]
  main --> ios["drivers/ios/index.ts (changed)"]
  main --> android["drivers/android (changed)"]
  schemas["contract/schemas.ts (changed)"] --> dispatcher[daemon/dispatcher.ts config.get]

Contract and event changes

configSchema (config.get's output, F6) gains ios.full: { bootTimeoutMs: number } and android.bootTimeoutMs: number. This PR bumps the protocol by one. No event changes. Bounds come from loadConfig: a positive number, else the daemon refuses to start naming the key (F5).

Other code on the same state

Searches: the two deadlines' uses (F1-F4, F8-F11), the stale-making sweeps (STALE_MAKING_MS, SEED_MAKE_CEILING_MS), boot estimates (COLD_BOOT_ESTIMATE_MS, SEED_MAKE_ESTIMATE_MS), the gateway's leaseRequestTimeoutMs.

• iOS stale making sweep (F14): never runs during a make of its kind, so a longer seed boot cannot be swept. No change.
• Android seed sweep (F12): a make takes two boots plus steps bounded at up to 430 s in all (F22); at the 300 s default that is about 1030 s, past today's 900 s, so a running make would be removed. The ceiling becomes the larger of 900 s and twice android.bootTimeoutMs plus 600 s (1200 s at the default). avdmanager create has no limit of its own, as today.
• Boot estimates and Doctor's stall threshold read the estimate, not the deadline: unchanged.
• Gateway leaseRequestTimeoutMs (5 min): a cold lease that makes a seed can now take up to two deadlines. Slim already can (600 s). No change.

Failure modes

A restart in the middle writes nothing new: the deadline is read at start. Two boots at once each count their own deadline.

Rules in play

• ADR 0002 §8: "a --full device, a runtime below the floor, or a recovery boot keeps the normal deadline": the normal deadline becomes ios.full.bootTimeoutMs.
• ADR 0060 §5: "ios.slim.bootTimeoutMs keeps its meaning ... and its default": unchanged.
• Contract rule: "Every change to a contract shape bumps it by one in the same PR": bumped.
• Documentation rule 9: the public config surface changes, so the F20 pages change in this PR.

Tests

Seams: IosSimctlDriver in src/drivers/ios/index.test.ts (model: the slim deadline test, F15), AndroidDriver in src/drivers/android/index-lifecycle.test.ts, loadConfig in src/core/config.test.ts, Dispatcher in src/daemon/dispatcher.test.ts, discoverDrivers in src/daemon/main.test.ts. The tests pinning 120 s (F15) move to 300 s. The Android tests that pass readinessTimeoutMs: 0 to make the exit wait instant (F16; index-lifecycle.test.ts:712, :739, :771) advance the fake clock past 180 s instead; Tests line 4 extends the one at 712. About 21 test files build a full config by hand and gain the two new fields.

• An operator's full iOS boot waits ios.full.bootTimeoutMs, then fails with BootTimeoutError: prepare full; prepare slim on an iOS 18.4 runtime; recover full; recover slim; prepare slim on iOS 18.5 keeps ios.slim.bootTimeoutMs; key unset (300 s) and set (400 s).
• A provision that makes a new iOS seed boots the seed within ios.full.bootTimeoutMs: key unset (300 s); key set (400 s).
• An Android boot waits android.bootTimeoutMs, then fails with BootTimeoutError: prepare from the snapshot; recover; a seed's two cold boots; a second makeReady while the device still boots; key unset (300 s) and set (600 s).
• An Android shutdown or delete waits 180 s for the emulator to exit, whatever android.bootTimeoutMs is: key 600 s, emulator never exits.
• An Android seed still being made is kept by a source listing while its two boots may still run: android.bootTimeoutMs 600 s, listing 1000 s into the make: kept; listing past the larger of 900 s and twice android.bootTimeoutMs plus 600 s: removed.
• An operator's config sets the two keys, or leaves them out: both unset (300000 each); both set; 0, -1, "300000" each refused naming the key.
• An admin reads the config and sees both keys: defaults; set values.
• A worker starts its drivers with the two keys from its config: iOS key set; Android key set.

Done when

• pnpm test:changed passes, and holds the eight Tests lines above.
• The configuration reference has a row for each key with its default (300000, 5 min); capacity's slim note, its boot-failed row and the requirements 180 s line point to the right key.
• The iOS and Android manuals' timer tables name both keys.

Out of scope

• Admission under memory pressure (#1246).
• The boot estimates, the BootTimeoutError text, the 30 s per-simctl call, the slim readback, Android's snapshot save and power-off waits.

Depends on

Written by an agent.