@flame0510/project-aether 1.9.1 → 1.10.0

package/docs/DESIGN-SYSTEM.md

@@ -2,7 +2,7 @@
 
 Source of truth: `app/design-system.ts` + CSS tokens in `app/globals.css`.
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
 ---
 
@@ -82,7 +82,7 @@ then use it — a one-off copy of markup is the thing this section exists to pre
 5. **CSS vars over hardcoded colors.** Never inline `#22c55e`, `#ef4444`, `#888` — use the CSS token.
 6. **Loading feedback.** Use `loading` prop on `Button` (shows inline spinner). Do not render separate loader elements.
 7. **Minimal animation.** Transitions on hover/active (0.1s–0.12s), spin on loading spinner. No bounce, shake, or decorative animations.
-8. **Data display: violet for the data, status colours for levels.** A chart series is `var(--violet)` (2px line, 10% wash), grid and axis text are `var(--border)` / `var(--text-dim)`, never the series colour. A `Meter` fill is violet when fine and `var(--yellow)` / `var(--red)` at its warning / critical level, with the level also written out — status never rests on colour alone. Focus on a chart is a 1px `outline` in `var(--violet-dim)`, not a shadow. See `TimeSeriesChart` and `Meter` in `docs/FRONTEND-ARCHITECTURE.md`.
+8. **Data display: violet for the data, status colours for levels.** A chart series is `var(--violet)` (2px line, 10% wash), grid and axis text are `var(--border)` / `var(--text-dim)`, never the series colour. A `Meter` fill is violet when fine and `var(--yellow)` / `var(--red)` at its warning / critical level, with the level also written out — status never rests on colour alone. Focus on a chart is a 1px `outline` in `var(--violet-dim)`, not a shadow. A figure that is only a share of a whole (the Costs page's agents and models) uses the same `Meter`, always at its `ok` level: it is a proportion, not a warning. See `TimeSeriesChart` and `Meter` in `docs/FRONTEND-ARCHITECTURE.md`.
 
 ### React hook
 

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
 ## Layering
 
@@ -39,7 +39,7 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `Metric` | `Metric.tsx` | Metric card with title, value, subtitle, tone, and a `size` (`md` default, `sm` for a grid inside a dialog: smaller value, tighter spacing). |
 | `StatusCard` | `StatusCard.tsx` | Health/status report card. |
 | `Meter` / `meterLevel` | `Meter.tsx` | Horizontal 0-100 % fill whose colour carries the level (`ok` accent, `warning` yellow, `critical` red); the level is also written out beside it, never colour alone. `meterLevel(percent, warning, critical)` picks the level. ARIA `role="meter"`. |
-| `TimeSeriesChart` | `TimeSeriesChart.tsx` | One series over time in plain SVG measured to its container (text never scaled): a 2px accent line for the value, a 10 % wash up to the bucket's peak, a hairline grid at 0 / 50 / 100 %, the latest value labelled at the line's end. Points further apart than 1.5 buckets are not joined (a gap means no samples). Hover or keyboard focus (← → Esc) shows a crosshair snapped to the nearest point with value and peak; a **Table** disclosure holds the same data. `stale` dims the previous render while a new range loads. Used by the System page. |
+| `TimeSeriesChart` | `TimeSeriesChart.tsx` | One series over time in plain SVG measured to its container (text never scaled): a 2px accent line for the value, a 10 % wash up to the bucket's peak, a hairline grid at 0 / 50 / 100 %, the latest value labelled at the line's end. Points further apart than 1.5 buckets are not joined (a gap means no samples). Hover or keyboard focus (← → Esc) shows a crosshair snapped to the nearest point with value and peak; a **Table** disclosure holds the same data. `stale` dims the previous render while a new range loads. `yMax` / `unit` scale and label a percentage by default; `formatValue` replaces the label format everywhere (axis, end label, tooltip, table) — the Costs page passes dollars. The left and right margins grow with the longest axis label and the end label, so a longer format is never cut. Used by the System and Costs pages. |
 | `Surface` | `Surface.tsx` | Shared panel/card surface, variant prop. |
 | `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
 | `Icons` | `Icons.tsx` | SVG icons (`EyeIcon`, `EyeOffIcon`), 16/20px shared. |
@@ -48,6 +48,8 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `BackupSection` | inline in `app/agents/PageClient.tsx` | BACKUP section of the agent detail panel, on the cold backup and the restore. **Backup Now** starts `POST /api/agents/[id]/cold-backup`; while the job runs a banner shows the file and its live percent with **Cancel** (`DELETE /cold-backup`). **Restore** (after a confirm) starts `POST /restore` and a banner shows `Restoring <file>…` (no percent: the extract is a single `tar xzf`, and there is no Cancel). Both sections poll their `GET` every 2 s while running, and on mount pick up a job that is already running — a backup lives in a Docker helper, a restore in `agent_restores`, so reloading the page or navigating away never loses them nor allows a second one (the server answers 409 anyway). Delete per row; all actions disabled while one runs; keyed busy state `{ kind, file }` so only the row in action shows the spinner. On the agent list, an activity Badge (fed by `/api/agents/activity-summary`, polled at 2 s only while something runs, otherwise riding the 15 s list poll) reads `BACKUP nn%`, `RESTORING`, `RECREATING`, `EDITING` or `UPDATING`. |
 | `RecreateSection` | inline in `app/agents/PageClient.tsx` | RECREATE section of the agent detail panel. **Recreate Container** starts `POST /api/agents/[id]/recreate` (202) after a confirm; a banner then shows the phase — *Backing up … nn%* while the cold backup runs, *Recreating container…* while the container is rebuilt and the gateway starts. The section polls `GET /recreate` every 2 s, and on mount picks up a recreate that is already running, so a reload or navigation never loses it; it refetches the agent once the job reports `done`. |
 | System page | `app/system/PageClient.tsx` | `/system`: CPU, memory and storage of the host, from `GET /api/metrics`. Three cards (CPU with cores and load; memory with available and swap; one `Meter` per filesystem with its roles) — thresholds 85/95 % for CPU and memory, 80/90 % for storage — then a range switch (`Tabs`: 1h · 24h · 7d · 30d) scoping the charts below it: CPU and memory average with peak, one chart per filesystem. Polls every 30 s with an `AbortController` ref (a range change aborts the previous fetch). Times in the configured Rev4a timezone (`useRev4aTimezone`). Before the first answer the cards and charts are skeletons shaped like them (`app/system/SystemSkeleton.tsx`, also the route's `loading.tsx`), so nothing jumps; the hostname line is cut with an ellipsis and never widens the page. Says *No samples yet* before the daemon's first sample and *Not collecting* when the latest sample is older than three intervals. Two columns of charts from lg (992px) up, one below. |
+| Costs page | `app/costs/PageClient.tsx` | `/costs`: what each agent spent, as its own OpenClaw priced it, from `GET /api/costs/usage`. A range switch (`Tabs`: Today · 7 days · 30 days, UTC days) scopes everything below it: three cards (spent with tokens and days; the cost split into input / output / cache read / cache write; the tokens with the share of input served from cache), the daily spend (`TimeSeriesChart` with dollars, not on Today), then *By agent* and *By model* side by side — each row a name and figure over a share `Meter`, the pattern of the System storage card — *Against the bill* (per vendor, what it billed, from balance or usage readings, next to what the agents priced over the same readings, top-ups apart), and the most expensive sessions. Warnings above: *No figures yet* before the daemon's first pass, *Not current* for agents still being read whose last read failed or is older than three intervals (a stopped or deleted agent keeps its figures unflagged), and *Calls without a price* by model (a model with no price is also marked in *By model*, so a $0.00 is never read as free). The header shows the DeepSeek band now (peak / off-peak, until when, UTC) when a DeepSeek model is on offer. Polls every 60 s with an `AbortController` ref. Skeletons shaped like the content (`app/costs/CostsSkeleton.tsx`, also the route's `loading.tsx`). Costs under a cent keep four decimals. |
+| Agent costs | `app/agents/CostSection.tsx` | The COSTS section of the agent panel, after MODEL: today (UTC), last 7 and 30 days with tokens, the top model, calls without a price, when the agent was last read (a note when not recently: a stopped agent keeps its last figures), and a link to `/costs`. From `GET /api/costs/agent`, every 60 s with an `AbortController` ref. |
 | Machine card | `app/components/SystemCockpit.tsx` | On the dashboard, next to Active sessions: CPU, RAM and the fullest disk now, each figure coloured only when past its threshold (same thresholds as the System page), the issues named in words, and a link to `/system`. It says *No samples yet* before the first sample, *Not collecting* when the newest is stale, and *Metrics unavailable* when a refresh fails (keeping the last figures). A `Surface`, not a `Metric`: a danger `Metric` paints its whole value red. |
 | Container terminal | `app/containers/terminal/[id]/TerminalClient.tsx` | Full-screen shell into a container: xterm.js 6 (`@xterm/xterm` + `addon-fit` refitted by a `ResizeObserver`, `addon-web-links`), loaded client-side only, palette from the design tokens. Keystrokes are sent raw (`onData`, `onBinary`), the size on connect and whenever the columns or rows change. A bar with `ui-kicker`, the container name, a status `Badge` (Connecting / Connected / Reconnecting / Closed) and `Button`s **Reconnect** / **Close**; styles are the `terminal-page` classes. Session id per container in `sessionStorage` (a UUID from `getRandomValues`: `randomUUID` is missing over plain HTTP), so a reload resumes the shell; after a drop it reconnects with `resume=1` and is told when the shell is gone; retries with backoff (six failed opens, about 40 s, then a message) and stops on the server's final close codes with the reason shown. **Close** while reconnecting still ends the waiting shell. Protocol and sessions: `docs/CONTAINER-TERMINAL.md`. |
 | `ImageDownloadBanner` | `app/agents/ImageDownloadBanner.tsx` | Agent image banner on the Agents page. Polls `/api/agents/image-status` every 2 s; offers **Download Image** when no supported version is downloaded, **Download <version>** when the registry publishes a newer one, and while a download runs shows the percent of layers finished and the latest line of docker's output (the bar is indeterminate until a percent can be computed). **Cancel** (`DELETE /api/agents/download-image`, own loading state) appears once `image-status` reports the download running; before that the button reads *Starting…* and is disabled. Every outcome — ready and cancelled for 3 s, a failure until the next action — comes from the server's `lastResult`, so one that ended while the page was closed or reloading is still reported if it is less than 30 s old (aged with `serverTime`). Each outcome is announced once per page load, although the Agents page mounts the banner in three places (mobile list, mobile detail, desktop). Downloading changes no agent. |

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -99,9 +99,10 @@ When environment variables are saved via the Config page (Save & Restart):
 
 | Route | Description |
 |---|---|
-| `/` | System overview — health, sessions, the machine's CPU / RAM / disk (links to `/system`), cost, live feed |
+| `/` | System overview — health, sessions, the machine's CPU / RAM / disk (links to `/system`), what the agents spent today (as on `/costs`), live feed |
 | `/agents` | Running agents (Docker containers with `AGENT_ID`), gateway token management, agent creation wizard, channel manager (Telegram pairing) |
 | `/containers` | All Docker containers on the host |
+| `/costs` | What each agent spent, as its own OpenClaw priced it with the rates Rev4a syncs: today / 7 / 30 UTC days, by day, by agent, by model, the most expensive sessions, the calls that could not be priced, the DeepSeek band now, and a check against what DeepSeek and OpenRouter actually billed (read by the daemon every 5 min into `costs.db`; each agent's own figures are also in its panel, COSTS) |
 | `/system` | The host machine: CPU, memory and swap, storage per filesystem — current values and 1h / 24h / 7d / 30d history (from `metrics.db`, sampled by the daemon every 30 s) |
 | `/wizard` | First-run setup wizard (Welcome → Providers → Agent → Ready) |
 | `/workspace` | File explorer with tree view + editor — VPS host or container workspaces |

package/docs/dev/API-REFERENCE.md

@@ -1,6 +1,6 @@
 # Rev4a API Reference
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
 All routes are under `/api/`. Authentication is required on every endpoint
 unless otherwise noted.
@@ -469,12 +469,12 @@ Returns all sessions (up to 2000), newest first, joined with lineage labels.
     "model": "openai-codex/gpt-5.4",
     "tokens_in": 12500,
     "tokens_out": 3200,
-    "cost_usd": 0.085,
+    "cost_usd": 0,
     "status": "idle",
     "task_preview": "Run hygiene audit...",
-    "started_at": 1749200000,
+    "started_at": 1749200000000,
     "ended_at": null,
-    "updated_at": 1749201000,
+    "updated_at": 1749201000000,
     "trello_card_url": null,
     "lineage_label": null,
     "lineage_agent_name": null
@@ -517,8 +517,76 @@ One session with its events and any child sessions.
 
 ## Stats & Costs
 
+Agent costs come from `costs.db`: what each agent's own OpenClaw priced, copied by the
+daemon (the queries are in `lib/agent-costs.ts` (spend) and `lib/cost-reconciliation.ts` (`vendor_balance`), on a read-only handle from `lib/costs-db.ts`). `GET /api/costs/usage` feeds the Costs
+page, `GET /api/costs` the dashboard, `GET /api/costs/agent` the agent panel. `GET
+/api/stats` and `GET /api/stats-since` still read the `sessions` table of `events.db`,
+whose `cost_usd` is no longer estimated (always 0).
+
+### `GET /api/costs/usage?range=today|7d|30d`
+What the agents spent in a range of UTC days, today included (default `7d`), read from
+`costs.db` (written by the daemon every 5 minutes, see `docs/dev/DATABASE.md`). Rev4a
+computes no cost: every figure is the one OpenClaw recorded with the prices Rev4a syncs.
+
+**Auth:** browser cookie or Bearer
+
+**Response:**
+```json
+{
+  "available": true,
+  "range": "7d",
+  "startDate": "2026-09-21",
+  "endDate": "2026-09-27",
+  "intervalS": 300,
+  "pricing": { "vendor": "DeepSeek", "band": "off-peak", "nextChange": 1790557200000, "source": "https://api-docs.deepseek.com/quick_start/pricing" },
+  "totals": { "cost": 0.0086, "tokens": 114053, "input": 47436, "output": 2233, "cacheRead": 64384, "cacheWrite": 0,
+              "inputCost": 0.0071, "outputCost": 0.0013, "cacheReadCost": 0.0002, "cacheWriteCost": 0, "missing": 0 },
+  "daily": [ { "date": "2026-09-21", "cost": 0.0071, "tokens": 96806, "missing": 0 } ],
+  "byAgent": [ { "container": "agent_9253eee3", "agentId": "agent_9253eee3", "name": "test", "cost": 0.0077, "tokens": 96806,
+                 "missing": 0, "collectedAt": 1790526404843, "attemptedAt": 1790526404843, "error": null } ],
+  "byModel": [ { "provider": "rev4a", "model": "deepseek/deepseek-flash", "cost": 0.0086, "tokens": 114053, "calls": 13 } ],
+  "sessions": [ { "container": "agent_9253eee3", "agentName": "test", "sessionId": "…", "sessionKey": "agent:main:…", "label": "…",
+                  "agentId": "main", "model": "deepseek/deepseek-flash", "cost": 0.004, "tokens": 18681, "missing": 0, "lastActivity": 1790322536609 } ],
+  "unpriced": [ { "model": "rev4a/deepseek/deepseek-v4-flash", "calls": 84, "agents": ["test", "test 2"] } ],
+  "reconciliation": [ { "vendor": "deepseek", "currency": "USD", "from": 1790529518869, "to": 1790536317000,
+                        "billed": 0.02, "priced": 0.0171, "topUps": 0, "readings": 3, "comparable": true } ]
+}
+```
+
+- `daily` has one entry per day of the range, zeros included.
+- `missing` counts calls OpenClaw could not price (no price for their model): they are in
+  the tokens, not in the cost. `unpriced` lists them by model over each agent's last 30
+  days.
+- `byAgent` holds every agent read, running or not, with use in the range, an error, or
+  a read in the last 15 minutes; `error` is why its last read stored nothing (OpenClaw's
+  own reason, e.g. "Gateway not reachable…"). An agent still being read (`attemptedAt`
+  within 3 × `intervalS`) with an `error` or a `collectedAt` older than that is not
+  current; a stopped or deleted agent is no longer read and keeps its last figures.
+- `sessions`: the 20 most expensive sessions active in the range; a session's figures are
+  its total over the last 30 days.
+- `pricing`: the band DeepSeek bills at now and when it changes, when a DeepSeek model is
+  on offer; `null` otherwise.
+- `reconciliation`: per vendor with a configured key (DeepSeek, OpenRouter), what it
+  billed next to what the agents priced over the same hourly readings — `{ vendor,
+  currency, from, to, billed, priced, topUps, readings, comparable }`. `billed` is the
+  balance drop (DeepSeek; rises are `topUps`, not spend) or the usage growth (OpenRouter);
+  `priced` the growth of the agents' total for that vendor's models. `billed`/`priced`
+  are `null` until two readings exist; `comparable` is false for a non-USD balance.
+  `vendor` is the lowercase key (`deepseek`, `openrouter`); `pricing.vendor` is a display
+  name. Known gaps, shown rather than corrected: the same key may also pay for the
+  assistant or clients outside Rev4a; a top-up and spend in the same hour net out; an
+  agent missed by a pass joins the agents' total one pass later; calls never priced are
+  priced by OpenClaw when read, so the agents' total can grow for calls made earlier.
+- `available: false` (zeros, empty lists) until the daemon has created `costs.db`.
+
+**Errors:** `400` for another `range`; `500` when `costs.db` cannot be read.
+
+---
+
 ### `GET /api/stats`
-Current-month aggregate stats (tokens + cost) grouped by model.
+Current-month aggregate stats (tokens + cost) grouped by model, from the `sessions` table
+(`started_at` is in milliseconds). The costs are the `sessions.cost_usd` column, which is no
+longer estimated: 0, except rows written before 2026-09-27. Agent spend is `GET /api/costs/usage`.
 
 **Auth:** Bearer or browser cookie
 
@@ -526,13 +594,13 @@ Current-month aggregate stats (tokens + cost) grouped by model.
 ```json
 {
   "total": {
-    "total": 1.24,
+    "total": 0,
     "total_in": 850000,
     "total_out": 210000,
     "sessions": 47
   },
   "byModel": [
-    { "model": "openai-codex/gpt-5.4", "cost": 0.95, "tokens_in": 600000, "tokens_out": 150000, "sessions": 30 }
+    { "model": "rev4a/deepseek/deepseek-flash", "cost": 0, "tokens_in": 600000, "tokens_out": 150000, "sessions": 30 }
   ]
 }
 ```
@@ -540,7 +608,8 @@ Current-month aggregate stats (tokens + cost) grouped by model.
 ---
 
 ### `GET /api/stats-since?ts=<unix_ms>`
-Total cost (USD) since a given timestamp.
+Sum of `sessions.cost_usd` since a given timestamp — 0 for sessions polled since 2026-09-27
+(see `GET /api/stats`).
 
 **Auth:** Bearer or browser cookie
 
@@ -548,28 +617,49 @@ Total cost (USD) since a given timestamp.
 
 **Response:**
 ```json
-{ "total": 0.42 }
+{ "total": 0 }
 ```
 
 ---
 
 ### `GET /api/costs`
-Full cost breakdown: today, 7d, 30d, all-time, per-model, plus cost-override for the current month.
+The dashboard's figures: today's spend (UTC day), all-time spend, today's calls without a
+price, and today's spend by model — from `costs.db`. The SSE stream (`GET /api/stream`)
+sends the same `today`.
 
-**Auth:** browser cookie
+**Auth:** browser cookie or Bearer
 
 **Response:**
 ```json
 {
-  "today": 0.12,
-  "week": 1.85,
-  "month": 6.40,
-  "allTime": 42.10,
-  "override": null,
-  "byModel": [ ... ]
+  "today": 0.0112,
+  "allTime": 0.0559,
+  "allTimeSource": "agents_openclaw",
+  "missingToday": 0,
+  "byModel": [ { "model": "deepseek/deepseek-flash", "cost_usd": 0.0112, "tokens": 244157, "calls": 7 } ]
 }
 ```
 
+`byModel` lists the models that cost something today; the free and unpriced ones are on the
+Costs page.
+
+**Errors:** `500` when `costs.db` cannot be read.
+
+---
+
+### `GET /api/costs/agent?container=<name>`
+One agent's spend for its panel, from `costs.db`.
+
+**Auth:** browser cookie or Bearer
+
+**Response:** `{ "available": true, "intervalS": 300, "today": 0.011, "week": 0.019,
+"month": 0.022, "tokensMonth": 2409574, "topModel": { "model": "deepseek/deepseek-flash",
+"cost": 0.022 }, "unpricedMonth": 81, "collectedAt": 1790529516737, "error": null }` —
+UTC days (today, last 7, last 30); `collectedAt`/`error` from the agent's last read.
+`{ "available": false, "intervalS": 300 }` before `costs.db` exists.
+
+**Errors:** `400` for an invalid container name; `500` when `costs.db` cannot be read.
+
 ---
 
 ### `GET /api/cost-override?month=YYYY-MM`
@@ -619,13 +709,17 @@ Paginated event log.
 ---
 
 ### `GET /api/stream`
-Server-Sent Events stream. Pushes a combined payload every ~3 s.
+Server-Sent Events stream. Every 5 s it sends one message per kind, each `{ type, data }`:
+`events` (new rows of the `events` table, only when there are any), `sessions` (the 100 most
+recent sessions with their lineage label) and `costs` (`{ "today": … }`, what the agents spent
+today, UTC day — the same figure as `GET /api/costs`).
 
-**Auth:** browser cookie
+**Auth:** browser cookie or Bearer
 
 **Event format:**
 ```
-data: {"events":[...],"sessions":[...],"costs":{"today":0.12},"lineage":[...]}
+data: {"type":"sessions","data":[...]}
+data: {"type":"costs","data":{"today":0.0112}}
 ```
 
 Use `EventSource` in the browser or `curl -N` for testing.
@@ -1973,14 +2067,16 @@ say so; it does not fail the others.
     { "id": "runtime.sessions", "label": "Runtime sessions", "health": "ok", "value": 1, "details": "last session activity 3m ago", "source": "runtime" }
   ],
   "recommendations": [
-    { "id": "cost.review-usage-based", "severity": "warning", "source": "cost", "title": "High usage-based cost", "details": "…", "actionHref": "/gateway", "dismissible": true, "createdAt": "2026-09-26T10:00:00.000Z" }
+    { "id": "cost.review-usage-based", "severity": "warning", "source": "cost", "title": "High spend today", "details": "…", "actionHref": "/costs", "dismissible": true, "createdAt": "2026-09-26T10:00:00.000Z" }
   ],
   "generatedAt": "2026-09-26T10:00:00.000Z"
 }
 ```
 
 Checks: `runtime.sessions`, `runtime.heartbeat`, `runtime.errors24h`,
-`cost.usageBasedToday`, `cron.jobs`. `health` (overall and per check) is `"ok"` /
+`cost.usageBasedToday` ("Spent today": the agents' spend today, UTC day, from `costs.db`;
+a warning above $10 or with calls without a price, each with its recommendation,
+`cost.review-usage-based` / `cost.unpriced-calls`), `cron.jobs`. `health` (overall and per check) is `"ok"` /
 `"warning"` / `"error"`; a recommendation's `severity` is `"info"` / `"warning"` /
 `"critical"`. `generatedAt` and `createdAt` are ISO strings.
 

package/docs/dev/DATABASE.md

@@ -1,10 +1,11 @@
 # Rev4a — Database Reference
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-09-27
 
-Rev4a keeps three SQLite files in WAL mode, by default all in the data directory's `data/`:
+Rev4a keeps four SQLite files in WAL mode, by default all in the data directory's `data/`:
 `events.db` (sessions and events, below), `metrics.db` (machine metrics, see
-[Metrics Database](#metrics-database-metricsdb)) and `credentials.db` (see
+[Metrics Database](#metrics-database-metricsdb)), `costs.db` (what the agents spent, see
+[Costs Database](#costs-database-costsdb)) and `credentials.db` (see
 [Credentials Database](#credentials-database-credentialsdb)).
 
 ## Location
@@ -23,7 +24,7 @@ PRAGMA synchronous = NORMAL;
 
 - The daemon writes; the Next.js API routes open read-only connections
 - `events.db`: `PRAGMA wal_checkpoint(PASSIVE)` after each daemon poll cycle, `FULL` every 10
-- `metrics.db`: SQLite's automatic checkpoint (every 1000 pages) — no explicit one
+- `metrics.db`, `costs.db`: SQLite's automatic checkpoint (every 1000 pages) — no explicit one
 - WAL files (`*.db-shm`, `*.db-wal`) — do not delete while the daemon is running
 
 ## Tables
@@ -38,11 +39,11 @@ CREATE TABLE sessions (
   model        TEXT,
   tokens_in    INTEGER DEFAULT 0,
   tokens_out   INTEGER DEFAULT 0,
-  cost_usd     REAL    DEFAULT 0,
+  cost_usd     REAL    DEFAULT 0,  -- always 0 since 2026-09-27: agent costs are in costs.db
   status       TEXT    DEFAULT 'idle',
   task_preview TEXT,
-  started_at   INTEGER,           -- Unix seconds
-  ended_at     INTEGER,           -- Unix seconds, null if active
+  started_at   INTEGER,           -- Unix ms
+  ended_at     INTEGER,           -- Unix ms, null if active
   updated_at   INTEGER,           -- Unix ms, updated only on real changes
   trello_card_url TEXT
 );
@@ -59,13 +60,19 @@ CREATE TABLE events (
   id         INTEGER PRIMARY KEY AUTOINCREMENT,
   ts         INTEGER NOT NULL,   -- Unix ms
   session_id TEXT    NOT NULL,
-  type       TEXT    NOT NULL,   -- spawn | complete | error | tool_call
+  type       TEXT    NOT NULL,   -- see below
   data       TEXT                -- JSON payload
 );
 
 CREATE INDEX idx_events_session ON events(session_id, ts);
 ```
 
+Types written today: `spawn`, `complete`, `fail`, `spawn_timeout` (the daemon's session poll),
+`system_anomaly` (the daemon's machine metrics, session `system`), `agent_created` and
+`agent_deleted` (the create and delete routes, session `system:agents`). **No retention:**
+rows are never pruned — on a development machine with a nearly full disk, `system_anomaly`
+reached ~4 000 rows in a month.
+
 ### `lineage` — explicit parent→child declarations
 
 ```sql
@@ -90,7 +97,7 @@ CREATE TABLE cost_override (
 );
 ```
 
-When a `cost_override` row exists for the current month, the UI displays the override value instead of the computed sum.
+Nothing reads `cost_override` except `/api/cost-override` itself: no page shows an override.
 
 The daemon also writes a `system_anomaly` event (session `system`) when the machine
 crosses a threshold — see [Metrics Database](#metrics-database-metricsdb). No feature
@@ -195,18 +202,21 @@ container started again. Rows are never pruned.
 ## Useful Queries
 
 ```sql
--- Total cost this month
-SELECT SUM(cost_usd) FROM sessions
-WHERE started_at >= strftime('%s', date('now', 'start of month'));
-
--- Active sessions right now
-SELECT session_id, label, model, status, cost_usd
+-- costs.db: what the agents spent this month (UTC days), by agent
+SELECT s.name, SUM(d.cost) AS spent, SUM(d.missing) AS unpriced
+FROM agent_cost_daily d LEFT JOIN agent_cost_sources s USING (container)
+WHERE d.date >= strftime('%Y-%m-01', 'now')
+GROUP BY d.container ORDER BY spent DESC;
+
+-- costs.db: spend by model, last 30 days
+SELECT model, SUM(cost) AS spent, SUM(calls) AS calls
+FROM agent_cost_model_daily WHERE date >= date('now', '-29 days')
+GROUP BY provider, model ORDER BY spent DESC;
+
+-- events.db: active sessions right now
+SELECT session_id, label, model, status
 FROM sessions WHERE status = 'working';
 
--- Cost by model (all time)
-SELECT model, SUM(cost_usd) AS total, COUNT(*) AS sessions
-FROM sessions GROUP BY model ORDER BY total DESC;
-
 -- Last poll time (freshness check)
 SELECT datetime(MAX(ts)/1000, 'unixepoch', 'localtime') AS last_event
 FROM events;
@@ -241,6 +251,19 @@ off the machine. `restore.sh` refuses an archive with links in it and a running
 SQLite `-wal` cannot mix into the restored state), then resets the permissions. Agent volumes are not included —
 the dashboard's cold backups cover them.
 
+### Other tables
+
+- `alert_state` — one row per alert key (`lib/alerts.ts`): whether it was sent and resolved, so
+  an alert is not sent twice.
+- `tool_calls` and `chat_messages` — created by `lib/db-bootstrap.mjs` and never written by
+  any code: `GET /api/tool-calls` reads an always-empty table, nothing reads `chat_messages`.
+  Kept until the `events.db` cleanup removes them.
+
+`events.db` is Rev4a's own record — what it did to agents (the job tables, created and
+deleted) and what it saw (anomalies, alerts). What agents do is read from OpenClaw: agent
+spend is in `costs.db`; sessions and lineage move to the lineage collector, and with it
+`sessions`, `lineage` and the poll's `spawn`/`complete` events leave this file.
+
 ## Metrics Database (`metrics.db`)
 
 Machine metrics of the host — CPU, RAM, swap, storage — kept apart from `events.db`, so
@@ -295,6 +318,83 @@ has dropped back under, or once after each daemon start: the state is kept in me
 Installs from before this database may still have a `system_metrics` table in
 `events.db`: nothing reads or writes it any more, and it can be dropped.
 
+## Costs Database (`costs.db`)
+
+What each agent spent, **as its own OpenClaw priced it** — Rev4a computes no cost here.
+Every model in the synced `rev4a` provider block carries its price
+([GATEWAY.md](GATEWAY.md#costs-openclaw-prices-every-call)); each agent's OpenClaw prices
+every call with it, and the daemon copies the figures here, so a stopped or deleted agent
+keeps its history.
+
+**Location:** `data/costs.db`, next to `events.db`, resolved like `metrics.db`.
+**Created by** the daemon when it starts, its only writer; the queries are in `lib/agent-costs.ts` (spend) and `lib/cost-reconciliation.ts` (`vendor_balance`), on a read-only handle from `lib/costs-db.ts` — for
+`GET /api/costs/usage`, `GET /api/costs`, `GET /api/costs/agent`, the SSE stream and
+system-health. No file yet → the API answers `available: false`. If the daemon
+cannot open it, it logs `[COSTS] disabled` and the rest of the daemon keeps running.
+**Collection:** 20 s after the daemon starts, then every 5 minutes. First every **running**
+container with an `AGENT_ID` label gets one short call, so that the ones whose index needs
+rebuilding do it in parallel; then, one at a time, two Gateway calls through
+`docker exec … openclaw gateway call` on the agent's port 3000 (token resolved inside the
+container, never on the host's argv), both with `agentScope: "all"` over the last 30 UTC
+days: `usage.cost` (per day, split into input / output / cache read / cache write, and
+the calls it could not price) and `sessions.usage` (per model per day, and the 50 most
+recent sessions). OpenClaw answers from an index of its transcripts that it rebuilds
+after a price change or a restart; an answer whose `cacheStatus` is not `fresh` is never
+stored — asked up to 6 times, 20 s apart (a rebuild took about 60 s on the VPS, from
+4 to 290 transcript files alike), then the previous figures stay and the container's row
+records the error — OpenClaw's own reason ("Gateway not reachable…") or how long the index
+stayed unfresh. An answer missing its lists is refused before anything is deleted. An agent with nothing in the range answers without
+`cacheStatus`, which counts as fresh.
+**Days** are UTC dates, OpenClaw's default and the clock DeepSeek's rates follow.
+**Retention:** the last 30 days are rewritten on every pass (late or repriced calls land in
+the right day); older rows are kept as last read.
+
+```sql
+-- One row per container per UTC day with any use: OpenClaw's usage.cost daily entry.
+CREATE TABLE agent_cost_daily (
+  container TEXT NOT NULL, date TEXT NOT NULL,          -- 'YYYY-MM-DD'
+  input INTEGER, output INTEGER, cache_read INTEGER, cache_write INTEGER, total_tokens INTEGER,
+  cost REAL, input_cost REAL, output_cost REAL, cache_read_cost REAL, cache_write_cost REAL,
+  missing INTEGER,                                      -- calls OpenClaw could not price
+  PRIMARY KEY (container, date)
+);
+-- Per model per day: sessions.usage aggregates.modelDaily.
+CREATE TABLE agent_cost_model_daily (
+  container TEXT NOT NULL, date TEXT NOT NULL, provider TEXT NOT NULL, model TEXT NOT NULL,
+  tokens INTEGER, cost REAL, calls INTEGER,
+  PRIMARY KEY (container, date, provider, model)
+);
+-- One row per session seen; its figures are the session's total over the 30-day window.
+CREATE TABLE agent_cost_sessions (
+  container TEXT NOT NULL, session_id TEXT NOT NULL,
+  session_key TEXT, label TEXT, agent_id TEXT, provider TEXT, model TEXT,
+  tokens INTEGER, cost REAL, missing INTEGER,
+  first_activity INTEGER, last_activity INTEGER,        -- Unix milliseconds
+  PRIMARY KEY (container, session_id)
+);
+CREATE INDEX idx_cost_sessions_last ON agent_cost_sessions(last_activity);
+-- The check against the bill: at most once an hour, after a pass, each vendor's own figure
+-- and, read at the same moment, the agents' cumulative priced total for that vendor's
+-- models (agent_cost_model_daily rows whose model starts with '<vendor>/'). Kept 400 days.
+CREATE TABLE vendor_balance (
+  ts INTEGER NOT NULL,        -- Unix ms
+  vendor TEXT NOT NULL,       -- 'deepseek' | 'openrouter' (a key must be configured)
+  currency TEXT,
+  balance REAL,               -- DeepSeek: total balance; OpenRouter: credits − usage
+  usage REAL,                 -- OpenRouter: lifetime usage (only grows); NULL for DeepSeek
+  agents_cost REAL NOT NULL DEFAULT 0,
+  PRIMARY KEY (vendor, ts)
+);
+-- One row per container ever read: its name (AGENT_NAME) and how the last pass went.
+CREATE TABLE agent_cost_sources (
+  container TEXT PRIMARY KEY, agent_id TEXT, name TEXT,
+  collected_at INTEGER,       -- last stored pass, Unix ms
+  attempted_at INTEGER,       -- last attempt, Unix ms
+  error TEXT,                 -- why the last attempt stored nothing; NULL after a good one
+  missing_by_model TEXT       -- JSON {"rev4a/<model>": calls} over the 30-day window
+);
+```
+
 ## Credentials Database (`credentials.db`)
 
 The credential hub uses a **separate SQLite file** (`credentials.db`) alongside

package/docs/dev/GATEWAY.md

@@ -1,6 +1,6 @@
 # Gateway Page
 
-> **Last updated:** 2026-09-15
+> **Last updated:** 2026-09-27
 
 The Gateway page (`/gateway`) is the control panel for provider configuration:
 API keys and the model catalogue offered to every agent container. It does not
@@ -69,14 +69,15 @@ against the Rev4a provider proxy using this token. See [`PROVIDERS.md`](PROVIDER
 
 ### Sync Flow
 
-When a provider key is saved, a model toggle is changed, Sync All is pressed, or
-Rev4a starts, the Gateway:
+When a provider key is saved, a model toggle is changed, Sync All is pressed, Rev4a
+starts, or a time-of-day price changes (see [Costs](#costs-openclaw-prices-every-call)),
+the Gateway:
 
 1. **Reads** `models.config.json` and the overrides, and keeps the models that are
    enabled and whose provider has a key. If the file cannot be read and no earlier
    read succeeded, the sync stops here and reports `configError`
 2. **Builds** a `models.providers.rev4a` config block (without `rev4a/` prefix on
-   model IDs)
+   model IDs), each model carrying the `cost` in force now
 3. **Lists** every container with the `AGENT_ID` Docker label, **running or
    not**. Stopped agents are included so that starting one later does not bring
    back an old catalogue
@@ -92,6 +93,48 @@ Rev4a starts, the Gateway:
    the file's original mode, and apply it when started or resumed
 7. **Does NOT restart** the gateway
 
+### Costs: OpenClaw prices every call
+
+Every model in the `rev4a` block carries a `cost` — `{ input, output, cacheRead,
+cacheWrite }` in $ per 1M tokens, from `priceAt()` in `lib/model-pricing.ts`. That is the
+field OpenClaw's own cost accounting reads first after an agent's `models.json`, so each
+agent prices every call, session and day itself, with the cache split out, and shows it in
+its own Control UI too. Rev4a computes no cost: the daemon reads OpenClaw's figures into
+`costs.db` and the Costs page (`/costs`) shows them (see
+[DATABASE.md](DATABASE.md#costs-database-costsdb)).
+
+- **No price, no `cost`.** A model without an entry in `model-pricing.json` or with a
+  dynamic router price (`-1`, OpenRouter Auto) gets none, and OpenClaw counts its calls
+  as "missing cost" rather than $0. The Costs page lists them, by model.
+- **Free models** (all-zero price) are written with $0.000001 per 1M tokens for every
+  rate: OpenClaw treats an all-zero `cost` as no price and would count every call as
+  unpriced. A billion tokens come to $0.001.
+- **Unknown cache rate.** An entry without `cacheRead` falls back to the input rate
+  (cached tokens priced as if the cache gave no discount); one without `cacheWrite` to
+  1.25 × the input rate — vendors that bill cache writes apart charge more than input
+  (Anthropic's five-minute cache: 1.25×), and the ones that report no cache writes never
+  use it. Either way an overestimate, never an undercount. `refresh:pricing` writes them
+  for OpenRouter models when OpenRouter publishes them (104 and 44 of 181 entries when
+  added); direct vendors are filled by hand from their pricing page.
+- **Time-of-day prices.** DeepSeek bills half its rates off-peak (peak 01:00–04:00 and
+  06:00–10:00 UTC, Monday–Friday). `PRICE_SCHEDULES` in `lib/model-pricing.ts` holds
+  that schedule; `priceAt()` writes the rate of the moment, and
+  `lib/price-schedule-sync.ts` (started by `instrumentation.ts`) checks at most every
+  minute — and exactly at a change due within the minute — whether the bands in force
+  differ from the ones last written, and runs a full sync when they do; a sync that
+  missed an agent is retried every 5 minutes, at most 3 times for one band — an agent busy
+  with an update, recreate, restore or edit writes the prices itself when it finishes; the
+  bands count as written after any sync, since a sync that misses one agent writes all the
+  others — and a new change is written at once, whatever retry was pending. A check rather than one timer to the next
+  change: a timer fires late after the machine sleeps, a check a minute after it wakes
+  (simulated: asleep 01:05–05:00 UTC across the 04:00 change → synced at 05:00). OpenClaw keeps the cost it recorded at call
+  time, so a later change of rate does not reprice a call (verified with a real call,
+  priced off-peak and read again after the switch to peak). Chinese public holidays,
+  which DeepSeek bills off-peak all day, are priced as peak — a small overestimate.
+- **Calls made before a model had a price** are priced by OpenClaw when read, at the
+  rate in force then; OpenClaw reindexes its transcripts after a price change, which is
+  why a read can briefly answer `cacheStatus: refreshing`.
+
 ### Model ID Convention
 
 Inside `models.providers.rev4a.models`, model IDs are stored **without** the
@@ -503,11 +546,12 @@ The OpenRouter payload carries `pricing.prompt`, `pricing.completion`,
 same pass.
 
 For direct-provider prices, use the provider's own pricing page. DeepSeek's is
-at `api-docs.deepseek.com/quick_start/pricing`, and note it charges **peak and
-off-peak rates** (peak: 01:00–04:00 and 06:00–10:00 UTC, Mon–Fri; off-peak is
-half). `model-pricing.json` holds one figure per model and cannot express that,
-nor cache-hit rates — **record the peak rate**, so the dashboard overstates
-spend rather than understating it.
+at `api-docs.deepseek.com/quick_start/pricing`. Record the **peak** rates, and
+the cache-hit rate as `cacheRead` (`cacheWrite` is the input rate for a vendor that
+bills a cache miss as ordinary input); the off-peak discount is applied by
+`PRICE_SCHEDULES` in `lib/model-pricing.ts`, which is where a schedule change goes.
+These prices are what every agent's OpenClaw computes its costs with (see
+[Costs](#costs-openclaw-prices-every-call)).
 
 ### What to check, in order