Repository navigation
Description
Part of #327.
Scope
An operator who holds a lease on a simulator or emulator can save it under a name as a baseline, see every baseline on the worker with its spec, version, size and whether it is stale, and remove one nobody uses. Saving ends the lease. Saving under a name that exists makes a new version and drops the old one. simlock nuke --delete-devices removes every baseline, and simlock doctor lists their sources. Nothing leases from a baseline yet: that is #1207. A gateway refuses the three operations until #1208.
Devices carry the baseline they were copied from only from #1207 on. This task adds the field to the device record so removal can read it, but nothing writes it here; the "in use" and "idle devices" cases of remove are proved with registry rows written by the test. Keeping an old version while devices of it remain is #1207's (R10 of the spec session): here a replace drops the old version at once, since no device carries one.
In short
An operator prepares a device on a held lease and runs simlock baseline save <name> --lease <id>. Simlock shuts the device down cleanly, keeps a copy of it as a source under the name, ends the lease and deletes the device. simlock baseline list shows the baselines; simlock baseline remove <name> deletes one.
A baseline is a named source an operator saved from a held lease, e.g. checkout. Its version is 1 at the first save and one more at each save under the same name. It is stale when the runtime, system image or emulator it was made with changed after the save, e.g. checkout after the Android 36 image was removed; it is fresh again if that runtime or image comes back.
sequenceDiagram
actor Op as Operator
participant D as Worker daemon
participant Dr as Driver
Op->>D: baseline.save {leaseId L1, name checkout}
D->>D: checks: admin, name, lease exists, virtual
D->>D: wait for any save or remove running on this worker
D->>D: end lease L1 (lease.released, explicit)
D->>Dr: saveSource(device) [new]
Dr-->>D: source id, size in bytes
D->>D: baselines row v1, baseline.saved [new]
D->>Dr: destroy(device)
D-->>Op: saved checkout v1, lease L1 ended
Before:
$ simlock baseline list
{"error":{"code":"USAGE","message":"Unknown command: baseline (run `simlock --help` for usage)"}}
After (sizes are the source's bytes on disk, divided by 10^9 and shown with one decimal as GB; below 1 GB divided by 10^6 as MB; - when the size could not be counted; the saved time is the worker's local time to the minute):
$ SIMLOCK_TOKEN=<operator token> simlock baseline save checkout --lease L1 --note "app 4.2, test user"
Saved baseline checkout v1: android Pixel 9, Android 36 (google_apis), full, 4.8 GB. Lease L1 ended.
$ SIMLOCK_TOKEN=<operator token> simlock baseline save checkout --lease L3
Saved baseline checkout v2: android Pixel 9, Android 36 (google_apis), full, 4.9 GB. Lease L3 ended.
$ SIMLOCK_TOKEN=<operator token> simlock baseline save login --lease L5 --note "signed in"
Saved baseline login v1: ios iPhone 17, iOS 27.0, slim, 3.1 GB. Lease L5 ended.
$ simlock baseline list
NAME VERSION PLATFORM MODEL OS MODE IMAGE SIZE SAVED NOTE
checkout 2 android Pixel 9 36 full google_apis 4.9 GB 2026-11-02 13:40
login 1 ios iPhone 17 27.0 slim - 3.1 GB 2026-11-01 09:12 signed in
stale: runtime com.apple.CoreSimulator.SimRuntime.iOS-27-0 is not installed
$ simlock baseline list --json
{"baselines":[{"name":"checkout","version":2,"platform":"android",…},{"name":"login",…,"staleReason":"runtime com.apple.CoreSimulator.SimRuntime.iOS-27-0 is not installed"}]}
$ SIMLOCK_TOKEN=<operator token> simlock baseline remove login
Remove baseline login v1? [y/N] y
Removed baseline login v1.
$ SIMLOCK_TOKEN=<agent token> simlock baseline save mine --lease L2
{"error":{"code":"FORBIDDEN","message":"Operation baseline.save requires role admin, session is agent"}}
$ SIMLOCK_TOKEN=<operator token> simlock baseline remove checkout --yes
{"error":{"code":"BASELINE_IN_USE","message":"baseline checkout is in use by lease L4"}}
$ SIMLOCK_TOKEN=<operator token> simlock baseline remove nothere --yes
{"error":{"code":"UNKNOWN_BASELINE","message":"no baseline named \"nothere\" on this worker"}}
$ simlock baseline list
No baselines on this worker.
Every error prints as one JSON line, as every CLI error does today (F31). The save line names the platform, model, iOS <os> or Android <os>, the image tag in brackets when the device has one, the mode and the size (left out when it could not be counted). A stale baseline's reason is the driver's words (#1204, #1205), on its own line under the row. Remove prints Deleted <n> idle devices made from it. after its line when it deleted any (device for one).
| Input | Today | After |
|---|---|---|
baseline save checkout --lease L1 (operator) |
unknown command | saved, lease L1 ended |
baseline save Checkout --lease L1 |
unknown command | BAD_REQUEST, nothing ends |
baseline save -checkout --lease L1 |
unknown command | BAD_REQUEST, nothing ends |
| a 65-character name | unknown command | BAD_REQUEST, nothing ends |
--note of 201 characters, or with a newline |
unknown command | BAD_REQUEST, nothing ends |
baseline save checkout (no --lease) |
unknown command | USAGE, exit 2 |
baseline save checkout --lease L9 (no such lease) |
unknown command | UNKNOWN_LEASE, exit 1 |
baseline save checkout --lease P1 (physical device) |
unknown command | BAD_REQUEST: lease P1 is on a physical device; only a simulator or emulator can be saved as a baseline |
baseline save checkout --lease L1 (agent token) |
unknown command | FORBIDDEN, exit 1 |
two saves of checkout at once |
unknown command | the second waits and becomes the next version |
baseline remove checkout with no terminal, no --yes |
unknown command | USAGE baseline remove requires confirmation or --yes, exit 2 |
baseline list (agent token) |
unknown command | the list |
baseline save checkout --lease L1 through a gateway |
unknown command | UNSUPPORTED_IN_GATEWAY_MODE, exit 2 (until #1208) |
If this task goes wrong, an operator runs baseline save, the lease ends, and the prepared device is gone with no baseline in the list.
Technical spec
Facts
Commit 019ba5c.
| # | Fact | Source |
|---|---|---|
| F1 | An operation is declared once with name, role, effect, input and output schemas and listed in OPERATIONS; warm.forget is an admin, write operation with an imageTagSchema field |
src/contract/operations.ts:602-614, src/contract/operations.ts:1101-1122 |
| F2 | imageTagSchema: 1 to 64 characters of letters, digits, _, ., - — the model for the baseline name |
src/contract/schemas.ts:86-90 |
| F3 | The dispatcher refuses a role mismatch with FORBIDDEN and the message Operation <op> requires role <role>, session is <role> |
src/daemon/dispatch.ts:352 |
| F4 | The worker dispatcher holds one handler per operation; warm.forget and nuke.run are two |
src/daemon/dispatcher.ts:277-278, src/daemon/dispatcher.ts:828-847 |
| F5 | The gateway dispatcher's table is typed total over the contract; warm.forget answers unsupportedByDesign, which throws UNSUPPORTED_IN_GATEWAY_MODE with details.operation and the message <op> acts on one machine's devices; run it against a worker |
src/gateway/dispatcher.ts:251-253, src/gateway/dispatcher.ts:776-783 |
| F6 | DaemonServer routes each request type to the dispatcher in a switch with one case per operation; an unlisted type is UNKNOWN_REQUEST |
src/daemon/server.ts:1165-1170, src/daemon/server.ts:1297-1298 |
| F7 | UNKNOWN_LEASE is exit 1, HTTP 404; UNKNOWN_DEVICE exit 12, 404; COMPONENT_IN_USE exit 12, 409; UNSUPPORTED_IN_GATEWAY_MODE exit 2, 501 |
src/contract/errors.ts:336, src/contract/errors.ts:387, src/contract/errors.ts:439-444, src/contract/errors.ts:492-497 |
| F8 | A spent virtual device is retired by driver.shutdown, a commit to shutdown, then driver.destroy and a commit to deleted with device.deleted (initiator lease-end); a failure goes to quarantine as shutdown-failed or delete-failed |
src/core/reclaim-coordinator.ts:96-103, src/core/reclaim-coordinator.ts:263-299, src/core/reclaim-coordinator.ts:303-315 |
| F9 | A release commits the lease end in the serialized decision section, then reclaims; release reasons are explicit, killed, device-lost; every release runs as a "normal" workflow that nuke's maintenance waits for |
src/leasing/lease-release-coordinator.ts:12, src/leasing/lease-release-coordinator.ts:255-306, src/leasing/lease-release-coordinator.ts:455-466 |
| F10 | lease.released carries lease id, device id, reason and owner id |
src/bus/index.ts:33-43 |
| F11 | Nuke runs under acquisition and release maintenance, releases every lease killed, then shuts down and, with deleteDevices, destroys every virtual device; its report is { deletedDevices, releasedLeaseIds } |
src/core/nuke-service.ts:79-118, src/core/nuke-service.ts:128-136, src/contract/schemas.ts:856-859 |
| F12 | A core table owner is a SqliteSchemaOwner (name, version, migrations) and the worker opens state.db with its owners listed in main.ts |
src/core/warm-pool/learned.ts:26-30, src/daemon/main.ts:346-349 |
| F13 | The devices table has no baseline column; the registry owner is at version 1 |
src/core/registry-schema.ts:4-35, src/core/registry-schema.ts:118-121 |
| F14 | The Driver has provision, shutdown, destroy and no verb that keeps a copy of a device |
src/core/driver.ts:263-286 |
| F15 | iOS shutdown runs simctl shutdown <udid> with a 30 s limit and treats "already shut down" as success |
src/drivers/ios/index.ts:1111-1113, src/drivers/ios/index.ts:1620-1629, src/drivers/ios/index.ts:68 |
| F16 | Android shutdown sends emu kill only after the ownership check (emu avd path, 5 s) passes, then waits for the process up to the readiness limit (default 180 s) and SIGKILLs it; with no process handle (a device adopted after a restart) it returns right after emu kill without waiting |
src/drivers/android/index.ts:1272-1277, src/drivers/android/index.ts:2192-2200, src/drivers/android/index.ts:2370-2385, src/drivers/android/index.ts:89, src/drivers/android/index.ts:134 |
| F17 | The Android driver cold-boots with -no-snapshot-load and saves a snapshot with adb -s <serial> emu avd snapshot save <name> under a 60 s limit |
src/drivers/android/index.ts:1139, src/drivers/android/index.ts:2328-2332, src/drivers/android/index.ts:137 |
| F18 | A hard emu kill right after preparing 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: adb shell sync; adb shell reboot -p → emulator exited in 2.2 s, prepared settings and /data/local/tmp file present at the next boot |
| F19 | simctl clone of a shut-down device copies data/ and device.plist, not /private/var/tmp/com.apple.CoreSimulator.SimDevice.<udid>; a clone into another device set (simctl --set <from set> clone <udid> <name> <to set>) takes 0.2 s, is listed only in the destination set, and carries a file from the source's data/ |
spike on this machine, 2026-11-02: simctl --set <s> clone <src> c1 → clone folder holds data/ and device.plist only; cross-set clone → 0.2 s, listed only in <to set>, file present |
| F20 | component remove asks Remove <platform> <version>? [y/N] on a terminal and is a usage error without one unless --yes |
src/cli/commands/component.ts:103-106 |
| F21 | The CLI tree names each command and the module that runs it; the website test requires every tree path on cli.mdx |
src/cli/tree.ts:58-70, src/cli/reference.test.ts:26-32 |
| F22 | The CLI already prints a local time to the minute as YYYY-MM-DD HH:MM |
src/cli/format.ts:177-181 |
| F23 | The client has one method per operation (forgetWarmKind → warm.forget) and the admin package re-exports its types |
src/simlock-client/client.ts:707-709, src/simlock-client/types.ts:58-59, src/admin/index.ts:69-70 |
| F24 | A declared HTTP route names method, path, role, input schemas, reply and its own error codes; component remove is DELETE /v1/components/{platform}/{version} with 501 for a gateway |
src/http/admin-declarations.ts:131-145 |
| F25 | The MCP server's tools are agent tools only: lease, list devices, release, status, run on device | src/mcp/AGENTS.md:32-39 |
| F26 | component.removed is emitted after a component removal is committed |
src/core/component-installer.ts:453 |
| F27 | The doctor report is { findings } today (#1204 adds sources) |
src/contract/schemas.ts:854 |
| F28 | Every registry write runs inside the one decision gate; a device operation is held by a claim, which other workflows read before acting on the device | src/core/create-core.ts:50-53, src/core/device-operation-claims.ts:44-48 |
| F29 | ManagedDeviceLifecycle.destroy claims a provisioning or shutdown device, calls driver.destroy, and commits deleted with device.deleted |
src/core/managed-device-lifecycle.ts:124-142 |
| F30 | CORE_ROUTE_SEGMENTS lists the first path segment of every core HTTP route, and core-routes.test.ts checks both the list and every registered route against it |
src/contract/protocol.ts:82-98, src/http/core-routes.test.ts:49-58, src/http/core-routes.test.ts:106-107 |
| F31 | The CLI writes every error as one JSON line {"error":{"code","message"}}; a UsageError is USAGE |
src/cli/errors.ts:42, src/cli/errors.ts:46 |
| F32 | A per-route HTTP test drives the route and checks the operation input it dispatches, as DELETE /v1/components/{platform}/{version} does |
src/http/app.test.ts:575-592 |
| F33 | The out-of-process e2e fake driver has provision, shutdown, destroy and no source verbs |
e2e/fake-driver/fake-driver.ts:447-451, e2e/fake-driver/fake-driver.ts:542-548 |
Modules touched
Searches: warm.forget|warmForget (9 files), nuke.run|nukeReportSchema (12), unsupportedByDesign (1), case " in src/daemon/server.ts, retireSpent|deleteSpent (1), registryOwner (6), SqliteSchemaOwner (8), component.removed (4), declareRoute( (5), registerTool( (1), CORE_ROUTE_SEGMENTS (3), implements Driver and async provision( in e2e/ (1).
src/contract/—operations.ts(baseline.save,baseline.list,baseline.remove),schemas.ts(baselineNameSchema,baselineNoteSchema,baselineEntrySchema, nuke report, the doctorsourcesentry's baseline fields),errors.ts(UNKNOWN_BASELINE,BASELINE_IN_USE,BASELINE_SAVE_FAILED),protocol.ts(bump;baselinesinCORE_ROUTE_SEGMENTS, F30),AGENTS.md.src/bus/index.ts,src/bus/index.test.ts— three events.src/core/— newbaselines.ts(BaselineService: save, list, remove, removeAll, stale check, the startup drop of unnamed baseline sources) andbaselines-schema.ts(ownerbaselines);driver.ts(saveSourceonDriver);fake-driver.ts(saveSource, a files map per device, a test hook that writes a file);reclaim-coordinator.ts(retireSaved: the spent path withsaveSourcein place ofshutdown);registry-schema.ts(version 2),registry-rows.ts,domain.ts(a virtual device'sbaseline{name, version}, read only here);nuke-service.ts(remove every baseline withdeleteDevices);doctor.ts(baseline name and version on asourcesentry);create-core.ts,core-ports.ts(theleaseSaveport);index.ts;AGENTS.md.src/leasing/lease-release-coordinator.ts—releaseToSave(leaseId, save): commits the end (explicit), calls the participants, then awaitsReclaimCoordinator.retireSavedunder thereclaimclaim;AGENTS.md.src/drivers/ios/index.ts—saveSource: the source rowmaking,simctl shutdown,simctl clonefrom the device set into the sources set (R1), copy of the device'sdisabled.plist, size, rowready.src/drivers/android/index.ts—saveSource: the source rowmaking,adb shell sync,adb shell reboot -p, wait for exit, else the ownership check andemu kill;copyTreeof the AVD folder into<root>/sources/<source id>/(Android: every emulator is a copy of a seed in its own folder, booted from its boot snapshot #1205's layout); one cold boot of the source with-no-snapshot-load,emu avd snapshot save simlock_boot, kill; size; rowready.src/daemon/—dispatcher.ts(three handlers),server.ts(three cases),main.ts(thebaselinesowner, the service, the stale check and the drop of unnamed baseline sources at start, the stale check oncomponent.removed).src/gateway/dispatcher.ts— the three operations answerunsupportedByDesignuntil A gateway routes a baseline request to a worker that holds it #1208.src/simlock-client/client.ts,types.ts;src/admin/index.ts—saveBaseline,listBaselines,removeBaseline.src/cli/—tree.ts,index.ts(usage), newcommands/baseline.ts,format.ts(the list table),AGENTS.md.src/http/—admin-declarations.ts(GET /v1/baselines,POST /v1/baselines,DELETE /v1/baselines/{name}),app.ts,app.test.ts,core-routes.test.ts,AGENTS.md.e2e/fake-driver/fake-driver.ts—saveSourceand the files map, so the console lane can save a baseline (Console: a Baselines page and a device's baseline #1209).- Docs:
docs/internal/EVENTS.md; websitereference/cli.mdx,reference/errors.mdx,reference/events.mdx,using-devices/programmatic-client.mdx, newworker/baselines.mdxand its sidebar entry inwebsite/astro.config.mjs. e2e/slow-baseline.test.ts(new).
MCP is not touched: its tools are agent tools (F25); #1207 adds the lease field there.
flowchart LR
CLI[cli baseline *]:::changed --> Client[simlock-client]:::changed
HTTP[http /v1/baselines]:::changed --> Disp
Client --> Server[daemon server]:::changed --> Disp[daemon dispatcher]:::changed
Disp --> Svc[core BaselineService]:::changed
Svc --> Rel[leasing releaseToSave]:::changed --> Rec[core retireSaved]:::changed
Rec --> Drv[drivers saveSource]:::changed --> FS[filesystem copyTree]
Svc --> Tbl[(state.db baselines)]:::changed
Svc --> Bus[bus baseline.*]:::changed
Nuke[core nuke]:::changed --> Svc
Doctor[core doctor]:::changed --> Svc
GW[gateway dispatcher]:::changed
classDef changed stroke-width:3px
sequenceDiagram
participant C as CLI
participant S as Worker daemon
participant L as leasing
participant R as core reclaim
participant Dr as Driver
C->>S: baseline.save {leaseId, name, note}
S->>S: role, input, lease exists and virtual
alt refused
S-->>C: FORBIDDEN / BAD_REQUEST / UNKNOWN_LEASE (lease untouched)
end
S->>S: queue behind any save or remove on this worker (a second save of a name waits, then is the next version)
S->>L: releaseToSave(leaseId)
L->>L: commit end, lease.released (explicit)
L->>R: retireSaved(device)
R->>Dr: saveSource(device)
Dr->>Dr: source row making, shut down, copy, row ready
alt saveSource throws
R->>R: quarantine (shutdown-failed)
S-->>C: BASELINE_SAVE_FAILED
else ok
R->>S: source id, size
S->>S: baselines row, baseline.saved; on a replace, drop the old version (baseline.removed replaced)
R->>Dr: destroy(device), device.deleted
S-->>C: {baseline, leaseId}
end
Surface and extension points
src/core/index.tsgrowsBaselineService(built bycreateCore, reached ascore.baselines):save({ leaseId, name, note?, requesterId }),list(),remove({ name, requesterId }),removeAll()(nuke),checkStale(),dropUnnamedSources()(start); andbaselinesOwner.DrivergainssaveSource(device: VirtualDriverDevice): Promise<{ sourceId: string; sizeBytes?: number }>: it writes its source row with kindbaselineandstatemakingbefore any folder or simulator exists (R2), shuts the device down cleanly itself, makes the source in the driver's own sources area (iOS: the sources device set; Android:<root>/sources/<source id>/, R1), and sets the rowready.sizeBytesis absent when it could not be counted.listSources()anddestroySource(id)are iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204's. Both fake drivers implement it (R15). No second implementation of anything: each driver implements the verb once.CorePortsgainsleaseSave: { releaseToSave(leaseId, save) }, supplied by leasing atcore.connect, asleaseMaintenanceis (core never imports leasing).
Contract and event changes
This PR bumps the protocol by one.
baselineNameSchema: string, 1 to 64 characters,^[a-z0-9][a-z0-9._-]*$; elseBAD_REQUESTbaseline name may contain only a-z, 0-9, '.', '_' and '-', and must start with a letter or digit.baselineNoteSchema: string, 0 to 200 characters, no control characters; elseBAD_REQUEST.baselineEntrySchema:name,version(integer ≥ 1),platform,model(≤ 64),osVersion(≤ 64),mode(slim|full),imageTag?(imageTagSchema),note?,sizeBytes?(integer ≥ 0, absent when not counted),savedAt(ISO 8601 string),staleReason?(≤ 300 characters).baseline.save: roleadmin, effectwrite, input{ leaseId: string 1..256, name, note? }strict; output{ baseline: entry, leaseId }.baseline.list: roleagent, effectread, input{}; output{ baselines: entry[] }, sorted by name, the newest version of each name only.baseline.remove: roleadmin, effectwrite, input{ name }strict (so aworkerIdisBAD_REQUEST); output{ name, versions: number[], deletedDevices: string[] },versionsevery version deleted, oldest first.nuke.runoutput gainsremovedBaselines: string[](names), empty withoutdeleteDevices.doctor.run: asourcesentry (iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204) of kindbaselinegainsbaselineNameandbaselineVersion. No doctor finding for a baseline; a source never makesfindingsnon-empty (R5).- Errors:
UNKNOWN_BASELINE{ name }, exit 12, HTTP 404, messageno baseline named "<name>" on this worker;BASELINE_IN_USE{ name, leaseId }, exit 12, HTTP 409, messagebaseline <name> is in use by lease <id>;BASELINE_SAVE_FAILED{ name, leaseId }, exit 1, HTTP 500, messagebaseline <name> was not saved: <driver message>. Lease <id> has ended.A physical lease isBAD_REQUESTwith the message in In short. - HTTP:
GET /v1/baselines(agent) →baseline.list;POST /v1/baselines(admin, JSON body{leaseId, name, note?}, strict) →baseline.save, 200;DELETE /v1/baselines/{name}(admin) →baseline.remove, 200. Each declares 501UNSUPPORTED_IN_GATEWAY_MODE; save declares 404UNKNOWN_LEASE, 500BASELINE_SAVE_FAILED; remove 404UNKNOWN_BASELINE, 409BASELINE_IN_USE. The name path value goes throughbaselineNameSchemain the dispatcher.baselinesjoinsCORE_ROUTE_SEGMENTS. - Events, with entries in
docs/internal/EVENTS.mdandevents.mdx(relayed):baseline.saved{ name, version, platform, model, osVersion, mode, imageTag?, sizeBytes?, leaseId, requesterId }after the row is committed;baseline.removed{ name, version, reason: "operator" | "nuke" | "replaced", requesterId? }once per version deleted, after its row is deleted;baseline.stale{ name, version, reason }when a fresh baseline is found stale (again after it was fresh in between).device.deletedgains initiatorbaseline-save(additive). state.db: ownerbaselines, version 1, tablebaselines(name,version,platform,model,os_version,mode,image_tag,note,saved_at,source_id,stale_reason; primary key(name, version); STRICT). The size is read from the source (listSources), not stored here. Ownerregistrygoes to version 2:baseline_name TEXT,baseline_version INTEGERondevices(R9).
Other code on the same state
Searches: the lease release path (beginRelease 6 hits, releaseAll 9), the spent path (retireSpent|deleteSpent 4), device destroy (devices.destroy|driver.destroy 11), nuke (releaseAllDuringMaintenance 5), source tables (#1204, #1205), devices table writers (Registry only), device claims (DeviceOperationClaims 1).
| Component | Same state | Both act | Who wins |
|---|---|---|---|
lease.release by the holder (F9) |
the lease | release first: the save answers UNKNOWN_LEASE and the device is reclaimed as usual; save first: the release answers UNKNOWN_LEASE |
the first commit in the serialized section |
| Lease expiry (F9) | the lease | same as release; expiry after the save's commit finds no lease | the first commit |
| Nuke (F11) | leases, devices, baselines | a save runs as a normal release workflow, so nuke's maintenance waits for it; with --delete-devices nuke then removes every baseline, rows first, then sources (R4); #1204's nuke destroys seeds only; a save asked during maintenance waits its turn like any release |
nuke after the save |
| Health monitor / crash recovery | the device | the lease ends before saveSource shuts the device down, so the monitor no longer watches it |
the save |
| Warm pool, idle rules, cleanup reaper | the device | the reclaim claim is held from the end commit to the delete, so none picks the device |
the save |
Another baseline.save or baseline.remove |
the baselines rows |
BaselineService runs one save or remove at a time per worker, in arrival order; a second save of one name becomes the next version |
the first |
baseline.remove and leasing (F28) |
devices of the baseline | the in-use check and a claim on each idle device of the baseline run in one decision-gate section; the claimed devices are then shut down and destroyed (F29) | the first in the gate |
| #1204 / #1205 seed making and cleanup | sources area | a baseline source has kind baseline and is never copied for a plain lease; its row is written making first, and a making row of this daemon process is never touched by seed making or cleanup (R2) |
each by kind |
component.remove (F26) |
sources | after component.removed the service runs checkStale() |
the removal |
| #1207 (provision from a baseline) | devices.baseline_*, baselines |
#1207 writes the device's baseline and keeps an old version while devices of it remain (R10); this task only reads the field and drops a replaced version at once | #1207 writes, #1206 reads |
Failure modes
| Call | Outcome | What happens | Limit, counted from |
|---|---|---|---|
baseline.save checks |
refused | FORBIDDEN, BAD_REQUEST, UNKNOWN_LEASE: nothing ends |
none |
releaseToSave |
lease gone at commit | UNKNOWN_LEASE; nothing else runs |
none |
iOS saveSource → simctl shutdown |
ok / already shut down | continues to the clone | 30 s, from the call (F15) |
iOS saveSource → simctl shutdown |
fails or times out | source row deleted; saveSource throws; device quarantined shutdown-failed; BASELINE_SAVE_FAILED |
30 s, from the call |
iOS saveSource → simctl clone |
fails or times out | partial clone and row deleted; throws as above | 30 s, from the call |
Android saveSource → shell sync, shell reboot -p |
ok, emulator exits | continues to the copy; the exit is seen on the process handle, or, with none (adopted after a restart, F16), by polling adb devices every second until the serial is gone |
5 s per command; 60 s for the exit, from reboot -p sent |
Android saveSource → reboot -p |
emulator still running at 60 s | ownership check, then emu kill (F16) and the same wait; continues |
5 s check |
Android saveSource → ownership check |
fails | nothing is sent; row deleted; throws; quarantined; BASELINE_SAVE_FAILED |
5 s, from the check |
Android saveSource → copyTree |
cp fails or times out |
cp killed at the limit; partial source folder and row deleted; throws as above |
600 s, from the cp spawn (R17) |
Android saveSource → source cold boot and snapshot save simlock_boot |
boot not ready, or save fails | source killed, folder and row deleted; throws as above | readiness limit (default 180 s) from the launch; 60 s from the save command (F17) |
destroy of the saved device |
fails | baseline is kept and answered; device quarantined delete-failed and retried (F8) |
as today |
listSources() |
a platform has no driver | its baselines list with staleReason the <platform> driver is not available on this worker, not stored, no event |
none |
destroySource on replace or remove |
fails | row kept, error answered INTERNAL; the next remove or replace tries again |
none |
- Restart during a save: the lease end and the device's
reclaimingstate are committed first, so startup recovers the device as an interrupted reclaim (today's path). The driver's source row leftmakingby the earlier process is destroyed by the driver at start (R2). Areadybaseline source that nobaselinesrow names is kept, reported bydoctoras an orphan source with its size, and destroyed only bydoctor --purge-orphans(decided in delivery, confirmed by the maintainer 2026-11-04). Nobaselinesrow exists before the source isready, so a restart never leaves a baseline that points at half a copy. - Stale check:
checkStale()reads each baseline's source fromlistSources()and stores its stale reason, or clears it when the runtime or image matches again. It runs at start, aftercomponent.removed, and before answeringbaseline.listanddoctor.run.baseline.stalefires when a reason is set on a row that had none.
Every row whose outcome an invoker sees has its case on the save, remove or list Tests line; the restart line's interrupted-reclaim part is today's path, proved by src/core/reclaim-coordinator.test.ts, and its source parts are save-line cases.
Rules in play
- Safety rule 1 (
docs/internal/agent-rules/safety.md:7-10), "only shuts down, erases, or deletes devices ... that exist in its own registry", with the amendment ADR 0061 §1 names (a driver may destroy its own sources): a save and a remove act only on registry devices and on sources in the driver's own table and sources area. - Safety rule 2 (
docs/internal/agent-rules/safety.md:54-58), "Never touch a leased device": the lease ends beforesaveSourcetouches the device; remove refuses a baseline with a leased device. - Safety rule 5 (
docs/internal/agent-rules/safety.md:84-85), "Destructive CLI commands confirm or require--yes":baseline removeasks or needs--yes;savenames the lease it ends. - Safety rule 6 (
docs/internal/agent-rules/safety.md:86-87), "Every destructive action is attributable":baseline.savedandbaseline.removedcarryrequesterId. - Events rules 3 and 8 (
docs/internal/agent-rules/events.md:12-14,docs/internal/agent-rules/events.md:30-31): emitted after the commit; documented in both catalogs. - ADR 0036 §2: owner
baselineskeeps its own table, no JSON text. - ADR 0061 §1: sources live where agents cannot reach them; §4: save ends the lease after a clean shutdown; remove refused while a lease uses it.
- Contract "Protocol version" (
src/contract/AGENTS.md): one bump. - Documentation rule 9: the CLI, HTTP, client, errors and events pages change in this PR.
Tests
Seam: the worker dispatcher, src/daemon/dispatcher.test.ts (model: describe("Dispatcher: warm.forget") and describe("Dispatcher: component.remove")) with FakeDriver; the iOS and Android cases of the save line also run at the driver seam, src/drivers/ios/index.test.ts and src/drivers/android/index.test.ts, with the faked process runner; the CLI output in src/cli/index.test.ts (model: describe("CLI: warm forget")); the HTTP cases in src/http/app.test.ts (model: the DELETE /v1/components/{platform}/{version} block, F32).
- An operator saves a held lease as a baseline: the lease ends, and the baseline is version 1, or one more than before under the same name. Cases: iOS (row
making,simctl shutdown,simctl cloneinto the sources set, the device'sdisabled.plistcopied, rowready, the device deleted); Android (shell sync,reboot -p,copyTree, one cold boot with-no-snapshot-loadsavingsimlock_boot, the device deleted); Android that does not power off in 60 s (ownership check,emu kill, still saved); Android with no process handle (exit seen byadb devices); fake driver (a file written on the device is in the copy's files); existing name (version 2, v1 row and source dropped,baseline.removedreplaced); two saves of one name at once (versions 1 and 2); namesCheckout,-checkout, 65 characters and a 201-character note (BAD_REQUEST, lease untouched); no--lease(USAGE, exit 2); agent token (FORBIDDEN, lease untouched); physical lease (BAD_REQUEST, lease untouched); unknown lease (UNKNOWN_LEASE);saveSourcefails (BASELINE_SAVE_FAILED, lease ended, device quarantined, no row); restart (amakingsource of an earlier process destroyed at start; areadybaselinesource no row names kept and reported bydoctor, deleted bydoctor --purge-orphans); HTTPPOST /v1/baselines(body dispatched asbaseline.save; agent token 403). - An operator lists baselines: each shows name, version, spec, note, size, saved time and stale reason. Cases: none (
No baselines on this worker.); one (the table row, and the--jsonanswer); no size (-); stale (thestale:line, from a source whose runtime is gone; cleared when it is back); doctor (thesourcesentry of kindbaselinecarriesbaselineNameandbaselineVersion,findingsempty); HTTPGET /v1/baselineswith an agent token. - An operator removes a baseline: an unused one and its idle devices go; one in use is refused. Cases: unused (source destroyed, a registry row of an idle device of it shut down and destroyed,
Deleted 1 idle device made from it.); in use (BASELINE_IN_USEnaming the lease, from a registry row leased); unknown (UNKNOWN_BASELINE); no terminal and no--yes(USAGE); HTTPDELETE /v1/baselines/{name}(path name dispatched asbaseline.remove;Checkoutis 400). - Saving, removing and a baseline going stale each record one event. Cases: saved (
baseline.savedwith the spec, size, lease id and requester); removed by operator (reason: operator); removed by nuke (nuke --delete-devicesremoves every baseline,reason: nuke,removedBaselinesin the report; plain nuke keeps them); removed as replaced (reason: replaced); stale (onebaseline.staleaftercomponent.removed, none on the next check, one more after it was fresh again).
The gateway answers are one more entry in src/gateway/dispatcher.test.ts's UNSUPPORTED_IN_GATEWAY_MODE table. src/http/core-routes.test.ts gains baselines in its segment list (F30).
Done when
pnpm exec vitest run --project unit src/daemon/dispatcher.test.ts src/cli/index.test.ts src/drivers/ios/index.test.ts src/drivers/android/index.test.ts src/gateway/dispatcher.test.ts src/bus/index.test.ts src/http/app.test.ts src/http/core-routes.test.ts src/cli/reference.test.tspasses.node .agents/scripts/protocol-bump-check.mjspasses andnode .agents/scripts/docs-surface-check.mjsprints no unmatched surface.pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjspasses and the HTTP reference lists the three/v1/baselinesroutes.- On a Mac with an iOS runtime:
e2e/slow-baseline.test.tsleases an iPhone, writes a file into its data folder, runssimlock baseline save, and finds the lease ended,simlock baseline listshowing version 1 with a size above 0, the source listed only in the sources set (not bysimlock simctl list), and the file inside the source's data folder. - On a Mac with the Android emulator:
e2e/slow-baseline.test.tsleases an emulator, writes a setting withadb shell settings put, saves it, and finds the lease ended, the list showing version 1, and asnapshots/simlock_bootfolder in the source; that a copy boots with the setting is A lease names a baseline and gets a copy of it #1207's check.
Out of scope
- Leasing from a baseline,
--baseline,SIMLOCK_BASELINE,BASELINE_MISMATCHand refusing a stale one (A lease names a baseline and gets a copy of it #1207). - Writing a device's baseline fields at provision, destroying idle devices of an older version at replace, and keeping an old version until its last device goes (A lease names a baseline and gets a copy of it #1207).
- Gateway answers,
worker listbaselines,--workeron remove (A gateway routes a baseline request to a worker that holds it #1208); the console page (Console: a Baselines page and a device's baseline #1209). - Rolling back to an older version; moving baselines between workers.
Depends on
Written by an agent.
Activity
test: baseline.save refuses a bad name or note, a non-admin, an unkno…
feat(daemon): baseline.save refuses a lease that is unknown or on a p…
test: a save under an existing name is the next version and drops the…
feat(core): a baseline saved under an existing name replaces the olde…
test: a save the driver cannot make answers BASELINE_SAVE_FAILED with…
feat(core): a save the driver cannot make answers BASELINE_SAVE_FAILE…
test: an operator lists baselines: the newest version of each with it…
feat(core): baseline.list answers the newest version of each baseline…
test: a baseline whose source reports a stale reason lists it, and li…
feat(core): checkStale stores each baseline's stale reason from its s…
32 remaining items
docs: baselines page, programmatic client, manuals and the architectu…
test(http): the OpenAPI document tags the three baseline routes (#1206)
refactor: baseline code reads smaller to Fallow: the device row's bas…
chore: merge task/1205 into the task, keeping both sides of the cli m…
test(android): saveSource tests boot a lease whose emulator stays up …
test(leasing): releaseToSave claims, ends as explicit and holds maint…
chore(leasing): releaseToSave is now reached by a test, so its Fallow…
test(daemon): baseline routes reach the dispatcher, the start pass ma…
fix(core): remove releases every cleanup claim, one stale transition …
docs(website): doctor sources can be baseline copies, and an unnamed …
docs(core): the core manual fits the 150-line budget (#1206)
test(core): a throwing dispose during baseline remove still disposes …
feat(baselines): save, list and remove baselines from held leases (#1235
feat(leasing): a lease names a baseline and gets a copy of it (#1236)