feat(leasing): lease --physical grants, queues and reclaims enrolled physical devices

[V3RON]

Closes #438

Status

Implement: done (11/11 green) Review: passed (4 rounds; maintainer accepted the 2 round-4 findings) Mutate: 654 mutants, 24 alive (explained in audit) Hardware: n/a Gate: running
Next: gate (after-pass review on 4b024fb passed; CI fix for three #436 tests that pinned the interim)

Done when

• simlock lease --platform ios --physical is granted an enrolled, free, present iPhone, and the grant shows it physical (e2e).
• Every row of the input table in "In short" gives the result shown there (e2e).
• Two agents asking for one device: the second is queued and granted after the first releases (e2e).
• A simulator request is not held behind a waiting physical request, nor the reverse (e2e).
• After a release, the fake driver log shows an uninstall for each app not on the enrollment app list and for no other app, and device.reclaimed names any listed app that is missing (e2e).
• A failed reclaim shows the device quarantined in simlock status; when retries run out it shows deleted, device.deleted has initiator quarantine, and the fake driver log has no destroy (e2e).
• The iOS and Android drivers' unit tests show the physical lease environment.
• simlock nuke with a physical lease ends it and the release's uninstall runs; the device stays enrolled (e2e).
• Through a gateway, a physical request is granted a worker's enrolled device (e2e).
• docs/CLI.md and docs/internal/KNOWN-PITFALLS.md say what the spec lists.
• No line needs real hardware.

Assumptions

• Assumption: DeviceRequest.physical type — declared physical?: boolean, not physical?: true, so existing callers that pass a virtual spec (physical: false) as a request still compile; the transports only ever send true.
• Assumption: RoutableRequest.physical is boolean too, and readers test === true.
• Assumption: cancelPending cancels a physical waiter in any live state, presence read included — the smallest rule that never strands a waiter.
• Assumption: a grant whose lease write throws sends the waiter back to waiting (NO_CAPACITY under noWait) with the claim released — matches the virtual path.
• Assumption: UNKNOWN_MODEL wording — a request that wrote an OS range says "os in the requested range"; a request naming neither model nor class says "class phone".
• Assumption: an enrollment commit wakes the queue at the composition root (src/daemon/enrollment-wake.ts), not in core — keeps core free of the leasing port.
• Assumption: nine stale fallow-ignore comments in src/core/registry.ts and one in src/gateway/fleet-coordinator.ts were removed because Fallow reported them stale.
• Assumption: the gateway test asserts the worker through lease.worker.id, not grant.device.workerId — the contract's grant device carries no worker id and the spec's Tests line does not require one; the contract is unchanged.

Mutants left alive (24)

• src/core/domain.ts noPhysicalMatch: request.osVersion !== undefined forced true - the regex rejects the text "undefined" anyway.
• src/core/fake-driver.ts #reclaimPhysical: scripted?.apps ?? [] fallback - extra listed apps only reach uninstall, which the fake ignores.
• src/gateway/fleet-coordinator.ts #walkWaiter: waiter.request.physical !== true - swaps the two claim sets consistently, no observable change.
• src/gateway/routing/stages/physical-interim.ts: kind: "rank" (runStages only tests for filter) and settles: true (module-level object, which Stryker does not run per test; the unit test "settles the pick on the lowest worker id, so a later rank cannot narrow it" fails with settles: false).
• src/http/app.ts toLeaseRequestInput: physical: undefined key - the tracker drops it before dispatch.
• src/leasing/lease-acquisition-coordinator.ts: GRANT_SOURCE "warm" (module-level constant; the test "records a physical grant as lease.granted from a warm device" fails with ""); #drivePhysical plan === undefined return (a TypeError would be swallowed by #track); noWait ?? false (the planner's wait and no-capacity plans both defer); #heldByOlder [] initial value (fitsPhysical on a non-request is false); current?.state in #grantPhysical (a device never leaves the snapshot); granted = false initial value and if (granted) this.#wakeQueue() (the queue re-drive after a grant finds nothing new to plan); operationPlan kind checks (grant-ready is handled before the call and virtual planning never returns grant-physical).

Review

Spec review: 7 blocking, 2 fixed, 4 notes. Code review: 12 blocking, 6 fixed, 8 notes. Claims review: 6 blocking, 6 fixed, 9 notes. Comment review: 56 blocking, 33 fixed, 0 notes.
Mutate: 654 mutants, 24 alive.

Round 1 (ae264a3): spec 4 blocking, code 4 blocking, claims 4 blocking, comments 43 blocking; 34 confirmed.

Round 2 (47d2808): spec 1 blocking, code 2 blocking, claims 0 blocking, comments 6 blocking; 8 confirmed.

Round 3 (44c84a0): spec 1 blocking, code 5 blocking, claims 0 blocking, comments 6 blocking; 5 confirmed.

Round 4 (510dbad): spec 1 blocking, code skipped, claims 0 blocking, comments 1 blocking; 2 confirmed, open.

Rejected:

• code: e2e/physical-devices-core.test.ts:202 title claims the retry waits for retryBackoffMs — the title only says when the record is ready, which the body proves

• spec: src/leasing/lease-acquisition-coordinator.ts:720 no test shows #heldByOlder holds back a device for every older matching waiter — the maintainer accepted it as reviewed

• comments: src/gateway/queue.ts:15 FleetLeaseRecord doc points at another module — the maintainer accepted it as reviewed

• code: src/leasing/lease-acquisition-coordinator.ts:660, :601, :384 test request.physical instead of lineOf — they pick a flow, not a queue line; no input diverges

• code: src/gateway/fleet-coordinator.ts:1347 and src/gateway/routing.ts:44 repeat the physical/virtual split — they choose stages or the forwarded model, not a queue line

• comments: src/gateway/fleet-coordinator.ts:90 and src/gateway/worker-registry.ts:112 cite an ADR — rule 17 allows ADR citations; both give a why

• spec: src/leasing/lease-acquisition-coordinator.ts:767 a failing lease write repeats the presence read without pause — not reproduced: 20 flushes gave 1 call

• spec: src/leasing/lease-acquisition-coordinator.ts:183 UNKNOWN_MODEL loses osVersion on the wire — a worker puts no details on the wire for any UNKNOWN_MODEL

• spec: src/gateway/fleet-coordinator.test.ts:4554 forwarded input not checked for physical — the title names the virtual request, not what was forwarded

• code: src/leasing/lease-acquisition-coordinator.ts:755 isActive check untested — unreachable today; spec line 179 asks for it as a guard

• claims: docs/internal/COMPONENTS.md:69 says missingApps is committed — it rides the committed transition's event; misleads at most

• claims: docs/CLI.md:549 describes a reclaim the real drivers cannot run yet — the doc states the feature's end state

• claims: docs/CLI.md:818 "not judged against a worker's catalog" — matches the spec's interim wording

• claims: docs/CLI.md:1337 self-contradicting sentence — confusing, but true

• claims: src/mcp/server.ts:126 description omits physical — incomplete, not false

• comments: 20 comment findings rejected as giving a why or documenting a client-exported shape (e2e/fake-driver/fake-driver.ts:587, src/cli/index.ts:958, src/contract/operations.ts:171, :181, src/contract/schemas.ts:321, :1049, src/core/domain.ts:24, src/core/driver.ts:113, :115, :326, :357, :364, src/core/reclaim-coordinator.test.ts:290, src/drivers/android/index.ts:910, :1000, src/drivers/ios/index.test.ts:1070, src/gateway/routing/pipeline.ts:31, src/leasing/lease-acquisition-coordinator.ts:142, src/leasing/wait-queue.ts:166, :363)

Written by an agent.

[V3RON]

Handoff

Mode green stopped at the session budget. Branch task/438, PR #456 (draft).

State. All spec unit tests pass (pnpm test:changed: 93 files, 3658 tests). The three e2e files pass except one assertion. Push 7f6739b is on origin and passed Fallow and the e2e typecheck, but its mutation run failed in the dry run (a core-level harness had no leasing port connected). The fix is the local head commit 'refactor(daemon): wake the queue after an enrollment commit at the composition root'; its push was still inside the pre-push mutation run when the budget ended. Check git log origin/task/438.. and push again so mutants are listed.

Open.

• spec needs: e2e/physical-gateway.test.ts:86 asserts grant.device.workerId on a gateway grant. The contract's grant device has no workerId (the worker is lease.worker.id). The rest of that test (grant, release, uninstall on the worker) passes. Adding the field changes every gateway grant, so I did not.
• Flaky, no issue filed: e2e/physical-leasing.test.ts 'a waiting physical request makes the warm pool create or boot nothing' failed once with three files in parallel (startWith's device add ran as agent: admin credential unavailable), then passed alone.
• Mutants not read yet; audit not run (stale-ref sweep, comments sweep, break-the-code check per test).
• PR body needs the new Status, ticked Done when lines (all but the gateway line are delivered by the e2e files the spec names) and these Assumptions: DeviceRequest.physical and RoutableRequest.physical are boolean and readers test === true; cancelPending cancels a physical waiter in any live state, presence read included; a grant whose lease write throws sends the waiter back to waiting (NO_CAPACITY under noWait) with the claim released; the UNKNOWN_MODEL message for a request that wrote an OS range says 'os in the requested range' and a request naming neither model nor class says 'class phone'; an enrollment commit wakes the queue at the composition root (src/daemon/enrollment-wake.ts), not in core; nine stale fallow-ignore comments in src/core/registry.ts and one in src/gateway/fleet-coordinator.ts were removed because the audit reported them stale.

Delivered. Contract (physical, physicalQueueDepth, protocol 25), fitsPhysical/noPhysicalMatch, toDriverDevice/uninstallPlan/readPhysicalPresence, physical reclaim and quarantine (retry, unenrol on give-up), both real drivers' physical environment and not-present presence, both fake drivers, leasing (could-match, grant claim, presence read, queue lines, wake order), gateway (lines, per-line pass claims, physical-interim), CLI --physical, console place, docs (CLI, ABOUT, CONFIGURATION, HTTP-API, CLIENT, CONSOLE, both EVENTS.md, COMPONENTS, ARCHITECTURE, KNOWN-PITFALLS).

[V3RON]

Handoff

Stopped on the session budget. Green is at 5ea6f3a (all unit, 45/46 e2e); the one failure is e2e/physical-gateway.test.ts:86 (asserts grant.device.workerId, which the contract does not carry: decision needed). Audit, reviews and the PR body Status are not done. Details on #438.

[V3RON]

Review notes

Not blocking, not verified. Each is one reviewer's claim.

• spec: src/core/fake-driver.ts:624 the core fake's leaseEnvironment ignores its device, so unit tests cannot see a physical grant's environment

• spec: src/daemon/dispatcher.ts:410 class is added only in the daemon dispatcher's answer; a stored grant has none

• spec: src/core/quarantine-coordinator.test.ts:769 title promises "its missing apps", body asserts only missingApps: [] (e2e proves a non-empty list)

• spec: src/core/domain.ts:644 "its text is what the message names as the fix" reads oddly for a range request

• code: src/leasing/lease-acquisition-coordinator.ts:760 a physical grant's timing.estimatedReclaimMs is 0; the driver prices the uninstall reclaim at 90 s

• code: src/core/domain.ts:676 UNKNOWN_MODEL message tells HTTP and MCP callers to write --os; their field is osVersion

• code: src/core/quarantine-coordinator.test.ts:695 comment explains decisionRuns, which no physical test reads now

• claims: docs/internal/COMPONENTS.md:69, src/mcp/server.ts:126, docs/CLI.md:549, docs/CLI.md:818, docs/CLI.md:1337 (see Rejected)

• code: src/leasing/lease-acquisition-coordinator.ts:1119 lease.queued position is computed again from the depth getters; WaitQueue#enqueue already computes it, so the two can drift

• claims: src/core/domain.ts:251 and src/contract/schemas.ts:213 "see DriverDevice.address" points at a doc comment that was cut

• claims: docs/CLI.md:291 the bracket list omits mode, which --mode with --physical names

• code: src/leasing/physical-leasing.test.ts:454 the cancelled-waiter test also covers the post-grant wake

• claims: src/gateway/worker-registry.ts:122 #drained doc names its callers; :125 #viewsChangedListeners only points to another doc

• Equivalent mutants: operationPlan in src/leasing/lease-acquisition-coordinator.ts (the grant-ready and grant-physical disjuncts). #decide grants a grant-ready plan before it calls operationPlan, and a physical plan takes its own path, so neither kind reaches it; the checks only narrow the type.

Written by an agent.

[V3RON]

Review notes (after-pass)

• code: e2e/physical-devices-core.test.ts:202 the test still passes when the quarantine retry ignores the backoff

Written by an agent.