@hellcoder/companion 0.116.1-preview.20260814042234.2d329a2 → 0.117.0

package/server/routes/system-routes.test.ts

@@ -30,6 +30,55 @@ vi.mock("../service.js", () => ({
   refreshServiceDefinition: vi.fn(),
 }));
 
+// ─── Mock claude-compat checker ────────────────────────────────────────────
+// The compat routes gate the post-2.1.121 --sdk-url lockdown workarounds.
+// Everything here touches the real Claude binary on disk, so it is mocked
+// wholesale — these tests exercise the route logic, never the filesystem.
+vi.mock("../claude-compat-checker.js", () => ({
+  checkCompat: vi.fn(async () => {}),
+  getCompatState: vi.fn(() => ({
+    installedVersion: "2.1.130",
+    installedPath: "/usr/local/bin/claude",
+    isIncompatible: true,
+    isPatched: false,
+    availableKnownGood: ["2.1.119", "2.1.120"],
+    suggestedPinTarget: "2.1.120",
+    lastChecked: 0,
+    error: null,
+  })),
+}));
+
+// ─── Mock claude-patcher ───────────────────────────────────────────────────
+vi.mock("../claude-patcher.js", () => ({
+  pinToVersion: vi.fn(async () => ({ ok: true })),
+  patchBinary: vi.fn(async () => ({
+    ok: true,
+    patchedPath: "/usr/local/bin/claude",
+    replacements: 3,
+  })),
+  unpatch: vi.fn(async () => ({ ok: true, target: "2.1.130" })),
+}));
+
+// ─── Mock settings-manager ─────────────────────────────────────────────────
+vi.mock("../settings-manager.js", () => ({
+  getSettings: vi.fn(() => ({
+    claudeBridgeMode: "none",
+    claudeBridgeIngressUrl: "",
+    claudeCompatBannerDismissedVersion: "",
+    dockerAutoUpdate: false,
+  })),
+  updateSettings: vi.fn(),
+}));
+
+// ─── Mock cli-ingress-server ───────────────────────────────────────────────
+// Starting the real one binds a TLS listener.
+vi.mock("../cli-ingress-server.js", () => ({
+  startCliIngressServer: vi.fn(async () => ({
+    urlPrefix: "wss://[::1]:8443",
+    stop: vi.fn(),
+  })),
+}));
+
 import { Hono } from "hono";
 import { getUsageLimits } from "../usage-limits.js";
 import {
@@ -39,6 +88,9 @@ import {
   setUpdateInProgress,
 } from "../update-checker.js";
 import { registerSystemRoutes } from "./system-routes.js";
+import { checkCompat, getCompatState } from "../claude-compat-checker.js";
+import { pinToVersion, patchBinary, unpatch } from "../claude-patcher.js";
+import { getSettings, updateSettings } from "../settings-manager.js";
 
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
@@ -75,8 +127,39 @@ let launcher: ReturnType<typeof createMockLauncher>;
 let wsBridge: ReturnType<typeof createMockWsBridge>;
 let terminalManager: ReturnType<typeof createMockTerminalManager>;
 
+/** Default compat state: an incompatible CLI with a known-good pin target. */
+function defaultCompatState() {
+  return {
+    installedVersion: "2.1.130",
+    installedPath: "/usr/local/bin/claude",
+    isIncompatible: true,
+    isPatched: false,
+    availableKnownGood: ["2.1.119", "2.1.120"],
+    suggestedPinTarget: "2.1.120",
+    lastChecked: 0,
+    error: null,
+  };
+}
+
 beforeEach(() => {
+  // clearAllMocks() resets call history but NOT implementations, so a
+  // mockReturnValue set inside one test leaks into every later one. Restoring
+  // the defaults here keeps the suite order-independent.
   vi.clearAllMocks();
+  vi.mocked(getCompatState).mockReturnValue(defaultCompatState() as any);
+  vi.mocked(pinToVersion).mockResolvedValue({ ok: true } as any);
+  vi.mocked(patchBinary).mockResolvedValue({
+    ok: true,
+    patchedPath: "/usr/local/bin/claude",
+    replacements: 3,
+  } as any);
+  vi.mocked(unpatch).mockResolvedValue({ ok: true, target: "2.1.130" } as any);
+  vi.mocked(getSettings).mockReturnValue({
+    claudeBridgeMode: "none",
+    claudeBridgeIngressUrl: "",
+    claudeCompatBannerDismissedVersion: "",
+    dockerAutoUpdate: false,
+  } as any);
 
   launcher = createMockLauncher();
   wsBridge = createMockWsBridge();
@@ -635,3 +718,321 @@ describe("POST /api/sessions/:id/message", () => {
     expect(json2.error).toMatch(/content/i);
   });
 });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// GET /api/system/memory  and  GET /api/system/disk
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("GET /api/system/memory", () => {
+  it("returns a memory snapshot including swap fields", async () => {
+    const res = await app.request("/api/system/memory");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+
+    expect(json.total_bytes).toBeGreaterThan(0);
+    expect(json.used_bytes).toBeLessThanOrEqual(json.total_bytes);
+    // Swap must always be present, even on a host with none configured —
+    // the UI keys off swap_total_bytes === 0 to hide the meter.
+    expect(typeof json.swap_total_bytes).toBe("number");
+    expect(typeof json.swap_used_bytes).toBe("number");
+    expect(typeof json.swap_used_percent).toBe("number");
+  });
+});
+
+describe("GET /api/system/disk", () => {
+  it("returns a disk snapshot for the Companion data volume", async () => {
+    const res = await app.request("/api/system/disk");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+
+    // getSystemDisk returns null when statfs is unavailable; the route passes
+    // that through as JSON null rather than an empty 204 body.
+    if (json === null) return;
+
+    expect(json.total_bytes).toBeGreaterThan(0);
+    expect(json.used_bytes).toBe(json.total_bytes - json.available_bytes);
+    expect(json.used_percent).toBeGreaterThanOrEqual(0);
+    expect(json.used_percent).toBeLessThanOrEqual(100);
+    expect(typeof json.path).toBe("string");
+  });
+
+  it("always responds 200 with a JSON body, never an empty 204", async () => {
+    // The browser client calls res.json() unconditionally — an empty body
+    // would throw and log a spurious API failure on every poll.
+    const res = await app.request("/api/system/disk");
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.not.toThrow();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// POST /api/update — guard branches only
+// ═══════════════════════════════════════════════════════════════════════════
+
+// The success path spawns `bun install -g` and calls process.exit(), so these
+// tests deliberately cover only the three refusal branches.
+describe("POST /api/update (guards)", () => {
+  it("returns 400 when not running as a service", async () => {
+    vi.mocked(getUpdateState).mockReturnValue({
+      currentVersion: "1.0.0", latestVersion: "1.1.0", lastChecked: 0,
+      isServiceMode: false, checking: false, updateInProgress: false, channel: "stable",
+    } as any);
+
+    const res = await app.request("/api/update", { method: "POST" });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toMatch(/service mode/i);
+    expect(setUpdateInProgress).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when no update is available", async () => {
+    vi.mocked(getUpdateState).mockReturnValue({
+      currentVersion: "1.0.0", latestVersion: "1.0.0", lastChecked: 0,
+      isServiceMode: true, checking: false, updateInProgress: false, channel: "stable",
+    } as any);
+    vi.mocked(isUpdateAvailable).mockReturnValue(false);
+
+    const res = await app.request("/api/update", { method: "POST" });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toMatch(/no update/i);
+  });
+
+  it("returns 409 when an update is already in progress", async () => {
+    vi.mocked(getUpdateState).mockReturnValue({
+      currentVersion: "1.0.0", latestVersion: "1.1.0", lastChecked: 0,
+      isServiceMode: true, checking: false, updateInProgress: true, channel: "stable",
+    } as any);
+    vi.mocked(isUpdateAvailable).mockReturnValue(true);
+
+    const res = await app.request("/api/update", { method: "POST" });
+    expect(res.status).toBe(409);
+    expect((await res.json()).error).toMatch(/already in progress/i);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Terminal routes
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("terminal routes", () => {
+  it("GET /api/terminal reports inactive when no terminal exists", async () => {
+    terminalManager.getInfo.mockReturnValue(null);
+    const res = await app.request("/api/terminal");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ active: false });
+  });
+
+  it("GET /api/terminal returns the terminal id and cwd when active", async () => {
+    terminalManager.getInfo.mockReturnValue({ id: "t-1", cwd: "/repo" });
+    const res = await app.request("/api/terminal?terminalId=t-1");
+    expect(await res.json()).toEqual({ active: true, terminalId: "t-1", cwd: "/repo" });
+    expect(terminalManager.getInfo).toHaveBeenCalledWith("t-1");
+  });
+
+  it("POST /api/terminal/spawn requires a cwd", async () => {
+    const res = await app.request("/api/terminal/spawn", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toMatch(/cwd/i);
+    expect(terminalManager.spawn).not.toHaveBeenCalled();
+  });
+
+  it("POST /api/terminal/spawn passes dimensions and container through", async () => {
+    const res = await app.request("/api/terminal/spawn", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ cwd: "/repo", cols: 120, rows: 40, containerId: "c-1" }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ terminalId: "terminal-123" });
+    expect(terminalManager.spawn).toHaveBeenCalledWith("/repo", 120, 40, { containerId: "c-1" });
+  });
+
+  it("POST /api/terminal/kill requires a terminalId", async () => {
+    // Covers both a missing body and a whitespace-only id.
+    const res1 = await app.request("/api/terminal/kill", { method: "POST" });
+    expect(res1.status).toBe(400);
+
+    const res2 = await app.request("/api/terminal/kill", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ terminalId: "  " }),
+    });
+    expect(res2.status).toBe(400);
+    expect(terminalManager.kill).not.toHaveBeenCalled();
+  });
+
+  it("POST /api/terminal/kill kills the named terminal", async () => {
+    const res = await app.request("/api/terminal/kill", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ terminalId: "t-1" }),
+    });
+    expect(res.status).toBe(200);
+    expect(terminalManager.kill).toHaveBeenCalledWith("t-1");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Claude compatibility routes (--sdk-url lockdown workarounds)
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("GET /api/claude-compat", () => {
+  it("refreshes when the cached state is stale, then returns the payload", async () => {
+    // lastChecked === 0 means "never checked" — must trigger a refresh.
+    const res = await app.request("/api/claude-compat");
+    expect(res.status).toBe(200);
+    expect(checkCompat).toHaveBeenCalled();
+
+    const json = await res.json();
+    expect(json.installedVersion).toBe("2.1.130");
+    expect(json.isIncompatible).toBe(true);
+    expect(json.suggestedPinTarget).toBe("2.1.120");
+    // Settings-derived fields are merged into the same payload.
+    expect(json.bridgeMode).toBe("none");
+    expect(json.bannerDismissedVersion).toBe("");
+  });
+
+  it("skips the refresh when the cached state is fresh", async () => {
+    vi.mocked(getCompatState).mockReturnValue({
+      installedVersion: "2.1.130", installedPath: "/usr/local/bin/claude",
+      isIncompatible: false, isPatched: false, availableKnownGood: [],
+      suggestedPinTarget: "", lastChecked: Date.now(), error: null,
+    } as any);
+
+    await app.request("/api/claude-compat");
+    expect(checkCompat).not.toHaveBeenCalled();
+  });
+});
+
+describe("POST /api/claude-compat/refresh", () => {
+  it("always re-checks and returns the fresh payload", async () => {
+    const res = await app.request("/api/claude-compat/refresh", { method: "POST" });
+    expect(res.status).toBe(200);
+    expect(checkCompat).toHaveBeenCalled();
+    expect((await res.json()).installedVersion).toBe("2.1.130");
+  });
+});
+
+describe("POST /api/claude-compat/pin", () => {
+  it("pins to the suggested target and disables patched bridge mode", async () => {
+    const res = await app.request("/api/claude-compat/pin", { method: "POST" });
+    expect(res.status).toBe(200);
+    expect(pinToVersion).toHaveBeenCalledWith("2.1.120");
+
+    // Pinning returns to a non-validator binary, so the bridge must be turned
+    // off — otherwise the CLI keeps being pointed at wss://[::1].
+    expect(updateSettings).toHaveBeenCalledWith({
+      claudeBridgeMode: "none",
+      claudeBridgeIngressUrl: "",
+    });
+    expect((await res.json()).pinnedTo).toBe("2.1.120");
+  });
+
+  it("honours an explicit version from the body", async () => {
+    await app.request("/api/claude-compat/pin", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ version: "2.1.119" }),
+    });
+    expect(pinToVersion).toHaveBeenCalledWith("2.1.119");
+  });
+
+  it("returns 400 when no known-good version is available to pin to", async () => {
+    vi.mocked(getCompatState).mockReturnValue({
+      installedVersion: "2.1.130", installedPath: "/usr/local/bin/claude",
+      isIncompatible: true, isPatched: false, availableKnownGood: [],
+      suggestedPinTarget: "", lastChecked: 0, error: null,
+    } as any);
+
+    const res = await app.request("/api/claude-compat/pin", { method: "POST" });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toMatch(/known-good/i);
+    expect(pinToVersion).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a pin failure as 400", async () => {
+    vi.mocked(pinToVersion).mockResolvedValue({ ok: false, error: "download failed" } as any);
+    const res = await app.request("/api/claude-compat/pin", { method: "POST" });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toBe("download failed");
+  });
+});
+
+describe("POST /api/claude-compat/patch", () => {
+  it("patches the binary, starts the ingress listener and persists the URL", async () => {
+    const res = await app.request("/api/claude-compat/patch", { method: "POST" });
+    expect(res.status).toBe(200);
+    expect(patchBinary).toHaveBeenCalled();
+
+    const json = await res.json();
+    expect(json.replacements).toBe(3);
+    expect(updateSettings).toHaveBeenCalledWith({
+      claudeBridgeMode: "patched",
+      claudeBridgeIngressUrl: "wss://[::1]:8443",
+    });
+  });
+
+  it("returns 400 when the binary cannot be patched", async () => {
+    vi.mocked(patchBinary).mockResolvedValue({ ok: false, error: "unknown layout" } as any);
+    const res = await app.request("/api/claude-compat/patch", { method: "POST" });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toBe("unknown layout");
+  });
+});
+
+describe("POST /api/claude-compat/unpatch", () => {
+  it("restores the binary and clears bridge settings", async () => {
+    const res = await app.request("/api/claude-compat/unpatch", { method: "POST" });
+    expect(res.status).toBe(200);
+    expect(unpatch).toHaveBeenCalled();
+    expect(updateSettings).toHaveBeenCalledWith({
+      claudeBridgeMode: "none",
+      claudeBridgeIngressUrl: "",
+    });
+    expect((await res.json()).target).toBe("2.1.130");
+  });
+
+  it("returns 400 when unpatching fails", async () => {
+    vi.mocked(unpatch).mockResolvedValue({ ok: false, error: "no backup" } as any);
+    const res = await app.request("/api/claude-compat/unpatch", { method: "POST" });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toBe("no backup");
+  });
+});
+
+describe("POST /api/claude-compat/dismiss-banner", () => {
+  it("records the explicitly supplied version", async () => {
+    const res = await app.request("/api/claude-compat/dismiss-banner", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ version: "2.1.131" }),
+    });
+    expect(res.status).toBe(200);
+    expect(updateSettings).toHaveBeenCalledWith({
+      claudeCompatBannerDismissedVersion: "2.1.131",
+    });
+  });
+
+  it("falls back to the currently installed version", async () => {
+    const res = await app.request("/api/claude-compat/dismiss-banner", { method: "POST" });
+    expect(res.status).toBe(200);
+    expect(updateSettings).toHaveBeenCalledWith({
+      claudeCompatBannerDismissedVersion: "2.1.130",
+    });
+  });
+
+  it("returns 400 when there is no version to record", async () => {
+    vi.mocked(getCompatState).mockReturnValue({
+      installedVersion: null, installedPath: null, isIncompatible: false,
+      isPatched: false, availableKnownGood: [], suggestedPinTarget: "",
+      lastChecked: 0, error: null,
+    } as any);
+
+    const res = await app.request("/api/claude-compat/dismiss-banner", { method: "POST" });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toMatch(/version/i);
+  });
+});

package/server/routes/system-routes.ts

@@ -4,6 +4,7 @@ import type { WsBridge } from "../ws-bridge.js";
 import type { TerminalManager } from "../terminal-manager.js";
 import { getUsageLimits } from "../usage-limits.js";
 import { getSystemMemory } from "../system-memory.js";
+import { getSystemDisk } from "../system-disk.js";
 import {
   getUpdateState,
   checkForUpdate,
@@ -49,6 +50,15 @@ export function registerSystemRoutes(
     return c.json(getSystemMemory());
   });
 
+  // Free space on the volume holding COMPANION_HOME. Backed by a single
+  // statfs(2) call, so it is cheap enough to poll without caching.
+  api.get("/system/disk", (c) => {
+    // JSON null rather than 204: the browser client calls res.json()
+    // unconditionally, and an empty body would throw and register a spurious
+    // API failure on every poll.
+    return c.json(getSystemDisk());
+  });
+
   api.get("/sessions/:id/usage-limits", async (c) => {
     const sessionId = c.req.param("id");
     const session = deps.wsBridge.getSession(sessionId);

package/server/system-disk.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { getSystemDisk } from "./system-disk.js";
+
+// getSystemDisk reads the real filesystem via statfs(2), so exact byte counts
+// are machine-dependent. The invariants below must hold on any host where
+// statfs succeeds. On a host without statfs the function returns null, which
+// every test tolerates — the meter is best-effort by design.
+describe("getSystemDisk", () => {
+  it("returns a coherent snapshot with sane invariants", () => {
+    const d = getSystemDisk();
+    if (!d) return; // statfs unavailable — nothing to assert
+
+    // A mounted filesystem always has positive capacity.
+    expect(d.total_bytes).toBeGreaterThan(0);
+
+    expect(d.used_bytes).toBeGreaterThanOrEqual(0);
+    expect(d.available_bytes).toBeGreaterThanOrEqual(0);
+    expect(d.used_bytes).toBeLessThanOrEqual(d.total_bytes);
+    expect(d.available_bytes).toBeLessThanOrEqual(d.total_bytes);
+
+    // used is derived as total - available (never bfree), so the identity
+    // must hold exactly. This is the guard against a future refactor
+    // switching to bfree and silently under-reporting usage.
+    expect(d.used_bytes).toBe(Math.max(0, d.total_bytes - d.available_bytes));
+  });
+
+  it("reports used_percent in 0–100 rounded to one decimal", () => {
+    const d = getSystemDisk();
+    if (!d) return;
+    expect(d.used_percent).toBeGreaterThanOrEqual(0);
+    expect(d.used_percent).toBeLessThanOrEqual(100);
+    expect(Math.round(d.used_percent * 10)).toBe(d.used_percent * 10);
+  });
+
+  it("reports the Companion data dir as the measured path", () => {
+    const d = getSystemDisk();
+    if (!d) return;
+    // The meter must describe the volume that session/recording files grow
+    // into, which is not necessarily the one holding "/".
+    expect(d.path).toBeTruthy();
+    expect(typeof d.path).toBe("string");
+  });
+
+  it("never throws, even though the underlying syscall can fail", () => {
+    // The route calls this on every poll with no try/catch of its own.
+    expect(() => getSystemDisk()).not.toThrow();
+  });
+});

package/server/system-disk.ts

@@ -0,0 +1,55 @@
+import { statfsSync } from "node:fs";
+import { COMPANION_HOME } from "./paths.js";
+
+export interface SystemDiskInfo {
+  /** Total size of the filesystem holding COMPANION_HOME, in bytes. */
+  total_bytes: number;
+  /** Space in use (total - available), in bytes. */
+  used_bytes: number;
+  /** Space available to this (unprivileged) user, in bytes. */
+  available_bytes: number;
+  /** Used percentage of total, 0–100, rounded to one decimal. */
+  used_percent: number;
+  /** Path the figures were measured for. */
+  path: string;
+}
+
+/**
+ * Snapshot of free space on the filesystem that holds the Companion data
+ * directory — that's the volume sessions, recordings and logs actually grow
+ * into, which is not necessarily the one holding "/".
+ *
+ * Deliberately uses statfs(2) rather than shelling out to `df`, and never
+ * walks the tree the way `du` would: this is a single syscall against the
+ * already-in-memory superblock (~0.1ms, no disk I/O), so it is safe to call
+ * on a poll interval and needs no caching layer.
+ *
+ * We report `bavail` (blocks free to unprivileged users) rather than `bfree`,
+ * which excludes the root-reserved reserve. That mirrors how getSystemMemory()
+ * prefers MemAvailable over MemFree: both answer "how much can I actually
+ * still use" rather than "how much is technically unallocated". It is also why
+ * this can read a percent or two above `df` for the same filesystem.
+ */
+export function getSystemDisk(): SystemDiskInfo | null {
+  try {
+    const stats = statfsSync(COMPANION_HOME);
+    // bsize is the preferred I/O block size that blocks/bavail are counted in.
+    const total = stats.blocks * stats.bsize;
+    const available = stats.bavail * stats.bsize;
+    const used = Math.max(0, total - available);
+    const used_percent =
+      total > 0 ? Math.round((used / total) * 1000) / 10 : 0;
+    return {
+      total_bytes: total,
+      used_bytes: used,
+      available_bytes: available,
+      used_percent,
+      path: COMPANION_HOME,
+    };
+  } catch {
+    // statfs is unavailable (very old runtime) or the path does not exist yet
+    // on a first run. The meter is best-effort — the route returns 204 and the
+    // UI renders nothing rather than showing a bogus zeroed bar.
+    return null;
+  }
+}

package/server/system-memory.test.ts

@@ -28,4 +28,36 @@ describe("getSystemMemory", () => {
     // At most one decimal place.
     expect(Math.round(m.used_percent * 10)).toBe(m.used_percent * 10);
   });
+
+  // Swap is read from the same /proc/meminfo snapshot as RAM. A host may have
+  // no swap at all, in which case every swap field must be 0 — the UI keys off
+  // swap_total_bytes === 0 to hide the meter entirely.
+  it("returns coherent swap figures, or zeroes when swap is absent", () => {
+    const m = getSystemMemory();
+
+    expect(m.swap_total_bytes).toBeGreaterThanOrEqual(0);
+    expect(m.swap_used_bytes).toBeGreaterThanOrEqual(0);
+
+    if (m.swap_total_bytes === 0) {
+      // No swap configured (or a non-Linux host): must not report phantom use.
+      expect(m.swap_used_bytes).toBe(0);
+      expect(m.swap_used_percent).toBe(0);
+      return;
+    }
+
+    // Used swap can never exceed the configured total, even though SwapFree
+    // can briefly exceed SwapTotal during swapoff — that's what the clamp is for.
+    expect(m.swap_used_bytes).toBeLessThanOrEqual(m.swap_total_bytes);
+    expect(m.swap_used_percent).toBeGreaterThanOrEqual(0);
+    expect(m.swap_used_percent).toBeLessThanOrEqual(100);
+    expect(Math.round(m.swap_used_percent * 10)).toBe(m.swap_used_percent * 10);
+  });
+
+  it("keeps swap independent of the RAM figures", () => {
+    // MemAvailable deliberately excludes swap, so a swapping box shows healthy
+    // RAM headroom while thrashing. Guards against a refactor that folds swap
+    // into used_bytes and hides exactly the condition we want to surface.
+    const m = getSystemMemory();
+    expect(m.used_bytes).toBe(Math.max(0, m.total_bytes - m.available_bytes));
+  });
 });

package/server/system-memory.ts

@@ -10,6 +10,15 @@ export interface SystemMemoryInfo {
   available_bytes: number;
   /** Used percentage of total, 0–100, rounded to one decimal. */
   used_percent: number;
+  /**
+   * Total swap, in bytes. 0 when no swap is configured, or on platforms where
+   * we cannot read it — callers should treat 0 as "no swap meter to show".
+   */
+  swap_total_bytes: number;
+  /** Swap in use (total - free), in bytes. */
+  swap_used_bytes: number;
+  /** Used percentage of swap, 0–100, rounded to one decimal. 0 when no swap. */
+  swap_used_percent: number;
 }
 
 /**
@@ -25,10 +34,19 @@ function readMeminfoKb(meminfo: string, key: string): number | null {
  * MemAvailable, which accounts for reclaimable page cache and therefore
  * reflects true OOM headroom far better than os.freemem(). Everywhere else
  * (or if /proc is unreadable) we fall back to the os module.
+ *
+ * Swap comes from the same single /proc/meminfo read, so reporting it costs
+ * nothing extra. It is worth surfacing separately rather than folding into the
+ * RAM figure: a box that has begun swapping heavily is already thrashing, and
+ * because MemAvailable excludes swap the RAM meter alone cannot show it. Swap
+ * exhaustion on top of high RAM use is the state immediately preceding the OOM
+ * killer, which is exactly what these meters exist to warn about.
  */
 export function getSystemMemory(): SystemMemoryInfo {
   let total = os.totalmem();
   let available = os.freemem();
+  let swapTotal = 0;
+  let swapUsed = 0;
 
   try {
     const meminfo = readFileSync("/proc/meminfo", "utf8");
@@ -38,16 +56,30 @@ export function getSystemMemory(): SystemMemoryInfo {
       total = totalKb * 1024;
       available = availableKb * 1024;
     }
+    const swapTotalKb = readMeminfoKb(meminfo, "SwapTotal");
+    const swapFreeKb = readMeminfoKb(meminfo, "SwapFree");
+    if (swapTotalKb !== null && swapFreeKb !== null) {
+      swapTotal = swapTotalKb * 1024;
+      // Clamp: SwapFree can momentarily exceed SwapTotal mid-swapoff.
+      swapUsed = Math.max(0, swapTotal - swapFreeKb * 1024);
+    }
   } catch {
     // Not Linux, or /proc/meminfo unavailable — keep the os module values.
+    // The os module exposes no swap figures, so swap stays 0 (= "unknown",
+    // rendered as no meter) rather than being reported as 0-bytes-used.
   }
 
   const used = Math.max(0, total - available);
   const used_percent = total > 0 ? Math.round((used / total) * 1000) / 10 : 0;
+  const swap_used_percent =
+    swapTotal > 0 ? Math.round((swapUsed / swapTotal) * 1000) / 10 : 0;
   return {
     total_bytes: total,
     used_bytes: used,
     available_bytes: available,
     used_percent,
+    swap_total_bytes: swapTotal,
+    swap_used_bytes: swapUsed,
+    swap_used_percent,
   };
 }