@hienlh/ppm 0.18.7 → 0.18.9

package/src/services/system-metrics/process-collector-windows-parse.ts

@@ -0,0 +1,153 @@
+/**
+ * Zero-IO parser for the tagged, tab-separated lines one Windows tick returns:
+ *
+ *   P<TAB>pid<TAB>ppid<TAB>Name<TAB>KernelModeTime<TAB>UserModeTime<TAB>WorkingSetSize<TAB>CreationDateUtcTicks<TAB>ReadTransferCount<TAB>WriteTransferCount
+ *   C<TAB>pid<TAB>CreationDateUtcTicks<TAB>CommandLine            (every 30 s only)
+ *   D… / N…                                                       (disk/net counters)
+ *   G… / M…                                                       (per-process GPU)
+ *   __ERR__ <message>                                             (a failed block)
+ *
+ * `CommandLine` is always the LAST field and may itself contain tabs, so rows
+ * are split with a field limit — a naive `split("\t")` corrupts them.
+ *
+ * The two transfer counts are appended AFTER the creation ticks so a `P` row
+ * from an older shape (or a host where the properties are empty) still parses,
+ * it just reports no disk figures.
+ */
+import { parsePerfRawDiskNet } from "./disk-net-collector-windows.ts";
+import { parseGpuLines, type ParsedGpuLines } from "./gpu-process-usage-windows.ts";
+import type { CounterSample } from "./rate-delta.ts";
+import { stripExecutableExtension, type RawProcessRow } from "./process-collector-types.ts";
+
+export interface WindowsCommandLine {
+  pid: number;
+  startedAt: number;
+  command: string;
+}
+
+export interface ParsedWindowsTick {
+  /** PID 0 (System Idle Process) is excluded — its kernel time is idle time and
+   *  inflates a naive CPU roll-up to ~99 %. */
+  processes: RawProcessRow[];
+  /** Null when the tick carried no `C` section. */
+  commands: WindowsCommandLine[] | null;
+  disk: CounterSample | null;
+  net: CounterSample | null;
+  /** Raw per-process GPU samples; the collector turns them into rates. */
+  gpu: ParsedGpuLines;
+  errors: string[];
+}
+
+/** .NET ticks (100 ns since 0001-01-01) → Unix epoch ms. Input MUST already be
+ *  UTC — the query calls `.ToUniversalTime()` because only .NET on that machine
+ *  knows the DST rule in force when the process started. BigInt because the
+ *  tick value exceeds 2^53. */
+export function ticksToEpochMs(ticks: string): number {
+  if (!/^\d+$/.test(ticks)) return 0;
+  const EPOCH_TICKS = 621355968000000000n;
+  const ms = (BigInt(ticks) - EPOCH_TICKS) / 10000n;
+  return ms > 0n ? Number(ms) : 0;
+}
+
+/** Split into at most `limit` fields; the remainder stays glued to the last one. */
+export function splitLimited(line: string, limit: number): string[] {
+  const out: string[] = [];
+  let start = 0;
+  while (out.length < limit - 1) {
+    const i = line.indexOf("\t", start);
+    if (i < 0) break;
+    out.push(line.slice(start, i));
+    start = i + 1;
+  }
+  out.push(line.slice(start));
+  return out;
+}
+
+const HUNDRED_NS_PER_MS = 10_000;
+const BYTES_PER_MB = 1024 * 1024;
+
+/** An empty (property absent / access denied) or non-numeric counter field is
+ *  "the OS did not say", which must stay `undefined` rather than become 0. */
+function optionalCount(field: string | undefined): number | undefined {
+  const text = (field ?? "").trim();
+  if (!/^\d+$/.test(text)) return undefined;
+  const n = Number(text);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function parseProcessLine(f: string[]): RawProcessRow | null {
+  const pid = Number(f[1]);
+  const ppid = Number(f[2]);
+  const kernel = Number(f[4]);
+  const user = Number(f[5]);
+  const ws = Number(f[6]);
+  if (![pid, ppid, kernel, user, ws].every(Number.isFinite)) return null;
+  if (pid === 0) return null;
+  return {
+    pid,
+    ppid: ppid >= 0 ? ppid : -1,
+    name: stripExecutableExtension((f[3] ?? "").trim()) || String(pid),
+    command: null,
+    cpuMs: (kernel + user) / HUNDRED_NS_PER_MS,
+    ramMB: ws / BYTES_PER_MB,
+    startedAt: ticksToEpochMs((f[7] ?? "").trim()),
+    diskReadBytes: optionalCount(f[8]),
+    diskWriteBytes: optionalCount(f[9]),
+  };
+}
+
+/** `CommandLine` arrives base64(UTF-8) because argv is attacker-controlled and
+ *  the transport is line-framed. Anything that is not valid base64 is dropped —
+ *  a raw string here means the field was tampered with, not that it is a command. */
+export function decodeCommandLine(b64: string): string {
+  if (!b64 || !/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) return "";
+  try {
+    return Buffer.from(b64, "base64").toString("utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+
+export function parseWindowsTick(text: string): ParsedWindowsTick {
+  const processes: RawProcessRow[] = [];
+  let commands: WindowsCommandLine[] | null = null;
+  const counterLines: string[] = [];
+  const gpuLines: string[] = [];
+  const errors: string[] = [];
+
+  for (const raw of text.split("\n")) {
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    if (!line) continue;
+    switch (line.slice(0, 2)) {
+      case "P\t": {
+        const row = parseProcessLine(splitLimited(line, 10));
+        if (row) processes.push(row);
+        break;
+      }
+      case "C\t": {
+        const f = splitLimited(line, 4);
+        const pid = Number(f[1]);
+        // A `C` section that exists but is all-null still counts as fetched.
+        commands ??= [];
+        if (!Number.isFinite(pid) || f.length < 4) break;
+        const command = decodeCommandLine((f[3] ?? "").trim());
+        if (command) commands.push({ pid, startedAt: ticksToEpochMs((f[2] ?? "").trim()), command });
+        break;
+      }
+      case "D\t":
+      case "N\t":
+        counterLines.push(line);
+        break;
+      case "G\t":
+      case "M\t":
+        gpuLines.push(line);
+        break;
+      default:
+        if (line.startsWith("__ERR__")) errors.push(line.slice("__ERR__".length).trim());
+        break;
+    }
+  }
+
+  const { disk, net } = parsePerfRawDiskNet(counterLines);
+  return { processes, commands, disk, net, gpu: parseGpuLines(gpuLines), errors };
+}

package/src/services/system-metrics/process-collector-windows.ts

@@ -0,0 +1,136 @@
+/**
+ * Windows process collector: one `Win32_Process` + disk + net round trip per
+ * tick through the long-lived PowerShell session (measured 172-206 ms), plus
+ * the expensive `CommandLine` pass only every 30 s.
+ *
+ * `Get-Process` is not used at all: unelevated it silently returns null CPU and
+ * start time for ~45 % of rows. `Win32_Process` with this property list has
+ * zero nulls. All scripts are static strings — no user input ever reaches them.
+ */
+import type { ProcessCollection, ProcessCollector, RawProcessRow } from "./process-collector-types.ts";
+import { createStickyColumns } from "./process-collector-types.ts";
+import { PowerShellSession, PsSessionDisabledError, PS_DISABLED_WARNING } from "./powershell-session.ts";
+import { parseWindowsTick, type WindowsCommandLine } from "./process-collector-windows-parse.ts";
+import { computeGpuPercents, memBytesToMB, type GpuUsageState } from "./gpu-process-usage-windows.ts";
+
+/** `.ToUniversalTime()` here, not in JS: only .NET on this machine knows which
+ *  DST rule applied at the instant each process started. */
+const CREATION_UTC_TICKS = "$($_.CreationDate.ToUniversalTime().Ticks)";
+
+export const WINDOWS_TICK_SCRIPT = [
+  "Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,Name,KernelModeTime,UserModeTime,WorkingSetSize,CreationDate,ReadTransferCount,WriteTransferCount | " +
+    `ForEach-Object { "P\`t$($_.ProcessId)\`t$($_.ParentProcessId)\`t$($_.Name)\`t$($_.KernelModeTime)\`t$($_.UserModeTime)\`t$($_.WorkingSetSize)\`t${CREATION_UTC_TICKS}\`t$($_.ReadTransferCount)\`t$($_.WriteTransferCount)" }`,
+  "Get-CimInstance Win32_PerfRawData_PerfDisk_PhysicalDisk -Filter \"Name='_Total'\" | " +
+    'ForEach-Object { "D`t$($_.DiskReadBytesPerSec)`t$($_.DiskWriteBytesPerSec)`t$($_.Timestamp_PerfTime)`t$($_.Frequency_PerfTime)" }',
+  "Get-CimInstance Win32_PerfRawData_Tcpip_NetworkInterface | " +
+    'ForEach-Object { "N`t$($_.Name)`t$($_.BytesReceivedPersec)`t$($_.BytesSentPersec)`t$($_.Timestamp_Sys100NS)" }',
+  // 505 engine instances on a dev box, of which ~50 are busy: filtering in
+  // PowerShell keeps the reply an order of magnitude smaller than the class.
+  "Get-CimInstance Win32_PerfRawData_GPUPerformanceCounters_GPUEngine | Where-Object { $_.UtilizationPercentage -gt 0 } | " +
+    'ForEach-Object { "G`t$($_.Name)`t$($_.UtilizationPercentage)`t$($_.Timestamp_Sys100NS)" }',
+  "Get-CimInstance Win32_PerfRawData_GPUPerformanceCounters_GPUProcessMemory | " +
+    'ForEach-Object { "M`t$($_.Name)`t$($_.DedicatedUsage)" }',
+].join("\n");
+
+/** +10 ms and +95 KB per fetch, and ~half the rows are access-denied (null)
+ *  unelevated — so it runs on its own slow cadence and merges by identity.
+ *  `CommandLine` is the only attacker-controlled field in the whole round trip
+ *  (any local process picks its own argv), so it travels base64-encoded: raw,
+ *  an embedded CR/LF would let it forge a `P` row for another pid or inject an
+ *  `__END_<id>__` line that truncates the reply. */
+export const WINDOWS_COMMANDLINE_SCRIPT =
+  "Get-CimInstance Win32_Process -Property ProcessId,CommandLine,CreationDate | " +
+  `ForEach-Object { "C\`t$($_.ProcessId)\`t${CREATION_UTC_TICKS}\`t$([Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$_.CommandLine)))" }`;
+
+export const COMMANDLINE_REFRESH_MS = 30_000;
+
+export interface WindowsProcessCollectorOptions {
+  session?: PowerShellSession;
+  now?: () => number;
+  commandRefreshMs?: number;
+  /** Seam for the one-shot startup timing line, so tests stay silent. */
+  log?: (message: string) => void;
+}
+
+export interface WindowsProcessCollector extends ProcessCollector {
+  readonly session: PowerShellSession;
+}
+
+export function createWindowsProcessCollector(opts: WindowsProcessCollectorOptions = {}): WindowsProcessCollector {
+  const session = opts.session ?? new PowerShellSession();
+  const now = opts.now ?? Date.now;
+  const refreshMs = opts.commandRefreshMs ?? COMMANDLINE_REFRESH_MS;
+  const log = opts.log ?? ((m: string) => console.log(m));
+  const observeColumns = createStickyColumns();
+  let commandByPid = new Map<number, WindowsCommandLine>();
+  let lastCommandFetchAt = Number.NEGATIVE_INFINITY;
+  let gpuState: GpuUsageState | null = null;
+  let logged = false;
+
+  return {
+    session,
+    stop: () => session.stop(),
+    async collect(): Promise<ProcessCollection> {
+      if (session.isDisabled()) return { rows: [], columns: observeColumns({}), warnings: [PS_DISABLED_WARNING] };
+
+      const wantCommands = now() - lastCommandFetchAt >= refreshMs;
+      const script = wantCommands ? `${WINDOWS_TICK_SCRIPT}\n${WINDOWS_COMMANDLINE_SCRIPT}` : WINDOWS_TICK_SCRIPT;
+      const startedRequestAt = now();
+      let text: string;
+      try {
+        text = await session.request(script);
+      } catch (e) {
+        if (e instanceof PsSessionDisabledError) {
+          return { rows: [], columns: observeColumns({}), warnings: [PS_DISABLED_WARNING] };
+        }
+        throw e;
+      }
+      if (!logged) {
+        logged = true;
+        // One line, once: the round trip now also carries the two GPU classes,
+        // and the 2 s tick budget is the thing that would break first.
+        log(`[system-metrics] windows tick round trip (incl. GPU pass): ${now() - startedRequestAt} ms`);
+      }
+
+      const parsed = parseWindowsTick(text);
+      if (parsed.commands) {
+        commandByPid = new Map(parsed.commands.map((c) => [c.pid, c]));
+        lastCommandFetchAt = now();
+      }
+
+      // First row for a pid wins, like the guard maps: a forged duplicate must
+      // not decide which start time the GPU delta key is anchored to.
+      const startedAtByPid = new Map<number, number>();
+      for (const p of parsed.processes) if (!startedAtByPid.has(p.pid)) startedAtByPid.set(p.pid, p.startedAt);
+      const gpu = computeGpuPercents(gpuState, parsed.gpu.engines, (pid) => startedAtByPid.get(pid));
+      gpuState = gpu.next;
+
+      const rows: RawProcessRow[] = parsed.processes.map((r) => ({
+        ...r,
+        command: mergeCommand(r, commandByPid.get(r.pid)),
+        // Windows reports GPU per pid for the whole machine, so a pid with no
+        // engine instance is measured-and-idle (0), not unmeasurable.
+        gpuPct: parsed.gpu.present ? gpu.pctByPid.get(r.pid) ?? 0 : undefined,
+        gpuMemMB: parsed.gpu.present ? memBytesToMB(parsed.gpu.memBytesByPid.get(r.pid) ?? 0) : undefined,
+      }));
+      return {
+        rows,
+        disk: parsed.disk,
+        net: parsed.net,
+        columns: observeColumns({
+          disk: rows.some((r) => r.diskReadBytes !== undefined),
+          gpu: parsed.gpu.present,
+        }),
+        warnings: parsed.errors.map((e) => `PowerShell: ${e}`),
+      };
+    },
+  };
+}
+
+/** A pid new since the last 30 s fetch — or recycled since — has no command
+ *  yet; the row falls back to its name until the next fetch. */
+export function mergeCommand(row: RawProcessRow, cached: WindowsCommandLine | undefined): string | null {
+  if (!cached) return null;
+  if (cached.startedAt && row.startedAt && cached.startedAt !== row.startedAt) return null;
+  return cached.command;
+}

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;
+  }
+}