From 8125cbf7b1aecc01a8be6a7b60ef593b61dd0d7c Mon Sep 17 00:00:00 2001
From: unohee <unohee.official@gmail.com>
Date: Thu, 10 Sep 2026 16:58:04 +0900
Subject: [PATCH] =?UTF-8?q?feat(web):=20usage=20dashboard=20=E2=80=94=20pu?=
 =?UTF-8?q?t=20the=20token/cost=20ledger=20on=20a=20screen=20(AGT-4289)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`/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:

  - AGT-4286: the draft stage at a 30.5% cache hit rate while every other stage
    sat at 83-88%.
  - AGT-4288: 13,287 draft calls across 239 tasks — 55.6 per task.

The endpoint groups by ONE axis per request, so the page fetches several in
parallel rather than changing the aggregate. 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, and they are what carry the signal:
on the ledger this was written against, `qwen3-235b` shows a 0.0% cache rate
beside `deepseek-v4-flash` at 82.7%.

Numbers the page refuses to state rather than state wrongly:

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

Also collapses six duplicated page-shell route blocks in webAppRoutes.ts into a
PAGE_SHELLS table plus tryServePageShell, which is the first test coverage any
of those six routes has had, and widens `lint` to cover 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. Widening it
surfaces 15 pre-existing warnings in other files; oxlint still exits 0.

Layout is measured, not reasoned: `auto-fit` answers a higher floor with more
tracks rather than wider ones, so a first attempt at the column-clipping fix
looked right and left 비용 off-screen at every desktop width. The floor is now
wider than the table it holds, and tests/web/usageLayout.test.ts is a tripwire
on the two declarations that were wrong before, since jsdom computes no layout
and no colour.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 package.json                     |   2 +-
 src/support/dashboardHtml.ts     |   1 +
 src/support/staticAssets.test.ts |  11 +-
 src/support/staticAssets.ts      |   5 +
 src/support/webAppRoutes.test.ts |  67 ++++
 src/support/webAppRoutes.ts      |  99 ++---
 tests/web/tokens.test.ts         |   2 +-
 tests/web/usage.test.ts          | 624 +++++++++++++++++++++++++++++++
 tests/web/usageLayout.test.ts    |  61 +++
 web/static/app.html              |   1 +
 web/static/chat.html             |   1 +
 web/static/css/usage.css         | 123 ++++++
 web/static/js/usage.mjs          | 444 ++++++++++++++++++++++
 web/static/orchestration.html    |   1 +
 web/static/threads.html          |   1 +
 web/static/usage.html            | 101 +++++
 web/static/warehouse.html        |   1 +
 17 files changed, 1483 insertions(+), 62 deletions(-)
 create mode 100644 src/support/webAppRoutes.test.ts
 create mode 100644 tests/web/usage.test.ts
 create mode 100644 tests/web/usageLayout.test.ts
 create mode 100644 web/static/css/usage.css
 create mode 100644 web/static/js/usage.mjs
 create mode 100644 web/static/usage.html

diff --git a/package.json b/package.json
index 208ad3a3..012cd2ed 100644
--- a/package.json
+++ b/package.json
@@ -24,7 +24,7 @@
     "postbuild": "chmod +x dist/cli.js && node -e \"const fs=require('node:fs');fs.rmSync('dist/web-static',{recursive:true,force:true});fs.cpSync('web/static','dist/web-static',{recursive:true})\"",
     "start": "node --env-file=.env dist/index.js",
     "stop": "pkill -f 'node --env-file=.env.*openswarm' 2>/dev/null || echo 'No process running'",
-    "lint": "oxlint src/",
+    "lint": "oxlint src/ web/static/js/",
     "typecheck": "tsc --noEmit -p tsconfig.check.json",
     "test": "node --experimental-vm-modules node_modules/vitest/vitest.mjs run",
     "test:coverage": "node --experimental-vm-modules node_modules/vitest/vitest.mjs run --coverage",
diff --git a/src/support/dashboardHtml.ts b/src/support/dashboardHtml.ts
index 85a81110..2fba8f79 100644
--- a/src/support/dashboardHtml.ts
+++ b/src/support/dashboardHtml.ts
@@ -22,6 +22,7 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
       <a href="/orchestration">Orchestration</a>
       <a href="/threads">Threads</a>
       <a href="/warehouse">Warehouse</a>
+      <a href="/usage">Usage</a>
       <a href="/issues">Issues</a>
     </nav>
     <div class="topbar-spacer"></div>
diff --git a/src/support/staticAssets.test.ts b/src/support/staticAssets.test.ts
index b26a0a33..6c4761e8 100644
--- a/src/support/staticAssets.test.ts
+++ b/src/support/staticAssets.test.ts
@@ -3,7 +3,8 @@ import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import {
-  contentTypeFor, readAppShell, readStaticAsset, readThreadBoardShell, resolveStaticRoot, StaticAssetError,
+  contentTypeFor, readAppShell, readStaticAsset, readThreadBoardShell, readUsageShell,
+  resolveStaticRoot, StaticAssetError,
 } from './staticAssets.js';
 
 describe('contentTypeFor', () => {
@@ -26,6 +27,14 @@ describe('resolveStaticRoot', () => {
   it('ships the durable repository thread shell', async () => {
     expect((await readThreadBoardShell())?.toString()).toContain('Repository threads');
   });
+
+  it('ships the usage shell, wired to its module (AGT-4289)', async () => {
+    // A shell that loses its <script> renders an empty page and still 200s,
+    // so assert the seam, not just that some HTML came back.
+    const shell = (await readUsageShell())?.toString() ?? '';
+    expect(shell).toContain('/static/js/usage.mjs');
+    expect(shell).toContain('/static/js/webToken.js');
+  });
 });
 
 describe('readStaticAsset', () => {
diff --git a/src/support/staticAssets.ts b/src/support/staticAssets.ts
index 3fc978c7..48fa9982 100644
--- a/src/support/staticAssets.ts
+++ b/src/support/staticAssets.ts
@@ -149,6 +149,11 @@ export async function readThreadBoardShell(): Promise<Buffer | null> {
   return readShellFile('threads.html');
 }
 
+/** The usage dashboard shell (AGT-4289). */
+export async function readUsageShell(): Promise<Buffer | null> {
+  return readShellFile('usage.html');
+}
+
 /** The /app entry document, or null when assets are not present. */
 export async function readAppShell(): Promise<Buffer | null> {
   return readShellFile('app.html');
diff --git a/src/support/webAppRoutes.test.ts b/src/support/webAppRoutes.test.ts
new file mode 100644
index 00000000..55fc5ea0
--- /dev/null
+++ b/src/support/webAppRoutes.test.ts
@@ -0,0 +1,67 @@
+// Page shells were six copies of the same ten lines, one per route (AGT-4289).
+// Copies drift: the 404-when-unbuilt path in particular is the one an operator
+// meets after a fresh clone, and it existed six times with no test on any of
+// them. These drive the single definition that replaced them.
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { ServerResponse } from 'node:http';
+
+import { tryServePageShell } from './webAppRoutes.js';
+
+/** A response that records what the handler did to it. */
+function res() {
+  const sent: { status?: number; headers?: Record<string, string>; body?: unknown } = {};
+  return {
+    sent,
+    res: {
+      writeHead: (status: number, headers: Record<string, string>) => { sent.status = status; sent.headers = headers; },
+      end: (body: unknown) => { sent.body = body; },
+    } as unknown as ServerResponse,
+  };
+}
+
+afterEach(() => { vi.restoreAllMocks(); });
+
+const PAGES = ['/orchestration', '/chat', '/warehouse', '/usage', '/threads', '/app'];
+
+describe('tryServePageShell', () => {
+  it.each(PAGES)('serves %s as HTML from the built assets', async (url) => {
+    const { res: r, sent } = res();
+
+    await expect(tryServePageShell(r, url)).resolves.toBe(true);
+
+    expect(sent.status).toBe(200);
+    expect(sent.headers?.['Content-Type']).toContain('text/html');
+    // The shells are a build product; a stale cache would serve yesterday's page.
+    expect(sent.headers?.['Cache-Control']).toBe('no-cache');
+    expect(String(sent.body)).toContain('<!doctype html>');
+  });
+
+  it('serves the usage page with its module and token script attached', async () => {
+    // A shell that loses either one still returns 200 and renders nothing
+    // useful: no data without the module, no data off-localhost without the
+    // token wrapper.
+    const { res: r, sent } = res();
+    await tryServePageShell(r, '/usage');
+    expect(String(sent.body)).toContain('/static/js/usage.mjs');
+    expect(String(sent.body)).toContain('/static/js/webToken.js');
+  });
+
+  it('declines a URL that names no page, so later routes still run', async () => {
+    const { res: r, sent } = res();
+    await expect(tryServePageShell(r, '/api/usage')).resolves.toBe(false);
+    expect(sent.status).toBeUndefined();
+  });
+
+  it('says how to build the assets rather than failing opaquely', async () => {
+    // What an operator meets on a fresh clone before `npm run build`.
+    const staticAssets = await import('./staticAssets.js');
+    vi.spyOn(staticAssets, 'readUsageShell').mockResolvedValue(null);
+    const { res: r, sent } = res();
+
+    await expect(tryServePageShell(r, '/usage')).resolves.toBe(true);
+
+    expect(sent.status).toBe(404);
+    expect(String(sent.body)).toContain('npm run build');
+  });
+});
diff --git a/src/support/webAppRoutes.ts b/src/support/webAppRoutes.ts
index a7aea70d..d4065d34 100644
--- a/src/support/webAppRoutes.ts
+++ b/src/support/webAppRoutes.ts
@@ -10,7 +10,7 @@
 
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { AutonomousRunner } from '../automation/autonomousRunner.js';
-import { readAppShell, readStaticAsset, StaticAssetError } from './staticAssets.js';
+import { readStaticAsset, StaticAssetError } from './staticAssets.js';
 
 function writeJson(res: ServerResponse, statusCode: number, body: unknown): void {
   res.writeHead(statusCode, { 'Content-Type': 'application/json' });
@@ -26,6 +26,44 @@ function messageOf(err: unknown): string {
   return 'Internal error';
 }
 
+/**
+ * Page shells: a URL, and the reader that returns its HTML.
+ *
+ * These were six copies of the same ten lines. One table and one helper means
+ * a new page is one entry, and the 404-when-unbuilt behaviour has a single
+ * definition rather than six that can drift apart.
+ */
+const PAGE_SHELLS: Record<string, () => Promise<Buffer | null>> = {
+  '/orchestration': async () => (await import('./staticAssets.js')).readOrchestrationShell(),
+  '/chat': async () => (await import('./staticAssets.js')).readChatShell(),
+  '/warehouse': async () => (await import('./staticAssets.js')).readWarehouseShell(),
+  '/usage': async () => (await import('./staticAssets.js')).readUsageShell(),
+  '/threads': async () => (await import('./staticAssets.js')).readThreadBoardShell(),
+  '/app': async () => (await import('./staticAssets.js')).readAppShell(),
+};
+
+/**
+ * Serve the shell registered for this URL. Returns false when the URL names no
+ * page, so the caller falls through to the routes after it.
+ *
+ * A missing shell is 404, not 500: the assets are a build product, and the
+ * message says how to produce them.
+ */
+export async function tryServePageShell(res: ServerResponse, url: string): Promise<boolean> {
+  // hasOwn, not a bare index: `url` is request input, and this must not
+  // depend on the caller's `/`-prefix invariant surviving a future change.
+  if (!Object.hasOwn(PAGE_SHELLS, url)) return false;
+  const load = PAGE_SHELLS[url];
+  const shell = await load();
+  if (!shell) {
+    writeJson(res, 404, { error: 'Static assets not built (run npm run build)' });
+  } else {
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
+    res.end(shell);
+  }
+  return true;
+}
+
 /**
  * Handle the /app, /static/*, and /api/work* routes. Returns true when the
  * request was handled. `readBody` is injected from web.ts so its size limit
@@ -66,64 +104,7 @@ export async function tryHandleAppRoutes(
     if (await tryHandleWorkSessionRoutes(req, res, url, requestUrl, runner)) return true;
   }
 
-  if (url === '/orchestration') {
-    const { readOrchestrationShell } = await import('./staticAssets.js');
-    const shell = await readOrchestrationShell();
-    if (!shell) {
-      writeJson(res, 404, { error: 'Static assets not built (run npm run build)' });
-    } else {
-      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
-      res.end(shell);
-    }
-    return true;
-  }
-
-  if (url === '/chat') {
-    const { readChatShell } = await import('./staticAssets.js');
-    const shell = await readChatShell();
-    if (!shell) {
-      writeJson(res, 404, { error: 'Static assets not built (run npm run build)' });
-    } else {
-      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
-      res.end(shell);
-    }
-    return true;
-  }
-
-  if (url === '/warehouse') {
-    const { readWarehouseShell } = await import('./staticAssets.js');
-    const shell = await readWarehouseShell();
-    if (!shell) {
-      writeJson(res, 404, { error: 'Static assets not built (run npm run build)' });
-    } else {
-      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
-      res.end(shell);
-    }
-    return true;
-  }
-
-  if (url === '/threads') {
-    const { readThreadBoardShell } = await import('./staticAssets.js');
-    const shell = await readThreadBoardShell();
-    if (!shell) {
-      writeJson(res, 404, { error: 'Static assets not built (run npm run build)' });
-    } else {
-      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
-      res.end(shell);
-    }
-    return true;
-  }
-
-  if (url === '/app') {
-    const shell = await readAppShell();
-    if (!shell) {
-      writeJson(res, 404, { error: 'Static assets not built (run npm run build)' });
-    } else {
-      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
-      res.end(shell);
-    }
-    return true;
-  }
+  if (await tryServePageShell(res, url)) return true;
 
   if (url.startsWith('/static/')) {
     try {
diff --git a/tests/web/tokens.test.ts b/tests/web/tokens.test.ts
index 0ef8ca32..bc1becd4 100644
--- a/tests/web/tokens.test.ts
+++ b/tests/web/tokens.test.ts
@@ -163,7 +163,7 @@ describe('page shells (AGT-4201)', () => {
   });
 
   it('share one navigation naming every page', () => {
-    const routes = ['/app', '/chat', '/orchestration', '/threads', '/warehouse'];
+    const routes = ['/app', '/chat', '/orchestration', '/threads', '/warehouse', '/usage'];
     for (const file of html) {
       const source = readFileSync(file, 'utf8');
       const name = relative(ROOT, file);
diff --git a/tests/web/usage.test.ts b/tests/web/usage.test.ts
new file mode 100644
index 00000000..7182c37d
--- /dev/null
+++ b/tests/web/usage.test.ts
@@ -0,0 +1,624 @@
+// @vitest-environment jsdom
+//
+// The page is a reader, so its whole value is whether a number arrives on
+// screen correctly — and the numbers that matter here are derived, not served.
+// `/api/usage` returns raw counters; cache rate, cost per call and calls per
+// task are computed in the view, which is exactly where a divide-by-zero or a
+// silent NaN turns a cost signal into a blank cell.
+//
+// Two of those derived numbers already found production defects: a 30.5% draft
+// cache rate beside 83-88% (AGT-4286), and 13,287 calls over 239 tasks
+// (AGT-4288). Both are asserted below against the shapes that produce them.
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { beforeEach, describe, expect, it, onTestFinished, vi } from 'vitest';
+// @ts-expect-error — browser ESM asset without type declarations
+import {
+  attributedTasks, cacheRate, costPerCall, formatCost, formatPercent, formatTokens,
+  loadUsage, rateClass, renderDays, renderSummary, renderTable, share,
+  rowShare, startUsageView, truncationNote, UNATTRIBUTED, windowFromSearch,
+} from '../../web/static/js/usage.mjs';
+
+const SHELL = readFileSync(resolve(__dirname, '../../web/static/usage.html'), 'utf8');
+
+function row(key: string, over: Record<string, number> = {}) {
+  return {
+    key, calls: 10, meteredCalls: 10, promptTokens: 1000, completionTokens: 100,
+    cachedTokens: 800, reasoningTokens: 0, costUsd: 1, ...over,
+  };
+}
+
+/** Mount the real shell so the tests bind to the same ids the page ships. */
+function mountShell(): void {
+  document.body.innerHTML = SHELL.replace(/^[\s\S]*?<body[^>]*>/, '').replace(/<\/body>[\s\S]*$/, '');
+}
+
+describe('derived numbers', () => {
+  it('computes a cache rate from prompt tokens', () => {
+    expect(cacheRate(row('a'))).toBeCloseTo(0.8);
+  });
+
+  it('returns null rather than dividing by zero when nothing was prompted', () => {
+    // 0% would sit this row next to the genuinely uncached ones, which is the
+    // comparison the page is for.
+    expect(cacheRate(row('a', { promptTokens: 0, cachedTokens: 0 }))).toBeNull();
+    expect(formatPercent(cacheRate(row('a', { promptTokens: 0 })))).toBe('—');
+  });
+
+  it('divides cost only over the calls that reported a price', () => {
+    // Half the calls unmetered: the per-call price is over the metered half,
+    // otherwise a free provider makes a paid one look cheap.
+    expect(costPerCall(row('a', { calls: 20, meteredCalls: 10, costUsd: 5 }))).toBeCloseTo(0.5);
+    expect(costPerCall(row('a', { meteredCalls: 0 }))).toBeNull();
+  });
+
+  it('has no share to report for a row that reported no price', () => {
+    // The row-level twin of the case below. On the live ledger gpt-5.6-terra
+    // carries 65% of all calls unmetered, and read `—` under 호출당 while
+    // reading 0.0% under 점유 in the same row.
+    expect(rowShare(row('a', { meteredCalls: 0, costUsd: 0 }), 10)).toBeNull();
+    expect(formatPercent(rowShare(row('a', { meteredCalls: 0 }), 10))).toBe('—');
+    expect(rowShare(row('a', { meteredCalls: 4, costUsd: 2.5 }), 10)).toBe(0.25);
+  });
+
+  it('has no share to report when there is no total, rather than reporting zero', () => {
+    // Same argument cacheRate makes: on a window where nothing was metered,
+    // 0.0% on every row reads as "these cost nothing relative to the rest"
+    // when the truth is that no price was reported at all. Live state — all
+    // four attributed tasks on the current ledger are unmetered.
+    expect(share(0, 0)).toBeNull();
+    expect(share(5, 0)).toBeNull();
+    expect(formatPercent(share(5, 0))).toBe('—');
+    expect(share(1, 4)).toBe(0.25);
+  });
+
+  it('buckets a rate, and refuses to bucket one it does not have', () => {
+    expect(rateClass(0.305)).toBe('rate-low');   // the AGT-4286 draft rate
+    expect(rateClass(0.5)).toBe('rate-mid');
+    expect(rateClass(0.85)).toBe('rate-high');   // where every other stage sat
+    expect(rateClass(null)).toBe('');
+  });
+
+  it('formats a cost small enough to round to zero without hiding it', () => {
+    expect(formatCost(0)).toBe('$0');
+    expect(formatCost(0.0043)).toBe('$0.0043');
+    expect(formatCost(56.38)).toBe('$56.38');
+    expect(formatCost(12345.67)).toBe('$12,345.67');   // grouped, like formatCount
+  });
+
+  it('does not print an exponential that is larger than the fixed range it escapes', () => {
+    // toExponential(1) rounds 9.99e-5 up to 1.0e-4, which sat in the column
+    // looking like a different kind of quantity than the $0.0001 beside it.
+    expect(formatCost(0.0000999)).toBe('$0.0001');
+    expect(formatCost(0.0001)).toBe('$0.0001');
+    expect(formatCost(0.0000036)).toBe('$3.6e-6');
+  });
+
+  it('abbreviates tokens, because the exact digit never matters', () => {
+    expect(formatTokens(999)).toBe('999');
+    expect(formatTokens(24_222)).toBe('24.2k');
+    expect(formatTokens(3_400_000)).toBe('3.4M');
+  });
+});
+
+describe('tables', () => {
+  beforeEach(() => { document.body.innerHTML = '<table id="t"></table>'; });
+
+  it('names the axis in the header instead of leaving the corner blank', () => {
+    const table = document.querySelector('#t')!;
+    renderTable(table, { by: 'model', rows: [row('qwen')], total: row('total') }, { label: '모델' });
+    expect(table.querySelector('thead th')?.textContent).toBe('모델');
+    // Falls back to the axis the aggregate names when no label is given.
+    renderTable(table, { by: 'stage', rows: [row('draft')], total: row('total') });
+    expect(table.querySelector('thead th')?.textContent).toBe('stage');
+  });
+
+  it('renders a row per key with the derived columns', () => {
+    const table = document.querySelector('#t')!;
+    renderTable(table, {
+      rows: [row('qwen', { costUsd: 3 }), row('deepseek', { costUsd: 1 })],
+      total: row('total', { costUsd: 4 }),
+    });
+
+    const cells = [...table.querySelectorAll('tbody tr')].map(tr =>
+      [...tr.querySelectorAll('td')].map(td => td.textContent));
+    expect(cells[0]?.[0]).toBe('qwen');
+    expect(cells[0]?.[3]).toBe('80.0%');   // cache rate
+    expect(cells[0]?.[6]).toBe('75.0%');   // share of a $4 total
+    expect(cells[1]?.[0]).toBe('deepseek');
+  });
+
+  it('says so when the window holds nothing', () => {
+    const table = document.querySelector('#t')!;
+    renderTable(table, { rows: [], total: row('total', { calls: 0, costUsd: 0 }) });
+    expect(table.querySelector('td')?.textContent).toContain('사용량이 없습니다');
+  });
+
+  it('colours a low cache rate so it stands out from its peers', () => {
+    const table = document.querySelector('#t')!;
+    renderTable(table, {
+      rows: [row('draft', { promptTokens: 1000, cachedTokens: 305 })],
+      total: row('total'),
+    });
+    expect(table.querySelector('td.rate-low')?.textContent).toBe('30.5%');
+  });
+
+  it('sorts by calls when asked, not by the cost order the API returns', () => {
+    // The API orders by cost. Calls-per-task is a different question and the
+    // task table exists to answer it.
+    const table = document.querySelector('#t')!;
+    renderTable(table, {
+      rows: [row('cheap-but-chatty', { calls: 989, costUsd: 1.4 }), row('pricey', { calls: 5, costUsd: 9 })],
+      total: row('total', { costUsd: 10.4 }),
+    }, { sortBy: 'calls' });
+    expect(table.querySelector('tbody td')?.textContent).toBe('cheap-but-chatty');
+  });
+
+  it('keeps a non-task out of a ranking of tasks', () => {
+    // The unattributed bucket outweighs every real task, so without this it
+    // sits at the top of "호출이 많은 순" and pushes them all below the fold.
+    const table = document.querySelector('#t')!;
+    renderTable(table, {
+      rows: [row(UNATTRIBUTED, { calls: 1499 }), row('audit-3-4', { calls: 66 })],
+      total: row('total'),
+    }, { sortBy: 'calls', excludeUnattributed: true });
+
+    const keys = [...table.querySelectorAll('tbody tr td:first-child')].map(td => td.textContent);
+    expect(keys).toEqual(['audit-3-4']);
+  });
+
+  it('still shows the unattributed bucket on axes where it is a real grouping', () => {
+    // On stage/model it is genuine spend and must not vanish.
+    const table = document.querySelector('#t')!;
+    renderTable(table, { rows: [row(UNATTRIBUTED, { calls: 1499 })], total: row('total') });
+    expect(table.querySelector('tbody td')?.textContent).toBe(UNATTRIBUTED);
+  });
+
+  it('caps how many rows it draws, and reports what it drew', () => {
+    const table = document.querySelector('#t')!;
+    const rows = Array.from({ length: 40 }, (_, i) => row(`m${i}`));
+    expect(renderTable(table, { rows, total: row('total') }, { limit: 5 }))
+      .toMatchObject({ rows: 40, drawn: 5, hidden: { count: 35 } });
+    expect(table.querySelectorAll('tbody tr')).toHaveLength(5);
+  });
+
+  it('names the rows it cut instead of dropping their spend silently', () => {
+    // Live state, not hypothetical: the project axis returns 67 rows over 30
+    // days and the panel draws 25 — 13% of spend, absent with no mention.
+    expect(truncationNote({ count: 5, costUsd: 5 })).toContain('5개 항목');
+    expect(truncationNote({ count: 5, costUsd: 5 })).toContain('$5.00');
+    expect(truncationNote({ count: 0, costUsd: 0 })).toBe('');
+    expect(truncationNote(undefined)).toBe('');
+  });
+
+  it('reports the cost of the rows IT hid, not of the aggregate tail', () => {
+    // The API orders by cost; this panel orders by calls. Re-slicing the
+    // aggregate therefore summed the cheapest rows instead of the hidden ones
+    // — $0.05 printed for $50.00 of absent spend. Whoever decides the order
+    // has to be the one who reports it.
+    const table = document.querySelector('#t')!;
+    const expensiveQuiet = Array.from({ length: 5 }, (_, i) =>
+      row(`nightly-${i}`, { calls: 1, costUsd: 10 }));
+    const cheapChatty = Array.from({ length: 30 }, (_, i) =>
+      row(`chatty-${i}`, { calls: 500, costUsd: 0.01 }));
+
+    const drew = renderTable(table, {
+      rows: [...expensiveQuiet, ...cheapChatty],   // aggregate order: cost desc
+      total: row('total', { costUsd: 50.3 }),
+    }, { sortBy: 'calls', limit: 30 });
+
+    // Sorted by calls, the five expensive-but-quiet rows fall off the end.
+    expect(drew.hidden.count).toBe(5);
+    expect(drew.hidden.costUsd).toBeCloseTo(50);
+    expect(truncationNote(drew.hidden)).toContain('$50.00');
+    const drawnKeys = [...table.querySelectorAll('tbody td:first-child')].map(td => td.textContent);
+    expect(drawnKeys).not.toContain('nightly-0');
+  });
+
+  it('puts the key in as text here too — the day label is the other raw-key path', () => {
+    // renderTable had this assertion; renderDays did not, and the mutation
+    // survived the whole suite.
+    document.body.innerHTML = '<div id="d"></div>';
+    renderDays(document.querySelector('#d')!, {
+      rows: [row('<img src=x onerror=alert(1)>')], total: row('total'),
+    });
+    expect(document.querySelector('#d .bar-day')?.textContent).toBe('<img src=x onerror=alert(1)>');
+    expect(document.querySelector('#d img')).toBeNull();
+  });
+
+  it('puts the full value on hover for the column that clips, and only that one', () => {
+    const table = document.querySelector('#t')!;
+    renderTable(table, { rows: [row('a-very-long-task-identifier-that-clips')], total: row('total') });
+    const cells = [...table.querySelectorAll('tbody td')] as HTMLElement[];
+    expect(cells[0].title).toBe('a-very-long-task-identifier-that-clips');
+    expect(cells.slice(1).every(td => td.title === '')).toBe(true);
+  });
+
+  it('does not claim nothing happened when the filter removed everything', () => {
+    // The task panel would otherwise print an exclusion note beside a table
+    // saying no usage was recorded.
+    const table = document.querySelector('#t')!;
+    renderTable(table, { rows: [row(UNATTRIBUTED, { calls: 9 })], total: row('total') },
+      { excludeUnattributed: true });
+    expect(table.querySelector('td')?.textContent).toContain('작업에 귀속되지 않았습니다');
+
+    renderTable(table, { rows: [], total: row('total') }, { excludeUnattributed: true });
+    expect(table.querySelector('td')?.textContent).toContain('사용량이 없습니다');
+  });
+
+  it('measures share against what the panel ranks, not the global total', () => {
+    // With the unattributed bucket excluded and holding all the spend, share
+    // of the global total is 0.0% on every row — three dead columns.
+    const table = document.querySelector('#t')!;
+    renderTable(table, {
+      rows: [row(UNATTRIBUTED, { costUsd: 100 }), row('a', { costUsd: 3 }), row('b', { costUsd: 1 })],
+      total: row('total', { costUsd: 104 }),
+    }, { excludeUnattributed: true });
+    const shares = [...table.querySelectorAll('tbody tr')].map(tr => tr.querySelectorAll('td')[6].textContent);
+    expect(shares).toEqual(['75.0%', '25.0%']);
+  });
+
+  it('puts ledger keys in as text, never as markup', () => {
+    const table = document.querySelector('#t')!;
+    renderTable(table, { rows: [row('<img src=x onerror=alert(1)>')], total: row('total') });
+    expect(table.querySelector('tbody td')?.textContent).toBe('<img src=x onerror=alert(1)>');
+    expect(table.querySelector('img')).toBeNull();
+  });
+});
+
+describe('day series', () => {
+  beforeEach(() => { document.body.innerHTML = '<div id="days"></div>'; });
+
+  it('orders oldest first and scales the bars to the busiest day', () => {
+    const days = document.querySelector('#days')!;
+    renderDays(days, {
+      rows: [row('2026-09-10', { costUsd: 25 }), row('2026-09-09', { costUsd: 50 })],
+      total: row('total', { costUsd: 75 }),
+    });
+    const labels = [...days.querySelectorAll('.bar-day')].map(el => el.textContent);
+    expect(labels).toEqual(['2026-09-09', '2026-09-10']);
+    const widths = [...days.querySelectorAll('.bar-fill')].map(el => (el as HTMLElement).style.width);
+    expect(widths).toEqual(['100%', '50%']);
+  });
+
+  it('does not divide by a zero peak when every day cost nothing', () => {
+    const days = document.querySelector('#days')!;
+    renderDays(days, { rows: [row('2026-09-10', { costUsd: 0 })], total: row('total', { costUsd: 0 }) });
+    expect((days.querySelector('.bar-fill') as HTMLElement).style.width).toBe('0%');
+  });
+
+  it('marks a day whose calls were free, so it does not read as no data', () => {
+    // Only metered providers report a price. A day of 170 unmetered calls
+    // draws a 0%-wide bar, which looks exactly like a day that never ran.
+    const days = document.querySelector('#days')!;
+    renderDays(days, {
+      rows: [row('2026-09-08', { calls: 170, meteredCalls: 0, costUsd: 0 }), row('2026-09-07', { costUsd: 4 })],
+      total: row('total', { costUsd: 4 }),
+    });
+    // Oldest first: 09-07 carries the cost and sets the peak, 09-08 is the free day.
+    const fills = [...days.querySelectorAll('.bar-fill')];
+    expect(fills[0].classList.contains('bar-fill-unmetered')).toBe(false);
+    expect(fills[1].classList.contains('bar-fill-unmetered')).toBe(true);
+  });
+
+  it('says so when the window holds nothing', () => {
+    const days = document.querySelector('#days')!;
+    renderDays(days, { rows: [], total: row('total') });
+    expect(days.textContent).toContain('사용량이 없습니다');
+  });
+});
+
+describe('attributed tasks (AGT-4288 number)', () => {
+  it('excludes the unattributed bucket from both the count and the calls', () => {
+    // `usageLedger` buckets every call with no taskId under one key. Counting
+    // it as a task, and its calls as task calls, read 340.6 calls/task against
+    // a true 53.3 on the ledger this was written from — 6.4x wrong, on the
+    // exact card written to reproduce AGT-4288.
+    const got = attributedTasks({
+      rows: [
+        row(UNATTRIBUTED, { calls: 1490 }),
+        row('audit-1-4', { calls: 60 }), row('audit-2-4', { calls: 53 }),
+        row('audit-3-4', { calls: 50 }), row('audit-4-4', { calls: 50 }),
+      ],
+      total: row('total', { calls: 1703 }),
+    });
+
+    expect(got).toEqual({ tasks: 4, calls: 213 });
+    expect(got.calls / got.tasks).toBeCloseTo(53.25);
+  });
+
+  it('reports nothing rather than zero tasks when only unattributed calls exist', () => {
+    expect(attributedTasks({ rows: [row(UNATTRIBUTED, { calls: 9 })], total: row('total') }))
+      .toEqual({ tasks: 0, calls: 0 });
+  });
+});
+
+describe('summary', () => {
+  beforeEach(mountShell);
+
+  it('reports calls per task — the ratio that reads as wrong, not the total', () => {
+    // AGT-4288's number: 13,287 calls over 239 tasks. The unattributed bucket
+    // rides along in the same axis and must not be counted as a 240th task.
+    renderSummary(document, {
+      model: { rows: [], total: row('total', { calls: 13287, meteredCalls: 13287, costUsd: 57.09 }) },
+      task: {
+        rows: [
+          row(UNATTRIBUTED, { calls: 4000 }),
+          ...Array.from({ length: 239 }, (_, i) => row(`t${i}`, { calls: 55 })),
+        ],
+        total: row('total'),
+      },
+    });
+    expect(document.querySelector('#sum-calls')?.textContent).toBe('13,287');
+    expect(document.querySelector('#sum-calls-note')?.textContent).toContain('239개 작업');
+    expect(document.querySelector('#sum-calls-note')?.textContent).toContain('55.0회');
+    // The headline is every call; the ratio is over attributed calls only.
+    // Without naming the remainder a reader divides 13,287/239 and lands 4x off.
+    expect(document.querySelector('#sum-calls-note')?.textContent).toContain('미귀속');
+    expect(document.querySelector('#sum-cost')?.textContent).toBe('$57.09');
+  });
+
+  it('names the unmetered calls instead of quietly under-reporting cost', () => {
+    renderSummary(document, {
+      model: { rows: [], total: row('total', { calls: 100, meteredCalls: 60, costUsd: 3 }) },
+      task: { rows: [], total: row('total') },
+    });
+    expect(document.querySelector('#sum-cost-note')?.textContent).toContain('40');
+  });
+
+  it('survives a window with no tasks at all', () => {
+    renderSummary(document, {
+      model: { rows: [], total: row('total', { calls: 0, meteredCalls: 0, promptTokens: 0, cachedTokens: 0, completionTokens: 0, costUsd: 0 }) },
+      task: { rows: [], total: row('total') },
+    });
+    expect(document.querySelector('#sum-calls-note')?.textContent).toBe('');
+    expect(document.querySelector('#sum-cache')?.textContent).toBe('—');
+  });
+});
+
+describe('loading', () => {
+  beforeEach(mountShell);
+
+  const ok = (by: string) => ({
+    ok: true,
+    json: async () => ({ since: '2026-09-09T00:00:00.000Z', until: '2026-09-10T00:00:00.000Z', by, rows: [row(`${by}-a`)], total: row('total') }),
+  });
+
+  it('asks for every axis in one window', async () => {
+    const fetchImpl = vi.fn(async (url: string) => ok(new URL(url, 'http://x').searchParams.get('by')!));
+    const data = await loadUsage('7d', fetchImpl as never);
+
+    const asked = fetchImpl.mock.calls.map(([url]) => new URL(url as string, 'http://x').searchParams.get('by'));
+    expect(asked.sort()).toEqual(['adapter', 'day', 'model', 'project', 'stage', 'task']);
+    expect(fetchImpl.mock.calls.every(([url]) => (url as string).includes('since=7d'))).toBe(true);
+    expect(data.model.rows[0].key).toBe('model-a');
+  });
+
+  it('fills the page from a fetched window', async () => {
+    const fetchImpl = vi.fn(async (url: string) => ok(new URL(url, 'http://x').searchParams.get('by')!));
+    await startUsageView({ fetchImpl: fetchImpl as never }).refresh();
+
+    expect(document.querySelector('#table-model tbody td')?.textContent).toBe('model-a');
+    expect(document.querySelector('#table-stage tbody td')?.textContent).toBe('stage-a');
+    expect(document.querySelector('#days .bar-day')?.textContent).toBe('day-a');
+    expect(document.querySelector('#status')?.textContent).toContain('기준');
+  });
+
+  it('names the token case instead of reading as a dead daemon', async () => {
+    // A 403 from a Tailscale browser is the missing-token case. Reporting it
+    // as a generic failure is what made the dashboard look dead before.
+    const fetchImpl = vi.fn(async () => ({ ok: false, status: 403, json: async () => ({}) }));
+    await startUsageView({ fetchImpl: fetchImpl as never }).refresh();
+    expect(document.querySelector('#status')?.textContent).toContain('웹 토큰');
+  });
+
+  it('applies a pasted token through the wrapper, not a second storage key', async () => {
+    // The panel markup shipped with warehouse.html; copying it without wiring
+    // it would leave a field that looks like it does something and does not.
+    // Attach to the real jsdom window and take it back off. Replacing
+    // `globalThis.window` outright would clobber the document every later test
+    // in this file renders into.
+    const storeToken = vi.fn();
+    (window as unknown as Record<string, unknown>).OpenSwarmWebToken = { storeToken };
+    onTestFinished(() => { delete (window as unknown as Record<string, unknown>).OpenSwarmWebToken; });
+    const fetchImpl = vi.fn(async (url: string) => ok(new URL(url, 'http://x').searchParams.get('by')!));
+    startUsageView({ fetchImpl: fetchImpl as never, location: { search: '' } as never });
+
+    (document.querySelector('#web-token') as HTMLInputElement).value = 'secret';
+    (document.querySelector('#save-token') as HTMLButtonElement).click();
+
+    expect(storeToken).toHaveBeenCalledWith('secret');
+    // Cleared from the field so the credential does not sit in the DOM.
+    expect((document.querySelector('#web-token') as HTMLInputElement).value).toBe('');
+    await vi.waitFor(() => expect(fetchImpl).toHaveBeenCalled());
+
+    (document.querySelector('#clear-token') as HTMLButtonElement).click();
+    expect(storeToken).toHaveBeenLastCalledWith('');
+  });
+
+  it('lets the newest window win when a slow one lands second', async () => {
+    // Pick 7d, change your mind, pick 24h. The 7d response arrives last and
+    // would paint over the 24h one — leaving the select, the URL and the
+    // status line all naming a window that none of the numbers belong to.
+    let release: (() => void) | undefined;
+    const slow = new Promise<void>((r) => { release = r; });
+    const fetchImpl = vi.fn(async (url: string) => {
+      const u = new URL(url, 'http://x');
+      const since = u.searchParams.get('since');
+      const by = u.searchParams.get('by')!;
+      if (since === '7d') await slow;
+      return {
+        ok: true,
+        json: async () => ({ by, rows: [row(`${by}-from-${since}`)], total: row('total') }),
+      };
+    });
+    const view = startUsageView({ fetchImpl: fetchImpl as never, location: { search: '' } as never });
+    const select = document.querySelector('#window') as HTMLSelectElement;
+
+    select.value = '7d';
+    const first = view.refresh();
+    select.value = '24h';
+    await view.refresh();
+    release!();
+    await first;
+
+    expect(document.querySelector('#table-model tbody td')?.textContent).toBe('model-from-24h');
+  });
+
+  it('refuses an empty 적용 instead of deleting the token that is working', async () => {
+    // `storeToken('')` is the wrapper's REMOVE path, and the field is empty in
+    // exactly the case that matters — it is cleared after each use and the
+    // wrapper's own prompt never fills it. One stray click would log a
+    // Tailscale operator out page-wide.
+    const storeToken = vi.fn();
+    (window as unknown as Record<string, unknown>).OpenSwarmWebToken = { storeToken };
+    onTestFinished(() => { delete (window as unknown as Record<string, unknown>).OpenSwarmWebToken; });
+    const fetchImpl = vi.fn(async (url: string) => ok(new URL(url, 'http://x').searchParams.get('by')!));
+    startUsageView({ fetchImpl: fetchImpl as never, location: { search: '' } as never });
+
+    (document.querySelector('#web-token') as HTMLInputElement).value = '   ';
+    (document.querySelector('#save-token') as HTMLButtonElement).click();
+
+    expect(storeToken).not.toHaveBeenCalled();
+    expect(document.querySelector('#status')?.textContent).toContain('입력한 뒤');
+    // 지우기 is still an explicit, separate action.
+    (document.querySelector('#clear-token') as HTMLButtonElement).click();
+    expect(storeToken).toHaveBeenCalledWith('');
+  });
+
+  it('rewrites a window the API would accept but the page does not offer', async () => {
+    // `?since=90m` parses server-side but is not in the selector, so the page
+    // rendered 24h under a URL claiming 90m — silently, on a shared link.
+    const replaceState = vi.fn();
+    const history = { replaceState };
+    const original = globalThis.history;
+    Object.defineProperty(globalThis, 'history', { value: history, configurable: true });
+    onTestFinished(() => {
+      Object.defineProperty(globalThis, 'history', { value: original, configurable: true });
+    });
+    const fetchImpl = vi.fn(async (url: string) => ok(new URL(url, 'http://x').searchParams.get('by')!));
+
+    startUsageView({ fetchImpl: fetchImpl as never, location: { search: '?since=90m' } as never });
+
+    expect(replaceState).toHaveBeenCalled();
+    expect(String(replaceState.mock.calls[0][2])).toContain('since=24h');
+  });
+
+  it('orders the task table by calls at the call site, not just when asked directly', async () => {
+    // The heading says "호출이 많은 순". Dropping the option at the call site
+    // silently orders by cost and no existing test noticed.
+    const fetchImpl = vi.fn(async (url: string) => {
+      const by = new URL(url, 'http://x').searchParams.get('by')!;
+      const rows = by === 'task'
+        ? [row('pricey', { calls: 5, costUsd: 9 }), row('chatty', { calls: 989, costUsd: 1.4 })]
+        : [row(`${by}-a`)];
+      return { ok: true, json: async () => ({ by, rows, total: row('total', { costUsd: 10.4 }) }) };
+    });
+
+    await startUsageView({ fetchImpl: fetchImpl as never, location: { search: '' } as never }).refresh();
+
+    expect(document.querySelector('#table-task tbody td')?.textContent).toBe('chatty');
+  });
+
+  it('names the calls it left out of the task ranking instead of just dropping them', async () => {
+    const fetchImpl = vi.fn(async (url: string) => {
+      const by = new URL(url, 'http://x').searchParams.get('by')!;
+      const rows = by === 'task'
+        ? [row(UNATTRIBUTED, { calls: 1499, costUsd: 0.47 }), row('audit-3-4', { calls: 66 })]
+        : [row(`${by}-a`)];
+      return { ok: true, json: async () => ({ by, rows, total: row('total') }) };
+    });
+
+    await startUsageView({ fetchImpl: fetchImpl as never, location: { search: '' } as never }).refresh();
+
+    const note = document.querySelector('#task-note')?.textContent ?? '';
+    expect(note).toContain('1,499');
+    expect(note).toContain('$0.47');
+    expect(document.querySelector('#table-task tbody td')?.textContent).toBe('audit-3-4');
+  });
+
+  it('keeps the controls on the window whose numbers are on screen when a load fails', async () => {
+    // The other half of the race the sequence token fixes. Switching to a
+    // window that fails left the select and the URL naming it while every
+    // figure was still the previous load's.
+    let failNext = false;
+    const fetchImpl = vi.fn(async (url: string) => {
+      if (failNext) throw new Error('network down');
+      return ok(new URL(url, 'http://x').searchParams.get('by')!);
+    });
+    const replaceState = vi.fn();
+    const original = globalThis.history;
+    Object.defineProperty(globalThis, 'history', { value: { replaceState }, configurable: true });
+    onTestFinished(() => {
+      Object.defineProperty(globalThis, 'history', { value: original, configurable: true });
+    });
+
+    const view = startUsageView({ fetchImpl: fetchImpl as never, location: { search: '' } as never });
+    await view.refresh();                       // 24h renders
+    const select = document.querySelector('#window') as HTMLSelectElement;
+    select.value = '30d';
+    failNext = true;
+    await view.refresh();                       // 30d fails
+
+    expect(select.value).toBe('24h');
+    expect(String(replaceState.mock.calls.at(-1)?.[2])).toContain('since=24h');
+    expect(document.querySelector('#status')?.textContent).toContain('24h 데이터를 유지합니다');
+    expect(document.querySelector('#table-model tbody td')?.textContent).toBe('model-a');
+  });
+
+  it('does not let a slow failure clear a newer good render', async () => {
+    // The catch path needs the sequence guard too.
+    let release: (() => void) | undefined;
+    const slow = new Promise<void>((r) => { release = r; });
+    const fetchImpl = vi.fn(async (url: string) => {
+      const u = new URL(url, 'http://x');
+      if (u.searchParams.get('since') === '7d') { await slow; throw new Error('slow failure'); }
+      return ok(u.searchParams.get('by')!);
+    });
+    const view = startUsageView({ fetchImpl: fetchImpl as never, location: { search: '' } as never });
+    const select = document.querySelector('#window') as HTMLSelectElement;
+
+    select.value = '7d';
+    const first = view.refresh();
+    select.value = '24h';
+    await view.refresh();
+    release!();
+    await first;
+
+    expect(document.querySelector('#status')?.textContent).toContain('기준');
+    expect(select.value).toBe('24h');
+  });
+
+  it('reports a failed axis rather than leaving the page on 불러오는 중', async () => {
+    const fetchImpl = vi.fn(async () => { throw new Error('network down'); });
+    await startUsageView({ fetchImpl: fetchImpl as never }).refresh();
+    expect(document.querySelector('#status')?.textContent).toContain('network down');
+  });
+
+  it('opens on the window the URL names, so a 30-day view can be linked', async () => {
+    // Also the only way to tell an empty window from a broken page: ask for a
+    // window you know has data.
+    const fetchImpl = vi.fn(async (url: string) => ok(new URL(url, 'http://x').searchParams.get('by')!));
+    await startUsageView({ fetchImpl: fetchImpl as never, location: { search: '?since=30d' } as never }).refresh();
+    expect((document.querySelector('#window') as HTMLSelectElement).value).toBe('30d');
+    expect(fetchImpl.mock.calls[0][0] as string).toContain('since=30d');
+  });
+
+  it('ignores a window the selector does not offer', () => {
+    expect(windowFromSearch('?since=30d')).toBe('30d');
+    expect(windowFromSearch('?since=99y')).toBeNull();
+    expect(windowFromSearch('')).toBeNull();
+    expect(windowFromSearch(undefined)).toBeNull();
+  });
+
+  it('reloads when the window changes', async () => {
+    const fetchImpl = vi.fn(async (url: string) => ok(new URL(url, 'http://x').searchParams.get('by')!));
+    startUsageView({ fetchImpl: fetchImpl as never });
+    const select = document.querySelector('#window') as HTMLSelectElement;
+    select.value = '30d';
+    select.dispatchEvent(new Event('change'));
+    await vi.waitFor(() => expect(fetchImpl).toHaveBeenCalled());
+    expect((fetchImpl.mock.calls[0][0] as string)).toContain('since=30d');
+  });
+});
diff --git a/tests/web/usageLayout.test.ts b/tests/web/usageLayout.test.ts
new file mode 100644
index 00000000..a7224b96
--- /dev/null
+++ b/tests/web/usageLayout.test.ts
@@ -0,0 +1,61 @@
+// Two properties this page needs that jsdom cannot see, so they are asserted
+// against the stylesheet text instead (AGT-4289).
+//
+// Both were shipped wrong once. The cache-rate colour was scoped to `td` while
+// the headline stat is a `<strong>`, so the one number the page is built
+// around rendered in the neutral colour — and the jsdom test passed, because
+// it asserted the class name and jsdom computes no colours. The grid floor was
+// set to 38rem, which looked right and was not: `auto-fit` answers a higher
+// floor with MORE tracks, so the panel stayed narrower than its table and the
+// 비용 column stayed off-screen.
+//
+// A real-browser check belongs in a rendering run, not the unit suite. These
+// are the tripwires that fire when someone edits the two declarations that
+// were wrong before.
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const RAW = readFileSync(resolve(__dirname, '../../web/static/css/usage.css'), 'utf8');
+/**
+ * Rules only.
+ *
+ * These assertions are about what the stylesheet declares, and this file
+ * explains its own history in prose — the first version of the `td.rate-low`
+ * check matched the sentence describing the bug it was guarding against.
+ */
+const CSS = RAW.replace(/\/\*[\s\S]*?\*\//g, '');
+
+describe('usage.css invariants', () => {
+  it('does not scope the rate colours to table cells', () => {
+    // `td.rate-low` would leave #sum-cache uncoloured.
+    expect(CSS).toMatch(/^\.rate-low\s/m);
+    expect(CSS).not.toMatch(/\btd\.rate-(low|mid|high)\b/);
+  });
+
+  it('defines all three rate buckets against palette tokens', () => {
+    for (const [cls, token] of [['low', 'danger'], ['mid', 'warning'], ['high', 'success']]) {
+      expect(CSS).toMatch(new RegExp(`\\.rate-${cls}\\s*\\{[^}]*var\\(--${token}\\)`));
+    }
+  });
+
+  it('keeps the grid floor wide enough for the table it holds', () => {
+    // Measured in Chromium against the real ledger: the widest table needs
+    // 774px, and auto-fit pins a track at its floor. Below ~48rem the 비용 and
+    // 점유 columns clip at every desktop width.
+    // Anchored to `.grid`: `.summary` uses auto-fit too and comes first in the
+    // file, so an unanchored match would report the wrong rule.
+    const m = /\.grid\s*\{[^}]*grid-template-columns:\s*repeat\(auto-fit,\s*minmax\(min\((\d+)rem/.exec(CSS);
+    expect(m, 'grid floor declaration not found — was .grid rewritten?').not.toBeNull();
+    expect(Number(m![1])).toBeGreaterThanOrEqual(50);
+  });
+
+  it('keeps the floor collapsible so a phone gets one column instead of overflow', () => {
+    expect(CSS).toMatch(/\.grid\s*\{[^}]*minmax\(min\(\d+rem,\s*100%\)/);
+  });
+
+  it('scrolls wide content inside its own box', () => {
+    expect(CSS).toMatch(/\.table-wrap\s*\{[^}]*overflow-x:\s*auto/);
+  });
+});
diff --git a/web/static/app.html b/web/static/app.html
index 2366aaf6..483966c7 100644
--- a/web/static/app.html
+++ b/web/static/app.html
@@ -22,6 +22,7 @@
       <a href="/orchestration">Orchestration</a>
       <a href="/threads">Threads</a>
       <a href="/warehouse">Warehouse</a>
+      <a href="/usage">Usage</a>
       <a href="/">Supervisor</a>
     </nav>
     <div class="topbar-spacer"></div>
diff --git a/web/static/chat.html b/web/static/chat.html
index 97b3969e..a3ced97f 100644
--- a/web/static/chat.html
+++ b/web/static/chat.html
@@ -20,6 +20,7 @@
       <a href="/orchestration">Orchestration</a>
       <a href="/threads">Threads</a>
       <a href="/warehouse">Warehouse</a>
+      <a href="/usage">Usage</a>
       <a href="/">Supervisor</a>
     </nav>
     <div class="topbar-spacer"></div>
diff --git a/web/static/css/usage.css b/web/static/css/usage.css
new file mode 100644
index 00000000..444386a1
--- /dev/null
+++ b/web/static/css/usage.css
@@ -0,0 +1,123 @@
+/* Usage dashboard layout (AGT-4289).
+   Every colour is an indirection into tokens.css — no literal lives here
+   (AGT-4201), so the page follows the shared palette and the light/dark
+   switch without a second source of truth. */
+
+.usage-main {
+  padding: var(--space-4);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+  overflow-y: auto;
+}
+
+/* --- summary --- */
+
+.summary {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(11rem, 1fr));
+  gap: var(--space-3);
+}
+
+.stat { padding: var(--space-3); display: flex; flex-direction: column; gap: var(--space-1); }
+.stat-label { font-size: var(--text-xs); color: var(--fg-muted); text-transform: uppercase; letter-spacing: 0.08em; }
+.stat-value { font-family: var(--font-mono); font-size: var(--text-xl); color: var(--fg-primary); }
+.stat-note  { font-size: var(--text-xs); color: var(--fg-muted); min-height: 1em; }
+
+/* --- panels --- */
+
+.panel .card-head {
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: var(--fg-secondary);
+  padding: var(--space-2) var(--space-3);
+  border-bottom: 1px solid var(--border);
+}
+
+/* The floor has to be at least the table's own width, because `auto-fit`
+   spends extra viewport on MORE columns, never wider ones — it packs as many
+   tracks as fit at the floor and then stretches them by whatever is left over.
+   A 22rem floor pinned every panel near 403-458px against a 774px table, so
+   비용 and 점유 — the two columns this page exists for — sat off the right
+   edge at 1280, 1440, 1920 and 2560. Raising it to 38rem did not help: three
+   tracks then fit at 1920 and the panel stayed at 617px. Measured, not
+   reasoned — the 38rem version looked correct and was not.
+
+   50rem (800px) exceeds the 774px the widest table needs, so a track can
+   never be narrower than its content. `min(…, 100%)` keeps a phone at one
+   column instead of overflowing. Resulting panels: 1248px at 1280 (1 track),
+   940px at 1920 (2), 830px at 2560 (3) — all above 774. */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(50rem, 100%), 1fr));
+  gap: var(--space-4);
+}
+
+/* Wide content scrolls inside its own box; the page never scrolls sideways. */
+.table-wrap { overflow-x: auto; }
+
+table { width: 100%; border-collapse: collapse; font-size: var(--text-sm); }
+th, td { padding: var(--space-2) var(--space-3); text-align: right; white-space: nowrap; }
+th:first-child, td:first-child { text-align: left; }
+thead th {
+  font-size: var(--text-xs);
+  font-weight: 600;
+  color: var(--fg-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  border-bottom: 1px solid var(--border);
+}
+tbody tr + tr td { border-top: 1px solid var(--border); }
+tbody tr:hover td { background: var(--bg-hover); }
+td.num, td.key { font-family: var(--font-mono); }
+td.key { color: var(--fg-primary); max-width: 22rem; overflow: hidden; text-overflow: ellipsis; }
+
+/* A rate far below its peers is the signal this page exists for (AGT-4286 was
+   a 30.5% cache rate beside 83-88%), so give it a colour.
+
+   Not scoped to `td`: the same classes go on the summary card's <strong>, and
+   a `td.rate-low` selector left the one headline number this page is built
+   around rendering in the neutral text colour while the table cell beside it
+   was red. The jsdom test asserted the class name, so it passed. */
+.rate-low  { color: var(--danger); }
+.rate-mid  { color: var(--warning); }
+.rate-high { color: var(--success); }
+
+/* --- day bars --- */
+
+.bars { display: flex; flex-direction: column; gap: var(--space-1); padding: var(--space-3); }
+.bar-row { display: grid; grid-template-columns: 6rem 1fr auto; align-items: center; gap: var(--space-3); }
+.bar-day { font-family: var(--font-mono); font-size: var(--text-xs); color: var(--fg-muted); }
+.bar-track { background: var(--bg-elevated); border-radius: var(--radius-sm); height: 1.1rem; overflow: hidden; }
+.bar-fill { background: var(--chart-1); height: 100%; min-width: 1px; }
+.bar-value { font-family: var(--font-mono); font-size: var(--text-xs); color: var(--fg-secondary); }
+
+/* --- access --- */
+
+.access .card-body { display: flex; flex-direction: column; gap: var(--space-2); align-items: flex-start; }
+.token-row { display: flex; gap: var(--space-2); width: min(28rem, 100%); }
+.token-row .input { flex: 1; }
+.text-button { background: none; border: 0; padding: 0; color: var(--fg-muted); font-size: var(--text-xs); cursor: pointer; text-decoration: underline; }
+
+/* Not `.empty`: shell.css defines that as a centred grid with its own padding,
+   so the message rendered centred with the wrong spacing. (The cell keeps its
+   width and colSpan either way — measured — so this is about appearance, not
+   layout collapse.) */
+.usage-empty {
+  display: table-cell;
+  color: var(--fg-muted);
+  padding: var(--space-3);
+  font-size: var(--text-sm);
+  text-align: left;
+}
+
+@media (max-width: 40rem) {
+  .bar-row { grid-template-columns: 4.5rem 1fr auto; }
+  .usage-main { padding: var(--space-2); }
+}
+
+/* A day with calls but no metered cost. Wide enough to see, narrow enough not
+   to claim a magnitude it does not have. */
+.bar-fill-unmetered { min-width: 3px; background: var(--border-strong); }
+
+.task-note { padding: var(--space-2) var(--space-3) 0; font-size: var(--text-xs); }
diff --git a/web/static/js/usage.mjs b/web/static/js/usage.mjs
new file mode 100644
index 00000000..f8f82bfb
--- /dev/null
+++ b/web/static/js/usage.mjs
@@ -0,0 +1,444 @@
+// Usage dashboard — the token/cost ledger, on a screen. (AGT-4289)
+//
+// `/api/usage` has served six axes since AGT-4178 and had no frontend reader;
+// the only consumer was the `openswarm cost` CLI. Two defects found by hand-
+// querying that ledger over ssh were each a single number on an axis it
+// already serves: a 30.5% draft cache rate beside 83-88% everywhere else
+// (AGT-4286), and 13,287 draft calls across 239 tasks (AGT-4288).
+//
+// The endpoint groups by ONE axis per request, so this fetches several in
+// parallel rather than changing the aggregate. The derived columns —
+// cache rate, cost per call, calls per task — are the ones that carry the
+// cost signal; the raw rows do not have them.
+
+const AXES = ['day', 'model', 'stage', 'adapter', 'project', 'task'];
+
+/**
+ * cachedTokens / promptTokens, or null when there is nothing to divide.
+ *
+ * Null rather than 0: a stage that made no prompt-token calls has no cache
+ * rate, and showing it as 0% would put it next to the genuinely uncached ones
+ * this page exists to surface.
+ */
+export function cacheRate(row) {
+  const prompt = row?.promptTokens ?? 0;
+  if (prompt <= 0) return null;
+  return (row.cachedTokens ?? 0) / prompt;
+}
+
+/**
+ * A row's share of the total, or null when there is no total to be a share of.
+ *
+ * Null, not 0, for the reason `cacheRate` gives above: an unmetered window has
+ * no cost to divide, and printing 0.0% puts every row of it beside rows that
+ * genuinely cost nothing relative to their peers. On the ledger this was
+ * written against all four attributed tasks are unmetered, so the whole 점유
+ * column read 0.0% while 호출당 in the same row honestly read `—`.
+ */
+export function share(value, total) {
+  if (!total || total <= 0) return null;
+  return value / total;
+}
+
+/**
+ * A row's share of `total`, or null when the row reported no price at all.
+ *
+ * `share` alone answers the aggregate-level question — is there a total to
+ * divide? This answers the row-level one, and they are different: on the live
+ * ledger `gpt-5.6-terra` carries 65% of all calls with no price reported, so
+ * it read `—` under 호출당 ("we have no price") and `0.0%` under 점유 ("we
+ * know its price and it is nothing") in the same row. Same gate `costPerCall`
+ * uses, for the same reason.
+ */
+export function rowShare(row, total) {
+  if ((row?.meteredCalls ?? 0) <= 0) return null;
+  return share(row.costUsd ?? 0, total);
+}
+
+/** Cost divided over the calls that actually reported a price. */
+export function costPerCall(row) {
+  const metered = row?.meteredCalls ?? 0;
+  if (metered <= 0) return null;
+  return (row.costUsd ?? 0) / metered;
+}
+
+/** Bucket a rate for colouring. Unknown rates get no class rather than a bad one. */
+export function rateClass(rate) {
+  if (rate === null || rate === undefined) return '';
+  if (rate < 0.4) return 'rate-low';
+  if (rate < 0.7) return 'rate-mid';
+  return 'rate-high';
+}
+
+export function formatCost(usd) {
+  const n = usd ?? 0;
+  if (n === 0) return '$0';
+  // Per-call costs get small as a window gets large: at 132k calls for $0.47
+  // every row rounds to $0.0000 with four places, and the column goes dead
+  // exactly when the window is big enough to be worth reading.
+  // Below the point where toExponential(1) would round the mantissa to 10 and
+  // print $1.0e-4 for a value smaller than the $0.0001 shown as fixed.
+  if (Math.abs(n) < 0.00005) return `$${n.toExponential(1)}`;
+  if (Math.abs(n) < 0.01) return `$${n.toFixed(4)}`;
+  // Group thousands, like formatCount does — these sit in adjacent columns.
+  return `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+export function formatCount(n) {
+  return (n ?? 0).toLocaleString('en-US');
+}
+
+/** Tokens are large and their exact value never matters — 1.2M reads, 1203481 does not. */
+export function formatTokens(n) {
+  const v = n ?? 0;
+  if (v >= 1e9) return `${(v / 1e9).toFixed(1)}B`;
+  if (v >= 1e6) return `${(v / 1e6).toFixed(1)}M`;
+  if (v >= 1e3) return `${(v / 1e3).toFixed(1)}k`;
+  return String(v);
+}
+
+export function formatPercent(rate) {
+  if (rate === null || rate === undefined) return '—';
+  return `${(rate * 100).toFixed(1)}%`;
+}
+
+function cell(text, className, { titled = false } = {}) {
+  const td = document.createElement('td');
+  td.textContent = text;
+  // Only the key column clips (max-width + overflow hidden, and the cell does
+  // not scroll), so only it needs the full value on hover. Numbers are short
+  // and a tooltip on each would be seven redundant ones per row.
+  if (titled) td.title = text;
+  if (className) td.className = className;
+  return td;
+}
+
+/**
+ * Render one axis as a table.
+ *
+ * Values go in through textContent: every key here is ledger data — a model
+ * id, a task identifier, a project directory name — and none of it is ours.
+ */
+/**
+ * Say what a table left out.
+ *
+ * Takes the tally `renderTable` returns rather than re-deriving it. The first
+ * version re-sliced the aggregate, which is ordered by cost — but the task
+ * panel sorts by calls inside `renderTable`, so the caller summed the cheapest
+ * tail instead of the rows actually hidden and printed $0.05 for $50.00 of
+ * absent spend. Whoever decides the order has to be the one who reports it.
+ */
+export function truncationNote(hidden) {
+  if (!hidden || hidden.count <= 0) return '';
+  return `그 외 ${formatCount(hidden.count)}개 항목(${formatCost(hidden.costUsd)})은 표시하지 않았습니다.`;
+}
+
+export function renderTable(table, aggregate, { limit = 25, sortBy = 'cost', label = '', excludeUnattributed = false } = {}) {
+  table.replaceChildren();
+  // A ranking of tasks must not be topped by the bucket for calls that named
+  // no task: it outweighs every real row and pushes them all below the fold.
+  const rows = [...(aggregate?.rows ?? [])].filter(r => !excludeUnattributed || r.key !== UNATTRIBUTED);
+  // Share is of what this panel ranks. Against the global total, every row in
+  // a panel whose excluded bucket holds all the spend reads 0.0%.
+  const shareBase = excludeUnattributed
+    ? rows.reduce((n, r) => n + (r.costUsd ?? 0), 0)
+    : (aggregate?.total?.costUsd ?? 0);
+  if (rows.length === 0) {
+    // "No usage recorded" is false when there WAS usage and the filter removed
+    // it — the task panel would otherwise print an exclusion note beside a
+    // table claiming nothing happened.
+    const filteredAll = excludeUnattributed && (aggregate?.rows?.length ?? 0) > 0;
+    const body = document.createElement('tbody');
+    const tr = document.createElement('tr');
+    const td = cell(filteredAll
+      ? '이 기간의 호출은 모두 작업에 귀속되지 않았습니다.'
+      : '이 기간에 기록된 사용량이 없습니다.', 'usage-empty');
+    td.colSpan = 7;
+    tr.append(td);
+    body.append(tr);
+    table.append(body);
+    return { rows: 0, drawn: 0, hidden: { count: 0, costUsd: 0 } };
+  }
+  if (sortBy === 'calls') rows.sort((a, b) => (b.calls ?? 0) - (a.calls ?? 0));
+
+  const head = document.createElement('thead');
+  const headRow = document.createElement('tr');
+  for (const heading of [label || aggregate?.by || '', '호출', '토큰', '캐시', '호출당', '비용', '점유']) {
+    const th = document.createElement('th');
+    th.textContent = heading;
+    th.scope = 'col';
+    headRow.append(th);
+  }
+  head.append(headRow);
+
+  const body = document.createElement('tbody');
+  const drawn = rows.slice(0, limit);
+  const cut = rows.slice(limit);
+  for (const row of drawn) {
+    const tr = document.createElement('tr');
+    const rate = cacheRate(row);
+    const per = costPerCall(row);
+    tr.append(
+      cell(row.key, 'key', { titled: true }),
+      cell(formatCount(row.calls), 'num'),
+      cell(formatTokens((row.promptTokens ?? 0) + (row.completionTokens ?? 0)), 'num'),
+      cell(formatPercent(rate), `num ${rateClass(rate)}`.trim()),
+      cell(per === null ? '—' : formatCost(per), 'num'),
+      cell(formatCost(row.costUsd), 'num'),
+      cell(formatPercent(rowShare(row, shareBase)), 'num'),
+    );
+    body.append(tr);
+  }
+  table.append(head, body);
+  return {
+    rows: rows.length,
+    drawn: drawn.length,
+    hidden: { count: cut.length, costUsd: cut.reduce((n, r) => n + (r.costUsd ?? 0), 0) },
+  };
+}
+
+/** Render the day axis as bars, oldest first — a series read left to right in time. */
+export function renderDays(container, aggregate) {
+  container.replaceChildren();
+  const rows = [...(aggregate?.rows ?? [])].sort((a, b) => String(a.key).localeCompare(String(b.key)));
+  if (rows.length === 0) {
+    const p = document.createElement('p');
+    p.className = 'usage-empty';
+    p.textContent = '이 기간에 기록된 사용량이 없습니다.';
+    container.append(p);
+    return;
+  }
+  // Scale to the busiest day, not to the total: the shape of the series is
+  // what is being read, and a fixed scale would flatten every quiet day.
+  //
+  // Cost is the axis because cost is what this page is for, but it is also
+  // optional — only metered providers report a price, and on the ledger this
+  // was written against two thirds of calls had none. A day of 170 unmetered
+  // calls costs $0 and would draw an empty track, which reads as "no data"
+  // rather than "no charge". Every row here has at least one call (the
+  // aggregate creates no row otherwise), so any row that drew nothing gets a
+  // marker instead: present, and not worth measuring.
+  const peak = Math.max(...rows.map(r => r.costUsd ?? 0), 0);
+  for (const row of rows) {
+    const line = document.createElement('div');
+    line.className = 'bar-row';
+
+    const day = document.createElement('span');
+    day.className = 'bar-day';
+    day.textContent = row.key;
+
+    const track = document.createElement('div');
+    track.className = 'bar-track';
+    const fill = document.createElement('div');
+    fill.className = 'bar-fill';
+    const fraction = peak > 0 ? (row.costUsd ?? 0) / peak : 0;
+    fill.style.width = `${fraction * 100}%`;
+    if (fraction === 0) fill.classList.add('bar-fill-unmetered');
+    track.append(fill);
+
+    const value = document.createElement('span');
+    value.className = 'bar-value';
+    value.textContent = `${formatCost(row.costUsd)} · ${formatCount(row.calls)}회`;
+
+    line.append(day, track, value);
+    container.append(line);
+  }
+}
+
+/** The bucket `usageLedger` gives every call that named no task. */
+export const UNATTRIBUTED = '(unattributed)';
+
+/** Tasks and their calls, with the unattributed bucket excluded from both. */
+export function attributedTasks(aggregate) {
+  const rows = (aggregate?.rows ?? []).filter(r => r.key !== UNATTRIBUTED);
+  return { tasks: rows.length, calls: rows.reduce((n, r) => n + (r.calls ?? 0), 0) };
+}
+
+/** Fill the four summary cards from the model axis, plus calls-per-task. */
+export function renderSummary(root, { model, task }) {
+  const total = model?.total ?? {};
+  const set = (id, text) => {
+    const el = root.querySelector(`#${id}`);
+    if (el) el.textContent = text;
+  };
+  set('sum-cost', formatCost(total.costUsd));
+  const unmetered = (total.calls ?? 0) - (total.meteredCalls ?? 0);
+  set('sum-cost-note', unmetered > 0 ? `${formatCount(unmetered)}회는 가격 미보고` : '');
+
+  set('sum-calls', formatCount(total.calls));
+  // The AGT-4288 number. It is the ratio, not the total, that reads as wrong —
+  // so the ratio has to be right. `usageLedger` buckets every call with no
+  // taskId under one '(unattributed)' key, which is not a task: counting it as
+  // one, and its calls as task calls, read 340.6 against a true 53.3 on the
+  // ledger this was written from.
+  const attributed = attributedTasks(task);
+  // Name the remainder, the way the 비용 card names its unmetered calls. The
+  // headline is every call; the ratio is over attributed calls only, and a
+  // reader dividing the headline by the task count lands 8x off.
+  const loose = (total.calls ?? 0) - attributed.calls;
+  set('sum-calls-note', attributed.tasks > 0
+    ? `${formatCount(attributed.tasks)}개 작업 · 작업당 ${(attributed.calls / attributed.tasks).toFixed(1)}회`
+      + (loose > 0 ? ` · ${formatCount(loose)}회 미귀속` : '')
+    : '');
+
+  set('sum-tokens', formatTokens((total.promptTokens ?? 0) + (total.completionTokens ?? 0)));
+  set('sum-tokens-note', `프롬프트 ${formatTokens(total.promptTokens)} · 출력 ${formatTokens(total.completionTokens)}`);
+
+  const rate = cacheRate(total);
+  set('sum-cache', formatPercent(rate));
+  const cacheEl = root.querySelector('#sum-cache');
+  if (cacheEl) cacheEl.className = `stat-value ${rateClass(rate)}`.trim();
+}
+
+/**
+ * Fetch every axis for one window.
+ *
+ * `Promise.all`, so one failed axis fails the load. The realistic failure is a
+ * 403, which hits all six identically and is reported as the token case; a
+ * partial render for the rarer per-request failures is a separate change.
+ */
+export async function loadUsage(since, fetchImpl = globalThis.fetch) {
+  const results = await Promise.all(AXES.map(async (by) => {
+    const res = await fetchImpl(`/api/usage?since=${encodeURIComponent(since)}&by=${by}`);
+    if (!res.ok) throw new Error(`/api/usage?by=${by} → ${res.status}`);
+    return [by, await res.json()];
+  }));
+  return Object.fromEntries(results);
+}
+
+/** Windows the selector offers. A hand-typed `?since=` outside this set is ignored. */
+export const WINDOWS = ['24h', '7d', '30d'];
+
+/** The window named by the URL, or null when it names nothing valid. */
+export function windowFromSearch(search) {
+  const value = new URLSearchParams(search ?? '').get('since');
+  return WINDOWS.includes(value) ? value : null;
+}
+
+/**
+ * Put the rendered window in the URL so the view can be linked and reloaded.
+ *
+ * replaceState, not push: flipping the window is not a navigation, and a back
+ * button that walks through every window the operator tried is noise.
+ */
+function writeWindowToUrl(value) {
+  try {
+    const url = new URL(globalThis.location?.href ?? 'http://localhost/usage');
+    url.searchParams.set('since', value);
+    globalThis.history?.replaceState?.(null, '', `${url.pathname}${url.search}`);
+  } catch { /* no history in a test document; rendering still proceeds */ }
+}
+
+export function startUsageView({ root = document, fetchImpl = globalThis.fetch, location: loc = globalThis.location } = {}) {
+  // Only the newest request may paint. Windows differ in cost — 24h opens one
+  // day file, 30d up to thirty — so picking 7d then 24h lands the 7d response
+  // second, and every control on the page would then deny the numbers on it.
+  let latest = 0;
+  const status = root.querySelector('#status');
+  const windowSelect = root.querySelector('#window');
+  const say = (text) => { if (status) status.textContent = text; };
+
+  // The window is state, so it belongs in the URL: a 30-day view can be linked
+  // and reloaded. It also makes an empty window distinguishable from a broken
+  // page — you can ask for a window you know has data.
+  const fromUrl = windowFromSearch(loc?.search);
+  if (fromUrl && windowSelect) windowSelect.value = fromUrl;
+  // `parseUsageSince` accepts more than the selector offers ('90m', an ISO
+  // date). Landing on one of those showed 24h data under a URL claiming
+  // otherwise, silently — so rewrite the URL to the window actually rendered.
+  else if (loc?.search?.includes('since=')) writeWindowToUrl(windowSelect?.value ?? '24h');
+
+  /** The window whose data is currently on screen, so a failure can go back to it. */
+  let rendered = null;
+
+  async function refresh() {
+    const since = windowSelect?.value ?? '24h';
+    const seq = ++latest;
+    say('불러오는 중…');
+    try {
+      const data = await loadUsage(since, fetchImpl);
+      if (seq !== latest) return;   // a newer window is already in flight
+      renderSummary(root, data);
+      renderDays(root.querySelector('#days'), data.day);
+      const LABELS = { model: '모델', stage: '스테이지', adapter: '어댑터', project: '프로젝트' };
+      for (const axis of ['model', 'stage', 'adapter', 'project']) {
+        const table = root.querySelector(`#table-${axis}`);
+        if (!table) continue;
+        const drew = renderTable(table, data[axis], { label: LABELS[axis] });
+        const note = root.querySelector(`#note-${axis}`);
+        if (note) note.textContent = truncationNote(drew.hidden);
+      }
+      const taskTable = root.querySelector('#table-task');
+      if (taskTable) {
+        const drew = renderTable(taskTable, data.task,
+          { sortBy: 'calls', limit: 30, label: '작업', excludeUnattributed: true });
+        // Excluded, not hidden: name what was left out and how big it was.
+        const loose = (data.task?.rows ?? []).find(r => r.key === UNATTRIBUTED);
+        const note = root.querySelector('#task-note');
+        if (note) {
+          const parts = [];
+          if (loose) parts.push(`작업에 귀속되지 않은 호출 ${formatCount(loose.calls)}회(${formatCost(loose.costUsd)})는 제외했습니다.`);
+          const cut = truncationNote(drew.hidden);
+          if (cut) parts.push(cut);
+          note.textContent = parts.join(' ');
+        }
+      }
+      rendered = since;
+      // `기준` names when the data ends. Falling back to `since` would print
+      // the window's START under that label, which is the opposite.
+      const until = data.model?.until;
+      say(until ? `기준 ${new Date(until).toLocaleString('ko-KR')}` : '');
+    } catch (err) {
+      if (seq !== latest) return;
+      // Put the controls back on the window the numbers actually came from.
+      // Otherwise a failed switch leaves the select and the URL naming 30d
+      // while every figure on screen is still the 24h load — the exact state
+      // the sequence token above exists to prevent, reached the other way.
+      if (rendered && rendered !== since && windowSelect) {
+        windowSelect.value = rendered;
+        writeWindowToUrl(rendered);
+      }
+      // A 403 here is the token case, not a dead daemon — say which.
+      const message = String(err?.message ?? err);
+      const scope = rendered && rendered !== since ? `${since} 조회 실패 — ${rendered} 데이터를 유지합니다. ` : '';
+      say(message.includes('403')
+        ? `${scope}접근 권한이 없습니다. 아래에서 웹 토큰을 입력하세요.`
+        : `${scope}사용량을 불러오지 못했습니다: ${message}`);
+    }
+  }
+
+  // The token panel. `webToken.js` already wraps fetch and prompts on a 403,
+  // so this is the explicit path rather than the only one — but shipping the
+  // markup without wiring it would leave a field that silently does nothing.
+  // Go through the wrapper's own store so there is one definition of where a
+  // token lives, not a second copy of the storage key.
+  const tokenStore = () => globalThis.window?.OpenSwarmWebToken;
+  const tokenInput = root.querySelector('#web-token');
+  root.querySelector('#save-token')?.addEventListener('click', () => {
+    // `storeToken('')` is the wrapper's REMOVE path, and this field is empty in
+    // exactly the case that matters: it is cleared after each use and the
+    // wrapper's own prompt never fills it. One stray click would otherwise
+    // delete a working credential page-wide — and if the prompt had been
+    // dismissed once, `declined` is latched and it does not come back.
+    const token = tokenInput?.value?.trim();
+    if (!token) { say('토큰을 입력한 뒤 적용을 누르세요.'); return; }
+    tokenStore()?.storeToken(token);
+    if (tokenInput) tokenInput.value = '';
+    refresh();   // says '불러오는 중…' itself; a confirmation here would be overwritten
+  });
+  root.querySelector('#clear-token')?.addEventListener('click', () => {
+    tokenStore()?.storeToken('');
+    say('이 탭의 토큰을 지웠습니다.');
+  });
+
+  windowSelect?.addEventListener('change', () => {
+    writeWindowToUrl(windowSelect.value);
+    refresh();
+  });
+  root.querySelector('#refresh')?.addEventListener('click', refresh);
+  return { refresh };
+}
+
+if (typeof document !== 'undefined' && document.querySelector('#days')) {
+  startUsageView().refresh();
+}
diff --git a/web/static/orchestration.html b/web/static/orchestration.html
index 99a5d1f8..2f0916a4 100644
--- a/web/static/orchestration.html
+++ b/web/static/orchestration.html
@@ -20,6 +20,7 @@
       <a href="/orchestration" aria-current="page">Orchestration</a>
       <a href="/threads">Threads</a>
       <a href="/warehouse">Warehouse</a>
+      <a href="/usage">Usage</a>
       <a href="/">Supervisor</a>
     </nav>
     <div class="topbar-spacer"></div>
diff --git a/web/static/threads.html b/web/static/threads.html
index 8f4d9ff0..efa618b2 100644
--- a/web/static/threads.html
+++ b/web/static/threads.html
@@ -20,6 +20,7 @@
       <a href="/orchestration">Orchestration</a>
       <a href="/threads" aria-current="page">Threads</a>
       <a href="/warehouse">Warehouse</a>
+      <a href="/usage">Usage</a>
       <a href="/">Supervisor</a>
     </nav>
     <div class="topbar-spacer"></div>
diff --git a/web/static/usage.html b/web/static/usage.html
new file mode 100644
index 00000000..4bb0d3ba
--- /dev/null
+++ b/web/static/usage.html
@@ -0,0 +1,101 @@
+<!doctype html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+  <title>OpenSwarm · Usage</title>
+  <script src="/static/js/themeBoot.js"></script>
+  <script src="/static/js/webToken.js"></script>
+  <link rel="stylesheet" href="/static/css/tokens.css" />
+  <link rel="stylesheet" href="/static/css/shell.css" />
+  <link rel="stylesheet" href="/static/css/usage.css" />
+</head>
+<body class="page-usage">
+  <header class="topbar">
+    <a class="brand" href="/app">🐝 OpenSwarm</a>
+    <span class="page-title">Usage</span>
+    <nav class="topbar-nav" aria-label="Pages">
+      <a href="/app">Cockpit</a>
+      <a href="/chat">Chat</a>
+      <a href="/orchestration">Orchestration</a>
+      <a href="/threads">Threads</a>
+      <a href="/warehouse">Warehouse</a>
+      <a href="/usage" aria-current="page">Usage</a>
+      <a href="/">Supervisor</a>
+    </nav>
+    <div class="topbar-spacer"></div>
+    <div class="topbar-actions">
+      <label class="sr-only" for="window">기간</label>
+      <select id="window" class="select">
+        <option value="24h" selected>최근 24시간</option>
+        <option value="7d">최근 7일</option>
+        <option value="30d">최근 30일</option>
+      </select>
+      <button type="button" id="refresh" class="btn btn-secondary btn-sm">새로고침</button>
+      <button type="button" id="theme-toggle" class="btn btn-ghost btn-icon theme-toggle" aria-label="테마 전환" aria-pressed="false">
+        <span class="when-dark" aria-hidden="true">☾</span><span class="when-light" aria-hidden="true">☀</span>
+      </button>
+    </div>
+  </header>
+
+  <main class="usage-main">
+    <p id="status" class="status-line status" role="status" aria-live="polite">불러오는 중…</p>
+
+    <section class="summary" aria-label="요약">
+      <div class="card stat"><span class="stat-label">비용</span><strong id="sum-cost" class="stat-value">—</strong><span id="sum-cost-note" class="stat-note"></span></div>
+      <div class="card stat"><span class="stat-label">호출</span><strong id="sum-calls" class="stat-value">—</strong><span id="sum-calls-note" class="stat-note"></span></div>
+      <div class="card stat"><span class="stat-label">토큰</span><strong id="sum-tokens" class="stat-value">—</strong><span id="sum-tokens-note" class="stat-note"></span></div>
+      <div class="card stat"><span class="stat-label">캐시 적중률</span><strong id="sum-cache" class="stat-value">—</strong><span class="stat-note">cached / prompt</span></div>
+    </section>
+
+    <section class="card panel" aria-labelledby="days-title">
+      <h2 id="days-title" class="card-head">일별</h2>
+      <div class="card-body"><div id="days" class="bars"></div></div>
+    </section>
+
+    <div class="grid">
+      <section class="card panel" aria-labelledby="model-title">
+        <h2 id="model-title" class="card-head">모델</h2>
+        <p id="note-model" class="muted task-note"></p>
+        <div class="card-body table-wrap"><table id="table-model"></table></div>
+      </section>
+      <section class="card panel" aria-labelledby="stage-title">
+        <h2 id="stage-title" class="card-head">스테이지</h2>
+        <p id="note-stage" class="muted task-note"></p>
+        <div class="card-body table-wrap"><table id="table-stage"></table></div>
+      </section>
+      <section class="card panel" aria-labelledby="adapter-title">
+        <h2 id="adapter-title" class="card-head">어댑터</h2>
+        <p id="note-adapter" class="muted task-note"></p>
+        <div class="card-body table-wrap"><table id="table-adapter"></table></div>
+      </section>
+      <section class="card panel" aria-labelledby="project-title">
+        <h2 id="project-title" class="card-head">프로젝트</h2>
+        <p id="note-project" class="muted task-note"></p>
+        <div class="card-body table-wrap"><table id="table-project"></table></div>
+      </section>
+    </div>
+
+    <section class="card panel" aria-labelledby="tasks-title">
+      <h2 id="tasks-title" class="card-head">작업별 — 호출이 많은 순</h2>
+      <p id="task-note" class="muted task-note"></p>
+      <div class="card-body table-wrap"><table id="table-task"></table></div>
+    </section>
+
+    <section class="card access" aria-labelledby="access-title">
+      <h2 id="access-title" class="card-head">원격 접근</h2>
+      <div class="card-body">
+        <p class="muted">로컬이 아닌 브라우저에서는 배포 시 설정한 웹 토큰이 필요합니다.</p>
+        <label for="web-token">OpenSwarm 웹 토큰</label>
+        <div class="token-row">
+          <input id="web-token" class="input" type="password" autocomplete="off" spellcheck="false" />
+          <button id="save-token" type="button" class="btn btn-secondary">적용</button>
+        </div>
+        <button id="clear-token" class="text-button" type="button">이 탭의 토큰 지우기</button>
+      </div>
+    </section>
+  </main>
+
+  <script type="module" src="/static/js/usage.mjs"></script>
+</body>
+</html>
diff --git a/web/static/warehouse.html b/web/static/warehouse.html
index 8e5a940b..ca8642b4 100644
--- a/web/static/warehouse.html
+++ b/web/static/warehouse.html
@@ -20,6 +20,7 @@
       <a href="/orchestration">Orchestration</a>
       <a href="/threads">Threads</a>
       <a href="/warehouse" aria-current="page">Warehouse</a>
+      <a href="/usage">Usage</a>
       <a href="/">Supervisor</a>
     </nav>
     <div class="topbar-spacer"></div>