Skip to content

Android: every emulator is a copy of a seed in its own folder, booted from its boot snapshot #1205

Closed

Description

@V3RON

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 id seed_<generated id>), outside every device's AVD home, is never leased, and only doctor and disk figures show it.
  • boot snapshot: the one quick-boot snapshot simlock_boot saved in a seed. It replaces today's per-device simlock_clean_baseline (F3, F5).
  • copy: <root>/<device id>/simlock.avd plus <root>/<device id>/simlock.ini, made from the seed's folder with cp keeping file times (F22). The driver device id keeps today's form simlock_<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 &lt;root&gt;/&lt;id&gt;/ (new)"]
  C --> B["boot -snapshot simlock_boot<br/>(changed: was clean-baseline / wipe)"] --> L[lease]
  L --> R["release: destroy, delete &lt;root&gt;/&lt;id&gt;/<br/>(changed: was snapshot load into the running emulator)"]
Loading

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_id answers 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 boot carries deviceId and readyAfterMs (today avdName, F17): every copy's AVD is named simlock, 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. provision and listSources recompute it each time: when the image and emulator match again, it clears.
  • a virtual device given to reclaim or reclaimStrategy (a programming error; maintainer, Named baselines: a lease starts from a device the operator prepared #327 spec session): DriverCrashError virtual 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
Loading

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>/
Loading

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, owner android-source-data, version 1, modelled on iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204's ios_source_data): source_id TEXT PRIMARY KEY, kind TEXT NOT NULL (seed or baseline; An operator saves, lists and removes baselines on a worker #1206 writes baseline), state TEXT NOT NULL (making or ready), 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 while making), size_bytes INTEGER (null when not counted), stale_reason TEXT (null when fresh), created_at INTEGER NOT NULL. At most one ready seed per spec_key. STRICT, no JSON text (ADR 0036 §2). The row is written with state making before any folder exists and set ready at the end (maintainer, Named baselines: a lease starts from a device the operator prepared #327 spec session).
  • android_device_data goes to version 2: a nullable avd_home TEXT column. AndroidDriverData gains avdHome?: 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 has avd_home null and reads back without avdHome.

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).

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 making row and its <root>/sources/<sid>/ folder, maybe with its emulator running. A making row is leftover when this process is not making it (the driver keeps the ids it is making in memory) or when its created_at is more than 900 s old, even if this process is making it: the next make of that kind, or the next listSources, then treats it as leftover and that make is abandoned (avdmanager create has no limit of its own, so 900 s is the make's ceiling). At startup (the first listSources, 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 by doctor as an orphan source and deleted only by doctor --purge-orphans (decided in delivery, confirmed by the maintainer 2026-11-04). A making row this process is making is never touched: not by another kind's seed making, not by listSources, doctor or nuke.
  • of a copy: a <root>/<id>/ folder with no registry record, listed by listManaged; 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 by listManaged and 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 and listManaged use the folder; copies boot -snapshot simlock_boot.
  • ADR 0061 §2: "The per-AVD simlock_clean_baseline snapshot, 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 runs cp itself.
  • 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 path against the device's own folder is the proof; the shared AVD name simlock is 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 — destroy deletes only a registry device's own folder; destroySource and 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" — cp runs inside the filesystem adapter.
  • Architecture rule 11: "Every wait that crosses a process boundary is bounded" — copyTree's cp 600 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 (no avdmanager create, one copy, -snapshot simlock_boot -no-snapshot-save, ANDROID_AVD_HOME=<root>/<id>); the snapshot does not load (ready late, snapshot-cold-boot with deviceId, no -wipe-data anywhere); 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's making row); seed making fails (cold boot not ready, power-off past 60 s, simlock_boot not saved: each removes folder and row and throws its message); copy fails (<root>/<id>/ removed, throws copying Android seed ...); leftovers at startup (a making row of an earlier process: emulator stopped by path, folder and row deleted; a folder with no row: left in place, reported by doctor, deleted by doctor --purge-orphans); a recover boot (-no-snapshot-load, no snapshot); estimates (provision 1 s with a seed, 150 s without; prepare boot 4 s); listSources (each ready seed with model, OS, image tag, size and stale reason; a making row left out; no size when directorySize throws); destroySource (its running emulator stopped by path, folder and row gone); the system image removed (removeComponent destroys 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); rm throws (destroy throws, nothing else deleted); a device made before this change (avdmanager delete avd -n simlock_<id> with ANDROID_AVD_HOME=<root>); reclaim of a virtual device (throws virtual devices are not reclaimed). Extends index.test.ts:1656 and :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, a destroy of one never kills the other); old-layout AVD (<root>/simlock_<id>.avd still 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); cp fails (rejects with its stderr); cp past timeoutMs (killed, rejects with timed out after <timeoutMs>ms); MemoryFilesystem copy keeps modifiedAtMs.

Done when

  • pnpm exec vitest run --project unit src/drivers/android src/ports/filesystem.test.ts passes.
  • grep -rn "simlock_clean_baseline\|simlock-clean-baseline\|wipe-data" src/drivers/android/index.ts prints only the old-layout prepare line named under Out of scope.
  • Slow lane, real emulator: e2e/slow-android-smoke.test.ts passes, 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 with simlock adb --lease <first> shell touch /data/local/tmp/t2 is absent on a lease made after both are released, which gets a new driver device id; the daemon log holds no Android snapshot boot fell back to a cold boot; after release each released device's folder is gone and doctor lists one Android seed in sources with sizeBytes above 0.
  • src/drivers/android/AGENTS.md describes the seed, the copy, the per-folder keys and android_source_data, and no longer names the clean baseline; src/ports/AGENTS.md names copyTree; troubleshooting.mdx names the deviceId field.

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 3, 2026
  4. 17 remaining items

  5. added a commit that references this issue on Nov 4, 2026
    026e724
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