Repository navigation
Description
Part of #327.
Scope
After this PR, a plain iOS lease gets a simulator that is a copy of a simulator Simlock booted once (the seed), so no iOS lease after the first of its kind waits for a factory first boot (36.4 s measured, F1). Seeds live in their own simctl device set, apart from the set leases use, so a lease holder's simlock simctl never lists, boots or changes one. Every simulator and emulator serves one lease and is destroyed when it ends, whatever lease.identity says; quarantine destroys a virtual device too, and never reclaims it. simlock doctor lists the seeds with their size, and simlock nuke --delete-devices deletes them.
It also adds the driver verbs every later task uses (provision with an optional source, listSources, destroySource) and the iOS source table. Android seeds are #1205: until #1205 merges, every Android lease creates a new emulator (the Android driver lists no sources).
One task: the one-lease rule and the seed cannot ship apart. Without the seed, one lease per simulator makes every iOS lease pay a first boot; without the rule, a reclaim would still erase a copy. Many existing tests that lease a released virtual device again change to expect a new device; that is most of the module count.
In short
Simlock now makes one shut-down simulator per model and iOS version, the seed, the first time a lease needs it, keeps it in a separate device set (the sources set), and copies it into the lease device set (simctl clone) for every lease. Every simulator and emulator is deleted when its lease ends, and the next lease gets a new copy with a new UDID. simlock doctor lists each seed with its size.
New term: seed, a simulator Simlock booted once and shut down, kept only to be copied and never leased. Example: the seed of iPhone 17 on iOS 27.0, made by the first lease of that kind.
flowchart LR
R[lease request] --> S{"seed of this<br/>model + OS?<br/>(new)"}
S -- no or stale --> M["make seed: create, boot,<br/>shut down (new)"] --> C
S -- yes --> C["simctl --set sources clone<br/>into the device set, marks,<br/>copy disabled.plist (new)"]
C --> B[makeReady: slim write, boot] --> L[lease]
L --> D["release: destroy<br/>(changed: was erase)"]
Before and after, on a Mac with iOS 27.0:
$ simlock lease --platform ios --detach | jq -r .device.driverDeviceId
4F1C… # first lease: create + first boot
$ simlock release <lease>
$ simlock lease --platform ios --detach | jq -r .device.driverDeviceId
4F1C… # today: the same simulator, erased, first boot again
9B07… # after: a new copy of the seed, booted in seconds
simlock doctor (stdout JSON) gains sources, one entry per source:
{"findings":[],"sources":[{"platform":"ios","kind":"seed","model":"iPhone 17","osVersion":"27.0","sizeBytes":1073741824}]}
sizeBytes is the seed's folder on disk in bytes, counted by Simlock once, when the seed is shut down after its first boot; it is absent when it could not be counted. A seed still being made is not listed. A stale seed carries staleReason, a phrase that reads after "is stale:", written by the iOS driver, one of these, word for word:
runtime <runtime id> is not installedruntime <runtime id> changed from build <old build> to <new build>device type <device type id> is not available
Log lines (warn, iOS driver logger), variable parts named:
could not copy the launchd overrides of seed <seed udid> to <copy udid>: <error>could not remove seed <seed udid> of removed runtime <runtime id>: <error>could not remove leftover source <udid>: <error>
If this goes wrong, a user sees a lease's simulator without Simlock's mark (a foreign-provenance-change finding), a seed in the lease device set, or every iOS lease waiting a full first boot again.
Technical spec
Facts
Commit dbc339d. (main with #1196 merged; src/core and src/leasing are the same as at 019ba5c except src/core/config.ts, two lines.)
| # | Fact | Source |
|---|---|---|
| F1 | simctl create + first boot to bootstatus -b takes 36.4 s; simctl erase 0.6 s then boot 39.3 s; simctl --set <s> clone <src> c1 2.3 s; a clone boots to bootstatus in 7.2 s; a cross-set simctl --set <sources> clone <src> c1 <device set> 0.2 s, the copy listed only in the destination set, with a file from the source's data/ |
spike on this machine, 2026-11-02: xcrun simctl create / erase / --set <s> clone + bootstatus -b → 36.4 s, 0.6 s + 39.3 s, 2.3 s, 7.2 s; xcrun simctl --set <sources> clone <src> c1 <set> → 0.2 s, simctl --set <set> list shows c1, --set <sources> list does not |
| F2 | The clone's folder holds data/ and device.plist only, no root simlock-mark.json; a file written in the source's data/ and a defaults write value are in the clone; no /private/var/tmp/com.apple.CoreSimulator.SimDevice.<clone udid> folder exists after the clone |
spike on this machine, 2026-11-02: ls <set>/<clone udid> → data device.plist; ls /private/var/tmp/com.apple.CoreSimulator.SimDevice.<clone udid> → no such file |
| F3 | provision runs simctl create simlock-<id> <devicetype> <runtime>, writes both marks, and under deviceSet: default deletes the new simulator when the mark write fails |
src/drivers/ios/index.ts:720-759 |
| F4 | #writeMark writes <root>/<udid>/data/simlock-mark.json then <root>/<udid>/simlock-mark.json, each {instanceId, token, udid, writtenAt} |
src/drivers/ios/index.ts:1364-1378 |
| F5 | makeReady writes the launchd overrides before the boot for a slim prepare, then boots and reads back; the overrides folder is <overridesRoot>/com.apple.CoreSimulator.SimDevice.<udid>, root a driver option (launchdOverridesRoot) |
src/drivers/ios/index.ts:761-788, :838-864, :874-876, :153-156, :193-194 |
| F6 | iOS reclaim of a simulator shuts down, runs simctl erase, rewrites the mark and returns {state: "shutdown", strategy: "erase"}; reclaimStrategy answers erase for a simulator |
src/drivers/ios/index.ts:936-954 |
| F7 | destroy shuts down, runs simctl delete, then removes the overrides folder, logging a failed removal |
src/drivers/ios/index.ts:960-977 |
| F8 | listManaged lists every simulator in the owned set (under default, those whose durable mark names this instance) as a device |
src/drivers/ios/index.ts:1022-1056, :1426-1429 |
| F9 | #bootAndWait boots, waits bootstatus -b and listapps under one deadline, and shuts down best effort on expiry; full boots get 120 s; any other simctl call 30 s |
src/drivers/ios/index.ts:799-817, :73, :69 |
| F10 | #shutdown treats "current state: Shutdown" as success |
src/drivers/ios/index.ts:1473-1482, :2207-2209 |
| F11 | A runtime from simctl list -j runtimes carries identifier, version, isAvailable and, when listed, buildversion as build |
src/drivers/ios/index.ts:243-250, :1793-1815 |
| F12 | removeComponent runs simctl runtime delete <identifier> and waits while it deletes |
src/drivers/ios/index.ts:521-540 |
| F13 | A driver's own table is a DeviceDataTable keyed by device_id; ios_device_data is owner ios-device-data version 1 |
src/core/driver.ts:21-24; src/drivers/ios/device-data.ts:35-64 |
| F14 | A schema owner is {name, version, migrations}; the worker opens state.db with the registry, warm pool, tokens and device-data owners |
src/ports/sqlite.ts:15-26; src/daemon/main.ts:352-363 |
| F15 | The Driver interface has provision(spec), reclaim, reclaimStrategy, destroy, listManaged and no source verbs |
src/core/driver.ts:231-311 |
| F16 | mayBeGranted is false only for a fresh device with a lastLeaseEndedAt; beginRelease stamps lastLeaseEndedAt on every lease end; a device takes leaseIdentity from lease.identity at registration, default reusable |
src/core/domain.ts:284-293; src/core/registry.ts:826, :249; src/core/config.ts:963 |
| F17 | On release, a device mayBeGranted refuses is shut down, committed shutdown, then destroyed and committed deleted with device.deleted initiator lease-end; any other virtual device goes through the driver's reclaim and device.reclaimed |
src/core/reclaim-coordinator.ts:96-103, :262-315 |
| F18 | Quarantine retries destroy a device mayBeGranted refuses and reclaim any other |
src/core/quarantine-coordinator.ts:229-236, :305-320 |
| F19 | Startup deletes idle shutdown devices mayBeGranted refuses; idle-shutdown shuts a ready device down once lastLeaseEndedAt is older than idle.shutdownAfterMs; idle-destroy deletes a shutdown one past idle.deleteAfterMs |
src/core/startup-converger.ts:64-71; src/core/cleanup/idle-shutdown.ts:6-20; src/core/cleanup/idle-destroy.ts:23-31 |
| F20 | The acquisition planner and the warm pool hand out or boot only devices mayBeGranted accepts |
src/leasing/acquisition-planner.ts:120-124, :142-146; src/core/warm-pool/policy.ts:174, :254 |
| F21 | The doctor report is {findings}; a worker builds it in reconcile |
src/contract/schemas.ts:854; src/core/doctor.ts:240-247 |
| F22 | nuke with deleteDevices shuts down and destroys every idle registry device; it reaches no driver |
src/core/nuke-service.ts:93-104, :128-136 |
| F23 | A removal is refused while a registry device or a provision claim uses the version; claimProvision refuses a provision of a version being removed |
src/core/component-installer.ts:408-410, :452-456, :468-472 |
| F24 | The Filesystem port has copyFile, rm, exists, mkdirp(path, {mode}) and directorySize |
src/ports/filesystem.ts:73-76, :88, :91 |
| F25 | The protocol is { min: 69, max: 69 } and every contract shape change bumps it |
src/contract/protocol.ts:13; src/contract/AGENTS.md:60-66 |
| F26 | The iOS smoke test asserts a second plain lease reuses the released simulator and the set holds one; the slim test asserts a re-lease gets the same UDID | e2e/slow-ios-smoke.test.ts:262-268; e2e/slow-ios-slim.test.ts:262 |
| F27 | The website says reusable wipes a released device and keeps it, fresh deletes it, and that Simlock wipes a device every time a lease ends |
website/src/content/docs/docs/worker/capacity.mdx:234-242; website/src/content/docs/docs/reference/configuration.mdx:63-64; website/src/content/docs/docs/worker/cleanup.mdx:41; website/src/content/docs/docs/using-devices/working-with-a-device.mdx:111, :118 |
| F28 | doctor.run without fix is an agent operation |
src/daemon/dispatcher.test.ts:950-960 |
| F29 | Under deviceSet: simlock the device set is an owned root (ensureOwnedRoot), default $SIMLOCK_HOME/devices/ios; under default it is Xcode's set and refuseOwnSetLeftovers checks the old own set |
src/drivers/ios/index.ts:341-366, :1715; src/core/device-root.ts:55 |
| F30 | simlock simctl adds --set <device set> itself and refuses a caller's --set; under simlock a lease's environment carries SIMLOCK_IOS_DEVICE_SET with the set's path; driver.passthrough is not checked against a lease |
src/drivers/ios/index.ts:1509-1513, :1321-1328, :1211-1213; src/daemon/dispatcher.ts:611-615 |
| F31 | The set-switch checks count only UDID-named folders of the old own set, and marked simulators in Xcode's set | src/drivers/ios/device-set-leftovers.ts:17-28, :30-50 |
| F32 | A BootTimeoutError from provision rejects the request with reason boot-timeout; any other provision error is retried once, then fails PROVISION_FAILED; classifyError maps no code for BootTimeoutError |
src/leasing/lease-acquisition-coordinator.ts:914-920, :931-944; src/daemon/error-code.ts:117-119, :191 |
| F33 | Quarantine retries reclaim a virtual device mayBeGranted accepts; a boot failure whose destroy fails, and doctor's stall fix, quarantine a device |
src/core/quarantine-coordinator.ts:229-236; src/core/device-provisioner.ts:125-142; src/core/AGENTS.md "How it works" 4 |
| F34 | The warm pool's provision runs beside a pass and does not stop when nuke starts (only new actions check maintenanceActive); nuke resets each registry device after releasing leases |
src/core/warm-pool/converger.ts:669-672, :781-795; src/core/nuke-service.ts:85-108 |
| F35 | Fast and slow e2e tests assert a released virtual device is reclaimed and kept, or wait for it to come back ready or shutdown (searches: device.reclaimed and waitForDeviceState(.*"(ready|shutdown)" in e2e/*.test.ts) |
e2e/lease-lifecycle.test.ts:63, :99, :103-111, :139, :338; e2e/warm-pool-reserve.test.ts:83; e2e/capacity-cleanup-nuke.test.ts:159, :173; e2e/daemon-lifecycle.test.ts:276, :315; e2e/held-lease-liveness.test.ts:89; e2e/startup-reconcile.test.ts:118, :188, :240; e2e/slow-agent-device.test.ts:385-396, :430-436; e2e/slow-warm-pool.test.ts:620-628; e2e/slow-android-tunnel.test.ts:595-620 |
| F36 | More website pages say a released device is wiped and kept | website/src/content/docs/docs/getting-started/first-lease.mdx:90; website/src/content/docs/docs/introduction/how-it-works.mdx:66; website/src/content/docs/docs/using-devices/agent-device.mdx:101 |
Modules touched
Searches: mayBeGranted, leaseIdentity, lease.identity, "fresh", provision(, reclaim(, reclaimStrategy(, implements Driver, doctorReportSchema, DoctorReport, NukeService, removeComponent(, refuseOwnSetLeftovers, driverDeviceId).toBe(, device.reclaimed and the same request must reuse in e2e/, wipe, keeps it and identity in website/.
flowchart LR
rc["core/reclaim-coordinator"] --> dom["core/domain mayBeGranted (changed)"]
q["core/quarantine-coordinator (changed: destroys every virtual device)"] --> drv
conv["core/startup-converger (changed: lists sources)"] --> drv
doc["core/doctor (changed)"] --> drv["core/driver Driver (changed)"]
nuke["core/nuke-service (changed)"] --> drv
prov["core/device-provisioner"] --> ios["drivers/ios (changed)"]
ios --> src["drivers/ios/source-data (new)"]
ios --> left["drivers/ios/device-set-leftovers (changed)"]
ios --> simctl[xcrun simctl]
ios --> fs[ports/filesystem]
main["daemon/main (changed)"] --> ios
main --> src
fake["core/fake-driver, e2e/fake-driver (changed)"] -.implements.-> drv
andr["drivers/android (changed: empty sources)"] -.implements.-> drv
sequenceDiagram
participant P as core provisioner
participant D as iOS driver
participant T as ios_source_data
participant S as simctl
P->>D: provision(spec)
D->>T: ready seed for this model + OS?
alt none, or stale
D->>T: row making
D->>S: --set <sources> create simlock-seed-<id>, mark, boot, bootstatus, shutdown
D->>T: row ready, size
end
D->>S: --set <sources> clone <seed udid> simlock-<id> <device set>
alt clone fails
D-->>P: throws (PROVISION_FAILED to the caller)
end
D->>D: write both marks, copy disabled.plist
D-->>P: device (new udid)
Files:
src/core/driver.ts(provision(spec, options?),listSources,destroySource,DriverSource),src/core/domain.ts,src/core/quarantine-coordinator.ts(every virtual device destroyed),src/core/reclaim-coordinator.ts(comments only),src/core/startup-converger.ts(onelistSourcesper driver before the warm pool starts),src/core/doctor.ts,src/core/nuke-service.ts,src/core/create-core.ts(wiring),src/core/fake-driver.ts,src/core/config.ts(comment onlease.identity),src/core/AGENTS.md.src/drivers/ios/index.ts,src/drivers/ios/source-data.ts(new),src/drivers/ios/device-set-leftovers.ts(the old mode's sources set counts),src/drivers/ios/AGENTS.md;src/drivers/android/index.ts(listSourcesanswers none,destroySourcethrows).src/daemon/main.ts(the source owner inowners, the database given to the iOS driver).src/contract/schemas.ts,src/contract/protocol.ts.- Tests:
src/drivers/ios/index.test.ts,src/daemon/dispatcher.test.ts,src/core/reclaim-coordinator.test.ts,src/core/quarantine-coordinator.test.ts,src/core/doctor.test.ts,src/core/nuke-service.test.ts, and every test that leases a released virtual device again (thedevice.reclaimedsearch:src/leasing/*.test.ts,src/core/registry.test.ts,src/core/warm-pool/converger.test.ts,src/core/reaper.test.ts,src/bus/index.test.ts,src/daemon/server.test.ts). e2e/slow-ios-smoke.test.ts,e2e/slow-ios-slim.test.ts;e2e/fake-driver/fake-driver.ts(the three verbs, R15); the tests that assert a reclaimed, kept virtual device (F35):e2e/lease-lifecycle.test.ts,e2e/warm-pool-reserve.test.ts,e2e/capacity-cleanup-nuke.test.ts,e2e/daemon-lifecycle.test.ts,e2e/held-lease-liveness.test.ts,e2e/startup-reconcile.test.ts,e2e/slow-android-tunnel.test.ts(waits for the released emulator to beready, then reads its adb rules; it now checks the rules are gone with the device),e2e/slow-agent-device.test.ts,e2e/slow-warm-pool.test.ts(each now expectsdevice.deletedinitiatorlease-end).- Docs:
docs/internal/EVENTS.md(device.reclaimednow only for physical devices),docs/internal/agent-rules/safety.mdrule 1 (the ADR 0061 §1 amendment: a driver may destroy its own sources), websiteworker/capacity.mdx,reference/configuration.mdx,worker/cleanup.mdx,using-devices/working-with-a-device.mdx,getting-started/first-lease.mdx,introduction/how-it-works.mdx,using-devices/agent-device.mdx(F27, F36),reference/cli.mdx(doctor, nuke),reference/events.mdx.
Surface and extension points
Driver gains three verbs every driver implements (architecture rule 19: what varies per platform is how a source is made and copied):
provision(spec: VirtualSpec, options?: { readonly source?: string }): Promise<DriverDevice>;
listSources(): Promise<readonly DriverSource[]>;
destroySource(sourceId: string): Promise<void>;
interface DriverSource {
readonly id: string;
readonly kind: "seed" | "baseline";
readonly model: string;
readonly osVersion: string;
readonly imageTag?: string;
readonly sizeBytes?: number; // absent when it could not be counted
readonly staleReason?: string; // reads after "is stale:", at most 300 characters
}listSources answers ready sources only; a making source of this process is never listed. model, osVersion and imageTag are the spec the source was made for (iOS has no image tag).
reclaim and reclaimStrategy are for physical devices only: the iOS driver, and both fake drivers, throw DriverCrashError("virtual devices are not reclaimed") for a simulator (#1205 does the same for Android). No core path calls them for a virtual device after this PR.
provision with no source copies the spec's seed, making it first when there is none or it is stale. With a source, it copies that source; an unknown or stale one throws DriverCrashError (core checks before calling, #1207). saveSource is not declared here (#1206). The iOS driver exports iosSourceDataOwner beside iosDeviceDataTable and takes database: SqliteDatabase in its options; nothing outside the driver reads ios_source_data (ADR 0036 §2).
Contract and event changes
This PR bumps the protocol by one. doctorReportSchema gains sources: an array of {platform, kind ("seed" | "baseline"), model, osVersion, imageTag?, sizeBytes?, staleReason?}; sizeBytes an optional non-negative integer, staleReason free text of at most 300 characters (the iOS ones are listed under In short; #1205 lists Android's). A source never makes findings non-empty. Daemon output only; no new input.
No event shape changes. docs/internal/EVENTS.md: device.reclaimed fires only for physical devices (a virtual device's lease end is device.deleted, initiator lease-end, F17).
ios_source_data (owner ios-source-data, version 1, STRICT, no JSON text): source_id TEXT primary key, kind TEXT (seed or baseline), spec_key TEXT (device type id and runtime id), udid TEXT nullable (null until simctl create answers), set_path TEXT (the sources set it was made in), device_type_id TEXT, runtime_id TEXT, runtime_build TEXT nullable (null when simctl list runtimes gave no build, F11; then only the runtime's presence is checked), model TEXT, os_version TEXT, state TEXT (making or ready), maker TEXT (a token the driver draws once per process), size_bytes INTEGER nullable, stale_reason TEXT nullable, created_at INTEGER. At most one ready seed per spec_key.
Where sources live (ADR 0061 §1): under deviceSet: simlock, the set <device set>/sources (made 0700 inside the owned root); under deviceSet: default, the owned root $SIMLOCK_HOME/devices/ios-sources (ensureOwnedRoot, platform ios). Every seed simctl call carries --set <sources set>; a copy is xcrun simctl --set <sources set> clone <seed udid> simlock-<id> <device set path> (under default, Xcode's set path). The row is written making before simctl create, and set ready with its size after the clean shutdown.
Other code on the same state
Searches: mayBeGranted (8 files outside tests), lastLeaseEndedAt (6), leaseIdentity (6), simctl verbs create|clone|delete|erase in src/drivers/ios (index.ts only), listManaged callers (doctor, startup read), /private/var/tmp (index.ts only).
- Acquisition planner, warm pool, idle cleanup and startup read
mayBeGranted(F18-F20). With every released virtual device refused, the planner and warm pool never pick one and startup deletes one leftshutdown. A device made before this PR that already ended a lease is refused at once and leaves through idle-shutdown, idle-destroy or the next start (F19), not through another lease. - Quarantine (F18, F33) is entered from a failed spent delete, a boot failure whose destroy failed, and doctor's stall fix, so a copy can be quarantined without serving a lease. Quarantine now destroys every virtual device, whatever
mayBeGrantedsays, and callsreclaimonly for a physical device. doctorand--purge-orphansreadlistManaged(F8), which lists the lease device set only. A seed is in the sources set, so it is never an orphan and never purged.- Startup:
core.convergecallslistSources()once per driver before the warm pool starts (a failure is logged and startup goes on). On that first call in a process the iOS driver destroys leftovers: eachmakingrow whosemakeris another process's (its simulator, if any, deleted, then the row), and nothing else: a simulator in the sources set that no row names is left in place, reported bydoctoras an orphan source, and destroyed only bydoctor --purge-orphans(decided in delivery, confirmed by the maintainer 2026-11-04). During the process, amakingrow of this process older than 300 s is destroyed by the next seed make of its kind; amakingrow of this process is never touched otherwise. An operator saves, lists and removes baselines on a worker #1206 builds its baseline cleanup on the same startup call. refuseOwnSetLeftoversandrefuseXcodeSetLeftovers(switchingdrivers.ios.deviceSet, F31) also count the UDID folders of the sources set the old setting used, so a switch with seeds left is refused like one with devices left;nuke --delete-devicesbefore the switch removes both.- Component removal (F23):
claimProvisionkeeps a provision, and so a seed make, off a version being removed; the driver deletes that runtime's seeds beforesimctl runtime delete. makeReady(ADR 0060) writes the copy'sdisabled.plistafter the copy step put the seed's there; the write merges, so the copy keeps the seed's entries it does not manage.nuke --delete-devicesdestroys every source of kindseedfromlistSources(R4; An operator saves, lists and removes baselines on a worker #1206 removes baselines). It runs under acquisition maintenance (F22), but a warm-pool creation already running keeps going (F34): its seed make is amakingrow nuke does not list, and its clone holds the seed's lock, whichdestroySourcealso takes, so nuke deletes the seed after that clone and the copy registers as a warm-pool creation does today.- A lease holder's
simlock simctladds--set <device set>and refuses a caller's--set(F30), so it never lists, boots or changes a seed, which is in the sources set.SIMLOCK_IOS_DEVICE_SETstill names the device set; undersimlockthe sources set is itssourcessubfolder, which an agent could only reach by runningxcrun simctl --seton that path by hand, outside Simlock. - Android: every emulator is a copy of a seed in its own folder, booted from its boot snapshot #1205 writes
android_source_dataand implements the same verbs; An operator saves, lists and removes baselines on a worker #1206 readslistSourcesand callsdestroySource; A lease names a baseline and gets a copy of it #1207 passessource. Shared values row "One lease per virtual device" is written here.
Failure modes
| Call | Outcome | What happens | Limit, counted from |
|---|---|---|---|
seed simctl create |
fails or times out | row deleted; provision throws; the request is retried once, then fails PROVISION_FAILED as today (F32) |
30 s, from the call |
seed boot to bootstatus -b + listapps |
times out or fails | best-effort shutdown, simctl delete of the seed, row deleted; provision throws DriverCrashError seed <udid> did not boot: <reason>, never BootTimeoutError (which would name no registry device), so the request ends PROVISION_FAILED after one retry |
120 s, from bootstatus (F9) |
seed simctl shutdown |
fails | seed deleted, row deleted; provision throws | 30 s, from the call |
seed directorySize |
throws | row ready with no size; doctor leaves sizeBytes out |
none (local) |
simctl clone |
fails or times out | provision throws, the lease fails PROVISION_FAILED; the seed stays |
30 s, from the call |
copy's #writeMark |
throws | as create today (F3): under default the copy is deleted; rethrown |
none |
copy disabled.plist |
absent | nothing copied | none |
copy disabled.plist |
throws | logged warn (In short), provision goes on |
none |
listSources catalog read |
fails | throws; doctor logs it and lists no sources for that platform; startup logs it and goes on, the leftover sweep runs on the next call |
30 s |
leftover sweep simctl delete |
fails | logged warn (could not remove leftover source), row kept, the call goes on |
30 s |
iOS reclaim / reclaimStrategy of a simulator |
called | throws DriverCrashError("virtual devices are not reclaimed"); a programming error, no core path calls it |
none |
destroySource simctl delete |
fails | throws, row kept; nuke logs and goes on; runtime removal logs the line under In short and goes on | 30 s |
| core release of a virtual device | destroy fails | quarantine, strategy delete, as a fresh device today (F17) |
as today |
| quarantine retry of a virtual device | destroy fails | counted retry; out of retries device.quarantine-stranded, as today |
as today |
A restart during a seed make leaves a making row of another process: the startup sweep deletes its simulator and the row, and the next provision of that kind makes the seed again. A restart between clone and the mark leaves an unmarked simulator in the set, which doctor reports as an orphan device, as after create today. Two provisions of one kind at once make one seed: the second waits for the first's make, and clones of one seed run one at a time.
Rules in play
- ADR 0061 §1: "A source is a device that has booted at least once, was shut down cleanly, and is never leased, booted or erased again" and "iOS sources are in their own
simctldevice set" — the seed, the sources set, its table and the verbs; "amakingrow an earlier daemon process left, and a source with no row, are destroyed at start" — the startup sweep. - ADR 0061 §2: "Every virtual device is spent after one lease: core's release path destroys it" and "Quarantine destroys a virtual device and never reclaims it" —
mayBeGranted, quarantine, the throwingreclaim, and the iOS copy step (clone, both marks,disabled.plist). - ADR 0061 §3: "A stale seed is destroyed and made again on the next provision" and "Removing a runtime or system image destroys the seeds made from it".
- ADR 0060 §1 and §4: the slim file is written before the copy's boot;
destroyremoves the copy's overrides folder (F7). - ADR 0036 §2: "Each owner creates its own tables" —
ios_source_data, columns only. - Safety rule 1, as ADR 0061 §1 amends it ("A driver may destroy its own sources"):
destroySourceand the sweep delete only simulators in the sources set, by a UDID the table holds or, underdoctor --purge-orphans, one no row names;safety.mdgains the amendment. - Safety rule 8: "
simlock-/simlock_naming is a cosmetic label" — a seed is known by its row, not itssimlock-seed-name. - Architecture rule 2: only the iOS driver runs
simctland reads its table. - Contract "Protocol version": the doctor report shape bumps it.
- Documentation rule 9: the website pages in F27 and the doctor and nuke reference change here.
- Testing rule 7: the one-lease claim extends "is never erased: its lease end is a shutdown and a delete" (
src/core/reclaim-coordinator.test.ts:527).
Tests
Seam: the daemon dispatcher with the fake driver (src/daemon/dispatcher.test.ts, model Dispatcher: nuke.run at :1568), and IosSimctlDriver with ScriptedProcessRunner and MemoryFilesystem where a case is iOS-only (src/drivers/ios/index.test.ts, model the slim mode block at :1978).
- An agent leases a plain iOS device: Simlock copies the kind's seed, making it first if there is none, and grants the copy; the seed is never granted, and
listManagednever lists it — cases (iOS driver): no seed yet (rowmakingfirst, then--set <sources> create, boot, shutdown, rowready, then the cross-set clone into the device set); seed present (clone only); seed stale, its runtime changed build, is remade; runtime listed with no build (seed kept, only presence checked); the seed is in the sources set (listManagedandsimlock simctl listnever show it, undersimlockanddefault); a seed boot timeout (seed and row deleted,DriverCrashError, the request endsPROVISION_FAILED); startup sweep (another process'smakingrow and its simulator deleted, a sources-set simulator with no row left in place and reported bydoctor, then deleted bydoctor --purge-orphans, this process'smakingrow untouched, one older than 300 s destroyed by the next make of its kind, a failed delete logged and the row kept); two provisions at once make one seed; a named source is copied instead of the seed. - A plain iOS lease is released: the simulator is destroyed, and the next lease gets a new copy that boots with the seed's
disabled.plist— cases: seed has adisabled.plist(copied to the new UDID before the boot); it has none; the clone fails (PROVISION_FAILED, seed kept); the copy's marks are its own. Release then lease through the dispatcher; the copy step in the iOS driver. - An operator runs doctor and nuke: seeds are listed with their size, and nuke deletes them — cases: doctor (one seed, with
sizeBytes; one with no size,sizeBytesabsent; a stale one with itsstaleReason,findingsempty); iOS driverlistSources(a row maps tokind,model,osVersion,sizeBytes; each of the three stale reasons word for word: runtime gone, runtime build changed, device type gone; the reason clears when the runtime is back; amakingrow not listed); nuke--delete-devices(every seed destroyed, a source of kindbaselinekept); plain nuke (sources kept); removing a runtime deletes its seeds (iOS driverremoveComponent, seeds of another runtime kept); switchingdeviceSetwith a seed left is refused. - Any virtual device is released: it is destroyed, whatever
lease.identitysays, and a device made before this feature goes the same way — cases:reusable(noreclaim,device.deletedinitiatorlease-end, next lease gets another device);fresh; device made before this feature (areusablerecord that already ended a lease is never granted again); a quarantined virtual device that never served a lease is destroyed, not reclaimed; iOS and fakereclaimof a simulator throwvirtual devices are not reclaimed. Extendssrc/core/reclaim-coordinator.test.ts:527andsrc/core/quarantine-coordinator.test.ts.
Done when
pnpm exec vitest run --project unit src/drivers/ios src/core src/daemon src/leasingpasses.pnpm test:e2e e2e/lease-lifecycle.test.ts e2e/warm-pool-reserve.test.tspasses, each expectingdevice.deletedinitiatorlease-endwhere it expecteddevice.reclaimed.grep -n '"erase", data.udid' src/drivers/ios/index.tsfinds nothing.- Slow lane, real simulator:
e2e/slow-ios-smoke.test.tspasses. Its second test leases a plain iPhone, releases it, leases again, and asserts the second UDID differs from the first, the first is gone from the set, the device set holds the copy only and the sources set holds the seed shut down,doctorlists one iOS seed withsizeBytesabove 0, and the second device'sdevice.readybootDurationis under 30 000 ms (F1: 7.2 s for a copy, 36.4 s for a first boot).e2e/slow-ios-slim.test.tspasses with its re-lease test expecting a new UDID that is slim. - Slow lane:
e2e/slow-agent-device.test.ts,e2e/slow-warm-pool.test.tsande2e/slow-android-tunnel.test.tspass with their release checks rewritten for a destroyed device:device.deletedinitiatorlease-endin place ofdevice.reclaimed(the agent-device session check measured from that event, the Android strategy check dropped). - The website pages in F27 and F36 no longer say a released device is wiped and kept,
lease.identitysays it no longer changes anything, and thedoctorandnukereference mention seeds.
Out of scope
- Android seeds, the boot snapshot and
copyTree(Android: every emulator is a copy of a seed in its own folder, booted from its boot snapshot #1205). saveSource, baselines and their records (An operator saves, lists and removes baselines on a worker #1206, A lease names a baseline and gets a copy of it #1207).- Retuning the iOS estimates: provision 500 ms, reclaim 34 s, boot 60 s stay; the first provision of a kind takes a seed boot longer than its estimate, and doctor's stall threshold only gets looser.
- Removing
lease.identityfrom the config, the contract or device records: it stays accepted and stored, with no effect. - Refusing
simctl clonein the passthrough.
Depends on
Written by an agent.
Activity
test: any virtual device is destroyed when its lease ends, whatever l…
feat(core): a released virtual device is destroyed, never granted aga…
test: tests that lease a released virtual device again expect a new d…
feat(drivers): reclaim and reclaimStrategy of a virtual device throw,…
test: doctor lists each driver's sources with their size, and a sourc…
feat(core): doctor lists each driver's sources (#1204)
feat(core): nuke --delete-devices deletes the drivers' seeds (#1204)
test: converge lists each driver's sources once before the warm pool …
feat(core): converge lists each driver's sources once (#1204)
test: a seed make that fails leaves no seed and no row (#1204)
49 remaining items
test(e2e): slow iOS smoke checks the sets, doctor's seed and the copy…
test(ios): the seed's row is making when create runs; the sources set…
fix(ios): the device-set refusal tells how to delete a seed (#1204)
test(doctor): sources of two drivers, and a driver whose listSources …
test: every-driver and every-idle-device claims use two drivers and t…
test(contract): the missing-list case fails only for the empty list (#…
test(e2e): warm tests claim a cleanup run keeps the pool's devices; t…
test(leasing): the second request queues behind a failing boot and is…
fix(core): a quarantine delete retry names the lease engine for a dev…
docs: a released virtual device is deleted, not wiped; claims in comm…
test: the nuke test's simulators are not reaped first, the 0700 mode …
chore: merge the feature branch into the task, keeping both sides of …
feat(ios): every simulator is a copy of a seed, and every virtual dev…
feat(leasing): a lease names a baseline and gets a copy of it (#1236)