The console stays smooth and light on a big fleet #905

Request: none

Problem

The web console reads every route the open page uses once a second, and again after every event the daemon sends, with no pause between bursts. The sidebar's Inbox count keeps the four fleet-wide lists (workers, leases, waiting requests, tokens) in that loop on every page. On a gateway with many workers and leases, each open tab asks for the whole fleet several times a second and mostly gets the same answer back, and the browser rebuilds every view each second.

Nothing is loaded only when a page needs it, and nothing is dropped when the operator leaves a page: lease and stats reads stay in memory for the life of the tab, while the event lists are thrown away and fetched again each time a page opens.

Who it is for

An operator who keeps the console open on a gateway with up to 50 workers (5–10 devices each, about 500 devices and up to 500 live leases), often in several tabs, and the gateway that answers them.

Outcome

• An idle console tab costs the gateway at most 40 requests a minute on any page, instead of about 4 a second.
• A page reads only its own data, while it is on screen. Leaving it stops its reads, and its data is dropped a minute later.
• A change the daemon sends an event for (a lease granted, a device booting, a worker connecting) still shows within about a second. Anything else (host load, a worker that connects as incompatible) shows within 15 seconds of the daemon serving it; a gateway refreshes a worker's host load every 30 s, so there host load can take about 45 s (decided in delivery, accepted by the maintainer 2026-10-23).
• An answer that has not changed costs no download and no re-render.

How it works for the user

sequenceDiagram
  participant O as Operator
  participant C as Console tab
  participant G as Gateway
  O->>C: opens Leases
  C->>G: GET /v1/leases, /v1/workers, /v1/inbox
  G-->>C: 200 + ETag
  Note over C: polls leases every 10 s, workers 15 s, inbox 10 s
  C->>G: GET /v1/leases (If-None-Match)
  G-->>C: 304, nothing changed
  G--)C: event lease.granted
  Note over C: waits 300 ms for the burst to end
  C->>G: GET /v1/leases, /v1/workers, /v1/inbox
  C->>G: same reads again 1.5 s later
  G--)C: event lease.renewed
  Note over C: deadline patched, no read
  O->>C: opens Usage
  Note over C: lease reads stop; lease data dropped after 60 s
  G--xC: connection lost
  Note over C: reads stop until the gateway answers again

What the operator sees does not change: the same pages, the same data, the same "Connected" and "Reconnecting" line. In the browser's network panel, before and after, an idle Leases page for one minute:

Examples

When a page's data is read, per route:

What could go wrong

• A change with no event of its own (host load) shows up to 15 s late instead of 1 s, and on a gateway up to about 45 s, since the gateway itself refreshes host load every 30 s. Expected; the docs say so (decided in delivery, accepted by the maintainer 2026-10-23).
• A new event name that should refresh a page refreshes nothing until the poll, up to 15 s late, until someone adds it to the event map. Likely over time.
• The Inbox count differs for a few seconds from what the Fleet page shows, because they are read at different moments. Rare and harmless.

Words used

• Poll interval: how often a page re-reads one route while it is on screen, e.g. leases every 10 s.
• Stale: data the console will re-read the next time a page needs it; an event marks data stale.
• Dropped: data no page has used for a while is removed from the tab's memory, e.g. leases 60 s after the last page that showed them closed.
• Burst window: the console waits until no event has arrived for 300 ms, but never more than 1 s after the burst's first event, before reading, so 50 events in a second cost one read.
• ETag / 304: a short fingerprint of an answer. The console sends back the last one it got; when the answer has not changed, the server says "304 Not Modified" with no body.
• Inbox item: one thing that needs the operator, e.g. a quarantined device or a request waiting over a minute. It carries a small copy of what it is about (its subject): the worker's own fields, or the device, the lease or the request.

Non-goals

• No server-side paging or filtering of /v1/workers or /v1/leases, and no GET /v1/workers/{id}.
• No filter on the event stream, and no resume after a reconnect from the last event id.
• No new event for a worker that connects as incompatible.
• No change to what any page shows, or to the CLI, except that the Inbox and Overview's "Could not check" note gives way to the page's refusal when GET /v1/inbox fails.
• Activity's scroll-back stays as it is: it is already dropped when the operator leaves Activity.
• The per-second clock still rebuilds the views that show a time; a cheaper clock is a follow-up.

Completion conditions

• With a fake gateway of 50 workers and 500 devices, an idle console tab makes at most 40 requests to /v1 (the event stream not counted) in the 60 s after each of the seven pages has loaded.
• A lease granted through the gateway shows on the Leases page within about a second, as today.
• Leaving a page stops its reads; coming back within a minute shows the kept data at once.
• A second read of an unchanged list answers 304.
• The sidebar count reads GET /v1/inbox and none of the four fleet lists; the Inbox page and the Overview's Needs you read it and /v1/workers, and not leases, tokens or waiting requests.

Open questions

None.

Decisions

• ADR 0044 — The console reads what its page shows, and events mark it stale: replaces the 1 s poll and the read after every event (ADR 0013 §3) with per-route intervals, a burst window and an event map; adds ETags, lease.get, workerLeaseId and GET /v1/inbox.
• Maintainer, this session: target 50 workers × 5–10 devices; event changes within about a second, others within 15 s; server scope = ETag, lease.get, GET /v1/inbox; ETag is a hash of the answer; inbox items carry ids, labels and timestamps; renewals patched in place via workerLeaseId; the event map below; read twice after a burst; test seams: console query layer in Node, HTTP app tests, one browser-lane request-count test.
• Maintainer, after the feature check: an inbox item embeds a small subject record (the worker's own fields without devices, catalog, leases or downloads, plus its held lease count; or the device with its worker's id and label; or the lease record with its holder; or the request), (the Inbox page reading nothing else was replaced by the next line).
• After the task checks (to confirm at approval): the Inbox page and Needs you also read /v1/workers for names, links and lease counts, since a row's menu and the drawer's event lines need them; the Activity history and the cheaper clock leave this feature; The daemon says what needs the operator: GET /v1/inbox #915 waits for Console: watch any device's screen, and layout fixes from the 2026-10-23 review #906's Console: layout fixes from the 2026-10-23 review #912.
• Taken as recommended (maintainer: smaller choices follow the recommendation): the rules and their helpers (holderName, deviceOfLease, isExpiring, stateEnteredAt, requestedDevice) live zod-free in src/contract/inbox.ts, and the console imports that file by path, a second exemption beside version-order.ts; idle ceiling 40 a minute over the 60 s after load, event stream not counted; the burst read waits at most 1 s after a burst's first event; a renewal of a lease the cached inbox shows as ending marks the inbox stale; the server rules and the console switch are one task, so the rules move in one change; the Inbox page's "could not check" note goes (the server reads its own data; a failed read shows the page's refusal); the worker page's Events tab is left to Console: watch any device's screen, and layout fixes from the 2026-10-23 review #906 The console reads per page through a query cache, and events mark data stale #914.
• The query cache lives in ui/src/state/: .dependency-cruiser.mjs:249 forbids @tanstack/* in ui/src/data/.

Shared values

Behaviours

Tasks

flowchart LR
  X[#912 of #906] -.-> T4
  T6 -.-> Y[#911 of #906]
  T1[#919 ETag] --> T5
  T2[#913 lease.get + workerLeaseId] --> T4
  T2 --> T5
  T3[#914 query layer] --> T4[#915 inbox on the server]
  T4 --> T5[#916 304 + renewals]
  T4 --> T6[#917 shared recent events]
  T5 --> T7[#918 request-count test]

• Unchanged JSON answers under /v1 are 304 with an ETag #919 Unchanged answers are 304. Risk: a stream gets buffered.
• One lease is read directly, and gateway leases name the worker's lease id #913 One lease read directly; gateway leases carry the worker's id. Risk: an agent sees another's lease.
• The console reads per page through a query cache, and events mark data stale #914 The console reads per page with TanStack Query and marks data stale from events. Risk: a change waits for the poll.
• The daemon says what needs the operator: GET /v1/inbox #915 The server says what needs the operator, and the console shows it. Risk: the Inbox shows a different list.
• The console sends ETags back and patches lease renewals in place #916 The console sends ETags back and patches renewals. Risk: a lease shows an old deadline.
• One shared recent-events list per console tab #917 One shared recent-events list per tab. Risk: a drawer misses events that came while it was closed.
• A browser test proves an idle console stays quiet on a 50-worker fleet #918 A browser test proves an idle tab stays quiet. Risk: a flaky ceiling.

Completion conditions: idle ceiling → #918; a lease shows within a second → #914; leaving stops reads → #914; 304 → #919, #916; inbox reads → #915.

Across features: #915 depends on #912; #911 depends on #914, #915 and #917.

Open work in the same area:

• Console: watch any device's screen, and layout fixes from the 2026-10-23 review #906 (watch any device's screen, layout fixes): Console: the worker's Events tab scrolls back through its history #911 (worker Events history) bumps the protocol, edits the contract and both dispatchers, rewrites useWorkerEvents and builds on EventFeed.loadOlder → Console: the worker's Events tab scrolls back through its history #911 already depends on The console reads per page through a query cache, and events mark data stale #914, The daemon says what needs the operator: GET /v1/inbox #915 and One shared recent-events list per console tab #917, so it lands after them. Console: layout fixes from the 2026-10-23 review #912 (layout fixes) changes inboxActions, state/inbox.ts and the Inbox screen → The daemon says what needs the operator: GET /v1/inbox #915 depends on it. Stream any running device to an operator by worker and device id #909, Console: watch a device from its drawer's Screen tab; the lease stream route goes #910 (device stream, lease Screen tab): no shared code. docs(adr): 0045 a device's screen streams to operators, not a lease's (#906) #908 took ADR 0045.
• Every device state change is one device.state-changed event #320 (one device.state-changed event): the map's device.* prefix covers it. None.
• Console: time in state for every device #319 (time in state for every device; draft, blocked by Every device shape says when the device entered its state #318): edits the Inbox's stalled line, which The daemon says what needs the operator: GET /v1/inbox #915 moves to src/contract/inbox.ts. Whichever lands second edits the other's file. None.
• Review fleet reconciliation: what breaks while a gateway rebuilds its view #412, fix(gateway): a stale worker view no longer brings back a released lease (#898) #899 (gateway views), fix(daemon): status.get shows an agent only its own leases and queue entries #893 (status.get for agents): no shared code. None.
• e2e console specs that assume a re-read every second (e2e/console/workers-answers.ts:12-14): The console reads per page through a query cache, and events mark data stale #914 updates them.

Written by an agent.