@flame0510/project-aether 1.7.0 → 1.8.0

package/docs/ARCHITECTURE.md

@@ -72,7 +72,7 @@
 
 **Credentials vault:** The `/credentials` page stores third-party service tokens in `credentials.db` and installs them into containers on explicit sync. Provider API keys live separately in `provider-keys.json`, managed from the Gateway UI.
 
-**Container management UI:** The `/containers` page lists all running Docker containers with resource usage and quick links, and opens a web terminal into any of them. Fully functional.
+**Container management UI:** The `/containers` page lists all Docker containers, running or stopped, with status, image, IP and ports, and opens a web terminal into any of them. Fully functional. (Machine CPU, RAM and disk are on `/system`.)
 
 **Workspace API:** Lazy-loaded file tree explorer with real-time reads (no caching), supports both host and container workspaces via `docker exec`.
 
@@ -81,7 +81,7 @@
 | Feature | Status | Notes |
 |---|---|---|
 | Credentials (UI + API) | 🟢 Implemented | SQLite, no encryption yet |
-| Container page | 🟢 Functional | Lists all containers, resources, web terminal |
+| Container page | 🟢 Functional | Lists all containers, web terminal |
 | Agent creation wizard | 🟢 Implemented | One-click create with model/template selection |
 | Provider proxy | 🟢 Implemented | Agents route through Rev4a provider gateway |
 | Shared volumes | 🟢 Implemented | Skills + repos mounted on all agents |
@@ -575,15 +575,16 @@ The Rev4a daemon (`daemon.js`) is a standalone Node.js process that bridges the
 1. Poll `openclaw sessions --json --all-agents` every 30 s
 2. Upsert session rows into `events.db`
 3. Emit `spawn` / `complete` / `fail` / `spawn_timeout` events into the `events` table
-4. Collect system metrics (CPU, RAM, disk) after every completed poll
-5. Detect anomalies (CPU > 85%, RAM > 90%) and record them
-6. Manage DB lifecycle (WAL mode, checkpoint after each cycle)
+4. Sample the host machine (CPU, RAM, swap, storage) every 30 s into `metrics.db`, on a
+   timer of its own
+5. Detect anomalies (CPU > 85%, RAM > 90%, a disk > 90%) and record them as events
+6. Manage DB lifecycle (WAL mode; events.db checkpointed after each poll cycle)
 
 ### Poll Interval
 
 A fixed 30 s timer, whether or not sessions are working. When the OpenClaw CLI is not on
-the host, the daemon logs it once and stays idle — and then records no system metrics
-either, since they are collected at the end of a poll.
+the host, the session poll logs it once and stays idle; the machine metrics keep being
+sampled, since they have their own timer.
 
 ### Cost Estimation
 
@@ -625,29 +626,41 @@ The daemon uses `INSERT … ON CONFLICT DO UPDATE` with these rules:
 
 ### System Metrics
 
-After every completed poll the daemon records a `system_metrics` row. Data sources:
+Every 30 s (`METRICS_INTERVAL_MS`) the daemon samples the machine it runs on and writes a
+`system_metrics` row plus one `system_disks` row per filesystem into `metrics.db` — its
+own database next to `events.db` (schema in `docs/dev/DATABASE.md`). Machine-wide sources:
+
+- **CPU**: busy share of all cores since the previous sample, from host ticks
+  (`os.cpus()`, i.e. `/proc/stat` on Linux) — the whole machine, not Rev4a's cgroup
+- **RAM / swap**: `/proc/meminfo` on Linux, used = `MemTotal − MemAvailable` (what `free`
+  shows); on macOS (development) active + wired + compressed pages from `vm_stat` and
+  `vm.swapusage`; elsewhere `os.totalmem()` / `os.freemem()` and no swap
+- **Storage**: `fs.statfsSync()` on `/`, Docker's data root (`docker info`, asked once and
+  retried every 10 min while Docker is down) and Rev4a's data directory, each device once;
+  a path that cannot be read (Docker Desktop's root inside its VM) is skipped
+- **Load**: `os.loadavg()` 1 / 5 / 15 min
+
+The first sample comes about 5 s after start (the CPU figure needs a delta from the baseline
+taken at load), then one every 30 s. Samples older than 30 days are pruned at every sample.
+`metrics.db` is opened in a try: if it cannot be (corrupt, unwritable), sampling is off —
+`[METRICS] disabled` in the log — and the session poll keeps running. The API side reads
+it through `lib/metrics-db.ts` (read-only, `null` when there is nothing to read);
+`GET /api/metrics` serves the System page (`/system`) and the dashboard's Machine card.
 
-- **CPU**: cgroup v2 usage delta (`/sys/fs/cgroup/cpu.stat`) when available, falls back to host ticks from `os.cpus()`
-- **RAM**: `os.totalmem()` / `os.freemem()`
-- **Disk**: `fs.statfsSync()` on the directory holding the events database — the
-  filesystem Rev4a's own data lives on; works the same on Linux and macOS
-- **Load**: `os.loadavg()[0]`
+### Anomaly Detection
 
-Metrics older than 30 days are pruned automatically each cycle.
+After each sample the daemon inserts a `system_anomaly` event into `events.db`
+(`{ metric, values, threshold, message }`) and logs `[ANOMALY] <message>` when:
 
-### Anomaly Detection
+| Metric | Condition | Repeats |
+|---|---|---|
+| CPU | > 85% on two consecutive samples | at most once per 5 min |
+| RAM | > 90% on two consecutive samples | at most once per 5 min |
+| Disk (each filesystem) | ≥ 90% | once when it reaches it, no cooldown — again only after it drops back under, or after the daemon restarts |
 
-The daemon compares the last two metric samples. When both exceed a threshold and the
-cooldown (5 min per metric) has passed, it inserts a `system_anomaly` event
-(`{ metric, values, threshold, message }`) and logs `[ANOMALY] CPU high: N%` or
-`[ANOMALY] RAM high: N%`. No feature consumes `system_anomaly` events yet; they only pass through the generic
+No feature consumes `system_anomaly` events yet; they only pass through the generic
 event feeds.
 
-| Metric | Threshold (two consecutive samples) |
-|---|---|
-| CPU | > 85% |
-| RAM | > 90% |
-
 ### DB Safety
 
 - WAL mode + `PRAGMA synchronous = NORMAL` for concurrent read safety

package/docs/DESIGN-SYSTEM.md

@@ -82,6 +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`.
 
 ### React hook
 

package/docs/FRONTEND-ARCHITECTURE.md

@@ -38,6 +38,8 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `ModalityIcons` | `ModalityIcons.tsx` | Capability badges parsed from a model's `modality` string (`"text+image->text"`). Input types render as icons; a non-text **output** is called out separately, since reading an image and generating one are different capabilities. Pass `dynamic` for router models, which advertise the union of everything they might route to and so show "varies" instead. |
 | `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. |
 | `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. |
@@ -45,6 +47,8 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `UpdateSection` | `app/agents/UpdateSection.tsx` | OPENCLAW VERSION section of the agent detail panel: the version the agent runs, **Update to <version>** when a newer supported version is downloaded (confirm modal, disabled while the agent is stopped), the running update's steps with backup progress, the outcome, and **Roll back to <version>** after an update. Polls `/api/agents/[id]/update` every 2 s while an update or rollback runs; one action at a time (keyed busy state). |
 | `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. |
+| 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. |
 | `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. |
 | `VersionBanner` | `app/components/VersionBanner.tsx` | "Update available" banner for Rev4a itself, when `GET /api/update-check?check=1` reports a newer published version (dismissable per version, remembered in `localStorage`). **Update now** starts `POST /api/update-check`; because that update restarts the server, the banner cannot be told the outcome by the response: it records what it asked for in `sessionStorage`, polls `/api/update-check` until the installed version moves (two minutes at most) and reloads, then on the next mount either confirms "Updated to vX" or reports that the update did not complete and points at `update.log` (the update's own output). It never reloads blindly onto the same version. |
 | `BrowserAccessSection` / `OpenControlUiButton` | `app/agents/BrowserAccessSection.tsx` | Browser access to one agent's Control UI, in its detail panel: requests waiting for approval (Approve / Reject) and approved browsers (Rename / Revoke), refreshed every 5 s while mounted. A successful approve, reject, rename or revoke updates the list at once, since the refresh behind it runs the OpenClaw CLI and takes seconds; a read started before the mutation is discarded. On agents that require approval, "Invite link" fetches `/api/agents/[id]/invite-link` and shows the link in a read-only field with Copy, which uses the Clipboard API in a secure context and the field's selection over plain HTTP, plus a warning when the link uses localhost. `OpenControlUiButton` opens `/api/agents/[id]/open-control-ui` in a new tab inside the click; that route redirects to a one-time link that pairs the browser with no approval, or to the plain token link when none can be issued. Used on the agent cards and in the panel. |
@@ -58,7 +62,7 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | Wizard icons | `app/wizard/icons.tsx` | Shared SVG icons (flyweight pattern): `ArrowRightIcon`, `CheckIcon`, `CheckCircleIcon`, `DockerIcon`, `GatewayIcon`, `AgentIcon`, `TemplateIcon`, `LinkIcon`, `ConfigIcon`, `InformationIcon`. |
 | `tokens` | `tokens.ts` | TypeScript types for `Tone` and related token values. |
 | `Badge` | `Badge.tsx` | Inline status tag with tone variants (success, danger, warning, neutral). Used for channel chips, pairing labels, error/success messages. |
-| `Skeleton` + shape helpers | `app/components/Skeleton.tsx` | Shimmer placeholders. `Skeleton` is the primitive; the rest mirror one specific layout each: `TreeSkeleton`, `CodeSkeleton`, `CronJobsSkeleton`, `CronRunsSkeleton`, `CredentialCardsSkeleton`, `AgentSyncRowsSkeleton`, `SkeletonLines`, `SkeletonMetric`, `CardRowSkeleton`. A shape helper must match the real markup it stands in for — same row structure, same paddings, same element count where the count is known — so nothing reflows when data replaces it. |
+| `Skeleton` + shape helpers | `app/components/Skeleton.tsx` | Shimmer placeholders. `Skeleton` is the primitive; the rest mirror one specific layout each: `TreeSkeleton`, `CodeSkeleton`, `CronJobsSkeleton`, `CronRunsSkeleton`, `CredentialCardsSkeleton`, `AgentSyncRowsSkeleton`, `SkeletonLines`, `SkeletonMetric`, `CardRowSkeleton`. A shape helper must match the real markup it stands in for — same row structure, same paddings, same element count where the count is known — so nothing reflows when data replaces it. Inside text (a `<p>`, a `<span>`) pass `as="span"`: a `<div>` there is invalid HTML, and the parser splits the paragraph in the server-rendered page. The System page keeps its own shapes in `app/system/SystemSkeleton.tsx`, each shimmer inside the class of the text it replaces so the line boxes are the real ones — measured to 0 px of movement on desktop and mobile. |
 
 ### Rules
 
@@ -153,7 +157,7 @@ For interactive pages that can change view/file/tab quickly:
 For every new/changed page:
 
 1. No new one-off card styles unless justified.
-2. Use `app/components/ui/*` primitives first — `Button`, `Input`, `Select`, `Modal`, `Toast`, `Surface`, `Metric`, `StatusCard`, `Pill`, `Page`, `Tabs`, `ItemList`, `FilterBar`, `PropertyList`, `TemplateOption`, `LoadingSpinner`.
+2. Use `app/components/ui/*` primitives first — `Button`, `Input`, `Select`, `Modal`, `Toast`, `Surface`, `Metric`, `StatusCard`, `Meter`, `TimeSeriesChart`, `Pill`, `Page`, `Tabs`, `ItemList`, `FilterBar`, `PropertyList`, `TemplateOption`, `LoadingSpinner`.
 3. Async data must render skeleton, not fake zero values.
 4. Business logic stays in `lib`/API routes; UI consumes typed payloads.
 5. If a pattern is introduced, name it and keep it in `lib/patterns` or `app/components/ui`.

package/docs/REV4A.md

@@ -97,9 +97,10 @@ When environment variables are saved via the Config page (Save & Restart):
 
 | Route | Description |
 |---|---|
-| `/` | System overview — containers, resources, quick links |
+| `/` | System overview — health, sessions, the machine's CPU / RAM / disk (links to `/system`), cost, 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 |
+| `/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 |
 | `/lineage` | Agent lineage / orchestration tree |

package/docs/dev/API-REFERENCE.md

@@ -1906,25 +1906,50 @@ Register a parent→child relationship between sessions.
 ## Metrics
 
 ### `GET /api/metrics`
-System metrics from the daemon's `system_metrics` table: the latest sample, the most
-recent samples, and 24 h CPU aggregates.
+Machine metrics of the host Rev4a runs on — CPU, RAM, swap, storage — read from
+`metrics.db` (written by the daemon every 30 s, see `docs/dev/DATABASE.md`): the latest
+sample, live host facts, and a bucketed history for one range. The System page
+(`/system`) and the dashboard's Machine card use it.
 
 **Auth:** Bearer or browser cookie
 
-**Query:** `limit` — how many `history` rows (default 60, max 1000): the most recent ones, returned oldest first.
+**Query:** `range` — `1h` (default), `24h`, `7d` or `30d`; anything else answers `400`.
+The range is cut into buckets of `bucket_s` seconds (about 120 points, never shorter than
+60 s — two samples, so a timer that drifts a second leaves no false gaps), each with its
+average and peak: 60 s for `1h`, 720 s for `24h`, 5040 s for `7d`, 21 600 s for `30d`.
 
 **Response:**
 ```json
 {
-  "latest": { "cpu": 12.5, "ram_used_mb": 1820, "ram_total_mb": 4096, "disk_used_gb": 38, "disk_total_gb": 100, "load_avg": 0.42, "ts": 1749201000 },
-  "history": [ { "cpu": 12.5, "ram_used_mb": 1820, "ram_total_mb": 4096, "ts": 1749201000 } ],
-  "stats_24h": { "cpu_avg": 14, "cpu_max": 68 }
+  "latest": {
+    "ts": 1790419256, "age_s": 12, "cpu": 21.5,
+    "ram_used_mb": 4779, "ram_total_mb": 7851, "swap_used_mb": 2048, "swap_total_mb": 4096,
+    "load_avg_1m": 1.35, "load_avg_5m": 1.56, "load_avg_15m": 1.21,
+    "disks": [
+      { "mount": "/", "roles": ["root", "docker", "data"], "used_mb": 61440, "avail_mb": 38912, "total_mb": 102400, "percent": 61 }
+    ]
+  },
+  "host": { "hostname": "vps", "platform": "linux", "cores": 4, "uptime_s": 290000 },
+  "interval_s": 30,
+  "range": "1h",
+  "bucket_s": 60,
+  "history": [ { "ts": 1790419230, "cpu_avg": 21.5, "cpu_max": 29.1, "ram_avg": 60.9, "ram_max": 61.2 } ],
+  "disk_history": [ { "mount": "/", "points": [ { "ts": 1790419230, "percent": 61 } ] } ]
 }
 ```
 
-`ts` is in **seconds**. The daemon records one sample per completed poll (every 30 s) and keeps
-30 days. A host without the OpenClaw CLI records none: the daemon stays idle there,
-and `latest` is `null`.
+- `ts` values are in **seconds**; a `history` point's `ts` is the start of its bucket.
+  Buckets with no samples are absent (the daemon was not running), not zero.
+- `ram_used_mb` is total − available, the figure `free` shows (Linux `/proc/meminfo`); on
+  macOS active + wired + compressed pages. `swap_*` are `null` where there is no swap
+  figure. `ram_avg`/`ram_max` are percentages.
+- `disks`: each filesystem once — `/`, Docker's data root (`docker info`), and Rev4a's
+  data directory, merged when they are the same device; `roles` says which of the three
+  it is. `percent` is used / (used + available), as `df` computes it.
+- `latest` is `null` before the daemon's first sample (the database is created when the
+  daemon starts, the first sample about 5 s later), and when `metrics.db` has no tables. `age_s` older than 3 × `interval_s`
+  means the daemon is not sampling; the page says so.
+- `host` is read live by the API process, which runs on the same host.
 
 ---
 
@@ -1932,7 +1957,11 @@ and `latest` is `null`.
 
 ### `GET /api/system-health`
 Aggregated checks of the runtime, cron jobs and usage cost, with recommendations. It
-does not report CPU, RAM, disk or the Docker daemon (those are in `GET /api/metrics`).
+does not report CPU, RAM or disk (those are in `GET /api/metrics`). Its `runtime.heartbeat`
+check ("Daemon heartbeat") reads the age of the newest machine metrics sample in
+`metrics.db`: it shows the daemon is alive, not that the OpenClaw session poll ingests —
+the two run on separate timers. A `metrics.db` that cannot be read makes this one check
+say so; it does not fail the others.
 
 **Auth:** browser cookie or bearer token
 
@@ -1950,7 +1979,7 @@ does not report CPU, RAM, disk or the Docker daemon (those are in `GET /api/metr
 }
 ```
 
-Checks: `runtime.sessions`, `runtime.ingestion`, `runtime.errors24h`,
+Checks: `runtime.sessions`, `runtime.heartbeat`, `runtime.errors24h`,
 `cost.usageBasedToday`, `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

@@ -2,13 +2,16 @@
 
 > **Last updated:** 2026-09-26
 
-Rev4a uses a single SQLite file (`events.db`) in WAL mode.
+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
+[Credentials Database](#credentials-database-credentialsdb)).
 
 ## Location
 
 | Environment | Path |
 |---|---|
-| VPS (default) | `/path/to/rev4a/data/events.db` |
+| Default | `~/.config/rev4a/data/events.db` (`$REV4A_DATA_DIR/data/events.db`) |
 | Custom | Set `REV4A_DB` env var |
 
 ## WAL Mode
@@ -19,8 +22,9 @@ PRAGMA synchronous = NORMAL;
 ```
 
 - The daemon writes; the Next.js API routes open read-only connections
-- `PRAGMA wal_checkpoint(PASSIVE)` runs after each daemon poll cycle
-- WAL files: `events.db-shm`, `events.db-wal` — do not delete while daemon is running
+- `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
+- WAL files (`*.db-shm`, `*.db-wal`) — do not delete while the daemon is running
 
 ## Tables
 
@@ -88,27 +92,9 @@ 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.
 
-### `system_metrics` — infrastructure metrics
-
-```sql
-CREATE TABLE system_metrics (
-  id           INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts           INTEGER NOT NULL,
-  cpu_percent  REAL,
-  ram_used_mb  INTEGER,
-  ram_total_mb INTEGER,
-  disk_used_gb REAL,
-  disk_total_gb REAL,
-  load_avg_1m  REAL
-);
-
-CREATE INDEX idx_metrics_ts ON system_metrics(ts);
-```
-
-Rows older than 30 days are pruned automatically by the daemon (one row per completed 30 s poll;
-none on a host without the OpenClaw CLI, where the daemon stays idle).
-No feature consumes the `system_anomaly` events the daemon writes to `events` yet; they
-only pass through the generic event feeds.
+The daemon also writes a `system_anomaly` event (session `system`) when the machine
+crosses a threshold — see [Metrics Database](#metrics-database-metricsdb). No feature
+consumes those events yet; they only pass through the generic event feeds.
 
 ### `agent_upgrades` — agent updates and rollbacks
 
@@ -255,6 +241,60 @@ 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.
 
+## Metrics Database (`metrics.db`)
+
+Machine metrics of the host — CPU, RAM, swap, storage — kept apart from `events.db`, so
+the event log holds sessions and events only and the history can be dropped on its own.
+
+**Location:** `data/metrics.db`, next to `events.db` (it follows `REV4A_DB`'s directory; both
+the daemon and the API resolve the data directory the same way, `REV4A_DATA_DIR` included).
+**Created by** the daemon when it starts (`CREATE TABLE IF NOT EXISTS`), which is also its
+only writer; `GET /api/metrics` and `GET /api/system-health` read it
+(`lib/metrics-db.ts`). Until the daemon has run once the file does not exist, and the
+API answers with `latest: null`. If the daemon cannot open it (corrupt, unwritable), it
+logs `[METRICS] disabled` and keeps polling sessions without sampling.
+**Sampling:** the first sample about 5 s after the daemon starts, then every 30 s, on a timer
+of its own — independent of the OpenClaw session poll.
+**Retention:** 30 days, pruned at every sample: ~86 400 `system_metrics` rows, and one
+`system_disks` row per filesystem per sample (up to ~259 200 for three).
+
+```sql
+CREATE TABLE system_metrics (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts            INTEGER NOT NULL,   -- Unix seconds
+  cpu_percent   REAL,               -- all cores, busy share since the previous sample
+  ram_used_mb   INTEGER,            -- total − available (Linux), as `free` shows it
+  ram_total_mb  INTEGER,
+  swap_used_mb  INTEGER,            -- NULL where there is no swap figure
+  swap_total_mb INTEGER,
+  load_avg_1m   REAL,
+  load_avg_5m   REAL,
+  load_avg_15m  REAL
+);
+CREATE INDEX idx_metrics_ts ON system_metrics(ts);
+
+-- One row per filesystem per sample: `/`, Docker's data root and Rev4a's data directory,
+-- each device once; roles lists which of them it is (e.g. 'root,docker,data').
+CREATE TABLE system_disks (
+  ts       INTEGER NOT NULL,        -- the same ts as the system_metrics row
+  mount    TEXT NOT NULL,
+  roles    TEXT,
+  used_mb  INTEGER,                 -- blocks − free
+  avail_mb INTEGER,                 -- what a normal user can still write
+  total_mb INTEGER
+);
+CREATE INDEX idx_disks_ts ON system_disks(ts);
+CREATE INDEX idx_disks_mount_ts ON system_disks(mount, ts);
+```
+
+**Anomalies** go to `events.db` as `system_anomaly` events: CPU above 85 % or RAM above
+90 % on two consecutive samples (at most once per 5 minutes per metric), and a filesystem
+at 90 % or more once when it reaches the threshold, with no cooldown (again only after it
+has dropped back under, or once after each daemon start: the state is kept in memory).
+
+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.
+
 ## Credentials Database (`credentials.db`)
 
 The credential hub uses a **separate SQLite file** (`credentials.db`) alongside

package/docs/rag/DATA-FRESHNESS.md

@@ -35,20 +35,24 @@ sends exactly three things:
 Lineage is **not** pushed over the stream; the Lineage page fetches it itself.
 
 The event feed is as close to real-time as Rev4a gets. However, events are
-generated by the daemon's poll cycle, so an event that just happened may take up
+generated by the daemon every 30 seconds — session events by its poll of OpenClaw,
+system anomalies by its machine sampling — so an event that just happened may take up
 to 30 seconds to appear, plus up to 5 more to reach the browser.
 
 ---
 
 ## System metrics (CPU, RAM, disk)
 
-**Update frequency:** every completed daemon poll cycle (30 seconds). A host without the
-OpenClaw CLI records no metrics at all: the daemon stays idle there.
+**Update frequency:** every 30 seconds, sampled by the Rev4a daemon on its own timer
+(it does not depend on OpenClaw being installed on the host). The System page refreshes
+every 30 seconds too, so a figure is at most about a minute old.
 
-**Retention:** 30 days (older rows are pruned automatically each cycle)
+**Retention:** 30 days, in their own database (`metrics.db`).
 
-These metrics are collected and stored, and served by `GET /api/metrics`. They
-are **not** shown on the dashboard — see the System Health note below.
+Shown on the **System** page (`/system`) — current CPU, memory, swap and storage, and
+their history over 1 hour, 24 hours, 7 days or 30 days — and, as three figures, on the
+Dashboard's Machine card. If the newest sample is older than 90 seconds the page says
+the collector is not running instead of showing stale numbers as current.
 
 ---
 
@@ -138,8 +142,9 @@ The tracked set is `USER.md`, `MEMORY.md`, `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md
 ## How to check if data is fresh
 
 System health is a card on the **Dashboard**, not a page of its own. Its checks
-cover session runtime, ingestion freshness, errors in the last 24 hours, today's
-usage-based cost, and cron jobs. It reports no CPU, RAM, or disk figures.
+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`)
+and the Dashboard's Machine card instead.
 
 To check directly on the server:
 ```bash

package/docs/rag/GLOSSARY.md

@@ -43,7 +43,7 @@ A third-party service token (GitHub PAT, Trello API key, Vercel token, Supabase
 A scheduled task that runs an agent automatically at a fixed time (e.g. every night at 3:15 AM). Configured with standard cron syntax. Jobs can be enabled/disabled per entry.
 
 ## Dashboard
-The main page of Rev4a (`/`). Shows live sessions, cost summary, health cards for Rev4a's runtime, cron and lineage, and a real-time event feed. It shows no CPU, RAM, disk or load average, and there is no setup banner: an incomplete wizard redirects to `/wizard`.
+The main page of Rev4a (`/`). Shows live sessions, cost summary, health cards for Rev4a's runtime, cron and lineage, and a real-time event feed. Its Machine card shows the server's CPU, RAM and fullest disk right now, with a link to the System page. There is no setup banner: an incomplete wizard redirects to `/wizard`.
 
 ## Event
 A lifecycle occurrence for a session: spawned, completed, failed, or missing too long (spawn timeout); the daemon also records system anomalies (high CPU or RAM) as events. Events appear in the live feed on the Dashboard and are pushed via SSE every 5 seconds.
@@ -130,7 +130,10 @@ Rev4a's store for third-party service tokens (GitHub, Trello, Vercel, Supabase,
 ## Workspace
 The directory where an agent's operational files live (config, memory files, skills, plugins, scripts). The Workspace page lets you browse, view, and edit files across the host workspace, which appears as `Local`, and all agent containers.
 
+## System (page)
+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, feed ingestion freshness, 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 usage-based cost, 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 metrics are collected by the daemon and stored for 30 days, and are served by `/api/metrics`, but no page displays them.
+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

@@ -9,7 +9,7 @@ Rev4a is the control panel for your AI agent infrastructure. It shows you everyt
 ### Dashboard (`/`)
 The main page. See live sessions (who's working right now), cost summary, an overall health indicator, and a real-time event feed. Click any session row to open the Session Drawer and see every tool call the agent made.
 
-The health cards cover Rev4a's own runtime, cron and watchdog, and lineage. They do **not** show CPU, RAM, disk, or load average: those metrics are collected and stored, but no page displays them. There is no wizard banner on the dashboard; an incomplete setup redirects to `/wizard` instead.
+The health cards cover Rev4a's own runtime, cron and watchdog, and lineage. The Machine card shows the server's CPU, RAM and fullest disk right now, coloured when it reaches a threshold, and links to the System page for details. There is no wizard banner on the dashboard; an incomplete setup redirects to `/wizard` instead.
 
 ### First-run wizard (`/wizard`)
 First-run setup wizard that guides new users through configuration. Four steps:
@@ -81,6 +81,9 @@ Full list of all Docker containers on the server, including stopped ones. Each r
 
 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.
 
+### 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.
+
 ### Container Terminal (`/containers/terminal/[id]`)
 Live web terminal into a Docker container. Run commands, inspect files, debug issues — like SSH but in the browser.
 

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

@@ -10,6 +10,7 @@ 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.
 - "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.

package/lib/db-bootstrap.mjs

@@ -91,16 +91,6 @@ export function initializeRev4aDb(dbPath) {
       updated_at INTEGER
     );
 
-  CREATE TABLE IF NOT EXISTS system_metrics (
-      ts INTEGER PRIMARY KEY,
-      cpu_percent REAL,
-      ram_used_mb INTEGER,
-      ram_total_mb INTEGER,
-      disk_used_gb REAL,
-      disk_total_gb REAL,
-      load_avg_1m REAL
-    );
-
     CREATE TABLE IF NOT EXISTS alert_state (
       alert_key TEXT PRIMARY KEY,
       kind TEXT NOT NULL,
@@ -114,7 +104,6 @@ export function initializeRev4aDb(dbPath) {
     CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id, ts);
     CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at);
     CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at);
-    CREATE INDEX IF NOT EXISTS idx_metrics_ts ON system_metrics(ts);
     CREATE INDEX IF NOT EXISTS idx_tool_calls_session ON tool_calls(session_id, ts);
     CREATE INDEX IF NOT EXISTS idx_alert_state_updated ON alert_state(updated_at);
   `);

package/lib/metrics-db.ts

@@ -0,0 +1,48 @@
+// Read access to the machine metrics database (daemon.js writes it).
+import fs from 'fs';
+import path from 'path';
+import Database from 'better-sqlite3';
+import { DB_PATH } from './db';
+
+/** Next to events.db, as daemon.js places it; its own file so the event log stays clean. */
+export const METRICS_DB_PATH = path.join(path.dirname(DB_PATH), 'metrics.db');
+
+/**
+ * Open the metrics database read-only, or null when there is nothing to read yet: no file
+ * (first start, or a daemon that never ran) or a file without the daemon's tables (it
+ * failed right after creating it). The daemon owns the schema.
+ */
+export function openMetricsDb(): Database.Database | null {
+  if (!fs.existsSync(METRICS_DB_PATH)) return null;
+  const db = new Database(METRICS_DB_PATH, { readonly: true, fileMustExist: true });
+  try {
+    const tables = db
+      .prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name IN ('system_metrics', 'system_disks')")
+      .get() as { n: number };
+    if (tables.n === 2) return db;
+  } catch (e) {
+    db.close();
+    throw e;
+  }
+  db.close();
+  return null;
+}
+
+/**
+ * Seconds-since-epoch of the newest sample, or null when there is none. `available` is
+ * false when there is no metrics database to read, `error` when it could not be read.
+ * Never throws: a broken metrics.db must not fail a caller about something else.
+ */
+export function latestMetricSample(): { available: boolean; ts: number | null; error?: string } {
+  let db: Database.Database | null = null;
+  try {
+    db = openMetricsDb();
+    if (!db) return { available: false, ts: null };
+    const row = db.prepare('SELECT MAX(ts) AS latest FROM system_metrics').get() as { latest: number | null };
+    return { available: true, ts: row.latest };
+  } catch (e) {
+    return { available: false, ts: null, error: (e as Error).message };
+  } finally {
+    db?.close();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flame0510/project-aether",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Rev4a — Revolution for Agents. OpenClaw agent fleet orchestrator.",
   "keywords": [
     "openclaw",

package/scripts/backup.sh

@@ -7,9 +7,9 @@
 #
 # What it archives: the whole Rev4a data directory — $REV4A_DATA_DIR when set,
 # otherwise ~/.config/rev4a (the same rule as lib/rev4a-paths.ts). That is `.env`
-# (secrets and configuration), everything under `data/` (events.db and credentials.db
-# with their -wal/-shm files, provider-keys.json, agents-token.json, model overrides,
-# the update log) and `shared/` (shared skills and rules). New files there are included
+# (secrets and configuration), everything under `data/` (events.db, metrics.db and
+# credentials.db with their -wal/-shm files, provider-keys.json, agents-token.json, model
+# overrides, the update log) and `shared/` (shared skills and rules). New files there are included
 # automatically.
 #
 # Not included: agent volumes (the cold backups in the dashboard cover those), the