@flame0510/project-aether 1.10.0 → 1.11.0

package/daemon.js

@@ -2,8 +2,9 @@
 /**
  * Rev4a Daemon — SQLite event logger
  * Polls OpenClaw sessions every 30s, writes events to SQLite, samples the host machine
- * (CPU, RAM, swap, storage) every 30s, and every 5 min reads what each running agent
- * spent, as its OpenClaw priced it, into costs.db — each on a timer of its own.
+ * (CPU, RAM, swap, storage) every 30s, samples what each container consumes every 60s
+ * (metrics.db), and every 5 min reads what each running agent spent, as its OpenClaw priced
+ * it, into costs.db — each on a timer of its own.
  */
 
 'use strict';
@@ -13,6 +14,9 @@ const fs = require('fs');
 const { spawnSync, execSync, execFile } = require('child_process');
 const Database = require('better-sqlite3');
 const path = require('path');
+// Shared with the dashboard (lib/docker-socket.ts): one copy of where the Docker socket is.
+const { dockerRequestJson } = require('./lib/docker-socket-path.js');
+const dockerStats = require('./lib/docker-stats.js');
 
 // Same rule as lib/rev4a-paths.ts: REV4A_DB, else <data dir>/data/events.db, where the data
 // dir is REV4A_DATA_DIR or ~/.config/rev4a — the API reads the files the daemon writes.
@@ -184,6 +188,57 @@ CREATE TABLE IF NOT EXISTS system_disks (
 );
 CREATE INDEX IF NOT EXISTS idx_disks_ts ON system_disks(ts);
 CREATE INDEX IF NOT EXISTS idx_disks_mount_ts ON system_disks(mount, ts);
+
+-- What each running container consumes, one row per container per sample (60 s). CPU is in
+-- cores (CPU-seconds per second) and every rate in bytes per second, both null for the first
+-- sample after a start and after a counter reset. Memory is the working set. A stopped
+-- container has no rows: a gap, not zeros.
+CREATE TABLE IF NOT EXISTS container_metrics (
+  ts INTEGER NOT NULL,
+  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 IF NOT EXISTS idx_container_metrics_ts ON container_metrics(ts);
+CREATE INDEX IF NOT EXISTS idx_container_metrics_c_ts ON container_metrics(container, ts);
+
+-- Who each container is: the agent's name (AGENT_NAME), whether it is an agent, and its named
+-- volumes (the link to docker_storage).
+CREATE TABLE IF NOT EXISTS container_sources (
+  container TEXT PRIMARY KEY,
+  agent_id TEXT,
+  name TEXT,
+  is_agent INTEGER NOT NULL DEFAULT 0,
+  volumes TEXT,
+  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, not the Mac).
+CREATE TABLE IF NOT EXISTS docker_host (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  ncpu INTEGER,
+  mem_total_mb INTEGER,
+  updated_at INTEGER
+);
+
+-- Disk Docker holds, read from /system/df every 10 min: kind 'volume' (name = the volume;
+-- reclaimable_mb = its size when no container uses it), 'layer' (a container's writable layer),
+-- 'images' and 'build_cache' (totals, with what could be freed).
+CREATE TABLE IF NOT EXISTS docker_storage (
+  ts INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  name TEXT NOT NULL DEFAULT '',
+  size_mb INTEGER,
+  reclaimable_mb INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_docker_storage_ts ON docker_storage(ts);
+CREATE INDEX IF NOT EXISTS idx_docker_storage_kind_ts ON docker_storage(kind, name, ts);
 `);
     return {
       db: mdb,
@@ -200,6 +255,26 @@ CREATE INDEX IF NOT EXISTS idx_disks_mount_ts ON system_disks(mount, ts);
       pruneMetrics: mdb.prepare('DELETE FROM system_metrics WHERE ts < ?'),
       pruneDisks: mdb.prepare('DELETE FROM system_disks WHERE ts < ?'),
       getLastTwoMetrics: mdb.prepare('SELECT cpu_percent, ram_used_mb, ram_total_mb FROM system_metrics ORDER BY ts DESC LIMIT 2'),
+      insertContainerMetric: mdb.prepare(`
+        INSERT INTO container_metrics (ts, container, cpu_cores, mem_mb, pids, net_rx_bps, net_tx_bps, blk_read_bps, blk_write_bps)
+        VALUES (@ts, @container, @cpu_cores, @mem_mb, @pids, @net_rx_bps, @net_tx_bps, @blk_read_bps, @blk_write_bps)
+      `),
+      upsertContainerSource: mdb.prepare(`
+        INSERT INTO container_sources (container, agent_id, name, is_agent, volumes, last_seen)
+        VALUES (@container, @agent_id, @name, @is_agent, @volumes, @last_seen)
+        ON CONFLICT(container) DO UPDATE SET agent_id = excluded.agent_id, name = excluded.name,
+          is_agent = excluded.is_agent, volumes = excluded.volumes, last_seen = excluded.last_seen
+      `),
+      upsertDockerHost: mdb.prepare(`
+        INSERT INTO docker_host (id, ncpu, mem_total_mb, updated_at) VALUES (1, @ncpu, @mem_total_mb, @updated_at)
+        ON CONFLICT(id) DO UPDATE SET ncpu = excluded.ncpu, mem_total_mb = excluded.mem_total_mb, updated_at = excluded.updated_at
+      `),
+      insertDockerStorage: mdb.prepare(`
+        INSERT INTO docker_storage (ts, kind, name, size_mb, reclaimable_mb) VALUES (@ts, @kind, @name, @size_mb, @reclaimable_mb)
+      `),
+      pruneContainerMetrics: mdb.prepare('DELETE FROM container_metrics WHERE ts < ?'),
+      pruneContainerSources: mdb.prepare('DELETE FROM container_sources WHERE last_seen < ?'),
+      pruneDockerStorage: mdb.prepare('DELETE FROM docker_storage WHERE ts < ?'),
     };
   } catch (err) {
     log(`[METRICS] disabled: cannot open ${METRICS_DB_PATH}: ${err.message}`);
@@ -416,6 +491,90 @@ function collectSystemMetrics() {
   }
 }
 
+// ── Container consumption ────────────────────────────────────────────────────
+//
+// What each running container uses — CPU, memory, processes, network, block I/O — and the
+// disk Docker holds for them, so the System page can say *who* is using the machine. Read from
+// the Docker Engine API (lib/docker-stats.js); written to metrics.db, next to the machine's
+// own numbers. Every running container, agents and the rest alike: the page tells them apart.
+
+const CONTAINERS_INTERVAL_MS = 60_000;
+/** The first pass only primes the CPU counters; the second, this long after, is the first with a CPU figure. */
+const CONTAINERS_FIRST_DELAY_MS = 6_000;
+const CONTAINERS_SECOND_DELAY_MS = 15_000;
+const STORAGE_INTERVAL_MS = 10 * 60_000;
+const STORAGE_FIRST_DELAY_MS = 25_000;
+
+// A rate over a gap longer than three intervals (a laptop that slept, skipped passes) is no rate.
+const containerSampler = dockerStats.createContainerSampler({
+  request: dockerRequestJson,
+  maxWindowS: (3 * CONTAINERS_INTERVAL_MS) / 1000,
+});
+let containersRunning = false;
+let dockerContainersDown = false;
+
+async function collectContainerMetrics() {
+  if (!metrics || containersRunning) return;
+  containersRunning = true;
+  try {
+    let sample;
+    try {
+      sample = await containerSampler.sample();
+      dockerContainersDown = false;
+    } catch (e) {
+      // Docker down or not yet up: said once, not every minute; it recovers by itself.
+      if (!dockerContainersDown) log(`[CONTAINERS] Docker unreachable: ${e.message}`);
+      dockerContainersDown = true;
+      return;
+    }
+    metrics.db.transaction(() => {
+      for (const row of sample.rows) metrics.insertContainerMetric.run({ ts: sample.ts, ...row });
+      for (const source of sample.sources) metrics.upsertContainerSource.run({ ...source, last_seen: sample.ts });
+      if (sample.host) metrics.upsertDockerHost.run({ ncpu: sample.host.ncpu, mem_total_mb: sample.host.memTotalMb, updated_at: sample.ts });
+      metrics.pruneContainerMetrics.run(sample.ts - METRICS_RETENTION_S);
+      metrics.pruneContainerSources.run(sample.ts - METRICS_RETENTION_S);
+    })();
+  } finally {
+    containersRunning = false;
+  }
+}
+
+let storageRunning = false;
+let dockerStorageFailing = false;
+
+async function collectDockerStorage() {
+  if (!metrics || storageRunning) return;
+  storageRunning = true;
+  try {
+    let df;
+    try {
+      df = dockerStats.parseStorage(await dockerRequestJson('GET', '/system/df', dockerStats.DF_TIMEOUT_MS));
+      if (!df) throw new Error('not a /system/df answer');
+      dockerStorageFailing = false;
+    } catch (e) {
+      // The last reading stays in the table: a failed one records nothing.
+      if (!dockerStorageFailing) log(`[CONTAINERS] Docker storage unreadable: ${e.message}`);
+      dockerStorageFailing = true;
+      return;
+    }
+    const ts = Math.floor(Date.now() / 1000);
+    const mb = (bytes) => (bytes === null ? null : Math.round(bytes / dockerStats.MB));
+    metrics.db.transaction(() => {
+      for (const v of df.volumes) {
+        metrics.insertDockerStorage.run({ ts, kind: 'volume', name: v.name, size_mb: mb(v.sizeBytes), reclaimable_mb: v.unused ? mb(v.sizeBytes) : 0 });
+      }
+      for (const l of df.layers) {
+        metrics.insertDockerStorage.run({ ts, kind: 'layer', name: l.container, size_mb: mb(l.sizeBytes), reclaimable_mb: null });
+      }
+      metrics.insertDockerStorage.run({ ts, kind: 'images', name: '', size_mb: mb(df.images.sizeBytes), reclaimable_mb: mb(df.images.reclaimableBytes) });
+      metrics.insertDockerStorage.run({ ts, kind: 'build_cache', name: '', size_mb: mb(df.buildCache.sizeBytes), reclaimable_mb: mb(df.buildCache.reclaimableBytes) });
+      metrics.pruneDockerStorage.run(ts - METRICS_RETENTION_S);
+    })();
+  } finally {
+    storageRunning = false;
+  }
+}
+
 // ── Agent Costs ──────────────────────────────────────────────────────────────
 //
 // What each agent spent, as its own OpenClaw computed it. Rev4a writes every model's
@@ -620,8 +779,8 @@ async function gatewayCall(container, method, params) {
   return JSON.parse(out.slice(start));
 }
 
-/** A Docker container name, as `docker ps` prints it; anything else is never exec'd. */
-const CONTAINER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+/** A Docker container name, as `docker ps` prints it; anything else is never exec'd (one rule: lib/docker-stats.js). */
+const CONTAINER_NAME_RE = dockerStats.CONTAINER_NAME_RE;
 /**
  * Each field quoted and escaped by Docker itself (`json`, `printf "%q"`), so a display
  * name holding a tab or a newline stays one field of one line. Only AGENT_NAME is read
@@ -1218,6 +1377,32 @@ const firstSample = metrics
   : null;
 if (metrics) log(`Machine metrics every ${METRICS_INTERVAL_MS / 1000}s into ${METRICS_DB_PATH}`);
 
+// Container consumption: a priming pass, a short wait for the first CPU figure, then every
+// interval; the disk Docker holds on a slower timer. Off when metrics.db failed.
+function sampleContainers() {
+  collectContainerMetrics().catch((e) => log(`[CONTAINERS ERROR] ${e.message}`));
+}
+function sampleStorage() {
+  collectDockerStorage().catch((e) => log(`[CONTAINERS ERROR] ${e.message}`));
+}
+let containersTimer = null;
+let containersPasses = 0;
+function scheduleContainers(delay) {
+  containersTimer = setTimeout(() => {
+    sampleContainers();
+    containersPasses++;
+    scheduleContainers(containersPasses === 1 ? CONTAINERS_SECOND_DELAY_MS : CONTAINERS_INTERVAL_MS);
+  }, delay);
+}
+let storageTimer = null;
+const firstStorage = metrics
+  ? setTimeout(() => { sampleStorage(); storageTimer = setInterval(sampleStorage, STORAGE_INTERVAL_MS); }, STORAGE_FIRST_DELAY_MS)
+  : null;
+if (metrics) {
+  scheduleContainers(CONTAINERS_FIRST_DELAY_MS);
+  log(`Container consumption every ${CONTAINERS_INTERVAL_MS / 1000}s, Docker storage every ${STORAGE_INTERVAL_MS / 60000} min, into ${METRICS_DB_PATH}`);
+}
+
 // Agent costs: first pass shortly after start (agents may still be booting), then every
 // interval. Off when costs.db failed.
 function sampleCosts() {
@@ -1235,6 +1420,9 @@ process.on('SIGTERM', () => {
   clearInterval(timer);
   clearTimeout(firstSample);
   clearInterval(metricsTimer);
+  clearTimeout(containersTimer);
+  clearTimeout(firstStorage);
+  clearInterval(storageTimer);
   clearTimeout(firstCosts);
   clearInterval(costsTimer);
   db.close();
@@ -1248,6 +1436,9 @@ process.on('SIGINT', () => {
   clearInterval(timer);
   clearTimeout(firstSample);
   clearInterval(metricsTimer);
+  clearTimeout(containersTimer);
+  clearTimeout(firstStorage);
+  clearInterval(storageTimer);
   clearTimeout(firstCosts);
   clearInterval(costsTimer);
   db.close();

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Rev4a Architecture — Design & Vision
 
 > **Status:** Active — `main` branch
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -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 Docker containers, running or stopped, with status, image, IP and ports, and opens a web terminal into any running one. Fully functional. (Machine CPU, RAM and disk are on `/system`.)
+**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 running one. Fully functional. Each running container's CPU, memory and processes are on its row, with a link to its charts on `/system`, which also shows the machine's CPU, RAM and disk.
 
 **Workspace API:** Lazy-loaded file tree explorer with real-time reads (no caching), supports both host and container workspaces via `docker exec`.
 
@@ -578,10 +578,12 @@ The Rev4a daemon (`daemon.js`) is a standalone Node.js process that bridges the
 3. Emit `spawn` / `complete` / `fail` / `spawn_timeout` events into the `events` table
 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. Read what each running agent spent, as its own OpenClaw priced it, every 5 min into
+5. Sample what each container consumes every 60 s, and the disk Docker holds every 10 min,
+   into `metrics.db` (see [Container Consumption](#container-consumption))
+6. Detect anomalies (CPU > 85%, RAM > 90%, a disk at 90%) and record them as events
+7. Read what each running agent spent, as its own OpenClaw priced it, every 5 min into
    `costs.db`, and each vendor's balance or usage every hour (see [Agent Costs](#agent-costs))
-7. Manage DB lifecycle (WAL mode; events.db checkpointed after each poll cycle)
+8. Manage DB lifecycle (WAL mode; events.db checkpointed after each poll cycle)
 
 ### Poll Interval
 
@@ -629,6 +631,35 @@ taken at load), then one every 30 s. Samples older than 30 days are pruned at ev
 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.
 
+### Container Consumption
+
+The System page says *that* the machine is busy; this says *who*. On a timer of its own the
+daemon reads every running container from the Docker Engine API — `GET /containers/{id}/stats?stream=false&one-shot=true`,
+10–20 ms a container, where `docker stats --no-stream` waits a second each and returns formatted
+strings — and writes `container_metrics` into `metrics.db` (schema in `docs/dev/DATABASE.md`):
+
+- **CPU** from the cumulative CPU time (ns): the difference between two samples over the
+  elapsed time, in cores; the first sample after a start only primes the counters. A counter
+  that goes backwards (the container restarted) gives no figure for that sample, never a spike.
+- **Memory** is the working set — usage minus the inactive page cache (`inactive_file` on
+  cgroup v2, `total_inactive_file` on v1), what `docker stats` shows.
+- **Processes, network and block I/O** as gauges and per-second rates. A container that stops
+  leaves a gap; one that is gone takes its counters with it.
+- **Names:** an agent's `AGENT_NAME` (read once per container id from its inspect), else the
+  container's name. Every running container is sampled — agents, and the rest as "container".
+- **Docker's disk** (`/system/df`, every 10 min): each named volume — which gives each agent's
+  storage, through the volume names its mounts list —, each writable layer, the images and the
+  build cache with what no container/build uses. Sizes and "unused" are readings, not advice.
+- The shares need Docker's own cores and memory (`/info`, re-read every 10 min): on Docker
+  Desktop those are its VM's (8 GB of a 16 GB Mac), on the VPS the machine's.
+
+The socket path rules (env, `/var/run`, Docker Desktop's `~/.docker/run`, `docker context`) live
+once, in `lib/docker-socket-path.js`, required by both the daemon and `lib/docker-socket.ts`. A
+Docker that is down is logged once and recovered from by itself; a failed disk reading leaves the
+previous one in place. `lib/container-metrics.ts` reads it all for `GET /api/metrics/containers`
+(the System page's *Agents and containers* section, the agent panel's RESOURCES, the Containers
+page). Anomalies per container (processes, sustained memory) are not raised yet.
+
 ### Agent Costs
 
 Rev4a computes no cost. Every model in the `rev4a` provider block synced into the agents

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 ## 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. `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. |
+| `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` (a number, or `'auto'`: a rounded ceiling just above the highest value or peak — for a series that is a small share of its natural scale, like one agent's CPU) / `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. |
@@ -47,9 +47,12 @@ 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. |
+| `Accordion` | `Accordion.tsx` | A row that opens: the header is a real `<button type="button">` (`aria-expanded`, `aria-controls` while open) carrying a `title`, `summary` figures and an optional muted `detail` line, so the answer to "what is this now" is on screen closed; the body holds what takes room and is **mounted only while open**, so a chart inside fetches nothing while closed. Controlled (`open` / `onToggle`: the parent can deep-link or fetch on it), optional `id` for a link to land on. Square, flat, tokens only. On mobile the summary wraps under the title. Used by the System page's agents. |
+| 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; an odd last chart spans both columns instead of leaving a hole. Under them, **Agents and containers** (`app/system/AgentsSection.tsx`, heading in the accent eyebrow with a rule above — `system-section-heading`): *Docker storage* (images, volumes, writable layers, build cache, each with what no container uses — wording neutral on purpose: an unused image may be a rollback target, an unused volume the cold backups), then **one `Accordion` per container**, sorted by CPU now (`GET /api/metrics/containers`, polled every 30 s with an `AbortController` ref). Closed: name, an *agent* / *container* pill, *stopped* when it is — or *no data* when Docker still lists it but its stats call fails — and CPU (share of Docker's cores), memory, storage, PIDs, with average · peak over the range tabs, cores, network and memory share on a muted line. Open (`AgentCharts.tsx`): the same three charts as the machine — CPU (share), Memory, Storage — for that container, fetched when it opens (`?container=`), polled every 30 s, aborted on close or range change; each with `yMax="auto"` (an agent is 0.01–2 % of Docker's cores) and sizes in MB/GB, on `subtle` surfaces inside the accordion. A last row, *Everything else*, is the machine minus the containers. `/system?agent=<container>` opens one and scrolls to it. Then **Recent alerts** (`RecentAlerts.tsx`, `GET /api/metrics/alerts`): the machine's latest 10 anomalies with time (configured timezone), metric pill and message. The section has its own skeleton (`SystemAgentsSkeleton`, also in the route's `loading.tsx`). |
 | 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. |
+| Agent resources | `app/agents/ResourceSection.tsx` | The RESOURCES section of the agent panel, after COSTS: CPU and memory now and over the last 24 h, processes, network, storage (volume and layer), from `GET /api/metrics/containers`, every 60 s with an `AbortController` ref, reset on agent switch; *Stopped* when the agent is not running, *Not collecting* when the newest sample is older than three intervals (the "now" figures then stand down), a refresh-failure line while the last answer stays, and a link to its charts on `/system?agent=<container>` — the history lives in one place. Rows are the shared `PanelRow` (`app/agents/PanelRow.tsx`, also used by COSTS). |
+| Containers page | `app/containers/ContainersClient.tsx` | `/containers`: one card per Docker container; a running one the daemon has sampled adds a line — CPU share, memory, PIDs — and *Charts →* to its accordion on `/system`. The figures are a bonus: a daemon that has not sampled yet, or a failed request, leaves the list as it was. |
 | 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. |
@@ -67,6 +70,12 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `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 route's `loading.tsx` sits in `RouteLoadingShell` (full width up to `maxWidth`, centred): the app shell's content area is a column flexbox, and a `margin: 0 auto` child without `width: 100%` shrinks to its content — every loader did, and its rows came out as wide as its 120 px title (measured: 120 px instead of 1040). `ListPageSkeleton` (a title over rows) is the list pages' loader. Create Agent (`app/agents/create/loading.tsx`) and the container terminal (`app/containers/terminal/[id]/loading.tsx`) have their own, shaped like the page, instead of inheriting the Agents / Containers rows; the Agents page prefetches `/agents/create` (its **+ New** uses `router.push`, which prefetches nothing) and the Containers **Terminal** is a `Link`, so both open without a full reload. 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. |
 
+The System page's container rows distinguish a recent Docker listing from fresh resource
+statistics. A row seen in Docker without figures says *no data*. When the newest statistics
+sample ages past three intervals, current CPU, memory and processes disappear; an older row
+says *not current*. The page advances its clock at each poll and recomputes age from
+`sampled_at`, so repeated failed refreshes cannot leave a previous answer labelled as current.
+
 ### Rules
 
 1. **Prefer existing primitives over new ad-hoc markup.** Every new component starts from the shared catalog.

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -101,9 +101,9 @@ When environment variables are saved via the Config page (Save & Restart):
 |---|---|
 | `/` | 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 |
+| `/containers` | All Docker containers on the host, each running one with its CPU, memory and processes now (from the daemon's container samples) and a link to its charts |
 | `/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) |
+| `/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); **Agents and containers**: what Docker holds on disk, and one row per container — CPU, memory, storage, processes — that opens to its own CPU / Memory / Storage charts (sampled every 60 s; a recently seen row without current statistics says "no data", and stale current figures are hidden; each agent's numbers are also in its panel, RESOURCES); and the machine's recent alerts |
 | `/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 |
@@ -308,7 +308,7 @@ Store third-party service credentials and install them into agent containers.
 ### Container management (`/containers`)
 View all running Docker containers with:
 - Name, image, status, ports, uptime
-- Resource usage (CPU, memory)
+- Resource usage now (CPU share, memory, processes) for each running container, with *Charts →* to its history on `/system`
 - Quick links to agent control UIs
 
 ### Agent management (`/agents`)

package/docs/dev/API-REFERENCE.md

@@ -1,6 +1,6 @@
 # Rev4a API Reference
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 All routes are under `/api/`. Authentication is required on every endpoint
 unless otherwise noted.
@@ -2045,6 +2045,81 @@ average and peak: 60 s for `1h`, 720 s for `24h`, 5040 s for `7d`, 21 600 s for
   means the daemon is not sampling; the page says so.
 - `host` is read live by the API process, which runs on the same host.
 
+### `GET /api/metrics/containers?range=1h|24h|7d|30d`
+What every container consumes — now, and as an average and peak over the range — plus what is
+not a container and the disk Docker holds. From `metrics.db` (the daemon samples every 60 s,
+see `docs/dev/DATABASE.md`). Default range `1h`.
+
+**Auth:** browser cookie or Bearer
+
+**Response:**
+```json
+{
+  "available": true, "range": "1h", "interval_s": 60,
+  "host": { "ncpu": 10, "mem_total_mb": 7837 },
+  "sampled_at": 1790789760, "age_s": 10,
+  "containers": [
+    { "container": "agent_9253eee3", "name": "test", "agent_id": "agent_9253eee3", "is_agent": true,
+      "running": true, "last_seen": 1790789760,
+      "now": { "cpu_cores": 0.022, "cpu_percent": 0.22, "mem_mb": 668, "mem_percent": 8.5, "pids": 12,
+               "net_rx_bps": 0, "net_tx_bps": 0, "blk_read_bps": 0, "blk_write_bps": 0 },
+      "range": { "cpu_avg_percent": 1.02, "cpu_max_percent": 2.17, "mem_avg_mb": 679, "mem_max_mb": 701 },
+      "storage": { "volume_mb": 1544, "layer_mb": 10, "total_mb": 1554, "ts": 1790789645 } }
+  ],
+  "rest": { "cpu_percent": 42.26, "mem_mb": 11864 },
+  "docker_storage": { "ts": 1790789645, "images_mb": 4734, "images_reclaimable_mb": 3518,
+                      "build_cache_mb": 1597, "build_cache_reclaimable_mb": 1597,
+                      "volumes_mb": 10120, "unused_volumes_mb": 7337, "layers_mb": 30,
+                      "unused_volumes": [ { "name": "rev4a-backups", "size_mb": 7337 } ] }
+}
+```
+
+- `cpu_percent` is a share of Docker's cores (`host.ncpu`), `mem_percent` of Docker's memory —
+  on Docker Desktop that is its VM, on the VPS the machine. `cpu_cores` is the raw figure.
+- `now` is `null` for a container that is not running (no sample within 3 intervals of the
+  newest sample — running is judged against the newest sample, not the wall clock, so a
+  stopped daemon does not make every container look stopped);
+  `running: false` ones stay listed while they were seen in the range. A rate that is null in
+  the newest sample (the first after a start) is replaced by the previous reading.
+- The list is sorted running first, then by CPU now. `storage` is the named volumes plus the
+  writable layer, from the last Docker disk reading (every 10 min).
+- `rest` is the machine's newest sample minus the running containers (the containers' CPU
+  re-scaled to the machine's cores first, so on Docker Desktop the two shares still compare):
+  the host, Rev4a and other software (`null` without a machine sample or Docker's figures).
+- `docker_storage.*_reclaimable_mb` and `unused_volumes` (the 5 largest): what **no container
+  uses** — images of older agent versions you may still roll back to count as such; a volume
+  like the cold backups' is listed, not advised for removal. `volumes_mb` sums all volumes;
+  `unused_volumes_mb` is the total of what no container uses, `unused_volumes` only names the
+  five largest.
+- `available: false` until the daemon has created the tables; with the tables present and no
+  rows yet it answers `available: true` with an empty list.
+
+**With `&container=<name>`** — that container's history, bucketed like `GET /api/metrics`:
+```json
+{ "available": true, "range": "1h", "interval_s": 60, "host": { "ncpu": 10, "mem_total_mb": 7837 },
+  "container": "agent_9253eee3", "name": "test", "bucket_s": 120,
+  "history": [ { "ts": 1790789640, "cpu_avg": 1.41, "cpu_max": 2.17, "mem_avg": 685, "mem_max": 701 } ],
+  "storage_bucket_s": 1200, "storage_history": [ { "ts": 1790788800, "total_mb": 1554 } ] }
+```
+`cpu_*` are shares of Docker's cores, `mem_*` MB. A container that was not running has no
+points for that stretch (a gap). A name that matches the rules but was never sampled answers
+`available: true` with an empty history.
+
+**Errors:** `400` for another `range` or an invalid container name. A `metrics.db` that
+cannot be opened (missing, corrupt) answers `available: false`, not an error.
+
+### `GET /api/metrics/alerts?limit=10`
+The machine's latest `system_anomaly` events (CPU above 85 % or memory above 90 % on two
+samples in a row, a disk at 90 %), newest first, from `events.db`. `limit` 1–50, default 10.
+
+**Auth:** browser cookie or Bearer
+
+**Response:**
+```json
+{ "alerts": [ { "ts": 1790789625355, "metric": "disk", "message": "Disk high: / 94% used", "threshold": 90, "values": [94] } ] }
+```
+`ts` is in **milliseconds** (the `events` table's unit); `metric` is `cpu`, `ram`, `disk` or `null`.
+
 ---
 
 ## System Health
@@ -2302,27 +2377,26 @@ Full key management documentation at [PROVIDERS.md](PROVIDERS.md).
 ## Containers
 
 ### `GET /api/containers`
-List all running Docker containers with resource usage.
+Every Docker container, running or stopped, with its identity and network details. What a
+running container consumes lives in `GET /api/metrics/containers`.
 
-**Auth:** browser cookie
+**Auth:** browser cookie or Bearer
 
-**Response:**
+**Response:** a bare array —
 ```json
-{
-  "containers": [
-    {
-      "name": "openclaw-atlas",
-      "image": "openclaw-agent-base:2026.9.3",
-      "status": "running",
-      "ports": ["0.0.0.0:3731->3000/tcp"],
-      "created": "2026-06-20T10:00:00Z",
-      "cpu_percent": 2.1,
-      "mem_usage_mb": 340
-    }
-  ]
-}
+[
+  { "id": "a1b2c3d4e5f6", "name": "openclaw-atlas", "image": "openclaw-agent-base:2026.9.3",
+    "status": "Up 3 hours", "state": "running", "ports": "0.0.0.0:3731->3000/tcp",
+    "ip": "172.18.0.2", "agentId": "agent_atlas", "displayName": "Atlas", "created": null }
+]
 ```
 
+- `name` is the daemon's `primaryName` (the name with one leading slash) — the same key the
+  metrics store and the `/system?agent=` link use.
+- `displayName` is the agent's `AGENT_NAME`, read from the inspect. If an inspect fails, the
+  row still comes from Docker's list (`ip` and `displayName` then `null`): a container is
+  never dropped, and never renamed, because one call failed.
+
 The container list is the only container route. There is no logs endpoint and no
 action endpoint: logs are read through the terminal WebSocket, and lifecycle
 operations on agent containers go through `/api/agents/[id]/lifecycle`.

package/docs/dev/DATABASE.md

@@ -1,9 +1,9 @@
 # Rev4a — Database Reference
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 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
+`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)).
@@ -318,6 +318,62 @@ 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.