@hienlh/ppm 0.18.8 → 0.18.9

package/src/services/system-metrics/process-cpu-delta.ts

@@ -0,0 +1,61 @@
+/**
+ * Instantaneous per-process CPU% from cumulative CPU time, shared by all OSes.
+ *
+ * Every OS's "CPU%" column is a lifetime average (`ps %cpu`, `/proc` utime over
+ * elapsed) — exactly why the old sparkline was a flat line. Machine-normalised
+ * like Task Manager: `deltaCpuMs / (wallMs × coreCount) × 100`, so a busy single
+ * thread on a 20-core box reads 5 % and group roll-ups sum to roughly the
+ * system total.
+ */
+
+export interface CpuTimeSample {
+  /** `${pid}:${startedAt}` — the same pid with a new start time is a new
+   *  process and gets a fresh baseline. `${pid}:0` when the start is unknown,
+   *  an accepted hole that mis-attributes at most one tick. */
+  key: string;
+  cpuMs: number;
+}
+
+export interface CpuDeltaState {
+  at: number;
+  byKey: Map<string, number>;
+}
+
+export function cpuSampleKey(pid: number, startedAt: number): string {
+  return `${pid}:${startedAt}`;
+}
+
+const round1 = (n: number): number => Math.round(n * 10) / 10;
+
+/**
+ * Unknown key → 0 (a first observation is never a guess). Counter going
+ * backwards → 0 and the baseline is reset. Dead keys are dropped from `next`
+ * every tick so a long session cannot grow the map without bound.
+ */
+export function computeCpuPercents(
+  prev: CpuDeltaState | null,
+  samples: readonly CpuTimeSample[],
+  now: number,
+  coreCount: number,
+): { percentByKey: Map<string, number>; next: CpuDeltaState } {
+  const percentByKey = new Map<string, number>();
+  const nextByKey = new Map<string, number>();
+  const wallMs = prev ? now - prev.at : 0;
+  const cores = Math.max(1, coreCount);
+  const usable = prev !== null && wallMs > 0;
+
+  for (const s of samples) {
+    nextByKey.set(s.key, s.cpuMs);
+    let pct = 0;
+    if (usable) {
+      const before = prev!.byKey.get(s.key);
+      if (before !== undefined) {
+        const delta = s.cpuMs - before;
+        if (delta >= 0) pct = round1(Math.min(100, (delta / (wallMs * cores)) * 100));
+      }
+    }
+    percentByKey.set(s.key, pct);
+  }
+
+  return { percentByKey, next: { at: now, byKey: nextByKey } };
+}

package/src/services/system-metrics/process-grouping.ts

@@ -0,0 +1,142 @@
+/**
+ * App grouping: roll every process up to its nearest ancestor below an OS
+ * "shell/service boundary", so Chrome is one row with 40 children and a
+ * terminal is one row with its shells. Exe-name grouping survives only as the
+ * bucket for orphans — it would merge every unrelated `node` on the machine
+ * into one row, which is worse than Task Manager.
+ */
+import type { MetricsPlatform, ProcessGroup, ProcessInfo } from "../../types/system-metrics.ts";
+
+/** Names are extension-free per the contract, so one literal matches every OS. */
+const WIN32_BOUNDARY_NAMES: ReadonlySet<string> = new Set([
+  "services", "svchost", "explorer", "wininit", "winlogon", "csrss", "userinit", "smss",
+]);
+const POSIX_BOUNDARY_NAMES: ReadonlySet<string> = new Set(["launchd", "systemd", "init"]);
+
+const round1 = (n: number): number => Math.round(n * 10) / 10;
+
+/** The optional per-process columns, which roll up by summation. */
+type OptionalMetric = "diskReadBps" | "diskWriteBps" | "gpuPct" | "gpuMemMB" | "netInBps" | "netOutBps";
+
+/**
+ * Sum over the members that HAVE a value; `undefined` when none does, so a
+ * group on a host that cannot measure a column stays "—" instead of claiming a
+ * confident 0. A member without a value contributes nothing rather than
+ * suppressing its siblings' figures — on Linux that is the common case (an
+ * access-denied `/proc/<pid>/io` next to readable ones).
+ */
+function sumOptional(procs: readonly ProcessInfo[], field: OptionalMetric): number | undefined {
+  let total = 0;
+  let measured = false;
+  for (const p of procs) {
+    const v = p[field];
+    if (typeof v === "number" && Number.isFinite(v)) {
+      total += v;
+      measured = true;
+    }
+  }
+  if (!measured) return undefined;
+  // A group's engine busy is still a share of one GPU, so it cannot exceed 100 %.
+  return round1(field === "gpuPct" ? Math.min(100, total) : total);
+}
+
+function isBoundary(p: ProcessInfo, platform: MetricsPlatform): boolean {
+  const name = p.name.toLowerCase();
+  if (platform === "win32") return p.pid === 0 || p.pid === 4 || WIN32_BOUNDARY_NAMES.has(name);
+  return p.pid <= 1 || POSIX_BOUNDARY_NAMES.has(name);
+}
+
+/**
+ * Climb `ppid` until the parent is absent, is a boundary, or started AFTER the
+ * child (Windows never clears a dead parent's ppid, so a recycled pid would
+ * otherwise adopt an unrelated subtree). Returns the chain from `p` upward.
+ */
+function ancestorChain(p: ProcessInfo, byPid: ReadonlyMap<number, ProcessInfo>, platform: MetricsPlatform): ProcessInfo[] {
+  const chain = [p];
+  const visited = new Set<number>([p.pid]);
+  let cur = p;
+  while (true) {
+    const parent = byPid.get(cur.ppid);
+    if (!parent || visited.has(parent.pid) || isBoundary(parent, platform)) break;
+    if (parent.startedAt && cur.startedAt && parent.startedAt > cur.startedAt) break;
+    visited.add(parent.pid);
+    chain.push(parent);
+    cur = parent;
+  }
+  return chain;
+}
+
+/**
+ * The PPM subtree always splits out of whatever shell chain launched it: on a
+ * dev host that chain is explorer → WindowsTerminal → bun → server, and without
+ * this rule PPM would roll up under "WindowsTerminal" and hand the UI a tree-kill
+ * button whose blast radius includes the server. The topmost PPM root in the
+ * chain wins so supervisor + server + children form ONE group.
+ */
+function resolveRoot(chain: ProcessInfo[], ppmRoots: ReadonlySet<number>): ProcessInfo {
+  for (let i = chain.length - 1; i >= 0; i--) {
+    if (ppmRoots.has(chain[i]!.pid)) return chain[i]!;
+  }
+  return chain[chain.length - 1]!;
+}
+
+/**
+ * @param ppmRoots  PPM's own roots (server + supervisor/parent): grouping boundaries.
+ * @param selfPid   This server's pid. Two PPM instances can share a machine (dev
+ *                  beside prod), so a PPM group is labelled by which one it is.
+ */
+export function groupProcesses(
+  procs: readonly ProcessInfo[],
+  platform: MetricsPlatform,
+  ppmRoots: ReadonlySet<number> = new Set(),
+  selfPid: number = -1,
+): ProcessGroup[] {
+  const byPid = new Map<number, ProcessInfo>();
+  for (const p of procs) byPid.set(p.pid, p);
+
+  const members = new Map<string, { label: string; rootPid: number | null; procs: ProcessInfo[] }>();
+  for (const p of procs) {
+    let key: string;
+    let label: string;
+    let rootPid: number | null;
+    if (p.ppid === -1) {
+      key = `exe:${p.name.toLowerCase()}`;
+      label = p.name;
+      rootPid = null;
+    } else {
+      const root = resolveRoot(ancestorChain(p, byPid, platform), ppmRoots);
+      key = `root:${root.pid}`;
+      label = ppmRoots.has(root.pid) ? `PPM (pid ${root.pid})` : root.name;
+      rootPid = root.pid;
+    }
+    const g = members.get(key);
+    if (g) g.procs.push(p);
+    else members.set(key, { label, rootPid, procs: [p] });
+  }
+
+  const groups: ProcessGroup[] = [];
+  for (const [key, g] of members) {
+    if (g.rootPid !== null && ppmRoots.has(g.rootPid) && g.procs.some((p) => p.pid === selfPid)) {
+      g.label = "PPM (this server)";
+    }
+    g.procs.sort((a, b) => b.cpu - a.cpu || b.ramMB - a.ramMB || a.pid - b.pid);
+    groups.push({
+      key,
+      label: g.label,
+      rootPid: g.rootPid,
+      cpu: round1(g.procs.reduce((s, p) => s + p.cpu, 0)),
+      ramMB: round1(g.procs.reduce((s, p) => s + p.ramMB, 0)),
+      count: g.procs.length,
+      ppm: g.procs.some((p) => p.ppm),
+      pids: g.procs.map((p) => p.pid),
+      diskReadBps: sumOptional(g.procs, "diskReadBps"),
+      diskWriteBps: sumOptional(g.procs, "diskWriteBps"),
+      gpuPct: sumOptional(g.procs, "gpuPct"),
+      gpuMemMB: sumOptional(g.procs, "gpuMemMB"),
+      netInBps: sumOptional(g.procs, "netInBps"),
+      netOutBps: sumOptional(g.procs, "netOutBps"),
+    });
+  }
+  groups.sort((a, b) => b.cpu - a.cpu || b.ramMB - a.ramMB || a.label.localeCompare(b.label));
+  return groups;
+}

package/src/services/system-metrics/process-io-delta.ts

@@ -0,0 +1,84 @@
+/**
+ * Per-process cumulative byte counters → bytes/second, shared by every OS.
+ *
+ * The whole-machine helper in `rate-delta.ts` cannot serve here: it works on a
+ * counter's OWN clock and corrects 32-bit wraps, whereas these counters are
+ * 64-bit per-process totals sampled on the tick's wall clock. So the identity
+ * rules are the same as the CPU delta's (`pid:startedAt` key, first observation
+ * is 0, dead keys dropped) and only the units differ.
+ *
+ * `undefined` in, `undefined` out: a field the OS refused (an access-denied
+ * `/proc/<pid>/io`, a Windows property that came back empty) must never become
+ * a confident 0.
+ */
+
+export interface ProcIoCounters {
+  diskReadBytes?: number;
+  diskWriteBytes?: number;
+  netInBytes?: number;
+  netOutBytes?: number;
+}
+
+export interface ProcIoSample extends ProcIoCounters {
+  /** `${pid}:${startedAt}` — see `cpuSampleKey`. */
+  key: string;
+}
+
+export interface ProcIoRates {
+  diskReadBps?: number;
+  diskWriteBps?: number;
+  netInBps?: number;
+  netOutBps?: number;
+}
+
+export interface ProcIoDeltaState {
+  at: number;
+  byKey: Map<string, ProcIoCounters>;
+}
+
+/** Faster than any bus this code will meet; a delta implying more is a counter
+ *  reset the OS did not flag, not a transfer. */
+const MAX_PLAUSIBLE_BPS = 100 * 1024 ** 3;
+
+export function computeProcIoRates(
+  prev: ProcIoDeltaState | null,
+  samples: readonly ProcIoSample[],
+  now: number,
+): { ratesByKey: Map<string, ProcIoRates>; next: ProcIoDeltaState } {
+  const ratesByKey = new Map<string, ProcIoRates>();
+  const nextByKey = new Map<string, ProcIoCounters>();
+  const wallSec = prev ? (now - prev.at) / 1000 : 0;
+  const usable = prev !== null && wallSec > 0;
+
+  for (const s of samples) {
+    const counters: ProcIoCounters = {
+      diskReadBytes: s.diskReadBytes,
+      diskWriteBytes: s.diskWriteBytes,
+      netInBytes: s.netInBytes,
+      netOutBytes: s.netOutBytes,
+    };
+    nextByKey.set(s.key, counters);
+    const before = usable ? prev!.byKey.get(s.key) : undefined;
+    ratesByKey.set(s.key, {
+      diskReadBps: bps(before?.diskReadBytes, s.diskReadBytes, wallSec),
+      diskWriteBps: bps(before?.diskWriteBytes, s.diskWriteBytes, wallSec),
+      netInBps: bps(before?.netInBytes, s.netInBytes, wallSec),
+      netOutBps: bps(before?.netOutBytes, s.netOutBytes, wallSec),
+    });
+  }
+
+  return { ratesByKey, next: { at: now, byKey: nextByKey } };
+}
+
+/**
+ * - counter not reported → `undefined` (unmeasurable, the UI shows "—")
+ * - no baseline yet, or the counter went backwards → 0
+ */
+function bps(before: number | undefined, current: number | undefined, wallSec: number): number | undefined {
+  if (current === undefined || !Number.isFinite(current)) return undefined;
+  if (before === undefined || wallSec <= 0) return 0;
+  const delta = current - before;
+  if (!Number.isFinite(delta) || delta <= 0) return 0;
+  const rate = Math.round(delta / wallSec);
+  return rate > MAX_PLAUSIBLE_BPS ? 0 : rate;
+}

package/src/services/system-metrics/process-io-linux.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-process disk bytes on Linux from `/proc/<pid>/io` — no subprocess.
+ *
+ * `read_bytes`/`write_bytes` are the counters that actually reached the block
+ * layer, which is what a Task-Manager "Disk" column means; `rchar`/`wchar`
+ * would also count page-cache hits and make every process look busy.
+ *
+ * The file is PTRACE_MODE_READ-protected, so unprivileged PPM sees it only for
+ * its own uid: an EACCES is the NORMAL case for other users' processes and must
+ * leave those rows unmeasured (`undefined`) rather than 0 or an exception.
+ */
+import { readFileSync } from "node:fs";
+
+export interface ProcIoBytes {
+  readBytes: number;
+  writeBytes: number;
+}
+
+const FIELD = /^(read_bytes|write_bytes):\s+(\d+)$/;
+
+/** Null when neither counter is present (a kernel thread reports zeros only in
+ *  some kernels, and a truncated read must not be guessed at). */
+export function parseProcIo(text: string): ProcIoBytes | null {
+  let read: number | undefined;
+  let write: number | undefined;
+  for (const line of text.split("\n")) {
+    const m = FIELD.exec(line.trim());
+    if (!m) continue;
+    const value = Number(m[2]);
+    if (!Number.isFinite(value)) continue;
+    if (m[1] === "read_bytes") read = value;
+    else write = value;
+  }
+  if (read === undefined && write === undefined) return null;
+  return { readBytes: read ?? 0, writeBytes: write ?? 0 };
+}
+
+/** Null on EACCES (another user's process), ENOENT (exited between readdir and
+ *  read) or an unparseable file. Never throws. */
+export function readProcIoBytes(pid: number): ProcIoBytes | null {
+  try {
+    return parseProcIo(readFileSync(`/proc/${pid}/io`, "utf-8"));
+  } catch {
+    return null;
+  }
+}

package/src/services/system-metrics/process-net-collector-darwin.ts

@@ -0,0 +1,103 @@
+/**
+ * Per-process network bytes on macOS via `nettop`. This is the ONLY mainstream
+ * OS with an unprivileged per-process network source: Windows needs an ETW
+ * session and Linux needs packet capture, so both leave the Net column hidden.
+ *
+ *   nettop -P -x -L 1 -J bytes_in,bytes_out
+ *     -P  aggregate per process instead of per connection
+ *     -x  raw byte counts, no "1.2M" suffixes
+ *     -L 1  one CSV sample, then exit (no interactive curses mode)
+ *     -J  emit only these two columns
+ *
+ * The CSV shape varies between macOS releases (a leading timestamp column comes
+ * and goes), so the parser hunts for the `<name>.<pid>` cell and takes the next
+ * two numeric cells rather than trusting fixed column indexes.
+ *
+ * UNVERIFIED on real macOS hardware — fixture-driven only.
+ */
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+
+export const NETTOP_ARGV = ["nettop", "-P", "-x", "-L", "1", "-J", "bytes_in,bytes_out"];
+const NETTOP_TIMEOUT_MS = 5000;
+
+export interface ProcNetBytes {
+  inBytes: number;
+  outBytes: number;
+}
+
+/** `<process name>.<pid>` — the name may itself contain dots
+ *  ("com.apple.WebKit.Networking.431"), so the pid is the LAST segment. The
+ *  name must contain a letter: the leading timestamp cell some macOS releases
+ *  emit ("14:33:05.976") is otherwise a perfect match and would invent a pid
+ *  out of the fractional seconds. */
+const NAME_PID_CELL = /^(.+)\.(\d+)$/;
+const NUMERIC_CELL = /^\d+$/;
+
+function pidCell(cell: string): number | null {
+  const m = NAME_PID_CELL.exec(cell);
+  if (!m || !/[A-Za-z]/.test(m[1]!)) return null;
+  const pid = Number(m[2]);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+export function parseNettopCsv(text: string): Map<number, ProcNetBytes> {
+  const byPid = new Map<number, ProcNetBytes>();
+  for (const line of text.split("\n")) {
+    const cells = line.split(",").map((c) => c.trim());
+    const at = cells.findIndex((c) => pidCell(c) !== null);
+    if (at < 0) continue;
+    const pid = pidCell(cells[at]!)!;
+    const numbers = cells.slice(at + 1).filter((c) => NUMERIC_CELL.test(c));
+    if (numbers.length < 2) continue;
+    const inBytes = Number(numbers[0]);
+    const outBytes = Number(numbers[1]);
+    if (!Number.isFinite(inBytes) || !Number.isFinite(outBytes)) continue;
+    // A pid can appear twice when nettop splits interfaces; sum them.
+    const prev = byPid.get(pid);
+    byPid.set(pid, {
+      inBytes: (prev?.inBytes ?? 0) + inBytes,
+      outBytes: (prev?.outBytes ?? 0) + outBytes,
+    });
+  }
+  return byPid;
+}
+
+export interface ProcessNetCollector {
+  /** Null when the sample failed — the rows then carry no net figures at all
+   *  rather than a fabricated 0. */
+  collect(): Promise<Map<number, ProcNetBytes> | null>;
+  isDisabled(): boolean;
+}
+
+const MAX_FAILURES = 3;
+
+export function createDarwinProcessNetCollector(
+  run: Runner = defaultRunner,
+  log: (message: string) => void = (m) => console.log(m),
+): ProcessNetCollector {
+  let failures = 0;
+  let disabled = false;
+  let logged = false;
+  return {
+    isDisabled: () => disabled,
+    async collect() {
+      if (disabled) return null;
+      const startedAt = Date.now();
+      try {
+        const r = await run(NETTOP_ARGV, NETTOP_TIMEOUT_MS);
+        if (r.code !== 0 || r.timedOut) throw new Error(r.stderr || `exit ${r.code}`);
+        failures = 0;
+        if (!logged) {
+          logged = true;
+          // The 2 s tick budget is what breaks first if nettop turns out slow.
+          log(`[system-metrics] nettop sample: ${Date.now() - startedAt} ms`);
+        }
+        return parseNettopCsv(r.stdout);
+      } catch {
+        if (++failures >= MAX_FAILURES) disabled = true;
+        return null;
+      }
+    },
+  };
+}

package/src/services/system-metrics/process-rows-builder.ts

@@ -0,0 +1,111 @@
+/**
+ * Raw collector rows → `ProcessInfo[]` for one tick: instantaneous CPU%, the
+ * cosmetic `ppm` flag, the guard-derived `protected` flag and a redacted,
+ * truncated command line.
+ */
+import type { MetricsPlatform, ProcessInfo } from "../../types/system-metrics.ts";
+import { redactSecrets } from "../redact-secrets.ts";
+import type { RawProcessRow } from "./process-collector-types.ts";
+import { computeCpuPercents, cpuSampleKey, type CpuDeltaState } from "./process-cpu-delta.ts";
+import { computeProcIoRates, type ProcIoDeltaState } from "./process-io-delta.ts";
+import { checkKillAllowed, type KillGuardContext } from "./kill-guard.ts";
+import { buildGuardMaps, type GuardMaps } from "./kill-identity-resolver.ts";
+import { computePpmPids } from "./ppm-process-ownership.ts";
+import type { ProtectedPids } from "./ppm-protected-pids.ts";
+
+/** Command lines are for recognising a process, not for archiving it. A 400-row
+ *  frame measured ~120 KB at 300 chars; 160 keeps it recognisable in a table
+ *  column while cutting roughly a quarter of every 2 s frame over the tunnel. */
+export const COMMAND_MAX_CHARS = 160;
+
+export interface BuildRowsInput {
+  rows: readonly RawProcessRow[];
+  platform: MetricsPlatform;
+  coreCount: number;
+  now: number;
+  prevCpu: CpuDeltaState | null;
+  prevIo: ProcIoDeltaState | null;
+  /** Resolved against THIS tick's rows, so liveness means "present in the table". */
+  resolveProtected: (isAlive: (pid: number) => boolean, nameOf: (pid: number) => string | undefined) => ProtectedPids;
+}
+
+export interface BuiltRows {
+  processes: ProcessInfo[];
+  nextCpu: CpuDeltaState;
+  nextIo: ProcIoDeltaState;
+  guardCtx: KillGuardContext;
+  protectedPids: ProtectedPids;
+  maps: GuardMaps;
+}
+
+/** Redact first, truncate second: secrets live at the front of argv. */
+export function sanitizeCommand(command: string | null, fallback: string): string {
+  if (!command) return fallback;
+  const redacted = redactSecrets(command);
+  return redacted.length > COMMAND_MAX_CHARS ? redacted.slice(0, COMMAND_MAX_CHARS) : redacted;
+}
+
+export function buildProcessRows(input: BuildRowsInput): BuiltRows {
+  const { platform } = input;
+  const maps = buildGuardMaps(input.rows);
+  // Only the de-duplicated rows are trusted from here on.
+  const rows = [...maps.byPid.values()];
+  const protectedPids = input.resolveProtected(
+    (pid) => maps.byPid.has(pid),
+    (pid) => maps.byPid.get(pid)?.name.toLowerCase(),
+  );
+  const guardCtx: KillGuardContext = {
+    platform,
+    protectedPids: protectedPids.pids,
+    ppidOf: maps.ppidOf,
+    startedAtOf: maps.startedAtOf,
+  };
+  const ppmPids = computePpmPids({
+    roots: protectedPids.roots,
+    extraPids: [...protectedPids.pids],
+    ppidOf: maps.ppidOf,
+    startedAtOf: maps.startedAtOf,
+  });
+
+  const samples = rows.map((r) => ({ key: cpuSampleKey(r.pid, r.startedAt), cpuMs: r.cpuMs }));
+  const { percentByKey, next } = computeCpuPercents(input.prevCpu, samples, input.now, input.coreCount);
+  // Same key and the same wall interval as the CPU delta, so a row's CPU% and
+  // its Bps figures can never describe two different spans of time.
+  const io = computeProcIoRates(
+    input.prevIo,
+    rows.map((r) => ({
+      key: cpuSampleKey(r.pid, r.startedAt),
+      diskReadBytes: r.diskReadBytes,
+      diskWriteBytes: r.diskWriteBytes,
+      netInBytes: r.netInBytes,
+      netOutBytes: r.netOutBytes,
+    })),
+    input.now,
+  );
+
+  const processes: ProcessInfo[] = rows.map((r) => {
+    const key = cpuSampleKey(r.pid, r.startedAt);
+    const rates = io.ratesByKey.get(key);
+    return {
+      pid: r.pid,
+      ppid: r.ppid,
+      name: r.name,
+      command: sanitizeCommand(r.command, r.name),
+      cpu: percentByKey.get(key) ?? 0,
+      ramMB: Math.round(r.ramMB * 10) / 10,
+      startedAt: r.startedAt,
+      ppm: ppmPids.has(r.pid),
+      protected: !checkKillAllowed({ pid: r.pid, name: r.name }, false, guardCtx).allowed,
+      // Left undefined (and therefore absent from the JSON frame) whenever the
+      // OS gave nothing for that counter.
+      diskReadBps: rates?.diskReadBps,
+      diskWriteBps: rates?.diskWriteBps,
+      netInBps: rates?.netInBps,
+      netOutBps: rates?.netOutBps,
+      gpuPct: r.gpuPct,
+      gpuMemMB: r.gpuMemMB,
+    };
+  });
+
+  return { processes, nextCpu: next, nextIo: io.next, guardCtx, protectedPids, maps };
+}

package/src/services/system-metrics/rate-delta.ts

@@ -0,0 +1,47 @@
+/**
+ * Cumulative byte counters → bytes/second. Disk and net are the same problem
+ * twice, so one helper serves both.
+ */
+import type { RateMetrics } from "../../types/system-metrics.ts";
+
+export interface CounterSample {
+  inBytes: number;
+  outBytes: number;
+  /** The counter's OWN clock, in seconds — never `Date.now()` when the source
+   *  carries a timestamp, because the tick's scheduling jitter (a Windows CIM
+   *  round trip alone is ~174 ms and can slip) would otherwise leak into the rate. */
+  atSec: number;
+}
+
+const UINT32 = 2 ** 32;
+/** Faster than any bus this code will meet; a corrected wrap that lands above
+ *  it is a counter reset, not a transfer. */
+const MAX_PLAUSIBLE_BPS = 100 * 1024 ** 3;
+
+export const UNAVAILABLE_RATE: RateMetrics = { inBps: 0, outBps: 0, available: false };
+
+/**
+ * - first sample → `available:false` (no baseline)
+ * - non-positive interval → `available:false`
+ * - negative delta → retry with +2^32 (`BytesReceivedPersec` is a 32-bit counter
+ *   that wraps roughly every 34 s of sustained gigabit); accept only when the
+ *   corrected rate is physically plausible, else `available:false`
+ */
+export function toRate(prev: CounterSample | null, next: CounterSample): RateMetrics {
+  if (!prev) return UNAVAILABLE_RATE;
+  const dt = next.atSec - prev.atSec;
+  if (!Number.isFinite(dt) || dt <= 0) return UNAVAILABLE_RATE;
+
+  const inBps = deltaRate(next.inBytes - prev.inBytes, dt);
+  const outBps = deltaRate(next.outBytes - prev.outBytes, dt);
+  if (inBps === null || outBps === null) return UNAVAILABLE_RATE;
+  return { inBps, outBps, available: true };
+}
+
+function deltaRate(delta: number, dtSec: number): number | null {
+  if (!Number.isFinite(delta)) return null;
+  const corrected = delta < 0 ? delta + UINT32 : delta;
+  if (corrected < 0) return null;
+  const bps = Math.round(corrected / dtSec);
+  return bps > MAX_PLAUSIBLE_BPS ? null : bps;
+}

package/src/services/system-metrics/system-metrics-platform.ts

@@ -0,0 +1,51 @@
+/** Per-OS collector wiring for the snapshot service. Nothing here spawns until
+ *  a full-tier tick actually calls a collector. */
+import type { MetricsPlatform } from "../../types/system-metrics.ts";
+import type { ProcessCollector } from "./process-collector-types.ts";
+import { EMPTY_PROCESS_COLLECTOR } from "./process-collector-types.ts";
+import type { DiskNetCounters } from "./disk-net-collector-linux.ts";
+import { collectLinuxDiskNet } from "./disk-net-collector-linux.ts";
+import { collectDarwinDiskNet } from "./disk-net-collector-darwin.ts";
+import { createNvidiaGpuCollector, type GpuCollector } from "./gpu-collector-nvidia.ts";
+import { createNvidiaProcessMemoryCollector } from "./gpu-process-memory-nvidia.ts";
+import { createLinuxProcessCollector } from "./process-collector-linux.ts";
+import { createDarwinProcessCollector } from "./process-collector-darwin.ts";
+import { createDarwinProcessNetCollector } from "./process-net-collector-darwin.ts";
+import { createWindowsProcessCollector } from "./process-collector-windows.ts";
+import { readProcTable } from "../proc-table-linux.ts";
+
+export interface PlatformCollectors {
+  platform: MetricsPlatform;
+  processes: ProcessCollector;
+  /** Null on win32: the counters ride along in the process round trip. */
+  diskNet: (() => Promise<DiskNetCounters>) | null;
+  gpus: GpuCollector;
+}
+
+export function toMetricsPlatform(p: NodeJS.Platform = process.platform): MetricsPlatform {
+  return p === "win32" || p === "darwin" ? p : "linux";
+}
+
+export function createPlatformCollectors(platform: MetricsPlatform = toMetricsPlatform()): PlatformCollectors {
+  const gpus = createNvidiaGpuCollector();
+  switch (platform) {
+    case "win32":
+      return { platform, processes: createWindowsProcessCollector(), diskNet: null, gpus };
+    case "darwin":
+      return {
+        platform,
+        processes: createDarwinProcessCollector(undefined, undefined, { net: createDarwinProcessNetCollector() }),
+        diskNet: () => collectDarwinDiskNet(),
+        gpus,
+      };
+    case "linux":
+      return {
+        platform,
+        processes: createLinuxProcessCollector(readProcTable, { gpuMemory: createNvidiaProcessMemoryCollector() }),
+        diskNet: async () => collectLinuxDiskNet(),
+        gpus,
+      };
+    default:
+      return { platform, processes: EMPTY_PROCESS_COLLECTOR, diskNet: null, gpus };
+  }
+}