@hienlh/ppm 0.23.10 → 0.23.11

package/src/services/system-metrics/cpu-details-darwin.ts

@@ -0,0 +1,268 @@
+/**
+ * Mission Center's CPU page on a Mac. Split like the Linux one: static facts for
+ * the hardware inventory (sysctl, plus the power manager's frequency tables for
+ * the top clock), live ones for the tick (the scheduler's thread total, the open
+ * file count, and the sensor readings `sensors-darwin.ts` takes once a tick).
+ *
+ * Apple Silicon is not one CPU but clusters of two kinds. `hw.perflevel<N>.*`
+ * describes each kind — core count, per-core L1, per-cluster L2 — and is the only
+ * honest source for the caches: the top-level `hw.l1icachesize` family answers
+ * for the EFFICIENCY cores alone (128 KiB L1i and a 4 MiB L2 on an M1 Max whose
+ * performance cores have 192 KiB and 12 MiB). An Intel Mac has no perf levels
+ * and uses `hw.cacheconfig`, which says how many logical CPUs share each level.
+ *
+ * Nothing Linux-specific is filled: macOS has no cpufreq driver, governor or
+ * energy-performance preference, so those stay absent and the page hides them.
+ */
+import type { CpuInfo } from "../../types/system-hardware.ts";
+import type { CpuMetrics } from "../../types/system-metrics.ts";
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+import { darwinKernel, isAppleSilicon, type DarwinKernel } from "./darwin-ffi.ts";
+import { parsePlistXml, plistArray, plistData, plistDict } from "./plist-xml.ts";
+import type { DarwinSensorReadings } from "./sensors-darwin.ts";
+
+// ---------------------------------------------------------------- static
+
+/** One kind of core: `hw.perflevel<N>.*`. */
+export interface PerfLevel {
+  /** "Performance" or "Efficiency" as the kernel names it. */
+  name: string;
+  physical: number;
+  logical: number;
+  l1iBytes?: number;
+  l1dBytes?: number;
+  l2Bytes?: number;
+  /** Cores sharing one L2, i.e. the cluster size. */
+  cpusPerL2?: number;
+}
+
+export function readPerfLevels(kernel: DarwinKernel): PerfLevel[] {
+  const count = kernel.sysctlNumber("hw.nperflevels") ?? 0;
+  const levels: PerfLevel[] = [];
+  for (let i = 0; i < count; i++) {
+    const at = (field: string) => kernel.sysctlNumber(`hw.perflevel${i}.${field}`);
+    const name = kernel.sysctlString(`hw.perflevel${i}.name`);
+    const physical = at("physicalcpu");
+    const logical = at("logicalcpu");
+    if (!name || !physical || !logical) continue;
+    levels.push({
+      name, physical, logical,
+      ...defined("l1iBytes", at("l1icachesize")),
+      ...defined("l1dBytes", at("l1dcachesize")),
+      ...defined("l2Bytes", at("l2cachesize")),
+      ...defined("cpusPerL2", at("cpusperl2")),
+    });
+  }
+  return levels;
+}
+
+/**
+ * Summed over DISTINCT caches, as the Linux page does: L1 is per core (data +
+ * instruction), L2 is per cluster. An M1 Max: 8 × (192 + 128) KiB + 2 × (128 +
+ * 64) KiB of L1, and two 12 MiB performance-cluster L2s plus one 4 MiB
+ * efficiency one. Apple Silicon has no L3 — its system-level cache is shared
+ * with the GPU and not published as a CPU cache — so L3 stays absent.
+ */
+export function cachesFromPerfLevels(levels: readonly PerfLevel[]): { l1?: number; l2?: number } {
+  let l1 = 0;
+  let l2 = 0;
+  let sawL1 = false;
+  let sawL2 = false;
+  for (const level of levels) {
+    if (level.l1iBytes !== undefined || level.l1dBytes !== undefined) {
+      l1 += ((level.l1iBytes ?? 0) + (level.l1dBytes ?? 0)) * level.physical;
+      sawL1 = true;
+    }
+    if (level.l2Bytes !== undefined) {
+      l2 += level.l2Bytes * Math.ceil(level.physical / Math.max(1, level.cpusPerL2 ?? level.physical));
+      sawL2 = true;
+    }
+  }
+  return { ...defined("l1", sawL1 ? l1 : undefined), ...defined("l2", sawL2 ? l2 : undefined) };
+}
+
+/** `hw.cacheconfig` / `hw.cachesize`: ten u64s each, index = cache level (0 is
+ *  memory). `cacheconfig[n]` logical CPUs share one level-n cache of
+ *  `cachesize[n]` bytes; `cachesize[1]` is the DATA cache only, so L1's
+ *  instruction half comes from `hw.l1icachesize`. */
+export function cachesFromCacheConfig(kernel: DarwinKernel): { l1?: number; l2?: number; l3?: number } {
+  const config = u64s(kernel.sysctlBytes("hw.cacheconfig"));
+  const sizes = u64s(kernel.sysctlBytes("hw.cachesize"));
+  const logical = kernel.sysctlNumber("hw.logicalcpu");
+  if (!config || !sizes || !logical) return {};
+  const instances = (level: number) => {
+    const sharing = config[level] ?? 0;
+    return sharing > 0 ? Math.max(1, Math.round(logical / sharing)) : 0;
+  };
+  const total = (level: number, extra = 0) => {
+    const n = instances(level);
+    const size = sizes[level] ?? 0;
+    return n > 0 && size > 0 ? (size + extra) * n : undefined;
+  };
+  return {
+    ...defined("l1", total(1, kernel.sysctlNumber("hw.l1icachesize") ?? 0)),
+    ...defined("l2", total(2)),
+    ...defined("l3", total(3)),
+  };
+}
+
+function u64s(bytes: Uint8Array | undefined): number[] | undefined {
+  if (!bytes || bytes.byteLength === 0 || bytes.byteLength % 8 !== 0) return undefined;
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const out: number[] = [];
+  for (let off = 0; off < bytes.byteLength; off += 8) out.push(Number(v.getBigUint64(off, true)));
+  return out;
+}
+
+/**
+ * `maxMHz` comes from the caller because on Apple Silicon it is not a sysctl at
+ * all — see `readPmgrDvfs`. On an Intel Mac `hw.cpufrequency` is the nominal
+ * clock; `hw.cpufrequency_max` is only kept when it says something more, since
+ * Intel Macs report the nominal clock there too rather than the turbo one.
+ */
+export function readDarwinCpuInfo(kernel: DarwinKernel | null = darwinKernel(), maxMHz?: number): CpuInfo | undefined {
+  if (!kernel) return undefined;
+  const name = kernel.sysctlString("machdep.cpu.brand_string");
+  const physicalCores = kernel.sysctlNumber("hw.physicalcpu");
+  const logicalCores = kernel.sysctlNumber("hw.logicalcpu");
+  if (!name || !physicalCores || !logicalCores) return undefined;
+
+  const appleSilicon = isAppleSilicon(kernel);
+  const levels = readPerfLevels(kernel);
+  const caches: { l1?: number; l2?: number; l3?: number } =
+    levels.length > 0 ? cachesFromPerfLevels(levels) : cachesFromCacheConfig(kernel);
+  const performance = levels.find((l) => l.name === "Performance");
+  const efficiency = levels.find((l) => l.name === "Efficiency");
+  const baseMHz = hzToMHz(kernel.sysctlNumber("hw.cpufrequency"));
+  const sysctlMax = hzToMHz(kernel.sysctlNumber("hw.cpufrequency_max"));
+  const topMHz = sysctlMax !== undefined && (baseMHz === undefined || sysctlMax > baseMHz) ? sysctlMax : maxMHz;
+
+  return {
+    name: name.trim(),
+    sockets: kernel.sysctlNumber("hw.packages") ?? 1,
+    physicalCores,
+    logicalCores,
+    ...(performance && efficiency
+      ? { performanceCores: performance.physical, efficiencyCores: efficiency.physical }
+      : {}),
+    ...defined("baseMHz", baseMHz),
+    ...defined("maxMHz", topMHz),
+    ...defined("virtualization", kernel.sysctlNumber("kern.hv_support") === 1
+      ? (appleSilicon ? "Apple Hypervisor" : "Intel VT-x")
+      : undefined),
+    isVirtualMachine: kernel.sysctlNumber("kern.hv_vmm_present") === 1,
+    ...defined("l1CacheBytes", caches.l1),
+    ...defined("l2CacheBytes", caches.l2),
+    ...defined("l3CacheBytes", caches.l3),
+  };
+}
+
+const hzToMHz = (hz: number | undefined) => (hz !== undefined && hz > 0 ? Math.round(hz / 1e6) : undefined);
+
+// ---------------------------------------------------------------- frequency tables
+
+/** Clock of each performance state, MHz, in the order the power manager lists
+ *  them (index = state, which is what IOReport's residencies are keyed by). */
+export interface DvfsTables {
+  ecpuMHz: number[];
+  pcpuMHz: number[];
+  gpuMHz: number[];
+}
+
+/**
+ * One `voltage-states*` blob: little-endian u32 pairs of (frequency, voltage).
+ * The frequency is in Hz on the M1 this was measured on; a table whose largest
+ * entry is below 10^8 is read as kHz, because a core above 4.29 GHz — an M4's —
+ * cannot be written in Hz in a u32 at all. A table with no plausible clock is
+ * not a frequency table and yields nothing.
+ */
+export function parseDvfsTable(bytes: Uint8Array | undefined): number[] {
+  if (!bytes || bytes.byteLength < 8) return [];
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const raw: number[] = [];
+  for (let off = 0; off + 8 <= bytes.byteLength; off += 8) raw.push(v.getUint32(off, true));
+  const top = Math.max(...raw);
+  const divisor = top >= 1e8 ? 1e6 : top >= 1e5 ? 1e3 : 0;
+  return divisor ? raw.map((f) => Math.round(f / divisor)) : [];
+}
+
+/**
+ * The tables the tools that read them agree on: `voltage-states1-sram` is the
+ * efficiency cluster, `voltage-states5-sram` the performance cluster and
+ * `voltage-states9` the GPU (the non-`sram` CPU tables hold no clocks). An M1 Max
+ * lists a second performance cluster and three more GPU tables with identical
+ * clocks, so reading one of each loses nothing.
+ */
+export function parsePmgrDvfs(xml: string): DvfsTables | undefined {
+  const entry = plistDict(plistArray(parsePlistXml(xml))?.[0]);
+  if (!entry) return undefined;
+  const tables = {
+    ecpuMHz: parseDvfsTable(plistData(entry["voltage-states1-sram"])),
+    pcpuMHz: parseDvfsTable(plistData(entry["voltage-states5-sram"])),
+    gpuMHz: parseDvfsTable(plistData(entry["voltage-states9"])),
+  };
+  return tables.ecpuMHz.length || tables.pcpuMHz.length || tables.gpuMHz.length ? tables : undefined;
+}
+
+/** The fastest any CPU core will run: the top performance state of either kind. */
+export function maxCpuMHz(tables: DvfsTables | undefined): number | undefined {
+  const all = [...(tables?.ecpuMHz ?? []), ...(tables?.pcpuMHz ?? [])];
+  return all.length > 0 ? Math.max(...all) : undefined;
+}
+
+let dvfs: Promise<DvfsTables | undefined> | undefined;
+
+/**
+ * `ioreg` for the power manager's node alone (19 ms). The tables are burned into
+ * the chip, so a successful read is kept for the life of the process; a failed
+ * one is not, and the next inventory request asks again.
+ */
+export function readPmgrDvfs(run: Runner = defaultRunner): Promise<DvfsTables | undefined> {
+  if (run !== defaultRunner) return fetchPmgrDvfs(run);
+  dvfs ??= fetchPmgrDvfs(run).then((tables) => {
+    if (!tables) dvfs = undefined;
+    return tables;
+  });
+  return dvfs;
+}
+
+async function fetchPmgrDvfs(run: Runner): Promise<DvfsTables | undefined> {
+  if (process.platform !== "darwin" && run === defaultRunner) return undefined;
+  try {
+    const result = await run(["ioreg", "-a", "-r", "-d", "1", "-n", "pmgr"], 5000);
+    if (result.code !== 0 || !result.stdout) return undefined;
+    return parsePmgrDvfs(result.stdout);
+  } catch {
+    // The inventory must answer without a top clock rather than not at all.
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------- live
+
+/**
+ * The per-tick extras, each absent when the kernel or the sensor behind it did
+ * not answer. `threadCount` is every thread the scheduler knows
+ * (processor_set_load_info), which is what the Linux page's `/proc/loadavg` total
+ * is too; `handleCount` is the kernel's open-file count, the Linux page's
+ * `file-nr`. The temperature is the SMC's core sensors; the clock and the power
+ * are IOReport's, the clock weighed by how long each core ran at each speed.
+ */
+export function collectDarwinCpuLive(
+  kernel: DarwinKernel | null = darwinKernel(),
+  sensors: Pick<DarwinSensorReadings, "cpuC" | "cpuPowerW" | "cpuMHz"> = {},
+): Partial<CpuMetrics> {
+  const load = kernel?.processorSetLoad();
+  return {
+    ...defined("threadCount", load?.threadCount),
+    ...defined("handleCount", kernel?.sysctlNumber("kern.num_files")),
+    ...defined("tempC", sensors.cpuC),
+    ...defined("powerW", sensors.cpuPowerW),
+    ...defined("currentMHz", sensors.cpuMHz),
+  };
+}
+
+function defined<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
+  return value === undefined ? {} : ({ [key]: value } as Record<K, V>);
+}

package/src/services/system-metrics/cpu-memory-collector.ts

@@ -1,15 +1,16 @@
 /**
  * Whole-machine CPU + memory. Runs in both tiers.
  *
- * Reads files on Linux and spawns nothing there. On darwin it spawns exactly one
- * `sysctl` per tick for swap, which `node:os` does not carry — measured at
- * 1.33 ms, see `memory-darwin.ts`.
+ * Reads files on Linux and spawns nothing there. On darwin the memory figures
+ * come from the kernel over FFI (`darwin-ffi.ts`, 0.08 ms), so nothing is
+ * spawned there either — `sysctl` is only the fallback for swap if libSystem
+ * cannot be opened.
  */
 import os from "node:os";
 import { readFileSync } from "node:fs";
 import type { CpuMetrics, MemoryMetrics } from "../../types/system-metrics.ts";
 import { enrichMemory, readZramTotals, type ZramTotals } from "./memory-linux.ts";
-import { parseSwapUsage, readSwapUsage } from "./memory-darwin.ts";
+import { parseSwapUsage, readDarwinMemory, readSwapUsage, toDarwinMemory, type DarwinMemorySample } from "./memory-darwin.ts";
 
 export interface CoreTimes {
   user: number;
@@ -182,22 +183,30 @@ export function parseMemAvailableBytes(meminfo: string): number | null {
  * and `os.freemem()` is within 0.2 GiB of CIM's `FreePhysicalMemory`. On Linux
  * `freemem()` is `MemFree`, which makes a warm page cache look like a nearly
  * full machine — `MemAvailable` is what `free` and Task-Manager-like tools show.
- * On **darwin** `freemem()` is already right and must be left alone: it agrees
- * with what `top` calls unused (75 MB against this figure's 124 MB on the same
- * host, sampled seconds apart), which is the number Activity Monitor shows.
  *
- * Swap is the one field macOS publishes and `os` does not, so it is fetched
- * separately — see `memory-darwin.ts` for why that costs a spawn and why the
- * page counts from `vm_stat` are deliberately not used.
+ * On **darwin** `freemem()` is the same mistake in a worse form: it counts free
+ * pages only (66 MB on a 32 GB Mac), so a machine Activity Monitor called 27 GB
+ * used read 99.7 % here. The page counts are read from the kernel instead and
+ * turned into Activity Monitor's figures — see `memory-darwin.ts`. The old
+ * `freemem()` arithmetic below is what is left for a darwin host where that
+ * read fails, and for Windows.
  */
 export function collectMemory(
   meminfo: () => string | null = readMeminfo,
   zram: () => ZramTotals | undefined = defaultZram,
   swapusage: () => string | null = readSwapUsage,
+  darwin: () => DarwinMemorySample | undefined = defaultDarwinMemory,
 ): MemoryMetrics {
   const totalBytes = os.totalmem();
-  let availableBytes = os.freemem();
   const info = meminfo();
+  if (!info) {
+    const sample = darwin();
+    if (sample) {
+      const mem = toDarwinMemory(totalBytes, sample);
+      return sample.swap ? mem : { ...mem, ...parseSwapUsage(swapusage()) };
+    }
+  }
+  let availableBytes = os.freemem();
   if (info) {
     const avail = parseMemAvailableBytes(info);
     if (avail !== null) availableBytes = avail;
@@ -216,6 +225,12 @@ export function collectMemory(
   return { ...base, ...parseSwapUsage(swapusage()) };
 }
 
+/** Undefined off darwin without touching FFI — `darwinKernel()` checks the
+ *  platform before it opens anything. */
+function defaultDarwinMemory(): DarwinMemorySample | undefined {
+  return readDarwinMemory();
+}
+
 /** Two `/sys` reads on a host that has zram and one cheap directory listing on
  *  one that does not — small enough to run per tick, unlike the DIMM layout. */
 function defaultZram(): ZramTotals | undefined {

package/src/services/system-metrics/darwin-ffi.ts

@@ -0,0 +1,232 @@
+/**
+ * The macOS kernel figures the System Monitor reads straight from libSystem over
+ * bun:ffi instead of spawning a tool for each: `sysctlbyname`, the VM page counts
+ * behind `vm_stat` and the scheduler's thread total.
+ *
+ * Two reasons this is FFI rather than `sysctl`/`vm_stat` in a subprocess. The
+ * memory figures run on BOTH tiers — the light one feeds the status bar on every
+ * page — and a spawn per tick there was the one process the light tier started.
+ * And every call here was measured at well under a millisecond (0.002 ms for the
+ * page counts once the library is open, against ~1.3 ms for the cheapest spawn),
+ * so nothing below needs to be async.
+ *
+ * Every struct layout is from the macOS SDK headers and was checked against the
+ * tool that prints the same numbers on a real M1 Max (`vm_stat`, `sysctl
+ * vm.swapusage`): a wrong offset does not fail, it reads a neighbouring field and
+ * returns a plausible number, so the parsers are pure and pinned by tests.
+ *
+ * Nothing is opened until first asked for, and a host where libSystem cannot be
+ * reached (anything but darwin) answers `undefined` for every figure — which the
+ * callers render as "not measured", never as zero.
+ */
+import { dlopen, FFIType as T, ptr } from "bun:ffi";
+
+const LIBSYSTEM = "/usr/lib/libSystem.B.dylib";
+const KERN_SUCCESS = 0;
+
+/** `<mach/host_info.h>`: HOST_VM_INFO64, and its count in `integer_t` units. */
+const HOST_VM_INFO64 = 4;
+export const VM_STATISTICS64_BYTES = 152;
+const HOST_VM_INFO64_COUNT = VM_STATISTICS64_BYTES / 4;
+
+/** `<mach/processor_info.h>`: PROCESSOR_SET_LOAD_INFO = { task_count, thread_count, load_average, mach_factor }. */
+const PROCESSOR_SET_LOAD_INFO = 4;
+const PROCESSOR_SET_LOAD_INFO_COUNT = 4;
+
+/** `struct xsw_usage` from `<sys/sysctl.h>`: three u64 then a u32 page size and a boolean_t. */
+export const XSW_USAGE_BYTES = 32;
+
+/** The fields of `vm_statistics64` this code reads, in pages. */
+export interface VmStatistics64 {
+  free: number;
+  active: number;
+  inactive: number;
+  wire: number;
+  purgeable: number;
+  speculative: number;
+  /** Pages the compressor itself occupies — what Activity Monitor calls "Compressed". */
+  compressor: number;
+  throttled: number;
+  /** File-backed pages. */
+  external: number;
+  /** Anonymous pages. */
+  internal: number;
+  /** Pages' worth of data held inside the compressor, before compression. */
+  uncompressedInCompressor: number;
+}
+
+export interface SwapUsage {
+  totalBytes: number;
+  usedBytes: number;
+}
+
+export interface ProcessorSetLoad {
+  taskCount: number;
+  threadCount: number;
+}
+
+/** What the collectors ask of the kernel. Injected, so every consumer is tested
+ *  against a fake and only this file ever touches a real symbol. */
+export interface DarwinKernel {
+  /** An integer sysctl (4 or 8 bytes). Undefined when the name does not exist
+   *  on this host — `hw.l3cachesize` on Apple Silicon, `hw.perflevel0.*` on Intel. */
+  sysctlNumber(name: string): number | undefined;
+  sysctlString(name: string): string | undefined;
+  /** A struct-valued sysctl, raw. */
+  sysctlBytes(name: string): Uint8Array | undefined;
+  vmStatistics(): VmStatistics64 | undefined;
+  processorSetLoad(): ProcessorSetLoad | undefined;
+}
+
+/**
+ * `vm_statistics64` as `<mach/vm_statistics.h>` lays it out (8-byte aligned,
+ * 152 bytes). Offsets verified field by field against `vm_stat` on macOS 15.
+ */
+export function parseVmStatistics64(bytes: Uint8Array): VmStatistics64 | undefined {
+  if (bytes.byteLength < VM_STATISTICS64_BYTES) return undefined;
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const u32 = (o: number) => v.getUint32(o, true);
+  return {
+    free: u32(0),
+    active: u32(4),
+    inactive: u32(8),
+    wire: u32(12),
+    purgeable: u32(88),
+    speculative: u32(92),
+    compressor: u32(128),
+    throttled: u32(132),
+    external: u32(136),
+    internal: u32(140),
+    uncompressedInCompressor: Number(v.getBigUint64(144, true)),
+  };
+}
+
+export function parseXswUsage(bytes: Uint8Array): SwapUsage | undefined {
+  if (bytes.byteLength < XSW_USAGE_BYTES) return undefined;
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const totalBytes = Number(v.getBigUint64(0, true));
+  const usedBytes = Number(v.getBigUint64(16, true));
+  // A used figure above the total is a sample taken while the swap file was
+  // being resized, not a bigger swap.
+  return { totalBytes, usedBytes: Math.min(usedBytes, totalBytes) };
+}
+
+/** A sysctl value by its length: `int` sysctls are 4 bytes, `quad` ones 8. */
+export function decodeSysctlNumber(bytes: Uint8Array): number | undefined {
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (bytes.byteLength === 4) return v.getInt32(0, true);
+  if (bytes.byteLength === 8) return Number(v.getBigInt64(0, true));
+  return undefined;
+}
+
+export function decodeSysctlString(bytes: Uint8Array): string | undefined {
+  const text = new TextDecoder().decode(bytes).replace(/\0+$/, "");
+  return text.length > 0 ? text : undefined;
+}
+
+type Symbols = {
+  sysctlbyname: (name: Uint8Array | number, oldp: number | null, oldlenp: number, newp: null, newlen: bigint) => number;
+  mach_host_self: () => number;
+  host_statistics64: (host: number, flavor: number, info: number, count: number) => number;
+  processor_set_default: (host: number, pset: number) => number;
+  processor_set_statistics: (pset: number, flavor: number, info: number, count: number) => number;
+};
+
+/** `undefined` until first asked for; `null` where libSystem cannot be opened. */
+let lib: Symbols | null | undefined;
+/** Send rights, taken once. `mach_host_self()` adds a user reference on every
+ *  call and `processor_set_default` hands out a right each time, so asking per
+ *  tick would leak one per tick for the life of the server. */
+let hostPort = 0;
+let psetPort = 0;
+const encoder = new TextEncoder();
+
+function open(): Symbols | null {
+  if (lib !== undefined) return lib;
+  lib = null;
+  if (process.platform !== "darwin") return null;
+  try {
+    lib = dlopen(LIBSYSTEM, {
+      sysctlbyname: { args: [T.ptr, T.ptr, T.ptr, T.ptr, T.u64], returns: T.i32 },
+      mach_host_self: { args: [], returns: T.u32 },
+      host_statistics64: { args: [T.u32, T.i32, T.ptr, T.ptr], returns: T.i32 },
+      processor_set_default: { args: [T.u32, T.ptr], returns: T.i32 },
+      processor_set_statistics: { args: [T.u32, T.i32, T.ptr, T.ptr], returns: T.i32 },
+    }).symbols as unknown as Symbols;
+  } catch {
+    lib = null;
+  }
+  return lib;
+}
+
+function host(l: Symbols): number {
+  if (hostPort === 0) hostPort = l.mach_host_self();
+  return hostPort;
+}
+
+function sysctlRaw(name: string): Uint8Array | undefined {
+  const l = open();
+  if (!l) return undefined;
+  const key = encoder.encode(`${name}\0`);
+  const len = new BigUint64Array(1);
+  // First call sizes the value, second reads it; a name this kernel does not
+  // have fails the first with ENOENT.
+  if (l.sysctlbyname(key, null, ptr(len), null, 0n) !== 0) return undefined;
+  const size = Number(len[0]);
+  if (!(size > 0) || size > 1 << 20) return undefined;
+  const buf = new Uint8Array(size);
+  if (l.sysctlbyname(key, ptr(buf), ptr(len), null, 0n) !== 0) return undefined;
+  return buf.subarray(0, Math.min(size, Number(len[0])));
+}
+
+const realKernel: DarwinKernel = {
+  sysctlNumber(name) {
+    const bytes = sysctlRaw(name);
+    return bytes ? decodeSysctlNumber(bytes) : undefined;
+  },
+  sysctlString(name) {
+    const bytes = sysctlRaw(name);
+    return bytes ? decodeSysctlString(bytes) : undefined;
+  },
+  sysctlBytes: sysctlRaw,
+  vmStatistics() {
+    const l = open();
+    if (!l) return undefined;
+    const info = new Uint8Array(VM_STATISTICS64_BYTES);
+    const count = new Uint32Array([HOST_VM_INFO64_COUNT]);
+    if (l.host_statistics64(host(l), HOST_VM_INFO64, ptr(info), ptr(count)) !== KERN_SUCCESS) return undefined;
+    return parseVmStatistics64(info);
+  },
+  processorSetLoad() {
+    const l = open();
+    if (!l) return undefined;
+    if (psetPort === 0) {
+      const out = new Uint32Array(1);
+      if (l.processor_set_default(host(l), ptr(out)) !== KERN_SUCCESS) return undefined;
+      psetPort = out[0]!;
+    }
+    const info = new Int32Array(PROCESSOR_SET_LOAD_INFO_COUNT);
+    const count = new Uint32Array([PROCESSOR_SET_LOAD_INFO_COUNT]);
+    if (l.processor_set_statistics(psetPort, PROCESSOR_SET_LOAD_INFO, ptr(info), ptr(count)) !== KERN_SUCCESS) {
+      // Re-ask next time rather than failing forever on a right that went stale.
+      psetPort = 0;
+      return undefined;
+    }
+    return { taskCount: info[0]!, threadCount: info[1]! };
+  },
+};
+
+/** The real kernel on darwin, null everywhere else — so a caller on another
+ *  platform never reaches a symbol, and says so with one check. */
+export function darwinKernel(): DarwinKernel | null {
+  return open() ? realKernel : null;
+}
+
+/**
+ * The CPU, not the process: `hw.optional.arm64` is 1 on Apple Silicon even for an
+ * x64 build of Bun running under Rosetta, where `process.arch` says "x64" while
+ * every sensor, core and cache belongs to an M-series chip.
+ */
+export function isAppleSilicon(kernel: DarwinKernel | null = darwinKernel()): boolean {
+  return kernel?.sysctlNumber("hw.optional.arm64") === 1;
+}

package/src/services/system-metrics/darwin-tool-reads.ts

@@ -0,0 +1,111 @@
+/**
+ * The macOS tools more than one collector needs in the same tick, each run at most
+ * once per `TOOL_MEMO_MS` and shared by whoever asks.
+ *
+ * On Linux the whole-machine Disk card and the per-drive pages read the same sysfs
+ * counters for free. On a Mac both come out of one `ioreg` call, and the Network
+ * card and the per-interface pages out of one `netstat`, so without sharing a tick
+ * would spawn each tool twice — and measure the two figures a few milliseconds
+ * apart, enough for a drive page and the card to disagree about one transfer. The
+ * trick is the one `createDrmGpuCollector` uses on Linux (`DRM_MEMO_MS`).
+ *
+ * A read that fails answers `undefined`, and that answer is shared too: the second
+ * caller in a tick does not respawn a tool that just failed. Concurrent callers get
+ * the same in-flight promise.
+ */
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+import { parsePlistXml, type PlistValue } from "./plist-xml.ts";
+
+/** Under the 2 s tick, so every tick reads fresh counters. */
+export const TOOL_MEMO_MS = 1000;
+/** The service list changes when someone edits System Settings → Network. */
+export const SERVICE_ORDER_TTL_MS = 60_000;
+
+const TOOL_TIMEOUT_MS = 3000;
+
+export interface ToolRead<T> {
+  value: T;
+  /** When the tool was started, seconds. None of these tools print a clock of
+   *  their own, so this is what a rate is measured against. */
+  atSec: number;
+}
+
+export interface DarwinToolReads {
+  /** Every block storage device with its driver and whole-disk media:
+   *  `ioreg -a -r -l -d 3 -c IOBlockStorageDevice` (~20 ms). */
+  blockDevices(): Promise<ToolRead<PlistValue> | undefined>;
+  /** Each GPU with its utilisation and every client process's GPU time:
+   *  `ioreg -a -r -l -d 2 -c IOAccelerator` (~35 ms). */
+  accelerators(): Promise<ToolRead<PlistValue> | undefined>;
+  /** `netstat -ib` (~40 ms): per-interface byte counters. */
+  netstat(): Promise<ToolRead<string> | undefined>;
+  /** `ifconfig -a -v` (~10 ms): link state, rate, type and the VPN flags. */
+  ifconfig(): Promise<ToolRead<string> | undefined>;
+  /** `networksetup -listnetworkserviceorder` (~30 ms): the services System
+   *  Settings shows, which decide what counts as a real interface. A failed
+   *  refresh keeps answering the last good list — this decides which interfaces
+   *  exist at all, and one timeout must not take Wi-Fi off the page for a minute. */
+  serviceOrder(): Promise<ToolRead<string> | undefined>;
+  /** `diskutil list -plist` (~30 ms): partitions, APFS containers and volumes.
+   *  Only the inventory asks for it. */
+  diskutilList(): Promise<ToolRead<PlistValue> | undefined>;
+  /** `mount` (~5 ms): what is mounted where, with its filesystem — the Mac's
+   *  `/proc/self/mountinfo`. Only the inventory asks for it. */
+  mounts(): Promise<ToolRead<string> | undefined>;
+}
+
+export function createDarwinToolReads(run: Runner = defaultRunner, now: () => number = Date.now): DarwinToolReads {
+  const text = (argv: string[], timeoutMs = TOOL_TIMEOUT_MS) => async () => {
+    const r = await run(argv, timeoutMs);
+    return r.code === 0 && r.stdout.length > 0 ? r.stdout : undefined;
+  };
+  const plist = (argv: string[], timeoutMs?: number) => {
+    const read = text(argv, timeoutMs);
+    return async () => {
+      const xml = await read();
+      return xml === undefined ? undefined : parsePlistXml(xml);
+    };
+  };
+  return {
+    blockDevices: memoised(TOOL_MEMO_MS, now, plist(["ioreg", "-a", "-r", "-l", "-d", "3", "-c", "IOBlockStorageDevice"])),
+    accelerators: memoised(TOOL_MEMO_MS, now, plist(["ioreg", "-a", "-r", "-l", "-d", "2", "-c", "IOAccelerator"])),
+    netstat: memoised(TOOL_MEMO_MS, now, text(["netstat", "-ib"])),
+    ifconfig: memoised(TOOL_MEMO_MS, now, text(["ifconfig", "-a", "-v"])),
+    serviceOrder: memoised(
+      SERVICE_ORDER_TTL_MS, now, text(["networksetup", "-listnetworkserviceorder"], 5000), { keepLastGood: true },
+    ),
+    diskutilList: memoised(TOOL_MEMO_MS, now, plist(["diskutil", "list", "-plist"], 10_000)),
+    mounts: memoised(TOOL_MEMO_MS, now, text(["mount"])),
+  };
+}
+
+function memoised<T>(
+  ttlMs: number,
+  now: () => number,
+  fetch: () => Promise<T | undefined>,
+  { keepLastGood = false } = {},
+): () => Promise<ToolRead<T> | undefined> {
+  let last: { at: number; read: Promise<ToolRead<T> | undefined> } | null = null;
+  let good: ToolRead<T> | undefined;
+  return () => {
+    const at = now();
+    if (last && at - last.at < ttlMs) return last.read;
+    const read = fetch()
+      .then((value) => (value === undefined ? undefined : { value, atSec: at / 1000 }))
+      .catch(() => undefined)
+      .then((result) => {
+        if (result) good = result;
+        return result ?? (keepLastGood ? good : undefined);
+      });
+    last = { at, read };
+    return read;
+  };
+}
+
+let shared: DarwinToolReads | null = null;
+
+/** The one instance the tick, the aggregate counters and the inventory share. */
+export function darwinToolReads(): DarwinToolReads {
+  return (shared ??= createDarwinToolReads());
+}