Console: watch any device's screen, and layout fixes from the 2026-10-23 review #906

Request: none

Problem

In the console, a device's live screen is shown on the lease, not on the device. A device with no lease, such as an idle or warm-pool simulator, cannot be watched at all. An operator looking at a device has to find its lease first. The stream's numbers (frame rate, bandwidth, dropped frames) sit under the picture all the time, though they only matter when something looks wrong.

The same review of the console found layout faults. The page shifts sideways when a scrollbar appears. The worker page has a "Fleet" link the sidebar already gives. The warm-pool tab runs its summary into its table with no line between them. The worker's Events tab shows only the last hour, does not fill the page and cannot load older events. Several boxes are cramped or overlap: the row ⋯ button in the fleet table, the Inbox row buttons, the toast's close button, and a ⋯ list that repeats the button beside it.

Who it is for

An operator using the console, on a single worker or on a gateway, who wants to see what a device is showing, whether or not an agent holds it.

Outcome

• The operator opens any device in the console and watches its screen, leased or not.
• The picture keeps running when an agent leases the device.
• The stream's numbers are one click away, not always on screen.
• The worker page's Events tab shows that worker's whole history, scrolling back as far as it is kept.
• The layout faults listed above are gone.

How it works for the user

flowchart TD
  A[Fleet → worker → device row] --> B[Device drawer opens on Details]
  B --> C{Screen tab}
  C -->|device ready or leased| D[Picture starts by itself]
  C -->|device not running| E["Sentence: why there is no picture"]
  E -->|device becomes ready| D
  C -->|streaming off on the worker| F["Streaming is off on <worker>."]
  D --> G[ⓘ opens the stream numbers]
  D -->|leave the tab or close the drawer| H[Picture stops]
  D -->|device reset after a lease, or shut down| I[Picture ends, the tab says why]

Before: Leases → a lease → Screen tab → Show screen. A device with no lease has no screen anywhere.

After: Fleet → a worker → a device → Screen tab. The lease drawer has no Screen tab.

Examples

Who may watch, and what they get, through GET /v1/stream/workers/{workerId}/devices/{deviceId}:

GET /v1/events?worker=<id>:

What could go wrong

• The picture freezes or ends when an agent leases the device being watched. Unlikely; a test covers it on a real simulator.
• A device is erased while still streaming to the console after its lease ends. Unlikely; the reset stops the stream first.
• A picture freezes, still marked live, after its idle device shut down. Unlikely; the worker stops the stream when the device stops running.
• The Events tab on a busy gateway loads slowly. Possible on a large history; it reads 100 events at a time.
• A layout fix moves something else on the page. Possible; the browser tests measure each box.

Words used

• Running device: a device in state ready (booted and idle, warm pool included) or leased. Only a running device streams.
• Fleet of one: a single worker answers fleet routes as if it were a gateway with one worker, itself. Its worker id is its instance id, as GET /v1/workers shows it.
• Device drawer: the panel that opens over the worker page when you select a device row.
• Stream numbers: Picture, Frames, Rate, Bandwidth and Dropped, today shown under the picture.

Non-goals

• Sharing one capture between several viewers (One capture per lease, shared by every viewer of its screen #602). Each viewer is still its own capture.
• Letting an agent token watch a screen. Streams are for operators.
• A --worker flag on simlock events, or a worker filter on the MCP tools.
• Booting a shut-down device to watch it.
• Any change to how a physical iPhone captures (ADR 0031).

Completion conditions

• On a gateway and on a single worker, an operator opens a ready device with no lease, picks Screen, and sees its picture.
• While the picture runs, an agent leases that device, and the picture keeps running.
• After that lease ends, the picture stops before the device is reset.
• An agent token gets 404 UNKNOWN_DEVICE from the stream route, for its own leased device too.
• GET /v1/stream/leases/{id} answers 404 and the lease drawer has no Screen tab.
• The ⓘ button shows the stream numbers; they are not under the picture.
• The worker page's Events tab fills the page and scrolls back to the oldest kept event of that worker, or to the console's event cap.
• The layout checks in the layout task pass in the browser lane.

Open questions

None.

Decisions

• ADR 0045 — A device's screen streams to operators, not a lease's (PR docs(adr): 0045 a device's screen streams to operators, not a lease's (#906) #908): the one route shape, operators only, running devices only, the refusal codes, and when a stream ends (viewer, capture, a lease end before reset, or the device stopping running). Numbered 0045 because PR docs(adr): 0044 the console reads what its page shows, and events mark it stale (#905) #907 holds 0044.
• ADR 0012 — A worker answers the fleet operations as a fleet of one: why a single worker answers the same /v1/stream/workers/{workerId}/… path, for its own id.
• Interview, 2026-10-23: the lease route is removed outright (nothing published uses it); the device drawer gets Details and Screen tabs, Details first; the picture starts when the Screen tab opens and stops when it closes, with no button; a not-running device keeps the tab and says why, and starts by itself when it becomes ready; the lease drawer loses its Screen tab with no link in its place; the worker filter is on GET /v1/events only, fleet of one on a worker; a ⋯ list never repeats the button beside it, anywhere; toasts are two columns with a borderless close button; the slow lane moves the stream tests to the device route and adds one "survives a lease" case on an iOS simulator.

Shared values

Behaviours

Tasks

flowchart LR
  T09["#909 device stream route"] --> T10["#910 console Screen tab on the device"]
  T11["#911 worker events history"]
  T12["#912 layout fixes"]

• Stream any running device to an operator by worker and device id #909 Device stream route — an operator can stream any running device through GET /v1/stream/workers/{workerId}/devices/{deviceId}, on a worker and through a gateway. Risk: a stream stops when its device is leased.
• Console: watch a device from its drawer's Screen tab; the lease stream route goes #910 Console Screen tab on the device — an operator watches a device from its drawer; the lease route and the lease Screen tab are gone. Risk: the picture does not stop when the tab closes, and the worker keeps capturing.
• Console: the worker's Events tab scrolls back through its history #911 Worker events history — the worker page's Events tab scrolls back through that worker's whole history. Risk: events of another worker appear on the tab.
• Console: layout fixes from the 2026-10-23 review #912 Layout fixes — the scrollbar, breadcrumb, warm-pool line, row ⋯, Inbox row, toast and ⋯ duplicate faults are gone. Risk: a fix moves another box.

Completion conditions → tasks: 1–3 and 4 → #909 (server) and #910 (console); 5–6 → #910; 7 → #911; 8 → #912.

Open work in the same area:

• One capture per lease, shared by every viewer of its screen #602 (one capture per lease, shared): rekeyed by device after this feature; no Depends on, it waits for Stream any running device to an operator by worker and device id #909 by its own revise.
• The console stays smooth and light on a big fleet #905 (console smooth on a big fleet) and its ADR 0044 (PR docs(adr): 0044 the console reads what its page shows, and events mark it stale (#905) #907), tasks One lease is read directly, and gateway leases name the worker's lease id #913–Unchanged JSON answers under /v1 are 304 with an ETag #919: Console: the worker's Events tab scrolls back through its history #911 depends on The console reads per page through a query cache, and events mark data stale #914 (same useWorkerEvents), The daemon says what needs the operator: GET /v1/inbox #915 (protocol bump; follows One lease is read directly, and gateway leases name the worker's lease id #913) and One shared recent-events list per console tab #917 (splits EventFeed, sets the event cap to 1,000), and takes the cap the console has when it lands. Console: layout fixes from the 2026-10-23 review #912 changes the Inbox row in screens/inbox/index.tsx only, so it stays clear of The daemon says what needs the operator: GET /v1/inbox #915's inboxActions and state/inbox.ts, and leaves useWorkerPage (state/workers.ts, rewritten by The console reads per page through a query cache, and events mark data stale #914) untouched; no Depends on.
• PR fix(e2e): move the mouse off the menu so a new toast is not hovered (#900) #903 / Console e2e: a success toast leaves after 6 s fails when the mouse rests over the new toast #900 (toast hover test): same toast area as Console: layout fixes from the 2026-10-23 review #912, different lines (a test's mouse moves). No Depends on.
• Console e2e: a worker is drained from Fleet with no dialog, and Undo undrains it fails on the row's drained text #886 (fleet row drained text e2e): same fleet row as Console: layout fixes from the 2026-10-23 review #912's ⋯ check. No Depends on.
• A worker joined to a gateway does not serve its own HTTP API or console #705 / Joined workers expose fleet access only through their gateway #806 (a joined worker serves no HTTP): a joined worker's stream is reached only through the gateway, as Stream any running device to an operator by worker and device id #909 has it. No Depends on.
• The warm pool learns what to keep warm, with no configuration #771 (learned warm pool): changes which devices are ready, not how they stream. No Depends on.

Written by an agent.