Repository navigation
Description
Part of #327.
Scope
After this PR an agent can name a baseline when it asks for a lease, from the CLI (--baseline, SIMLOCK_BASELINE), the HTTP API, MCP and the client, and gets a new copy of that baseline: the operator's apps, files and settings are on the device when the grant arrives. A request naming a baseline that does not exist, does not match the request or is stale fails at once. A device made from a baseline only ever serves a request for that baseline at its current version, and a plain request never gets one. Replacing a baseline leaves running leases alone, deletes idle copies of the old version, and gives the next lease the new version, also a request that was already waiting. The warm pool keeps copies of baselines it saw leased. simlock status and simlock list --devices show which baseline and version a device came from.
#1206 delivers saving, listing and removing baselines; #1204 and #1205 make every virtual device a copy that serves one lease. This task joins the two: the baseline becomes a pool key and a request field.
The task is wide (one request field and one device field on every surface: contract, leasing, core registry, warm pool, CLI, HTTP, MCP, events, website), so Modules touched lists more than 20 files, most of them one field each; it stays at 7 Tests lines. It does not split: a contract field with no leasing behind it, or leasing with no surface that sends the field, could not be tested from any invoker.
In short
A lease request may name a baseline. Simlock checks it against the baseline at once, then grants a device copied from the baseline's source (the shut-down device the operator saved). When the lease ends the copy is destroyed (#1204), so the next lease naming the baseline gets a new copy with none of the previous lease's changes.
A request naming baseline checkout takes the baseline's platform, model, OS, mode and image tag. Anything it names itself must match the baseline, checked in that order; the first field that differs is named in BASELINE_MISMATCH.
flowchart LR
R[lease.request<br/>baseline: checkout] --> B{{"resolve the baseline<br/>(new: unknown, mismatch, stale fail here)"}}
B --> P{{"planner: idle device of<br/>checkout at its current version?<br/>(changed: the baseline is a pool key)"}}
P -->|yes| G[grant]
P -->|no| C{{"provision: copy checkout's source<br/>(changed: names the source)"}}
C --> G
G --> E{{"grant and lease.granted carry<br/>baseline name and version (changed)"}}
A user's session (the CLI prints the grant and errors as one JSON line, F25):
Before:
$ simlock lease --platform android --baseline checkout
{"error":{"code":"USAGE","message":"Unknown option '--baseline'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- \"--baseline\""}}
$ echo $?
2
After, with baseline checkout version 1 saved from a full Pixel 9 on Android 36 (#1206):
$ simlock lease --platform android --baseline checkout --detach
{"device":{"id":"<device id>","spec":{"physical":false,"platform":"android","model":"Pixel 9","osVersion":"36","baseline":{"name":"checkout","version":1}},…},"lease":{"id":"<lease id>",…},…}
$ SIMLOCK_BASELINE=checkout simlock lease --platform android --detach
(the same grant: a checkout copy)
$ simlock lease --platform android --baseline checkout --os 35
{"error":{"code":"BASELINE_MISMATCH","message":"baseline checkout is Android 36, the request asks for 35"}}
$ simlock lease --platform android --baseline chekout
{"error":{"code":"UNKNOWN_BASELINE","message":"no baseline named \"chekout\" on this worker"}}
$ simlock lease --platform ios --baseline login # baseline login saved on iOS 27.0, that runtime since removed
{"error":{"code":"BASELINE_STALE","message":"baseline login is stale: runtime <runtime id> is not installed"}}
$ simlock status
…
Device <device id>: leased, mode full, serves default mode: yes, baseline checkout v1
Messages, word for word (<name> is the baseline's name, <asked> the request's value as sent):
| Field that differs | BASELINE_MISMATCH message |
|---|---|
| platform | baseline <name> is <ios or android>, the request asks for <asked> |
| model | baseline <name> is <model>, the request asks for <asked> |
| OS | baseline <name> is <iOS or Android> <version>, the request asks for <asked> |
| mode | baseline <name> is <slim or full>, the request asks for <asked> |
| image tag | baseline <name> is image tag <tag, or none>, the request asks for <asked> |
Inputs, with checkout saved from a full Pixel 9 on Android 36 with no image tag:
| Request | Today | After |
|---|---|---|
--platform android |
plain device | plain device, never a checkout copy |
--platform android --baseline checkout |
USAGE, unknown option |
a checkout v1 copy |
--platform android --baseline checkout --device "pixel 9" |
USAGE |
a checkout copy (letter case and aliases as the catalog, F12) |
--platform android --baseline checkout --device "Pixel 8" |
USAGE |
BASELINE_MISMATCH: baseline checkout is Pixel 9, the request asks for Pixel 8 |
--platform android --baseline checkout --image-tag google_apis |
USAGE |
BASELINE_MISMATCH: baseline checkout is image tag none, the request asks for google_apis |
--platform android --baseline checkout --os ">=35" |
USAGE |
a checkout copy (36 satisfies the range, as satisfiesOs, F45) |
--platform android --baseline checkout --os 35 |
USAGE |
BASELINE_MISMATCH, at once |
--platform android --baseline checkout --mode slim |
USAGE |
BASELINE_MISMATCH, at once |
--platform ios --baseline checkout |
USAGE |
BASELINE_MISMATCH naming the platform, at once |
--platform android --baseline checkout --class tablet |
USAGE |
BAD_REQUEST: a request names a baseline or a class, not both: send only one of \baseline` and `class`` |
--platform android --baseline checkout --physical |
USAGE |
BAD_REQUEST: `baseline` has no meaning for a physical device |
--platform android --baseline nothere |
USAGE |
UNKNOWN_BASELINE, at once |
--platform android --baseline checkout, Android 36 image removed |
USAGE |
BASELINE_STALE with #1205's Android reason, at once |
--platform android --baseline checkout waiting for capacity while the operator saves checkout v2 |
USAGE |
a checkout v2 copy |
SIMLOCK_BASELINE=checkout, --baseline other |
env var has no effect | other is sent (the flag wins) |
SIMLOCK_BASELINE= (empty), no flag |
no effect | no baseline sent |
--baseline "" |
USAGE |
BAD_REQUEST from #1206's name rule (at least 1 character) |
If this task goes wrong, a user notices a lease naming a baseline that comes up without the operator's app, or a plain lease that comes up with someone's signed-in test account.
Technical spec
Facts
Commit 019ba5c.
| # | Fact | Source |
|---|---|---|
| F1 | lease.request's input is a strict object with no baseline field: platform, model, class, osVersion, mode, imageTag, physical and the request options. |
src/contract/operations.ts:148-175 |
| F2 | A physical request naming mode, imageTag or allowDownload: true is refused, one issue per field, with the message `<field>` has no meaning for a physical device; a request naming both a model and a class is refused with a request names a model or a class, not both: send only one of `model` and `class`. |
src/contract/operations.ts:177-191, src/contract/operations.ts:194-221 |
| F3 | requestedDevice turns the input into the DeviceRequest the daemon queues; the daemon dispatcher calls it, and so do the gateway's dispatcher and its dispatch to a worker. |
src/contract/operations.ts:288-298, src/daemon/dispatcher.ts:466, src/gateway/dispatcher.ts:692, src/gateway/fleet-coordinator.ts:1072 |
| F4 | A device's spec on the wire (deviceSpecSchema: physical, platform, model, osVersion, imageTag) is the spec of a device record, a status device and a granted device. |
src/contract/schemas.ts:92-98, src/contract/schemas.ts:183, src/contract/schemas.ts:217, src/contract/schemas.ts:248 |
| F5 | A stored request and a waiting request carry requestedDeviceSchema (platform, model, class, osVersion, mode, imageTag, physical). |
src/contract/schemas.ts:310-318, src/contract/schemas.ts:326, src/contract/schemas.ts:371 |
| F6 | VirtualSpec holds platform, model, osVersion, mode and imageTag; sameSpec is equal on physical, platform, model, OS, mode and image tag. |
src/core/domain.ts:28-48, src/core/domain.ts:92-101 |
| F7 | DeviceRequirement holds platform, target, OS and image tag; fits refuses a physical spec, then compares platform and image tag, then the target and the OS; exactRequirement builds one from a spec. |
src/core/domain.ts:122-130, src/core/domain.ts:146-153, src/core/domain.ts:166-180 |
| F8 | The planner grants or boots an idle device only when mayBeGranted, the pool mode is equal and fits holds. |
src/leasing/acquisition-planner.ts:119-124 |
| F9 | The warm pool keys its kinds, ready devices and retries by sameSpec, and matches waiting demand by fits. |
src/core/warm-pool/policy.ts:186, src/core/warm-pool/policy.ts:258, src/core/warm-pool/policy.ts:491, src/core/warm-pool/converger.ts:193, src/core/warm-pool/retry.ts:59 |
| F10 | lease.requested is emitted when the request is admitted; the spec is resolved once, afterwards, and stored on the waiter (waiter.spec, waiter.requirement) for every later decision; a throw while resolving rejects the request with reason unresolvable-spec (how UNKNOWN_MODEL fails today). |
src/leasing/lease-acquisition-coordinator.ts:289-299, src/leasing/lease-acquisition-coordinator.ts:310, src/leasing/lease-acquisition-coordinator.ts:485-495, src/leasing/lease-acquisition-coordinator.ts:594 |
| F11 | #resolveSpec applies the worker's default mode to a request with none, settles a class or range against the catalog, resolves through the driver (installing when allowed) and holds the image tag to the request's. |
src/leasing/lease-acquisition-coordinator.ts:501-529, src/leasing/lease-acquisition-coordinator.ts:1463-1471 |
| F12 | A model name matches a catalog model ignoring letter case, or by one of its aliases. | src/core/catalog-match.ts:14-21 |
| F13 | The provisioner takes a component claim inside the decision gate, then calls driver.provision(spec) outside it, and registers the device with that spec in a second gate section. |
src/core/device-provisioner.ts:58-80, src/core/device-provisioner.ts:89-95 |
| F14 | Driver.provision takes only the spec today; the iOS, Android and fake drivers implement it. |
src/core/driver.ts:263, src/drivers/ios/index.ts:751, src/drivers/android/index.ts:1051, src/core/fake-driver.ts:404 |
| F15 | A provision that fails is retried once; the second failure rejects the request with PROVISION_FAILED. |
src/leasing/lease-acquisition-coordinator.ts:931-944, src/leasing/create-leasing.test.ts:5002 |
| F16 | The registry owner is at version 1 (#1206 raises it to 2 with devices.baseline_name, devices.baseline_version); devices and lease_requests have an image_tag column and no baseline column. |
src/core/registry-schema.ts:3-35, src/core/registry-schema.ts:56-75, src/core/registry-schema.ts:118-122 |
| F17 | The registry writes a virtual spec's mode and tag through specColumns, reads them back into spec, and writes and reads a stored request's fields column by column. |
src/core/registry-rows.ts:236-239, src/core/registry-rows.ts:485-499, src/core/registry-rows.ts:320-345, src/core/registry-rows.ts:598-608 |
| F18 | A state owner migrates by appending a step to migrations and raising version; the token store's second step is an ALTER TABLE … ADD COLUMN. Steps run in one transaction at open. |
src/auth/token-store.ts:22-30, src/state/AGENTS.md:21 |
| F19 | A repeat of a request under the same idempotency key is the same request only when every device field is equal. | src/leasing/lease-request-book.ts:411-422 |
| F20 | lease.granted carries lease id, device id, requester, request id, source, fleet request id and platform; LeaseLifecycle.grant emits it from the registry's device record and returns that record as the grant's device. |
src/bus/index.ts:23-32, src/leasing/lease-lifecycle.ts:93-116 |
| F21 | device.provisioned carries the spec. |
src/bus/index.ts:98-103 |
| F22 | The warm pool owner is at version 1; warm_kinds is unique on platform, model, OS, mode and image tag, every column NOT NULL, and warm_kind_leases.kind_id references warm_kinds (id); a learned kind is read back into a VirtualSpec. |
src/core/warm-pool/learned.ts:6-30, src/core/warm-pool/learned.ts:52-89, src/core/warm-pool/learned.ts:222-231 |
| F23 | The converger learns a kind from lease.granted, taking the granted device's spec. |
src/core/warm-pool/converger.ts:202-214 |
| F24 | CatalogCheck.gone answers the learned kinds whose platform has no driver or that the catalog no longer lists. |
src/core/warm-pool/catalog-check.ts:39-47, src/core/warm-pool/catalog-check.ts:93-100 |
| F25 | simlock lease has no --baseline option, maps --image-tag to imageTag, and prints the grant as one JSON line; a CLI error is one JSON line {"error":{"code","message"}}. |
src/cli/commands/lease.ts:43-61, src/cli/commands/lease.ts:174-189, src/cli/args.ts:30-32, src/cli/errors.ts:42 |
| F26 | The CLI environment reads SIMLOCK_URL and SIMLOCK_TOKEN from the process environment into named fields. |
src/cli/environment.ts:441-442, src/cli/types.ts:105 |
| F27 | Today's CLI refuses the flag. | this machine, 2026-11-02: node dist/cli/main.js lease --platform android --baseline checkout → {"error":{"code":"USAGE","message":"Unknown option '--baseline'. …"}}, exit 2 |
| F28 | simlock status prints Device <id>: <state>, mode <mode>, serves default mode: <yes or no> per device; simlock list --devices prints the device records as JSON. |
src/cli/format.ts:266-278, src/cli/format.ts:305-308, src/cli/commands/list.ts:39-40 |
| F29 | HTTP: the lease body schema is strict and has imageTag; the route copies each field into the dispatch input; the lease payload has imageTag from the device spec. |
src/http/lease-declarations.ts:196-215, src/http/app.ts:181-191, src/http/tracker.ts:87-95, src/http/tracker.ts:26-48, src/http/tracker.ts:62-85, src/http/lease-declarations.ts:17-34 |
| F30 | MCP's lease tool input is leaseRequestFields without fleetRequestId, requesterId and requires; its output is lease.request's output; its description lists the fields in prose. |
src/mcp/contracts.ts:40-44, src/mcp/contracts.ts:53, src/mcp/server.ts:209 |
| F31 | The client's requestLease input type is the contract's lease.request input. |
src/simlock-client/types.ts:22 |
| F32 | BAD_REQUEST is exit 2, HTTP 400; RUNTIME_MISSING and UNKNOWN_MODEL are exit 12, HTTP 422; classifyError maps a core error class to its code. |
src/contract/errors.ts:256, src/contract/errors.ts:322-323, src/daemon/error-code.ts:139-141 |
| F33 | A device that ended its one fresh lease is never granted again (mayBeGranted); #1204 makes every virtual device take this path. |
src/core/domain.ts:285-293 |
| F34 | Every path that deletes a device record publishes device.deleted after the commit: ManagedDeviceLifecycle.destroy, the spent path, and the registry's own deletes that quarantine and doctor use. |
src/core/managed-device-lifecycle.ts:124-142, src/core/reclaim-coordinator.ts:302-313, src/core/registry.ts:428-433, src/core/registry.ts:517-522 |
| F35 | The warm pool's status target has platform, model, OS, mode and image tag; simlock status prints them joined by /. |
src/contract/schemas.ts:496-506, src/core/warm-pool/figures.ts:6, src/cli/format.ts:312-321 |
| F36 | A simctl clone carries the source's files and preferences into the copy. |
spike on this machine, 2026-11-02: simctl --set <s> clone <src> c1 → a file written in the source's data/ and a defaults write value are present in the clone |
| F37 | An Android copy under the same AVD name in its own AVD home keeps the prepared state and loads the source's snapshot. | spike on this machine, 2026-11-02: ANDROID_AVD_HOME=<base>/d1, cp -c -p -R <src home>/simlock.avd <base>/d1/simlock.avd → "INFO | Successfully loaded snapshot 'simlock_boot' using 2213 ms" |
| F38 | The website says a device is wiped at every lease end and describes lease.identity as reuse or replace. |
website/src/content/docs/docs/using-devices/working-with-a-device.mdx:111, website/src/content/docs/docs/introduction/how-it-works.mdx:32, website/src/content/docs/docs/using-devices/lease-lifecycle.mdx:90, website/src/content/docs/docs/worker/capacity.mdx:234-242 |
| F39 | The website documents --image-tag in the CLI reference, Choosing a device, the error tables and the client page. |
website/src/content/docs/docs/reference/cli.mdx:96-113, website/src/content/docs/docs/using-devices/choosing-a-device.mdx:92-102, website/src/content/docs/docs/reference/errors.mdx:48-52, website/src/content/docs/docs/using-devices/programmatic-client.mdx:113 |
| F40 | EVENTS.md describes lease.granted's payload in one row. |
docs/internal/EVENTS.md:51 |
| F41 | A provisioned or booted device is granted inside the decision gate (#grantHandoff); a grant that fails re-queues the waiter as waiting-for-device. |
src/leasing/lease-acquisition-coordinator.ts:1244-1270 |
| F42 | A waiting request's line in simlock list and in the inbox names platform, model or class, OS, mode and image tag, and no other field. |
src/cli/commands/list.ts:105-122, src/contract/inbox.ts:49-60 |
| F43 | warm.forget answers each forgotten kind's platform, model, OS, mode and image tag, and the CLI prints them as Forgot <platform> <model> <os> (<mode>, <tag>). |
src/daemon/dispatcher.ts:833-845, src/cli/commands/warm.ts:65-77 |
| F44 | POST /v1/leases declares its error codes by status; 422 lists only UNKNOWN_MODEL. |
src/http/lease-declarations.ts:237-241 |
| F45 | fits compares the OS with satisfiesOs, which takes an exact version or a range. |
src/core/domain.ts:177, src/core/domain.ts:194 |
Modules touched
Searches: imageTag in src/**/*.ts outside tests (33 files), image_tag (3), sameSpec( (5), fits( (6), requestedDevice( (5), "lease.granted" (6), each file read for whether a baseline field changes it. Files under src/agent-device/ match imageTag and stay out (#1203).
src/contract/operations.ts:baselineonleaseRequestBaseSchema(An operator saves, lists and removes baselines on a worker #1206's name schema);refusePhysicalWithImageFieldsrefuses it; a new refinement refusesbaselinewithclass;requestedDevicecarries it.src/contract/schemas.ts:baseline(name) onrequestedDeviceSchema;baseline({name, version}) ondeviceSpecSchema;baseline(name) onwarmPoolTargetSchemaand on awarm.forgetanswer's kind.src/contract/errors.ts:BASELINE_MISMATCH,BASELINE_STALErows and details.src/contract/inbox.ts:describeRequestedDevicenamesbaseline <name>, and noclass undefinedfor a request with neither model nor class (F42).src/contract/protocol.ts: the protocol bump.src/core/domain.ts: the device's baseline is ONE field, An operator saves, lists and removes baselines on a worker #1206'sbaseline{name, version} on a virtual spec, read fromdevices.baseline_nameanddevices.baseline_version; this task adds no second field. It addsDeviceRequirement.baseline({name, version}), compares the spec's baseline insameSpec,fitsandexactRequirementlike the image tag (ADR 0061 §5), and adds the purebaselineMismatch(baseline, request, catalogEntry)(the catalog entry of the baseline's model, which holds its aliases; the gateway passes the holder's catalog from its view) (R12: fields in the order platform, model, OS, mode, image tag; model by the catalog's case and alias rule, F12; OS bysatisfiesOs, F45), exported for A gateway routes a baseline request to a worker that holds it #1208's gateway.src/core/driver.ts:BaselineMismatchError,BaselineStaleErrorbesideUnknownModelError(provision(spec, { source })is iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204's).src/core/device-provisioner.ts: in the gate section that takes the component claim (F13), reads the current version of the spec's baseline and its source, sets the spec's version to it, and holds that version until the record is registered; passes the source toprovision; registration writes An operator saves, lists and removes baselines on a worker #1206's two columns.src/core/registry-schema.ts,src/core/registry-rows.ts: registry migration to version 3 (R9) addinglease_requests.baseline TEXT;specColumnswrites and reads An operator saves, lists and removes baselines on a worker #1206'sdevices.baseline_name,devices.baseline_version.src/core/baselines.ts(An operator saves, lists and removes baselines on a worker #1206's):current(name); holds on a version for provisions in flight; on a save of a new version, inside the decision gate and with device claims, destroys every idle (unleased, unclaimed) device of an older version (R10); drops an older version (row anddestroySource,baseline.removedreasonreplaced) only when no device record of it is left and no provision holds it, checked on everydevice.deleted(F34) and at startup. This replaces An operator saves, lists and removes baselines on a worker #1206's drop at once on replace.src/core/fake-driver.tsande2e/fake-driver/fake-driver.ts: no change; iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204'sprovision {source}and An operator saves, lists and removes baselines on a worker #1206's files map already make a copy carry its source's files (R15).src/drivers/ios/index.ts,src/drivers/android/index.ts: no change; iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204 and Android: every emulator is a copy of a seed in its own folder, booted from its boot snapshot #1205 copy a givensource.src/core/warm-pool/learned.ts: warm pool migration to version 2 (R9): rebuildswarm_kindswithbaseline TEXT NOT NULL DEFAULT ''in the unique key, keeping each row'sidsowarm_kind_leasesstays valid (F22);forgetanswers the baseline;src/core/warm-pool/catalog-check.ts: drops a kind whose baseline is removed or stale;src/core/warm-pool/converger.ts,src/core/warm-pool/figures.ts: a kind's spec takes the baseline's current version at each pass; targets show the baseline.src/leasing/lease-acquisition-coordinator.ts: at admit, checks a request naming a baseline (unknown, mismatch, stale, in that order, R12) and fails it at once; at every decision, sets the waiter's requirement to the baseline's current version (R10); at grant (in the gate, F41), a device whose version is no longer current is not granted: it is destroyed and the waiter decides again.src/leasing/lease-request-book.ts:sameDeviceRequest;src/leasing/lease-lifecycle.ts:lease.grantedgainsbaseline.src/bus/index.ts:lease.grantedpayload type.src/daemon/error-code.ts: two new classifications;src/daemon/dispatcher.ts:warm.forgetanswers the baseline.src/cli/commands/lease.ts,src/cli/environment.ts,src/cli/types.ts:--baseline,SIMLOCK_BASELINE;src/cli/format.ts: the status device line and warm target;src/cli/commands/list.ts: a waiting request's line namesbaseline <name>(F42);src/cli/commands/warm.ts:Forgot …names the baseline (F43).src/http/lease-declarations.ts,src/http/app.ts,src/http/tracker.ts: body field, dispatch input, lease payloadbaseline; the lease routes declareBASELINE_MISMATCHandBASELINE_STALEunder 422 andUNKNOWN_BASELINEunder 404 (F44).src/mcp/server.ts: the tool description (the input follows the contract, F30).src/gateway/routing/request-match.ts: the requirement it builds names no baseline (compile only; routing by baseline is A gateway routes a baseline request to a worker that holds it #1208).e2e/slow-baseline.test.ts(An operator saves, lists and removes baselines on a worker #1206's): one iOS and one Android lease-from-baseline case.- Docs:
docs/internal/EVENTS.md,src/core/AGENTS.md,src/leasing/AGENTS.md,src/core/warm-pool/AGENTS.md; website pages listed under Done when.
flowchart LR
CLI[cli lease*] --> D[daemon dispatcher]
HTTP[http lease routes*] --> D
MCP[mcp lease tool*] --> D
D --> K[contract lease.request*]
D --> L[leasing coordinator*]
L --> BL[core baselines store, T3*]
L --> PL[acquisition planner]
PL --> DOM[core domain fits / sameSpec*]
L --> PR[core device provisioner*]
PR --> BL
PR --> DRV[ios / android driver provision]
PR --> REG[core registry V3*]
L --> LL[lease lifecycle: lease.granted*]
WP[warm pool learned V2 / catalog check*] --> BL
WP --> PR
BUS[bus device.deleted] --> BL
sequenceDiagram
participant A as simlock lease
participant D as daemon dispatcher
participant L as leasing coordinator
participant B as baselines store (T3)
participant P as provisioner
participant V as driver
A->>D: lease.request {platform, baseline: checkout}
D->>L: request (lease.requested emitted)
L->>B: current("checkout") at admit
alt unknown, mismatch or stale
B-->>L: none / v1 differs / v1 stale
L-->>A: UNKNOWN_BASELINE / BASELINE_MISMATCH / BASELINE_STALE
else matches
B-->>L: v1 (android, Pixel 9, 36, full)
L->>B: current version, at every decision (in the gate)
L->>P: provision(spec with baseline checkout)
P->>B: current version and its source, held (in the gate)
P->>V: provision(spec, {source})
V-->>P: new copy
P-->>L: ready device (record has checkout v1, hold released)
L->>B: still current? (grant, in the gate)
alt a save made v2 meanwhile
L->>L: destroy the v1 copy, decide again
else current
L-->>A: grant, device.spec.baseline = {checkout, 1}
end
end
Contract and event changes
This PR bumps the protocol by one.
lease.requestinput:baseline, optional, An operator saves, lists and removes baselines on a worker #1206's baseline name rule (1–64 characters ofa-z,0-9,.,_,-, starting with a letter or digit); anything else isBAD_REQUESTwith An operator saves, lists and removes baselines on a worker #1206's message. Withphysical: trueit isBAD_REQUEST,`baseline` has no meaning for a physical device. Withclassit isBAD_REQUEST,a request names a baseline or a class, not both: send only one of `baseline` and `class`. The HTTP body (POST /v1/leasesand the lease-request route) takes the samebaseline; MCP and the client take it through the contract (F30, F31).- Device spec (
deviceSpecSchema, so a device record, a status device, a granted device and an HTTP lease payload):baseline: { name, version }on a device copied from a baseline; absent on any other.versionis an integer from 1. - Stored and waiting request spec (
requestedDeviceSchema):baseline(the name) when the request named one. - Warm pool status target and each kind in a
warm.forgetanswer:baseline(the name) on a learned baseline kind. - New error codes:
BASELINE_MISMATCH(exit 2, HTTP 422, details{ baseline, field },fieldone ofplatform,model,osVersion,mode,imageTag) andBASELINE_STALE(exit 12, HTTP 422, details{ baseline, reason }). Messages as In short. The HTTP lease routes declare them under 422 and An operator saves, lists and removes baselines on a worker #1206'sUNKNOWN_BASELINEunder 404, the one status that code has (F44). - Events, each in
docs/internal/EVENTS.mdand the website's events page, all additive (events rule 6):lease.grantedgainsbaseline: { name, version }when the device has one;lease.requested,lease.rejectedandlease.declinedcarryrequestSpec.baselinewhen the request named one;device.provisioned'sspeccarriesbaselinewhen the device has one.
Other code on the same state
Searches: the devices rows' spec columns (specColumns, image_tag: 3 files), every reader of a device spec's identity (sameSpec( 5 files, fits( 6 files, mayBeGranted 3 files), the warm_kinds table (1 file), the baselines table (#1206).
| Component | Acts on | Both at once, or in either order |
|---|---|---|
| Acquisition planner (F8) | idle devices by fits |
Reads the requirement this task builds; a plain requirement carries no baseline, so it never fits a baseline device, and a baseline requirement carries the version current at that decision, read in the same gate a save runs in, so an older version never fits. |
| Warm pool policy and converger (F9) | kinds and ready devices by sameSpec |
A baseline kind and a plain kind of the same model are two kinds; a ready device of an older version matches no kind and is not counted as ready for one. |
#notifyReclaimWait (src/leasing/lease-acquisition-coordinator.ts:1229) |
reclaiming devices by sameSpec |
Compares the baseline too; nothing else changes. |
| Every path that deletes a device: #1204's release path (F33), quarantine, doctor, nuke (F34) | device records, then device.deleted |
Each destroys a baseline copy like any other; the drop check listens to device.deleted, so it runs after the commit on every path and a version is dropped only after its last record is gone. |
#1206's baseline.save replacing a version |
the baselines rows and the old source |
This task adds the device side (R10): in the decision gate, with device claims, the save destroys the old version's idle devices and leaves leased and claimed ones; the old source is dropped by the drop check once no record and no provision hold that version. A provision that read v1 before the save holds v1 until its record is registered, then fails the grant check and is destroyed, so the save never deletes a source a copy is reading. A request waiting during the save gets v2 at its next decision. |
#1206's baseline.remove |
the source and idle copies | Reads the devices' baseline field this task writes to find copies and refuse one in use (BASELINE_IN_USE). A remove while a copy of that baseline is being made: the copy fails, and the request ends as any failed provision (F15). |
| #1206's stale marking | baselines stale reason |
The coordinator reads the stale reason at resolve time; a baseline marked stale after the resolve fails in the copy, as any failed provision (F15). |
| Gateway (F3) | requestedDevice |
Forwards baseline to the worker it chooses from this task on; routing by baseline is #1208. |
Warm pool forget (src/core/warm-pool/learned.ts:113-126) |
warm_kinds rows of a model |
Forgets baseline kinds of the model too, as it forgets every kind of the model today; its answer names each one's baseline (F43). |
| #1143 (open, ADR 0056) | the warm pool owner's version | Also raises the warm pool version; whichever merges second renumbers its step (R9). |
Failure modes
| Call | Outcome | What happens | Limit, counted from |
|---|---|---|---|
| Coordinator → baselines store, current version by name | ok | the request becomes an exact request for the baseline's spec, plus baseline {name, version}; no download is ever attempted |
in-process read, no wait |
| Coordinator → baselines store | absent (no such name) | rejected UNKNOWN_BASELINE, reason unresolvable-spec |
none |
| Coordinator → baselines store | a requested field differs | rejected BASELINE_MISMATCH naming the first differing field |
none |
| Coordinator → baselines store | stale reason set | rejected BASELINE_STALE with the reason |
none |
| Coordinator → baselines store | throws (database error) | rejected with the error as today's resolve errors are (F10) | none |
| Provisioner → baselines store, source of (name, version) in the gate | absent (removed since the resolve) | rejected UNKNOWN_BASELINE; nothing is copied |
none |
Provisioner → driver.provision(spec, {source}) |
ok | device registered with the baseline name and version | the driver's own provision bound, from the call |
Provisioner → driver.provision(spec, {source}) |
throws (copy failed, source gone) | retried once, then PROVISION_FAILED (F15) |
as today |
Baselines drop check on device.deleted → driver.destroySource |
throws | logged; the row of the old version is kept; the next device.deleted or the next start tries again |
none |
| Grant → baselines store, device's version still current | no (a save made a new version) | the device is destroyed, the waiter decides again and gets the new version | none |
| Save → destroy an idle old-version device | throws | the device stays shutdown with its old version, which is kept until that device is gone; the save still succeeds (decided in delivery, confirmed by the maintainer 2026-11-04) |
none |
State this task writes:
- Device record
baseline_name,baseline_version: written in the registration commit with the rest of the record (F13); a restart in the middle leaves either no record or a whole one. Two requests at once each register their own device. lease_requests.baseline: written with the request in its admit commit.warm_kinds.baseline: written inlearn's transaction (F22);''for a plain kind.- A replaced version kept after its last device was destroyed because the daemon stopped in between: dropped at the next start, after the startup step that deletes spent devices (
src/core/AGENTS.md:102). No separate test: the start calls the same drop function the replace test drives. - Migrations (registry 2 to 3, warm pool 1 to 2) run in the one open transaction (F18); a throw refuses the start and leaves
state.dbas it was.
Rules in play
- ADR 0061 §5: "The baseline is a pool key …
fitsandsameSpeccompare it like the image tag" — done indomain.ts, with the version in the key so "a device of an older version … is never granted". - ADR 0061 §4: "the old source is destroyed once no device made from it remains" — the drop check on every
device.deletedand at startup. - ADR 0061 §1: "
provision(spec, { source? })copies the named source" — the provisioner passes the baseline's source; ADR 0061 §1's amendment of safety rule 1 lets the driver destroy its own source when a version is dropped. - ADR 0015 §6 and ADR 0007 §6, as narrowed by ADR 0061: the baseline is one more pool-identity key beside mode and image tag.
- ADR 0038 §5, as narrowed: "a learned kind carries the baseline" —
warm_kinds.baseline. src/contract/AGENTS.md"Protocol version": "Every change to a contract shape bumps it by one in the same PR" — bumped once.- Events rule 6 (
docs/internal/agent-rules/events.md:22-25): "additive changes only" — every event change adds an optional field. Events rule 3: "published after the state change … is committed" —lease.grantedreads the committed record. - Architecture rule 1 (
docs/internal/agent-rules/architecture.md:6): "The core is platform-agnostic" — the core passes an opaque source id; only drivers copy. - Architecture rule 10 (
docs/internal/agent-rules/architecture.md:46): "A rule is enforced in exactly one place" — the mismatch rule lives only inbaselineMismatchindomain.ts(R12); the coordinator and A gateway routes a baseline request to a worker that holds it #1208's gateway call it; the CLI, HTTP and MCP only carry the field. - Safety rule 2 (
docs/internal/agent-rules/safety.md:54): "Never touch a leased device" — a replace destroys only idle, unclaimed old-version devices. src/state/AGENTS.md:21and:27: each owner migrates its own tables by version — registry and warm pool each add one step.- Documentation rule 9 (
docs/internal/agent-rules/documentation.md:70): "A change to the public surface updates the website in the same change". - Testing rule 7 (
docs/internal/agent-rules/testing.md:98): "Prove each claim once, at the cheapest level" — surface lines extend the existingimageTagtests.
Tests
Seam: the daemon dispatcher with the fake driver and #1206's baselines, modelled on src/daemon/dispatcher.test.ts ("Dispatcher: image tags", line 2128); the CLI, HTTP and MCP cases extend src/cli/index.test.ts (the --image-tag flag table, line 6344), src/http/app.test.ts (line 738) and src/mcp/server.test.ts (line 375); the warm pool case src/core/warm-pool/learned.test.ts.
- An agent leases naming a baseline: it gets a copy of the baseline, and the grant and
lease.grantedcarry its name and version. Cases: platform and name; with matching model and OS (--device "pixel 9",--os ">=35"); CLI flag;SIMLOCK_BASELINE; HTTP; MCP. (The fake source's file is on the copy; the CLI flag beats the env var, and an empty env var sends nothing.) - A request naming a baseline that cannot serve it fails at once. Cases: unknown name (
UNKNOWN_BASELINE); different OS; different mode; different platform; different model; different image tag (eachBASELINE_MISMATCH, the In short message word for word); stale (BASELINE_STALE); with--physical; with--class(eachBAD_REQUEST, message word for word). No device is provisioned in any case. - Devices never cross pools: a plain request never gets a baseline device, a named one never gets a plain or other baseline's device, and a device of an older version is never granted. Cases: idle baseline device and plain request; idle plain device and named request; idle device of another baseline; idle device of an older version.
- A baseline lease is released: the next lease naming it sees none of the previous lease's changes. Cases: iOS; Android. (Fast lane: a new device id, copied from the source again; the file a lease wrote on its fake device is absent. Hardware:
e2e/slow-baseline.test.ts.) - An operator replaces a baseline: running leases keep their device, the next lease gets the new version, and the old version is deleted when its last device goes. Cases: lease running during replace; no lease running; request waiting during replace. (An idle v1 device is destroyed by the save; the waiting request is granted v2; a v1 copy finished after the save is not granted;
baseline.removedreasonreplacedis recorded when the old version goes, also when its last device leaves through quarantine.) - The warm pool learns a baseline kind from a lease and keeps a copy warm. Cases: baseline kind; plain kind beside it. (Two rows; the warm copy is of the current version; the status target in JSON and the
simlock statuswarm line name the baseline;warm forgetnames it.) simlock statusandsimlock list --devicesshow a device's baseline and version. Cases: baseline device; plain device. (A waiting request's line insimlock listand the inbox names the baseline.)
Done when
pnpm test:changedpasses with the seven Tests lines above.pnpm exec vitest run --project unit src/core/registry.test.ts src/core/warm-pool/learned.test.tspasses, including a reopen of astate.dbat registry version 2 and warm pool version 1 that migrates them to 3 and 2 and keeps each learned kind and its leases.- On a Mac with an iOS runtime: an operator leases an iPhone, writes a file into an app's container, saves it as a baseline (An operator saves, lists and removes baselines on a worker #1206); an agent leases naming it and finds the file, writes a second file, releases; the next lease naming it finds the first file and not the second.
scripts/slow-e2e.sh e2e/slow-baseline.test.ts -t ios. - On a Mac with an Android emulator: the same steps with a file under
/data/local/tmpand asettings putvalue.scripts/slow-e2e.sh e2e/slow-baseline.test.ts -t android. - The website says how to name a baseline and what each new error means:
reference/cli.mdx(--baseline,SIMLOCK_BASELINE),using-devices/choosing-a-device.mdx(a "Start from a baseline" section, including that copies share a saved signed-in account),using-devices/programmatic-client.mdx,using-devices/errors.mdxandreference/errors.mdx(BASELINE_MISMATCH,BASELINE_STALE),reference/events.mdx(lease.granted), andintroduction/how-it-works.mdxandusing-devices/lease-lifecycle.mdxsay a lease naming a baseline starts from it (the one-lease wording onworking-with-a-device.mdxandworker/capacity.mdxis iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204's).pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjspasses. docs/internal/EVENTS.mdrows forlease.granted,lease.requested,lease.rejected,lease.declinedanddevice.provisionedname the new field.
Out of scope
- Saving, listing and removing baselines, their events other than
lease.granted, and stale marking (An operator saves, lists and removes baselines on a worker #1206). - Routing a request naming a baseline on a gateway, and a worker view's baselines (A gateway routes a baseline request to a worker that holds it #1208).
- The console (Console: a Baselines page and a device's baseline #1209).
- agent-device naming a baseline (agent-device: allocate a device from a named baseline #1203).
- A configured (runtime) warm target naming a baseline (ADR 0056, Runtime warm-pool targets: warm.set and warm.list, kept in state.db #1143 to Console: Add device… from the catalog keeps one more warm #1146).
simlock warm forget --baseline: forgetting a model forgets its baseline kinds too.
Depends on
Written by an agent.
Activity
test: a request naming a baseline that cannot serve it fails at once (#…
feat(leasing): a request naming a baseline that cannot serve it fails…
test: devices never cross pools: a plain request never gets a baselin…
feat(core): a baseline is a pool key: sameSpec and fits compare its n…
test: a baseline lease is released: the next lease naming it sees non…
feat(contract): protocol 72 for the baseline field on lease.request a…
test: a baseline lease matches its model and OS by catalog rules (#1207)
test: the CLI sends --baseline, or SIMLOCK_BASELINE when the flag is …
feat(cli): lease --baseline and SIMLOCK_BASELINE name a baseline (#1207)
feat(http): the lease body takes baseline, the payload shows it, the …
6 remaining items
feat: the warm pool, status, list, registry v3 and docs carry the bas…
test(e2e): the slow baseline cases lease a copy and see the saved sta…
refactor: baselineMismatch, the provisioner's claim, the waiting-requ…
refactor(core): the provisioner's registration section is its own met…
fix(leasing): audit of the baseline lease: split two Fallow findings,…
test(leasing): prove the baseline copy's claim, hold and version, the…
fix(leasing): a repeat with another baseline is an idempotency confli…
docs: the device.deleted initiator baseline-replaced in both event ca…
test(daemon): the matching rule's order for mode against the OS and t…
test(http): the lease routes' tags and codes and the SSE event schema…
test(e2e): the Android baseline case writes and reads a file under /d…
test(daemon): an idle old copy that will not delete stays shut down w…
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)