Proxy lease by device spec: --os and --image-tag, honoured or refused by the backend

Start with the proxy lease flow and the exported keys beside LEASE_ALLOCATE_PROVIDER_FLAG_KEYS in packages/contracts/src/lease-scope.ts; trace how LeaseAllocateOptions and the MCP open schema carry allocation options. Use the completion conditions to map the required proxy, daemon, live-lease, and documentation changes. Done means the listed behaviors, schemas, remote-proxy docs, help text, and ADR amendment are complete; an open linked pull request (#3865) already covers this work.

Purpose

open through connect proxy already allocates by spec: without --udid/--serial it sends platform, target, device, and the backend picks the device (#3487). Simlock, as the backend, can also pick by OS version and Android image tag. This adds those two keys to the proxy lease, and makes a backend that cannot honour them refuse instead of silently ignoring them.

Simlock side: callstackincubator/simlock#814.

Flow

sequenceDiagram
    participant CLI as agent-device CLI
    participant B as backend (simlock front)
    participant D as agent-device daemon
    CLI->>B: lease.allocate {leaseId, platform, target, device?, osVersion?, imageTag?}
    alt backend consumes the spec
        B->>B: pick device by spec (validate os grammar, class, tag)
        B->>D: lease.allocate {leaseId, udid|serial, ttlMs} (spec keys stripped)
        D-->>B: lease {deviceKey}
        B-->>CLI: lease {deviceKey, device: {model, osVersion, imageTag?}}
    else plain daemon receives a spec key
        D-->>CLI: UNSUPPORTED_OPERATION reason device-spec-unsupported, keys: [...]
    else backend older than this feature
        B-->>CLI: lease {deviceKey} without device facts
        CLI->>B: lease.release
        CLI-->>CLI: fail: device-spec-unsupported
    end

Wire

New keys on agent_device.lease.allocate, one exported list beside LEASE_ALLOCATE_PROVIDER_FLAG_KEYS in packages/contracts/src/lease-scope.ts, also on LeaseAllocateOptions:

Echo on the returned lease (data.lease.device), written by the backend that honoured the request:

deviceKey stays the identity. lease.device is the proof the spec was understood.

Rules

• Flags on open, install, reinstall, uninstall; connect proxy stores them as defaults like platform and device.
• --target stays the class selector (mobile, tv, desktop); the backend maps it. No --device-class.
• A daemon that receives either key on an allocate refuses: UNSUPPORTED_OPERATION, details.reason: 'device-spec-unsupported', details.keys. Local daemon and plain agent-device proxy included. No partial honouring.
• A lease returned without lease.device after a request that named a spec key: the CLI releases it and fails with the same reason.
• A live lease serves a later open only when its spec matches the request's; otherwise CONNECTION_DEVICE_CONFLICT.
• Keys are agent-visible in MCP and the SDK schemas (not operatorField).
• No --allow-download, --mode, lease-wait: downloads and mode are backend config.
• Decision recorded as an amendment to ADR 0007, no new ADR.

Example

agent-device connect proxy --daemon-base-url http://worker:7700/v1/agent-device
agent-device open MyApp --platform ios --device "iPhone 17 Pro" --os ">=26"
agent-device open MyApp --platform android --os 34 --image-tag google_apis_playstore
agent-device open MyApp --platform ios --os ">=26"   # local daemon
# Error: UNSUPPORTED_OPERATION device-spec-unsupported (keys: osVersion)

open --json prints lease.device.

Completion conditions

• open --os/--image-tag through a proxy sends the keys on allocate; devices.list is not called first.
• A fake backend that echoes lease.device → open succeeds and reports the granted model and OS.
• A fake backend that returns no lease.device → the lease is released, open fails with device-spec-unsupported.
• Local daemon and agent-device proxy refuse the keys with the typed reason; the lease registry records nothing.
• Second open with a different --os on a live lease → CONNECTION_DEVICE_CONFLICT.
• MCP open tool schema and LeaseAllocateOptions carry the two keys; remote-proxy.md and help remote document them.
• ADR 0007 amended.

Postponed

--physical was in the first cut and is dropped (Decision comment below): neither phone reaches the daemon simlock runs today (iOS: the daemon-wide simulator set hides physical devices in agent-device's inventory; Android: phones sit on the default adb server, the daemon on simlock's). Simlock will spec a phone path on its side first.

Sequencing

1. This issue (agent-device release).
2. Simlock front maps the keys and echoes lease.device (callstackincubator/simlock#814).