Merge pull request #692: feat(header): opt-in GPU and CPU clock readings after CPU and MEM

Conflict in config/test-suites.ts resolved by keeping both sides: #689's
header-divider and #692's header-host-sensors browser tests are both
listed in BROWSER_TEST_GLOBS.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/host-sensors.ts

@@ -0,0 +1,501 @@
+/**
+ * @fileoverview Optional host readings for the header stats: GPU load and memory, and the live CPU and GPU clock
+ * speeds.
+ *
+ * Every reader is opt-in per request (the route only calls the ones the browser asks for, and the browser only
+ * asks when the matching setting is on), answers `undefined` when the host has no such sensor, and never
+ * throws. Reads are cached for a couple of seconds so several open tabs cost one read.
+ *
+ * Sources, with no extra dependency:
+ *   - GPU: `nvidia-smi` (NVIDIA), else the amdgpu sysfs files (`gpu_busy_percent`, `mem_info_vram_*`,
+ *     `pp_dpm_sclk`), else, inside WSL, the Windows performance counters through `typeperf.exe` (any vendor,
+ *     Intel included: load and memory in use, but Windows publishes no GPU clock for them).
+ *   - CPU clock: inside WSL the Windows `Processor Frequency` counter (WSL's own cpuinfo is a fixed number),
+ *     else the mean of `scaling_cur_freq` across cores, else the `cpu MHz` lines of /proc/cpuinfo.
+ *
+ * The parsers are pure and exported so the tests need no hardware.
+ *
+ * @module host-sensors
+ */
+
+import { execFile, spawn, type ChildProcess } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface GpuReading {
+  /** Core utilisation, 0 to 100. */
+  percent: number;
+  /** Graphics memory in use as a share of what is available, 0 to 100, when that is known. */
+  memPercent?: number;
+  memUsedMB?: number;
+  memTotalMB?: number;
+  /** Current graphics clock in MHz, when known. */
+  mhz?: number;
+}
+
+export interface HostSensors {
+  gpu?: GpuReading;
+  cpuMhz?: number;
+}
+
+export interface SensorRequest {
+  /** GPU load, graphics memory and clock. */
+  gpu?: boolean;
+  cpuMhz?: boolean;
+}
+
+const CACHE_MS = 2000;
+/** A counter sample older than this (a few sampling intervals) is no longer a live reading. */
+const FRESH_MS = 10000;
+/** After a reader fails, leave it alone this long: nvidia-smi absent or timing out, PowerShell failing. */
+const READER_BACKOFF_MS = 60000;
+/** The GPU counters stay in the sampler this long after the last GPU read that needed them. */
+const GPU_COUNTERS_HOLD_MS = 120000;
+const EXEC_TIMEOUT_MS = 1500;
+const SYS_DRM = '/sys/class/drm';
+const SYS_CPU = '/sys/devices/system/cpu';
+const TYPEPERF = '/mnt/c/Windows/System32/typeperf.exe';
+const POWERSHELL = '/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe';
+const MB = 1048576;
+
+const clampPercent = (n: number) => Math.min(100, Math.max(0, Math.round(n)));
+const finite = (n: number) => (Number.isFinite(n) ? n : undefined);
+
+/** Parse `nvidia-smi --query-gpu=utilization.gpu,memory.used,memory.total,clocks.gr --format=csv,noheader,nounits`. */
+export function parseNvidiaSmi(output: string): GpuReading | undefined {
+  const line = output.split('\n').find((l) => l.trim());
+  if (!line) return undefined;
+  const [util, used, total, clock] = line.split(',').map((s) => finite(Number(s.trim())));
+  if (util === undefined) return undefined;
+  const reading: GpuReading = { percent: clampPercent(util) };
+  if (used !== undefined && total !== undefined && total > 0) {
+    reading.memUsedMB = Math.round(used);
+    reading.memTotalMB = Math.round(total);
+    reading.memPercent = clampPercent((used / total) * 100);
+  }
+  if (clock !== undefined && clock > 0) reading.mhz = Math.round(clock);
+  return reading;
+}
+
+/** The active line of an amdgpu `pp_dpm_sclk` table (`1: 1800Mhz *`). */
+export function parseDpmClock(text: string): number | undefined {
+  const active = text.split('\n').find((l) => l.trim().endsWith('*'));
+  const mhz = active ? /(\d+)\s*mhz/i.exec(active)?.[1] : undefined;
+  return mhz ? Number(mhz) : undefined;
+}
+
+/** Mean of per-core `scaling_cur_freq` values (kHz) as MHz. */
+export function meanKhzAsMhz(values: number[]): number | undefined {
+  const good = values.filter((v) => Number.isFinite(v) && v > 0);
+  if (!good.length) return undefined;
+  return Math.round(good.reduce((a, b) => a + b, 0) / good.length / 1000);
+}
+
+/** Mean of the `cpu MHz : 3412.5` lines of /proc/cpuinfo. */
+export function parseCpuInfoMhz(text: string): number | undefined {
+  const values = [...text.matchAll(/^cpu MHz\s*:\s*([\d.]+)/gim)].map((m) => Number(m[1]));
+  return meanKhzAsMhz(values.map((v) => v * 1000));
+}
+
+export interface WindowsCounters {
+  gpu?: { percent: number; memUsedMB: number; dedicated: boolean };
+  cpuMhz?: number;
+}
+
+const ENGINE =
+  /GPU Engine\(.*?_luid_(0x[0-9a-f]+_0x[0-9a-f]+)_phys_\d+_eng_\d+_engtype_([^)]*)\)\\Utilization Percentage/i;
+const ADAPTER_MEMORY = /GPU Adapter Memory\(luid_(0x[0-9a-f]+_0x[0-9a-f]+)_phys_\d+\)\\(Shared|Dedicated) Usage/i;
+const CPU_FREQUENCY = /Processor Information\(_Total\)\\Processor Frequency/i;
+
+/**
+ * Parse one `typeperf.exe -sc 1 ...` sample: a quoted CSV header of counter paths and one row of values.
+ * Task Manager's GPU figure is its busiest engine, so per adapter the load is the largest per-engine-type sum
+ * (3D, copy, video decode...), capped at 100. The adapter that holds the most graphics memory is the real one
+ * (Windows also lists software adapters that hold a few kilobytes). A `Shared Usage` only means an integrated
+ * GPU, whose memory is carved out of system RAM.
+ */
+export function parseTypeperf(output: string): WindowsCounters {
+  const rows = output
+    .split(/\r?\n/)
+    .filter((l) => l.startsWith('"'))
+    .map((l) => l.slice(1, l.lastIndexOf('"')).split('","'));
+  if (rows.length < 2) return {};
+  const [names, values] = rows;
+  const engines = new Map<string, Map<string, number>>();
+  const memory = new Map<string, { shared: number; dedicated: number }>();
+  let cpuMhz: number | undefined;
+  names.forEach((name, i) => {
+    const value = finite(Number(values[i]));
+    if (value === undefined || values[i].trim() === '') return;
+    const engine = ENGINE.exec(name);
+    if (engine) {
+      const byType = engines.get(engine[1].toLowerCase()) ?? new Map<string, number>();
+      byType.set(engine[2], (byType.get(engine[2]) ?? 0) + value);
+      engines.set(engine[1].toLowerCase(), byType);
+      return;
+    }
+    const mem = ADAPTER_MEMORY.exec(name);
+    if (mem) {
+      const luid = mem[1].toLowerCase();
+      const entry = memory.get(luid) ?? { shared: 0, dedicated: 0 };
+      if (mem[2].toLowerCase() === 'shared') entry.shared = value;
+      else entry.dedicated = value;
+      memory.set(luid, entry);
+      return;
+    }
+    if (CPU_FREQUENCY.test(name) && value > 0) cpuMhz = Math.round(value);
+  });
+  const result: WindowsCounters = {};
+  if (cpuMhz) result.cpuMhz = cpuMhz;
+  const luids = new Set([...engines.keys(), ...memory.keys()]);
+  let best: { luid: string; bytes: number; load: number } | undefined;
+  for (const luid of luids) {
+    const m = memory.get(luid);
+    const bytes = (m?.shared ?? 0) + (m?.dedicated ?? 0);
+    const load = Math.max(0, ...(engines.get(luid)?.values() ?? []));
+    if (!best || bytes > best.bytes || (bytes === best.bytes && load > best.load)) best = { luid, bytes, load };
+  }
+  if (best && (engines.size > 0 || memory.size > 0)) {
+    result.gpu = {
+      percent: clampPercent(best.load),
+      memUsedMB: Math.round(best.bytes / MB),
+      dedicated: (memory.get(best.luid)?.dedicated ?? 0) > 0,
+    };
+  }
+  return result;
+}
+
+const run = (cmd: string, args: string[], timeout = EXEC_TIMEOUT_MS) =>
+  new Promise<string | undefined>((resolve) => {
+    execFile(cmd, args, { timeout, windowsHide: true, maxBuffer: 4 * MB }, (err, stdout) =>
+      resolve(err ? undefined : stdout)
+    );
+  });
+
+const readText = (path: string) =>
+  readFile(path, 'utf8').then(
+    (t) => t.trim(),
+    () => undefined
+  );
+const readNumber = async (path: string) => {
+  const text = await readText(path);
+  return text === undefined ? undefined : finite(Number(text));
+};
+
+/** Linux running under WSL: Windows programs can be started, and the GPU belongs to Windows. */
+let wsl: boolean | undefined;
+function inWsl(): boolean {
+  wsl ??=
+    process.platform === 'linux' &&
+    (Boolean(process.env.WSL_INTEROP) ||
+      existsSync('/proc/sys/fs/binfmt_misc/WSLInterop') ||
+      existsSync('/proc/sys/fs/binfmt_misc/WSLInterop-late'));
+  return wsl;
+}
+
+let windowsRamMB: number | undefined;
+let ramProbe: Promise<void> | undefined;
+let ramRetryAt = 0;
+
+/**
+ * Windows' installed RAM in MB once PowerShell has answered, else undefined. The probe (about a second, 8 s
+ * timeout) is started here but never awaited: the stats route answers CPU and MEM only after the sensors, so
+ * the GPU reading carries the memory in use alone until the answer lands, and the total from then on. A
+ * failure is not retried on every GPU poll: it waits READER_BACKOFF_MS first.
+ */
+function windowsRamMBIfKnown(): number | undefined {
+  if (windowsRamMB !== undefined || ramProbe || Date.now() < ramRetryAt) return windowsRamMB;
+  ramProbe = run(
+    POWERSHELL,
+    ['-NoProfile', '-NonInteractive', '-Command', '(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory'],
+    8000
+  ).then((out) => {
+    const bytes = out ? finite(Number(out.trim())) : undefined;
+    if (bytes && bytes > 0) windowsRamMB = Math.round(bytes / MB);
+    else ramRetryAt = Date.now() + READER_BACKOFF_MS;
+    ramProbe = undefined;
+  });
+  return undefined;
+}
+
+/** What the sampler needs from a child process; `ChildProcess` fits, and tests pass a fake. */
+export type SamplerChild = Pick<ChildProcess, 'stdout' | 'kill' | 'once'>;
+
+export interface CounterStreamOptions {
+  start: (counters: string[]) => SamplerChild;
+  now?: () => number;
+  /**
+   * How long a read waits for a sample when it has none fresh (0, the default, never waits: the read
+   * answers undefined and the next poll shows the reading). The stats route awaits the sensors before it
+   * answers CPU and MEM, so a cold sampler must not hold it up.
+   */
+  firstSampleMs?: number;
+  /** A sampler older than this is replaced, so counters of processes that started since are picked up. */
+  recycleMs?: number;
+  /** A sampler nobody has read for this long is stopped. */
+  idleMs?: number;
+  /** After the sampler fails to start or exits at once, do not try again for this long. */
+  backoffMs?: number;
+}
+
+/**
+ * One long-running `typeperf.exe -si 2` instead of a process per read: every `typeperf` sample takes over a
+ * second (rate counters need two collections), which would keep one running back to back. The newest row is kept
+ * and handed out; the process is replaced every `recycleMs` (its wildcard counters are expanded once, at
+ * start) and stopped after `idleMs` without a read, so nothing runs while the settings are off.
+ */
+export function createCounterStream(options: CounterStreamOptions) {
+  const now = options.now ?? Date.now;
+  const firstSampleMs = options.firstSampleMs ?? 0;
+  const recycleMs = options.recycleMs ?? 30000;
+  const idleMs = options.idleMs ?? 30000;
+  const backoffMs = options.backoffMs ?? 60000;
+  let child: SamplerChild | undefined;
+  let key = '';
+  let startedAt = 0;
+  let lastRead = 0;
+  let blockedUntil = 0;
+  let latest: { at: number; value: WindowsCounters } | undefined;
+  let waiting: Array<() => void> = [];
+
+  const stop = () => {
+    const old = child;
+    child = undefined;
+    if (old) {
+      try {
+        old.kill();
+      } catch {
+        /* already gone */
+      }
+    }
+  };
+
+  const begin = (counters: string[]) => {
+    stop();
+    const nextKey = counters.join('\n');
+    // A sample of other counters is no answer; one from an older sampler of the same counters still is.
+    if (nextKey !== key) latest = undefined;
+    key = nextKey;
+    startedAt = now();
+    // The header row and the partial line belong to this process alone: a late row from a replaced sampler
+    // must never become the next one's header.
+    let header: string | undefined;
+    let buffer = '';
+    let sampled = false;
+    let started: SamplerChild;
+    try {
+      started = options.start(counters);
+    } catch {
+      blockedUntil = now() + backoffMs;
+      return;
+    }
+    child = started;
+    started.stdout?.on('data', (chunk: Buffer | string) => {
+      if (child !== started) return;
+      buffer += chunk.toString();
+      let at: number;
+      while ((at = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, at).replace(/\r$/, '');
+        buffer = buffer.slice(at + 1);
+        if (!line.startsWith('"')) continue;
+        if (!header) {
+          header = line;
+          continue;
+        }
+        sampled = true;
+        latest = { at: now(), value: parseTypeperf(`${header}\n${line}`) };
+        const release = waiting;
+        waiting = [];
+        release.forEach((fn) => fn());
+      }
+    });
+    const ended = () => {
+      if (child !== started) return;
+      child = undefined;
+      // It ended without a sample (typeperf missing, counters unknown): leave it alone for a while.
+      if (!sampled) blockedUntil = now() + backoffMs;
+      const release = waiting;
+      waiting = [];
+      release.forEach((fn) => fn());
+    };
+    started.once('exit', ended);
+    started.once('error', ended);
+  };
+
+  return {
+    /** The newest fresh sample for these counters, or undefined (a cold sampler is not waited for unless `firstSampleMs` says so). */
+    async read(counters: string[]): Promise<WindowsCounters | undefined> {
+      lastRead = now();
+      if (now() < blockedUntil) return undefined;
+      const wanted = counters.join('\n');
+      if (!child || key !== wanted || now() - startedAt > recycleMs) begin(counters);
+      if (!latest || key !== wanted || now() - latest.at >= FRESH_MS) {
+        if (!child) return undefined;
+        if (firstSampleMs > 0) {
+          await new Promise<void>((resolve) => {
+            waiting.push(resolve);
+            setTimeout(resolve, firstSampleMs).unref();
+          });
+        }
+      }
+      return latest && now() - latest.at < FRESH_MS ? latest.value : undefined;
+    },
+    /** Stop the sampler when nobody has read it lately. */
+    sweep() {
+      if (child && now() - lastRead > idleMs) {
+        stop();
+        latest = undefined;
+      }
+    },
+    stop,
+  };
+}
+
+const GPU_COUNTERS = [
+  '\\GPU Engine(*)\\Utilization Percentage',
+  '\\GPU Adapter Memory(*)\\Shared Usage',
+  '\\GPU Adapter Memory(*)\\Dedicated Usage',
+];
+const CPU_COUNTERS = ['\\Processor Information(_Total)\\Processor Frequency'];
+
+/**
+ * The counters one sampler reads. They do not depend on which reading a browser asked for (those are per
+ * device, so two browsers can differ): the CPU clock is always sampled, and the GPU counters are added on a
+ * machine with no native GPU reader (and dropped again once nothing has needed them for a while). A request then only picks its fields from the sample.
+ */
+export function windowsCounterList(needGpu: boolean): string[] {
+  return needGpu ? [...GPU_COUNTERS, ...CPU_COUNTERS] : [...CPU_COUNTERS];
+}
+
+export function createWindowsSource(
+  stream: Pick<ReturnType<typeof createCounterStream>, 'read' | 'stop'>,
+  now: () => number = Date.now
+) {
+  let gpuUntil = 0;
+  return {
+    /**
+     * A GPU reading is wanted and no native reader answered: sample the GPU counters too, for
+     * GPU_COUNTERS_HOLD_MS after the last such read. A single failed nvidia-smi therefore costs a sampler
+     * restart, not a GPU sampler for the life of the server.
+     */
+    needGpuCounters() {
+      gpuUntil = now() + GPU_COUNTERS_HOLD_MS;
+    },
+    read: () => stream.read(windowsCounterList(now() < gpuUntil)),
+    stop: () => stream.stop(),
+  };
+}
+
+const windowsCounters = createCounterStream({
+  // Spawn the Windows program directly: if it is missing, the error lands in the stream's back-off.
+  start: (counters) =>
+    spawn(TYPEPERF, ['-si', '2', ...counters], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }),
+});
+const windowsSource = createWindowsSource(windowsCounters);
+let sweepTimer: ReturnType<typeof setInterval> | undefined;
+
+/** Stop the background sampler and its idle sweep (the server calls this on shutdown). */
+export function stopHostSensors(): void {
+  if (sweepTimer) clearInterval(sweepTimer);
+  sweepTimer = undefined;
+  windowsSource.stop();
+}
+
+async function readAmdGpu(): Promise<GpuReading | undefined> {
+  const cards = (await readdir(SYS_DRM).catch(() => [] as string[])).filter((n) => /^card\d+$/.test(n)).sort();
+  for (const card of cards) {
+    const dev = join(SYS_DRM, card, 'device');
+    const busy = await readNumber(join(dev, 'gpu_busy_percent'));
+    if (busy === undefined) continue;
+    const reading: GpuReading = { percent: clampPercent(busy) };
+    const used = await readNumber(join(dev, 'mem_info_vram_used'));
+    const total = await readNumber(join(dev, 'mem_info_vram_total'));
+    if (used !== undefined && total !== undefined && total > 0) {
+      reading.memUsedMB = Math.round(used / MB);
+      reading.memTotalMB = Math.round(total / MB);
+      reading.memPercent = clampPercent((used / total) * 100);
+    }
+    const sclk = await readText(join(dev, 'pp_dpm_sclk'));
+    const mhz = sclk ? parseDpmClock(sclk) : undefined;
+    if (mhz) reading.mhz = mhz;
+    return reading;
+  }
+  return undefined;
+}
+
+/** nvidia-smi is not run again before this time: it failed or timed out, and waits READER_BACKOFF_MS. */
+let nvidiaSkipUntil = 0;
+
+/** NVIDIA, then AMD. A host without a working nvidia-smi is not asked again on every poll. */
+async function readNativeGpu(): Promise<GpuReading | undefined> {
+  if (Date.now() >= nvidiaSkipUntil) {
+    const out = await run('nvidia-smi', [
+      '--query-gpu=utilization.gpu,memory.used,memory.total,clocks.gr',
+      '--format=csv,noheader,nounits',
+    ]);
+    const reading = out ? parseNvidiaSmi(out) : undefined;
+    if (reading) return reading;
+    nvidiaSkipUntil = Date.now() + READER_BACKOFF_MS;
+  }
+  return readAmdGpu();
+}
+
+/** A GPU reading from the Windows counters (WSL only): load and memory in use, but no clock. */
+function gpuFromWindows(windows: WindowsCounters | undefined): GpuReading | undefined {
+  if (!windows?.gpu) return undefined;
+  const { percent, memUsedMB, dedicated } = windows.gpu;
+  const reading: GpuReading = { percent, memUsedMB };
+  // An integrated GPU draws its memory from system RAM, and Windows lets it use up to half of it. Until
+  // Windows has said how much RAM it has, the reading is the memory in use alone (the header shows no ring).
+  const ram = dedicated ? undefined : windowsRamMBIfKnown();
+  if (ram) {
+    reading.memTotalMB = Math.round(ram / 2);
+    reading.memPercent = clampPercent((memUsedMB / reading.memTotalMB) * 100);
+  }
+  return reading;
+}
+
+async function readCpuMhz(windows: WindowsCounters | undefined): Promise<number | undefined> {
+  // Under WSL the Linux side only has a fixed figure, so until Windows answers there is no reading.
+  if (windows) return windows.cpuMhz;
+  const cores = (await readdir(SYS_CPU).catch(() => [] as string[])).filter((n) => /^cpu\d+$/.test(n));
+  const khz = await Promise.all(cores.map((c) => readNumber(join(SYS_CPU, c, 'cpufreq', 'scaling_cur_freq'))));
+  const fromSysfs = meanKhzAsMhz(khz.filter((v): v is number => v !== undefined));
+  if (fromSysfs) return fromSysfs;
+  const info = await readText('/proc/cpuinfo');
+  return info ? parseCpuInfoMhz(info) : undefined;
+}
+
+const cache = new Map<string, { at: number; value: HostSensors }>();
+const inFlight = new Map<string, Promise<HostSensors>>();
+
+/** Read only what was asked for. Missing sensors are simply absent from the result. */
+export async function readHostSensors(request: SensorRequest): Promise<HostSensors> {
+  const key = `${request.gpu ? 'g' : ''}${request.cpuMhz ? 'c' : ''}`;
+  if (!key) return {};
+  sweepTimer ??= setInterval(() => windowsCounters.sweep(), 10000).unref();
+  const hit = cache.get(key);
+  if (hit && Date.now() - hit.at < CACHE_MS) return hit.value;
+  const running = inFlight.get(key);
+  if (running) return running;
+  const promise = (async () => {
+    // Native GPU readers first: a machine with a working nvidia-smi never starts the GPU counters.
+    const nativeGpu = request.gpu ? await readNativeGpu() : undefined;
+    const wsl = inWsl();
+    const windowsGpu = wsl && request.gpu && !nativeGpu;
+    if (windowsGpu) windowsSource.needGpuCounters();
+    const windows = wsl && (request.cpuMhz || windowsGpu) ? await windowsSource.read() : undefined;
+    const [gpu, cpuMhz] = await Promise.all([
+      request.gpu ? (nativeGpu ?? gpuFromWindows(windows)) : undefined,
+      request.cpuMhz ? readCpuMhz(wsl ? (windows ?? {}) : undefined) : undefined,
+    ]);
+    const value: HostSensors = {};
+    if (gpu) value.gpu = gpu;
+    if (cpuMhz) value.cpuMhz = cpuMhz;
+    cache.set(key, { at: Date.now(), value });
+    return value;
+  })().finally(() => inFlight.delete(key));
+  inFlight.set(key, promise);
+  return promise;
+}

src/web/public/app.js

@@ -2435,8 +2435,6 @@ class CodemanApp {
     if (data.parentSessionId) this.markConnectionLineEntering?.('lineage:' + data.id);
     this.renderSessionTabs();
     this.updateCost();
-    // Start stats polling when first session appears
-    if (this.sessions.size === 1) this.startSystemStatsPolling();
     if (this._urlSessionId === data.id) this._selectUrlSession();
   }
 
@@ -2492,8 +2490,8 @@ class CodemanApp {
     this.renderSessionTabs();
     this.renderRalphStatePanel();  // Update ralph panel after session deleted
     this.renderProjectInsightsPanel();  // Update project insights panel after session deleted
-    // Stop stats polling when no sessions remain
-    if (this.sessions.size === 0) this.stopSystemStatsPolling();
+    // Stats polling keeps going with no session left: the header shows CPU, MEM and the opt-in readings
+    // regardless, and would sit at "--" otherwise.
   }
 
   // SSE wrappers — skip terminal events while WebSocket owns active terminal I/O.
@@ -5064,12 +5062,9 @@ class CodemanApp {
     // survive reloads and SSE reconnects (methods in approvals-ui.js).
     this.seedApprovals?.();
 
-    // Start/stop system stats polling based on session count
-    if (this.sessions.size > 0) {
-      this.startSystemStatsPolling();
-    } else {
-      this.stopSystemStatsPolling();
-    }
+    // Poll the header stats whether or not a session is open (fetchSystemStats skips the call while the
+    // stats pill is hidden); starting restarts the interval, so only start it once.
+    if (!this.systemStatsInterval) this.startSystemStatsPolling();
 
     // CRITICAL: Clean up all floating windows before loading new subagents
     // This prevents memory leaks from ResizeObservers, EventSources, and DOM elements

src/web/public/i18n.js

@@ -451,6 +451,8 @@
     'Header Displays': '顶部栏显示',
     'Font Controls': '字体控制',
     'System Stats': '系统状态',
+    'GPU Stats': 'GPU 状态',
+    'CPU MHz': 'CPU 频率',
     'Lifecycle Log': '生命周期日志',
     'Response Viewer': '回复查看器',
     'Attachments Button': '附件按钮',

src/web/public/index.html

@@ -178,6 +178,30 @@
             </div>
             <span class="stat-value" id="statMem">--</span>
           </div>
+          <div class="stat-item" id="statGpuItem" hidden>
+            <span class="stat-ring" id="statGpuRing" aria-hidden="true"></span>
+            <span class="stat-label">GPU</span>
+            <div class="stat-bar">
+              <div class="stat-bar-fill stat-bar-cpu" id="statGpuBar"></div>
+            </div>
+            <span class="stat-value" id="statGpu">--%</span>
+          </div>
+          <div class="stat-item" id="statVramItem" hidden>
+            <span class="stat-ring" id="statVramRing" aria-hidden="true"></span>
+            <span class="stat-label">VRAM</span>
+            <div class="stat-bar">
+              <div class="stat-bar-fill stat-bar-cpu" id="statVramBar"></div>
+            </div>
+            <span class="stat-value" id="statVram">--%</span>
+          </div>
+          <div class="stat-item" id="statGpuMhzItem" hidden>
+            <span class="stat-label">GPU</span>
+            <span class="stat-value" id="statGpuMhz">-- MHz</span>
+          </div>
+          <div class="stat-item" id="statCpuMhzItem" hidden>
+            <span class="stat-label">CPU</span>
+            <span class="stat-value" id="statCpuMhz">-- MHz</span>
+          </div>
         </div>
         <button class="btn-icon-header btn-redraw-terminal btn-redraw-terminal--hidden" onclick="app.restoreTerminalSize()" title="Redraw terminal to fit current screen (Ctrl+Shift+R)" aria-label="Redraw terminal"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="1 4 1 10 7 10"/><polyline points="23 20 23 14 17 14"/><path d="M20.49 9A9 9 0 0 0 5.64 5.64L1 10m22 4l-4.64 4.36A9 9 0 0 1 3.51 15"/></svg></button>
         <button class="btn-icon-header btn-response-viewer-header btn-response-viewer-header--hidden" onclick="app.toggleResponseViewer()" title="View last response" aria-label="View last response"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg></button>
@@ -2097,6 +2121,8 @@
                   <div class="set-chips" data-search="header buttons plan usage font stats lifecycle response file viewer attachments monitor session away cron redraw split tiles">
                     <label class="set-chip" data-preview="header" data-preview-order="1" data-preview-text="A+"><input type="checkbox" id="appSettingsShowFontControls"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 20 10 5l6 15"/><path d="M6.5 15h7"/><path d="M18 12h4M20 10v4"/></svg><span>Font Size</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="2" data-preview-text="CPU 12%"><input type="checkbox" id="appSettingsShowSystemStats" checked><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 12h4l2.5-7 4 14L16 12h5"/></svg><span>System Stats</span></label>
+                    <label class="set-chip" data-preview="header" data-preview-order="2" data-preview-text="GPU 8%"><input type="checkbox" id="appSettingsShowGpuStats"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="7" width="18" height="10" rx="2"/><path d="M7 21v-4M12 21v-4M17 21v-4M7 7V3M17 7V3"/></svg><span>GPU Stats</span></label>
+                    <label class="set-chip" data-preview="header" data-preview-order="2" data-preview-text="3400 MHz"><input type="checkbox" id="appSettingsShowCpuMhz"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/></svg><span>CPU MHz</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="3"><input type="checkbox" id="appSettingsShowRedrawButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="1 4 1 10 7 10"/><polyline points="23 20 23 14 17 14"/><path d="M20.49 9A9 9 0 0 0 5.64 5.64L1 10m22 4l-4.64 4.36A9 9 0 0 1 3.51 15"/></svg><span>Redraw Terminal</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="4"><input type="checkbox" id="appSettingsShowResponseViewer"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg><span>Response Viewer</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="5"><input type="checkbox" id="appSettingsShowAwayDigestButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 6h13"/><path d="M8 12h13"/><path d="M8 18h13"/><path d="M3 6h.01"/><path d="M3 12h.01"/><path d="M3 18h.01"/></svg><span>Away Digest</span></label>

src/web/public/panels-ui.js

@@ -6859,13 +6859,29 @@ Object.assign(CodemanApp.prototype, {
     // Skip polling when system stats display is hidden
     const statsEl = document.getElementById('headerSystemStats');
     if (!statsEl || statsEl.style.display === 'none') return;
+    // One request at a time: the poll fires every 2 s, and a slow answer (a cold WSL sampler, a hung
+    // server) must not pile up requests behind it.
+    if (this._systemStatsPending) return;
+    this._systemStatsPending = true;
 
     try {
-      const res = await fetch('/api/system/stats');
+      // Opt-in readings are only requested while their header setting is on (default off).
+      const settings = this.loadAppSettingsFromStorage?.() ?? {};
+      const wanted = ['gpu', settings.showGpuStats, 'cpumhz', settings.showCpuMhz];
+      const query = [];
+      for (let i = 0; i < wanted.length; i += 2) if (wanted[i + 1] === true) query.push(`${wanted[i]}=1`);
+      const res = await fetch('/api/system/stats' + (query.length ? '?' + query.join('&') : ''), {
+        signal:
+          typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+            ? AbortSignal.timeout(8000)
+            : undefined,
+      });
       const stats = await res.json();
       this.updateSystemStatsDisplay(stats.data);
     } catch (err) {
       // Silently fail - system stats are not critical
+    } finally {
+      this._systemStatsPending = false;
     }
   },
 
@@ -6910,6 +6926,58 @@ Object.assign(CodemanApp.prototype, {
         memBar.classList.add('medium');
       }
     }
+
+    // After the MEM block, so nothing in the optional readings can stop MEM updating.
+    this._updateHostSensors(stats);
+  },
+
+  /**
+   * The opt-in readings after CPU and MEM: GPU load, GPU memory and GPU clock (the GPU Stats setting) and the CPU clock. An item
+   * shows only while its setting is on AND the host reported it, so a machine without a readable GPU just
+   * has nothing extra in the header.
+   */
+  _updateHostSensors(stats) {
+    const settings = this.loadAppSettingsFromStorage?.() ?? {};
+    const show = (id, visible) => {
+      const el = this.$(id);
+      if (el) el.hidden = !visible;
+    };
+    const fill = (valueId, ringId, barId, percent, text) => {
+      const value = this.$(valueId);
+      if (value) {
+        value.textContent = text;
+        value.classList.toggle('high', percent > 80);
+      }
+      this._setStatRing(ringId, percent);
+      const bar = this.$(barId);
+      if (bar) bar.style.width = `${Math.min(100, percent)}%`;
+    };
+    const gpu = settings.showGpuStats === true ? stats.gpu : undefined;
+    show('statGpuItem', Boolean(gpu));
+    if (gpu) fill('statGpu', 'statGpuRing', 'statGpuBar', gpu.percent, `${gpu.percent}%`);
+    // Graphics memory: the amount in use whenever it is known, with a ring only when the total is too (an
+    // integrated GPU under WSL, where Windows reports usage but the share of RAM is a guess, may have none).
+    show('statVramItem', Boolean(gpu && gpu.memUsedMB !== undefined));
+    if (gpu && gpu.memUsedMB !== undefined) {
+      const used = `${(gpu.memUsedMB / 1024).toFixed(1)}G`;
+      const ring = this.$('statVramRing');
+      if (gpu.memPercent !== undefined) {
+        fill('statVram', 'statVramRing', 'statVramBar', gpu.memPercent, used);
+        if (ring) ring.style.display = '';
+      } else {
+        const vram = this.$('statVram');
+        if (vram) vram.textContent = used;
+        if (ring) ring.style.display = 'none';
+      }
+    }
+    // The GPU clock is a third GPU Stats item (the host may not report one: Windows has none for Intel).
+    show('statGpuMhzItem', Boolean(gpu && gpu.mhz !== undefined));
+    const gpuMhzEl = gpu && gpu.mhz !== undefined ? this.$('statGpuMhz') : null;
+    if (gpuMhzEl) gpuMhzEl.textContent = `${gpu.mhz} MHz`;
+    const cpuMhz = settings.showCpuMhz === true && stats.cpuMhz !== undefined ? stats.cpuMhz : undefined;
+    show('statCpuMhzItem', cpuMhz !== undefined);
+    const cpuMhzEl = cpuMhz !== undefined ? this.$('statCpuMhz') : null;
+    if (cpuMhzEl) cpuMhzEl.textContent = `${cpuMhz} MHz`;
   },
 
   /**

src/web/public/settings-ui.js

@@ -514,6 +514,9 @@ Object.assign(CodemanApp.prototype, {
     // Header visibility settings
     document.getElementById('appSettingsShowFontControls').checked = settings.showFontControls ?? defaults.showFontControls ?? false;
     document.getElementById('appSettingsShowSystemStats').checked = settings.showSystemStats ?? defaults.showSystemStats ?? true;
+    // Opt-in host readings after CPU and MEM: all default OFF.
+    document.getElementById('appSettingsShowGpuStats').checked = settings.showGpuStats ?? defaults.showGpuStats ?? false;
+    document.getElementById('appSettingsShowCpuMhz').checked = settings.showCpuMhz ?? defaults.showCpuMhz ?? false;
     document.getElementById('appSettingsHeaderStatsStyle').value = this.resolveHeaderStatsStyle(settings);
     document.getElementById('appSettingsShowLifecycleLog').checked = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? false;
     document.getElementById('appSettingsShowResponseViewer').checked = settings.showResponseViewer ?? defaults.showResponseViewer ?? false;
@@ -2904,6 +2907,8 @@ Object.assign(CodemanApp.prototype, {
       // Header visibility settings
       showFontControls: document.getElementById('appSettingsShowFontControls').checked,
       showSystemStats: document.getElementById('appSettingsShowSystemStats').checked,
+      showGpuStats: document.getElementById('appSettingsShowGpuStats').checked,
+      showCpuMhz: document.getElementById('appSettingsShowCpuMhz').checked,
       headerStatsStyle: document.getElementById('appSettingsHeaderStatsStyle').value,
       showLifecycleLog: document.getElementById('appSettingsShowLifecycleLog').checked,
       showResponseViewer: document.getElementById('appSettingsShowResponseViewer').checked,
@@ -3234,6 +3239,9 @@ Object.assign(CodemanApp.prototype, {
       showCronButton: _crb,
       // Per-device bottom-bar indicator, absent from SettingsUpdateSchema (.strict()): it must not reach the PUT.
       showGitStatus: _sgs,
+      // Opt-in header readings (GPU Stats, CPU MHz): per-device and absent from the .strict() schema.
+      showGpuStats: _sgp,
+      showCpuMhz: _scm,
       gitStatusTree: _gst,
       gitStatusMaxRepos: _gsm,
       gitStatusTimeoutSeconds: _gst2,
@@ -4113,6 +4121,8 @@ Object.assign(CodemanApp.prototype, {
         // Header visibility - hide everything on mobile
         showFontControls: false,
         showSystemStats: false,
+        showGpuStats: false,
+        showCpuMhz: false,
         showTokenCount: false,
         showCost: false,
         // Panel visibility - hide panels on mobile (not enough space)
@@ -4880,7 +4890,7 @@ Object.assign(CodemanApp.prototype, {
    */
   _displaySettingKeySet() {
     const displayKeys = new Set([
-      'showFontControls', 'showSystemStats', 'headerStatsStyle', 'showTokenCount', 'showCost',
+      'showFontControls', 'showSystemStats', 'showGpuStats', 'showCpuMhz', 'headerStatsStyle', 'showTokenCount', 'showCost',
       'showLifecycleLog', 'showResponseViewer', 'showRedrawButton',
       'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
       'subagentActiveTabOnly', 'tabTwoRows', 'showTabCliLogos', 'tabOrientation', 'tabRailWidth', 'tabRailDetail', 'tabRailSort', 'tabArrangement', 'tabStateOrder', 'sessionListLayout', 'sessionSidebarFontSize', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',

src/web/public/styles.css

@@ -2356,6 +2356,13 @@ body.solo-mode .header-divider {
   }
 }
 
+/* The opt-in host readings (GPU, VRAM, MHz) start hidden and are shown by panels-ui.js once the host
+   reports them; a plain `display` on .stat-item would override the attribute, and the Tiles style sets its own
+   (a grid) at a higher specificity, so the selector carries the style attribute to outrank it. */
+html[data-header-stats] .header-system-stats .stat-item[hidden] {
+  display: none;
+}
+
 /* Connection Indicator */
 .connection-indicator {
   display: flex;

src/web/routes/system-routes.ts

@@ -13,6 +13,7 @@ import { totalmem, freemem, loadavg, cpus } from 'node:os';
 import { execSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { dataPath } from '../../config/instance.js';
+import { readHostSensors } from '../../host-sensors.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage, type NiceConfig } from '../../types.js';
 import { isUnauthenticatedNetworkAcknowledged } from '../network-auth-policy.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
@@ -1007,8 +1008,15 @@ export function registerSystemRoutes(
 
   // ========== System Stats ==========
 
-  app.get('/api/system/stats', async () => {
-    return getSystemStats();
+  // GPU (load, memory, clock) and CPU clock readings are opt-in: the browser adds ?gpu=1 and ?cpumhz=1 only while
+  // the matching header setting is on, so a default install never runs nvidia-smi or reads sysfs.
+  app.get('/api/system/stats', async (req) => {
+    const query = req.query as { gpu?: string; cpumhz?: string };
+    const sensors = await readHostSensors({
+      gpu: query.gpu === '1',
+      cpuMhz: query.cpumhz === '1',
+    });
+    return { ...getSystemStats(), ...sensors };
   });
 
   // ========== Settings ==========

src/web/server.ts

@@ -45,6 +45,7 @@ import { looksLikeHostReboot, newestPersistedActivity, planRebootRestore } from
 import { rebootRestoreRegistry } from './reboot-restore-registry.js';
 import { dataPath, getDataDir, CODEMAN_INSTANCE } from '../config/instance.js';
 import { WebhookNotifier, readWebhookConfig } from '../webhook-notify.js';
+import { stopHostSensors } from '../host-sensors.js';
 import type { WebhookUrgency } from '../types/push.js';
 import { webviewFetch } from './webview-egress.js';
 import { readRemoteHosts, rehydrateRemoteHostFields } from '../remote-hosts.js';
@@ -4175,6 +4176,9 @@ export class WebServer extends EventEmitter {
     // got wrong once.
     void stopDeepSeekWeb();
 
+    // The header's GPU / CPU clock sampler is a Windows child process under WSL, and its idle sweep a timer.
+    stopHostSensors();
+
     // Same teardown rule: the per-endpoint llama-swap log tails are otherwise closed
     // only by the periodic idle sweep, whose interval is disposed just below.
     closeAllLlamaSwapLogTails();