Repository navigation
Description
Part of #327.
Scope
After this PR, an operator sees baselines in the web console: a Baselines page lists every baseline the worker holds (on a gateway, every worker's, each with its worker), with its spec, note, size, saved time and whether it is stale; and a device's drawer says which baseline and version the device was copied from. The page only shows: saving and removing stay on the CLI (maintainer, #327 spec session: "console list read-only").
One PR: the page, the drawer fact, the event mapping that keeps the page current and the website pages that describe them have no smaller slice a user would see.
In short
A new sidebar link, Baselines, opens /baselines: one table, one row per baseline. A device made from a baseline shows a Baseline fact in its drawer, for example checkout v2; a plain device shows none. A baseline saved, removed or gone stale shows on the page within about a second, with no reload.
flowchart LR
E["event stream: baseline.saved / removed / stale"] -->|"marks ['baselines'] stale (new)"| Q[(query cache)]
Q -->|"GET /v1/baselines (new key)"| P["Baselines page (new)"]
W["GET /v1/workers"] --> D["device drawer: Baseline fact (new)"]
The page, on a gateway (on a single host there is no Worker column):
| Worker | Name | Version | Platform | Model | OS | Mode | Note | Size | Saved | Stale |
|---|---|---|---|---|---|---|---|---|---|---|
| mac-studio-1 | checkout | 2 | Android | Pixel 9 / google_apis | 36 | full | app 4.2, test user | 4.5 GiB | 2 h ago | |
| mac-mini-2 | login | 1 | iOS | iPhone 17 | 27.0 | slim | — | 3 d ago | ■ stale · runtime com.apple.CoreSimulator.SimRuntime.iOS-27-0 is not installed |
- Model shows
<model> / <image tag>when the baseline has an image tag, as the Warm pool tab does (F13). - Size is the entry's size in bytes, printed by the console's
formatBytes(MiB under 1 GiB, else GiB with one decimal, F12); an entry with no size (it could not be counted) shows—. - Saved is the time since the entry's saved time,
<duration> ago, as Leases prints renewals (F13); the ISO time is the cell'stitle. - Stale is empty for a usable baseline. A stale one shows a warn
Statuswith the wordstale, then·and the entry's stale reason, word for word (colour is never the only signal, F18). - Rows are ordered by name, then by worker name. The table shows 25 rows at a time with a pager for 50 or 100, as Queue (F23).
- With no baseline the table says, in one line:
No baselines.(F11, F17). - The drawer's Baseline fact sits after Runtime:
<name> v<version>, in mono.
| What the daemon answers | Today | After |
|---|---|---|
/baselines in the address |
Not found | the Baselines page |
| a baseline list with entries | not shown | one row each |
| an empty list | not shown | No baselines. |
| an entry with a stale reason | not shown | the row's Stale cell: stale · <reason> |
| an entry with no size | not shown | the row's Size cell: — |
a device record with a baseline checkout, version 2 |
drawer shows no baseline | drawer fact Baseline checkout v2 |
| a device record with no baseline | as today | as today, no Baseline fact |
each of baseline.saved, baseline.removed and baseline.stale |
marks nothing (F5) | marks ['baselines'] stale |
If this task goes wrong, an operator sees a wrong or missing figure on the Baselines page or in a drawer; no lease or device changes.
Technical spec
Facts
Commit 019ba5c3d.
| # | Fact | Source |
|---|---|---|
| F1 | The console's pages are one route table; a route's group (Operate or Observe) puts it in a sidebar group |
ui/src/app/routes.ts:12-36 |
| F2 | The sidebar order and groups are written in the manual and the design doc: Overview, Inbox, Operate (Fleet, Leases, Queue), Observe (Activity, Usage) | ui/AGENTS.md:106-119; docs/internal/DESIGN.md:134-137 |
| F3 | The route order is asserted by a unit test and by the browser fixtures the shell spec reads | ui/src/app/routes.test.ts:20-30; e2e/console/fixtures.ts:749-764; e2e/console/shell.spec.ts:153-178 |
| F4 | A route's cache key is its first path segment (/v1/baselines → ['baselines']); poll and fresh times are per key, and a key not listed gets fresh 2 s and no poll |
ui/src/state/queries.ts:40-50, :66-72 |
| F5 | An event name maps to stale keys in staleKeys; a name not listed (any baseline.* today) maps to none |
ui/src/model/stale-keys.ts:17-44; ADR 0044 docs/internal/adr/0044-the-console-reads-what-its-page-shows-and-events-mark-it-stale.md:73-74 |
| F6 | A gateway passes a worker's event on to the console's stream | ADR 0044 :77-78 |
| F7 | A page's state hook reads its own route and /v1/workers for worker names, through useRouteQuery |
ui/src/state/waiting.ts:40-47 |
| F8 | The device drawer's Details tab shows Model, Runtime, State, then Holder, Lease and UDID when present | ui/src/screens/fleet/device-drawer.tsx:85-118 |
| F9 | DeviceRow is built from each device of a worker view; optional fields (mode, imageTag) are added through defined |
ui/src/model/worker-page.ts:289-343 |
| F10 | A worker view's devices are statusDeviceSchema, which #1207 extends with the device's baseline (feature Shared values "Device's baseline") |
src/contract/schemas.ts:214, :1208 |
| F11 | DataTable takes an empty line and draws it when there are no rows |
ui/src/ds/table.tsx:35, :86 |
| F12 | formatBytes prints MiB under 1 GiB, else GiB with one decimal |
ui/src/model/load.ts:13-18 |
| F13 | Leases prints a past time as <duration> ago; the Warm pool tab prints a model with an image tag as <model> / <tag> |
ui/src/model/leases.ts:264; ui/src/model/worker-page.ts:580 |
| F14 | useDaemonMode gives the daemon's mode, read from GET /v1/status; the console never guesses gateway |
ui/src/state/live.tsx:92-95; ADR 0037 docs/internal/adr/0037-the-console-acts-through-the-http-routes-on-base-ui.md:144-154 |
| F15 | Browser specs run a real daemon with fake drivers (startDaemon("worker" | "gateway")) and can replace one route's body with answer(page, pathname, body), keeping the daemon's real headers |
e2e/console/fixtures.ts:214-223; e2e/console/stub-answers.ts:6-14 |
| F16 | The sidebar icons are a fixed table of SVG paths keyed by name | ui/src/ds/icon.tsx:1-20 |
| F17 | An empty page says so in one line ("No leases."); no column repeats one value on every row | docs/internal/DESIGN.md:304-306 |
| F18 | Colour is never the only signal; every page works at 360 px wide with no sideways scroll | ui/AGENTS.md:155, :161 |
| F19 | The search dialog's page results come from the route table | ui/src/app/shell.tsx:19 |
| F20 | Activity summarises any event from its payload's known fields and falls back to the event name, so baseline.* events show there with no change |
ui/src/model/activity.ts:31-43 |
| F21 | The website's console page lists the sidebar's pages and the drawer's Details facts; the fleet console page describes what a gateway adds | website/src/content/docs/docs/worker/console.mdx:75, :120-122; website/src/content/docs/docs/gateway/fleet-console.mdx:30 |
| F22 | GET /v1/workers is an admin route declared in src/http/admin-declarations.ts; #1206 declares baseline.list's route beside it (feature Shared values "Baseline list entry"), and #1208 makes it list every worker's entries with the worker on a gateway |
src/http/admin-declarations.ts:12-19 |
| F23 | Queue pages its table through usePaging with TABLE_SIZES (25, 50, 100); the website says every list shows 25 rows with a pager for 50 or 100 |
ui/src/state/waiting.ts:48-51; ui/src/model/paging.ts:3; website/src/content/docs/docs/worker/console.mdx:77 |
| F24 | One table test lists each event with exactly the routes it marks; a route not in its watched list is never checked | ui/src/state/queries.test.ts:155-187 |
| F25 | Besides the shell spec, five browser specs loop over NAV or NAV_LABELS, so a new route runs through them; the big-fleet title counts "seven pages" |
e2e/console/big-fleet.spec.ts:43, :61; e2e/console/long-lists.spec.ts:806; e2e/console/sign-in.spec.ts:179; e2e/console/proxy-sign-in.spec.ts:177; e2e/console/inbox.spec.ts:568 |
| F26 | A browser spec drives the daemon's CLI through daemon.cli(args), and startFleet starts a gateway with joined workers |
e2e/console/fixtures.ts:25-28, :424-430 |
Modules touched
Searches: ROUTES, NavGroup, staleKeys, TIMES, DeviceRow, FactList, NAV_GROUPS, NAV =, of NAV, NAV_LABELS in ui/ and e2e/console/; ## Find your way around and ### Open a device under website/.
flowchart LR
routes["app/routes.ts (changed)"] --> screen["screens/baselines (new)"]
screen --> state["state/baselines.ts (new)"]
state --> model["model/baselines.ts (new)"]
state --> q["state/queries.ts (changed)"]
q --> stale["model/stale-keys.ts (changed)"]
drawer["screens/fleet/device-drawer.tsx (changed)"] --> wp["model/worker-page.ts (changed)"]
screen --> ds["ds/icon.tsx (changed)"]
ui/src/model/baselines.ts(new):baselineRows(entries, workers, now): the rows above, sorted, with the Worker cell only when an entry carries a worker. Unit testui/src/model/baselines.test.ts.ui/src/state/baselines.ts(new):useBaselines()reads/v1/baselinesand/v1/workers(F7), maps through the builder and pages the rows withusePaging({ sizes: TABLE_SIZES, … }), as Queue (F23); the Worker column shows whenuseDaemonMode()saysgateway(F14).ui/src/screens/baselines/index.tsxandbaselines.css(new):BaselinesScreen, aPagetitledBaselineswith oneDataTable, itsemptyline (F11) and the pager. No screen unit test: the rows are proved in the model test and the drawing in the browser spec (testing rule 7).ui/src/app/routes.ts: the route{ group: "Operate", icon: "baselines", label: "Baselines", path: "/baselines" }, after Queue.routes.test.tsgains it (F3).ui/src/ds/icon.tsx: abaselinesicon (F16).ui/src/model/stale-keys.ts:baseline.saved,baseline.removed,baseline.stale→[['baselines']].ui/src/state/queries.test.ts: the table test (F24) watches/v1/baselinesand gains the three rows.ui/src/state/queries.ts:baselines: { freshMs: FRESH_MS, pollMs: 15_000 }(F4), the Fleet's poll, so a change a gateway learns with no event still shows.ui/src/model/worker-page.ts:DeviceRow.baseline?: string(<name> v<version>) from the device record's baseline (F9, F10).ui/src/screens/fleet/device-drawer.tsx: the Baseline fact after Runtime (F8).ui/AGENTS.md: the Pages table row, the sidebar groups line, the key table in Reads.docs/internal/DESIGN.md:134-137: the sidebar order.e2e/console/fixtures.ts:NAVandNAV_GROUPSgain Baselines (F3);e2e/console/baselines.spec.ts(new).e2e/console/big-fleet.spec.ts: the title says "eight pages" (F25); the otherNAVloops (F25) take the new page with no edit.website/src/content/docs/docs/worker/console.mdx: a## Baselinessection, the sidebar list (:75) and the drawer's Details line (:122).website/src/content/docs/docs/gateway/fleet-console.mdx: one line that a gateway's Baselines page adds the Worker column.
sequenceDiagram
participant B as Browser (console)
participant D as Daemon (worker or gateway)
D--)B: baseline.saved (event stream)
Note over B: 300 ms with no event
B->>D: GET /v1/baselines (If-None-Match)
D-->>B: 200 entries, or 304
B->>D: GET /v1/baselines
D-->>B: 403 FORBIDDEN (not an operator)
Note over B: the page shows the route's refusal, as every page
Contract and event changes
None. The console reads #1206's baseline.list route and entry (with #1208's worker on a gateway) and #1207's device baseline as they are; it adds no shape, code or event, so it does not bump the protocol. The UI imports the entry type from src/contract/ type-only (ui/AGENTS.md, "Uses").
Other code on the same state
Searched staleKeys( (2 hits: the definition and ui/src/state/queries.ts:219), routeKey( and TIMES in ui/src/state/queries.ts, DeviceRow (4 files under ui/src/). The state this task writes is the browser's query cache: one new key, ['baselines'], read only by the new page; nothing else reads or writes it. The drawer reads ['workers'] as today; #1207 writes the device's baseline into that record, and its change reaches the drawer through the device.* and lease.* events that already mark ['workers'] stale (F5). #1206 and #1208 write the baseline records the route answers; the console never writes them.
Failure modes
| Call | Outcome | What happens | Limit, counted from |
|---|---|---|---|
GET /v1/baselines |
200 | the rows | the client's request timeout, from the send (as every read) |
GET /v1/baselines |
304 | the cached rows stay | same |
GET /v1/baselines |
refused (401, 403, 501) | the page shows the route's refusal through Loaded, as every page |
same |
GET /v1/baselines |
network lost or timeout | the page keeps its rows; the sidebar says Reconnecting (ADR 0044 §1) | same |
GET /v1/workers |
refused or lost | worker names fall back to the entry's worker id; the table still shows | same |
The task writes no state that outlives the tab. No Tests line for the refusal and loss rows: they are the shared Loaded and connection paths every page already tests.
Rules in play
- ADR 0037 §1, "Base UI is the base of the design system, inside
ds/only": the page usesPageandDataTablefromds/, no new Base UI import. - ADR 0037 §4, "It never guesses
gateway": the Worker column followsuseDaemonMode(F14). - ADR 0044 §1–2, "One key per route" and "An event name maps to the keys it changes": one new key, three event names mapped (F4, F5).
- ADR 0061 §6, "
baseline.liston a gateway lists every worker's baselines, each with its worker": the Worker column. ui/AGENTS.mdLayers: model builds rows, state reads, the screen draws;.dependency-cruiser.mjschecks it.docs/internal/DESIGN.mdVoice and Table:No baselines., numbers mono and right-aligned (F17).- Documentation rule 9, "A change to the public surface updates the website in the same change": the two console pages.
- Testing rule 7, "Prove each claim once, at the cheapest level": rows, order and formats in
model/baselines.test.ts; the browser spec proves what only a browser sees.
Tests
Seam: the console's browser lane, a real daemon with fake drivers (F15), modelled on e2e/console/queue.spec.ts. Baselines are saved for real through daemon.cli (F26): the out-of-process fake driver gains saveSource in #1206 and provision {source} in #1204 (resolution R15), so baseline.saved and baseline.removed reach the page as they do in use. A stale entry is the one case stubbed with answer (F15), since the fake driver has no way to make a source stale. Rows, order and formats are in ui/src/model/baselines.test.ts, modelled on ui/src/model/waiting.test.ts; the event map in the existing table test ui/src/state/queries.test.ts (F24).
- An operator opens the console: a Baselines page lists each worker's baselines, and a device's drawer shows its baseline — baselines present (with the page open,
baseline save checkout --lease <id> --note "app 4.2"shows the row with no reload, each column as in In short; a second save showscheckoutversion 2 in place of 1;lease --baseline checkoutgives a device whose drawer showsBaseline checkout v2, while a plain lease's device shows no Baseline fact; after both leases end,baseline remove checkouttakes the row away with no reload; on a gateway with two workers, each saving one baseline, the Worker column names each and the gateway's relayed event shows the row; in the model test, rows ordered by name then worker, Size byformatBytes, Saved as<duration> ago); none (the daemon's own empty answer:No baselines.); stale (/v1/baselinesstubbed with 26 entries, so the pager shows and the 26th is on page 2, one of them with stale reasonruntime com.apple.CoreSimulator.SimRuntime.iOS-27-0 is not installedand no size: the Stale cell shows the square,stale ·and the reason word for word, Size shows—; inqueries.test.ts, each ofbaseline.saved,baseline.removedandbaseline.stalemarks exactly/v1/baselines).
The sidebar order is the existing shell spec "the sidebar shows Overview and Inbox, then the Operate group…" (e2e/console/shell.spec.ts:153), extended through NAV and NAV_GROUPS; the 360 px and keyboard checks are the existing "every view" specs (e2e/console/views.spec.ts:105, :121), and the request budget, pager, sign-in and Inbox-count loops are the specs in F25; all pick the new route up from NAV and run in Done when.
Done when
pnpm exec vitest run --project unit ui/src/model/baselines.test.ts ui/src/app/routes.test.ts ui/src/state/queries.test.tspasses.pnpm test:console --project=chromium e2e/console/baselines.spec.ts e2e/console/shell.spec.ts e2e/console/views.spec.ts e2e/console/long-lists.spec.ts e2e/console/sign-in.spec.ts e2e/console/proxy-sign-in.spec.ts e2e/console/inbox.spec.tspasses.pnpm test:console --project=chromium e2e/console/big-fleet.spec.tspasses, in its own command (about 62 s per page, eight pages).- The sidebar shows Baselines in the Operate group after Queue, in
routes.ts,ui/AGENTS.mdandDESIGN.mdalike. website/src/content/docs/docs/worker/console.mdxhas a Baselines section and the drawer's Baseline fact;fleet-console.mdxsays the gateway adds the Worker column.
Out of scope
- Saving, replacing or removing a baseline from the console (CLI only, maintainer, Named baselines: a lease starts from a device the operator prepared #327 spec session).
- A baseline column in the worker's Devices table, or baselines on the worker's own page.
- Summaries for
baseline.*events in Activity beyond today's fallback (F20). - Fixing the console pages' older page names on the website beyond the lines this task touches.
Depends on
Written by an agent.
Activity
test: each of baseline.saved, baseline.removed and baseline.stale mar…
test: baseline rows are ordered by name then worker and mark a stale …
feat(ui): baseline rows are ordered by name then worker and carry the…
test: the Baselines page shows versions, the Worker column, stale rea…
feat(ui): the Baselines page shows the Worker and Stale columns and a…
docs: the Baselines page in the console manual, the design doc, the w…
docs: the console's Baselines section links the website's Baselines p…
docs: the drawer lists state before the baseline; test: the stale squ…
docs: ADR 0061 is Accepted (#1209)
fix(android): the daemon leaves its adb server running while an emula…
12 remaining items
fix(e2e): the baseline emulator test nukes its devices, so the pool's…
V3RON commentedon Nov 4, 2026
Handoff
Done: the stack's final hardware run passes on
4e6d4656a(7 slow-lane files, 53/53, iOS and Android). Hardware fixes 4 and 5 fixed only e2e cleanup: removing a home retries, and the Android baseline test nukes its devices. The fix-check over the loop commits (519e2c04f..4e6d4656a) has run. CI passes.Not done: R4 is open, so #1245 is back in draft and the stack does not merge.
Findings:
src/drivers/android/index.ts:1477#provisionFromSourcecopies a ready baseline source without re-checking whether it is stale. ADR 0061 §3 says a stale source is never copied. iOS re-checks in#namedSource. A lens probe removed a saved source's system image, and provision still resolved. The bug came from loop commit0d38b3336.Blocked on: maintainer. The review cap is spent. Fixing R4 needs one fix run, a fix-check past the cap, and the Android lane again.
Written by an agent.
fix(android): a baseline source is re-checked for staleness before it…
docs(website): the baselines page leads with what an operator needs, …
fix(baselines): a baseline records the image tag its saved device car…
fix(baselines): a copy of a baseline loses the LaunchServices databas…
fix(baselines): every simulator copy loses the LaunchServices databas…
feat(ui): a Baselines page and a device's baseline (#1245)