Repository navigation
Description
Part of #327.
Scope
After this PR, every Android emulator Simlock makes is a copy of a seed: a source AVD that booted once, was powered off cleanly, and holds one boot snapshot. A plain Android lease gets a new copy in its own folder, booted from that snapshot in a few seconds, and the copy is thrown away when the lease ends (#1204's release path). No Android reset loads a snapshot into a running emulator or wipes a disk any more, so the 18-minute hang (#1047) and the shared-hash invalidation (#1048) have no code left to happen in. It also adds the filesystem port verb copyTree, which #1206 uses to save a baseline.
One task: the seed, the copy, the per-folder keying and the removal of the clean-baseline snapshot all change the same functions (provision, makeReady, destroy, listManaged and the ownership check) and one test block; shipping half of them would leave copies that two devices cannot tell apart.
In short
An Android lease is now served by a fresh copy of a seed device, and the copy is deleted when the lease ends. The first lease of a kind (model, API level, system image) makes the seed once; every later lease of that kind copies it and boots from its snapshot.
New terms (from the feature's Words used):
- seed: the source Simlock makes for one model and system image, e.g. the Pixel 9 on
system-images;android-36;google_apis;arm64-v8a. It lives in<root>/sources/<source id>/(source idseed_<generated id>), outside every device's AVD home, is never leased, and onlydoctorand disk figures show it. - boot snapshot: the one quick-boot snapshot
simlock_bootsaved in a seed. It replaces today's per-devicesimlock_clean_baseline(F3, F5). - copy:
<root>/<device id>/simlock.avdplus<root>/<device id>/simlock.ini, made from the seed's folder withcpkeeping file times (F22). The driver device id keeps today's formsimlock_<generated id>(F1), so the folder is<root>/simlock_<generated id>/.
flowchart LR
P[provision] --> K{"seed for this kind,<br/>not stale? (new)"}
K -- no --> S["make seed: create, cold boot,<br/>sync + power off, cold boot,<br/>save simlock_boot, kill (new)"] --> C
K -- yes --> C["copy seed to <root>/<id>/ (new)"]
C --> B["boot -snapshot simlock_boot<br/>(changed: was clean-baseline / wipe)"] --> L[lease]
L --> R["release: destroy, delete <root>/<id>/<br/>(changed: was snapshot load into the running emulator)"]
What a user sees:
- The first plain lease of a kind on a worker takes longer once: two cold boots and a snapshot save before the copy boots. Later leases of that kind boot from the snapshot (3.8 s and 4.4 s for two at once, measured, F22).
adb shell settings get secure android_idanswers the same value on every copy of one seed (F22).- A device's driver id names its own folder:
<root>/<device id>/simlock.avd, not<root>/<device id>.avd. - The daemon log warning
Android snapshot boot fell back to a cold bootcarriesdeviceIdandreadyAfterMs(todayavdName, F17): every copy's AVD is namedsimlock, so the name no longer tells devices apart.
Messages, word for word, variable parts in <>:
- copy fails:
copying Android seed <source id> to <device id> failed: <cp's stderr, or "timed out after 600000ms"> - seed power-off does not finish:
Android seed <source id> did not power off within 60000ms - seed snapshot not listed after the save:
Android seed <source id>: boot snapshot simlock_boot was not saved - destroy refused (as today, F9, with the device id):
Refusing to delete <device id>: could not tell which AVD the emulator on <serial> runs - stale reason of a source (read by An operator saves, lists and removes baselines on a worker #1206 for baselines and by
doctor; a stale seed is remade silently), each at most 300 characters, the whole list:system image <package> is not installed,system image <package> changed from revision <old> to <new>,emulator changed from <old version> to <new version>,android.emulator launch settings changed.provisionandlistSourcesrecompute it each time: when the image and emulator match again, it clears. - a virtual device given to
reclaimorreclaimStrategy(a programming error; maintainer, Named baselines: a lease starts from a device the operator prepared #327 spec session):DriverCrashErrorvirtual devices are not reclaimed
If this goes wrong, a user sees an Android lease granted a device that another lease is using, or one that still holds the previous lease's apps.
Technical spec
Facts
Commit 019ba5c.
| # | Fact | Source |
|---|---|---|
| F1 | provision runs avdmanager create avd -n simlock_<id> -k <package> -d <profile> in the root, applies a devices.xml or library profile to config.ini, computes the config hash, and returns deviceId equal to the AVD name |
src/drivers/android/index.ts:1051-1106 |
| F2 | makeReady takes the per-device lock by AVD name; recover cold-boots with -no-snapshot-load; prepare reconciles the clean baseline, boots, captures simlock_clean_baseline when none, restarts from it and writes the mark |
src/drivers/android/index.ts:1120-1159 |
| F3 | A standard reclaim checks the config hash, the ownership probe, then runs emu avd snapshot load simlock_clean_baseline (60 s); a mismatch, a failed probe or a failed load shuts down and sets a wipe for the next boot; full always wipes |
src/drivers/android/index.ts:1180-1246, :141, :2390-2402 |
| F4 | Launch arguments: -avd <avdName> -port <port> -no-snapshot-save -grpc <port+3000> -grpc-use-token -crash-report-mode never plus -wipe-data -no-snapshot-load, -snapshot simlock_clean_baseline or -no-snapshot-load |
src/drivers/android/index.ts:2227-2262, :2880-2885 |
| F5 | Baseline capture: emu avd snapshot save (60 s), snapshot list must name it, then <root>/<avd>.avd/simlock-clean-baseline.json holds {configHash, snapshot} |
src/drivers/android/index.ts:2328-2368, :137 |
| F6 | The config hash covers the image path and revision, emulator -version, the config.ini image.sysdir.1, hw.* (not hw.device.hash2) and disk.dataPartition.* lines, and non-default headless/gpu |
src/drivers/android/index.ts:1972-2010 |
| F7 | Every adb, emulator and avdmanager call carries ANDROID_AVD_HOME=<root> and ANDROID_ADB_SERVER_PORT; the emulator env adds ANDROID_EMU_CRASH_REPORTING_DATABASE=<root>/emu-crash.db |
src/drivers/android/index.ts:922-948 |
| F8 | The ownership gate asks adb -s <serial> emu avd path (5 s) on every call and compares it, whole or through realpath, with <root>/<avdName>.avd; readiness checks the same path and refuses another |
src/drivers/android/index.ts:2192-2219, :2168-2177, :134 |
| F9 | destroy shuts down its own handle, or for a device found after a restart asks every attached serial emu avd path and refuses (Refusing to delete <avdName>: ...) when one cannot answer or its emulator does not exit; then avdmanager delete avd -n <avdName> and frees the port |
src/drivers/android/index.ts:1279-1335 |
| F10 | listManaged lists <root>/*.avd; per settled serial reads getprop ro.boot.qemu.avd_name and the erasable mark, keeps only names in the root, then needs emu avd path to name <root>/<name>.avd |
src/drivers/android/index.ts:1375-1419, :1443-1501 |
| F11 | #dataFor refuses a device whose id differs from its AVD name; the #devices map and #withDeviceLock are keyed by AVD name |
src/drivers/android/index.ts:2441-2495, :537 |
| F12 | Estimates: provision 1 s; boot 4 s when #baselineVerdict says the clean baseline would load, else 70 s; recover 70 s; reclaim 6 s snapshot, 32 s wipe |
src/drivers/android/index.ts:1557-1577, :94, :138, :146, :151, :162, :2296-2312 |
| F13 | removeComponent runs sdkmanager --uninstall <package> and touches no AVD |
src/drivers/android/index.ts:1663-1704 |
| F14 | android_device_data (version 1) has avd_name, config_hash, nullable image_identity, port, serial; AndroidDriverData has the same five fields; the daemon registers the table for android |
src/drivers/android/device-data.ts:26-75, src/drivers/android/data.ts:1-7, src/daemon/main.ts:1278 |
| F15 | The Filesystem port has copyFile, rm (recursive, forced), directorySize, but no tree copy; NodeFilesystem takes no constructor arguments; MemoryFilesystem is the fake |
src/ports/filesystem.ts:52-92, :119-126, :213-215, :283-290, :321-330 |
| F16 | Core retires a spent (fresh, already leased) device at release instead of reclaiming it, and quarantine deletes one |
src/core/domain.ts:290-292, src/core/reclaim-coordinator.ts:96-103, src/core/quarantine-coordinator.ts:228-231 |
| F17 | After a snapshot launch ready later than 3 × 4 s, the driver reports snapshot-cold-boot with avdName; the daemon logs Android snapshot boot fell back to a cold boot with avdName and readyAfterMs |
src/drivers/android/index.ts:2275-2278, src/daemon/main.ts:1418-1424 |
| F18 | The root holds the .simlock-owned.json marker and the emu-crash.db folder beside the AVDs |
src/core/device-root.ts:6, src/drivers/android/index.ts:946 |
| F19 | A hard adb emu kill right after preparing an emulator lost the changes; adb shell sync then adb shell reboot -p kept them, power-off 2.2 s |
spike on this machine, 2026-11-02: settings + a file in /data/local/tmp, then emu kill → changes gone; shell sync; shell reboot -p → changes present after the next boot |
| F20 | A snapshot saved in AVD src did not load in a copy renamed c1; the emulator cold-booted the copied disk itself, prepared state present |
spike on this machine, 2026-11-02: boot of c1 → WARNING | Failed to load snapshot 'simlock_boot', ready in 15.7 s |
| F21 | hardware-qemu.ini and snapshots/<name>/hardware.ini hold the AVD's absolute path |
spike on this machine, 2026-11-02: grep -r <src home> <copy> → both files |
| F22 | A copy kept under the same AVD name in its own AVD home (ANDROID_AVD_HOME=<base>/d1, cp -c -p -R <src home>/simlock.avd <base>/d1/simlock.avd, .ini copied with path= rewritten) loaded the snapshot; two copies at once were ready in 3.8 s and 4.4 s; kill + delete + copy + boot 2.8 s; each answered emu avd path with its own folder; both had the same android_id |
spike on this machine, 2026-11-02: INFO | Successfully loaded snapshot 'simlock_boot' using 2213 ms; adb emu avd path → /tmp/bl-spike3/d1/simlock.avd and .../d2/simlock.avd; settings get secure android_id equal |
| F23 | cp -c -R of an AVD took 0.05–0.5 s; adb emu avd snapshot save simlock_boot 3.7 s; the source AVD was 4.8 GB, 3.8 GB of it snapshots |
spike on this machine, 2026-11-02 (M3 Pro, emulator 36.5.11, API 36 google_apis arm64) |
| F24 | Node 24.14 fs.copyFileSync(a, b, COPYFILE_FICLONE) of a 2 GB file on APFS took 3587 ms and free disk dropped by the full size |
spike on this machine, 2026-11-02 |
| F25 | PR #1082 (open) writes hw.keyboard into the AVD's config.ini before every prepare boot, keyed by AVD name |
gh pr diff 1082: hunk @@ -1067,6 +1075,7 @@ adds await this.#applyHardwareKeyboard(data.avdName) |
| F26 | The driver tests run AndroidDriver on ScriptedProcessRunner and MemoryFilesystem; two-instances.test.ts scripts the clean-baseline save and list |
src/drivers/android/index.test.ts:23-28, :124-151; src/drivers/android/two-instances.test.ts:308-309 |
| F27 | The slow smoke test expects <home>/devices/android/<driverDeviceId>.avd, a device demoted to shutdown after release, then a doctor with no foreign-provenance-change for that stopped device |
e2e/slow-android-smoke.test.ts:214, :226-238, :240-259 |
| F28 | An AVD in the root with no registry record is an orphan that doctor --purge-orphans destroys |
src/core/driver.ts:235-241 |
| F29 | A daemon test asserts the snapshot-cold-boot warning's fields { avdName, readyAfterMs } |
src/daemon/main.test.ts:2509-2520 |
Modules touched
Searches: CLEAN_BASELINE, simlock_clean_baseline, simlock-clean-baseline, #baselineHash, #baselineVerdict, #reconcileBaseline, needsWipe, snapshotExpected, baselineCaptured, avdName, ANDROID_AVD_HOME, #env(, #withDeviceLock, #devices., .avd in src/, e2e/, docs/, website/; copyFile( and Filesystem implementations in src/.
flowchart LR
core["core (T1: provision with source, release destroys)"] --> drv["drivers/android/index.ts (changed)"]
drv --> src["drivers/android/source-data.ts (new)"]
drv --> dd["drivers/android/device-data.ts, data.ts (changed)"]
drv --> fs["ports/filesystem.ts copyTree (new verb)"]
fs --> cp[cp]
drv --> tools[avdmanager, emulator, adb]
daemon["daemon/main.ts (changed: table, log field)"] --> drv
Files: src/drivers/android/index.ts, src/drivers/android/source-data.ts (new, the android_source_data table), src/drivers/android/data.ts, src/drivers/android/device-data.ts, src/drivers/android/device-data.test.ts, src/drivers/android/index.test.ts, src/drivers/android/two-instances.test.ts, src/drivers/android/AGENTS.md, src/ports/filesystem.ts, src/ports/filesystem.test.ts, src/ports/AGENTS.md, src/daemon/main.ts, src/daemon/main.test.ts, e2e/slow-android-smoke.test.ts, website/src/content/docs/docs/worker/troubleshooting.mdx, website/src/content/docs/docs/using-devices/working-with-a-device.mdx.
sequenceDiagram
participant C as core
participant D as Android driver
participant F as Filesystem.copyTree
participant E as emulator / adb
C->>D: provision(spec)
alt no fresh seed of this kind
D->>D: insert android_source_data row, state making
D->>E: avdmanager create (ANDROID_AVD_HOME=<root>/sources/<sid>)
D->>E: cold boot, shell sync, shell reboot -p, cold boot
D->>E: emu avd snapshot save simlock_boot, snapshot list, emu kill
D->>D: measure size, set the row ready
end
D->>F: copyTree(<seed>/simlock.avd, <root>/<id>/simlock.avd, timeoutMs 600000)
alt cp fails or times out
F-->>D: error
D->>D: rm <root>/<id>/
D-->>C: throws "copying Android seed ... failed: ..."
end
D->>D: write <root>/<id>/simlock.ini with path= rewritten
D-->>C: device <id>
C->>D: makeReady(prepare)
D->>E: emulator -avd simlock -snapshot simlock_boot -no-snapshot-save (ANDROID_AVD_HOME=<root>/<id>)
E-->>D: ready (snapshot, or the emulator's own cold boot of the same disk)
D-->>C: ready
C->>D: destroy (at release, T1)
D->>E: emu avd path == <root>/<id>/simlock.avd ? emu kill : refuse
D->>D: rm <root>/<id>/
Surface and extension points
Filesystem grows one verb, copyTree(from: string, to: string, options: { timeoutMs: number }): Promise<void>: to must not exist; it becomes a copy of the folder from with file modification times kept. Every caller passes 600 000 ms (this task's seed copy, #1206's save). Its one adapter is NodeFilesystem, which gains an optional constructor argument { platform?: NodeJS.Platform; processRunner?: ProcessRunner } (defaults process.platform and a NodeProcessRunner) so tests can drive each branch: darwin runs cp -c -p -R <from> <to>, linux runs cp -a --reflink=auto <from> <to>, the cp adapter kills cp at timeoutMs and rejects with timed out after <timeoutMs>ms; anything else copies recursively in Node keeping modification times (fs.promises.cp with recursive and preserveTimestamps), which has no bound: timeoutMs is ignored there, and the port's doc comment says so. MemoryFilesystem.copyTree copies its entries with their modifiedAtMs. ADR 0061 §2: another adapter can replace this one without touching a driver; no registry is added, since only one implementation is named.
The Driver verbs provision(spec, { source? }), listSources() and destroySource(id) are #1204's; this task implements them for Android. source names a source id; Android serves only seeds until #1206 adds baselines. listSources answers each ready row as #1204's DriverSource: model the profile name, osVersion the API level (36), imageTag the tag (google_apis), sizeBytes absent when it could not be counted, staleReason. It never lists a making row.
estimate (F12): provision 1 s when a ready row of the spec's kind with no stored stale_reason exists (read from the table, no process call), else 150 s (seed making: two cold boots, a power-off and a snapshot save); boot with purpose prepare 4 s for a copy, 70 s for a device made before this change and for recover. #baselineVerdict and #bootEstimate's clean-baseline branch go; reclaim estimates stay.
Contract and event changes
None to the wire or the events: rg "avdName|simlock_clean_baseline" src/contract docs/internal/EVENTS.md finds nothing. The daemon log line Android snapshot boot fell back to a cold boot swaps its avdName field for deviceId (a log field, not an event).
Stored state:
android_source_data(new table, ownerandroid-source-data, version 1, modelled on iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204'sios_source_data):source_id TEXT PRIMARY KEY,kind TEXT NOT NULL(seedorbaseline; An operator saves, lists and removes baselines on a worker #1206 writesbaseline),state TEXT NOT NULL(makingorready),spec_key TEXT NOT NULL(<model>|<system image package>, e.g.Pixel 9|system-images;android-36;google_apis;arm64-v8a),model TEXT NOT NULL,os_version TEXT NOT NULL(API level),image_tag TEXT NOT NULL,folder TEXT NOT NULL(<root>/sources/<source id>),avd_name TEXT NOT NULL(simlock),image_identity TEXT NOT NULL(image path and revision, F1),emulator_version TEXT NOT NULL,config_hash TEXT(F6; null whilemaking),size_bytes INTEGER(null when not counted),stale_reason TEXT(null when fresh),created_at INTEGER NOT NULL. At most onereadyseed perspec_key.STRICT, no JSON text (ADR 0036 §2). The row is written withstatemakingbefore any folder exists and setreadyat the end (maintainer, Named baselines: a lease starts from a device the operator prepared #327 spec session).android_device_datagoes to version 2: a nullableavd_home TEXTcolumn.AndroidDriverDatagainsavdHome?: string:<root>/<device id>for a copy; absent for a device made before this change, whose AVD is<root>/<avdName>.avd. A row written before hasavd_homenull and reads back withoutavdHome.
Other code on the same state
Searches: .avd and ANDROID_AVD_HOME in src/ (index.ts 31 hits, device-profile-source.ts 2, daemon/main.ts 0), simlock_clean_baseline in src/ (index.ts, index.test.ts, two-instances.test.ts), emu avd path in src/ (index.ts 5), deviceRoot readers of the Android root in src/core (doctor, nuke through listManaged), open PRs on src/drivers/android/index.ts (#1082, #1128, #1129).
- Core release and quarantine (iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204): every released or quarantined virtual device is destroyed (F16 path, Shared values "One lease per virtual device"), so Android's virtual
reclaimbranches (F3) have no caller. This task deletes them;reclaimandreclaimStrategyof a virtual device throwDriverCrashError("virtual devices are not reclaimed"); physical reclaim is unchanged. - Doctor and nuke (iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204): doctor lists
listSourcesin itssources;nuke --delete-devicescallsdestroySourceon every source of kindseed; this task answers both for Android.listManagednever reports a source, so neither treats a seed as an orphan (F28), and a source never makesfindingsnon-empty. #foreignAvdImageDirectoriesreads only the user's AVD home, never the root (src/drivers/android/index.ts:1734-1756); unchanged.- Passthrough
adbkeepsANDROID_AVD_HOME=<root>(F7): adb reaches an emulator by serial, not by AVD home. Its refusal ofemu avd snapshot deletestays; deleting a copy's snapshot costs only that copy's boot. - Device input, screen and tunnels address a device by serial (unchanged).
- A running seed's emulator answers
emu avd pathwith<root>/sources/<sid>/simlock.avd:listManagedskips it, anddestroyof a device never sends it anything, since its path is no device's own. - An operator saves, lists and removes baselines on a worker #1206 (Shared values "Source records", "
copyTree"): writesbaselinerows intoandroid_source_data(statemakingfirst) and copies a device folder throughcopyTreewith 600 000 ms; it readsstale_reason. Android: every emulator is a copy of a seed in its own folder, booted from its boot snapshot #1205 owns the columns; An operator saves, lists and removes baselines on a worker #1206 adds no column without a version bump of the table. Seed making never touches abaselinerow or folder. src/daemon/main.test.ts(F29) andlogAndroidDiagnostic: the warning's fields become{ deviceId, readyAfterMs }.e2e/slow-android-smoke.test.ts(F27): a released device is now destroyed, so "device demoted to shutdown" and the stopped-deviceforeign-provenance-changecheck lose their subject. They become: the released device leaveslist --devices, its folder is gone, anddoctorexits 0 with no finding naming it and one Android seed insources.- PR feat(android): android.emulator.hardwareKeyboard gives emulators a hardware keyboard #1082 (F25) writes
hw.keyboardintoconfig.inibefore every prepare boot. On a copy that changes the hardware the snapshot was saved with, so every boot would cold-boot. Whichever merges second moves the write to seed making and adds the setting to the seed's hash (a change makes the seed stale). - PR test(e2e): find the Android SDK on Windows in the slow Android tests #1128 adds an export at the file's end; PR fix(android): stop the emulator's qemu child too when killing it on Windows #1129 adds
killTree: trueto the emulator spawn (F4's call). Both rebase cleanly over this task's changes; whichever merges second keeps both.
Failure modes
| Call | Outcome | What happens | Limit, counted from |
|---|---|---|---|
avdmanager create avd for a seed |
non-zero exit | seed folder and making row removed, provision throws the tool's message (as today, F1) |
none, as today |
| seed cold boot | not ready | emulator SIGKILLed, seed folder and row removed, BootTimeoutError |
180 s readiness, from the spawn |
seed adb shell sync, adb shell reboot -p |
the emulator exits | next step | 60 s, from reboot -p |
| same | does not exit in time | ownership-gated emu kill, then SIGKILL of the handle; seed folder and row removed; throws ... did not power off within 60000ms |
60 s, from reboot -p |
seed emu avd snapshot save simlock_boot |
non-zero, timeout, or snapshot list lacks it |
emulator killed, seed folder and row removed, throws ... boot snapshot simlock_boot was not saved |
60 s (F5), from the save |
seed emu kill after the save |
exits | size measured, row set ready |
readiness timeout 180 s, then SIGKILL |
seed directorySize |
throws | row ready with no size; sizeBytes absent |
none (local) |
copyTree |
ok | .ini written, device returned |
600 s, from the cp spawn |
copyTree |
cp non-zero or timeout |
cp killed at the limit, the driver removes <root>/<id>/, throws copying Android seed ... |
600 s, from the spawn |
emulator boot of a copy, -snapshot simlock_boot |
snapshot loads | ready | 180 s readiness, from the spawn |
| same | snapshot does not load | the emulator cold-boots the same disk itself (F20); ready later; snapshot-cold-boot reported past 12 s; no wipe |
180 s, from the spawn |
emu avd path in destroy |
names the device's own folder | emu kill, wait for exit, rm <root>/<id>/ |
5 s probe; exit wait 180 s then SIGKILL of an own handle |
| same | another path | nothing sent to that emulator, the device's own folder deleted (decided in delivery, confirmed by the maintainer 2026-11-04) | 5 s, from the probe |
| same | unreadable or timeout | nothing sent, folder kept, throws Refusing to delete <id>: ... |
5 s, from the probe |
rm <root>/<id>/ |
throws | destroy throws; the device stays in the registry for core to retry |
none (local) |
emulator -version in the stale check |
non-zero | provision throws as today (F6) |
none, as today |
destroySource of a seed on image removal |
throws | removeComponent still succeeds; the seed's stale_reason reads system image <package> is not installed, so doctor lists it and nuke deletes it |
none |
Restart in the middle:
- of seed making: a
makingrow and its<root>/sources/<sid>/folder, maybe with its emulator running. Amakingrow is leftover when this process is not making it (the driver keeps the ids it is making in memory) or when itscreated_atis more than 900 s old, even if this process is making it: the next make of that kind, or the nextlistSources, then treats it as leftover and that make is abandoned (avdmanager createhas no limit of its own, so 900 s is the make's ceiling). At startup (the firstlistSources, which core runs at daemon start), the driver stops each leftover's emulator (ownership-gated by its own path), deletes its folder and row, and leaves every folder under<root>/sources/that no row names in place, reported bydoctoras an orphan source and deleted only bydoctor --purge-orphans(decided in delivery, confirmed by the maintainer 2026-11-04). Amakingrow this process is making is never touched: not by another kind's seed making, not bylistSources, doctor or nuke. - of a copy: a
<root>/<id>/folder with no registry record, listed bylistManaged; it is an orphan, as an unregistered AVD is today (F28). - of a destroy: the folder may be half deleted; the registry record stays and the next destroy deletes the rest.
Two callers at once: two provisions of one kind with no seed make one seed (an in-process lock per spec_key; the second waits and copies). Makes of different kinds run side by side and never touch each other's rows or folders. Two calls on one device queue on its lock, now keyed by its AVD folder.
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" — seeds live in
<root>/sources/, are never reported bylistManagedand never booted after their snapshot save. - ADR 0061 §2: "keys every device by its own AVD folder" and "never
-wipe-data" — the lock,#devices, the ownership gate andlistManageduse the folder; copies boot-snapshot simlock_boot. - ADR 0061 §2: "The per-AVD
simlock_clean_baselinesnapshot, its marker file and the config-hash wipe go" — all three are deleted; the hash is kept only for staleness. - ADR 0061 §2: copy through "one filesystem port verb,
copyTree(from, to)" — no driver runscpitself. - 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 0001 (owned roots) and safety rule 8: "Ownership is proven, never inferred" — every copy and seed lives under the marked root, and
emu avd pathagainst the device's own folder is the proof; the shared AVD namesimlockis never evidence. - Safety rule 1: "only shuts down, erases, or deletes devices ... that exist in its own registry", with ADR 0061 §1's amendment that a driver may destroy its own sources —
destroydeletes only a registry device's own folder;destroySourceand the leftover sweep only a folder under<root>/sources/of the marked root. - ADR 0036 §2: "Every value is a column; each owner keeps its own tables" —
android_source_data, no JSON text. - Architecture rule 9: "Every external API is accessed through a port interface" —
cpruns inside the filesystem adapter. - Architecture rule 11: "Every wait that crosses a process boundary is bounded" —
copyTree'scp600 s, power-off 60 s; the Node fallback runs in-process and is unbounded, as its comment says. - Documentation rule 9: the troubleshooting log fields and the snapshot line on "working with a device" change in this PR.
Tests
Seam: AndroidDriver (provision, makeReady, destroy, listManaged, listSources, destroySource, removeComponent) on ScriptedProcessRunner and MemoryFilesystem, modelled on "deletes only the provisioned simlock AVD" and "stops a discovered running emulator before deleting its AVD after a restart" in src/drivers/android/index.test.ts; the port in src/ports/filesystem.test.ts; the real emulator in e2e/slow-android-smoke.test.ts.
- An agent leases a plain Android device: Simlock copies the kind's seed into the device's own folder, making it first if there is none, and boots it from the boot snapshot — cases: no seed yet (create, cold boot,
shell sync+shell reboot -p, cold boot,snapshot save simlock_boot, kill, row inserted, then the copy); seed present (noavdmanager create, one copy,-snapshot simlock_boot -no-snapshot-save,ANDROID_AVD_HOME=<root>/<id>); the snapshot does not load (ready late,snapshot-cold-bootwithdeviceId, no-wipe-dataanywhere); seed stale (emulator version changed: destroyed and made again; changed back: reason cleared); two provisions at once with no seed (one seed made); two kinds made at once (neither touches the other'smakingrow); seed making fails (cold boot not ready, power-off past 60 s,simlock_bootnot saved: each removes folder and row and throws its message); copy fails (<root>/<id>/removed, throwscopying Android seed ...); leftovers at startup (amakingrow of an earlier process: emulator stopped by path, folder and row deleted; a folder with no row: left in place, reported bydoctor, deleted bydoctor --purge-orphans); arecoverboot (-no-snapshot-load, no snapshot); estimates (provision 1 s with a seed, 150 s without;prepareboot 4 s);listSources(eachreadyseed with model, OS, image tag, size and stale reason; amakingrow left out; no size whendirectorySizethrows);destroySource(its running emulator stopped by path, folder and row gone); the system image removed (removeComponentdestroys that image's seeds, a failed destroy leaves the seed listed stale). Replaces the clean-baseline tests from "validates a new clean baseline" (index.test.ts:707) to "quotes a 4 s prepare boot" (:1137). - A plain Android device is destroyed: the ownership check passes, the emulator is killed and its folder deleted — cases: check passes (
emu kill, then<root>/<id>/gone); check fails (unreadable or timed-out answer: nothing sent, refused, folder kept); another path answers (nothing sent to that emulator, the device's own folder deleted; decided in delivery, confirmed by the maintainer 2026-11-04);rmthrows (destroy throws, nothing else deleted); a device made before this change (avdmanager delete avd -n simlock_<id>withANDROID_AVD_HOME=<root>);reclaimof a virtual device (throwsvirtual devices are not reclaimed). Extendsindex.test.ts:1656and:5231. - Two running copies of one seed are told apart: listing, locks and the ownership check go by each device's own AVD folder — cases: two copies running (each serial mapped to its own device by
emu avd path, adestroyof one never kills the other); old-layout AVD (<root>/simlock_<id>.avdstill listed and attributed); seed folder is not a device (<root>/sources/neither listed nor its running emulator attributed). Extends "manages every AVD in its root" (index.test.ts:4872). - A source is copied through the filesystem port — cases: macOS (
cp -c -p -R <from> <to>through the injected runner, and a real run on a temp folder keeping modification times, skipped when not on darwin); Linux (cp -a --reflink=auto <from> <to>through the injected runner); other (Node copy, modification times kept, on a temp folder);cpfails (rejects with its stderr);cppasttimeoutMs(killed, rejects withtimed out after <timeoutMs>ms);MemoryFilesystemcopy keepsmodifiedAtMs.
Done when
pnpm exec vitest run --project unit src/drivers/android src/ports/filesystem.test.tspasses.grep -rn "simlock_clean_baseline\|simlock-clean-baseline\|wipe-data" src/drivers/android/index.tsprints only the old-layout prepare line named under Out of scope.- Slow lane, real emulator:
e2e/slow-android-smoke.test.tspasses, including a new test: two plain leases of Pixel 9 at once are granted from one seed (one folder under<home>/devices/android/sources/), each in<home>/devices/android/<driverDeviceId>/simlock.avd; a file written withsimlock adb --lease <first> shell touch /data/local/tmp/t2is absent on a lease made after both are released, which gets a new driver device id; the daemon log holds noAndroid snapshot boot fell back to a cold boot; after release each released device's folder is gone anddoctorlists one Android seed insourceswithsizeBytesabove 0. src/drivers/android/AGENTS.mddescribes the seed, the copy, the per-folder keys andandroid_source_data, and no longer names the clean baseline;src/ports/AGENTS.mdnamescopyTree;troubleshooting.mdxnames thedeviceIdfield.
Out of scope
- Baselines: saving, listing, removing, naming one in a request (An operator saves, lists and removes baselines on a worker #1206, A lease names a baseline and gets a copy of it #1207).
- Core's release, doctor and nuke paths and the Driver verb signatures (iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204).
- A disk-space check before a copy on a filesystem without copy-on-write.
- Prepare of a device made before this change: it boots
-wipe-data -no-snapshot-loadonce (the old clean-baseline snapshot is ignored) and is destroyed at its release by iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204's path. - Low-RAM emulators (Lease an Android device that runs as a low-RAM device #484) and emulator RAM and cores in config (Lighter, faster-to-reset devices for a pool of coding agents on one Mac #1049 point 3).
Depends on
Written by an agent.
Activity
test: a source is copied through the filesystem port (#1205)
feat(ports): copyTree copies a folder through cp, keeping modificatio…
test: a plain Android device is destroyed after its ownership check (#…
feat(android): destroy deletes a copy's folder after its ownership ch…
feat(android): the snapshot cold boot warning names the device id (#1205
test: a stale seed carries its reason, which clears when the image an…
feat(android): a seed's stale reason is recomputed on each listing an…
test: a failed seed make removes its folder and row, and a failed cop…
feat(android): a failed seed make removes its folder and row, a faile…
test: two plain leases of one kind provisioned at once make one seed (#…
17 remaining items
test(android): a destroyed virtual device closes the loopback listene…
test(android): a kind with a ready seed is provisioned while another …
test(android): the restart shutdown test and the live smoke test drop…
test(android): helper comments say what they model (#1205)
refactor(android): listManaged attributes a serial in one method; the…
docs: the tunnel cleanup text and the reclaim comment say a virtual d…
test(android): the probes the audit found green now fail: the 12 s bo…
test: a worker registers both platforms' source-data owners; destroy …
fix(android): the seed's sync and power-off are bounded to 60 s; the …
docs(android): stale reclaim and wipe claims in comments and test tit…
docs(android): two test titles name an emulator's destroy, not a recl…
chore: merge origin/task/1204 into the task, carrying main's emulator…
docs(test): the adb-server comment sits on RepliesTcpStreamConnector,…
feat(android): every emulator is a copy of a seed, booted from its bo…