Skip to content

Commit f504227

Browse files
thymikeeclaude
andcommitted
fix(providers): hand a ready device only to callers still within budget
Second review round on the shared lease table: - A ready answer goes to a caller only while that caller's own signal and deadline still hold, so a caller whose deadline passed before its timer ran is not handed a device; nobody waiting means it is stopped. - The session a start rented is recorded even when nobody takes it, so a release that ended the start reports the device (Revyl: `revylRunId`). - A caller whose budget is already spent sends no start. - Shutdown repeats its drain until it has ended every entry, including one a recovery or release opened while it ran. - Revyl carries its platform in the lease request, names its cap `REVYL_ALLOCATION_TIMEOUT_MS` with a margin over start plus readiness, and builds its driver with `createRevylLeaseDriver`. - ADR 0007 records the inventory and interactor effect of the fence, the `provider-lease-releasing` reason and Revyl's in-process digest change. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 85259a8 commit f504227

7 files changed

Lines changed: 158 additions & 41 deletions

File tree

‎docs/adr/0007-remote-device-leases.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
Accepted
66

7-
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). 2026-11-02, the Revyl provider runtime serves its lease lifecycle from a shared lease table instead of a table of its own (#4102).
7+
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). 2026-11-02, the Revyl provider runtime serves its lease lifecycle from a shared lease table instead of a table of its own, and its runtime-owner instance widens to the shared 32-byte digest, which Revyl keeps in-process only (#4102).
88

99
## Rules at a glance
1010

@@ -167,10 +167,10 @@ The provider supplies its start timeout, an optional stop timeout, start, stop,
167167
The table owns the rules that decide whether a billed device is still rented:
168168

169169
- One lease id has at most one start. Overlapping allocations join it, and a ready session is reused.
170-
- Each caller waits until the earlier of its own deadline and the start timeout. A caller that gives up stops nothing. A ready device goes to the callers still waiting, and it is stopped when no caller waits.
170+
- Each caller waits until the earlier of its own deadline and the start timeout. A caller whose budget is already spent sends no start. A caller that gives up stops nothing. A ready device goes to the callers still waiting within their budgets, and it is stopped when no caller waits.
171171
- A start can publish its rental before it answers. A teardown waits for the answer for at most the start timeout, then stops the published rental and keeps the lease pending until the answer arrives.
172-
- Release, recovery, a failed start, and shutdown each end a lease through one teardown that all of them join. The teardown fences the lease in the same step: from then on, an allocation of the lease is refused, including an allocation that was already waiting.
173-
- A teardown forgets a lease only after the provider confirmed the stop of every rental that it knows. A failed or late stop keeps the lease for the next teardown, which joins the stop still in flight. Shutdown reports what stays rented with `provider-cleanup-pending`.
172+
- Release, recovery, a failed start, and shutdown each end a lease through one teardown that all of them join. The teardown fences the lease in the same step: from then on, an allocation of the lease is refused, including an allocation that was already waiting, and the device inventory and interactor no longer serve the lease. Revyl reports the refusal as `provider-lease-releasing`.
173+
- A teardown forgets a lease only after the provider confirmed the stop of every rental that it knows. A failed or late stop keeps the lease for the next teardown, which joins the stop still in flight. Shutdown also ends every lease that a recovery or release opens while it drains, and it reports what stays rented with `provider-cleanup-pending`.
174174
- If a start fails without an answer, or a recovery finds no entry, the teardown asks find-by-lease. If the provider cannot name the rental, the lease stays pending, and the next teardown asks again.
175175

176176
A table in each provider was rejected: each provider derived the same rules again, and most review findings on the second provider (#4092) were about that bookkeeping.

‎packages/contracts/src/platform-runtime.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,10 @@ export function providerRuntimeOwner(
7777
});
7878
}
7979

80-
// Changing these re-identifies every provider runtime, and so orphans every durable resource whose
81-
// envelope names an owner instance, such as a Limrun app-log descriptor. The length is fixed for the
82-
// same reason. Each provider pins its own digest through the wrapper that builds its principal.
80+
// Changing these re-identifies every provider runtime. For a provider that writes its instance into
81+
// durable state, such as Limrun's app-log descriptors, that orphans every such resource; Revyl keeps
82+
// its instance in-process only. The length is fixed for the same reason. Each provider pins its own
83+
// digest through the wrapper that builds its principal.
8384
const RUNTIME_INSTANCE_KEY_LENGTH_BYTES = 32;
8485
const RUNTIME_INSTANCE_SCRYPT_COST = 16_384;
8586
const RUNTIME_INSTANCE_SCRYPT_MAX_MEMORY = 64 * 1024 * 1024;

‎packages/provider-revyl/src/revyl-session.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,12 @@ import type {
1717

1818
/** How long Revyl may take to assign a worker and connect the device before the start is given up on. */
1919
const READY_TIMEOUT_MS = 240_000;
20-
/** The longest one allocation may take: `start_device`'s own answer budget, then readiness. */
21-
export const REVYL_START_TIMEOUT_MS = REVYL_START_DEVICE_TIMEOUT_MS + READY_TIMEOUT_MS;
20+
/**
21+
* The longest one allocation may take: `start_device`'s own answer budget, then readiness measured
22+
* from that answer, and a margin so the lease table's cap never cuts readiness Revyl still allows.
23+
*/
24+
export const REVYL_ALLOCATION_TIMEOUT_MS =
25+
REVYL_START_DEVICE_TIMEOUT_MS + READY_TIMEOUT_MS + 10_000;
2226
/** Revyl's worker answers `health` with 503 until the device is attached; the CLI polls on that beat. */
2327
const READY_POLL_INTERVAL_MS = 2_000;
2428
/** Revyl releases an idle session on its own; this is the lease the runtime asks for. */
@@ -61,7 +65,7 @@ export type RevylStartRequestInput = Readonly<{
6165

6266
/**
6367
* One caller's own patience: the signal it cancels with and the deadline it stops at. Both are optional,
64-
* and the lease table cuts the deadline to `REVYL_START_TIMEOUT_MS`.
68+
* and the lease table cuts the deadline to `REVYL_ALLOCATION_TIMEOUT_MS`.
6569
*/
6670
export type RevylCallerBudget = Readonly<{ signal?: AbortSignal; deadline?: number }>;
6771

‎packages/provider-revyl/src/runtime.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -418,6 +418,8 @@ test('a release that lands mid-start stops the session only once Revyl has made
418418
// only has from the lease, and that is what makes the stop below land after the session exists.
419419
const released = await runtime.leaseLifecycle!.release!(lease);
420420
assert.equal(released?.providerSessionId, revylSessionIdForLease('lease-1'));
421+
// The release reports the device the start rented, not only the session id.
422+
assert.equal(released?.revylRunId, 'run-1');
421423
await refused;
422424

423425
const answered = fixture.answeredPaths();

‎packages/provider-revyl/src/runtime.ts‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ import {
2323
} from './device.ts';
2424
import { createRevylClient, isRevylSessionGone, type RevylClient } from './revyl-client.ts';
2525
import {
26-
REVYL_START_TIMEOUT_MS,
26+
REVYL_ALLOCATION_TIMEOUT_MS,
2727
revylCallerGaveUp,
2828
revylCleanupPending,
2929
startRevylSession,
@@ -44,6 +44,9 @@ import { resolveRevylRuntimeInstance } from './runtime-instance.ts';
4444
import { revylSessionIdForLease } from './session-identity.ts';
4545
import type { RevylStartRequest } from './session-allocation.ts';
4646

47+
/** What one lease's start asks Revyl for, with the platform the lease was admitted for. */
48+
type RevylLeaseRequest = RevylStartRequest & Readonly<{ platform: RevylPlatform }>;
49+
4750
export type RevylRuntimeOptions = Readonly<{
4851
apiKey: string;
4952
/** Overrides the Revyl backend origin; unset uses the public backend. */
@@ -96,7 +99,7 @@ export function createRevylRuntime(options: RevylRuntimeOptions): RevylRuntimeRe
9699
class RevylRuntimeImplementation implements ProviderDeviceRuntime {
97100
private readonly options: RevylRuntimeOptions;
98101
/** Every lease this runtime rents a device for, until Revyl confirms that device's `/stop`. */
99-
private readonly leases: ProviderLeaseTable<RevylSession, RevylRentedSession, RevylStartRequest>;
102+
private readonly leases: ProviderLeaseTable<RevylSession, RevylRentedSession, RevylLeaseRequest>;
100103
readonly provider = REVYL_PROVIDER;
101104

102105
readonly leaseLifecycle: LeaseLifecycleProvider = {
@@ -128,7 +131,7 @@ class RevylRuntimeImplementation implements ProviderDeviceRuntime {
128131
...(options.backendUrl === undefined ? {} : { backendUrl: options.backendUrl }),
129132
clientVersion: options.clientVersion,
130133
});
131-
this.leases = createProviderLeaseTable(revylLeaseDriver(client));
134+
this.leases = createProviderLeaseTable(createRevylLeaseDriver(client));
132135
}
133136

134137
ownsDevice(device: DeviceInfo): boolean {
@@ -167,10 +170,15 @@ class RevylRuntimeImplementation implements ProviderDeviceRuntime {
167170
// Before the join below: an allocation that reuses a live lease still carries flags of its own,
168171
// and Revyl reads none of them — whether it starts a device or joins one that is starting.
169172
rejectRefusedRevylProfileFields(context);
170-
const request = resolveRevylStartRequest(context, {
171-
...(this.options.deviceModel === undefined ? {} : { deviceModel: this.options.deviceModel }),
172-
...(this.options.osVersion === undefined ? {} : { osVersion: this.options.osVersion }),
173-
});
173+
const request: RevylLeaseRequest = {
174+
...resolveRevylStartRequest(context, {
175+
...(this.options.deviceModel === undefined
176+
? {}
177+
: { deviceModel: this.options.deviceModel }),
178+
...(this.options.osVersion === undefined ? {} : { osVersion: this.options.osVersion }),
179+
}),
180+
platform,
181+
};
174182
const session = await this.leases.allocate(lease, request, {
175183
...revylCallerBudget(context),
176184
requireJoinable: (started) => requireSameRevylStartRequest(lease.leaseId, started, request),
@@ -205,16 +213,16 @@ class RevylRuntimeImplementation implements ProviderDeviceRuntime {
205213
* What Revyl supplies to the lease table. A session is stopped by the id this runtime issued for its
206214
* lease, so that id is also what a lease this process never started is recovered by.
207215
*/
208-
function revylLeaseDriver(
216+
function createRevylLeaseDriver(
209217
client: RevylClient,
210-
): ProviderLeaseDriver<RevylSession, RevylRentedSession, RevylStartRequest> {
218+
): ProviderLeaseDriver<RevylSession, RevylRentedSession, RevylLeaseRequest> {
211219
return {
212-
startTimeoutMs: REVYL_START_TIMEOUT_MS,
220+
startTimeoutMs: REVYL_ALLOCATION_TIMEOUT_MS,
213221
// A session is created when `start_device` answers, not when it is sent, so the issued id is never
214222
// published before that answer: a stop sent earlier reads as "already gone" and leaves the device.
215223
start: async (lease, request, control) => {
216224
const started = await startRevylSession(client, lease, {
217-
platform: revylLeasePlatform(lease),
225+
platform: request.platform,
218226
appUrl: request.appUrl,
219227
deviceModel: request.deviceModel,
220228
osVersion: request.osVersion,
@@ -282,7 +290,7 @@ function revylLeasePlatform(lease: DeviceLease): RevylPlatform {
282290

283291
/**
284292
* The caller's own patience, read from the lease context it arrived with. The lease table cuts its
285-
* deadline to `REVYL_START_TIMEOUT_MS`.
293+
* deadline to `REVYL_ALLOCATION_TIMEOUT_MS`.
286294
*/
287295
function revylCallerBudget(context?: LeaseLifecycleContext): RevylCallerBudget {
288296
return {

‎packages/provision-kit/src/provider-lease-table.test.ts‎

Lines changed: 79 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import assert from 'node:assert/strict';
2-
import { test } from 'vitest';
2+
import { test, vi } from 'vitest';
33
import type { DeviceLease } from '@agent-device/contracts/device';
44
import {
55
createProviderLeaseTable,
@@ -169,6 +169,19 @@ test('overlapping allocations of one lease share one start, and a repeat reuses
169169
assert.deepEqual(await first, { id: 'session-1' });
170170
assert.deepEqual(await second, { id: 'session-1' });
171171
assert.deepEqual(await provider.table.allocate(lease(), {}), { id: 'session-1' });
172+
// Reusing the ready session is checked the same way as joining the start.
173+
await assert.rejects(
174+
provider.table.allocate(
175+
lease(),
176+
{ app: 'b' },
177+
{
178+
requireJoinable: () => {
179+
throw new Error('different request');
180+
},
181+
},
182+
),
183+
/different request/,
184+
);
172185
assert.equal(provider.controls.length, 1);
173186
});
174187

@@ -228,7 +241,10 @@ test('a release during a start refuses the waiting allocation and stops the devi
228241
await settle();
229242
assert.deepEqual(provider.stopped, [], 'the stop waits for the answer that names the device');
230243
provider.answerStart(0, ready('session-1'));
231-
assert.equal((await releasing)?.handle.id, 'session-1');
244+
assert.deepEqual(await releasing, {
245+
handle: { id: 'session-1' },
246+
session: { id: 'session-1' },
247+
});
232248
await refused;
233249
assert.deepEqual(provider.stopped, ['session-1']);
234250
});
@@ -248,6 +264,39 @@ test('a caller that aborts mid-start is answered at once, and the late device is
248264
assert.equal(await provider.table.release('lease-1'), undefined);
249265
});
250266

267+
test("a ready answer after the only caller's deadline is stopped, even before its timer fires", async () => {
268+
// The clock moves past the deadline without running timers, which is a busy event loop: the caller's
269+
// own give-up has not run yet when the start answers.
270+
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] });
271+
try {
272+
const provider = fakeProvider();
273+
const allocating = provider.table.allocate(lease(), {}, { deadline: Date.now() + 100 });
274+
const refused = assert.rejects(allocating, reason('provider-not-ready'));
275+
await settle();
276+
vi.setSystemTime(Date.now() + 200);
277+
provider.answerStart(0, ready('session-1'));
278+
await refused;
279+
await settle();
280+
assert.deepEqual(provider.stopped, ['session-1']);
281+
} finally {
282+
vi.useRealTimers();
283+
}
284+
});
285+
286+
test('a caller whose budget is already spent sends no start', async () => {
287+
const provider = fakeProvider();
288+
await assert.rejects(
289+
provider.table.allocate(lease('lease-1'), {}, { deadline: Date.now() - 1 }),
290+
reason('provider-not-ready'),
291+
);
292+
await assert.rejects(
293+
provider.table.allocate(lease('lease-2'), {}, { signal: AbortSignal.abort() }),
294+
reason('request_canceled'),
295+
);
296+
await settle();
297+
assert.equal(provider.controls.length, 0);
298+
});
299+
251300
test('a joiner still waiting keeps the device when the caller that started it gives up', async () => {
252301
const provider = fakeProvider();
253302
const controller = new AbortController();
@@ -384,6 +433,9 @@ test('a published rental is stopped when its start stalls, and the late answer e
384433
});
385434
await gaveUp;
386435
assert.deepEqual(provider.stopped, ['instance-1'], 'the stalled rental is stopped by its handle');
436+
// The start may still rent, so the lease id is not handed to a new allocation meanwhile.
437+
await assert.rejects(provider.table.allocate(lease(), {}), reason('lease-releasing'));
438+
assert.equal(provider.controls.length, 1);
387439

388440
// The start finally answers with the same rental: it is already stopped, so the lease ends.
389441
provider.answerStart(0, ready('instance-1'));
@@ -429,6 +481,31 @@ test('shutdown waits for an in-flight allocation, stops its device, and refuses
429481
assert.equal(provider.controls.length, 1);
430482
});
431483

484+
test('shutdown also ends a lease that a recovery opens while it drains', async () => {
485+
const provider = fakeProvider();
486+
await allocated(provider);
487+
const stop = deferred<void>();
488+
provider.queueStop(async () => await stop.promise);
489+
// The recovery's own stop fails, and so does the drain's retry of it.
490+
provider.queueStop(refusedStop());
491+
provider.queueStop(refusedStop());
492+
493+
const shutdown = provider.table.shutdown();
494+
await settle();
495+
const recovery = assert.rejects(
496+
provider.table.recover(lease('lease-2')),
497+
reason('provider-cleanup-pending', 'recover'),
498+
);
499+
stop.resolve();
500+
await assert.rejects(shutdown, (error: unknown) => {
501+
assert.ok(reason('provider-cleanup-pending', 'shutdown')(error));
502+
assert.deepEqual((error as TableError).details.handles, ['found-lease-2']);
503+
return true;
504+
});
505+
await recovery;
506+
assert.deepEqual(provider.stopped, ['session-1', 'found-lease-2', 'found-lease-2']);
507+
});
508+
432509
test('shutdown reports what it could not stop and keeps it for a later release', async () => {
433510
const provider = fakeProvider();
434511
await allocated(provider);

0 commit comments

Comments
 (0)