Skip to content

An operator saves, lists and removes baselines on a worker #1206

Closed

Description

@V3RON

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
Loading

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 doctor sources entry's baseline fields), errors.ts (UNKNOWN_BASELINE, BASELINE_IN_USE, BASELINE_SAVE_FAILED), protocol.ts (bump; baselines in CORE_ROUTE_SEGMENTS, F30), AGENTS.md.
  • src/bus/index.ts, src/bus/index.test.ts — three events.
  • src/core/ — new baselines.ts (BaselineService: save, list, remove, removeAll, stale check, the startup drop of unnamed baseline sources) and baselines-schema.ts (owner baselines); driver.ts (saveSource on Driver); fake-driver.ts (saveSource, a files map per device, a test hook that writes a file); reclaim-coordinator.ts (retireSaved: the spent path with saveSource in place of shutdown); registry-schema.ts (version 2), registry-rows.ts, domain.ts (a virtual device's baseline {name, version}, read only here); nuke-service.ts (remove every baseline with deleteDevices); doctor.ts (baseline name and version on a sources entry); create-core.ts, core-ports.ts (the leaseSave port); index.ts; AGENTS.md.
  • src/leasing/lease-release-coordinator.ts — releaseToSave(leaseId, save): commits the end (explicit), calls the participants, then awaits ReclaimCoordinator.retireSaved under the reclaim claim; AGENTS.md.
  • src/drivers/ios/index.ts — saveSource: the source row making, simctl shutdown, simctl clone from the device set into the sources set (R1), copy of the device's disabled.plist, size, row ready.
  • src/drivers/android/index.ts — saveSource: the source row making, adb shell sync, adb shell reboot -p, wait for exit, else the ownership check and emu kill; copyTree of 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; row ready.
  • src/daemon/ — dispatcher.ts (three handlers), server.ts (three cases), main.ts (the baselines owner, the service, the stale check and the drop of unnamed baseline sources at start, the stale check on component.removed).
  • src/gateway/dispatcher.ts — the three operations answer unsupportedByDesign until 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), new commands/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 — saveSource and 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; website reference/cli.mdx, reference/errors.mdx, reference/events.mdx, using-devices/programmatic-client.mdx, new worker/baselines.mdx and its sidebar entry in website/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
Loading
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
Loading

Surface and extension points

  • src/core/index.ts grows BaselineService (built by createCore, reached as core.baselines): save({ leaseId, name, note?, requesterId }), list(), remove({ name, requesterId }), removeAll() (nuke), checkStale(), dropUnnamedSources() (start); and baselinesOwner.
  • Driver gains saveSource(device: VirtualDriverDevice): Promise<{ sourceId: string; sizeBytes?: number }>: it writes its source row with kind baseline and state making before 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 row ready. sizeBytes is absent when it could not be counted. listSources() and destroySource(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.
  • CorePorts gains leaseSave: { releaseToSave(leaseId, save) }, supplied by leasing at core.connect, as leaseMaintenance is (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._-]*$; else BAD_REQUEST baseline 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; else BAD_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: role admin, effect write, input { leaseId: string 1..256, name, note? } strict; output { baseline: entry, leaseId }.
  • baseline.list: role agent, effect read, input {}; output { baselines: entry[] }, sorted by name, the newest version of each name only.
  • baseline.remove: role admin, effect write, input { name } strict (so a workerId is BAD_REQUEST); output { name, versions: number[], deletedDevices: string[] }, versions every version deleted, oldest first.
  • nuke.run output gains removedBaselines: string[] (names), empty without deleteDevices.
  • doctor.run: a sources entry (iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204) of kind baseline gains baselineName and baselineVersion. No doctor finding for a baseline; a source never makes findings non-empty (R5).
  • Errors: UNKNOWN_BASELINE { name }, exit 12, HTTP 404, message no baseline named "<name>" on this worker; BASELINE_IN_USE { name, leaseId }, exit 12, HTTP 409, message baseline <name> is in use by lease <id>; BASELINE_SAVE_FAILED { name, leaseId }, exit 1, HTTP 500, message baseline <name> was not saved: <driver message>. Lease <id> has ended. A physical lease is BAD_REQUEST with 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 501 UNSUPPORTED_IN_GATEWAY_MODE; save declares 404 UNKNOWN_LEASE, 500 BASELINE_SAVE_FAILED; remove 404 UNKNOWN_BASELINE, 409 BASELINE_IN_USE. The name path value goes through baselineNameSchema in the dispatcher. baselines joins CORE_ROUTE_SEGMENTS.
  • Events, with entries in docs/internal/EVENTS.md and events.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.deleted gains initiator baseline-save (additive).
  • state.db: owner baselines, version 1, table baselines (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. Owner registry goes to version 2: baseline_name TEXT, baseline_version INTEGER on devices (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 reclaiming state are committed first, so startup recovers the device as an interrupted reclaim (today's path). The driver's source row left making by the earlier process is destroyed by the driver at start (R2). A ready baseline source that no baselines row names is kept, reported by doctor as an orphan source with its size, and destroyed only by doctor --purge-orphans (decided in delivery, confirmed by the maintainer 2026-11-04). No baselines row exists before the source is ready, so a restart never leaves a baseline that points at half a copy.
  • Stale check: checkStale() reads each baseline's source from listSources() and stores its stale reason, or clears it when the runtime or image matches again. It runs at start, after component.removed, and before answering baseline.list and doctor.run. baseline.stale fires 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 before saveSource touches 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 remove asks or needs --yes; save names the lease it ends.
  • Safety rule 6 (docs/internal/agent-rules/safety.md:86-87), "Every destructive action is attributable": baseline.saved and baseline.removed carry requesterId.
  • 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 baselines keeps 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 clone into the sources set, the device's disabled.plist copied, row ready, the device deleted); Android (shell sync, reboot -p, copyTree, one cold boot with -no-snapshot-load saving simlock_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 by adb 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.removed replaced); two saves of one name at once (versions 1 and 2); names Checkout, -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); saveSource fails (BASELINE_SAVE_FAILED, lease ended, device quarantined, no row); restart (a making source of an earlier process destroyed at start; a ready baseline source no row names kept and reported by doctor, deleted by doctor --purge-orphans); HTTP POST /v1/baselines (body dispatched as baseline.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 --json answer); no size (-); stale (the stale: line, from a source whose runtime is gone; cleared when it is back); doctor (the sources entry of kind baseline carries baselineName and baselineVersion, findings empty); HTTP GET /v1/baselines with 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_USE naming the lease, from a registry row leased); unknown (UNKNOWN_BASELINE); no terminal and no --yes (USAGE); HTTP DELETE /v1/baselines/{name} (path name dispatched as baseline.remove; Checkout is 400).
  • Saving, removing and a baseline going stale each record one event. Cases: saved (baseline.saved with the spec, size, lease id and requester); removed by operator (reason: operator); removed by nuke (nuke --delete-devices removes every baseline, reason: nuke, removedBaselines in the report; plain nuke keeps them); removed as replaced (reason: replaced); stale (one baseline.stale after component.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.ts passes.
  • node .agents/scripts/protocol-bump-check.mjs passes and node .agents/scripts/docs-surface-check.mjs prints no unmatched surface.
  • pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs passes and the HTTP reference lists the three /v1/baselines routes.
  • On a Mac with an iOS runtime: e2e/slow-baseline.test.ts leases an iPhone, writes a file into its data folder, runs simlock baseline save, and finds the lease ended, simlock baseline list showing version 1 with a size above 0, the source listed only in the sources set (not by simlock simctl list), and the file inside the source's data folder.
  • On a Mac with the Android emulator: e2e/slow-baseline.test.ts leases an emulator, writes a setting with adb shell settings put, saves it, and finds the lease ended, the list showing version 1, and a snapshots/simlock_boot folder 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

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. 32 remaining items

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

Metadata

Metadata

Assignees

Labels

task:readySpec checked. An agent may implement it once its Depends on allow.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions