@amd-gaia/agent-ui 0.22.0 → 0.24.0

package/services/auto-updater.cjs

@@ -4,9 +4,19 @@
 /**
  * auto-updater.cjs — GAIA Agent UI auto-update service.
  *
- * Wraps `electron-updater` for the GitHub Releases auto-update flow.
+ * Wraps `electron-updater` against a CONFIGURABLE generic feed (R2-primary —
+ * issue #1724). The forward-update channel URL is resolved at runtime from
+ * `GAIA_UPDATE_FEED_URL` or `feedUrl` in ~/.gaia/update-config.json, and the
+ * app fetches the mutable `latest*.yml` channel pointer from it. When no feed
+ * is configured the updater enters a loud `no-channel` state (no silent
+ * no-op). The actual R2 publish feed + mutable channel pointer is milestone-52
+ * work (#1719); until it lands, point the env var at any generic feed (a local
+ * mock works) to exercise the path.
+ *
  * Implements §4 Layer 3 + §7 Phase F of docs/plans/desktop-installer.mdx.
- * Issue #1336: adds in-app rollback to a specific previous release.
+ * Issue #1336: in-app rollback to a specific previous release still lists and
+ * installs from GitHub Releases (that path is independent of the forward feed
+ * and migrates to R2 with #1719).
  *
  * Behavior:
  *   - First check 10 seconds after `init()` is called (typically from
@@ -51,6 +61,12 @@ const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000; // Subsequent checks every 4h
 const LOG_PATH = path.join(os.homedir(), ".gaia", "electron-updater.log");
 const UPDATE_CONFIG_PATH = path.join(os.homedir(), ".gaia", "update-config.json");
 
+// Mutable channel pointer name. electron-updater's generic provider fetches
+// `${feedUrl}/${DEFAULT_CHANNEL}.yml` (+ per-platform variants). The Hub Worker
+// re-points this file each release while versioned artifacts stay immutable —
+// that split is the A6/A7 resolution (#1724).
+const DEFAULT_CHANNEL = "latest";
+
 // per_page=100 is the GitHub API max for a single page; we fetch broadly so
 // draft/prerelease/platform filtering still yields a full page of installable
 // releases before the display cap below. >100 releases would need pagination
@@ -72,6 +88,8 @@ const STATES = Object.freeze({
   DOWNLOADED: "downloaded",
   ERROR: "error",
   DISABLED: "disabled",
+  // No forward-update feed configured — loud, actionable, never a silent no-op.
+  NO_CHANNEL: "no-channel",
 });
 
 // ── Module state ─────────────────────────────────────────────────────────────
@@ -93,6 +111,8 @@ let scheduledTimeout = null;
 let initialCheckTimeout = null;
 let ipcHandlersRegistered = false;
 let initialized = false;
+// The resolved forward-update feed URL (generic/R2), or null when unconfigured.
+let forwardFeedUrl = null;
 
 // Lazy-loaded Electron references (populated inside init()).
 let electronApi = null; // { dialog, ipcMain, app }
@@ -147,13 +167,86 @@ function _loadPin() {
  */
 function _savePin(pinnedVersion) {
   fs.mkdirSync(path.dirname(UPDATE_CONFIG_PATH), { recursive: true });
+  // Merge into any existing config so we don't clobber a persisted feedUrl.
+  let existing = {};
+  try {
+    if (fs.existsSync(UPDATE_CONFIG_PATH)) {
+      existing = JSON.parse(fs.readFileSync(UPDATE_CONFIG_PATH, "utf8")) || {};
+    }
+  } catch {
+    existing = {};
+  }
   fs.writeFileSync(
     UPDATE_CONFIG_PATH,
-    JSON.stringify({ pinnedVersion }, null, 2),
+    JSON.stringify({ ...existing, pinnedVersion }, null, 2),
     "utf8"
   );
 }
 
+// ── Forward-update feed resolution (issue #1724) ────────────────────────────────
+
+/**
+ * Resolve the generic forward-update feed URL, or null if none is configured.
+ * Precedence: GAIA_UPDATE_FEED_URL env > feedUrl in update-config.json.
+ */
+function _resolveFeedUrl() {
+  const envUrl = process.env.GAIA_UPDATE_FEED_URL;
+  if (typeof envUrl === "string" && envUrl.trim()) return envUrl.trim();
+  try {
+    if (fs.existsSync(UPDATE_CONFIG_PATH)) {
+      const cfg = JSON.parse(fs.readFileSync(UPDATE_CONFIG_PATH, "utf8"));
+      if (cfg && typeof cfg.feedUrl === "string" && cfg.feedUrl.trim()) {
+        return cfg.feedUrl.trim();
+      }
+    }
+  } catch (err) {
+    log("warn", "Failed to read feedUrl from update-config.json:", err && err.message);
+  }
+  return null;
+}
+
+/**
+ * Point electron-updater at the configured generic (R2) feed + mutable channel.
+ * When nothing is configured, enter the loud NO_CHANNEL state and set no feed —
+ * an unconfigured updater must never silently pretend it's up to date.
+ *
+ * @returns {boolean} true when a feed was applied, false when NO_CHANNEL.
+ */
+function _applyForwardFeed() {
+  if (!autoUpdaterRef) return false;
+  const url = _resolveFeedUrl();
+  if (!url) {
+    forwardFeedUrl = null;
+    setState({
+      status: STATES.NO_CHANNEL,
+      error:
+        "No update channel configured — set GAIA_UPDATE_FEED_URL (or feedUrl " +
+        "in ~/.gaia/update-config.json) to your R2 channel base URL. " +
+        "Auto-update is paused until a feed is configured.",
+    });
+    log("warn", "No update feed configured — auto-update paused (NO_CHANNEL)");
+    return false;
+  }
+  try {
+    autoUpdaterRef.setFeedURL({
+      provider: "generic",
+      url,
+      channel: DEFAULT_CHANNEL,
+    });
+    forwardFeedUrl = url;
+    log("info", `Update feed set (generic): ${url} [channel=${DEFAULT_CHANNEL}]`);
+    return true;
+  } catch (err) {
+    forwardFeedUrl = null;
+    setState({
+      status: STATES.ERROR,
+      error: `Failed to set update feed URL: ${(err && err.message) || String(err)}`,
+    });
+    log("error", "Failed to set feed URL:", err && err.message);
+    return false;
+  }
+}
+
 // ── State management ─────────────────────────────────────────────────────────
 
 function broadcastState() {
@@ -359,8 +452,10 @@ async function installVersion(tag) {
 /**
  * Clear the version pin and resume normal auto-updates.
  *
- * Restores the GitHub provider feed, sets autoDownload=true, and clears
- * allowDowngrade so the next check is the normal forward-only flow.
+ * Restores the configured forward (R2 generic) feed, sets autoDownload=true,
+ * and clears allowDowngrade so the next check is the normal forward-only flow.
+ * If no feed is configured, resume lands in the loud NO_CHANNEL state rather
+ * than silently reverting to a stale rollback feed.
  */
 function clearPin() {
   // A failed clear is non-fatal — worst case the stale pin re-pauses updates
@@ -375,17 +470,9 @@ function clearPin() {
   if (autoUpdaterRef) {
     autoUpdaterRef.autoDownload = true;
     autoUpdaterRef.allowDowngrade = false;
-    // Restore the GitHub provider (overrides any generic/tagged feed set by
-    // installVersion). Owner/repo must match electron-builder.yml publish block.
-    try {
-      autoUpdaterRef.setFeedURL({
-        provider: "github",
-        owner: "amd",
-        repo: "gaia",
-      });
-    } catch (err) {
-      log("warn", "Failed to restore GitHub feed on resume:", err && err.message);
-    }
+    // Restore the forward channel (overrides any generic/tagged rollback feed
+    // set by installVersion). Loud NO_CHANNEL if unconfigured.
+    _applyForwardFeed();
   }
 
   log("info", "Version pin cleared — auto-updates resumed");
@@ -403,6 +490,16 @@ async function checkForUpdates() {
     log("warn", "checkForUpdates called before init — ignoring");
     return;
   }
+  // No forward feed and not pinned → surface the loud NO_CHANNEL state instead
+  // of asking electron-updater to check a feed that doesn't exist. Re-resolve
+  // first so a feed written to config after init() is picked up here.
+  if (!forwardFeedUrl && !state.pinnedVersion) {
+    if (!_applyForwardFeed()) return;
+    // Feed just became available after a no-feed (NO_CHANNEL) start — init()
+    // skipped arming the periodic scheduler, so arm it now or background checks
+    // never resume once the feed goes live.
+    if (!scheduledTimeout) scheduleNextCheck();
+  }
   if (checkInProgress) {
     log("info", "Skipping check — another check is already in progress");
     return;
@@ -691,6 +788,25 @@ function init(mainWindow) {
     log("warn", "Failed to register IPC handlers:", err && err.message);
   }
 
+  // Point the updater at the configured R2 generic feed (#1724). When a pin is
+  // active, installVersion() owns the feed (rollback path), so skip. With no
+  // pin and no feed, _applyForwardFeed enters the loud NO_CHANNEL state and we
+  // don't schedule checks against a nonexistent feed.
+  let feedReady = true;
+  if (!savedPin) {
+    feedReady = _applyForwardFeed();
+  }
+
+  initialized = true;
+
+  if (!feedReady && !savedPin) {
+    log(
+      "info",
+      "Auto-updater initialized without a channel — checks paused until a feed is configured"
+    );
+    return;
+  }
+
   // First check after CHECK_DELAY_MS, then every CHECK_INTERVAL_MS.
   initialCheckTimeout = setTimeout(async () => {
     try {
@@ -701,7 +817,6 @@ function init(mainWindow) {
     scheduleNextCheck();
   }, CHECK_DELAY_MS);
 
-  initialized = true;
   log(
     "info",
     `Auto-updater initialized; first check in ${CHECK_DELAY_MS}ms`

package/services/backend-installer-progress-dialog.cjs

@@ -399,7 +399,7 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
         return "retry";
       case 2: {
         try {
-          await shell.openExternal("https://amd-gaia.ai/quickstart#cli-install");
+          await shell.openExternal("https://amd-gaia.ai/docs/quickstart#cli-install");
         } catch {
           // ignore
         }

package/services/backend-installer.cjs

@@ -645,7 +645,8 @@ function _extraCaCertificates() {
   try {
     return [fs.readFileSync(file, "utf8")];
   } catch (err) {
-    log(`Could not read NODE_EXTRA_CA_CERTS (${file}): ${err.message}`);
+    // err.message already names the offending path — don't re-log the env value.
+    log(`Could not read NODE_EXTRA_CA_CERTS: ${err.message}`);
     return [];
   }
 }
@@ -725,7 +726,10 @@ function _probeViaProxy(target, proxy, ca, finish, setSock) {
   try {
     proxyUrl = new URL(proxy);
   } catch {
-    finish({ ok: false, kind: "connectivity", message: `${target.href}: invalid proxy URL "${proxy}"` });
+    // HTTPS_PROXY/HTTP_PROXY may embed credentials (http://user:pass@host) —
+    // strip the userinfo before the value reaches the install log.
+    const redacted = proxy.replace(/^(\w+:\/\/)[^@/]*@/, "$1***@");
+    finish({ ok: false, kind: "connectivity", message: `${target.href}: invalid proxy URL "${redacted}"` });
     return;
   }
   const headers = {};
@@ -1530,11 +1534,11 @@ async function installBackend(opts = {}) {
           ? "GAIA retried with the OS certificate store and it still failed. "
           : "") +
         "Ask IT to install the proxy's root CA in your system's trusted certificate store, then relaunch GAIA. " +
-        "See https://amd-gaia.ai/quickstart#cli-install";
+        "See https://amd-gaia.ai/docs/quickstart#cli-install";
     } else {
       suggestion = `Try installing manually:\n  uv pip install ${pipPackage} --python ${
         IS_WINDOWS ? `${GAIA_VENV_DISPLAY}/Scripts/python.exe` : `${GAIA_VENV_DISPLAY}/bin/python`
-      }\nThen restart GAIA. See https://amd-gaia.ai/quickstart#cli-install`;
+      }\nThen restart GAIA. See https://amd-gaia.ai/docs/quickstart#cli-install`;
     }
     throw new InstallError(
       `Failed to install ${pipPackage} (pip exit ${installResult.code}).`,
@@ -1551,7 +1555,7 @@ async function installBackend(opts = {}) {
       `GAIA binary not found at ${GAIA_VENV_DISPLAY} after install.`,
       {
         stage: STAGES.INSTALL_PACKAGE,
-        suggestion: "The package was installed but the gaia executable is missing. Try reinstalling from https://amd-gaia.ai/quickstart",
+        suggestion: "The package was installed but the gaia executable is missing. Try reinstalling from https://amd-gaia.ai/docs/quickstart",
       }
     );
   }
@@ -1788,7 +1792,7 @@ async function ensureBackend(opts = {}) {
         "GAIA backend not found after installation.",
         {
           stage: STAGES.VERIFY,
-          suggestion: "Check the log file and try reinstalling. See https://amd-gaia.ai/quickstart",
+          suggestion: "Check the log file and try reinstalling. See https://amd-gaia.ai/docs/quickstart",
         }
       );
       setState(STATES.FAILED, {

package/services/deep-link.cjs

@@ -0,0 +1,230 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * deep-link.cjs — parse `gaia://` deep links (issue #1725).
+ *
+ * The website's "Open in GAIA" button hands the running app a
+ * `gaia://hub/install/<id>` URL. This module is the pure, Electron-free
+ * parser so it can be unit-tested without a running app; main.cjs owns the
+ * OS protocol registration and dispatch to the install runtime.
+ *
+ * Design: parse errors are THROWN with an actionable message (no silent
+ * fallback). main.cjs surfaces the message to the user instead of dropping a
+ * malformed link on the floor.
+ */
+
+"use strict";
+
+const SCHEME = "gaia:";
+
+// Agent ids as published on the hub: start alphanumeric, then letters, digits,
+// dot, dash, underscore. Bounded length keeps a hostile link from ballooning.
+const AGENT_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+/**
+ * Parse a `gaia://` deep link into a structured command.
+ *
+ * Supported form:
+ *   gaia://hub/install/<id>  → { action: "install", agentId }
+ *
+ * @param {string} rawUrl
+ * @returns {{ action: "install", agentId: string }}
+ * @throws {Error} with an actionable message on anything malformed/unsupported
+ */
+function parseDeepLink(rawUrl) {
+  if (typeof rawUrl !== "string" || !rawUrl.trim()) {
+    throw new Error(
+      'Not a GAIA deep link — expected a "gaia://…" URL but got ' +
+        (rawUrl === "" ? "an empty string" : JSON.stringify(rawUrl)) +
+        "."
+    );
+  }
+
+  const trimmed = rawUrl.trim();
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`Malformed GAIA deep link "${trimmed}" — not a valid URL.`);
+  }
+
+  if (parsed.protocol !== SCHEME) {
+    throw new Error(
+      `Unsupported URL scheme "${parsed.protocol}" — GAIA deep links must start with "gaia://".`
+    );
+  }
+
+  const host = parsed.hostname;
+  const segments = parsed.pathname.split("/").filter(Boolean);
+
+  if (host === "hub" && segments[0] === "install") {
+    const agentId = segments[1] ? decodeURIComponent(segments[1]) : "";
+    if (!agentId) {
+      throw new Error(
+        `GAIA install link "${trimmed}" is missing an agent id — expected gaia://hub/install/<id>.`
+      );
+    }
+    if (!AGENT_ID_RE.test(agentId)) {
+      throw new Error(
+        `GAIA install link has an invalid agent id "${agentId}" — ids may contain letters, digits, dot, dash and underscore.`
+      );
+    }
+    if (segments.length > 2) {
+      throw new Error(
+        `GAIA install link "${trimmed}" has unexpected extra path segments — expected gaia://hub/install/<id>.`
+      );
+    }
+    return { action: "install", agentId };
+  }
+
+  throw new Error(
+    `Unrecognized GAIA deep link "${trimmed}" — only gaia://hub/install/<id> is supported.`
+  );
+}
+
+/**
+ * Find the first `gaia://` argument in an argv array (Windows/Linux hand the
+ * deep link to the app as a command-line argument). Returns null if absent.
+ *
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+function extractDeepLinkFromArgv(argv) {
+  if (!Array.isArray(argv)) return null;
+  for (const arg of argv) {
+    if (typeof arg === "string" && arg.startsWith("gaia://")) return arg;
+  }
+  return null;
+}
+
+/**
+ * Act on a parsed deep-link command, with every Electron/runtime effect
+ * injected so the security-critical control flow is unit-testable.
+ *
+ * SECURITY (issue #2196 review): a `gaia://hub/install/<id>` link comes from an
+ * untrusted web page, so the install MUST be gated behind an explicit per-agent
+ * confirmation — the same trust bar the in-app install enforces (#2201). A bare
+ * OS "Open GAIA?" prompt is NOT consent to download and run a specific agent.
+ * If `confirm` does not return true, no install is attempted. `confirm` is
+ * expected to have shown the agent's real catalog tier and permissions first
+ * (see `buildInstallPrompt`), not just its bare id, before resolving true.
+ *
+ * Once confirmed, the install is sent with the trust override set — the
+ * backend's non-verified gate now covers every non-verified agent, not just
+ * native ones, and this out-of-band flow already required its own explicit
+ * per-agent confirmation regardless of tier.
+ *
+ * @param {{ action: string, agentId: string }} command
+ * @param {{
+ *   confirm: (command: {action: string, agentId: string}) => Promise<boolean>,
+ *   installAgent: (agentId: string, opts?: { trustNative?: boolean }) => Promise<any>,
+ *   focusWindow?: () => void,
+ *   logger?: { log?: (...a: any[]) => void, error?: (...a: any[]) => void },
+ * }} deps
+ * @returns {Promise<{ installed: boolean, reason?: string }>}
+ */
+async function dispatchDeepLink(command, deps) {
+  const { confirm, installAgent, focusWindow, logger } = deps || {};
+  const log = (logger && logger.log) || (() => {});
+
+  if (!command || command.action !== "install") {
+    throw new Error(
+      `Unsupported deep-link action "${command && command.action}".`
+    );
+  }
+  if (typeof confirm !== "function" || typeof installAgent !== "function") {
+    throw new Error(
+      "dispatchDeepLink requires confirm() and installAgent() dependencies"
+    );
+  }
+
+  // Surface the app first so the confirmation dialog is clearly GAIA's.
+  if (typeof focusWindow === "function") focusWindow();
+
+  const approved = await confirm(command);
+  if (approved !== true) {
+    log(`[deep-link] User declined install of "${command.agentId}"`);
+    return { installed: false, reason: "declined" };
+  }
+
+  log(`[deep-link] Confirmed — installing "${command.agentId}"`);
+  await installAgent(command.agentId, { trustNative: true });
+  return { installed: true };
+}
+
+// ── Informed trust prompt (security fix: gate ALL non-verified agents) ─────
+//
+// The bare confirm dialog above only ever showed the raw agent id — no tier,
+// no permissions, no AMD-verified indicator. That's per-agent confirmation,
+// but it isn't INFORMED consent. buildInstallPrompt renders the same facts
+// the in-app trust gate (hubLanes.trustGateFor) shows, from a catalog entry,
+// so the caller (main.cjs) can put them in front of the user before they
+// confirm.
+
+const TIER_LABEL = {
+  verified: "AMD Verified",
+  community: "Community",
+  experimental: "Experimental",
+};
+
+/** Normalize a possibly-missing/unknown tier the same way the in-app gate does. */
+function normalizeTier(entry) {
+  const t = entry && entry.security_tier;
+  return t === "verified" || t === "community" ? t : "experimental";
+}
+
+/**
+ * Build the confirmation prompt for a deep-link install from its catalog
+ * entry. Pure — no Electron dependency — so the trust posture is
+ * unit-testable without a running dialog.
+ *
+ * @param {{
+ *   id: string,
+ *   name?: string,
+ *   security_tier?: "verified" | "community" | "experimental",
+ *   permissions?: string[],
+ * } | null | undefined} entry — the agent's catalog entry.
+ * @returns {{ title: string, message: string, detail: string, requiresTrust: boolean }}
+ * @throws {Error} if no entry is given — never build a prompt for an agent
+ *   that couldn't be looked up; the caller must fail closed instead.
+ */
+function buildInstallPrompt(entry) {
+  if (!entry || typeof entry !== "object") {
+    throw new Error(
+      "buildInstallPrompt requires a catalog entry — refuse rather than prompting blind."
+    );
+  }
+
+  const tier = normalizeTier(entry);
+  const requiresTrust = tier !== "verified";
+  const name = entry.name || entry.id;
+  const permissions = Array.isArray(entry.permissions) ? entry.permissions : [];
+
+  const detail = [
+    `Tier: ${TIER_LABEL[tier]}${requiresTrust ? " — NOT AMD-verified" : ""}`,
+    permissions.length
+      ? `Permissions: ${permissions.join(", ")}`
+      : "Permissions: none declared",
+    requiresTrust
+      ? "This agent has not been audited by AMD. Only continue if you trust the " +
+        "publisher — installing downloads and runs third-party code on your machine."
+      : "This agent has been reviewed and verified by AMD.",
+  ].join("\n\n");
+
+  return {
+    title: requiresTrust
+      ? "Install untrusted agent from the web?"
+      : "Install agent from the web?",
+    message: `A website asked GAIA to install "${name}" (${entry.id}).`,
+    detail,
+    requiresTrust,
+  };
+}
+
+module.exports = {
+  parseDeepLink,
+  extractDeepLinkFromArgv,
+  dispatchDeepLink,
+  buildInstallPrompt,
+};

package/services/system-metrics.cjs

@@ -0,0 +1,154 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * GAIA Agent UI — System metrics collection (issue #2007)
+ *
+ * Collects real host metrics (CPU, memory, disk, network, per-process
+ * usage) for the observability dashboard and exposes them to the
+ * renderer over the `system:get-metrics` IPC channel. The shape matches
+ * the renderer's `SystemMetrics` type (src/types/agent.ts).
+ *
+ * GPU/NPU utilization is intentionally omitted (left `undefined`): there
+ * is no dependency-free cross-platform source for it, and the renderer
+ * type marks those fields optional — `undefined` renders as
+ * "unavailable", never as a fake zero.
+ *
+ * Errors propagate: a failing source rejects the IPC invoke so the
+ * renderer can surface it. No silent nulls.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const { app, ipcMain } = require("electron");
+
+const SYSTEM_GET_METRICS_CHANNEL = "system:get-metrics";
+
+const BYTES_PER_GB = 1024 * 1024 * 1024;
+
+/** Minimum sampling window for the very first CPU reading (ms). */
+const FIRST_CPU_SAMPLE_MS = 120;
+
+// Previous aggregate CPU times — CPU% is a delta between two samples.
+let prevCpuTimes = null;
+
+function readCpuTimes() {
+  let idle = 0;
+  let total = 0;
+  for (const cpu of os.cpus()) {
+    for (const [kind, ms] of Object.entries(cpu.times)) {
+      total += ms;
+      if (kind === "idle") idle += ms;
+    }
+  }
+  return { idle, total };
+}
+
+function cpuPercentBetween(prev, curr) {
+  const totalDelta = curr.total - prev.total;
+  const idleDelta = curr.idle - prev.idle;
+  if (totalDelta <= 0) return 0;
+  const pct = (1 - idleDelta / totalDelta) * 100;
+  return Math.min(100, Math.max(0, pct));
+}
+
+async function sampleCpuPercent() {
+  if (prevCpuTimes === null) {
+    // First call: take a short two-point sample so the reading is real,
+    // not a since-boot average.
+    prevCpuTimes = readCpuTimes();
+    await new Promise((r) => setTimeout(r, FIRST_CPU_SAMPLE_MS));
+  }
+  const curr = readCpuTimes();
+  const pct = cpuPercentBetween(prevCpuTimes, curr);
+  prevCpuTimes = curr;
+  return pct;
+}
+
+async function readDiskUsage(diskPath) {
+  let stat;
+  try {
+    stat = await fs.promises.statfs(diskPath);
+  } catch (err) {
+    throw new Error(
+      `Failed to read disk usage for ${diskPath}: ${err.message}. ` +
+        "The observability dashboard needs a readable filesystem path — " +
+        "check that the path exists and is accessible."
+    );
+  }
+  const totalBytes = stat.blocks * stat.bsize;
+  const freeBytes = stat.bfree * stat.bsize;
+  return {
+    diskUsedGB: (totalBytes - freeBytes) / BYTES_PER_GB,
+    diskTotalGB: totalBytes / BYTES_PER_GB,
+  };
+}
+
+function readProcesses(now) {
+  // Electron's own process tree (main, renderer, GPU, utility) — the
+  // processes this app can meaningfully report on without a system-wide
+  // process scanner dependency.
+  return app.getAppMetrics().map((p) => ({
+    pid: p.pid,
+    name: p.name || p.serviceName || p.type,
+    cpuPercent: p.cpu.percentCPUUsage,
+    memoryMB: p.memory.workingSetSize / 1024, // workingSetSize is in KB
+    uptime: p.creationTime ? Math.max(0, (now - p.creationTime) / 1000) : 0,
+  }));
+}
+
+function readNetworkUp() {
+  return Object.values(os.networkInterfaces()).some((addrs) =>
+    (addrs || []).some((a) => !a.internal)
+  );
+}
+
+/**
+ * Collect a full SystemMetrics snapshot from the real host.
+ *
+ * @param {object} [options]
+ * @param {string} [options.diskPath] Filesystem path to report disk usage
+ *   for (defaults to the user's home directory).
+ * @returns {Promise<object>} SystemMetrics-shaped snapshot.
+ */
+async function collectSystemMetrics(options = {}) {
+  const diskPath = options.diskPath || os.homedir();
+
+  const [cpuPercent, disk] = await Promise.all([
+    sampleCpuPercent(),
+    readDiskUsage(diskPath),
+  ]);
+
+  const totalMem = os.totalmem();
+  const freeMem = os.freemem();
+  const now = Date.now();
+
+  return {
+    cpuPercent,
+    memoryUsedGB: (totalMem - freeMem) / BYTES_PER_GB,
+    memoryTotalGB: totalMem / BYTES_PER_GB,
+    diskUsedGB: disk.diskUsedGB,
+    diskTotalGB: disk.diskTotalGB,
+    networkUp: readNetworkUp(),
+    processes: readProcesses(now),
+    timestamp: now,
+  };
+}
+
+/**
+ * Register the `system:get-metrics` IPC handler. Collection errors reject
+ * the renderer's invoke() so the store can surface them.
+ */
+function registerIpcHandlers() {
+  ipcMain.handle(SYSTEM_GET_METRICS_CHANNEL, async () => {
+    return collectSystemMetrics();
+  });
+}
+
+module.exports = {
+  collectSystemMetrics,
+  registerIpcHandlers,
+  SYSTEM_GET_METRICS_CHANNEL,
+};