[addisdev]

Why

The Galaxy S8+ (988a1b3541354f565a) is about to be cabled to ultra and kept for one job: driving the Instagram app for the growth pilot (taylab-launch-kit#229, ui-test jobs pinned with targets.match to that id, targets.executor: ultra-phone, max_attempts: 1). Once ultra runs an executor, any other Android host job could claim that signed-in phone and open other apps on it: an ad hoc os ~ 'android', a fan-out, the explore night, or a schedule without a pin. Pools and matches can't stop that, because they describe what a job wants. A reservation describes what the device accepts.

What

• fleet device reserve <id> <label> [--note T] / fleet device unreserve <id>, backed by POST /api/v1/devices/{id}/reserve and /unreserve (admin scope). Reservations go in a new device_reservations table, not on the device row. That way a phone can be reserved before it is cabled up, and the reservation survives the registry forgetting the device.
• The rule (collector/src/reserved.ts, pure). A reserved device goes only to a job that has both:
  • "reservation": "<label>", a new top-level job field
  • a pin on the device: targets.device_id, or a targets.match that pins its id. "Pins" is tested by behaviour: the expression must match the device and must stop matching when its id (and a serial equal to it) is swapped for another. device_id == 'X' && … pins; device_id == 'X' || os ~ 'android' does not.
• Where it is enforced:
  • matchingDevices: fan-out and the composer preview
  • specEligibleFor: device-executor claims and preemption
  • executorsHolding: host routing, so an unpinned Android job no longer routes to ultra just because the reserved phone is attached there
  • the host executor's own selectTargets, which gets every reservation as reserved_devices in the /executor/next-job answer. This is a new optional protocol field, not stored on the job.
  • the web-shots Android-Chrome profile
• At the door: a job that pins a reserved device without its label is refused with the new error code device_reserved (409). Validate warns left out as reserved for other work: <id> (<label>), and fan-out's no_matching_devices names the reserved devices it left out.
• Visible: reserved_for on /api/v1/devices, a RESERVED column in fleet devices, reserved_for in fleet_devices, and fleet run --reservation LABEL. The skill tells agents to leave reserved devices alone.
• Fix found on the way: the executor described an Android target without device_id. So the kit's device_id == '<serial>' pin was routed to the right executor and then matched nothing there (skip, "no targets"). The executor's descriptor now includes device_id.

For the growth phone (kit #229)

fleet device reserve 988a1b3541354f565a growth-instagram --note "Instagram growth pilot, signed in"

and each job spec adds one top-level field:

{ "reservation": "growth-instagram",
  "targets": { "executor": "ultra-phone", "match": "device_id == '988a1b3541354f565a'", "exclusive": true },
  "lease": { "max_attempts": 1 } }

Tests

• cd collector && npm test: ALL PASS. The dashboard build ran too. New smoke section 41 covers reserve-before-register, conflicts, the shelf listing, fan-out with and without the label, validate warnings, device_reserved on both enqueue routes, host routing (the phone's executor skips the unpinned job and takes the growth job; the claim carries reserved_devices), a reserved device-executor agent, and unreserve. New src/reserved.test.ts covers the rule and the executor's selectTargets, including the device_id match fix.
• cd fleet && npm test: 82 pass, 2 skipped (pre-existing). New CLI test for reserve, list, conflict, the refused pin, a run with --reservation, and unreserve; the MCP fleet_devices test now checks reserved_for.
• mkdocs build --strict: clean.

Notes

• Based on main and opened against main as asked. CONTRIBUTING says feature branches come from develop, and develop is ahead (Explore: survive a dropped model, judge only missions that drove the app, fail fast on Xcode's first launch #101, Move the lab's brain to ultra #105). This branch doesn't touch those files apart from CHANGELOG.md's [Unreleased] section.
• Executors that predate this ignore reserved_devices, so the guard is only complete once ultra's brain and executors run this code.

🤖 Generated with Claude Code