@hienlh/ppm 0.23.5 → 0.23.7

package/src/services/speech-to-text/whisper-transcribe.service.ts

@@ -0,0 +1,117 @@
+/**
+ * One transcription = one `whisper-cli` run over a temp WAV.
+ *
+ * Per-request process rather than a long-lived `whisper-server`, for two
+ * reasons: Homebrew's formula builds with `WHISPER_BUILD_SERVER=OFF`, so a Mac
+ * has no server binary to talk to; and a resident server holds the model
+ * (574 MB) in RAM between sentences that are minutes apart.
+ *
+ * Runs are serialised. Two at once would each load the model and fight for the
+ * same cores, turning two five-second waits into two twelve-second ones.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, rmSync } from "node:fs";
+import { availableParallelism } from "node:os";
+import { resolve } from "node:path";
+import { isInventedLine } from "./whisper-hallucinations.ts";
+import { installedModel, vadModelPath } from "./whisper-install.service.ts";
+import { findWhisperBinary, whisperModelDir, whisperTmpDir } from "./whisper-paths.ts";
+
+const TIMEOUT_MS = 180_000;
+
+/**
+ * whisper.cpp defaults to 4 threads. Measured on a 24-thread i9-12900K with
+ * large-v3-turbo over a 10s clip: 4 threads 12.0s, 8 threads 8.1s, 16 threads
+ * 5.6s, 24 threads 5.4s — so it is worth raising, and worth capping where the
+ * curve flattens instead of taking every core the host has.
+ */
+export function threadCount(cpus: number = availableParallelism()): number {
+  return Math.max(1, Math.min(16, cpus));
+}
+
+/** A non-speech annotation on a line of its own: "[BLANK_AUDIO]", "(nhạc)", "*gunshot*". */
+const ANNOTATION = /^[[(*][^)\]*]*[\])*]$/;
+
+/**
+ * `-nt` prints text without timestamps, one line per segment. Three kinds of
+ * line are not something anyone dictated: an annotation, a line with no letter
+ * or digit in it at all (a bare "." is what this model makes of a hum in
+ * English), and a sentence it invented out of non-speech — see
+ * whisper-hallucinations.ts.
+ */
+export function parseWhisperText(stdout: string): string {
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(
+      (line) =>
+        line.length > 0 &&
+        !ANNOTATION.test(line) &&
+        /[\p{L}\p{N}]/u.test(line) &&
+        !isInventedLine(line),
+    )
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function whisperArgs(binary: string, wavPath: string, modelPath: string, language: string): string[] {
+  return [
+    binary,
+    "-m", modelPath,
+    "-f", wavPath,
+    "-l", language,
+    "-t", String(threadCount()),
+    "-nt",
+    "-np",
+    // Without VAD, silence is transcribed as an invented sentence — see whisper-catalog.ts.
+    "--vad",
+    "--vad-model", vadModelPath(),
+  ];
+}
+
+let queue: Promise<unknown> = Promise.resolve();
+
+export interface TranscribeResult {
+  text: string;
+  /** Wall time of the whisper-cli run, for the UI's "took Ns" and for tuning. */
+  ms: number;
+}
+
+/** Throws when Whisper is not installed, the run fails, or it outruns the timeout. */
+export async function transcribeWav(wav: Uint8Array, language = "vi"): Promise<TranscribeResult> {
+  const run = queue.then(() => runOnce(wav, language));
+  // Keep the chain alive after a failure, and never leak the rejection through it.
+  queue = run.catch(() => {});
+  return run;
+}
+
+async function runOnce(wav: Uint8Array, language: string): Promise<TranscribeResult> {
+  const binary = findWhisperBinary();
+  const model = installedModel();
+  if (!binary || !model) throw new Error("Whisper is not installed on this host");
+
+  mkdirSync(whisperTmpDir(), { recursive: true });
+  const wavPath = resolve(whisperTmpDir(), `${randomUUID()}.wav`);
+  await Bun.write(wavPath, wav);
+
+  const started = Date.now();
+  try {
+    const cmd = whisperArgs(binary.path, wavPath, resolve(whisperModelDir(), model.file), language);
+    const proc = Bun.spawn({ cmd, stdout: "pipe", stderr: "pipe", stdin: "ignore", windowsHide: true });
+    const timer = setTimeout(() => proc.kill(), TIMEOUT_MS);
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    clearTimeout(timer);
+    if (code !== 0) {
+      const detail = stderr.trim().split("\n").slice(-1)[0] ?? `exit ${code}`;
+      throw new Error(`whisper-cli failed: ${detail}`);
+    }
+    return { text: parseWhisperText(stdout), ms: Date.now() - started };
+  } finally {
+    rmSync(wavPath, { force: true });
+  }
+}

package/src/services/supervisor.ts

@@ -20,7 +20,7 @@ import {
   readAndDeleteCmd, readStatus, updateStatus, writeStatus,
   STATUS_FILE, PID_FILE,
 } from "./supervisor-state.ts";
-import type { ResolvedTunnelConfig, TunnelMode } from "./named-tunnel/named-tunnel-config.ts";
+import { resolveTunnelConfig, type ResolvedTunnelConfig, type TunnelMode } from "./named-tunnel/named-tunnel-config.ts";
 import { readTunnelConfigFresh, chooseTunnelSpawn } from "./named-tunnel/named-tunnel-runtime.ts";
 import { waitForLogLine } from "./named-tunnel/named-tunnel-readiness.ts";
 import { nextNamedRetryDelayMs } from "./named-tunnel/named-tunnel-retry.ts";
@@ -101,6 +101,11 @@ const TUNNEL_REGEN_MIN_INTERVAL_MS = 300_000; // 5min
 // cache, never `configService` (a separate process, stale here) nor a fresh
 // async DB read (would reorder the startup adopt/probe-before-spawn race).
 let namedTunnelMode: ResolvedTunnelConfig | null = null;
+// Effective master switch: the argv flag AND `tunnel.enabled` from config.
+// Module-level rather than a local because the SIGUSR1 and Windows-command
+// handlers close over it before startup reaches the config read, and because
+// `retunnel` flips it live when the user toggles the switch.
+let tunnelSharingEnabled = false;
 // The mode of the tunnel actually spawned (as opposed to `namedTunnelMode`,
 // which is merely the persisted intent) — a token failure leaves config=named
 // but live=quick, and every status write / throttle / restart decision must
@@ -430,6 +435,26 @@ function restartTunnel(port: number) {
   spawnTunnel(port).catch((e) => log("ERROR", `restartTunnel failed: ${e}`));
 }
 
+/**
+ * Tear the tunnel down for good because the master switch went off — as opposed
+ * to `restartTunnel`, which kills in order to respawn.
+ *
+ * Bumping the generation is the load-bearing part: the running spawn loop is
+ * awaiting its child's `exited` and would otherwise treat the kill as a crash
+ * and respawn. The probe needs no stopping — it returns early once there is no
+ * `tunnelUrl` and no live process.
+ */
+function stopTunnelForDisable(): void {
+  tunnelGeneration++;
+  cancelNamedRetry();
+  namedRetryAttempt = 0;
+  if (tunnelChild) { try { tunnelChild.kill(); } catch {} tunnelChild = null; }
+  if (adoptedTunnelPid) { try { process.kill(adoptedTunnelPid, "SIGTERM"); } catch {} adoptedTunnelPid = null; }
+  tunnelUrl = null;
+  tunnelPort = null;
+  updateStatus({ shareUrl: null, tunnelPid: null, tunnelPort: null });
+}
+
 // ─── Server shutdown ───────────────────────────────────────────────────
 // On Windows the server's Claude SDK grandchildren are node-spawned (the
 // provider forces `executable: "node"`), so they live OUTSIDE Bun's job
@@ -855,6 +880,14 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   // setup, disable, or token rotation since the last spawn must be picked up
   // before deciding what to spawn next.
   namedTunnelMode = await readTunnelConfigFresh();
+  // The freshest possible view of the master switch, so consult it here rather than
+  // relying on all six call sites remembering to. Two of them — the Windows
+  // leaked-probe-handle restart and the edge probe's respawns — do not, and a
+  // respawn is exactly when a switch flipped since the last spawn should take hold.
+  if (!namedTunnelMode.enabled) {
+    log("INFO", "Public tunnel is switched off — not spawning cloudflared");
+    return;
+  }
 
   let bin: string;
   try {
@@ -1206,6 +1239,10 @@ async function probeNamedTunnelHealth(): Promise<boolean> {
 }
 
 function startTunnelProbe() {
+  // Idempotent: a supervisor that booted with the tunnel switched off never
+  // started this, and turning the switch on has to be able to start it then —
+  // without leaving a second interval behind on the boots that did start it.
+  if (tunnelProbeTimer) return;
   tunnelProbeTimer = setInterval(async () => {
     if (shuttingDown || !tunnelUrl) { tunnelFailCount = 0; return; }
     if (!tunnelChild && !adoptedTunnelPid) { tunnelFailCount = 0; return; }
@@ -2049,7 +2086,16 @@ export async function runSupervisor(opts: {
         // restarts the ladder so a later transient failure gets a full budget.
         cancelNamedRetry();
         namedRetryAttempt = 0;
-        restartTunnel(_opts.port);
+        // `retunnel` is also how the master switch is applied without a
+        // restart, so it has to be able to mean "stop" and not only "respawn".
+        tunnelSharingEnabled = _opts.share && namedTunnelMode.enabled;
+        if (tunnelSharingEnabled) {
+          startTunnelProbe();
+          restartTunnel(_opts.port);
+        } else {
+          log("INFO", "Tunnel switched off — tearing down the running tunnel");
+          stopTunnelForDisable();
+        }
         // Deliberate fall-through (no return): a bare `ppm restart` sends a
         // bare SIGUSR2 with no command file of its own, and a `retunnel` that
         // happens to still be unclaimed at that instant must not silently
@@ -2091,7 +2137,7 @@ export async function runSupervisor(opts: {
       log("ERROR", `Self-replace failed: ${result.error}, restarting children`);
       spawnServer(serverArgs, logFd);
       // Tunnel was kept alive during selfReplace; only respawn if dead
-      if (opts.share && !tunnelChild && !tunnelUrl) spawnTunnel(_opts.port);
+      if (tunnelSharingEnabled && !tunnelChild && !tunnelUrl) spawnTunnel(_opts.port);
     }
   });
 
@@ -2200,7 +2246,16 @@ export async function runSupervisor(opts: {
           tunnelFailCount = 0;
           cancelNamedRetry();
           namedRetryAttempt = 0;
-          restartTunnel(_opts.port);
+          // Same dual meaning as the POSIX path: this is how the master switch
+          // is applied live, so it must also be able to mean "stop".
+          tunnelSharingEnabled = _opts.share && cfg.enabled;
+          if (tunnelSharingEnabled) {
+            startTunnelProbe();
+            restartTunnel(_opts.port);
+          } else {
+            log("INFO", "Tunnel switched off — tearing down the running tunnel");
+            stopTunnelForDisable();
+          }
         });
       }
       else if (cmd.action === "upgrade") {
@@ -2209,7 +2264,7 @@ export async function runSupervisor(opts: {
           if (!result.success) {
             log("ERROR", `Self-replace failed: ${result.error}, restarting children`);
             spawnServer(serverArgs, logFd);
-            if (opts.share && !tunnelChild && !tunnelUrl) spawnTunnel(_opts.port);
+            if (tunnelSharingEnabled && !tunnelChild && !tunnelUrl) spawnTunnel(_opts.port);
           }
         });
       }
@@ -2229,12 +2284,34 @@ export async function runSupervisor(opts: {
   // tunnel's origin port (public URL continuity), so adoption state must be
   // settled first — the old order raced spawnServer's port selection.
   let tunnelAdopted = false;
-  if (opts.share) {
-    // Populate the cache BEFORE adoptTunnel/probe — an adopted tunnel skips
-    // spawnTunnel entirely for this whole generation, so without this the
-    // cache would stay null (adoptTunnel's named-hostname gate always refuses,
-    // and the probe can never tell named from quick) until the next spawn.
+  // Populate the cache BEFORE adoptTunnel/probe — an adopted tunnel skips
+  // spawnTunnel entirely for this whole generation, so without this the
+  // cache would stay null (adoptTunnel's named-hostname gate always refuses,
+  // and the probe can never tell named from quick) until the next spawn.
+  // It also carries the master switch, so it is read before the gate rather
+  // than inside it.
+  // This read must not be able to decide whether the edge below gets spawned.
+  // It already did once: a `systemctl restart` brought this process up while
+  // the outgoing one still held the database's write lock, the rejection ended
+  // startup right here, and PPM ran for eight minutes with nothing listening on
+  // its public port — the server child came back on the health check, which has
+  // no equivalent for an edge that was never started in the first place.
+  //
+  // The fallback is sharing OFF, not the resolver's default: an absent config
+  // row means "on" (it predates the master switch), so defaulting would publish
+  // a tunnel for someone who had switched sharing off and whose config merely
+  // could not be read.
+  try {
     namedTunnelMode = await readTunnelConfigFresh();
+  } catch (e) {
+    log("ERROR", `Tunnel config unreadable — continuing with sharing off: ${e}`);
+    namedTunnelMode = resolveTunnelConfig({ enabled: false });
+  }
+  tunnelSharingEnabled = opts.share && namedTunnelMode.enabled;
+  if (opts.share && !tunnelSharingEnabled) {
+    log("INFO", "Tunnel off (tunnel.enabled = false) — no cloudflared will be started");
+  }
+  if (tunnelSharingEnabled) {
     // Defensive — already `false` at module init, but a fresh boot must never
     // start with an inherited restart-once budget "spent".
     namedProbeRestartAttempted = false;
@@ -2250,6 +2327,12 @@ export async function runSupervisor(opts: {
     // Sweep leftover cloudflared orphans (crashed supervisors / pre-fix stale
     // loops) so they don't saturate the network and false-trigger regeneration.
     await reapOrphanedTunnels(tunnelAdopted ? adoptedTunnelPid : null);
+  } else if (opts.share) {
+    // Switched off while a tunnel from an earlier boot is still alive: nothing
+    // adopts or probes it now, so it would go on serving a stale origin with no
+    // supervisor watching it.
+    killStaleTunnel();
+    await reapOrphanedTunnels(null);
   }
 
   // The edge owns the public port, so it must exist before anything else tries
@@ -2298,7 +2381,7 @@ export async function runSupervisor(opts: {
 
   // Spawn server + (fresh) tunnel in parallel
   const promises: Promise<void>[] = [spawnServer(serverArgs, logFd)];
-  if (opts.share && !tunnelAdopted) promises.push(spawnTunnel(_opts.port));
+  if (tunnelSharingEnabled && !tunnelAdopted) promises.push(spawnTunnel(_opts.port));
 
   await Promise.all(promises);
 

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

@@ -0,0 +1,252 @@
+/**
+ * Mission Center's CPU page, from `/sys/devices/system/cpu`, `/proc` and hwmon.
+ * Split in two: the static facts go in the hardware inventory (they cannot change
+ * while the kernel is up), the live ones ride the tick.
+ *
+ * Package power is RAPL's cumulative energy counter, so it needs two samples like
+ * any other rate — the caller keeps the previous one.
+ */
+import type { CpuInfo } from "../../types/system-hardware.ts";
+import { readAttr, readNumber, realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+
+export const SYS_CPU = "/sys/devices/system/cpu";
+const RAPL_DIR = "/sys/class/powercap";
+const HWMON_DIR = "/sys/class/hwmon";
+
+/** `/sys/class/hwmon/<h>/name` of the package sensor, in preference order. */
+const PACKAGE_SENSORS = ["coretemp", "k10temp", "zenpower"];
+
+// ---------------------------------------------------------------- static
+
+export function readCpuInfo(fs: LinuxFs = realLinuxFs): CpuInfo | undefined {
+  const cpuinfo = fs.read("/proc/cpuinfo");
+  if (!cpuinfo) return undefined;
+  const topology = parseCpuinfoTopology(cpuinfo);
+  const caches = readCacheSizes(fs);
+
+  return {
+    name: topology.model,
+    sockets: topology.sockets,
+    physicalCores: topology.physicalCores,
+    logicalCores: topology.logicalCores,
+    ...defined("baseMHz", khzToMhz(readNumber(fs, `${SYS_CPU}/cpu0/cpufreq/base_frequency`))),
+    ...defined("maxMHz", khzToMhz(readNumber(fs, `${SYS_CPU}/cpu0/cpufreq/cpuinfo_max_freq`))),
+    ...defined("virtualization", virtualizationName(topology.flags)),
+    isVirtualMachine: topology.flags.has("hypervisor"),
+    ...defined("l1CacheBytes", caches.l1),
+    ...defined("l2CacheBytes", caches.l2),
+    ...defined("l3CacheBytes", caches.l3),
+    ...defined("freqDriver", readAttr(fs, `${SYS_CPU}/cpu0/cpufreq/scaling_driver`)),
+    ...defined("freqGovernor", readAttr(fs, `${SYS_CPU}/cpu0/cpufreq/scaling_governor`)),
+    ...defined("powerPreference", readAttr(fs, `${SYS_CPU}/cpu0/cpufreq/energy_performance_preference`)),
+  };
+}
+
+export interface CpuTopology {
+  model: string;
+  logicalCores: number;
+  physicalCores: number;
+  sockets: number;
+  flags: Set<string>;
+}
+
+/** `/proc/cpuinfo` is one block per logical CPU. Sockets are the distinct
+ *  `physical id`s; physical cores are `cpu cores` summed once per socket, which
+ *  is right for a hybrid part too — the kernel reports the real count there. */
+export function parseCpuinfoTopology(text: string): CpuTopology {
+  let model = "";
+  const flags = new Set<string>();
+  const coresPerSocket = new Map<string, number>();
+  let logicalCores = 0;
+  let currentSocket = "0";
+
+  for (const line of text.split("\n")) {
+    const sep = line.indexOf(":");
+    if (sep < 0) continue;
+    const key = line.slice(0, sep).trim();
+    const value = line.slice(sep + 1).trim();
+    if (key === "processor") { logicalCores++; currentSocket = "0"; }
+    else if (key === "model name" && !model) model = value;
+    else if (key === "physical id") currentSocket = value;
+    else if (key === "cpu cores") coresPerSocket.set(currentSocket, Number(value) || 0);
+    else if (key === "flags" && flags.size === 0) for (const f of value.split(/\s+/)) flags.add(f);
+  }
+
+  const sockets = Math.max(coresPerSocket.size, 1);
+  let physicalCores = 0;
+  for (const n of coresPerSocket.values()) physicalCores += n;
+  return { model, logicalCores, physicalCores: physicalCores || logicalCores, sockets, flags };
+}
+
+/** Intel publishes `vmx`, AMD `svm`. Mission Center prints the marketing name. */
+export function virtualizationName(flags: ReadonlySet<string>): string | undefined {
+  if (flags.has("vmx")) return "Intel VT-x";
+  if (flags.has("svm")) return "AMD-V";
+  return undefined;
+}
+
+/** Cache sizes summed over DISTINCT caches: every CPU sharing one reports the
+ *  same `shared_cpu_list`, so that string is the deduplication key. L1 combines
+ *  data and instruction, which is what Mission Center shows as one figure. */
+export function readCacheSizes(fs: Pick<LinuxFs, "list" | "read">): { l1?: number; l2?: number; l3?: number } {
+  const seen = new Set<string>();
+  const totals = new Map<number, number>();
+
+  for (const cpu of fs.list(SYS_CPU) ?? []) {
+    if (!/^cpu\d+$/.test(cpu)) continue;
+    const cacheDir = `${SYS_CPU}/${cpu}/cache`;
+    for (const index of fs.list(cacheDir) ?? []) {
+      if (!index.startsWith("index")) continue;
+      const dir = `${cacheDir}/${index}`;
+      const level = readNumber(fs, `${dir}/level`);
+      const size = parseCacheSize(readAttr(fs, `${dir}/size`));
+      const shared = readAttr(fs, `${dir}/shared_cpu_list`);
+      if (level === undefined || size === undefined) continue;
+      const key = `${level}:${readAttr(fs, `${dir}/type`) ?? ""}:${shared ?? `${cpu}/${index}`}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      totals.set(level, (totals.get(level) ?? 0) + size);
+    }
+  }
+  return {
+    ...defined("l1", totals.get(1)),
+    ...defined("l2", totals.get(2)),
+    ...defined("l3", totals.get(3)),
+  };
+}
+
+/** sysfs writes cache sizes as "48K" / "30720K" / "16M". */
+export function parseCacheSize(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const m = /^(\d+)([KMG])?$/i.exec(raw.trim());
+  if (!m) return undefined;
+  const n = Number(m[1]);
+  const unit = (m[2] ?? "").toUpperCase();
+  const scale = unit === "G" ? 1024 ** 3 : unit === "M" ? 1024 ** 2 : unit === "K" ? 1024 : 1;
+  return n * scale;
+}
+
+// ---------------------------------------------------------------- live
+
+export interface RaplSample {
+  microjoules: number;
+  atSec: number;
+}
+
+export interface CpuLiveExtras {
+  currentMHz?: number;
+  tempC?: number;
+  powerW?: number;
+  threadCount?: number;
+  handleCount?: number;
+  uptimeSec?: number;
+}
+
+export interface CpuLiveResult {
+  extras: CpuLiveExtras;
+  /** RAPL baseline to hand back on the next tick; null when the host has none. */
+  rapl: RaplSample | null;
+}
+
+export function collectCpuLive(
+  prevRapl: RaplSample | null,
+  fs: Pick<LinuxFs, "list" | "read"> = realLinuxFs,
+  now: () => number = Date.now,
+): CpuLiveResult {
+  const atSec = now() / 1000;
+  const rapl = readRaplEnergy(fs, atSec);
+  const loadavg = fs.read("/proc/loadavg") ?? "";
+
+  return {
+    rapl,
+    extras: {
+      ...defined("currentMHz", meanCurrentMHz(fs)),
+      ...defined("tempC", readPackageTempC(fs)),
+      ...defined("powerW", raplWatts(prevRapl, rapl)),
+      ...defined("threadCount", parseThreadCount(loadavg)),
+      ...defined("handleCount", parseHandleCount(fs.read("/proc/sys/fs/file-nr"))),
+      ...defined("uptimeSec", parseUptimeSec(fs.read("/proc/uptime"))),
+    },
+  };
+}
+
+/** Mean of every online core's current clock. `scaling_cur_freq` is what the
+ *  governor asked for; `cpuinfo_cur_freq` needs root on some drivers, so it is
+ *  never read here. */
+export function meanCurrentMHz(fs: Pick<LinuxFs, "list" | "read">): number | undefined {
+  let sum = 0;
+  let count = 0;
+  for (const cpu of fs.list(SYS_CPU) ?? []) {
+    if (!/^cpu\d+$/.test(cpu)) continue;
+    const khz = readNumber(fs, `${SYS_CPU}/${cpu}/cpufreq/scaling_cur_freq`);
+    if (khz === undefined) continue;
+    sum += khz;
+    count++;
+  }
+  return count > 0 ? Math.round(sum / count / 1000) : undefined;
+}
+
+/** The package sensor, in preference order; `temp1_input` is the package on
+ *  coretemp ("Package id 0") and the die on k10temp. */
+export function readPackageTempC(fs: Pick<LinuxFs, "list" | "read">): number | undefined {
+  const chips = fs.list(HWMON_DIR) ?? [];
+  for (const wanted of PACKAGE_SENSORS) {
+    for (const chip of chips) {
+      if (readAttr(fs, `${HWMON_DIR}/${chip}/name`) !== wanted) continue;
+      const milli = readNumber(fs, `${HWMON_DIR}/${chip}/temp1_input`);
+      if (milli !== undefined) return Math.round(milli / 100) / 10;
+    }
+  }
+  return undefined;
+}
+
+/** Sum of every RAPL package domain. Intel exposes `intel-rapl:N`, AMD the same
+ *  interface; a host with neither (a VM, an ARM board) reports no power at all. */
+export function readRaplEnergy(fs: Pick<LinuxFs, "list" | "read">, atSec: number): RaplSample | null {
+  let microjoules = 0;
+  let found = false;
+  for (const entry of fs.list(RAPL_DIR) ?? []) {
+    if (!/^intel-rapl:\d+$/.test(entry)) continue;
+    const name = readAttr(fs, `${RAPL_DIR}/${entry}/name`) ?? "";
+    if (!name.startsWith("package")) continue;
+    const uj = readNumber(fs, `${RAPL_DIR}/${entry}/energy_uj`);
+    if (uj === undefined) continue;
+    microjoules += uj;
+    found = true;
+  }
+  return found ? { microjoules, atSec } : null;
+}
+
+/** Watts over the interval. The counter wraps at `max_energy_range_uj`, which a
+ *  negative delta reveals — one unmeasured tick is better than a false spike. */
+export function raplWatts(prev: RaplSample | null, next: RaplSample | null): number | undefined {
+  if (!prev || !next) return undefined;
+  const dt = next.atSec - prev.atSec;
+  const dj = next.microjoules - prev.microjoules;
+  if (!(dt > 0) || dj < 0) return undefined;
+  return Math.round(dj / dt / 1000) / 1000;
+}
+
+/** `/proc/loadavg`'s fourth field is `running/total` kernel tasks. */
+export function parseThreadCount(loadavg: string): number | undefined {
+  const m = /\s(\d+)\/(\d+)\s/.exec(` ${loadavg.trim()} `);
+  const n = m ? Number(m[2]) : NaN;
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/** `/proc/sys/fs/file-nr`: allocated, free, max. The first is the live count. */
+export function parseHandleCount(fileNr: string | null): number | undefined {
+  const n = Number(fileNr?.trim().split(/\s+/)[0]);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+export function parseUptimeSec(uptime: string | null): number | undefined {
+  const n = Number(uptime?.trim().split(/\s+/)[0]);
+  return Number.isFinite(n) ? Math.round(n) : undefined;
+}
+
+const khzToMhz = (khz: number | undefined) => (khz === undefined ? undefined : Math.round(khz / 1000));
+
+function defined<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
+  return value === undefined ? {} : ({ [key]: value } as Record<K, V>);
+}