Host ports leased with the device

Start by tracing the existing lease request and grant paths used by simlock lease, POST /v1/lease-requests, and MCP lease_simulator, including renew, release, gateway, and daemon restart behavior. Review the listed completion conditions and open questions before changing the shared request and grant model. Done requires coordinated CLI, API, MCP, persistence, allocation, status, gateway, and documentation changes across docs/CLI.md, docs/CONFIGURATION.md, docs/HTTP-API.md, docs/CLIENT.md, and both EVENTS.md files.

Request: #155

Problem

A lease isolates a device but not the host ports the work needs. Two agents on one machine start a dev server, a mock API, or a debug proxy on the same default port. The second start fails, or it talks to the first agent's server without noticing. Each agent picks ports on its own, so nothing stops the race. Today teams hand out port ranges by hand.

Who it is for

Parallel coding agents that build and run apps against Simlock devices on one machine: several agents on a local worker, or several CI jobs sharing one. Any app type: native iOS and Android, cross-platform frameworks, anything with a local backend.

Outcome

• A lease request can ask for a number of host ports. The grant lists them. A request that asks for none gets none, and nothing changes for existing callers.
• Every port in a grant comes from a configured range. No two live leases hold the same port. A port Simlock itself listens on, or hands to an emulator, is never in a grant.
• A port was not in use on the host when it was picked. What the holder runs on it afterwards is the holder's business.
• --export-env exports the ports as shell variables next to the existing ones, so a script gets its ports with no parsing.
• The same request field and grant field work over the unix socket, the HTTP API, and MCP.
• An Android emulator leased with ports can reach them on the host without the agent doing anything beyond starting its server. iOS simulators share the host's network, so localhost:<port> already works there.
• The ports are freed when the lease ends, however it ends: release, expiry, release --all, nuke, or a lost device. They stay with the lease across a daemon restart, as the lease does.
• simlock status and lease listings show each lease's ports.
• Through a gateway, the ports are on the worker that owns the device, the same as the rest of the grant's environment. The grant says so. Renew and release need no change.

Non-goals

• Knowing what runs on a port. Simlock does not start, stop, watch, or name the process. No bundler, framework, or tool is named in config, flags, output, or code.
• Forwarding a port between machines. Through a gateway or over HTTP the ports are reported, not tunnelled. That is the data plane the gateway design leaves out.
• Reaching a port on the device from the host (the other direction).
• Adding or changing ports after the grant. Ports are fixed for the life of the lease.
• Ports without a device. A port is only ever part of a device lease.
• Routing a fleet request by port availability. Routing is unchanged.

Completion conditions

• simlock lease --platform android --device 'Pixel 8' --detach --ports 2 prints a grant with two distinct ports inside the configured range. The same holds for --platform ios.
• lease_simulator over MCP and POST /v1/lease-requests accept the same field and return the same ports on the lease.
• Two leases granted at the same time never share a port. A port freed by one lease can be granted to the next.
• --export-env prints one export line per port next to the existing variables.
• A request that asks for no ports gets a grant that names none. simlock lease without the flag behaves exactly as on main.
• A port that another process was listening on when the lease was granted is not in the grant.
• With a server listening on a leased port on the host, a client inside the leased emulator reaches it. How it is addressed is open question 2.
• After simlock release, lease expiry, simlock release --all, simlock nuke, and a device lost mid-lease, every port of that lease is free for the next grant, and a server the holder left listening on it is still running.
• The ports are still on the lease after simlock daemon stop and simlock daemon start.
• simlock status and simlock lease list show each lease's ports.
• A configured range that overlaps http.port, drivers.android.adbServerPort, or the emulator console and adb ports is refused, naming the key. See open question 5.
• A request that asks for more ports than the range can give right now gets the answer in open question 3, never a partial grant.
• Through a gateway, a lease with ports is granted, renewed, and released, and the ports are freed on the worker when it ends.
• docs/CLI.md, docs/CONFIGURATION.md, docs/HTTP-API.md, docs/CLIENT.md, and both EVENTS.md files describe the field, the variables, the config keys, and any event change.

Open questions

1. Ask by count or by name? Recommended: a count (--ports <n>, ports: n), exported as SIMLOCK_PORT_1 to SIMLOCK_PORT_n. Names can be added later without breaking this.
2. How does the emulator reach a host port? (a) localhost:<port> inside the emulator reaches the host's port, set up by Simlock at grant and again when it reboots the emulator during crash recovery. (b) The grant names the emulator-side address (10.0.2.2:<port>) and the app has to use it. Recommended: (a). It is the only reading of "no extra steps", and the port number is the same on both sides.
3. When the range cannot serve the request: fail at once with a closed error code, or wait in the queue like device capacity? Recommended: fail at once. With the default range, exhaustion means misconfiguration, and waiting would need the gateway to track port availability per worker.
4. Defaults for the range and the per-lease cap? Recommended: 20000-20999 and at most 16 per lease, both configurable. That sits below the OS ephemeral range and above every port Simlock uses.
5. A range that overlaps Simlock's own ports: refuse at daemon start naming the key, or skip those ports at grant time? Recommended: refuse at start, as the other contradictory config pairs do.
6. Should the pick check the host for a listener, or only Simlock's own bookkeeping? Recommended: check the host, best effort. A server left behind by a previous holder is the common failure.
7. Through a gateway the ports are reported and not forwarded, as Non-goals say. Confirm.

Written by an agent.