Lease limit per platform: one iOS and one Android per agent #961

Request: #947

Problem

lease.maxPerRequester is one number for all platforms, default 1. An agent asked to fix a bug on iOS and Android leases the iPhone, then fails on the Pixel with REQUESTER_ALREADY_LEASED (exit 13). The docs' only answer is "ask the operator to raise lease.maxPerRequester", which also lets one agent take two iPhones and starve the queue.

The limit should be configurable per platform, so an operator can say "one iOS and one Android per agent" without allowing two of either.

Who it is for

The operator of a Simlock worker or gateway whose agents test one change on iOS and Android at once, for example a React Native team. It serves every agent kind that leases through the CLI, MCP or HTTP. Under Claude Code a session and its sub-agents share one requester, so this limit is also what lets two sub-agents hold an iPhone and a Pixel at the same time.

agent-device users already get this today: each agent-device session is its own requester and holds one device, so iOS and Android are two sessions. This feature changes nothing on that path; it corrects the docs that say otherwise.

Outcome

• An operator sets lease.maxPerRequester to {"ios": 1, "android": 1}. One requester then holds one iOS and one Android lease at once. A second iOS request is refused, and so is a second Android one.
• A requester may also wait for an iOS device and an Android device at the same time. Cancelling one (an aborted programmatic-client call, or DELETE /v1/lease-requests/{id}) cancels only that request. simlock lease cancels nothing on Ctrl-C, as today.
• The refusal says which platform's limit was hit and names the lease that holds it.
• A config with a number keeps today's meaning: that many leases across all platforms. Nobody has to change a config.
• The same holds through a gateway, counted across the fleet.

How it works for the user

flowchart TD
  A["agent: simlock lease --platform android"] --> B{"held + waiting on this scope<br/>≥ the scope's limit?"}
  B -- no --> C{"a request on this platform<br/>already waiting?"}
  C -- no --> Q[queue → grant]
  C -- yes --> W["exit 13: already has a waiting Android request"]
  B -- "yes, held ≥ limit" --> H["exit 13: already holds Android lease &lt;id&gt;"]
  B -- "yes, held < limit" --> W2["exit 13: waiting-request message"]

The scope is the request's platform when the limit is an object, and every platform when it is a number.

Operator, before and after:

$ simlock config set lease.maxPerRequester '{"ios":1,"android":1}'
$ simlock daemon stop && simlock daemon start

Agent, today with the default limit 1:

$ simlock lease --platform ios --json        # granted lease-a
$ simlock lease --platform android --json
Requester claude-code:5f1c already holds lease lease-a; release it (`simlock release lease-a`) before requesting another device
$ echo $?
13

Agent, after, with {"ios":1,"android":1}:

$ simlock lease --platform ios --json        # granted lease-a
$ simlock lease --platform android --json    # granted lease-b
$ simlock lease --platform ios --json
Requester claude-code:5f1c already holds iOS lease lease-a; release it (`simlock release lease-a`) before requesting another iOS device
$ echo $?
13

Examples

What a request gets. "Holds" and "waits" are the same requester's leases and requests.

Config values:

What could go wrong

• An agent cancels its Android request and its iOS request is cancelled instead. Likely only if cancel is not narrowed to the platform; a test covers it.
• A gateway counts a requester's fleet leases by the wrong platform and lets two iPhones through. Unlikely; a gateway test covers it.
• An operator writes simlock config set lease.maxPerRequester.ios 2 over a number and silently gets Android 1. Rare; the docs show the JSON form.

Words used

• requester: the identity a lease is counted against, e.g. claude-code:<session id>, an HTTP token's id, or SIMLOCK_AGENT_ID.
• scope: the leases a limit counts. The request's platform when lease.maxPerRequester is an object; every platform when it is a number.
• waiting request: a lease request admitted but not yet granted or refused.
• physical lease: a lease on an enrolled phone (simlock lease --physical). It counts against its platform: an iPhone is iOS.

Non-goals

• No per-token cap on agent-device sessions. Each agent-device session stays its own requester holding one device.
• No total cap on top of the object form (for example "two devices, at most one per platform").
• No separate limit for physical devices.
• No change while the daemon runs: a new value applies after a restart, like every other config key.
• No per-requester or per-token overrides.

Completion conditions

• With {"ios":1,"android":1} on a worker, one requester is granted an iOS and an Android lease at once, and a second iOS request fails with exit 13 and a message naming the iOS lease.
• With {"ios":1,"android":1}, one requester waits for iOS and Android at once; cancelling the Android request leaves the iOS request waiting.
• With a number, or with no value, every case in the Examples table gives its "After" result.
• The same holds through a gateway, counted across its workers.
• Every website page that describes the limit describes the new shape, and none says an agent-device token holds one lease at a time.

Open questions

Decisions

• No ADR. ADR 0005 §14 keeps the count fleet-wide on a gateway; the number in it was already made configurable by lease.maxPerRequester without amending it.
• Both config forms, number means total (maintainer, 2026-10-23).
• A waiting request counts against its own platform only, at most one waiting per platform per requester; lease.cancel takes an optional platform (maintainer, 2026-10-23).
• agent-device keeps one requester per agent-device session; the docs are fixed (maintainer, 2026-10-23; one agent-device session holds one device, decided 2026-10-16).
• Taken on recommendation, listed for approval: a platform missing from the object gets 1; a physical lease counts against its platform (a physical request carries its platform, src/contract/schemas.ts:349-356); the refusal names the platform under the object form and keeps today's text under the number form; a change applies on restart.

Shared values

Behaviours

Tasks

One task: the gateway runs on leasing's WaitQueue and on the same config type, so a worker-only PR would change the gateway half-way.

• Per-platform lease limit per requester, on a worker and a gateway #966 Per-platform lease limit per requester, on a worker and a gateway — an operator sets {"ios":1,"android":1} and one agent holds an iPhone and a Pixel, never two of either, directly or through a gateway. Risk: a requester gets a second device of one platform, or cancelling one waiting request cancels the other.

Every Completion condition → #966.

Open work in the same area:

• One command installs the agent rules where agent tools read them #157 / Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 (PR feat(cli): simlock instructions prints the rules an agent must follow #960), agent instructions: says the operator decides the limit; line 55 "you already hold a lease" stays true per platform. No Depends on; a note goes to One command installs the agent rules where agent tools read them #157.
• fix(daemon): status.get shows an agent only its own leases and queue entries #893, fix(daemon): exec children get a minimal environment; docs say what an agent token can do #891 (open PRs) edit lease-lifecycle.mdx, remote-agents.mdx, access-control.mdx: same pages, different lines; the second to merge rebases. No Depends on.
• A standalone worker writes a private agent-device profile for local agents #956 (PR feat(modules): a standalone worker writes a private agent-device profile for local agents #963), A standalone worker serves agent-device on localhost by default #957 (local agent-device) rewrite using-devices/agent-device.mdx; Per-platform lease limit per requester, on a worker and a gateway #966 adds one sentence near :22. The second to merge rebases. No Depends on.
• A request waits only behind requests for the same platform #387 (one waiting line per platform): a queue-order change, not admission. No Depends on.
• device.exec fills in the lease's device and refuses another #958 / MCP: run_on_device runs a command on the session's lease #959 (MCP run_on_device): uses the session's lease; the default limit is unchanged. No Depends on.

Written by an agent.