feat(web): usage dashboard — put the token/cost ledger on a screen (AGT-4289)

[unohee]

Why

/api/usage has served six axes (model · stage · task · project · adapter · day) since AGT-4178 and had no frontend reader — the only consumer was the openswarm cost CLI. The dashboard's sole cost display was an SSE counter that accumulated within a session and reset on refresh.

Two defects found while this was being written were each a single number on an axis the endpoint already served, and both were found by hand-querying the ledger over ssh rather than by looking at anything:

Issue	The number	Axis
AGT-4286	draft cache hit rate 30.5% while every other stage sat at 83-88%	by=stage
AGT-4288	13,287 draft calls across 239 tasks — 55.6 per task	by=stage + by=task

What it does

Fetches several axes in parallel; the endpoint groups by one axis per request. No backend change.

The derived columns are the point — cache rate, cost per call and calls per task do not exist in the rows the API returns. On the live ledger qwen3-235b shows 0.0% cache beside deepseek-v4-flash at 82.7%.

Numbers it refuses to state rather than state wrongly

• A rate with no prompt tokens behind it, and a share from a row that reported no price, render as —. Printing 0.0% would put an unmetered row beside rows that genuinely cost nothing relative to their peers — the exact comparison this page exists to support.
• The unattributed bucket is not a task, so it is out of the task ranking and out of calls-per-task, and the note above that table says how many calls and how much cost were excluded.
• Rows past the cap are counted and priced, because the project axis returns 67 rows over 30 days and the panel draws 25.

Also in this PR

• Collapses six duplicated page-shell route blocks in webAppRoutes.ts into a PAGE_SHELLS table + tryServePageShell — the first test coverage any of those six routes has had.
• Widens lint from oxlint src/ to include web/static/js/. That directory had never been linted by any gate in this repo, which is how a 412-line new file reached round three with dead code still in it. This surfaces 15 pre-existing warnings in other files (webToken.js ×7, threadBoard.mjs, themeBoot.js, sessionPanel.mjs, diffPanel.mjs); usage.mjs itself is clean and oxlint exits 0, so CI is unaffected. Those 11 warnings are a follow-up, not a reason to keep the directory unlinted.

Layout is measured, not reasoned

auto-fit answers a higher floor with more tracks, not wider ones. The first attempt at the column-clipping fix raised the floor to 38rem, looked correct, and left 비용 off-screen at every desktop width:

1920 | panel 617  table 774 | clipped | 4 of 7 columns

The floor is now wider than the table it holds — 7/7 at 1280/1440/1920/2560, no page-level horizontal scroll at any width including 390. tests/web/usageLayout.test.ts is a tripwire on the two declarations that were wrong before, because jsdom computes neither layout nor colour.

Verification

Gate	Result
npx tsc --noEmit	exit 0
npm run build	exit 0
npm run lint	exit 0 (15 pre-existing warnings, above)
npx vitest run (full)	exit 0 — 5955 passed / 10 skipped
Chromium, live ledger, 6 viewports	0 console errors, 0 document overflow

Review

Four rounds of layer-2 independent subagent review (openswarm review is not run on my own changes, per the 2026-09-02 policy). Rounds 1-3 each returned REVISE and each found genuinely new defects; round 4 returned APPROVE with five findings, all filed as follow-ups, three of which are fixed here anyway.

The one worth naming: round 3's R3-1 was introduced by my fix for round 2's finding of the same shape. truncationNote summed the aggregate's cost-ordered tail while the task panel re-sorted by calls inside renderTable, so it printed $0.05 for $50.00 of hidden spend — worse than the silence it replaced. renderTable now owns the ordering and reports what it hid; truncationNote only formats.

Closes AGT-4289.

🤖 Generated with Claude Code