@flame0510/project-aether 1.10.0 → 1.11.0

package/docs/rag/DATA-FRESHNESS.md

@@ -1,6 +1,6 @@
 # Data Freshness in Rev4a
 
-> **Last updated:** 2026-09-27
+> **Last updated:** 2026-10-01
 
 Understanding how current the data in Rev4a is — and what is truly real-time vs. periodically updated.
 
@@ -56,6 +56,21 @@ the collector is not running instead of showing stale numbers as current.
 
 ---
 
+## Container consumption (System page, Containers page, agent panel)
+
+**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.
+
+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

package/docs/rag/GLOSSARY.md

@@ -1,6 +1,6 @@
 # Rev4a Glossary
 
-> **Last updated:** 2026-09-27
+> **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).

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,6 +1,6 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-27
+> **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,9 +77,9 @@ 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).
@@ -87,6 +87,10 @@ What each agent spent, as its own OpenClaw priced it with the prices Rev4a syncs
 ### 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-27
+> **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.

package/lib/container-metrics.ts

@@ -0,0 +1,340 @@
+/**
+ * What each container consumes, read from metrics.db (daemon.js writes it — see
+ * docs/dev/DATABASE.md, Container consumption). The queries behind the System page's
+ * *Agents* section, the agent panel and the Containers page; the routes stay thin.
+ *
+ * CPU is stored in cores and shown as a share of Docker's cores (`docker_host.ncpu`): on the
+ * VPS that is the machine, on Docker Desktop its VM. Memory is the working set in MB,
+ * with its share of Docker's memory next to it.
+ */
+import type Database from 'better-sqlite3';
+
+/** How often daemon.js samples containers, and reads Docker's disk (seconds). */
+export const CONTAINER_INTERVAL_S = 60;
+export const STORAGE_INTERVAL_S = 600;
+/** History points per chart. */
+const POINTS = 120;
+/** A container whose newest sample is older than this many intervals is not running. */
+const RUNNING_WITHIN_INTERVALS = 3;
+
+const TABLES = ['container_metrics', 'container_sources', 'docker_host', 'docker_storage'];
+
+/** False until the daemon has created the tables (first start after an update). */
+export function containerTablesReady(db: Database.Database): boolean {
+  const row = db
+    .prepare(`SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name IN (${TABLES.map(() => '?').join(', ')})`)
+    .get(...TABLES) as { n: number };
+  return row.n === TABLES.length;
+}
+
+/** Seconds per chart point: at least two samples, so a drifting timer leaves no empty bucket. */
+export function bucketSeconds(spanS: number, intervalS: number): number {
+  return Math.max(2 * intervalS, Math.round(spanS / POINTS));
+}
+
+export interface DockerHost { ncpu: number; mem_total_mb: number }
+
+export function readDockerHost(db: Database.Database): DockerHost | null {
+  const row = db.prepare('SELECT ncpu, mem_total_mb FROM docker_host WHERE id = 1').get() as
+    { ncpu: number | null; mem_total_mb: number | null } | undefined;
+  return row && row.ncpu && row.mem_total_mb ? { ncpu: row.ncpu, mem_total_mb: row.mem_total_mb } : null;
+}
+
+/** `value` as a percent of `whole`, to `digits` decimals — CPU needs two: an idle agent is a few hundredths of a percent of the machine. */
+const pct = (value: number | null, whole: number | null | undefined, digits = 1): number | null =>
+  value === null || !whole ? null : Math.round((value / whole) * 100 * 10 ** digits) / 10 ** digits;
+const round2 = (n: number | null): number | null => (n === null ? null : Math.round(n * 100) / 100);
+
+/** The named volumes a container uses, as daemon.js recorded them. */
+function volumesOf(list: string | null): string[] {
+  return list ? list.split(',').filter(Boolean) : [];
+}
+
+export interface ContainerNow {
+  cpu_cores: number | null;
+  cpu_percent: number | null;
+  mem_mb: number | null;
+  mem_percent: number | null;
+  pids: number | null;
+  net_rx_bps: number | null;
+  net_tx_bps: number | null;
+  blk_read_bps: number | null;
+  blk_write_bps: number | null;
+}
+
+export interface ContainerRow {
+  container: string;
+  name: string;
+  agent_id: string | null;
+  is_agent: boolean;
+  running: boolean;
+  last_seen: number;
+  now: ContainerNow | null;
+  /** Average and peak over the range, CPU as a share of Docker's cores. */
+  range: { cpu_avg_percent: number | null; cpu_max_percent: number | null; mem_avg_mb: number | null; mem_max_mb: number | null };
+  /** Named volumes plus the writable layer, from the last reading of Docker's disk. */
+  storage: { volume_mb: number | null; layer_mb: number | null; total_mb: number | null; ts: number | null };
+}
+
+export interface DockerStorage {
+  ts: number;
+  images_mb: number | null;
+  images_reclaimable_mb: number | null;
+  build_cache_mb: number | null;
+  build_cache_reclaimable_mb: number | null;
+  volumes_mb: number;
+  /** What no container uses, all of it — `unused_volumes` lists only the largest five. */
+  unused_volumes_mb: number;
+  layers_mb: number;
+  /** Volumes no container uses (cold backups, leftovers), largest first. */
+  unused_volumes: { name: string; size_mb: number }[];
+}
+
+export interface ContainerOverview {
+  host: DockerHost | null;
+  /** Unix seconds of the newest sample, and how old it is. */
+  sampled_at: number | null;
+  age_s: number | null;
+  containers: ContainerRow[];
+  /** The machine minus the containers: what is not one of them (the host, Rev4a, other software). */
+  rest: { cpu_percent: number | null; mem_mb: number | null } | null;
+  docker_storage: DockerStorage | null;
+}
+
+interface NowRow {
+  ts: number; cpu_cores: number | null; mem_mb: number | null; pids: number | null;
+  net_rx_bps: number | null; net_tx_bps: number | null; blk_read_bps: number | null; blk_write_bps: number | null;
+}
+
+/** The newest reading of each volume, layer and total, or null before the first. */
+export function readDockerStorage(db: Database.Database): DockerStorage | null {
+  const ts = (db.prepare('SELECT MAX(ts) AS ts FROM docker_storage').get() as { ts: number | null }).ts;
+  if (ts === null) return null;
+  const rows = db.prepare('SELECT kind, name, size_mb, reclaimable_mb FROM docker_storage WHERE ts = ?').all(ts) as
+    { kind: string; name: string; size_mb: number | null; reclaimable_mb: number | null }[];
+  const one = (kind: string) => rows.find((r) => r.kind === kind);
+  const sum = (kind: string) => rows.filter((r) => r.kind === kind).reduce((acc, r) => acc + (r.size_mb ?? 0), 0);
+  const unused = rows
+    .filter((r) => r.kind === 'volume' && (r.reclaimable_mb ?? 0) > 0)
+    .map((r) => ({ name: r.name, size_mb: r.reclaimable_mb as number }))
+    .sort((a, b) => b.size_mb - a.size_mb);
+  return {
+    ts,
+    images_mb: one('images')?.size_mb ?? null,
+    images_reclaimable_mb: one('images')?.reclaimable_mb ?? null,
+    build_cache_mb: one('build_cache')?.size_mb ?? null,
+    build_cache_reclaimable_mb: one('build_cache')?.reclaimable_mb ?? null,
+    volumes_mb: sum('volume'),
+    unused_volumes_mb: unused.reduce((a, v) => a + v.size_mb, 0),
+    layers_mb: sum('layer'),
+    unused_volumes: unused.slice(0, 5),
+  };
+}
+
+interface AggregateRow { container: string; cpu_avg: number | null; cpu_max: number | null; mem_avg: number | null; mem_max: number | null }
+
+/**
+ * From 24 hours up, the average and peak scan every sample of the range: the page's heaviest
+ * query — synchronous, so it holds the server's event loop (about 100 ms for ten containers
+ * over 24 h, measured) on every 30 s poll — and its answer hardly moves in two minutes. So
+ * those ranges are kept that long; shorter ones are cheap and read fresh.
+ */
+const LONG_RANGE_S = 24 * 3_600;
+const AGGREGATE_TTL_MS = 120_000;
+const aggregateCache = new Map<string, { at: number; rows: Map<string, AggregateRow> }>();
+
+function rangeAggregates(db: Database.Database, spanS: number, since: number): Map<string, AggregateRow> {
+  const cacheable = spanS >= LONG_RANGE_S;
+  const key = `${db.name}:${spanS}`;
+  if (cacheable) {
+    const hit = aggregateCache.get(key);
+    if (hit && Date.now() - hit.at < AGGREGATE_TTL_MS) return hit.rows;
+  }
+  const rows = new Map(
+    (db
+      .prepare(
+        `SELECT container, AVG(cpu_cores) AS cpu_avg, MAX(cpu_cores) AS cpu_max, AVG(mem_mb) AS mem_avg, MAX(mem_mb) AS mem_max
+         FROM container_metrics WHERE ts > ? GROUP BY container`,
+      )
+      .all(since) as AggregateRow[])
+      .map((r) => [r.container, r]),
+  );
+  if (cacheable) aggregateCache.set(key, { at: Date.now(), rows });
+  return rows;
+}
+
+/**
+ * Every container seen in the range: who it is, what it uses now, its average and peak over
+ * the range, and its disk — running ones first, by CPU.
+ */
+export function readContainerOverview(
+  db: Database.Database,
+  spanS: number,
+  nowS = Math.floor(Date.now() / 1000),
+  /** Cores of the machine the API runs on, to put the containers' CPU on the machine's scale in `rest`. */
+  hostCores?: number,
+): ContainerOverview {
+  const host = readDockerHost(db);
+  const sampledAt = (db.prepare('SELECT MAX(ts) AS ts FROM container_metrics').get() as { ts: number | null }).ts;
+  const since = nowS - spanS;
+
+  const sources = db
+    .prepare('SELECT container, agent_id, name, is_agent, volumes, last_seen FROM container_sources WHERE last_seen > ?')
+    .all(since) as { container: string; agent_id: string | null; name: string | null; is_agent: number; volumes: string | null; last_seen: number }[];
+
+  const aggregates = rangeAggregates(db, spanS, since);
+  // Running is judged against the newest sample, not the wall clock: a daemon that stopped must
+  // not make every container look stopped (the page says "Not collecting" instead) — but never
+  // against a sample from the future, which a clock set back would leave behind.
+  const reference = sampledAt === null ? null : Math.min(sampledAt, nowS);
+
+  const storage = readDockerStorage(db);
+  const storageRows = storage
+    ? (db.prepare('SELECT kind, name, size_mb FROM docker_storage WHERE ts = ?').all(storage.ts) as { kind: string; name: string; size_mb: number | null }[])
+    : [];
+  const sizeOf = (kind: string, name: string) => storageRows.find((r) => r.kind === kind && r.name === name)?.size_mb ?? null;
+
+  const newest = db.prepare(
+    `SELECT ts, cpu_cores, mem_mb, pids, net_rx_bps, net_tx_bps, blk_read_bps, blk_write_bps
+     FROM container_metrics WHERE container = ? ORDER BY ts DESC LIMIT 3`,
+  );
+
+  const containers: ContainerRow[] = sources.map((s) => {
+    const recent = newest.all(s.container) as NowRow[];
+    const latest = recent[0];
+    const running = Boolean(latest && reference !== null && latest.ts >= reference - RUNNING_WITHIN_INTERVALS * CONTAINER_INTERVAL_S);
+    // A rate is null on the first sample after a start; the previous reading stands in for it.
+    const rate = (key: keyof NowRow) => recent.find((r) => r[key] !== null)?.[key] ?? null;
+    const cores = running ? (rate('cpu_cores') as number | null) : null;
+    const now: ContainerNow | null = running
+      ? {
+          cpu_cores: cores,
+          cpu_percent: pct(cores, host?.ncpu, 2),
+          mem_mb: latest.mem_mb,
+          mem_percent: pct(latest.mem_mb, host?.mem_total_mb),
+          pids: latest.pids,
+          net_rx_bps: rate('net_rx_bps') as number | null,
+          net_tx_bps: rate('net_tx_bps') as number | null,
+          blk_read_bps: rate('blk_read_bps') as number | null,
+          blk_write_bps: rate('blk_write_bps') as number | null,
+        }
+      : null;
+    const agg = aggregates.get(s.container);
+    const volumeSizes = volumesOf(s.volumes).map((v) => sizeOf('volume', v));
+    const volume = volumeSizes.length && volumeSizes.some((v) => v !== null) ? volumeSizes.reduce<number>((a, v) => a + (v ?? 0), 0) : null;
+    const layer = sizeOf('layer', s.container);
+    return {
+      container: s.container,
+      name: s.name || s.container,
+      agent_id: s.agent_id,
+      is_agent: s.is_agent === 1,
+      running,
+      last_seen: s.last_seen,
+      now,
+      range: {
+        cpu_avg_percent: pct(agg?.cpu_avg ?? null, host?.ncpu, 2),
+        cpu_max_percent: pct(agg?.cpu_max ?? null, host?.ncpu, 2),
+        mem_avg_mb: agg?.mem_avg == null ? null : Math.round(agg.mem_avg),
+        mem_max_mb: agg?.mem_max ?? null,
+      },
+      storage: {
+        volume_mb: volume,
+        layer_mb: layer,
+        total_mb: volume === null && layer === null ? null : (volume ?? 0) + (layer ?? 0),
+        ts: storage?.ts ?? null,
+      },
+    };
+  });
+
+  containers.sort((a, b) =>
+    Number(b.running) - Number(a.running)
+    || (b.now?.cpu_percent ?? -1) - (a.now?.cpu_percent ?? -1)
+    || a.name.localeCompare(b.name));
+
+  // Machine minus the containers, from the machine's newest sample.
+  const machine = db
+    .prepare('SELECT cpu_percent, ram_used_mb FROM system_metrics ORDER BY ts DESC LIMIT 1')
+    .get() as { cpu_percent: number | null; ram_used_mb: number | null } | undefined;
+  const running = containers.filter((c) => c.running && c.now);
+  // The machine's CPU is a share of the host's cores; a container's is of Docker's — the same on a
+  // server, not on Docker Desktop, whose VM may have fewer. Compare in cores over the host's.
+  const containersShare = hostCores && hostCores > 0
+    ? (running.reduce((a, c) => a + (c.now?.cpu_cores ?? 0), 0) / hostCores) * 100
+    : running.reduce((a, c) => a + (c.now?.cpu_percent ?? 0), 0);
+  const rest = machine && host
+    ? {
+        cpu_percent: machine.cpu_percent === null ? null : round2(Math.max(0, machine.cpu_percent - containersShare)),
+        mem_mb: machine.ram_used_mb === null ? null : Math.max(0, machine.ram_used_mb - running.reduce((a, c) => a + (c.now?.mem_mb ?? 0), 0)),
+      }
+    : null;
+
+  return {
+    host,
+    sampled_at: sampledAt,
+    age_s: sampledAt === null ? null : Math.max(0, nowS - sampledAt),
+    containers,
+    rest,
+    docker_storage: storage,
+  };
+}
+
+export interface ContainerHistory {
+  host: DockerHost | null;
+  container: string;
+  name: string | null;
+  bucket_s: number;
+  /** CPU as a share of Docker's cores (average and peak), memory in MB (average and peak). */
+  history: { ts: number; cpu_avg: number | null; cpu_max: number | null; mem_avg: number | null; mem_max: number | null }[];
+  storage_bucket_s: number;
+  /** Named volumes plus the writable layer, MB. */
+  storage_history: { ts: number; total_mb: number | null }[];
+}
+
+/** One container's history, bucketed like the machine's (`GET /api/metrics`). */
+export function readContainerHistory(db: Database.Database, container: string, spanS: number, nowS = Math.floor(Date.now() / 1000)): ContainerHistory {
+  const host = readDockerHost(db);
+  const since = nowS - spanS;
+  const bucket = bucketSeconds(spanS, CONTAINER_INTERVAL_S);
+  const storageBucket = bucketSeconds(spanS, STORAGE_INTERVAL_S);
+
+  const source = db.prepare('SELECT name, volumes FROM container_sources WHERE container = ?').get(container) as
+    { name: string | null; volumes: string | null } | undefined;
+
+  const rows = db
+    .prepare(
+      `SELECT (ts / CAST(@bucket AS INTEGER)) * CAST(@bucket AS INTEGER) AS ts,
+         AVG(cpu_cores) AS cpu_avg, MAX(cpu_cores) AS cpu_max, AVG(mem_mb) AS mem_avg, MAX(mem_mb) AS mem_max
+       FROM container_metrics WHERE container = @container AND ts > @since
+       GROUP BY ts / CAST(@bucket AS INTEGER) ORDER BY ts`,
+    )
+    .all({ bucket, container, since }) as { ts: number; cpu_avg: number | null; cpu_max: number | null; mem_avg: number | null; mem_max: number | null }[];
+
+  const volumes = volumesOf(source?.volumes ?? null);
+  const placeholders = volumes.map(() => '?').join(', ');
+  // Volumes and the writable layer, summed per reading, then averaged per bucket.
+  const storageRows = db
+    .prepare(
+      `SELECT (ts / CAST(? AS INTEGER)) * CAST(? AS INTEGER) AS ts, AVG(total) AS total_mb FROM (
+         SELECT ts, SUM(size_mb) AS total FROM docker_storage
+         WHERE ts > ? AND ((kind = 'layer' AND name = ?)${volumes.length ? ` OR (kind = 'volume' AND name IN (${placeholders}))` : ''})
+         GROUP BY ts
+       ) GROUP BY ts / CAST(? AS INTEGER) ORDER BY ts`,
+    )
+    .all(storageBucket, storageBucket, since, container, ...volumes, storageBucket) as { ts: number; total_mb: number | null }[];
+
+  return {
+    host,
+    container,
+    name: source?.name ?? null,
+    bucket_s: bucket,
+    history: rows.map((r) => ({
+      ts: r.ts,
+      cpu_avg: pct(r.cpu_avg, host?.ncpu, 2),
+      cpu_max: pct(r.cpu_max, host?.ncpu, 2),
+      mem_avg: r.mem_avg === null ? null : Math.round(r.mem_avg),
+      mem_max: r.mem_max,
+    })),
+    storage_bucket_s: storageBucket,
+    storage_history: storageRows.map((r) => ({ ts: r.ts, total_mb: r.total_mb === null ? null : Math.round(r.total_mb) })),
+  };
+}

package/lib/docker-socket-path.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * Where the Docker Engine API socket is, and a JSON request against it.
+ *
+ * Plain CommonJS on purpose: the routes reach it through lib/docker-socket.ts, and
+ * daemon.js — run by node directly, with no bundler — requires it. One copy of the rules
+ * below, so the daemon cannot drift from the dashboard on where Docker lives.
+ *
+ * The socket path is NOT the same everywhere. `/var/run/docker.sock` is the Linux default
+ * (and what the VPS uses), but Docker Desktop on macOS puts it at `~/.docker/run/docker.sock`
+ * and does not create the /var/run symlink unless the user opts in. Hardcoding the Linux
+ * path made every read-only Docker route return an empty list on macOS — agents existed
+ * and ran, but the dashboard showed nothing, because creation shells out to the `docker`
+ * CLI (which reads the context) while listing went through this socket.
+ */
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+let cached = null;
+let lastMissAt = 0;
+
+/**
+ * How long a failed resolution is remembered. Long enough that a Docker outage doesn't
+ * spawn a `docker context inspect` per request, short enough that a server which started
+ * before the Docker daemon picks it up on its own.
+ */
+const MISS_TTL_MS = 5000;
+
+function fromDockerHostEnv() {
+  const raw = process.env.DOCKER_HOST;
+  if (!raw) return null;
+  // Only unix sockets are usable here; tcp:// would need a different client.
+  if (!raw.startsWith('unix://')) return null;
+  return raw.slice('unix://'.length);
+}
+
+function fromDockerContext() {
+  try {
+    const out = execFileSync(
+      'docker',
+      ['context', 'inspect', '--format', '{{.Endpoints.docker.Host}}'],
+      { encoding: 'utf-8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    return out.startsWith('unix://') ? out.slice('unix://'.length) : null;
+  } catch {
+    return null;
+  }
+}
+
+function usable(candidate) {
+  if (!candidate) return null;
+  try {
+    fs.accessSync(candidate, fs.constants.R_OK | fs.constants.W_OK);
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the Docker socket, most authoritative source first. Returns null when Docker
+ * isn't reachable at all.
+ *
+ * A success is cached for the life of the process — the path doesn't move. A failure is
+ * only cached for MISS_TTL_MS: Rev4a can legitimately start before the Docker daemon is up
+ * (systemd ordering, Docker Desktop still booting), and caching that failure permanently
+ * would leave every Docker route returning an empty list until someone restarted the server.
+ *
+ * @returns {string | null}
+ */
+function resolveDockerSocket() {
+  if (cached) return cached;
+  if (Date.now() - lastMissAt < MISS_TTL_MS) return null;
+
+  const found =
+    usable(fromDockerHostEnv()) ??
+    usable(fromDockerContext()) ??
+    // Docker Desktop (macOS, and Windows with WSL integration)
+    usable(path.join(os.homedir(), '.docker', 'run', 'docker.sock')) ??
+    // Linux default — the VPS lands here
+    usable('/var/run/docker.sock');
+
+  if (found) cached = found;
+  else lastMissAt = Date.now();
+
+  return found;
+}
+
+/**
+ * A request against the Docker Engine API, resolved as JSON. Rejects when Docker is
+ * unreachable, the answer is an HTTP error (Docker's error bodies are JSON too — a status
+ * is never resolved as data), the payload isn't JSON, or `timeoutMs` (when given) passes.
+ *
+ * @template [T=any]
+ * @param {string} method
+ * @param {string} apiPath
+ * @param {number} [timeoutMs] 0 or omitted: no timeout
+ * @returns {Promise<T>}
+ */
+function dockerRequestJson(method, apiPath, timeoutMs = 0) {
+  return new Promise((resolve, reject) => {
+    const socketPath = resolveDockerSocket();
+    if (!socketPath) {
+      reject(new Error('Docker socket not found'));
+      return;
+    }
+
+    const req = http.request(
+      { socketPath, path: apiPath, method, headers: { Host: 'localhost' } },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          if ((res.statusCode ?? 500) >= 400) {
+            reject(new Error(`Docker error ${res.statusCode}: ${data.slice(0, 200) || '(no body)'}`));
+            return;
+          }
+          try { resolve(JSON.parse(data)); }
+          catch { reject(new Error('Invalid JSON from Docker')); }
+        });
+      },
+    );
+    if (timeoutMs > 0) req.setTimeout(timeoutMs, () => req.destroy(new Error('Docker request timed out')));
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+module.exports = { resolveDockerSocket, dockerRequestJson };