device.rotate: rotate a leased iOS simulator over the contract, HTTP and the client #1107

Part of #1105.

Scope

A holder rotates its iOS phone or tablet simulator lease with one call over the daemon contract, HTTP (POST /v1/leases/{id}/rotate) or the JS client, on a worker or through a gateway, whether or not capabilities.input.enabled is on. The per-lease device input moves into the daemon (ADR 0053), shared by the rotate and the input module's sockets, and DeviceInput.send returns a promise so a failed write is reported. The orientation list and alias parser the CLI, MCP and the agent-device front use ship here, in the contract. The watching-the-screen page describes the action.

In short

After this PR, an agent sends POST /v1/leases/<lease-id>/rotate with {"orientation":"landscape_left"} and its leased iPhone or iPad simulator turns, answering 200 {"leaseId":"<lease-id>","orientation":"landscape_left"} once the event is written to the input helper. Through a gateway, <lease-id> is always the id the agent holds. A lease on anything else answers 422 ROTATION_UNSUPPORTED with Lease <lease-id> is on <device>; only an iOS simulator can be rotated, <device> one of an Apple TV simulator, an Apple Watch simulator, an Apple Vision simulator, a <model> simulator (another iOS model), an Android emulator, an Android phone, an Android tablet, an iPhone, an iPad. A helper that cannot start, or a write that fails, answers 503 INPUT_UNAVAILABLE with Lease <lease-id>'s simulator cannot take input: <reason>, <reason> the driver's text cut to 200 characters. With an input socket open, its helper is reused.

flowchart LR
  C[HTTP / client / gateway] --> O[device.rotate - new]
  O --> R[daemon per-lease device input - moved here]
  S[input module socket] --> R
  R --> H[iOS input helper: 0x07, send awaited - changed]

$ curl -X POST -H "Authorization: Bearer $T" -d '{"orientation":"landscape_left"}' http://worker:7300/v1/leases/3f9c/rotate
404                                                    # before
{"leaseId":"3f9c","orientation":"landscape_left"}      # after
$ curl ... -d '{"orientation":"landscape-left"}' ...
400 {"code":"BAD_REQUEST", ...}                        # after: HTTP takes only the four names

If this goes wrong, a user sees an input socket lose its touches when a rotate runs at the same time, or a rotate that answers 200 but never turns the simulator.

Technical spec

Facts

Commit 795733b.

Modules touched

Searches: openInput, createInputSessions, send(message, device.exec, INPUT_ORIENTATIONS, LEASE_ROUTES, beforeDeviceReclaim across src/.

• src/contract/ — orientation.ts (the four names, the alias table, parseOrientation, the unknown message, isRotatableModel and modelFamily; added to NOT_SHAPES), device.rotate, two error codes, protocol bump, matrices.
• src/core/ — INPUT_ORIENTATIONS reads the contract's list; DeviceInput.send returns Promise<void>; the fake device input.
• src/drivers/ios/input/, src/drivers/android/input/ — send returns the write's promise (Android: resolves once the packet is written, at once for a dropped kind).
• src/daemon/ — the per-lease device-input registry, the device.rotate handler, closing at lease end, ctx.inputs handing modules the lease's shared input.
• src/modules/ — ModuleInputs gains leaseInput(leaseId, platform, device) returning the lease's shared input handle (by-shape type and its type test).
• src/input/ — sessions take the lease's input from ctx.inputs.leaseInput; worker.test.ts's fake follows.
• src/gateway/ — device.rotate handler, coordinator forward, mapping the worker's lease id back to the caller's.
• src/http/ — the route declaration and handler.
• src/simlock-client/, src/client/ — rotate and its types.
• website/ — errors reference, HTTP reference, watching-the-screen.

flowchart LR
  http[http*] --> daemon[daemon dispatcher*]
  gateway[gateway*] --> daemon
  client[simlock-client*] --> daemon
  daemon --> reg[daemon device inputs*]
  input[input module*] --> reg
  reg --> catalog[core driver catalog]
  catalog --> drivers[drivers input send*]
  daemon --> contract[contract*]

sequenceDiagram
  participant A as Agent
  participant G as Gateway
  participant W as Worker
  participant H as iOS helper
  A->>G: POST /v1/leases/w1.3f9c/rotate {orientation}
  G->>W: device.rotate {3f9c, orientation, requesterId: gw:..:agent}
  W->>H: 0x07 {orientation} (send awaited)
  W-->>G: {leaseId: 3f9c, orientation}
  G-->>A: 200 {leaseId: w1.3f9c, orientation}
  Note over W,A: open or write fails: 503 INPUT_UNAVAILABLE; not a phone/tablet simulator: 422 ROTATION_UNSUPPORTED; both name w1.3f9c; worker gone: 503 WORKER_UNREACHABLE

Contract and event changes

This PR bumps the protocol by one.

• device.rotate: input {leaseId: string, orientation: one of F1, requesterId?: string} (leaseId, requesterId bounded as device.exec's); output {leaseId, orientation}; role agent; effect write; authorize as device.exec (F13). Any other orientation string, an empty one, or a missing one is BAD_REQUEST.
• ROTATION_UNSUPPORTED: 422, exit 12, details {leaseId, platform: "ios"|"android", physical: boolean, class: string}; class is the physical class (phone, tablet), the simulator's modelFamily (tv, watch, vision, unknown), or emulator. A simulator is rotatable when isRotatableModel(spec.model): the model starts with iPhone or iPad (F16, F26); any other model, an unknown one included, is refused without a catalog read.
• INPUT_UNAVAILABLE: 503, exit 1, details {leaseId, reason}; reason 1 to 200 characters, the factory's unavailable text or the open's or write's error message, cut; unknown error when that text is empty.
• src/contract/orientation.ts is a helper with no wire shape of its own, listed in NOT_SHAPES.
• No event (F23; EVENTS.md unchanged).

Other code on the same state

Searches: openInput( (3 hits outside tests), .send( on a device input (2: src/input/sessions.ts, the fake), sockets.size (1), beforeDeviceReclaim (5).

• Input module sessions (src/input/sessions.ts): a user of the shared input. A rotate during an open socket uses the same input and does not close it; a socket that opens while a rotate is in flight joins it; the last of either to finish closes it. A socket's send catches and drops the promise's rejection, so it is never unhandled (F27); the failed write still reaches the sockets through onFailed, which closes them 1013, as today.
• onFailed on the shared input: the registry drops it and every socket closes 1013, as today; a rotate in flight gets INPUT_UNAVAILABLE; the next user opens a fresh input.
• Lease end: the registry closes the lease's input from its own lease-end participant, not ordered against module hooks (F12). A rotate whose open is pending when the lease ends answers UNKNOWN_LEASE and sends nothing.
• Stream and agent-device modules: do not touch device input.

Failure modes

A daemon restart mid-rotate leaves no state: the registry is memory only and the helper is a child. Two rotates at once share one open and both send, in arrival order.

Rules in play

• ADR 0053 §1-6 (PR docs(adr): 0053 the daemon owns each lease's device input, and device.rotate uses it #1106): "The daemon keeps one device input per lease" — the registry and op follow it.
• ADR 0052 §4: "0x82 keeps saying portrait" — unchanged.
• ADR 0049 §4 narrowed by 0053: "A lease has one device input" stays true; it is now the daemon's.
• Contract "Adding an operation" steps 1-8 (src/contract/AGENTS.md); "One OS grammar ... one duration parser. Nobody else parses" — one orientation parser, in the contract.

Tests

Seam: daemon dispatch over the socket with a fake input factory, modelled on src/daemon/input-lease.e2e.test.ts; HTTP on src/http/core-routes.test.ts; the client on its existing exec test.

• A holder calls device.rotate on its iOS-simulator lease and gets {leaseId, orientation}; the helper received 0x07 with that orientation; cases: each of the four names; input module on with a socket open (its helper is reused, no second open); input module off (helper opened, then closed).
• A caller rotates a lease it may not touch, or names a bad orientation, and is refused; cases: unknown lease id → UNKNOWN_LEASE; another requester's lease → FORBIDDEN; an agent naming a requesterId → FORBIDDEN; admin naming a requesterId that is not the lease's → FORBIDDEN; landscape-left, auto, empty → BAD_REQUEST.
• A holder rotates a lease not on an iOS phone or tablet simulator and gets ROTATION_UNSUPPORTED naming it; no helper starts; cases: Apple TV simulator; an iOS simulator model with no known family (a <model> simulator); Android emulator; Android phone; iPhone; an iPad simulator rotates.
• A holder rotates when the helper cannot start or the write fails and gets INPUT_UNAVAILABLE with the reason; cases: no input factory for the platform; helper open rejects; write rejects; a helper that failed earlier is replaced by a fresh one; a socket's failed write closes it 1013 and the daemon keeps running.
• An input socket opened after a rotate's helper closed gets a fresh helper; a socket open during a rotate keeps its helper after the rotate answers; cases: socket opens after; socket open during; lease reclaimed while the rotate's open is pending → UNKNOWN_LEASE, nothing sent.
• An agent calls POST /v1/leases/{id}/rotate on a worker and through a gateway and gets 200 {leaseId, orientation}, or the error code's status; cases: worker ok; gateway ok (forwarded to the worker's lease id, answered with the caller's); gateway ROTATION_UNSUPPORTED and INPUT_UNAVAILABLE name the caller's lease id; unknown lease 404; Android 422; helper missing 503.
• A client program calls client.rotate(leaseId, orientation) and gets the op's output; cases: ok; ROTATION_UNSUPPORTED thrown as a typed error.
• The core alias parser maps a spelling to an orientation or the unknown message; cases: every row of the feature's Examples table.

The socket behaviours src/input/worker.test.ts and src/daemon/input-lease.e2e.test.ts prove today stay proven: their assertions keep their meaning, with worker.test.ts's fake inputs moved to leaseInput (F11).

Done when

• The Tests lines pass; src/input/worker.test.ts and src/daemon/input-lease.e2e.test.ts pass with only the fake's shape changed.
• operations.test.ts's role and effect matrices hold device.rotate.
• The errors reference lists both codes; the HTTP reference lists the route; watching-the-screen says rotation is also POST /v1/leases/{id}/rotate, with the input module off.

Out of scope

• The CLI command and MCP tool (simlock rotate and MCP rotate_device #1108); the agent-device front (The agent-device front answers orientation on an iOS-simulator lease #1109).
• Android rotation; reporting the orientation in 0x82.

Depends on

• docs(adr): 0053 the daemon owns each lease's device input, and device.rotate uses it #1106

Written by an agent.