Warm pool keeps a spare learned copy while its copies are held

Start with evaluate in src/core/warm-pool/policy.ts and the listed cases for learned and configured kinds; the issue identifies these as the main planning seam. Then read task #1381 and ADR 0069, which define the chosen behavior. Done means all four completion conditions in #1381 are met, including the e2e cases in e2e/warm-pool-learned.test.ts.

Request: #1371

Problem

From #1371: once the warm pool has learned a baseline (demo, iOS), a lease of it starts in 0 s. But while that warm copy is leased, no spare copy boots. Releasing it and leasing again 2 s later boots a new copy (38 s). The capacity docs say the warm pool "keeps idle devices booted, so a lease starts without waiting for a boot".

The pool counts a learned kind's leased copies as copies it still has, because they used to come back ready on release. They no longer do: every simulator and emulator is destroyed after one lease. So while every copy of a kind is leased, the pool keeps none ready, and the next lease waits for a boot. Plain learned kinds behave the same way as baselines.

Who it is for

An agent, or a person, who leases the same kind of device again while another lease of that kind is still held. For example, a second agent asks for the demo baseline while the first agent still holds it.

Outcome

While the worker has room, a lease of a learned kind starts without waiting for a boot, also when every other copy of that kind is leased. While copies are leased, the pool keeps at least one spare ready, and never more than the busiest moment of the last 24 hours.

How it works for the user

sequenceDiagram
  participant A as Agent 1
  participant B as Agent 2
  participant W as Worker
  A->>W: lease --baseline demo
  W-->>A: the ready copy, 0 s
  W->>W: boots one spare copy (was: nothing)
  B->>W: lease --baseline demo
  alt room for the spare
    W-->>B: the spare, 0 s
  else no room (running limit, RAM)
    W-->>B: waits for a boot, as today
  end

Before:

$ simlock lease --platform ios --baseline demo --detach   # copy 1 leased, 0 s
$ simlock lease --platform ios --baseline demo --detach
{"push":"progress","stage":"booting","etaMs":60000}       # 38 s

After:

$ simlock lease --platform ios --baseline demo --detach   # copy 1 leased, 0 s
$ simlock lease --platform ios --baseline demo --detach   # the spare, 0 s

Examples

Copies of one learned kind kept ready. Peak: the most leases of that kind held at the same moment in the last 24 hours, at least 1.

Peak	Leased now	Today	After
1	0	1	1
1	1	0	1
3	1	2	2
3	3	0	1
3	0 (burst just ended)	3	3

A configured target (warmPool.targets) is unchanged: it keeps its count ready, whatever is leased.

What could go wrong

• During a held burst a worker runs one more device per learned kind, so on a full worker another kind may be pushed out or reported short. Likely on small Macs; by design.
• If the spare is not booted, leases keep waiting for a boot as today. Users would see a lease time of tens of seconds where 0 s was expected.

Words used

• learned kind: a kind of device the warm pool keeps ready because it was leased, not because the config names it, e.g. iPhone 17 on iOS 26.0, or the demo baseline.
• peak: the most leases of one learned kind held at the same moment in the last 24 hours, at least 1, e.g. 3 after three agents held demo at once.
• spare: a ready, unleased copy of a learned kind, kept so the next lease does not wait.

Non-goals

• No change to configured targets, the budget (running limit, RAM, boot cap), displacement or which kinds are learned.
• No new config key, status field or event. status keeps showing a learned kind's count as its peak.
• Not the wording of warmPool.enabled in the configuration reference; that is #1373.

Completion conditions

• With a learned kind of peak 1 whose only copy is leased, the pool plans one new copy of it.
• With a learned kind of peak 3 and three copies leased, the pool plans one new copy, not three.
• On a worker with room for two devices, a second lease of a kind made while the first is held is granted warm.
• The capacity and how-it-works pages say a spare is kept while copies are leased.

Open questions

none

Decisions

• ADR 0069 — A learned kind keeps one ready copy while its copies are leased (PR #1378): a learned kind keeps max(peak − leased, 1) ready, replacing ADR 0038 §2's "leased and reclaiming copies count as had".

Shared values

none

Behaviours

Behaviour (invoker, action, what it sees)	Seam	Cases	Task
A warm pool pass over a learned kind plans enough copies to keep max(peak − leased, 1) ready, counting copies on their way, for a plain kind and a baseline kind alike	evaluate in src/core/warm-pool/policy.ts	peak 1, 1 leased → 1 new; peak 1, 1 reclaiming → 1 new; peak 1, 1 ready under a claim → 1 new; peak 3, 3 leased → 1 new; peak 3, 2 leased + 1 reclaiming → 1 new; peak 3, 1 leased + 1 ready → 1 new; peak 3, 3 leased + 1 boot in flight → none; baseline kind demo peak 1, 1 leased → 1 new; baseline kind demo peak 2, 2 copies of version 1 leased while version 2 is newest → 1 new	#1381
A pass over a kind both configured and learned plans the larger of what each count lacks	evaluate	configured 1 + learned peak 2, 1 leased, 0 ready → 1 new; configured 2 + learned peak 1, 1 leased, 0 ready → 2 new	#1381
A worker with no targets and room for a second device, holding a lease of a kind, grants the next lease of that kind warm, and after a release makes a new ready copy in place of the deleted one	withDaemon with the fake iOS driver script, e2e/warm-pool-learned.test.ts	first lease held → a second ready copy appears and a second lease is granted warm while the first is held; first released → a new ready copy of the kind, not the released device	#1381

Tasks

• #1381 A learned kind keeps one ready copy while its copies are leased — the next lease of a learned kind no longer waits for a boot while its other copies are held. Risk: one more running device per kind during a burst.

Completion conditions: all four by #1381.

Open work in the same area:

• #1373 (bug, configuration reference wording of warmPool.enabled): another page and line; no Depends on.
• #1363 / PR for ADR 0068 (memory pressure pauses warming): pauses passes, does not change the learned count; no Depends on.
• #1143, #1144 (runtime warm targets, ADR 0056): change configured targets only; no Depends on.

Written by an agent.