Skip to content

iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204

Closed

Description

@V3RON

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)"]
Loading

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 installed
  • runtime <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
Loading
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)
Loading

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 (one listSources per 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 on lease.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 (listSources answers none, destroySource throws).
  • src/daemon/main.ts (the source owner in owners, 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 (the device.reclaimed search: 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 be ready, 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 expects device.deleted initiator lease-end).
  • Docs: docs/internal/EVENTS.md (device.reclaimed now only for physical devices), docs/internal/agent-rules/safety.md rule 1 (the ADR 0061 §1 amendment: a driver may destroy its own sources), website worker/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 left shutdown. 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 mayBeGranted says, and calls reclaim only for a physical device.
  • doctor and --purge-orphans read listManaged (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.converge calls listSources() 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: each making row whose maker is 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 by doctor as an orphan source, and destroyed only by doctor --purge-orphans (decided in delivery, confirmed by the maintainer 2026-11-04). During the process, a making row of this process older than 300 s is destroyed by the next seed make of its kind; a making row 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.
  • refuseOwnSetLeftovers and refuseXcodeSetLeftovers (switching drivers.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-devices before the switch removes both.
  • Component removal (F23): claimProvision keeps a provision, and so a seed make, off a version being removed; the driver deletes that runtime's seeds before simctl runtime delete.
  • makeReady (ADR 0060) writes the copy's disabled.plist after 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-devices destroys every source of kind seed from listSources (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 a making row nuke does not list, and its clone holds the seed's lock, which destroySource also 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 simctl adds --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_SET still names the device set; under simlock the sources set is its sources subfolder, which an agent could only reach by running xcrun simctl --set on 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_data and implements the same verbs; An operator saves, lists and removes baselines on a worker #1206 reads listSources and calls destroySource; A lease names a baseline and gets a copy of it #1207 passes source. 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 simctl device set" — the seed, the sources set, its table and the verbs; "a making row 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 throwing reclaim, 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; destroy removes 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"): destroySource and the sweep delete only simulators in the sources set, by a UDID the table holds or, under doctor --purge-orphans, one no row names; safety.md gains the amendment.
  • Safety rule 8: "simlock- / simlock_ naming is a cosmetic label" — a seed is known by its row, not its simlock-seed- name.
  • Architecture rule 2: only the iOS driver runs simctl and 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 listManaged never lists it — cases (iOS driver): no seed yet (row making first, then --set <sources> create, boot, shutdown, row ready, 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 (listManaged and simlock simctl list never show it, under simlock and default); a seed boot timeout (seed and row deleted, DriverCrashError, the request ends PROVISION_FAILED); startup sweep (another process's making row and its simulator deleted, a sources-set simulator with no row left in place and reported by doctor, then deleted by doctor --purge-orphans, this process's making row 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 a disabled.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, sizeBytes absent; a stale one with its staleReason, findings empty); iOS driver listSources (a row maps to kind, 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; a making row not listed); nuke --delete-devices (every seed destroyed, a source of kind baseline kept); plain nuke (sources kept); removing a runtime deletes its seeds (iOS driver removeComponent, seeds of another runtime kept); switching deviceSet with a seed left is refused.
  • Any virtual device is released: it is destroyed, whatever lease.identity says, and a device made before this feature goes the same way — cases: reusable (no reclaim, device.deleted initiator lease-end, next lease gets another device); fresh; device made before this feature (a reusable record that already ended a lease is never granted again); a quarantined virtual device that never served a lease is destroyed, not reclaimed; iOS and fake reclaim of a simulator throw virtual devices are not reclaimed. Extends src/core/reclaim-coordinator.test.ts:527 and src/core/quarantine-coordinator.test.ts.

Done when

  • pnpm exec vitest run --project unit src/drivers/ios src/core src/daemon src/leasing passes.
  • pnpm test:e2e e2e/lease-lifecycle.test.ts e2e/warm-pool-reserve.test.ts passes, each expecting device.deleted initiator lease-end where it expected device.reclaimed.
  • grep -n '"erase", data.udid' src/drivers/ios/index.ts finds nothing.
  • Slow lane, real simulator: e2e/slow-ios-smoke.test.ts passes. 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, doctor lists one iOS seed with sizeBytes above 0, and the second device's device.ready bootDuration is under 30 000 ms (F1: 7.2 s for a copy, 36.4 s for a first boot). e2e/slow-ios-slim.test.ts passes 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.ts and e2e/slow-android-tunnel.test.ts pass with their release checks rewritten for a destroyed device: device.deleted initiator lease-end in place of device.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.identity says it no longer changes anything, and the doctor and nuke reference mention seeds.

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 2, 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 2, 2026
  3. self-assigned this
    on Nov 2, 2026
  4. 49 remaining items

  5. added 2 commits that reference this issue on Nov 4, 2026
    8b02728
    659c318
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

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