@flame0510/project-aether 1.9.1 → 1.11.0

package/docs/dev/DATABASE.md

@@ -1,10 +1,11 @@
 # Rev4a — Database Reference
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-10-01
 
-Rev4a keeps three 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
+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 and container metrics, 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,139 @@ 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.
 
+### Container consumption (also in `metrics.db`)
+
+What each running container uses, and the disk Docker holds, so the System page can say
+*who* is using the machine. The daemon writes it from the Docker Engine API
+(`lib/docker-stats.js`; where the socket is comes from `lib/docker-socket-path.js`, shared
+with the dashboard's `lib/docker-socket.ts`); `lib/container-metrics.ts` reads it for
+`GET /api/metrics/containers`, the agent panel and the Containers page. The tables are
+created with `CREATE TABLE IF NOT EXISTS` when the daemon starts, so an update adds them;
+until then the API answers `available: false`.
+
+**Sampling:** containers every 60 s, on a timer of its own — a priming pass 6 s after the
+daemon starts (it only records the gauges: a CPU figure needs two readings), the first
+complete one 15 s later — and Docker's disk (`/system/df`) every 10 min, the first reading
+25 s after start. **Retention:** 30 days, pruned at every sample. A stopped container has no
+rows: a gap, not zeros. Size, estimated: 60 s × 10 containers × 30 days ≈ 430 000 rows ≈ 35 MB
+(to be measured on the VPS; rollups to 5 min may be added if it grows).
+
+```sql
+-- One row per running container per sample. CPU in cores (CPU-seconds per second), rates in
+-- bytes per second; each is NULL on the first sample after a start and when its counter went
+-- backwards (the container restarted) — never a negative rate or a spike. Memory is the
+-- working set: usage − inactive page cache, what `docker stats` shows.
+CREATE TABLE container_metrics (
+  ts INTEGER NOT NULL,            -- Unix seconds
+  container TEXT NOT NULL,
+  cpu_cores REAL,
+  mem_mb INTEGER,
+  pids INTEGER,
+  net_rx_bps INTEGER, net_tx_bps INTEGER,
+  blk_read_bps INTEGER, blk_write_bps INTEGER
+);
+CREATE INDEX idx_container_metrics_ts ON container_metrics(ts);
+CREATE INDEX idx_container_metrics_c_ts ON container_metrics(container, ts);
+
+-- Who each container is: an agent's name (AGENT_NAME), whether it is an agent, and its named
+-- volumes (the link to docker_storage). Forgotten after the retention.
+CREATE TABLE container_sources (
+  container TEXT PRIMARY KEY,
+  agent_id TEXT, name TEXT, is_agent INTEGER NOT NULL DEFAULT 0,
+  volumes TEXT,                   -- comma-separated volume names
+  last_seen INTEGER NOT NULL
+);
+
+-- Docker's own cores and memory: the denominators for a container's share (on Docker Desktop
+-- that is its VM — 8 GB of a 16 GB Mac — not the machine). One row.
+CREATE TABLE docker_host (id INTEGER PRIMARY KEY CHECK (id = 1), ncpu INTEGER, mem_total_mb INTEGER, updated_at INTEGER);
+
+-- Disk Docker holds, one set of rows per reading: kind 'volume' (name = the volume;
+-- reclaimable_mb = its size when no container uses it), 'layer' (name = a container, its
+-- writable layer), 'images' and 'build_cache' (totals; reclaimable_mb = what no container /
+-- no build uses). A size Docker could not compute is NULL.
+CREATE TABLE docker_storage (ts INTEGER NOT NULL, kind TEXT NOT NULL, name TEXT NOT NULL DEFAULT '', size_mb INTEGER, reclaimable_mb INTEGER);
+CREATE INDEX idx_docker_storage_ts ON docker_storage(ts);
+CREATE INDEX idx_docker_storage_kind_ts ON docker_storage(kind, name, ts);
+```
+
+## 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
 

package/docs/rag/DATA-FRESHNESS.md

@@ -1,6 +1,6 @@
 # Data Freshness in Rev4a
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-10-01
 
 Understanding how current the data in Rev4a is — and what is truly real-time vs. periodically updated.
 
@@ -11,7 +11,7 @@ Understanding how current the data in Rev4a is — and what is truly real-time v
 **Update frequency:** every 30 seconds
 
 The daemon polls `openclaw sessions --json --all-agents` on a fixed 30-second
-timer. Session statuses, token counts, and costs are therefore up to 30 seconds
+timer. Session statuses and token counts are therefore up to 30 seconds
 behind reality.
 
 The interval is fixed: it does not speed up while a session is `working`. Do not tell
@@ -56,12 +56,39 @@ the collector is not running instead of showing stale numbers as current.
 
 ---
 
-## Cost totals
+## Container consumption (System page, Containers page, agent panel)
 
-**Update frequency:** every 30 seconds (recalculated from sessions on each API call)
+**Update frequency:** every 60 seconds for CPU, memory, processes, network and block I/O of
+each running container; every 10 minutes for the disk Docker holds (volumes, writable layers,
+images, build cache). Both are sampled by the Rev4a daemon on timers of their own and kept 30
+days in `metrics.db`. The first figures after the daemon starts take about 20 seconds (a CPU
+figure needs two readings). A stopped container leaves a gap in its charts, not zeros.
 
-The cost figures shown in the dashboard are always computed fresh from the
-database on each page load or SSE push. They are not cached.
+CPU is a share of Docker's cores and memory a share of Docker's memory: on Docker Desktop that
+is its virtual machine (for example 8 GB of a 16 GB Mac), on a server it is the machine. If the
+newest sample is older than three minutes the System page says it is not collecting — the
+figures still on show are the last known ones, not live. The agent panel stands its "now" rows
+down, and the Containers page clears its usage row rather than leave stale figures. A container
+still seen in Docker's list but without fresh statistics says "no data", not "stopped".
+
+## Agent costs (Costs page)
+
+**Update frequency:** every 5 minutes. The Rev4a daemon asks each running agent
+what it spent and keeps the figures in their own database (`costs.db`); the page
+refreshes every minute. An agent whose figures could not be read recently is listed
+under **Not current** with the reason.
+
+The costs are computed by each agent's own OpenClaw, with the prices Rev4a writes
+into the agent for every model. A call to a model without a price is counted but not
+priced: the page lists those under **Calls without a price**. Days are UTC. DeepSeek
+bills half price off-peak; Rev4a switches the agents' prices at each change, so each
+call is priced at the rate it ran at.
+
+## Cost totals (dashboard)
+
+The dashboard's "Spent today" card and "Spent by model" list show the same figures as the
+Costs page, for today (UTC day): up to 5 minutes behind the agents. The vendor readings
+behind *Against the bill* on the Costs page are taken once an hour.
 
 **Cost override:** `/api/cost-override` exists, but no page in the dashboard
 reads or writes it. There is no UI for setting one, so do not direct a user to
@@ -143,7 +170,7 @@ The tracked set is `USER.md`, `MEMORY.md`, `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md
 
 System health is a card on the **Dashboard**, not a page of its own. Its checks
 cover session runtime, the daemon heartbeat, errors in the last 24 hours, today's
-usage-based cost, and cron jobs. CPU, RAM and disk are on the System page (`/system`)
+what the agents spent today, and cron jobs. CPU, RAM and disk are on the System page (`/system`)
 and the Dashboard's Machine card instead.
 
 To check directly on the server:

package/docs/rag/GLOSSARY.md

@@ -1,6 +1,6 @@
 # Rev4a Glossary
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-10-01
 
 Terms you'll encounter while using the Rev4a dashboard.
 
@@ -22,7 +22,7 @@ A compressed archive (`.tar.gz`) of an agent's persistent volume (`/root/`). Bac
 Which browsers may open an agent's Control UI. On OpenClaw 9.x every new browser must be approved once; the approval is remembered per browser. Managed in the "BROWSER ACCESS" section of the agent detail panel: approve or reject waiting browsers, rename or revoke approved ones. The Open button uses a one-time link that skips the approval. The Invite link button gives a link for someone else: their browser still waits for approval.
 
 ## Container
-A Docker container running on the server. Each agent runs in its own container. The Containers page shows all containers, including infrastructure ones such as databases and reverse proxies, with a web terminal link (a real shell in the browser; a dropped connection is resumed for 2 minutes). It shows no CPU or memory metrics.
+A Docker container running on the server. Each agent runs in its own container. The Containers page shows all containers (a running one also with its CPU, memory and processes now), including infrastructure ones such as databases and reverse proxies, with a web terminal link (a real shell in the browser; a dropped connection is resumed for 2 minutes).
 
 ## Channel
 A communication channel (Telegram) configured on an agent. Channels allow users to send DMs to the agent via messaging apps. The Channel Manager modal lets you connect/disconnect Telegram and manage pairings (approve/reject senders).
@@ -31,7 +31,10 @@ A communication channel (Telegram) configured on an agent. Channels allow users
 Modal in the agent detail panel for configuring Telegram channels. Connect with bot token, restart agent, manage pairings (approve pending codes, revoke approved senders). Pairings are polled every 5 seconds with automatic cancellation of stale requests via AbortController.
 
 ## Cost
-The estimated cost of an agent session in USD, calculated from tokens used and per-model pricing. Rev4a shows cost by today, 7 days, 30 days, all-time, and by model.
+What an agent spent in USD. Each agent's OpenClaw prices every model call itself, with the prices Rev4a writes into it (input, output, cached input), and Rev4a reads those figures every 5 minutes. The Costs page (`/costs`) shows them for today, 7 or 30 days — by day, by agent, by model, and the most expensive sessions. The dashboard's "Spent today" card shows the same figures for today, and each agent's panel on the Agents page has a COSTS section with its own. The Costs page also compares the agents' figures with what DeepSeek and OpenRouter actually billed (their balance or usage, read every hour).
+
+## Off-peak
+DeepSeek bills half price outside its peak hours (peak: 01:00–04:00 and 06:00–10:00 UTC, Monday–Friday). Rev4a writes the lower prices into the agents when off-peak starts and the full ones when it ends, so each call is priced at the rate in force when it ran. The Costs page header shows the current band.
 
 ## Cost Override
 A manual correction for a month's total cost, stored through `/api/cost-override`. There is currently no screen for it: no page in the dashboard reads or writes an override, so it can only be set by calling the API directly.
@@ -85,7 +88,7 @@ Replace an agent's persistent volume with a previously created backup. The conta
 Undo an agent's latest OpenClaw update: the backup taken just before the update is put back and the agent starts again on its previous version. Anything the agent did after the update is lost. Offered in the agent's OPENCLAW VERSION section while that backup exists.
 
 ## Session
-One instance of an agent doing work. Tracks: start/end time, tokens used, cost, model, status, and task description. A session starts when an agent receives a task and ends when it completes or fails.
+One instance of an agent doing work. Tracks: start/end time, tokens used, model, status, and task description; what a session cost is on the Costs page (most expensive sessions). A session starts when an agent receives a task and ends when it completes or fails.
 
 ## Pairing
 A security mechanism for Telegram channels. When a user sends `/start` to the bot, a 4-digit pairing code is generated. An admin must approve this code in the Channel Manager to add the user to the allowlist. Approved senders can be revoked at any time.
@@ -134,6 +137,6 @@ The directory where an agent's operational files live (config, memory files, ski
 The page with the machine Rev4a runs on: CPU (with cores and load), memory and swap, and each disk's used and free space, now and over 1 hour, 24 hours, 7 days or 30 days. A bar turns yellow and then red when it reaches a threshold (CPU and memory 85 % / 95 %, disk 80 % / 90 %), and the level is written next to it.
 
 ## System Health
-A card on the Dashboard reporting whether Rev4a itself is working, not the hardware it runs on. `/api/system-health` returns checks for session runtime, the daemon heartbeat (how old its latest machine sample is), errors in the last 24 hours, today's usage-based cost, and cron jobs, each with a health of `ok`, `warning` or `error`, plus a list of recommendations.
+A card on the Dashboard reporting whether Rev4a itself is working, not the hardware it runs on. `/api/system-health` returns checks for session runtime, the daemon heartbeat (how old its latest machine sample is), errors in the last 24 hours, today's what the agents spent today, and cron jobs, each with a health of `ok`, `warning` or `error`, plus a list of recommendations.
 
 It reports no CPU, RAM, disk or load average: those are on the System page (`/system`), sampled every 30 seconds by the daemon and kept for 30 days.

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,6 +1,6 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-10-01
 
 Rev4a is the control panel for your AI agent infrastructure. It shows you everything your agents are doing, how much they cost, and whether the system is healthy — all in one dashboard.
 
@@ -77,13 +77,20 @@ Interactive graph showing session family trees — which agent spawned which chi
 Connects agents to AI providers. Add and remove provider API keys, enable or disable individual models in the catalogue read from `models.config.json`, and push the resulting model list to every agent container. It does not assign models to agents: choosing which model an agent runs is done per agent, in the Model section of the agent's detail panel on the Agents page. Every model row has a **Details** button: the modal shows the model's description, price and provider, its architecture and parameter count when the weights are public, reasoning modes, capabilities, benchmarks with sources, licence and how much disk the weights take — the numbers come from the model card on Hugging Face and from curated entries that cite a source, never from estimates.
 
 ### Containers (`/containers`)
-Full list of all Docker containers on the server, including stopped ones. Each row shows name, status, image, IP, ports, and an agent pill where applicable. Click "Terminal" to open an interactive shell into that container.
+Full list of all Docker containers on the server, including stopped ones. Each row shows name, status, image, IP, ports, and an agent pill where applicable. Click "Terminal" to open an interactive shell into that container. A running container also shows what it consumes now — CPU share, memory and processes — with a "Charts" link to its history on the System page.
 
-The page shows no CPU or memory figures and has no start, stop, or restart buttons: it is read-only apart from the terminal link. Container lifecycle is managed from the Agents page.
+The page has no start, stop, or restart buttons: it is read-only apart from the terminal link. Container lifecycle is managed from the Agents page.
+
+### Costs (`/costs`)
+What each agent spent, as its own OpenClaw priced it with the prices Rev4a syncs. Pick today, 7 days or 30 days (UTC days): the total, where the money went (input, output, cache), the tokens and how much input came from cache, a chart of the spend per day, the spend by agent and by model, and the most expensive sessions. Calls that could not be priced are listed by model, and agents whose figures are not current are flagged. When a DeepSeek model is on offer, the header shows whether DeepSeek is billing peak or off-peak (half price) and until when. Figures are read from the agents every 5 minutes. *Against the bill* compares them with what DeepSeek and OpenRouter actually charged (their balance or usage, read every hour); a small gap is normal, since the same key may pay for the assistant too. Each agent's own spend is also in its panel on the Agents page (COSTS).
 
 ### System (`/system`)
 The machine Rev4a runs on. Three cards — CPU (percent, cores, load average), memory (used, available, swap) and storage (each disk with its used and free space, and whether it is the system disk, where Docker keeps agents, or where Rev4a keeps its data) — then charts of CPU, memory and each disk over 1 hour, 24 hours, 7 days or 30 days (for CPU and memory the average line with the peak shaded). Hover a chart (or focus it and use the arrow keys) to read a point; each chart has a Table view. Bars turn yellow and red when they reach their thresholds. Figures refresh every 30 seconds; history is kept 30 days.
 
+### Agents and containers (on the System page)
+Under the machine's charts: what Docker holds on disk (images, volumes, writable layers, build cache, and how much of each no container uses), then one row per container sorted by CPU. A closed row shows its name, whether it is an agent, and its CPU share, memory, storage and processes now, with the average and peak over the chosen range (1 hour to 30 days); open it for the same three charts as the machine — CPU, Memory, Storage — for that container. "Everything else" is what is not a container (the host, Rev4a, other software). Each agent's panel on the Agents page has the same numbers in its RESOURCES section, with a link to its charts. Below, the machine's recent alerts: CPU, memory or a disk that crossed its limit, and when.
+When Docker still sees a container but it has no current statistics, its row says "no data". If collection stops, the current figures are hidden and old rows say "not current" instead of implying a live reading.
+
 ### Container Terminal (`/containers/terminal/[id]`)
 Live web terminal into a running Docker container — like SSH in the browser: Tab completion, command history, `top`, `vi`, resizing with the window. If the connection drops (network, laptop sleep) the shell keeps running for 2 minutes and reconnecting picks it up; reloading the page resumes it too. **Close** ends the shell. If the container is stopped or missing, the page says so and offers **Reconnect**. Only a logged-in user can open it.
 

package/docs/rag/WHAT-I-CAN-ANSWER.md

@@ -1,6 +1,6 @@
 # What PULSE Can Answer
 
-> **Last updated:** 2026-09-26
+> **Last updated:** 2026-10-01
 
 PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
 
@@ -11,6 +11,9 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "Where do I find the agents page?"
 - "How do I get to the container list?"
 - "Where do I see CPU, RAM or disk usage of the server?" — The System page (`/system`), and the Machine card on the Dashboard.
+- "Which agent is using the most CPU or memory?" — The "Agents and containers" section of the System page: one row per container, sorted by CPU, with memory, storage and processes; open a row for its charts. An agent's own panel has the same numbers under RESOURCES.
+- "What is filling the disk?" — The "Docker storage" block on the System page: images, volumes (an unused volume is named), writable layers and build cache.
+- "Why is there a red bar or an alert on the System page?" — "Recent alerts" at the bottom of the System page lists what crossed its limit and when.
 - "Where can I see the first-run wizard?"
 - "Is there a page for cron jobs?"
 - "Where can I see my AI providers?" — The Gateway page (`/gateway`) shows providers and the model catalogue. Which model an agent runs is on the Agents page, in that agent's detail panel.
@@ -20,7 +23,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "How does the custom agent bootstrap work?"
 - "Where is the lineage graph?"
 - "How do I open the file explorer?"
-- "Which page shows costs?"
+- "Which page shows costs?" — The Costs page (`/costs`): what each agent spent, by day, agent, model and session.
 - "Where do I manage credentials (GitHub, Trello, etc.)?"
 - "How do I connect an agent to Telegram?"
 - "How do I approve a Telegram pairing?"
@@ -93,7 +96,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 ## Troubleshooting Questions
 
 - "Why is my agent not showing up?"
-- "Why are costs missing for some sessions?"
+- "Why are costs missing for some sessions?" — On the Costs page, calls to a model without a price are listed under "Calls without a price": the model left the catalogue or has no price yet.
 - "Why can't I connect to the container terminal?"
 - "Why is the gateway sync not working?"
 - "How do I check if the daemon is running?"

package/instrumentation.ts

@@ -7,12 +7,14 @@
  */
 export async function register() {
   if (process.env.NEXT_RUNTIME === 'nodejs') {
+    let startupSynced = false;
     try {
       const { syncAllAgents } = await import('./app/api/gateway/sync');
       // The outcome used to be discarded. syncAllAgents reports failures instead of
       // throwing, so the catch below never saw a sync that reached no container —
       // Docker not yet up at boot left the fleet stale with nothing in the log.
       const outcome = syncAllAgents();
+      startupSynced = outcome.ok;
       if (outcome.ok) {
         console.log(`[rev4a] Startup sync: ${outcome.summary}`);
       } else {
@@ -22,6 +24,15 @@ export async function register() {
       // Best-effort — don't block startup if sync fails
       console.warn('[rev4a] Failed to sync agents on startup');
     }
+    // Prices that change with the time of day (DeepSeek off-peak): write the new rates
+    // into every agent at each change, so OpenClaw prices each call at the rate it ran at.
+    // A startup sync that missed an agent is written again by the first check.
+    try {
+      const { startPriceScheduleSync } = await import('./lib/price-schedule-sync');
+      startPriceScheduleSync(startupSynced);
+    } catch {
+      console.warn('[rev4a] Could not start the price schedule re-sync');
+    }
     // Updates cut off by the restart: no job runs in a fresh process, so any update
     // still marked active becomes `interrupted` and waits for the operator.
     try {