An operator installs a runtime or system image with one command

[V3RON]

Request: none

Supersedes #78.

Problem

Simlock installs an iOS simulator runtime or an Android system image only as a side effect of a lease request that passes --allow-download. An operator cannot prepare a machine before agents use it. The first agent that needs a missing runtime waits 10 to 20 minutes for a multi-GB download.

#191 removes lease-triggered downloads through a gateway. After it, a fleet worker has no Simlock way to get a new runtime at all.

Who it is for

An operator setting up a machine, or adding a runtime to one that is already serving agents.

Outcome

• One command installs a named iOS simulator runtime or Android system image. No lease is requested and no device is created.
• A component is named by platform and version: ios 26.4 is the iOS 26.4 simulator runtime, android 35 is the system image for API level 35.
• The command shows progress while it runs and ends with a clear result: installed, already installed, or failed with the reason.
• Running it again for an installed component changes nothing and succeeds.
• A platform runs one download at a time. A request for another component on that platform waits its turn.
• One component is never downloaded twice at the same time. A request that names it the same way joins the download already running, whether it came from this command or from a lease request. A request that names it another way, the newest runtime beside a version, waits its turn and starts no download if the first one made the component available.
• Each joined request gets its own result. A failure is reported to every request that joined that download.
• It is admin-only. An agent session or an agent token is refused.
• downloads.policy: "never" refuses it, the same as it refuses a lease-triggered download. With on-request or always the command itself is the consent.
• Android license consent stays its own switch, downloads.acceptAndroidLicenses.
• A call has one time budget, downloads.timeoutMs, counted from the moment it is made. Waiting for a turn uses it up too; it does not start again when the download starts. A call that runs out fails, and one still waiting never starts a download.
• The free-disk check runs before the download starts. Disk is set aside for a download for as long as it runs: downloads running at the same time are counted together, and one that would not fit beside the others is refused before it starts.
• The amount set aside is a fixed estimate per platform. Neither platform installer reports a size before it downloads.
• The installed component appears in the catalog without a daemon restart.
• The same operation is reachable over HTTP with an operator token.
• --allow-download on a lease request keeps working on a single node as it does today.

Non-goals

• Installing prerequisites. Xcode, the JDK, and the Android cmdline-tools, emulator and platform-tools packages stay the operator's job.
• Installing through a gateway. That is a separate feature.
• Removing a component. That is a separate feature.
• A new listing command. The catalog already lists what is installed.
• Choosing between several installed Xcode versions. Simlock uses the one xcrun resolves to.
• Installing at daemon start from a configured list.
• Resuming an install after a daemon restart. Running the command again is the recovery.
• Holding disk space against other programs. Simlock counts only its own downloads; the installers write to locations Simlock does not control.

Completion conditions

• On a machine without the component, the command installs it, and simlock catalog then lists it. Checked by hand on real hardware for one iOS runtime and one Android system image, and by an e2e test with the fake driver.
• The same command run again reports "already installed" and starts no download.
• Two install commands and one lease request for the same component, started together, cause one installer run, and all three end with a result.
• The same iOS runtime asked for once as the newest and once by its version, at the same time, causes one installer run.
• With downloads.policy: "never" the command fails, names the policy, and starts no download.
• An agent session gets FORBIDDEN.
• With too little free disk the command fails before any download starts and names required and available bytes.
• An iOS and an Android component that fit one at a time but not together: the first starts, the second is refused before its download starts.
• component.install-started and component.installed or component.install-failed are emitted once per install, not once per request that joined it.
• docs/CLI.md, docs/HTTP-API.md and docs/CONFIGURATION.md describe the command and how downloads.policy applies to it.

Open questions

Decisions

• ADR 0010 — Components are installed, recorded and removed through one owner in the core: the driver verb, the single installer, how downloads.policy applies, the record of installs, and the wire. Accepted — not yet implemented.

Tasks

1. Lease-triggered downloads go through one installer in the core #216: Lease-triggered downloads go through one installer in the core.
2. simlock component install installs a component from the CLI, the client and HTTP #217: simlock component install on the CLI, the client and HTTP.

Written by an agent.

[V3RON]

Spec updated: Outcome now fixes how a component is named (ios 26.4, android 35); Open questions is empty.

Written by an agent.

[V3RON]

Spec updated: Outcome (one download per platform, fixed disk estimates), Decisions (ADR 0010, Proposed) and Tasks (#216, #217) added.

Written by an agent.

[V3RON]

Spec updated: Outcome now says downloads.timeoutMs is one budget per call, waiting included.

Written by an agent.

[V3RON]

Spec updated: Outcome says which requests join a download and which wait their turn; Decisions marks ADR 0010 accepted.

Written by an agent.

[V3RON]

Spec updated: one completion condition now names two platforms, since one platform runs one download at a time.

Written by an agent.

[github-actions]

All 2 sub-issues are closed. If the completion conditions hold on main, close this feature and flip its ADRs to Accepted.

[V3RON]

All sub-issues are done: #216 (#225), #217 (#228). Progress reporting on real hardware continues in #240.