Skip to content

A lease names a baseline and gets a copy of it #1207

Closed

Description

@V3RON

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)"}}
Loading

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: baseline on leaseRequestBaseSchema (An operator saves, lists and removes baselines on a worker #1206's name schema); refusePhysicalWithImageFields refuses it; a new refinement refuses baseline with class; requestedDevice carries it.
  • src/contract/schemas.ts: baseline (name) on requestedDeviceSchema; baseline ({name, version}) on deviceSpecSchema; baseline (name) on warmPoolTargetSchema and on a warm.forget answer's kind.
  • src/contract/errors.ts: BASELINE_MISMATCH, BASELINE_STALE rows and details.
  • src/contract/inbox.ts: describeRequestedDevice names baseline <name>, and no class undefined for 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's baseline {name, version} on a virtual spec, read from devices.baseline_name and devices.baseline_version; this task adds no second field. It adds DeviceRequirement.baseline ({name, version}), compares the spec's baseline in sameSpec, fits and exactRequirement like the image tag (ADR 0061 §5), and adds the pure baselineMismatch(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 by satisfiesOs, F45), exported for A gateway routes a baseline request to a worker that holds it #1208's gateway.
  • src/core/driver.ts: BaselineMismatchError, BaselineStaleError beside UnknownModelError (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 to provision; 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) adding lease_requests.baseline TEXT; specColumns writes and reads An operator saves, lists and removes baselines on a worker #1206's devices.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 and destroySource, baseline.removed reason replaced) only when no device record of it is left and no provision holds it, checked on every device.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.ts and e2e/fake-driver/fake-driver.ts: no change; iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204's provision {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 given source.
  • src/core/warm-pool/learned.ts: warm pool migration to version 2 (R9): rebuilds warm_kinds with baseline TEXT NOT NULL DEFAULT '' in the unique key, keeping each row's id so warm_kind_leases stays valid (F22); forget answers 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.granted gains baseline.
  • src/bus/index.ts: lease.granted payload type.
  • src/daemon/error-code.ts: two new classifications; src/daemon/dispatcher.ts: warm.forget answers 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 names baseline <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 payload baseline; the lease routes declare BASELINE_MISMATCH and BASELINE_STALE under 422 and UNKNOWN_BASELINE under 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
Loading
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
Loading

Contract and event changes

This PR bumps the protocol by one.

  • lease.request input: baseline, optional, An operator saves, lists and removes baselines on a worker #1206's baseline name rule (1–64 characters of a-z, 0-9, ., _, -, starting with a letter or digit); anything else is BAD_REQUEST with An operator saves, lists and removes baselines on a worker #1206's message. With physical: true it is BAD_REQUEST, `baseline` has no meaning for a physical device. With class it is BAD_REQUEST, a request names a baseline or a class, not both: send only one of `baseline` and `class`. The HTTP body (POST /v1/leases and the lease-request route) takes the same baseline; 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. version is 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.forget answer: baseline (the name) on a learned baseline kind.
  • New error codes: BASELINE_MISMATCH (exit 2, HTTP 422, details { baseline, field }, field one of platform, model, osVersion, mode, imageTag) and BASELINE_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's UNKNOWN_BASELINE under 404, the one status that code has (F44).
  • Events, each in docs/internal/EVENTS.md and the website's events page, all additive (events rule 6): lease.granted gains baseline: { name, version } when the device has one; lease.requested, lease.rejected and lease.declined carry requestSpec.baseline when the request named one; device.provisioned's spec carries baseline when 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 in learn'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.db as it was.

Rules in play

  • ADR 0061 §5: "The baseline is a pool key … fits and sameSpec compare it like the image tag" — done in domain.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.deleted and 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.granted reads 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 in baselineMismatch in domain.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:21 and :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 existing imageTag tests.

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.granted carry 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 (each BASELINE_MISMATCH, the In short message word for word); stale (BASELINE_STALE); with --physical; with --class (each BAD_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.removed reason replaced is 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 status warm line name the baseline; warm forget names it.)
  • simlock status and simlock list --devices show a device's baseline and version. Cases: baseline device; plain device. (A waiting request's line in simlock list and the inbox names the baseline.)

Done when

  • pnpm test:changed passes with the seven Tests lines above.
  • pnpm exec vitest run --project unit src/core/registry.test.ts src/core/warm-pool/learned.test.ts passes, including a reopen of a state.db at 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/tmp and a settings put value. 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.mdx and reference/errors.mdx (BASELINE_MISMATCH, BASELINE_STALE), reference/events.mdx (lease.granted), and introduction/how-it-works.mdx and using-devices/lease-lifecycle.mdx say a lease naming a baseline starts from it (the one-lease wording on working-with-a-device.mdx and worker/capacity.mdx is 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.mjs passes.
  • docs/internal/EVENTS.md rows for lease.granted, lease.requested, lease.rejected, lease.declined and device.provisioned name the new field.

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 2, 2026
  2. added
    task:readySpec checked. An agent may implement it once its Depends on allow.
    and removed
    task:draftScope written; technical spec or its spec check missing.
    on Nov 2, 2026
  3. self-assigned this
    on Nov 3, 2026
  4. 6 remaining items

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