A lease holder streams its lease's screen #1015

Part of #1013.

Scope

A lease holder watches its own lease's screen with its agent token, on a standalone worker and through a gateway, at GET /v1/leases/{id}/stream. Every stream that a lease end stops now says why in its last frame, and the console shows that reason. This task also adds the lease route seam (Shared values: Lease route on #1013) that #1017 reuses.

In short

An agent token can now open GET /v1/leases/L-42/stream for a lease it owns and get the same frames the device route gives an operator (F1, F7). Another agent's lease and an unknown lease answer 404 UNKNOWN_LEASE with Unknown lease: <id>, as GET /v1/leases/{id} does (F3, F19). When the lease ends, the last frame on every stream of that device is a new tag 0x07 holding {"reason":"explicit"} (or killed, expired, device-lost), then the body ends. A leased phone that drops off also gets device-lost. The console says why, in the words of Shared values: ended frame on #1013, and not as an error.

flowchart LR
  C[Caller, agent token] --> H["http: /v1/leases/{id}/stream (NEW)"]
  H -->|lease.get: owner or operator, else 404| S[stream module lease handler NEW]
  S -->|worker| Cap[captures by device]
  S -->|gateway: relay with leaseId| W[worker relay target /stream/leases/<workerLeaseId> NEW]
  W --> Cap
  E[lease ends] -->|0x07 frame, then end CHANGED| Cap

Before and after, through a gateway:

$ curl -s -H "Authorization: Bearer $AGENT" https://gw:7480/v1/leases/L-42/stream -o /dev/null -w '%{http_code}\n'
404                                   # before: no such route
200                                   # after: the lease's picture
$ curl -s -H "Authorization: Bearer $OTHER_AGENT" https://gw:7480/v1/leases/L-42/stream
{"error":{"code":"UNKNOWN_LEASE","message":"Unknown lease: L-42"}}

If this goes wrong, a user would notice an agent seeing another agent's screen, or a picture that stops with no reason.

Technical spec

Facts

Commit e1f2f43.

Modules touched

Searches: mount.prefix, HttpMount, ModuleMount, beginOnDevice, stopOnDevice, relayedDeviceTargetOf, SCREEN_FRAME_TAG, onEnd( across src/, ui/src/ and website/.

• src/http/app.ts: the lease route: /v1/leases/{id}/<module name> for each loaded module that has a lease handler, behind agentAuth; resolves the lease with lease.get (F3), then calls the handler with (request, identity, lease).
• src/modules/types.ts, src/modules/host.ts: WorkerModule.leaseRoute and GatewayModule.leaseRoute, collected like mounts (F2). The host refuses to load a module whose name is a core lease sub-route (renew, exec), as it refuses a name that clashes with a core first segment; the core route wins (decided in delivery, pending the maintainer).
• src/stream/: the lease handler on worker and gateway, the relayed path /stream/leases/<workerLeaseId>, the ended frame on lease end, the route declaration.
• src/core/screen.ts: tag ended: 0x07.
• ui/src/data/stream.ts: on 0x07, onEnd with the reason.
• src/stream/AGENTS.md, src/http/AGENTS.md, website pages in F17.

flowchart LR
  http[http app CHANGED] --> host[modules host CHANGED]
  host --> stream[stream module CHANGED]
  stream --> screen[core/screen CHANGED]
  ui[console stream reader CHANGED] --> screen
  stream -->|gateway relay| relay[gateway relay]

sequenceDiagram
  participant C as Agent
  participant G as Gateway http
  participant SG as stream (gateway)
  participant W as Worker stream
  C->>G: GET /v1/leases/L-42/stream
  G->>G: lease.get L-42 for the caller
  alt not the caller's, or unknown
    G-->>C: 404 UNKNOWN_LEASE
  else
    G->>SG: leaseRoute(request, identity, lease)
    SG->>W: relay /stream/leases/w1-7 (leaseId w1-7)
    alt lease gone on the worker
      W-->>C: 404 UNKNOWN_LEASE
    else worker unreachable
      SG-->>C: 503 WORKER_UNREACHABLE
    else
      W-->>C: frames … 0x07 {"reason"} , end
    end
  end

Contract and event changes

None: no src/contract/ shape changes (searched src/contract for stream, lease.get). The HTTP surface gains GET /v1/leases/{id}/stream, declared in src/stream/definition.ts so the OpenAPI document lists it (F18), with 200 (the stream's content types and headers, as the device route), 404 UNKNOWN_LEASE, 409 DEVICE_NOT_RUNNING, 415 STREAM_NOT_SUPPORTED, 500 INTERNAL, 502 and 503 as the device route. The ended frame payload is JSON {"reason": string}, one of the four values in F8, at most 64 bytes; a reader that cannot parse it ends with no reason. No event changes.

Other code on the same state

Searches: stopOnDevice (3 hits: captures.ts, create.ts, captures.ts lease end), beginOnDevice (2 hits: captures.ts, worker-link.ts), registry.snapshot.leases in src/stream (0 hits).

• Device-stop events (F9) and lease end (F7) both call stopOnDevice. Lease end writes 0x07 with its reason, then ends. device.absence-detected with previousState: "leased" also writes 0x07 {"reason":"device-lost"}: on that path the lease end is already committed and its participants run after the event (F20). Every other device stop ends with no frame. A slot already stopped writes nothing more, so the lease end that follows an absence adds no second frame.
• The device route and the lease route share the capture table by device: a lease end stops both, as today.
• A lease route open races its own lease end: the handler registers its slot (beginOnDevice) first, then checks the lease is still in registry.snapshot.leases (F16), then opens. A lease that ended before the check answers 404 UNKNOWN_LEASE; one that ends after is stopped by stopOnDevice with the 0x07 frame.
• Input socket for a lease #1017 adds a lease socket on the same lease route path resolution (Shared values: Lease socket on Let a lease holder watch and interact with its device's screen #1013).

Failure modes

State written: none persisted. A daemon restart ends every stream as today.

Rules in play

• Architecture rule 10, "A rule is enforced in exactly one place": the ownership check lives only in the http lease route (lease.get); the stream module never checks owners.
• Architecture rule 15, "Dependencies point from the optional to the required": http knows only module names and a lease handler, never stream.
• Architecture rule 21, "A host never names an implementation": the lease route matches a loaded module's name, with no stream literal in src/http.
• Documentation rule 9, "A change to the public surface updates the website in the same change": the pages in F17 and the OpenAPI declaration (F18).
• ADR 0045 §4 (lifetime) stays; ADR 0049 §1, §2 and §6 are what this task builds.

Tests

Seam: src/daemon/stream-gateway.e2e.test.ts (a real gateway and worker over HTTP, the screen faked), extended with a standalone worker daemon; the console row on ui/src/data/stream.test.ts. The "lease gone on the worker" case cannot be held open between two real daemons (the gateway's own lease.get answers first once its view refreshes), so it runs in src/stream/gateway-link.test.ts with a relay that answers as that worker; its 404 message names the gateway lease id. The device-lost cases drive both F20 (a phone marked absent) and F21 (the health monitor).

• A caller GETs /v1/leases/{id}/stream on a standalone worker and gets the picture or a refusal: own lease 200; another's 404 UNKNOWN_LEASE; unknown 404; operator 200; stream capability off 404.
• A caller GETs /v1/leases/{id}/stream on a gateway and gets the lease's worker's picture or a refusal: own lease 200; another's 404 UNKNOWN_LEASE; worker unreachable 503 WORKER_UNREACHABLE; worker without the stream module 503 STREAM_UNAVAILABLE; lease gone on the worker 404 UNKNOWN_LEASE; and, at the worker's own stream lease handler, a /stream/leases/<id> request for a lease missing from the worker's registry answers 404 UNKNOWN_LEASE (decided in delivery, pending the maintainer).
• A viewer of either stream route sees a 0x07 frame with the reason, then the end, when the lease ends: explicit, expired, killed; device-lost by the health monitor and by physical absence; lease route and device route; a device that was not leased going absent writes no 0x07 frame (decided in delivery, pending the maintainer). The 0x07 cases may run at the stream module's surface (src/stream/create.test.ts) where the device-lost cases need a real health monitor or enrolled phone (decided in delivery, pending the maintainer).
• A module whose name is a core lease sub-route (renew, exec) is refused at load, and POST /v1/leases/{id}/renew still renews (decided in delivery, pending the maintainer).
• A console viewer sees why the picture stopped when a 0x07 frame arrives: 0x07 with a reason (each of the four shows its Shared values text, and the stream's error stays empty); an unknown tag is still skipped.

The tag pin in ui/src/data/stream.test.ts:625 (F13) covers the new tag in both tables.

Done when

• pnpm test passes with the five tests above.
• The OpenAPI document lists GET /v1/leases/{id}/stream with its statuses.
• watching-the-screen.mdx and access-control.mdx say a lease holder can watch its own lease, and how a stream ends.
• src/stream/AGENTS.md and src/http/AGENTS.md describe the lease route.

Out of scope

• Input (Input socket for a lease #1017, Android input through scrcpy's control channel #1018, iOS simulator input through the HID injector #1019).
• Sharing one capture between viewers (One capture per lease, shared by every viewer of its screen #602).
• A 0x07 frame for ends other than a lease end (device shutdown, quarantine, delete, capture error).
• A worker of an older Simlock behind a newer gateway (Failure modes).

Depends on

Written by an agent.