Skip to content

Console: a Baselines page and a device's baseline #1209

Closed

Description

@V3RON

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)"]
Loading

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's title.
  • Stale is empty for a usable baseline. A stale one shows a warn Status with the word stale, 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)"]
Loading
  • 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 test ui/src/model/baselines.test.ts.
  • ui/src/state/baselines.ts (new): useBaselines() reads /v1/baselines and /v1/workers (F7), maps through the builder and pages the rows with usePaging({ sizes: TABLE_SIZES, … }), as Queue (F23); the Worker column shows when useDaemonMode() says gateway (F14).
  • ui/src/screens/baselines/index.tsx and baselines.css (new): BaselinesScreen, a Page titled Baselines with one DataTable, its empty line (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.ts gains it (F3).
  • ui/src/ds/icon.tsx: a baselines icon (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/baselines and 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: NAV and NAV_GROUPS gain Baselines (F3); e2e/console/baselines.spec.ts (new). e2e/console/big-fleet.spec.ts: the title says "eight pages" (F25); the other NAV loops (F25) take the new page with no edit.
  • website/src/content/docs/docs/worker/console.mdx: a ## Baselines section, 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
Loading

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 uses Page and DataTable from ds/, no new Base UI import.
  • ADR 0037 §4, "It never guesses gateway": the Worker column follows useDaemonMode (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.list on a gateway lists every worker's baselines, each with its worker": the Worker column.
  • ui/AGENTS.md Layers: model builds rows, state reads, the screen draws; .dependency-cruiser.mjs checks it.
  • docs/internal/DESIGN.md Voice 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 shows checkout version 2 in place of 1; lease --baseline checkout gives a device whose drawer shows Baseline checkout v2, while a plain lease's device shows no Baseline fact; after both leases end, baseline remove checkout takes 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 by formatBytes, Saved as <duration> ago); none (the daemon's own empty answer: No baselines.); stale (/v1/baselines stubbed with 26 entries, so the pager shows and the 26th is on page 2, one of them with stale reason runtime com.apple.CoreSimulator.SimRuntime.iOS-27-0 is not installed and no size: the Stale cell shows the square, stale · and the reason word for word, Size shows —; in queries.test.ts, each of baseline.saved, baseline.removed and baseline.stale marks 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.ts passes.
  • 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.ts passes.
  • pnpm test:console --project=chromium e2e/console/big-fleet.spec.ts passes, 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.md and DESIGN.md alike.
  • website/src/content/docs/docs/worker/console.mdx has a Baselines section and the drawer's Baseline fact; fleet-console.mdx says 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

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 2, 2026
  2. added
    task:readySpec checked. An agent may implement it once its Depends on allow.
    and removed
    task:draftScope written; technical spec or its spec check missing.
    on Nov 2, 2026
  3. self-assigned this
    on Nov 3, 2026
  4. 12 remaining items

  5. V3RON commented on Nov 4, 2026

    @V3RON
    ContributorAuthor

    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:

    • R4 (code, blocking): src/drivers/android/index.ts:1477 #provisionFromSource copies 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 commit 0d38b3336.

    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.

  6. added
    task:blockedAgent stopped on a blocker in its handoff. Maintainer re-adds the label it came from.
    and removed
    task:readySpec checked. An agent may implement it once its Depends on allow.
    on Nov 4, 2026
  7. removed their assignment
    on Nov 4, 2026
  8. added
    task:readySpec checked. An agent may implement it once its Depends on allow.
    and removed
    task:blockedAgent stopped on a blocker in its handoff. Maintainer re-adds the label it came from.
    on Nov 4, 2026
  9. self-assigned this
    on Nov 4, 2026
  10. added a commit that references this issue on Nov 4, 2026
    059a270
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

task:readySpec checked. An agent may implement it once its Depends on allow.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions