A seed settles in the background, so later copies boot into a settled system

Abierto
#1,732 9 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
30/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
typescript
Área
backend, cli, devtools

Línea de trabajo

Start by tracing the CLI command handling and seed lifecycle for iOS and Android, then read the existing device scheduling, pressure handling, doctor, and event flows. The issue does not name source files or tests, so locate those entry points before estimating the implementation. Done means background settling and simlock seed work on both platforms, with the stated scheduling, pressure, doctor, event, and real-device performance conditions met.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

feature:planned

Request: #1540

Problem

In the reporter's words (#1540): "Every fresh lease of an iPhone Duo simulator (iOS 27.3) spent about 5 minutes in iOS first-boot work after the clone booted. Poster extensions, BackgroundShortcutRunner, CommCenter and other first-boot daemons were running, and the host load average reached 200-400 (Apple silicon, 16 GB)." During that window opening Safari took 35-55 s and the first XCUITest snapshot exceeded a 90 s client timeout, and every new lease repeats it.

"A clone of a ready seed should boot into a settled system." With a seed left to settle by hand for about 8 minutes, Safari opened in 8.6-16.6 s, the first snapshot took 3.9-8.75 s, and the spike was gone.

Simlock saves a seed as soon as its device takes commands, before the system has finished its first-boot work, so every copy does that work again. The same holds on Android: the seed's boot snapshot is saved as soon as the emulator is ready, while its post-boot jobs still run, so every copy resumes them.

Measured on one Mac (comments on this issue), CPU a copy uses in its first 5 minutes after ready:

Copy of today's seed Copy of a seed left to settle first
iOS 27.2, iPhone 17 about 690 core-seconds, the same as a brand-new simulator about 455, near idle after 3 minutes; the first minute is as busy as today
Android 36 (Play Store), Pixel 8 about 530, the same as a cold boot about 65: idle from the first second

Making the first lease of a kind wait about 6 minutes for its seed to settle is not acceptable: the first lease must be served as fast as today.

Who it is for

  • Agents and CI jobs leasing simulators and emulators on a worker: every lease today starts on a device, and a host, busy with first-boot work for minutes.
  • Operators of a worker who prepare it ahead of time (a setup script after installing Xcode, a runtime or a system image) and want the first leases to start on a settled device too.

Outcome

  • After the first lease of a kind, Simlock settles that kind's seed in the background, when the worker is quiet, without making any lease wait. Leases that start after that boot into a settled system: on Android no post-boot work at all, on iOS about a third less, and quiet after the first few minutes.
  • An operator can run simlock seed <ios|android> <model> [--os <version>] [--image-tag <tag>] on a worker to make and settle a kind's seed before anyone leases it. The command exits once the seed is settled.
  • simlock doctor --json reports, for each seed, whether it is settled (doctor's text output prints no sources today).
  • simlock events shows when a settle started and how it ended (settled, cap, failed or aborted).

How it works for the user

flowchart TD
  L[First lease of a new kind] --> Q[Seed made as today, lease served at once]
  Q --> P[Copies do first-boot work, as today]
  Q --> W{Worker quiet?<br/>no boot under way for a while,<br/>no other settle, no memory or disk pressure}
  W -- not yet --> W
  W -- yes --> S[Simlock settles the seed in the background]
  S --> D[Later leases boot settled]
  O[Operator: simlock seed ios 'iPhone 17' --os 27.2] --> S2[Seed made if missing, settled<br/>after any settle ahead of it]
  S2 --> E[Command prints the settled seed and exits 0]

Operator session (wording final in the design):

$ simlock seed ios "iPhone 17" --os 27.2
seed iPhone 17, iOS 27.2: waiting behind another settle…
seed iPhone 17, iOS 27.2: settling…
seed iPhone 17, iOS 27.2: settled in 6m19s (1.8 GB)

$ simlock seed ios "iPhone 17" --os 27.2
seed iPhone 17, iOS 27.2: already settled (1.8 GB)

$ simlock seed android "Pixel 8" --os 36 --image-tag google_apis_playstore
seed Pixel 8, Android 36 (google_apis_playstore): making the seed…
seed Pixel 8, Android 36 (google_apis_playstore): settling…
seed Pixel 8, Android 36 (google_apis_playstore): settled in 6m15s (5.0 GB)

$ simlock --url https://gateway.example seed ios "iPhone 17"
{"error":{"code":"UNSUPPORTED_IN_GATEWAY_MODE","message":"seed acts on one machine's devices; run it against a worker"}}

Examples

Input Today After
simlock seed ios "iPhone 17" --os 27.2, no seed yet unknown command seed made and settled, exit 0
same, seed settled already unknown command prints it, exit 0 at once
same, a seed from before this feature exists unknown command that seed is settled, exit 0
same, another settle running unknown command waits for it, then settles
simlock seed ios "iPhone 17" (no --os) unknown command the newest installed runtime, as a lease picks
simlock seed ios "iPhone 17" --os ">=26" unknown command the newest installed runtime in the range, as a lease picks
simlock seed android "Pixel 8" --os 36 unknown command the image a lease of it would get (the default tag first), settled
simlock seed android "Pixel 8" on a Windows worker unknown command settled, as on macOS and Linux
simlock seed ios "iPhone 17" --image-tag google_apis unknown command refused: an image tag is Android only, as for a lease
simlock seed ios "iPhone 17" --os 12.0 unknown command refused, as a lease of it is
--os naming a runtime or image not installed unknown command RUNTIME_MISSING (exit 12), nothing downloaded; the message points at simlock component install, not --allow-download
unknown model, e.g. simlock seed ios "iPhone 99" unknown command UNKNOWN_MODEL (exit 12)
simlock seed "iPhone 17" (no platform) unknown command usage error, exit 2
memory pressure reaches new-devices-paused during a settle unknown command the settle is stopped, the quick seed kept; it settles again once pressure is back to none
free disk below the disk-pressure threshold (10 GiB by default) unknown command waits; the settle starts when space is back
through a gateway (--url) unknown command UNSUPPORTED_IN_GATEWAY_MODE
Ctrl-C while waiting unknown command stops waiting; the settle stays queued
first lease of a new kind served at once, seed unsettled served at once, seed unsettled
an iOS lease after its seed settled ~690 core-seconds of first-boot work ~455, quiet after ~3 min
an Android lease after its seed settled ~530 core-seconds, ready in ~4 s ~65, ready in ~10 s

What could go wrong

  • A settle running when a lease arrives slows that lease's boot: two busy devices at once instead of one. Likely now and then on a busy worker.
  • On a worker that is never quiet, seeds never settle in the background, and leases stay as slow as today until an operator runs simlock seed.
  • An Android lease that boots a new copy is ready about 6 s later than today (a larger snapshot to load). A lease served from a warm device does not see it.
  • A settled seed is larger (iOS 1.2 → 1.8 GB, Android 3.0 → 5.0 GB here), and while a settle runs the worker briefly holds two seeds and a copy.
  • On iOS about a minute of heavy work stays on every copy's first boot; on a small host running several simulators that minute still hurts.

Words used

  • seed: the shut-down device Simlock keeps per kind and copies for every plain lease, e.g. one seed for "iPhone 17, iOS 27.2" or "Pixel 8, Android 36, google_apis_playstore".
  • first-boot work: what the system does after a device already takes commands, e.g. wallpaper and widget discovery on iOS, background jobs and app optimisation on Android; minutes of CPU.
  • settled seed: a seed saved after that work finished, so its copies do not do it again.
  • quick seed: a seed saved as today, as soon as its device takes commands.
  • settle: Simlock booting a copy of a quick seed, waiting until that device's own processes go idle, and saving it as the kind's seed.
  • quiet worker: no device booting for a while, no other settle, no memory or disk pressure.

Non-goals

  • Making the first lease of a kind wait for a settled seed.
  • Baselines: they work as today, and are never settled. An iOS baseline is a copy of a lease that ran, so its copies probably behave like a settled seed's. An Android baseline's snapshot is still saved right after a cold boot, so its copies probably redo part of the post-boot work; not measured, and left as it is in this feature.
  • Pre-seeding from config at daemon start, or a warmPool.targets entry that seeds without keeping a device booted.
  • Pacing the warm pool's refill boot (#1550).
  • One seed per iOS mode: one seed serves slim and full leases alike.
  • Removing the minute of work every iOS copy still does.

Completion conditions

  • On a real Mac, a lease of a kind whose seed was settled by simlock seed does less work than on main: on Android its emulator uses under a quarter of a quick copy's CPU in its first 5 minutes after ready; on iOS its simulator uses under three quarters, and under 0.3 cores from minute 3.
  • The first lease of a new kind waits for nothing it did not wait for on main: no settle, no quiet period, and on Android no copy turn unless a deletion of that seed is under way.
  • With leases booting, no settle starts; after they end and the worker stays quiet, the kind's seed is settled without anyone running a command, and simlock doctor --json says so.
  • simlock seed exits 0 with a settled seed on both platforms (Android on macOS, Linux and Windows), refuses a missing runtime or image and a gateway, and leaves its settle queued on Ctrl-C.
  • At most one settle runs on a worker at any time.
  • Every settle that ends while the daemon runs shows in simlock events as one seed.settle-started and one seed.settle-ended with its outcome; a settle cut by a crash has no end event, and the next start sweeps it.

Open questions

Decisions

  • Decided in the session: both platforms, because the measurement shows Android copies redo the same work and gain the most from a settled seed (about 88% less CPU), at about 6 s more to ready and 2 GB more per seed.
  • Decided in the session: a seed is queued for its background settle only once a lease has used it, and the queue is ordered by how many leases used it since it was made, because a kind leased once by mistake should not take a settle ahead of real ones, and seeds from before the upgrade then settle as they are used rather than all at once.
  • Decided in the session: the triage comment's fixed 8-minute wait before the seed's shutdown (#1540) is rejected, because it makes the first lease of a kind wait.
  • Decided in the session: simlock seed waits until the seed is settled, skips the quiet-period wait, and still takes its turn behind a running settle and pauses under memory or disk pressure, because a setup script needs a settled seed when the command exits, without recreating the load spike.
  • Decided in the session: simlock seed takes the platform first, as simlock warm forget does, then a lease's device words (<model>, --os, --image-tag), resolved as a lease resolves them (the default image tag first), without --mode (one seed serves both modes) or --allow-download, because an operator names a kind the way they lease it.
  • Decided in the session: simlock seed prints one stderr line per stage: making the seed…, waiting behind another settle…, waiting: memory pressure…, waiting: free disk below <threshold>…, waiting: no room for another device…, settling…, each after seed <model>, <OS> <version>[ (<tag>)]:, because a person running a setup script should see why it waits.
  • Decided in the session: a settle goes on at memory pressure warming-paused and is stopped at new-devices-paused, keeping the quick seed and settling it again once pressure is none, because those are the steps at which Simlock already stops warming and new devices.
  • Decided in the session: Android seeds settle on Windows workers too, the emulator's CPU read through PowerShell CIM as host memory already is, because Android runs on Windows workers and the gain there is the same.
  • Decided in the session: an operator's simlock seed skips the whole quiet rule (boots under way and the 5 minutes after) and an earlier failure's hour, but still waits behind a running settle, memory and disk pressure and capacity, because the operator asked for it now.
  • Decided in the session: an operator's settle stopped by memory pressure goes back to waiting (waiting: memory pressure…) and settles once pressure is none; a make under way finishes first, because the call is still within its 60 minutes.
  • Decided in the session: an operator's wait is for a kind, so a simlock seed that arrives while the background settle of that kind runs waits for it and answers settled.
  • Decided in the session: at the 60-minute limit the operator's wait ends with SEED_SETTLE_FAILED and leaves the queue; a settle already under way goes on, as a background one.
  • Decided in the session: a seed make that simlock seed starts holds the same reservation, claim and gates as a settle, because it boots a full device too.
  • Decided in the session: a reboot of a ready device for a lease's except list is not seen by the quiet rule, because it takes no capacity reservation and boots a device whose first-boot work is done.
  • Decided in the session: no pre-seeding from config in v1, because a warm target means a device kept booted, and simlock seed covers setup scripts.
  • Decided in the session: idle is judged from the settling device's own processes, not host load, because a shared Mac's load says nothing about that device.
  • Decided in the session: simlock seed is worker-only and refused through a gateway, as every command acting on one machine's devices is.
  • Decided in the session: simlock seed never downloads a runtime or image, as the warm pool never does.
  • Decided in the session: a settle does not start while free disk is below diskPressure.freeBytesThreshold, because nothing checks free space before a copy today (the disk guard serves component installs only) and a settle briefly holds two seeds and a copy.
  • Decided in the session: the driver counts, per seed, the leases copied from it since it was made, because the warm pool's per-kind lease rows exist only for learned kinds.
  • Decided in the session: Ctrl-C on simlock seed only stops the waiting; the settle stays queued, as a component install keeps running when its client goes away.
  • Decided in the session: the design goes ahead although iOS gains about a third, not all, because the measured gain is real and Android's is near total.
  • Decided in the session: the idle rule is the device's own process tree using under 0.15 cores (iOS) or 0.35 cores (Android) over the last 120 s, no earlier than 180 s after ready, with a cap of 15 minutes after ready, because those bars ended both measured settles cleanly at about 6 minutes, and Android's CPU comes in waves that a shorter window would stop inside.
  • Decided in the session: a settle that reaches the cap still saves its seed, marked settled, because it is never less settled than the quick seed it replaces.
  • Decided after #1631: an Android settle saves only once the copy has a default network, because a snapshot saved before the guest's data call is up restores offline (13 of 13 leases in #1631, online 16 to 58 s later), while one saved with a default network restores with it (3 of 3 here, online at ready). The wait is an event, not a poll: ConnectivityService logs Sending CONNECTED broadcast … isDefaultNetwork=true when it picks a default network, and a one-shot logcat -m 1 exits on it (about 0.7 s after the guest logged it, measured on Android 36). One dumpsys connectivity read backs it up, so a log text that changes in another image falls back to the cap rather than failing the settle. The quick seed keeps saving at ready, because the first lease must not wait.
  • Decided in the session: the quiet period is 5 minutes since the last boot or creation reservation was released, counted from the release itself (not from a poll), because a copy's first-boot work lasts about 3 to 5 minutes and an Android copy is ready in seconds.
  • Decided in the session: a settle that fails is logged and its seed is not tried again for an hour, so a seed that cannot settle does not boot a device every 30 s.
  • Decided in the session: a settle holds a creation reservation and a component claim for its whole run, because it boots a full device that core's RAM budget and a component removal must see.
  • Decided in the session: a settle emits two events, seed.settle-started and seed.settle-ended with its outcome, and nothing finer, so an operator sees in simlock events and the daemon log when a settle ran and how it ended.
  • Decided in the session: on Android a seed's copies and its deletion take turns, as on iOS, because a settle replaces a seed while copies of it may be running, and today nothing stops that.
  • Decided in the session: simlock seed waits at most 60 minutes from arrival, then fails, because an unbounded wait behind memory pressure would hold a setup script forever.
  • ADR 0090 — A seed is settled in the background and replaced by its settled copy: narrows ADR 0061 §1 (a ready seed is never booted, and no command names it but doctor) and §2 (an Android seed's snapshot is saved right after a cold boot).
  • ADR 0061 — Every virtual device is a copy of a source: seeds, staleness and the copy steps this feature builds on.
  • ADR 0076 — An iOS clone names only its own folders before its first boot: the lineage swap a settle copy and a settled seed go through.
  • ADR 0068 — A worker pauses warming and new devices under memory pressure: the pause a settle obeys.
  • Prerequisite: #1731 (an iOS copy can skip its UDID rewrite when its seed is deleted between clone and rewrite). A routine seed swap widens that window, so it is fixed first.

Behaviours

Id Behaviour (invoker, action, what it sees) Seam Cases Task
B1 Core settles a quick seed in the background. It checks when the quiet period ends, on a memory reading, when a settle ends and every 5 minutes. A check reads the gates first: no creation or boot reservation under way and none released in the last 5 minutes (I5, timed from the release), memory pressure none, free disk at or above diskPressure.freeBytesThreshold, no failure delay. Only then does it call listSources on the drivers that have a settle verb (bounded at 60 s each), keep the quick seeds a lease used, and settle the one with the most leases createSeedSettler (I4) with a fake driver, fake clock, real CapacityCoordinator, fake memory pressure, fake diskFree two candidates (more leases first; equal: listed order); 0 leases, settled, stale, orphan (none chosen); a reservation under way; one taken and released between two checks (seen); released 4 min 59 s ago, then 5 min; step warming-paused, new-devices-paused; disk 1 byte under the threshold, at it; a driver with no settle verb; the creation reservation refused (next check); listSources throws (logged, check ends); listSources past 60 s (logged, check ends); gates shut (no listSources call) #1746
B2 At most one settle runs on a worker; a lease that boots during a settle does not stop it I4 a second candidate while one settles (waits for it); a lease's reservation mid-settle (settle goes on); two platforms with candidates (one at a time) #1746
B3 A settle, and a seed make an operator asked for, hold a creation reservation (counted full) and a component claim for the kind's runtime or image from before the driver call until it returns, on every exit I4 with CapacityCoordinator and a fake component installer settled; the driver throws; aborted; component remove of that runtime meanwhile (refused as with a creation in flight); an operator make then settle (one reservation across both) #1746
B4 A daemon stop ends the settler: beginStop (in the worker's beginStop) starts no settle; stop (awaited in the worker's dispose before the drivers are disposed, beside components.close()) aborts a running settle and resolves once the driver returns; an operator's wait then fails DAEMON_STOPPING I4, and worker-composition dispose order stop mid-settle (driver's signal aborted, awaited before driver dispose); stop with none running; stop while an operator waits #1746
B5 A settle that fails is logged as a warning naming the kind and the message, and that seed is not chosen in the background for an hour I4 the driver throws; a check within the hour (another candidate, or none); after the hour (chosen again); an operator call within the hour (settles, B6) #1746
B6 A settle running when memory pressure reaches new-devices-paused is aborted; the quick seed is kept and chosen again once pressure is none, with no failure delay; at warming-paused it goes on I4 new-devices-paused mid-settle (aborted, no warning, no delay); warming-paused mid-settle (goes on); back to none (settled later); an operator's settle aborted so (its call goes back to waiting memory-pressure, then settles); an operator's make under way (it finishes, then the call waits before settling) #1746
B7 A nuke holds the settler (I4 holdWhile): a running settle is aborted and awaited before nuke deletes seeds, none starts during the nuke, and checks resume after it NukeService with the settler's handle nuke during a settle (no seed is made ready after nuke reports them deleted); nuke with none running; an operator wait during nuke (waits, then goes on) #1746
B8 simlock doctor --json lists, for each seed, settled and leases; a baseline has neither doctor.run through the dispatcher with a fake driver a quick seed with 3 leases; a settled seed with 0; a baseline #1746
B9 The idle check (I11) over process readings (I10): the device's tree is its root process and every descendant by parent id; its CPU is the sum, over every process ever seen in the tree, of the largest cumulative CPU time read for it, so a process that exits keeps its time; cores are the CPU added over the last 120 s divided by the time between the readings IdleWatch (I11) with built readings; NodeProcessTable (I10) with a fake process runner idle 181 s after ready; a wave at 3 min, then idle; a process that exits between readings; the root not found yet (busy); the cap at 15 min; ps times 1:02.50, 01:02:03, 2-01:02:03; a PowerShell CIM answer (100-ns units); a reading that times out (counts as no reading) #1746
B23 Every settle the settler starts emits seed.settle-started once the reservation and claim are held and the driver is called, and seed.settle-ended once the driver returns or throws, with its outcome (I13); a seed make for an operator emits neither I4 with a recording event bus settled (settled, new source id, size); the cap (cap); the driver throws (failed, message); aborted by memory pressure, daemon stop and nuke (aborted with each reason); an operator settle (trigger: operator); a kind already settled for an operator (no event) #1746
B10 simlock seed <ios|android> <model> [--os] [--image-tag] [--json] on a worker: the daemon resolves the kind as a lease does (I9), without downloading; the settler (I4 settle) waits for a running settle, memory or disk pressure and capacity, then makes the seed if missing or stale and settles it if quick; the command prints the seed and exits 0 seed.make (I7) through the daemon dispatcher with a fake driver; CLI through runCli with a fake admin client settled already (already-settled, no reservation); quick seed (settled); no seed (making, then settling); another kind's settle running (waiting settle-running); the background settle of this kind running (waits, answers settled); two calls for one kind (one settle, both answered); memory pressure, disk, capacity (waiting with each reason, then goes on); the make fails or the settle fails (SEED_SETTLE_FAILED failed, exit 1); 60 min pass (SEED_SETTLE_FAILED timed-out; entry leaves the queue, a settle under way goes on); --json (I7's output, one line) #1749
B11 simlock seed refuses what it cannot settle, before any device boots I7 and the CLI no platform word (usage error, exit 2); unknown model (UNKNOWN_MODEL, exit 12); --image-tag with ios (BAD_REQUEST); a runtime or image not installed (RUNTIME_MISSING, exit 12, I7's message); iOS below 16 (the lease's refusal); through a gateway (UNSUPPORTED_IN_GATEWAY_MODE); an agent session (FORBIDDEN); virtual devices off (the lease's refusal) #1749
B12 Ctrl-C while simlock seed waits stops the wait: one stderr line, exit 0, and the daemon goes on CLI through runCli with a fake admin client and a signal Ctrl-C during waiting; during settling; doctor --json afterwards shows the seed settled #1749
B13 On real hardware a copy of a settled seed does less work slow lane e2e/slow-seed-settle.test.ts: one iOS and one Android kind; a lease of each before and after simlock seed, with its device's tree CPU for 5 min after ready Android under a quarter of the quick copy's CPU; iOS under three quarters and under 0.3 cores from minute 3 #1749
B14 iOS: every plain lease copied from a seed adds one to that seed's lease count; listSources reports settled and leases IosSimctlDriver with the fake simctl harness plain provision (+1); a baseline copy (seed unchanged); a clone that fails (unchanged); a seed from before this feature (settled: false, leases: 0); a first lease of a new kind (no wait beyond the make) #1747
B15 iOS settleSeed: the quick seed is cloned into the device set as a provision clones it (marks, LaunchServices database dropped, lineage swapped, in the seed's turn); booted with SimulatorBoot.bootAndWait only (no slim overrides, no volume or window step); read every 2 s with the idle check, the root being the launchd_sim whose command line names the copy's folder; shut down; cloned into the sources set as a new seed (LaunchServices dropped, lineage [copy UDID, ...seed lineage] recorded); in one transaction the new row is ready and settled and the old row turns making with settle_of set; the old seed is deleted in its turn, then its row; the copy is deleted with its log folder IosSimctlDriver with fake simctl, a fake process table, fake clock idle at 181 s (idle); idle only at 900 s; still busy at 900 s (cap, saved); the boot times out (throws, copy deleted, quick seed kept); aborted mid-reading (throws, copy and settle row gone, quick seed kept); a source that is not a ready quick seed (throws); a clone of the old seed in flight (its deletion waits); deviceSet: default (copy marked, clipboard sync off) #1747
B16 iOS: what a restart leaves of a settle is swept at the next start; within one process a make never sweeps a settle IosSimctlDriver another process's settle row (row, copy and partial seed deleted, quick seed kept); a retired quick seed's row (its simulator and row deleted); a make of the kind 6 min into this process's settle (untouched) #1747
B17 iOS ensureSeed: answers the kind's fresh ready seed, or makes it as a provision would, without creating a device IosSimctlDriver fresh; stale (remade); none (made); two calls at once (one make) #1747
B18 Android: every plain lease copied from a seed adds one to that seed's lease count; listSources reports settled and leases AndroidDriver with the fake emulator host plain provision; a baseline copy; a copy that fails; a seed from before this feature; a first lease of a new kind (made and copied with no wait beyond the make) #1748
B19 Android settleSeed: under the kind's lock (seed:<spec key>) the quick seed is checked and its copy turn taken, then the lock is let go; the AVD is copied into a new source folder; booted from simlock_boot with a reserved console port and the leases' launch flags; read every 2 s (5 s on Windows) with the idle check, the root being the emulator process the driver spawned; once the idle rule passes, the copy must have a default network (#1631): a one-shot listener started at the copy's ready (adb logcat -T 1 -m 1 -e 'CONNECTED broadcast.*isDefaultNetwork=true' ConnectivityService:D '*:S') has fired, or one dumpsys connectivity read shows Active default network: <number>; otherwise the save waits for the listener, up to the cap; simlock_boot saved again and checked with snapshot list; the emulator stopped; under the kind's lock again, in one transaction, the new row is ready and settled with its config hash and size and the old row turns making with settle_of set; the old folder is deleted once no copy of it is in flight, then its row AndroidDriver with the fake emulator host, a fake process table, fake clock idle at 181 s; idle with no default network yet (the save waits for the listener); idle, the listener never fired but dumpsys connectivity shows a default network (saved); no default network by the cap (saved, as busy at the cap); idle only at the cap; still busy at the cap (saved); a provision of the kind meanwhile (served at once from the quick seed); snapshot not listed (throws, new folder deleted, quick seed kept); the emulator exits early (throws); aborted (throws, cleaned); a source that is not a ready quick seed (throws); process.platform win32 (readings through PowerShell) #1748
B20 Android: a seed's copies and its deletion take turns: a deletion waits for every copy in flight from that folder, and no copy starts from a folder being deleted AndroidDriver stale remake during a copy; destroySource during a copy; destroySeedsOf during a copy; a settle's swap during a copy; a copy asked for after a deletion began (copies the current seed, or makes one) #1748
B21 Android: what a restart leaves of a settle is swept at the next start, the emulator stopped by its path; within one process a make never sweeps a settle AndroidDriver another process's settle row; a retired quick seed's row; a make of the kind during this process's settle #1748
B22 Android ensureSeed: answers the kind's fresh ready seed, or makes it as a provision would, without creating a device AndroidDriver fresh; stale (remade); none (made); two calls at once (one make) #1748

Stored state

Id What and where Created, changed, deleted by Listed or swept by A restart mid-step leaves Schema step Task Used by
S1 ios_source_data columns lease_count INTEGER NOT NULL DEFAULT 0, settled INTEGER NOT NULL DEFAULT 0 lease_count + 1 by provision after a plain copy's lineage swap succeeds; both written by settleSeed's swap (new row settled = 1, lease_count = 0); deleted with the row listSources (I1), core's settler through it, doctor nothing half-written: one statement per change ios-source-data +1 #1747 —
S2 ios_source_data column settle_of TEXT. A settle's row: kind = 'seed', state = 'making', settle_of = the quick seed, throwaway_udid = the settle copy. A retired quick seed's row: state = 'making', settle_of = the seed that replaced it settle row inserted by settleSeed before the clone, setThrowaway after it, made ready with settle_of cleared in the swap transaction that retires the quick seed's row; the retired row deleted after its simulator; both deleted on every failed or aborted exit #sweepLeftovers (another process's making rows, as for a make); makingRowsOfKindBefore skips rows with settle_of set a settle row, its copy and maybe a partial seed clone, or a retired row and its simulator: deleted at the next start by the sweep; the kind's ready seed is kept ios-source-data +1 #1747 —
S3 android_source_data columns lease_count INTEGER NOT NULL DEFAULT 0, settled INTEGER NOT NULL DEFAULT 0, settle_of TEXT; a settle row's folder is the new source folder; a retired row keeps its folder as S1 and S2, by Android's provision and settleSeed listSources, #sweepLeftovers (stops a running emulator by path, deletes the folder) a settle row, its folder and maybe a running emulator, or a retired row and its folder: swept at the next start android-source-data +1 #1748 —
S4 Android copy turns, in memory, per seed folder taken by provision's #copySeed and settleSeed's copy; every seed deletion waits for them — nothing: in memory none #1748 —
S5 Core settler state, in memory: operator waits by kind, the running settle and its abort controller, failed seeds with their retry time, when the last creation or boot reservation was released createSeedSettler (I4) — operator calls end with DAEMON_CONNECTION_LOST at the client; a running settle is aborted by stop (B4) or swept by the driver (S2, S3) none #1746 #1749

Interfaces

Id What Shape and bounds Errors and limits Where Task Used by
I1 DriverSource gains settled?: boolean and leases?: number (integer ≥ 0): both set on a seed, both absent on a baseline. DoctorSource carries them; the doctor.run output schema's source object adds both, optional (bumps the protocol by one) — none new src/core/driver.ts, src/contract/report-schemas.ts:119 (doctorSourceSchema) #1746 #1747, #1748, #1749
I2 Driver.settleSeed?(sourceId: string, options: { signal: AbortSignal }): Promise<{ sourceId: string; sizeBytes?: number; settledAfterMs: number; reason: "idle" | "cap" }>: settles the ready quick seed sourceId, answers the new seed sourceId names a ready seed with settled false DriverCrashError for a source that is not a ready quick seed, a failed boot or save; the signal's reason when aborted. Bounded by the driver's boot timeout, then 15 min after ready, then the save steps' own limits src/core/driver.ts #1746 #1747, #1748
I3 Driver.ensureSeed?(spec: VirtualSpec): Promise<{ sourceId: string; settled: boolean; leases: number; sizeBytes?: number }>: the kind's fresh ready seed, made if missing or stale spec from I9 what a provision's seed make throws (BootTimeoutError, DriverCrashError) src/core/driver.ts #1746 #1747, #1748, #1749
I4 createSeedSettler(options) in src/core/seed-settle/index.ts, handle { start(): void; beginStop(): void; stop(): Promise<void>; holdWhile<T>(work: () => Promise<T>): Promise<T>; settle(spec: VirtualSpec, options: { onProgress(progress: SeedSettleProgress): void }): Promise<SeedSettleResult> }. Options: drivers, eventBus, capacity (CapacityCoordinator), decisions, registry, components (claimProvision), memoryPressure (MemoryPressureReader: current, onReading), filesystem (diskFree), diskPath (the reaper's), diskPressure config, clock, logger. Built in createCore; start after warmPool.start(); beginStop from the worker's beginStop; stop awaited in the worker's dispose before driver dispose; passed to NukeService. Constants: check every 5 min, quiet 5 min, retry after a failure 1 h, listSources bound 60 s, an operator wait 60 min SeedSettleProgress = { stage: "making" } | { stage: "waiting"; reason: "settle-running" | "memory-pressure" | "disk-pressure" | "capacity" } | { stage: "settling" }; SeedSettleResult = { sourceId; sizeBytes?; outcome: "settled" | "already-settled"; settledAfterMs? } settle rejects with SeedSettleFailedError (I12) for a failed make or settle and at 60 min, SeedSettlerStoppedError (I12) after beginStop core #1746 #1749
I5 CapacityCoordinator.onBootActivity(listener: (underWay: number) => void): () => void: called after every take and release of a creation, boot or rewarm reservation with the number now open; the settler stamps the release that brings it to 0 with its clock underWay integer ≥ 0 none src/core/capacity/coordinator.ts #1746 —
I6 nextSettle(view): SettleDecision, pure: view = { candidates: readonly { platform; sourceId; leases; failedUntil? }[]; operator: readonly { platform; specKey; sourceId? }[]; running: boolean; underWay: number; lastReleasedAt?: number; now: number; pressure: MemoryPressureStep; diskFreeBytes: number; freeBytesThreshold: number }; answers { kind: "wait"; reason } or { kind: "settle"; platform; sourceId?; operator: boolean }. specKey is the resolved spec's platform, model, osVersion and imageTag, and joins operator calls for one kind; once ensureSeed answers, the wait carries that sourceId, and it is by sourceId that it matches the running settle (an Android spec with no tag and no default tag has none in its key). An operator kind goes first and skips the quiet rule and the failure delay — none src/core/seed-settle/policy.ts #1746 —
I7 Operation seed.make, role admin, effect write, worker only. Input (strict): platform ios | android, model string 1–200, osVersion? (the lease's OS grammar, os-range.ts), imageTag? string 1–100. Output: { platform; model; osVersion; imageTag?; sourceId; sizeBytes?; outcome: "settled" | "already-settled"; settledAfterMs? }. Push seed-progress { requestId; kind: { platform; model; osVersion; imageTag? }; progress: SeedSettleProgress }. Admin client makeSeed(input, { onProgress? }). Bumps the protocol by one the kind comes from I9 before the settler is called the lease's codes for I9's refusals (UNKNOWN_MODEL, BAD_REQUEST, MODE_UNAVAILABLE never, the below-iOS-16 refusal, virtual devices off); RUNTIME_MISSING with the message <OS name> <version> is not installed; install it with simlock component install <platform> <version> (with no exact version: no installed <OS name> runtime fits <the range, or "the default">; install one with simlock component install <platform> and a version); FORBIDDEN for an agent; gateway UNSUPPORTED_IN_GATEWAY_MODE "seed acts on one machine's devices; run it against a worker"; new SEED_SETTLE_FAILED { platform; model; reason: "failed" | "timed-out" }, kind domain, exit 1, HTTP 500, message seed <model> could not be settled: <driver message> or seed <model> was not settled within 60 minutes; DAEMON_STOPPING src/contract/operations-admin.ts, pushes.ts, errors.ts, protocol.ts, operations.test.ts; src/daemon/dispatcher-components.ts, server-requests.ts, error-code.ts; src/gateway/dispatcher.ts; src/simlock-client/client-api.ts, types.ts; src/admin/index.ts #1749 —
I8 CLI simlock seed <ios|android> <model> [--os <version|range>] [--image-tag <tag>] [--json]. Stderr, one line per stage change: seed <model>, <OS name> <version>[ (<tag>)]: then making the seed…, waiting behind another settle…, waiting: memory pressure…, waiting: free disk below <threshold>…, waiting: no room for another device… or settling…. Stdout: …: settled in <m>m<ss>s (<size>) or …: already settled (<size>). --json: I7's output, one line, no stderr lines. Ctrl-C: stderr stopped waiting; the settle goes on in the daemon, exit 0 words as simlock lease's, without --mode, --allow-download, --baseline, --physical exit codes from I7's errors; a usage error exits 2 src/cli/tree.ts, src/cli/commands/seed.ts, src/cli/index.ts help; website/src/content/docs/docs/reference/cli.mdx, errors.mdx, worker/capacity.mdx #1749 —
I9 Leasing's handle gains resolveSeedSpec(request: { platform; model; osVersion?; imageTag? }): Promise<VirtualSpec>: the lease's resolution (default image tag first, allowDownload: false) with the served-mode check skipped and mode: "full" in the answer, because one seed serves every mode, throwing the lease's errors as they are — UnknownModelError, UnsupportedRequestOptionError, RuntimeMissingError, the iOS floor and range errors, VirtualDevicesOffError src/leasing/acquisition-spec-resolver.ts, create-leasing.ts #1749 —
I10 Port ProcessTable in src/ports/process-table.ts: list(): Promise<readonly { pid: number; ppid: number; cpuSeconds: number; command: string }[]>. Node adapter: POSIX ps -axo pid=,ppid=,time=,command= (time [[dd-]hh:]mm:ss[.cc]); win32 PowerShell Get-CimInstance Win32_Process with ProcessId, ParentProcessId, KernelModeTime + UserModeTime (100-ns units) and CommandLine. A fake beside it — bounded at 5 s (POSIX) and 15 s (Windows); a timeout or non-zero exit throws src/ports/process-table.ts, index.ts #1746 #1747, #1748
I11 IdleWatch in src/core/idle-watch.ts: new IdleWatch({ root(processes): number | undefined; idleCores; windowMs: 120_000; minAfterReadyMs: 180_000; capAfterReadyMs: 900_000; readyAt }), observe(processes, now), state(now): "busy" | "idle" | "cap" (B9's rule) idleCores 0.15 (iOS), 0.35 (Android) none core, exported from src/core/index.ts #1746 #1747, #1748
I12 SeedSettleFailedError { platform; model; reason: "failed" | "timed-out"; message }, and SeedSettlerStoppedError (after beginStop) — mapped by src/daemon/error-code.ts (#1749): the first to SEED_SETTLE_FAILED, the second to DAEMON_STOPPING src/core/driver.ts beside the other domain errors #1746 #1749
I13 Events seed.settle-started { platform; model; osVersion; imageTag?; sourceId; leases; trigger: "background" | "operator" } and seed.settle-ended { platform; model; osVersion; imageTag?; sourceId; outcome: "settled" | "cap" | "failed" | "aborted"; reason?: "memory-pressure" | "daemon-stopping" | "nuke"; message?; newSourceId?; sizeBytes?; durationMs }, emitter SeedSettler, relayed as baseline.saved is. sourceId is the quick seed; newSourceId and sizeBytes only on settled and cap; reason only on aborted; message (the driver's, at most 500 characters) only on failed. seed.settle-ended is emitted after the driver's swap is committed (events rule 3) — none src/core/seed-settle/; src/bus/index.ts (EventMap) and index.test.ts (EVENT_NAMES); docs/internal/EVENTS.md; website/src/content/docs/docs/reference/events.mdx #1746 —

Existing code

Commit fb426763.

Searches: ios_source_data (source-data.ts, seeds.ts: 41 hits), android_source_data (23), findReadySeed (4), listSources (19 outside tests), saveSource (12), tryReserveProvisioning (6), claimProvision (5), diskFree (7), memoryPressure.current (9), unsupportedByDesign (14), component.install in contract, daemon, gateway and cli (22), destroySource (9), closeWarmPool (3), Get-CimInstance (3), "ps" in src (2).

Id Code (path:line) Today With this feature Handled by
X1 src/drivers/ios/seeds.ts:214-262 provision clones the seed in its turn, swaps lineage after the turn bumps the seed's lease_count; the file list is read in the turn (#1731) B14, S1, #1731
X2 src/drivers/ios/seeds.ts:341-412 #makeSeed, :343-349 own-process sweep by STALE_MAKING_MS (300 s) sweeps this process's making rows of the kind older than 300 s skips rows with settle_of, so a settle or a retired seed is never swept by a make B16, S2
X3 src/drivers/ios/seeds.ts:137-187 saveSource clone into the sources set, LaunchServices drop, lineage record, for a baseline its clone-and-record steps are reused by settleSeed with kind seed B15
X4 src/drivers/ios/seeds.ts:320-329, :458-461; src/drivers/ios/seed-turns.ts:22-29 a deletion waits for clones in their turn the settle deletes the old seed the same way B15
X5 src/drivers/ios/seeds.ts:559-573 destroySeedsOf walks ready rows only also ends a settle or retired row of that runtime B16
X6 src/drivers/ios/seeds.ts:110-136 listSources ready rows as DriverSource adds settled, leases B14, I1
X7 src/drivers/ios/index.ts:372-397 makeReady slim, boot, courtesies for every lease boot a settle boots with bootAndWait only B15
X8 src/drivers/android/seeds.ts:427-470 provision, :455 #copySeed outside the seed:<spec key> lock a copy can run while its seed folder is deleted copies and deletions take turns (S4); the count is bumped after a copy B18, B20
X9 src/drivers/android/seeds.ts:205-215, :252-255, :410-425, :736-745 seed removals delete the folder with no wait for copies each waits for the folder's copies in flight B20
X10 src/drivers/android/seeds.ts:613-685 #bootToSnapshot, #saveBootSnapshot; src/drivers/android/device-table.ts:84-96 withLock cold boot, save simlock_boot at ready, under the kind's lock; the lock has no time limit settleSeed holds the lock only to check and to swap; the boot and the readings run outside it B19
X11 src/drivers/android/seeds.ts:172-193 #sweepLeftovers, :39, :125 the make bound sweeps making rows older than any make skips this process's rows with settle_of B21, S3
X12 src/core/capacity/coordinator.ts:68-140 reservations, :58-62 onReservationsChanged, :212-224 release reservations for leases and the warm pool; one observer callback a settle takes a creation reservation; onBootActivity reports every take and release (I5) B1, B3
X13 src/core/component-installer.ts:470-485 claimProvision counts provisions not yet registered; a removal is refused meanwhile a settle and an operator make claim the runtime for their run B3
X14 src/core/reaper.ts:217 diskFree(diskPath ?? ".") the reaper's disk reading the settler reads the same path and threshold B1
X15 src/core/doctor.ts:139-170 #sources spreads each DriverSource into DoctorSource the new fields flow through; the output schema adds them B8, I1
X16 src/core/create-core.ts:478-500, :520-530 warm pool started after startup sources; closeWarmPool sync the settler is built here and started after the warm pool I4
X17 src/daemon/worker-composition.ts:508 beginStop, :599-622 dispose closeWarmPool() at beginStop; components.close() and settleAcquisitions() awaited before driver dispose (#1200) settler.beginStop() at beginStop; await settler.stop() beside components.close() B4
X18 src/core/nuke-service.ts:47-61 options, :92-129, :142-163 #destroySeeds deletes every ready seed through listSources and destroySource runs inside settler.holdWhile, so no settle runs or swaps during it B7
X19 src/leasing/acquisition-spec-resolver.ts:76-156, :380-399, :433-438; src/leasing/create-leasing.ts:251-257 resolveSpec is private; the warm pool's resolve folds errors into refusal strings resolveSeedSpec exposes the throwing path I9, B11
X20 src/drivers/ios/catalog.ts:137, :151 "pass --allow-download" the RUNTIME_MISSING message seed.make replaces the message for its caller only B11, I7
X21 src/gateway/dispatcher.ts:268-274 unsupportedByDesign worker-only operations refused seed.make added B11
X22 src/daemon/server-requests.ts:337-338, :532-549 component progress pushed by request id seed-progress pushed the same way B10, I7
X23 src/daemon/error-code.ts:109-148 maps core errors to codes; BootTimeoutError is PROVISION_FAILED maps SeedSettleFailedError and SeedSettlerStoppedError; the settler wraps a failed make in the first I12, B10
X24 src/ports/host-load.ts:164-181, src/ports/process-supervisor.ts:45 PowerShell CIM reads on Windows, bounded NodeProcessTable reads processes the same way I10
X25 src/contract/operations.test.ts:64, :162; e2e/contract-surface.test.ts:92 role and effect matrices; surface probe seed.make rows added I7
X26 docs/internal/EVENTS.md:125-127 baseline.* rows; website/src/content/docs/docs/reference/events.mdx:169 the source events today are the baseline ones two seed.* rows added beside them I13, B23

Tasks

flowchart LR
  B[#1731 iOS lineage race] --> T2[#1747 iOS settle]
  T1[#1746 core settler] --> T2
  T1 --> T3[#1748 Android settle]
  T2 --> T4[#1749 simlock seed]
  T3 --> T4
  • #1746 Core settles quick seeds in the background — once a driver offers the verbs, core settles a used quick seed when the worker is quiet, and doctor --json shows settled and leases. Risk: a settle that starts while leases boot, or a daemon stop that hangs.
  • #1747 iOS settle — later iOS leases boot about a third quieter. Risk: a copy naming another simulator's folders, or an orphan seed after a restart.
  • #1748 Android settle — later Android leases boot with almost no post-boot work, on macOS, Linux and Windows. Risk: a lease waiting behind a settle, or a copy losing its seed folder.
  • #1749 simlock seed — an operator settles a kind before its first lease. Risk: a hang past 60 minutes, or an error that points at --allow-download.

Completion conditions and the task that delivers each:

  • A copy of a settled seed does less work on real hardware: #1749 (B13, slow lane).
  • The first lease of a new kind waits for nothing new: #1747 (B14), #1748 (B18, B20).
  • No settle starts while leases boot; seeds settle with no command; doctor --json says so: #1746 (B1, B8), with #1747 and #1748 for the real drivers.
  • simlock seed succeeds and refuses as listed: #1749 (B10, B11, B12).
  • At most one settle at a time: #1746 (B2).
  • Every settle shows as two events: #1746 (B23).

Open work in the same area:

  • #1731 (bug) changes provision's lineage swap in src/drivers/ios/seeds.ts: #1747 depends on it.
  • #1558 (request: settle widget discovery) is covered by this feature; it closes once its reporter confirms on a settled seed. No Depends on.
  • #1550 (request: pace the warm pool's refill boot) shares the capacity reservations; a settle only takes one more. No Depends on.
  • #1547 (draft PR: simctl lifecycle timeouts) changes the clone and create calls #1747 uses, on other lines. No Depends on.
  • #1700 (bug: Windows daemon stop while an Android seed is remade) is near #1748's Windows path; it is a stop-order fix. No Depends on.

Written by an agent.

Lenguaje dominante
TypeScript
Estrellas
705
Forks
40
Merge medio
12 h 9 min
PR fusionados (30 d)
376

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de callstackincubator/simlock

Todos los issues de callstackincubator/simlock

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.