Stream any running device to an operator by worker and device id #909

Part of #906.

Scope

An operator can stream the screen of any running device, leased or not, through GET /v1/stream/workers/{workerId}/devices/{deviceId}. A single worker answers it for its own id; a gateway relays it to the named worker. A stream keeps running when its device is leased, stops before the device is reset after a lease, and stops when the device stops running with no lease end (shut down, absent, quarantined, deleted). The lease route GET /v1/stream/leases/{id} stays until #910 moves the console off it and removes it. The slow-lane stream tests move to the new route.

In short

Today a picture is asked for by lease id, so a device with no lease has none. After this PR it is asked for by worker id and device id, by an operator only, and a ready or leased device answers with its picture. Any other device state answers 409.

flowchart LR
  C[Operator] -->|"GET /v1/stream/workers/w1/devices/d1 (new)"| G[Gateway]
  G -->|"relay /stream/devices/d1 (new)"| W[Worker]
  C -->|same path, w1 = its own id| W
  W -->|"state ready or leased? (new)"| D[Driver capture]
  L[Lease ends] -->|"reclaim hook: stop captures on its device (changed)"| D

Before and after, with an operator token on a worker whose id is w1:

$ curl -H "authorization: Bearer $OP" localhost:8787/v1/stream/workers/w1/devices/dev_ready
today: 404 {"error":{"code":"UNKNOWN_LEASE","message":"This path names no stream lease"}}
after: 200, simlock-stream-codec: h264, the frames

$ curl … /v1/stream/workers/w1/devices/dev_off        (state shutdown)
after: 409 {"error":{"code":"DEVICE_NOT_RUNNING","message":"The device is shutdown; only a ready or leased device streams"}}

"Running device": state ready (booted and idle, warm pool included) or leased.

If this goes wrong, a user would see the picture stop when an agent leases the device being watched, or a device reset while still being filmed.

Technical spec

Facts

Modules touched

Searches: rg "stream/leases|leaseIdOf|requireLease|captures.stop|createStreamLeaseEnd|WorkerContext|unknownLease|noSuchStream" over src, e2e, docs/internal, website/src/content/docs.

flowchart LR
  H[http app: module mount] --> M[stream/mounts, service *]
  M --> WL[stream/worker-link *]
  M --> GL[stream/gateway-link, gateway.ts *]
  WL --> CA[stream/captures *]
  WL --> R[core registry snapshot]
  WL --> DC[core DriverCatalog.openScreen]
  GL --> GR[gateway relay]
  MH[modules/types, host: WorkerContext.instanceId *] --> W[stream/worker.ts *]
  DM[daemon/main.ts *] --> MH

sequenceDiagram
  participant C as Operator
  participant G as Gateway stream
  participant W as Worker stream
  participant D as Driver
  C->>G: GET /v1/stream/workers/w1/devices/d1
  G->>G: role operator? worker w1 known?
  G->>W: relay.request url /stream/devices/d1, tenant gw:inst:principal
  W->>W: device d1 in registry? state ready or leased?
  W-->>G: 409 DEVICE_NOT_RUNNING (shutdown)
  G-->>C: 409 DEVICE_NOT_RUNNING, code kept
  W->>D: openScreen(platform, d1)
  D-->>W: meta, frames
  W-->>C: 200 frames (relayed unread)

Contract and event changes

• HTTP: route GET /v1/stream/workers/{workerId}/devices/{deviceId}, declared in src/stream/definition.ts beside the lease route. Statuses: 200 (the simlock-stream-* headers as today; no x-simlock-lease, which nothing reads: rg x-simlock-lease ui src finds only service.ts and definition.ts), 404 UNKNOWN_DEVICE and UNKNOWN_WORKER, 405 BAD_REQUEST, 409 DEVICE_NOT_RUNNING, 415, 500, 502, 503 as today. Path segments are URL-decoded.
• DEVICE_NOT_RUNNING is a stream refusal in src/stream/refusal.ts (codes there are free strings), added to that file's list of codes it raises; src/contract/errors.ts does not change.
• On the relay door the worker serves a device stream whatever the relayed tenant: the gateway already refused non-operators, and a relay comes only from a gateway's uplink session (ADR 0045 §2, F5). The role check is on the HTTP door only.
• WorkerContext gains instanceId: string (module contract, not the wire).
• The uplink's relay.request is unchanged (F6): the device route sends no leaseId.
• No protocol bump: no daemon contract shape changes. No events (ADR 0045 §6).

Other code on the same state

The capture registry and the device records. Searched rg "captures\.(begin|stop)|beforeDeviceReclaim|leaseEnded" src (8 hits) and rg "snapshot.devices" src/stream (2). Components:

• The reclaim hook (lease end): stops every capture on the ended lease's device, lease and device captures alike; the reclaim waits for those closes, as today. If a viewer opens a device stream while the hook runs, the device's state is already not leased and not ready (reclaiming), so it gets 409.
• The warm pool's shutdown, the reaper, doctor and a physical device going absent, quarantined or deleted: no lease end, so the module stops the device's captures on device.shutdown, device.absence-detected, device.quarantined or device.deleted (F14, F23, F24). The event follows the change, so a capture may run briefly on a stopped device; nothing here delays the shutdown.
• A lease granted while streaming: no hook runs; the stream keeps running.
• Console: watch a device from its drawer's Screen tab; the lease stream route goes #910 removes the lease route and its capture keying; this task keeps both working.

Failure modes

State: captures live in memory only; a restart ends every stream with its process. Two viewers on one device get two captures (ADR 0045 §5).

Rules in play

• ADR 0045 §1–§6: the route, operator only, running states, refusals, lifetime (including the four device events), no events emitted — this task builds all six on the server.
• ADR 0012 §1: "the worker itself" — the worker answers only its own instance id.
• ADR 0030: the stream stays an optional module; the new context field is added for every module.
• src/stream/AGENTS.md Rules: "Ownership before any work; unknown and not-yours answer the same" — role, worker and device are checked before a capture opens; an agent gets the same 404 for any device.
• documentation rule 9: website/src/content/docs/docs/using-devices/watching-the-screen.mdx:103 documents the device route and operator tokens; src/stream/AGENTS.md changes its route, its rule "a capture never outlives its lease" to "its device's running state", and its files table.

Tests

Seam: createWorkerStream and createGatewayStream through their mount and relay target (model: src/stream/create.test.ts, with TestRegistry gaining a device state), and the fast gateway e2e src/daemon/stream-gateway.e2e.test.ts.

• An operator asks a single worker for a device's stream: ready → 200 frames; leased → 200; shutdown, provisioning, reclaiming, quarantined, physical absent → 409 DEVICE_NOT_RUNNING with the state in the message; unknown device → 404 UNKNOWN_DEVICE; another worker id → 404 UNKNOWN_WORKER; driver cannot capture → 415; nothing opened for any refusal.
• An agent token asks for a device's stream: on a worker, for the device its lease holds → 404 UNKNOWN_DEVICE; through a gateway, same; nothing opened.
• An operator asks a gateway for a device's stream: relayed → 200 frames; unknown worker → 404 UNKNOWN_WORKER; disconnected worker → 503 WORKER_UNREACHABLE; the worker's 409 DEVICE_NOT_RUNNING and 404 UNKNOWN_DEVICE arrive with their codes.
• A watched device changes: a ready device is leased → the stream keeps sending frames; that lease ends → the capture is closed before the reclaim hook returns; the hook runs while the capture is still opening → 409, capture closed; device.shutdown, device.absence-detected, device.quarantined or device.deleted for the device → its captures stopped and the stream ends; the same event for another device → its stream untouched; the capture ends → the stream ends; the viewer aborts → the capture is closed once. Extends create.test.ts's "stops a relayed capture when its lease ends".
• A real unleased simulator streams, and keeps streaming when leased: slow lane, e2e/slow-ios-stream.test.ts — a warmPool.targets entry keeps one simulator ready with no lease (an iOS reclaim ends in shutdown, so lease-and-release cannot); it answers frames; a lease is granted for that kind mid-stream, the test checks the grant names the watched device id, and frames keep coming for 10 s; the other slow stream tests (F22) call the device route.

Done when

• pnpm test and pnpm test:e2e src/daemon/stream-gateway.e2e.test.ts pass, with the first four Tests lines.
• Slow lane: scripts/slow-e2e.sh e2e/slow-ios-stream.test.ts e2e/slow-android-stream.test.ts passes on this machine. The physical-device stream tests are moved to the device route; their run is not required (no phone on this machine).
• rg -l stream/leases e2e/slow-*.test.ts finds nothing.
• The OpenAPI document lists GET /v1/stream/workers/{workerId}/devices/{deviceId} with its statuses.
• watching-the-screen.mdx documents the device route, for operator tokens.

Out of scope

• Removing GET /v1/stream/leases/{id} and the console change (Console: watch a device from its drawer's Screen tab; the lease stream route goes #910).
• Sharing one capture between viewers (One capture per lease, shared by every viewer of its screen #602).
• Any change to how a physical iPhone captures.

Depends on

Written by an agent.