Accepted
Decision history: 2026-10-21, a macos-app lease session takes its app device's claim instead of no claim, so exclusion against whole-Mac and same-app sessions also holds across daemons (ADR 0035, #3323).
- Allocate device leases lazily, when the device, backend, and provider are known.
- Run lease admission, heartbeat, stored session lease refresh, and request execution under the same daemon request lock.
- Do not mutate lease ownership before the lock. Scope resolution may happen before the lock.
- Generated connection profiles must strip daemon and Metro bearer tokens.
- A session cannot outlive its lease. Lease-end teardown clears the session's device claim even when the device no longer answers.
- Report each lease that a request ended once, at response level. A client never sends a release after such a request.
- Admitted work that is still wanted preserves its lease. If the client hung up, the request neither defers expiry past that cancellation nor renews the lease.
- Before admission, send lease heartbeats for as long as a client phase runs, for example an artifact upload. Renew under the window that the caller named, or else under the lease's existing window.
- Before a pending human-control activation reports active, it fences new mutations and drains the mutations already admitted.
- Only host administrators allocate
macos-appleases. Tenantlease_releaseis refused. - Confine each request admitted under a
macos-applease to the leased app. - A
macos-applease session binds its app device and takes that device's claim (ADR 0035).
Remote daemon users need a clear ownership boundary before commands reach a platform runner or helper. Shared proxies and hosted providers need ownership to include the selected device and connection provider, not only tenant/run.
Runner and helper processes already have backend-specific mutual exclusion. That guard protects platform tooling, not remote client ownership. Thus, direct exposure of those errors makes device contention harder to recover from.
A remote device lease is logical ownership of one selected device by one remote client for a connection provider such as proxy, cloud, or limrun.
connect establishes the connection profile and client identity.
Lease allocation is lazy.
It happens when a device, backend, and provider are known.
A runner/process lease is a backend helper guard. It is not a user/client ownership boundary. It stays below daemon device leases and should not be weakened or replaced by them.
open is the natural point to acquire a device lease because target resolution and session creation meet there.
Commands after open must refresh the lease.
After the default 60 seconds without activity, the device should become available again.
These operations must run under the same daemon request lock:
- Lease admission.
- Heartbeat.
- Stored session lease refresh.
- Request execution.
Scope resolution may happen before the lock. Lease ownership mutation must not happen before the lock.
Generated connection profiles are non-secret. They may persist routing and lease metadata, but must strip daemon and Metro bearer tokens. Tokens are supplied in memory for the current command or through environment/CLI token paths.
The proxy process is expected to be long-lived and self-serve. Recovery from a stale or expired device lease should not require a proxy restart.
A caller that owns the lifetime of a lease, and allocates and releases it itself, can allocate with retainOnClose.
Session close then leaves that lease and its provider device in place.
Only leases.release, expiry, or daemon shutdown ends it.
The default is unchanged, so the CLI's proxy sharing still frees devices on close.
The allocated lease reports retainOnClose: true only if the daemon honored it.
Only the lease's own client can turn it on for a lease that the run already holds.
An unexpired retainOnClose lease keeps an idle daemon alive.
Other leases, including human-control holds, do not.
If the caller stops heartbeats for a retained lease, that lease expires after its ttlMs.
Idle reap then shuts the daemon down within one more idle window.
A session cannot outlive the lease under which it was opened.
When the lease is released or expires, the daemon tears the session down under its execution locks and clears its device claim.
Any teardown of a leased session, including close, finishes an active recording. A finished export at a remote temp path then belongs to the lease's tenant as a downloadable artifact, like the artifact of any record stop (ADR 0024 2.5).
This applies even when the device no longer answers.
A release is a tenant lease_release or a host DELETE /admin/leases/<lease-id>.
The daemon sweeps for expired leases every second.
Thus, expiry does not wait for a later request.
In-flight work and human-control holds still keep a lease from expiring.
After daemon shutdown begins, no new lease-end teardown starts.
Shutdown waits for any lease-end teardown that already started before it tears sessions down itself.
A provider lease that ends with its daemon still holds a rented device on the provider side, and that device stays billed.
Thus, the daemon journals the live leases of each provider that can recover an expired lease, in live-provider-leases.json in its state directory.
A daemon that starts and finds this journal hands each lease in it to the expired-lease recovery of its provider, which ends the rented device.
The lease itself is not restored, and its controller connects again.
Restoring the live lease was rejected: the sessions and device claims of the dead daemon are gone, so a restored lease would name a device that no session can reach.
When a request closes a session, the daemon ends the lease of that session, unless the lease was allocated with retainOnClose.
The reply to that request reports each lease that it ended once, at response level, as endedLeases: [{ leaseId, outcome: 'released' }].
On success, the report is in data.
On failure, the report is in error.details, including for a close that failed after the release.
This applies to every request that can close a session:
close.- A
batchclose step. - The
closeof areplayortestscript. - The session cleanup that
testruns after each script.
Nested requests record on the ledger of the outermost request, so a step reply never repeats the report. If a close finds its lease already inactive, it reports that lease as ended. A client never sends a release after such a request. If a client stores the lease id, it forgets that id when the reply names it. A gateway that relays the reply reads the lease end from it.
Close and lease-end teardown take the same execution locks. Thus, whichever runs second finds the session gone. A close after a lease end has no session and ends no lease. If a client still stores that lease id, its next heartbeat finds the lease inactive. The client then allocates a new lease under a fresh id.
Device contention can fail before platform execution with an explicit device-lease error. That error includes the backend, provider, selected device key, and owning lease expiry.
Backend-only leases remain valid for older remote clients. Provider-aware clients get device-level contention and clearer recovery.
A lease renews when a request is admitted, and never again while that request runs. Thus, an admitted command slower than the inactivity TTL used to expire the lease that paid for its own device. The daemon then tore the session down while the client still waited for its result. Admitted work therefore preserves its lease in the same way as a human-control hold does. While the request is still wanted, it defers expiry. If the request finishes while it is still wanted, it renews the lease for its existing inactivity TTL from the moment the work ended. A request whose client hung up preserves nothing. It neither defers expiry past that cancellation nor renews the lease when the request finally finishes. Thus, a handler that ignores its cancellation cannot hold a rented device open.
The inactivity TTL that the client asked for determines which leases this preservation reaches. The daemon default is one minute. A cloud WebDriver connection profile asks for ten minutes. Thus, a single command that runs longer than its own lease is ordinary on the default. On the longer window, such a command is only reachable through a profile.
Allocation is admitted work too. The registry records a lease before a hosted provider creates the session behind it. Creation of that session can take longer than the inactivity TTL of the lease. Thus, a lease timed from its record was already expired, or nearly expired, when its client first received it. The paid session that the lease pointed at was orphaned. The allocation therefore holds a work pass while the provider allocates. The lease cannot expire during that allocation. If a successful allocation is still wanted by its requester, the inactivity TTL starts from the moment allocation completed. A requester that hung up preserves nothing, and its allocation is released as before.
The protection of admitted work covers nothing that happens before a request is admitted. An artifact install uploads the artifact from the caller before the request that will consume it is admitted. Thus, an upload slower than the inactivity window of the lease expired the lease that paid for the target device of the bytes (#2946). The caller therefore sends lease heartbeats over the ordinary transport for as long as that phase runs. Each heartbeat names the lease scope exactly as the command named it, and carries no payload of its own. An install names no window, so its heartbeats renew for the window that the lease already carries. A caller that did name a window continues to renew on that window.
A heartbeat used to resolve an absent window to the registry default instead. That resolution shortened, without notice, every lease allocated above that default. That was the other half of the reason that the upload could not survive. Request admission had its own copy of that mistake. It named a proxy-specific default for every admitted request. Thus, a lease allocated longer than the default lost its window on the next command. Admission also renews on the window of the lease. The window that a lease carries is the one that its client named when it allocated.
The first heartbeat is sent when the phase starts, not one cadence later. The reason is that a heartbeat proves that the lease on which the upload spends time is still alive. Otherwise, a lease shorter than any fixed cadence would lapse before anything renewed it. A lease that is already gone is caught early, but not before the phase begins. Hashing, the preflight, and the start of the stream can all run while the first heartbeat is still outstanding. Thus, the first heartbeat makes sure that the loss is learned during the upload instead of after it. Each heartbeat answers with the window that it just renewed. The loop arms the next heartbeat when the current heartbeat starts, not when it settles. Thus, a heartbeat that never answers is abandoned on schedule and does not stop the schedule. A phase that settles does not wait for a heartbeat still in flight.
Cadence and budget are deliberately two numbers. A heartbeat is armed every third of the window, but it is allowed the whole window to answer. If the budget were equal to the cadence, a heartbeat that needs more than a third of a window for its round trip could never answer. Examples are a tunneled proxy and an uplink that the upload itself saturates. Every heartbeat would then time out again on exactly the slow links that the heartbeat exists to protect. The window, not the cadence, is the interval in which liveness still matters. Thus, the window is also the longest time that an answer to a heartbeat is worth a wait.
That ceiling is the shorter of the window and the heartbeat's own request policy, currently ninety seconds. Thus, a ten-minute lease gives a heartbeat ninety seconds instead of the full window. This limit costs nothing that the heartbeat exists to provide. The daemon renews the lease when it handles the request, before it answers. Thus, a round trip abandoned at the cap has still extended the lease if the request ever arrived. If the request never arrived, the transport has stopped carrying traffic. A socket held open for the rest of a window measured in minutes does not help that transport. The cap refuses exactly that idle hold. The cap binds only on windows longer than the policy. On those windows, the heartbeat already has the longest answer deadline that any lease gets. Shorter windows are bounded by their own window, as above.
A heartbeat is a fresh request each time, never the protected request rewritten. The reason is that a timed-out heartbeat is canceled under its request identity, and heartbeats must not inherit each other's cancellation. In these cases, a heartbeat ends the phase with that error and cancels the upload:
- The heartbeat finds that the lease is gone.
- The heartbeat finds that this request can never renew the lease. This is so if the scope is missing or belongs to another lease. This is also so if the daemon rejects the scope and window that the heartbeat itself was built with, which no later heartbeat will ask differently.
Thus, the upload does not finish bytes against a device that nobody owns or a lease that will stop renewing. A heartbeat that fails for any other reason is reported, and the phase continues. The reason is that a later heartbeat covers one lost request. This includes a request abandoned at its budget instead of answered. Thus, that promise holds for a stalled round trip, not only for a round trip that fails fast.
Human-control holds coexist with an open remote session.
They belong to LeaseRegistry.
They use the same backend/provider/device contention key as device-aware leases.
Hold heartbeat, expiry, lease preservation, and release refresh are one registry-owned lifecycle.
Release or expiry of the last hold gives the lease its existing inactivity TTL again.
Expiry uses the hold's expiry instant.
Tenant hold operations are ordinary daemon RPCs admitted through request-admission.ts.
Their device comes only from the admitted lease.
Host administration is a distinct loopback capability authenticated with the daemon token, never a tenant credential.
Tenants cannot modify host holds.
Mutation admission derives from existing recording effects, observation-class inventory, and observability semantics. Takeover and lease heartbeats are exempt from the mutation fence, not from their ownership checks. Unknown effects are treated as mutations. A pending activation fences new mutations and drains the mutations already admitted before it reports active. Advisory execution locks alone do not establish this guarantee for fresh sessions.
Activation follows the cancellation signal of the calling RPC or host HTTP request. A disconnect during the drain removes only the pending hold of that request. Successor and unrelated holds remain intact. A canceled activation does not cancel the mutations under drain. Completed holds use their TTL or explicit release lifecycle.
Holds and ordinary proxy leases are in-memory and do not survive daemon restart. Controllers must reconnect and establish them again. No persisted hold store is used. Local takeover is deferred. A future host-global human-control fence must coexist with the device claim of the local session, not acquire it exclusively.
A lease on the macOS host would rent the whole desktop.
Thus, the macOS platform rents one app instead.
The device key of a macos-app lease is a bundle id, optionally pinned to one process (<bundleId> or <bundleId>@<pid>).
If a tenant could name the scope, the scope would be self-chosen.
Thus, only a host administrator allocates a macos-app lease, over the loopback /admin/leases route that uses the daemon token like host holds.
Tenant lease_allocate refuses the backend.
The host picks the lease id.
A repeated PUT renews the lease.
A PUT that names another scope for an existing id is refused, not rewritten.
Heartbeat, expiry, and the loss on daemon restart are those of any lease, with two exceptions:
- A tenant heartbeat or request cannot renew the lease for longer than the window of the host's last PUT.
- A tenant cannot release the lease.
lease_releaseis refused withMACOS_APP_LEASE_HOST_OWNED.
The lease ends through one of these:
- The host's
DELETE /admin/leases/<lease-id>. - Expiry.
- The loss on daemon restart.
- The close of a session that the lease holds, if the host set
retainOnCloseto false.
Request admission confines every request admitted under the lease.
Thus, batch steps and replay actions are confined when they enter admission again.
The confinement has these parts:
- An allow list of commands: the commands whose command registry descriptor declares
appLease: 'allowed'. A command without that declaration is refused, including a command that is added later. Of the commands that lease admission otherwise exempts, onlylease_heartbeatandlease_releasedeclare it. openandcloseof the leased bundle only.- The
appsurface only. - Window-only screenshots.
- No input that names a host path or launches beside the app.
- For every request except
openand thebatchenvelope, an existing session that is the leased app.
Thus, a request that names no session cannot fall back to the host Mac.
open requires the native app backend (ADR 0031), because XCTest posts screen events that can land outside the app's window.
Before each admitted request, a pid-pinned lease is checked against the running process.
A session opened under the lease binds the app device of the leased bundle, not the Mac (ADR 0035).
It takes that app device's claim, like any other session.
Sessions on other apps of the Mac do not conflict with it, in this daemon or another.
A session on the same app, or on the whole Mac, conflicts with it.
A tenant sees that conflict as a generic DEVICE_IN_USE with its typed reason, never the other owner's session, workspace, state directory, or recovery command.
Thus, one daemon serves several leased apps beside the host's own app sessions.
These rules bind a request that names the lease or runs in its session.
A daemon policy leases.require (ADR 0029) refuses requests that name no lease.
The proxy token is one credential for every client.
Thus, a host that serves several clients through one proxy authenticates each client.
The host sets the tenant, session isolation, and lease of that client on every request that it forwards.
A proxy lease can name a device spec beside platform, target, and device: osVersion, imageTag, and physical on agent_device.lease.allocate.
Only a backend in front of the daemon, such as simlock, can pick a device by these keys.
A daemon cannot pick by them.
If a daemon ignored them, a request would run on a device that it did not ask for.
Thus, a daemon refuses every request that names a non-blank osVersion or imageTag, or physical: true, before admission and before a lease is recorded.
The refusal is UNSUPPORTED_OPERATION with details.reason: 'device-spec-unsupported' and details.keys.
This applies to a local daemon and to a daemon behind agent-device proxy.
A blank osVersion or imageTag and physical: false name nothing, so a daemon accepts them.
A named value is used as given, without trimming.
A value of another type is refused with INVALID_ARGS, details.reason: 'device-spec-invalid', and details.keys.
readLeaseDeviceSpec is the one decision on these rules, for CLI flags, the SDK, MCP, and the daemon.
A remote config file first applies the value rules of every config key: a string must be non-empty, and a boolean also accepts a boolean string such as "true".
The backend that honours the spec strips the keys before it forwards the allocation, and echoes the granted device on the lease as lease.device (model, osVersion, imageTag?, physical).
deviceKey stays the identity of the lease; lease.device is the proof that the spec was understood.
A backend older than the spec returns a lease without lease.device.
The CLI proxy connection then releases that lease and fails with UNSUPPORTED_OPERATION and details.reason: 'device-spec-unsupported'.
details.released reports whether the release succeeded.
A live lease serves a later command only when every spec key that the command names equals the one the lease was allocated by; otherwise the command fails with CONNECTION_DEVICE_CONFLICT.
The client never picks a device by spec from the daemon inventory.
--target stays the only class selector.
Rejected: partial honouring of the keys that a daemon understands, because a silent mismatch is worse than a refusal; a separate --device-class flag, because --target already names the class.