Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
a91a54e
test: a plain lease on a phones-only platform is refused with UNKNOWN…
V3RON Nov 16, 2026
217b998
feat(leasing): a plain lease on a phones-only platform is refused at …
V3RON Nov 16, 2026
cc7e413
docs(config): android.virtualDevices and ios.virtualDevices (#1598)
V3RON Nov 16, 2026
a14f15d
test: a --physical lease on a phones-only platform is granted, waits …
V3RON Nov 16, 2026
1c34ceb
test: <platform>.virtualDevices loads, config set writes it, and a no…
V3RON Nov 16, 2026
9a4eb01
feat(config): android.virtualDevices and ios.virtualDevices are boole…
V3RON Nov 16, 2026
074f4b4
test: the catalog of a phones-only worker has empty lists and virtual…
V3RON Nov 16, 2026
7220d1b
feat(catalog): a phones-only platform's entry has empty lists and vir…
V3RON Nov 16, 2026
df5776d
test: simlock catalog prints the phones-only line (#1598)
V3RON Nov 16, 2026
6ac4b90
feat(cli): simlock catalog says virtual devices are off for a phones-…
V3RON Nov 16, 2026
702f00c
test: component install, list and remove work on a phones-only platfo…
V3RON Nov 16, 2026
33f1e22
test: startup on a phones-only platform deletes its idle devices and …
V3RON Nov 16, 2026
f7b6123
feat(core): startup deletes the idle devices of a platform whose virt…
V3RON Nov 16, 2026
7c84e12
docs(events): virtual-devices-off initiates device.shutdown and devic…
V3RON Nov 16, 2026
5fdf497
test: the warm pool on a phones-only platform boots nothing and holds…
V3RON Nov 16, 2026
eeca099
feat(warm-pool): a platform with virtual devices off holds no reserve…
V3RON Nov 16, 2026
6524df8
test: doctor names <platform>.virtualDevices for a warm target it can…
V3RON Nov 16, 2026
42c4a6c
feat(doctor): a warm target on a phones-only platform is reported wit…
V3RON Nov 16, 2026
3766c43
docs: the phones-only platform in the manuals, flows, errors and trou…
V3RON Nov 16, 2026
c1b6823
Merge remote-tracking branch 'origin/feature/1588-adr' into task/1598
V3RON Nov 16, 2026
ced124e
docs: cite ADR 0080 for the phones-only platform after the renumber (…
V3RON Nov 16, 2026
ab4578b
refactor(warm-pool): one expression keeps a platform's reserve or zer…
V3RON Nov 16, 2026
2638b45
fix(test): virtualDevices-off test leases the other platform; correct…
V3RON Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/internal/EVENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,8 @@ worker is ever contacted. `lease-id-taken` (ADR 0020; widens a published vocabul
| `device.quarantine-recovered` | device id, attempts, reclaim strategy (erase/snapshot/wipe/uninstall), `missingApps` for a physical device (additive), the device's `platform` (`ios` or `android`) | a quarantined device's retried purge succeeded; it returned to `ready`/`shutdown` and rejoined the warm pool. Never emitted for a spent `fresh` device (`mayBeGranted` false): its retry is a delete, and a successful one emits `device.deleted` with initiator `lease-end` (`lease-engine` for a device that never served a lease) | QuarantineCoordinator | implemented |
| `device.quarantine-abandoned` | device id, attempts, the device's `platform` (`ios` or `android`) | a quarantined device exhausted its configured retry budget (`warmPool.quarantine.maxRetries`) — purge retries, or delete retries for a spent `fresh` device — and was destroyed, or, for a physical device, unenrolled: Simlock never destroys one (safety rule 2, ADR 0022 §4) | QuarantineCoordinator | implemented |
| `device.quarantine-stranded` | device id, attempts, stable error summary, the device's `platform` (`ios` or `android`) | a quarantined device exhausted its retry budget (purge or delete retries) and the destroy that should have retired it also failed; it stays `quarantined` with no further retry until an operator intervenes | QuarantineCoordinator | implemented |
| `device.shutdown` | device id, initiator (rule/command; `daemon-stop` when a stopping daemon shut down an idle device, #1056; `warm-pool` when the warm pool shut an idle device down, over the running limit, with `warmPool.enabled: false`, to keep `warmPool.reserveRunning` running slots free, or because a ready device that never served a lease and that no `warmPool.targets` entry and no kind the pool learned from a lease keeps has been idle past `idle.shutdownAfterMs`, or to displace it: an idle device shut down so a newer learned kind, or a configured target, can boot into its slot; `lease-engine` when a ready warm device failed the reboot a lease with `except` asked of it, ADR 0066 §2) | device stopped, still on disk | Registry; ReclaimCoordinator for interrupted reclaim recovery | implemented |
| `device.deleted` | device id, initiator (`lease-end` when a `fresh` device's lease ended and its delete completed — from ReclaimCoordinator, at startup convergence, or retried from quarantine; #75. `doctor` when `doctor --fix` marked a missing device, or startup's lease reconciler found a leased device absent from a platform it could read and ended the lease in the same write, ADR 0019 §2. `operator` when `device remove` unenrolled a physical device, ADR 0022 §2. `quarantine` when a physical device's quarantine retries ran out and it was unenrolled, ADR 0022 §4; `lease-engine` when a device that failed to boot for a lease was destroyed in cleanup, or when quarantine's delete retry removed a device that never served a lease; `cleanup-reaper` when the cleanup reaper destroyed a device; `nuke` when `nuke` destroyed it; `baseline-save` when `baseline save` kept a copy of the device and deleted it; `baseline-remove` when `baseline remove` deleted an idle device made from the baseline; `baseline-replaced` when a newer baseline version replaced the one an idle device was made from and the device was deleted), physical (the record's own flag: `true` for an enrolled physical device, `false` for a simulator or emulator; additive, events rule 6) | device removed from the registry, and from disk for a virtual device; a physical device is only forgotten and nothing is sent to it | Registry | implemented |
| `device.shutdown` | device id, initiator (rule/command; `daemon-stop` when a stopping daemon shut down an idle device, #1056; `warm-pool` when the warm pool shut an idle device down, over the running limit, with `warmPool.enabled: false`, to keep `warmPool.reserveRunning` running slots free, or because a ready device that never served a lease and that no `warmPool.targets` entry and no kind the pool learned from a lease keeps has been idle past `idle.shutdownAfterMs`, or to displace it: an idle device shut down so a newer learned kind, or a configured target, can boot into its slot; `lease-engine` when a ready warm device failed the reboot a lease with `except` asked of it, ADR 0066 §2; `virtual-devices-off` when startup shut down an idle device of a platform whose `<platform>.virtualDevices` is false, ADR 0080 §2) | device stopped, still on disk | Registry; ReclaimCoordinator for interrupted reclaim recovery | implemented |
| `device.deleted` | device id, initiator (`lease-end` when a `fresh` device's lease ended and its delete completed — from ReclaimCoordinator, at startup convergence, or retried from quarantine; #75. `doctor` when `doctor --fix` marked a missing device, or startup's lease reconciler found a leased device absent from a platform it could read and ended the lease in the same write, ADR 0019 §2. `operator` when `device remove` unenrolled a physical device, ADR 0022 §2. `quarantine` when a physical device's quarantine retries ran out and it was unenrolled, ADR 0022 §4; `lease-engine` when a device that failed to boot for a lease was destroyed in cleanup, or when quarantine's delete retry removed a device that never served a lease; `cleanup-reaper` when the cleanup reaper destroyed a device; `nuke` when `nuke` destroyed it; `baseline-save` when `baseline save` kept a copy of the device and deleted it; `baseline-remove` when `baseline remove` deleted an idle device made from the baseline; `baseline-replaced` when a newer baseline version replaced the one an idle device was made from and the device was deleted; `virtual-devices-off` when startup deleted an idle device of a platform whose `<platform>.virtualDevices` is false, ADR 0080 §2), physical (the record's own flag: `true` for an enrolled physical device, `false` for a simulator or emulator; additive, events rule 6) | device removed from the registry, and from disk for a virtual device; a physical device is only forgotten and nothing is sent to it | Registry | implemented |
| `device.enrolled` | device id, platform, driver device id (the canonical ID), model, OS version, class (phone/tablet), app count, reenrolled, initiator (`operator` or `auto`) | an admin's `device add`, or the worker's auto-enroller under `devices.autoEnroll` (ADR 0073), wrote a physical device `ready` (ADR 0022 §2). `reenrolled` is `true` when the device already had a `ready`, `quarantined` or `absent` record, which kept its registry ID and took a fresh read of model, OS version, class and apps | Registry | implemented |
| `device.absence-detected` | device id, previous state (ready/leased/reclaiming), absent reason (locked/untrusted/not-present) | an enrolled physical device became `absent` (ADR 0022 §2, §7, §8): the `PhysicalDeviceWatcher` read it not present `health.stableObservations` times in a row (a leased device's lease ends first, `lease.released` device-lost, in the same write), or `ReclaimCoordinator` found it not present after a failed reclaim (`reclaiming → absent`, no `device.purge-failed`, no `device.quarantined`). Emitted after the commit | Registry (the watcher's writes, the reclaim's failure path) | implemented |
| `device.returned` | device id, OS version | the watcher read an `absent` physical device present, and the return reclaim it started committed `absent → reclaiming` with the OS version the read reports (ADR 0022 §7). Emitted after that commit; the reclaim then emits `device.reclaimed` | Registry (written by `ReclaimCoordinator`'s return reclaim) | implemented |
Expand Down
2 changes: 1 addition & 1 deletion docs/internal/flows/device-selection.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Never read: the sdkmanager catalog. A preference list is merged in `daemon/worke

## Virtual: request → spec

In `AcquisitionSpecResolver` (`leasing/acquisition-spec-resolver.ts`), a part of `LeaseAcquisitionCoordinator`, no lock held:
In `AcquisitionSpecResolver` (`leasing/acquisition-spec-resolver.ts`), a part of `LeaseAcquisitionCoordinator`, no lock held. A platform whose `<platform>.virtualDevices` is `false` is refused first, with `VirtualDevicesOffError` (`UNKNOWN_MODEL`), before the baseline branch, any catalog read or download (ADR 0080 §2):

1. `physical: true` → skip to the physical branch.
A virtual Android request with no `imageTag` on a worker with `android.defaultImageTag` is tried first as if it named that tag, with downloads off and `defaultTag` set so only host-CPU images count; a `RuntimeMissingError` runs steps 2 to 9 again on the request as it came (ADR 0078).
Expand Down
5 changes: 4 additions & 1 deletion docs/internal/flows/startup.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,10 @@ Before step 16, a driver with `deviceTcp` sweeps the reverse rules into 47000-47
`device.shutdown` (initiator `startup-interrupted-reclaim`).
3. Spent deletes: `shutdown` devices that may not be granted again are deleted
inline. A failed delete is logged; the device stays `shutdown`.
4. Warm pool and capacity observer start. The pool closes the lease rows of its learned-kind
4. Idle devices of a platform whose `<platform>.virtualDevices` is `false`: a `ready` one is
shut down, then every `ready` or `shutdown` one is deleted (initiator `virtual-devices-off`),
skipping claimed and leased ones. A failure is logged and the start goes on.
5. Warm pool and capacity observer start. The pool closes the lease rows of its learned-kind
record whose lease the registry no longer holds, and its first pass boots the recorded kinds.
22. `queue.changed` with the first depth. Converge done → health `running`.

Expand Down
5 changes: 5 additions & 0 deletions src/cli/commands/catalog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@
function formatCatalog(response: CatalogGetOutput): string {
if (response.platforms.length === 0) return "No platforms available.";
return response.platforms
.map((entry) => {

Check failure on line 40 in src/cli/commands/catalog.ts

View workflow job for this annotation

GitHub Actions / Fallow

High CRAP score (moderate)

Function '<arrow>' has a CRAP score of 31.6 (threshold: 30). • Severity: moderate • Cyclomatic: 10 • Cognitive: 10 • CRAP: 31.6 (threshold: 30) • Lines: 48 CRAP combines complexity with coverage: high CRAP means changes here carry high risk. Consider adding tests, simplifying the function, or both.
const defaultRuntime = entry.defaultRuntime ?? "(none)";
const custom = new Set(entry.customModels ?? []);
const modelLine = (model: string): string[] => {
Expand Down Expand Up @@ -69,6 +69,11 @@
);
return [
`Platform: ${entry.platform}`,
...(entry.virtualDevices === false
? [
` Virtual devices: off (${entry.platform}.virtualDevices is false); only enrolled physical devices are leased`,
]
: []),
` Runtimes: ${entry.runtimes.length > 0 ? esc(entry.runtimes.join(", ")) : "(none)"} (default: ${esc(defaultRuntime)})`,
...(entry.defaultImageTag === undefined
? []
Expand Down
33 changes: 33 additions & 0 deletions src/cli/index-catalog-components.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,39 @@ describe("CLI: catalog", () => {
);
});

it("prints the phones-only line right after the platform line, and --json carries virtualDevices false", async () => {
const entry = {
classDefaults: {},
modelAliases: {},
modelClasses: {},
modelRuntimes: {},
models: [],
platform: "android" as const,
runtimes: [],
virtualDevices: false as const,
};
const run = async (arguments_: string[]) => {
const output = outputCapture();
const environment = output.environmentWith({
connectAdmin: async () =>
fakeClient({ getCatalog: () => Promise.resolve({ platforms: [entry] }) }),
});
await expect(runCli(arguments_, environment)).resolves.toBe(0);
return output.stdout;
};

expect(await run(["catalog", "--platform", "android"])).toBe(
[
"Platform: android",
" Virtual devices: off (android.virtualDevices is false); only enrolled physical devices are leased",
" Runtimes: (none) (default: (none))",
" Models: (none)",
"",
].join("\n"),
);
expect(JSON.parse(await run(["catalog", "--json"]))).toEqual({ platforms: [entry] });
});

it("prints each model with the runtimes it pairs with", async () => {
const output = outputCapture();
const environment = output.environmentWith({
Expand Down
2 changes: 1 addition & 1 deletion src/contract/protocol.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ export interface ProtocolRange {
const protocolRangeSchema = z.object({ min: z.number().int(), max: z.number().int() });

/** Widen only once a second version is kept alive side by side with the first; a bump that leaves no shim behind moves both ends. */
export const PROTOCOL_VERSION_RANGE: ProtocolRange = { min: 89, max: 91 };
export const PROTOCOL_VERSION_RANGE: ProtocolRange = { min: 89, max: 92 };

const LEGACY_DAEMON_PROTOCOL_VERSION = 2;

Expand Down
2 changes: 2 additions & 0 deletions src/contract/status-schemas.ts
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,8 @@ export const platformCatalogSchema = z.object({
.optional(),
defaultMode: deviceModeSchema.optional(),
defaultImageTag: imageTagSchema.optional(),
/** why: ADR 0080 §3: `false` says this worker serves only enrolled physical devices of the platform; absent means it makes virtual devices. */
virtualDevices: z.literal(false).optional(),
});

/**
Expand Down
1 change: 1 addition & 0 deletions src/core/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ Devices:
- `devices.except_categories` holds the list a lease kept running, written in the grant commit (`createLease`).
- `shutdown`, `destroy` and `dispose` answer `undefined` for a leased, gone or moved device. That is not an error.
- Unreadable is not gone: startup skips a platform it could not list; doctor reports no drift there.
- Startup deletes the idle `ready` and `shutdown` devices of a platform whose `<platform>.virtualDevices` is `false` (initiator `virtual-devices-off`); a leased one runs to its release (ADR 0080 §2).
- Warm pool and startup never install. Instance id is never regenerated.
- `sweepWriteLeftovers` logs a pid-less legacy leftover and never deletes it.
- Doctor's `service-broken` comes from an injected `serviceCheck`, never from drift.
Expand Down
13 changes: 11 additions & 2 deletions src/core/config-defaults.ts
Original file line number Diff line number Diff line change
Expand Up @@ -149,8 +149,17 @@ export function defaultConfig(
recoveryBackoffMs: 5_000,
maxConcurrentRecoveries: 1,
},
ios: { ...driverDefaults(driverSections, "ios"), defaultMode: "full", defaultModels: {} },
android: { ...driverDefaults(driverSections, "android"), defaultModels: {} },
ios: {
...driverDefaults(driverSections, "ios"),
defaultMode: "full",
defaultModels: {},
virtualDevices: true,
},
android: {
...driverDefaults(driverSections, "android"),
defaultModels: {},
virtualDevices: true,
},
gateway: {
disconnectedRetentionMs: DEFAULT_DISCONNECTED_RETENTION_MS,
execTimeoutMs: DEFAULT_GATEWAY_EXEC_TIMEOUT_MS,
Expand Down
41 changes: 39 additions & 2 deletions src/core/config-platform-and-driver-settings.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,12 @@ describe("loadConfig", () => {
'Invalid config value for "android.turbo"',
);
expect(unknown.warn).toHaveBeenCalledWith('Unknown config key: "android.turbo"');
expect(unknown.config.android).toEqual({ defaultModels: {} });
expect(set.config.ios).toEqual({ defaultMode: "full", defaultModels: {} });
expect(unknown.config.android).toEqual({ defaultModels: {}, virtualDevices: true });
expect(set.config.ios).toEqual({
defaultMode: "full",
defaultModels: {},
virtualDevices: true,
});
});

it("loads android.defaultImageTag when it is a valid image tag, leaves it unset when absent, and refuses any other value naming the key and what it expects", async () => {
Expand All @@ -77,6 +81,39 @@ describe("loadConfig", () => {
}
});

it("loads <platform>.virtualDevices as true when unset, false when set, refuses a non-boolean naming the key, and ignores it with a warning on a gateway", async () => {
const load = async (file: unknown, role: "gateway" | "worker" = "worker") => {
const filesystem = new MemoryFilesystem();
const warn = vi.fn();
await filesystem.mkdirp("/home/agent/.simlock");
await filesystem.writeFileAtomic(configPath, JSON.stringify(file));
const config = await loadConfig({
configPath,
filesystem,
role,
systemStats: createStats(),
warn,
});
return { config, warn };
};

const unset = (await load({})).config;
expect([unset.android.virtualDevices, unset.ios.virtualDevices]).toEqual([true, true]);
const android = (await load({ android: { virtualDevices: false } })).config;
expect([android.android.virtualDevices, android.ios.virtualDevices]).toEqual([false, true]);
const ios = (await load({ ios: { virtualDevices: false } })).config;
expect([ios.android.virtualDevices, ios.ios.virtualDevices]).toEqual([true, false]);
for (const value of ["no", 0]) {
await expect(load({ android: { virtualDevices: value } }), String(value)).rejects.toThrow(
'Invalid config value for "android.virtualDevices": expected a boolean',
);
}
const gateway = await load({ ios: { virtualDevices: false } }, "gateway");
expect(gateway.warn).toHaveBeenCalledWith(
'Ignoring "ios": it configures a worker, and this daemon runs in gateway mode.',
);
});

it.each(["fast", "worker", true])(
"rejects an ios.defaultMode of %j, naming the key",
async (value) => {
Expand Down
4 changes: 4 additions & 0 deletions src/core/config-types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -166,11 +166,15 @@ export interface Config {
readonly ios: {
readonly defaultMode: DeviceMode;
readonly defaultModels: DefaultModels;
/** why: false makes this worker serve only enrolled physical iOS devices (ADR 0080 §1). */
readonly virtualDevices: boolean;
} & DriverConfigSection;
readonly android: {
/** why: the image tag an Android lease that names none gets where an image of it fits (ADR 0078 §1). */
readonly defaultImageTag?: string;
readonly defaultModels: DefaultModels;
/** why: false makes this worker serve only enrolled physical Android devices (ADR 0080 §1). */
readonly virtualDevices: boolean;
} & DriverConfigSection;
/**
* why: ADR 0005 §3/§6. Both sides of the fleet live under one key, and which half is read depends
Expand Down
2 changes: 2 additions & 0 deletions src/core/config-validators.ts
Original file line number Diff line number Diff line change
Expand Up @@ -256,11 +256,13 @@ export function configValidators(
...driverValidators(driverSections, "ios"),
defaultMode: stringUnion(["slim", "full"]),
defaultModels: defaultModelsValidator,
virtualDevices: booleanValue,
}),
android: objectValidator({
...driverValidators(driverSections, "android"),
defaultImageTag: imageTagValidator,
defaultModels: defaultModelsValidator,
virtualDevices: booleanValue,
}),
stalledTransition: objectValidator({
thresholdMultiplier: numberAtLeast(1),
Expand Down
27 changes: 27 additions & 0 deletions src/core/create-core.ts
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,10 @@ export function createCore(options: CoreOptions): Core {
const drivers = new DriverCatalog(options.drivers, {
logger: options.logger,
preferences: options.modelPreferences,
virtualDevices: {
android: options.config.android.virtualDevices,
ios: options.config.ios.virtualDevices,
},
});
const deviceLifecycle = new ManagedDeviceLifecycle(
drivers,
Expand Down Expand Up @@ -390,6 +394,29 @@ export function createCore(options: CoreOptions): Core {
const startup = new StartupConverger({
claims,
decisions,
idleDeletion: {
// why: a failed shutdown or delete must not stop the daemon from starting: the device stays in the state it reached and the next start tries again (ADR 0080 §2).
deleteIdle: async (device) => {
try {
const stopped =
device.state === "ready"
? await deviceLifecycle.shutdown(device, "virtual-devices-off", "cleanup")
: device;
if (stopped !== undefined) {
await deviceLifecycle.destroy(stopped, "virtual-devices-off", "cleanup");
}
} catch (error: unknown) {
options.logger?.warn("Could not delete an idle device at start", {
deviceId: device.id,
error: stableError(error),
platform: device.spec.platform,
});
}
},
platforms: (["ios", "android"] as const).filter(
(platform) => !drivers.virtualDevices(platform),
),
},
interruptedReclaimRecovery: {
recoverInterruptedReclaim: async (device) => {
await reclaim.recoverInterrupted(device.id);
Expand Down
Loading
Loading