@hienlh/ppm 0.18.7 → 0.18.9

package/src/services/system-metrics/powershell-session.ts

@@ -0,0 +1,182 @@
+/**
+ * ONE long-lived PowerShell child for the polling lifetime.
+ *
+ * Why not spawn per tick: every `powershell.exe` spawn costs a 32 MiB allocator
+ * segment Bun never returns to the OS (see windows-process-tree.ts) and ~400 ms
+ * versus ~140 ms in-session. Requests are serialised, time-limited, and a
+ * failed child may be restarted only a fixed number of times for the server's
+ * whole life — a refilling budget would re-arm against a permanently wedged
+ * CIM provider and spawn hundreds of times a day.
+ */
+import { defaultPsSpawner, encodeRequestLine, type PsChild, type PsSpawner } from "./powershell-session-bootstrap.ts";
+
+export { POWERSHELL_BOOTSTRAP, defaultPsSpawner, type PsChild, type PsSpawner } from "./powershell-session-bootstrap.ts";
+
+export interface PowerShellSessionOptions {
+  spawn?: PsSpawner;
+  /** Measured p95 real tick is 206 ms; 5 s only fires on a wedged CIM provider. */
+  requestTimeoutMs?: number;
+  /** Absolute cap for the server's lifetime — a refilling budget would re-arm
+   *  against a permanently wedged provider and spawn hundreds of times a day. */
+  maxRestarts?: number;
+  /** Child working set creeps over hours; a scheduled recycle is free of the budget. */
+  recycleAfterMs?: number;
+  now?: () => number;
+}
+
+export const PS_DISABLED_WARNING = "Windows process collection disabled after repeated PowerShell failures";
+
+export class PsSessionBusyError extends Error { constructor() { super("PowerShell request already in flight"); } }
+export class PsSessionDisabledError extends Error { constructor() { super(PS_DISABLED_WARNING); } }
+
+interface Pending { id: string; resolve: (s: string) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }
+
+/** Anything larger than this without an end marker is not a reply we want. */
+const MAX_BUFFER_CHARS = 8 * 1024 * 1024;
+
+export class PowerShellSession {
+  private readonly spawn: PsSpawner;
+  private readonly requestTimeoutMs: number;
+  private readonly maxRestarts: number;
+  private readonly recycleAfterMs: number;
+  private readonly now: () => number;
+
+  private child: PsChild | null = null;
+  private generation = 0;
+  private spawnedAt = 0;
+  private restarts = 0;
+  private everStarted = false;
+  private previousDiedAbnormally = false;
+  private disabled = false;
+  private buffer = "";
+  private pending: Pending | null = null;
+  private nextId = 1;
+
+  constructor(opts: PowerShellSessionOptions = {}) {
+    this.spawn = opts.spawn ?? defaultPsSpawner;
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 5000;
+    this.maxRestarts = opts.maxRestarts ?? 5;
+    this.recycleAfterMs = opts.recycleAfterMs ?? 6 * 60 * 60 * 1000;
+    this.now = opts.now ?? Date.now;
+  }
+
+  isHealthy(): boolean { return this.child !== null && !this.disabled; }
+  isDisabled(): boolean { return this.disabled; }
+  isBusy(): boolean { return this.pending !== null; }
+  restartCount(): number { return this.restarts; }
+  childPid(): number | null { return this.child?.pid ?? null; }
+
+  request(script: string): Promise<string> {
+    if (this.disabled) return Promise.reject(new PsSessionDisabledError());
+    if (this.pending) return Promise.reject(new PsSessionBusyError());
+    if (this.child && this.now() - this.spawnedAt >= this.recycleAfterMs) this.stop();
+    if (!this.child) {
+      try { this.start(); } catch (e) { return Promise.reject(e as Error); }
+    }
+    const child = this.child!;
+    const id = String(this.nextId++);
+    return new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(() => this.onFailure(`PowerShell request timed out after ${this.requestTimeoutMs} ms`), this.requestTimeoutMs);
+      this.pending = { id, resolve, reject, timer };
+      try {
+        child.stdin.write(encodeRequestLine(id, script));
+        child.stdin.flush?.();
+      } catch (e) {
+        this.onFailure(`PowerShell stdin write failed: ${(e as Error).message}`);
+      }
+    });
+  }
+
+  /** Write nothing, kill, clear. Safe to call repeatedly. No subscribers must mean no child. */
+  stop(): void {
+    this.teardown(new Error("PowerShell session stopped"));
+  }
+
+  private teardown(pendingError: Error): void {
+    const child = this.child;
+    this.child = null;
+    this.generation++;
+    this.buffer = "";
+    this.failPending(pendingError);
+    if (child) { try { child.kill(); } catch { /* already gone */ } }
+  }
+
+  private start(): void {
+    if (this.everStarted && this.previousDiedAbnormally) {
+      if (this.restarts >= this.maxRestarts) {
+        this.disabled = true;
+        throw new PsSessionDisabledError();
+      }
+      this.restarts++;
+    }
+    this.everStarted = true;
+    this.previousDiedAbnormally = false;
+    const gen = ++this.generation;
+    const child = this.spawn();
+    this.child = child;
+    this.spawnedAt = this.now();
+    this.buffer = "";
+    void this.pump(child, gen);
+    void drain(child.stderr);
+    child.exited.then(
+      () => { if (gen === this.generation) this.onFailure("PowerShell exited unexpectedly"); },
+      () => { if (gen === this.generation) this.onFailure("PowerShell exited unexpectedly"); },
+    );
+  }
+
+  private async pump(child: PsChild, gen: number): Promise<void> {
+    const reader = child.stdout.getReader();
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done || gen !== this.generation) break;
+        this.buffer += decoder.decode(value, { stream: true });
+        this.scan();
+      }
+    } catch { /* stream torn down with the child */ }
+    if (gen === this.generation) this.onFailure("PowerShell stdout closed");
+  }
+
+  /** Resolve the pending request on ITS marker; discard any stale marker's output. */
+  private scan(): void {
+    while (true) {
+      const m = /__END_(\d+)__/.exec(this.buffer);
+      if (!m) {
+        if (this.buffer.length > MAX_BUFFER_CHARS) this.buffer = "";
+        return;
+      }
+      const reply = this.buffer.slice(0, m.index);
+      this.buffer = this.buffer.slice(m.index + m[0].length).replace(/^\r?\n/, "");
+      const p = this.pending;
+      if (p && p.id === m[1]) {
+        this.pending = null;
+        clearTimeout(p.timer);
+        p.resolve(reply);
+      }
+    }
+  }
+
+  /** Timeout, exit or write failure: kill, mark for a counted restart, reject. */
+  private onFailure(reason: string): void {
+    this.previousDiedAbnormally = true;
+    this.teardown(new Error(reason));
+  }
+
+  private failPending(error: Error): void {
+    const p = this.pending;
+    if (!p) return;
+    this.pending = null;
+    clearTimeout(p.timer);
+    p.reject(error);
+  }
+}
+
+/** A full stderr pipe would block the child; read and discard it. */
+async function drain(stream: ReadableStream<Uint8Array> | null | undefined): Promise<void> {
+  if (!stream) return;
+  try {
+    const reader = stream.getReader();
+    while (!(await reader.read()).done) { /* discard */ }
+  } catch { /* closed with the child */ }
+}

package/src/services/system-metrics/ppm-process-ownership.ts

@@ -0,0 +1,34 @@
+/**
+ * The cosmetic `ppm` flag: PPM's roots (server + supervisor/parent), every
+ * descendant of those roots, and the app share tunnel. Drives the "PPM only"
+ * filter in the UI. It is NOT a safety mechanism — the kill guard walks the
+ * ppid maps itself and never keys off this flag.
+ */
+import { collectDescendants } from "./kill-guard.ts";
+
+export interface PpmOwnershipInput {
+  roots: ReadonlySet<number>;
+  /** Extra pids owned outright (the share tunnel, preview tunnels). */
+  extraPids: readonly number[];
+  ppidOf: ReadonlyMap<number, number>;
+  startedAtOf: ReadonlyMap<number, number>;
+}
+
+/**
+ * Descendants follow ppid links only while the parent started no later than
+ * the child — Windows never clears a dead parent's ppid reference, so an
+ * unguarded walk would adopt whatever unrelated process later reused that pid.
+ */
+export function computePpmPids(input: PpmOwnershipInput): Set<number> {
+  const out = new Set<number>();
+  const ctx = { ppidOf: input.ppidOf, startedAtOf: input.startedAtOf };
+  for (const root of input.roots) {
+    if (!input.ppidOf.has(root)) continue;
+    out.add(root);
+    for (const pid of collectDescendants(root, ctx)) out.add(pid);
+  }
+  for (const pid of input.extraPids) {
+    if (input.ppidOf.has(pid)) out.add(pid);
+  }
+  return out;
+}

package/src/services/system-metrics/ppm-protected-pids.ts

@@ -0,0 +1,84 @@
+/**
+ * Which pids the kill guard must never end: the PPM server, its supervisor (or
+ * plain parent), the edge forwarder, the app share tunnel and every per-port
+ * preview tunnel PPM spawned.
+ *
+ * `status.json` is unvalidated disk state — `supervisorPid` is only cleared by
+ * a fresh supervisor start, `bun dev:server` has no supervisor at all, and dev
+ * and prod share `~/.ppm`. So every candidate is dropped unless it is alive
+ * right now, and a cloudflared candidate must also carry the cloudflared image
+ * name (a spoofed command line cannot buy protection). A dead or recycled
+ * `supervisorPid` therefore counts as absent and the real parent is protected.
+ */
+import { readStatus } from "../supervisor-state.ts";
+import { activeTunnels } from "../../server/routes/tunnel-spawn.ts";
+
+export interface ProtectedPidsInput {
+  status: Record<string, unknown>;
+  selfPid: number;
+  parentPid: number;
+  /** Extra cloudflared pids PPM spawned itself (per-port preview tunnels). */
+  portTunnelPids: readonly number[];
+  isAlive: (pid: number) => boolean;
+  /** Lowercased, extension-free image name for a live pid, or undefined. */
+  nameOf: (pid: number) => string | undefined;
+}
+
+export interface ProtectedPids {
+  /** Everything the kill guard refuses outright. */
+  pids: Set<number>;
+  /** PPM's own roots: server + supervisor/parent. Grouping boundaries and the
+   *  seeds of the `ppm` ownership walk. */
+  roots: Set<number>;
+  /** This server's own pid — lets the UI tell "this server" from another PPM
+   *  instance on the same machine (dev next to prod). */
+  selfPid: number;
+}
+
+function pidOf(v: unknown): number | null {
+  return typeof v === "number" && Number.isInteger(v) && v > 0 ? v : null;
+}
+
+/** Images a PPM supervisor / edge forwarder can run as: the Bun runtime, Node,
+ *  or the compiled single binary. A live pid with any other image is a
+ *  recycled `status.json` entry, not PPM. */
+const PPM_IMAGE_NAMES: ReadonlySet<string> = new Set(["bun", "node", "ppm"]);
+
+export function resolveProtectedPids(input: ProtectedPidsInput): ProtectedPids {
+  const { status, isAlive, nameOf } = input;
+  const roots = new Set<number>([input.selfPid]);
+  const isPpmImage = (pid: number) => isAlive(pid) && PPM_IMAGE_NAMES.has(nameOf(pid) ?? "");
+  const cloudflared = (pid: number) => isAlive(pid) && nameOf(pid) === "cloudflared";
+
+  const supervisor = pidOf(status.supervisorPid);
+  if (supervisor !== null && isPpmImage(supervisor)) roots.add(supervisor);
+  else if (input.parentPid > 0 && isAlive(input.parentPid)) roots.add(input.parentPid);
+
+  const pids = new Set<number>(roots);
+
+  const edge = pidOf(status.edgePid);
+  if (edge !== null && isPpmImage(edge)) pids.add(edge);
+
+  const tunnel = pidOf(status.tunnelPid);
+  if (tunnel !== null && cloudflared(tunnel)) pids.add(tunnel);
+  for (const pid of input.portTunnelPids) {
+    if (pid > 0 && cloudflared(pid)) pids.add(pid);
+  }
+
+  return { pids, roots, selfPid: input.selfPid };
+}
+
+/** Live-state wrapper: reads `status.json` and the preview-tunnel registry. */
+export function resolveProtectedPidsLive(
+  isAlive: (pid: number) => boolean,
+  nameOf: (pid: number) => string | undefined,
+): ProtectedPids {
+  return resolveProtectedPids({
+    status: readStatus(),
+    selfPid: process.pid,
+    parentPid: process.ppid,
+    portTunnelPids: [...activeTunnels.values()].map((t) => t.pid),
+    isAlive,
+    nameOf,
+  });
+}

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

@@ -0,0 +1,141 @@
+/**
+ * macOS process collector via `ps` (cheap there, no leak, no `/proc`).
+ *
+ * Every tick: `pid ppid etime time rss comm` with `comm` LAST because on macOS
+ * it is the full executable path and may contain spaces ("Google Chrome").
+ * Every 30 s: `pid args` for command lines, merged by pid — the same slow
+ * cadence Windows uses for `CommandLine`, and it keeps the per-tick call to one
+ * `ps` whose columns can be parsed unambiguously.
+ * UNVERIFIED on real macOS hardware; a parse miss yields a warning, never garbage.
+ */
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+import type { ProcessCollection, ProcessCollector, RawProcessRow } from "./process-collector-types.ts";
+import { createStickyColumns } from "./process-collector-types.ts";
+import type { ProcessNetCollector } from "./process-net-collector-darwin.ts";
+
+export const DARWIN_TICK_ARGV = ["ps", "-Ao", "pid=,ppid=,etime=,time=,rss=,comm="];
+export const DARWIN_ARGS_ARGV = ["ps", "-Ao", "pid=,args="];
+export const DARWIN_ARGS_REFRESH_MS = 30_000;
+const PS_TIMEOUT_MS = 5000;
+
+/** `[[dd-]hh:]mm:ss[.cs]` → milliseconds; NaN-free (garbage → 0). */
+export function parsePsCpuTime(text: string): number {
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+(?:\.\d+)?)$/.exec(text.trim());
+  if (!m) return 0;
+  const days = Number(m[1] ?? 0);
+  const hours = Number(m[2] ?? 0);
+  const minutes = Number(m[3]);
+  const seconds = Number(m[4]);
+  const total = ((days * 24 + hours) * 60 + minutes) * 60 + seconds;
+  return Number.isFinite(total) ? Math.round(total * 1000) : 0;
+}
+
+const TICK_LINE = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\d+)\s+(.*)$/;
+
+export function parseDarwinPsTick(text: string, now: number): RawProcessRow[] {
+  const rows: RawProcessRow[] = [];
+  for (const line of text.split("\n")) {
+    const m = TICK_LINE.exec(line);
+    if (!m) continue;
+    const pid = Number(m[1]);
+    if (pid <= 0) continue;
+    const elapsedMs = parsePsCpuTime(m[3]!);
+    const comm = m[6]!.trim();
+    rows.push({
+      pid,
+      ppid: Number(m[2]),
+      name: comm.slice(comm.lastIndexOf("/") + 1) || comm || String(pid),
+      command: null,
+      cpuMs: parsePsCpuTime(m[4]!),
+      ramMB: Number(m[5]) / 1024,
+      // etime is 1 s resolution: coarse, but enough as an identity guard.
+      startedAt: elapsedMs > 0 ? Math.round((now - elapsedMs) / 1000) * 1000 : 0,
+    });
+  }
+  return rows;
+}
+
+export function parseDarwinPsArgs(text: string): Map<number, string> {
+  const out = new Map<number, string>();
+  for (const line of text.split("\n")) {
+    const m = /^\s*(\d+)\s+(.+)$/.exec(line);
+    if (m) out.set(Number(m[1]), m[2]!.trim());
+  }
+  return out;
+}
+
+/**
+ * `etime` ticks in whole seconds while `now` has ms, so `now - etime` jitters by
+ * up to a second between ticks. Pin each pid to the first value seen so the CPU
+ * delta key `${pid}:${startedAt}` stays stable; a jump beyond the jitter means
+ * the pid really was recycled.
+ */
+export function stabilizeStartedAt(rows: RawProcessRow[], memo: Map<number, number>): RawProcessRow[] {
+  const seen = new Set<number>();
+  for (const r of rows) {
+    seen.add(r.pid);
+    const cached = memo.get(r.pid);
+    if (cached !== undefined && Math.abs(cached - r.startedAt) <= 2000) r.startedAt = cached;
+    else memo.set(r.pid, r.startedAt);
+  }
+  for (const pid of memo.keys()) if (!seen.has(pid)) memo.delete(pid);
+  return rows;
+}
+
+export interface DarwinProcessCollectorOptions {
+  /** Omitted or null → no per-process network sample. The production wiring in
+   *  `system-metrics-platform.ts` injects it, so a unit test never spawns
+   *  `nettop` by accident. */
+  net?: ProcessNetCollector | null;
+}
+
+export function createDarwinProcessCollector(
+  run: Runner = defaultRunner,
+  now: () => number = Date.now,
+  opts: DarwinProcessCollectorOptions = {},
+): ProcessCollector {
+  let argsByPid = new Map<number, string>();
+  let lastArgsAt = Number.NEGATIVE_INFINITY;
+  const startedAtMemo = new Map<number, number>();
+  const net = opts.net ?? null;
+  const observeColumns = createStickyColumns();
+
+  return {
+    stop: () => {},
+    async collect(): Promise<ProcessCollection> {
+      const warnings: string[] = [];
+      const tick = await run(DARWIN_TICK_ARGV, PS_TIMEOUT_MS);
+      if (tick.code !== 0 || tick.timedOut) {
+        return {
+          rows: [],
+          columns: observeColumns({}),
+          warnings: [`Process list unavailable: ps exited ${tick.code ?? "on timeout"}`],
+        };
+      }
+      const t = now();
+      if (t - lastArgsAt >= DARWIN_ARGS_REFRESH_MS) {
+        const args = await run(DARWIN_ARGS_ARGV, PS_TIMEOUT_MS);
+        if (args.code === 0 && !args.timedOut) {
+          argsByPid = parseDarwinPsArgs(args.stdout);
+          lastArgsAt = t;
+        } else {
+          warnings.push("Command lines unavailable: ps args query failed");
+        }
+      }
+      const netByPid = (await net?.collect()) ?? null;
+      const rows = stabilizeStartedAt(parseDarwinPsTick(tick.stdout, t), startedAtMemo)
+        .map((r) => ({
+          ...r,
+          command: argsByPid.get(r.pid) ?? null,
+          // nettop lists only processes with sockets, so a missing pid means
+          // "measured, no traffic".
+          netInBytes: netByPid ? netByPid.get(r.pid)?.inBytes ?? 0 : undefined,
+          netOutBytes: netByPid ? netByPid.get(r.pid)?.outBytes ?? 0 : undefined,
+        }));
+      if (rows.length === 0) warnings.push("Process list unavailable: ps output did not parse");
+      // Disk and GPU have no per-process source on macOS without private APIs.
+      return { rows, columns: observeColumns({ net: netByPid !== null }), warnings };
+    },
+  };
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Linux process collector over `/proc` — zero subprocesses for the table and
+ * the per-process disk counters. Reuses the repo's `readProcTable()`, which
+ * already anchors the `/proc/<pid>/stat` parse on the last `)` so a process
+ * name containing spaces cannot shift the fields.
+ *
+ * Per-process VRAM needs the one `nvidia-smi` call; per-process GPU busy % has
+ * no unprivileged source at all, so `gpuPct` stays undefined here.
+ */
+import { readProcTable, type ProcEntry } from "../proc-table-linux.ts";
+import type { ProcessCollection, ProcessCollector, RawProcessRow } from "./process-collector-types.ts";
+import { createStickyColumns } from "./process-collector-types.ts";
+import { readProcIoBytes, type ProcIoBytes } from "./process-io-linux.ts";
+import type { ProcessGpuMemoryCollector } from "./gpu-process-memory-nvidia.ts";
+
+const KB_PER_MB = 1024;
+
+export function procEntriesToRows(entries: readonly ProcEntry[]): RawProcessRow[] {
+  const rows: RawProcessRow[] = [];
+  for (const e of entries) {
+    if (e.pid <= 0) continue;
+    rows.push({
+      pid: e.pid,
+      ppid: e.ppid >= 0 ? e.ppid : -1,
+      name: e.comm,
+      // Kernel threads have an empty cmdline; the tick falls back to the name.
+      command: e.args || null,
+      cpuMs: e.cpuMs,
+      ramMB: e.rssKB / KB_PER_MB,
+      startedAt: Number.isFinite(e.startedAtMs) && e.startedAtMs > 0 ? Math.round(e.startedAtMs) : 0,
+    });
+  }
+  return rows;
+}
+
+export interface LinuxProcessCollectorOptions {
+  /** Injected so unit tests never touch a real `/proc`. */
+  readIo?: (pid: number) => ProcIoBytes | null;
+  /** Omitted or null → no per-process VRAM query at all. The production wiring
+   *  in `system-metrics-platform.ts` injects it; defaulting to a real collector
+   *  here would make an innocent unit test spawn `nvidia-smi`. */
+  gpuMemory?: ProcessGpuMemoryCollector | null;
+}
+
+export function createLinuxProcessCollector(
+  readTable: () => ProcEntry[] | null = readProcTable,
+  opts: LinuxProcessCollectorOptions = {},
+): ProcessCollector {
+  const readIo = opts.readIo ?? readProcIoBytes;
+  const gpuMemory = opts.gpuMemory ?? null;
+  const observeColumns = createStickyColumns();
+
+  return {
+    stop: () => {},
+    async collect(): Promise<ProcessCollection> {
+      const table = readTable();
+      if (!table) {
+        return { rows: [], columns: observeColumns({}), warnings: ["Process list unavailable: /proc is not readable"] };
+      }
+      const gpuMemByPid = (await gpuMemory?.collect()) ?? null;
+
+      let anyIo = false;
+      const rows = procEntriesToRows(table).map((r) => {
+        // EACCES for another user's process is expected, not an error: that row
+        // simply has no disk figures.
+        const io = readIo(r.pid);
+        if (io) anyIo = true;
+        return {
+          ...r,
+          diskReadBytes: io?.readBytes,
+          diskWriteBytes: io?.writeBytes,
+          // The query lists only processes holding VRAM, so a missing pid means
+          // "measured, holding none".
+          gpuMemMB: gpuMemByPid ? gpuMemByPid.get(r.pid) ?? 0 : undefined,
+        };
+      });
+
+      return {
+        rows,
+        columns: observeColumns({ disk: anyIo, gpu: gpuMemByPid !== null }),
+        warnings: [],
+      };
+    },
+  };
+}

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

@@ -0,0 +1,80 @@
+/** Shared shapes between the per-OS process collectors and the tick assembler. */
+import type { ProcessColumnAvailability } from "../../types/system-metrics.ts";
+import type { CounterSample } from "./rate-delta.ts";
+
+export interface RawProcessRow {
+  pid: number;
+  /** -1 when unknown. */
+  ppid: number;
+  /** Executable basename without extension, original case. */
+  name: string;
+  /** Raw command line, or null when unreadable / not yet fetched. */
+  command: string | null;
+  /** Cumulative CPU time (user + kernel), milliseconds. */
+  cpuMs: number;
+  ramMB: number;
+  /** Epoch ms UTC; 0 when unknown. */
+  startedAt: number;
+  /** CUMULATIVE per-process byte counters. The rows builder turns them into
+   *  bytes/second over the tick's wall interval, exactly like `cpuMs` — a
+   *  collector must never pre-compute a rate from them. `undefined` = this OS
+   *  (or this pid, e.g. an access-denied `/proc/<pid>/io`) does not expose it. */
+  diskReadBytes?: number;
+  diskWriteBytes?: number;
+  netInBytes?: number;
+  netOutBytes?: number;
+  /** ALREADY a rate, 0-100: the GPU busy counters carry their own high-resolution
+   *  clock, so their delta cannot use the wall interval and is computed by the
+   *  collector instead. */
+  gpuPct?: number;
+  gpuMemMB?: number;
+}
+
+export interface ProcessCollection {
+  rows: RawProcessRow[];
+  /** Windows piggybacks the disk/net counters on the same round trip. */
+  disk?: CounterSample | null;
+  net?: CounterSample | null;
+  /** Which optional per-process columns this collector can fill on this host.
+   *  Absent = none (the platform has no per-process disk/gpu/net source). */
+  columns?: ProcessColumnAvailability;
+  warnings: string[];
+}
+
+export interface ProcessCollector {
+  collect(): Promise<ProcessCollection>;
+  /** Release any long-lived child. Must be safe to call repeatedly. */
+  stop(): void;
+}
+
+/** Frozen: it is shared by every light-tier snapshot, so an accidental mutation
+ *  would rewrite history for all of them. */
+export const NO_PROCESS_COLUMNS: ProcessColumnAvailability = Object.freeze({ disk: false, gpu: false, net: false });
+
+/**
+ * Sticky column availability. A capability is advertised as soon as it has
+ * produced a value ONCE on this host and is never withdrawn: a single tick
+ * where the GPU perf provider hiccups (or where every process happens to be
+ * idle) must not make the UI drop a whole column and re-add it 2 s later.
+ * Machines do not lose hardware mid-session.
+ */
+export function createStickyColumns(): (seen: Partial<ProcessColumnAvailability>) => ProcessColumnAvailability {
+  const state: ProcessColumnAvailability = { ...NO_PROCESS_COLUMNS };
+  return (seen) => {
+    state.disk ||= seen.disk === true;
+    state.gpu ||= seen.gpu === true;
+    state.net ||= seen.net === true;
+    return { ...state };
+  };
+}
+
+/** A collector for platforms without process support: always empty. */
+export const EMPTY_PROCESS_COLLECTOR: ProcessCollector = {
+  collect: async () => ({ rows: [], warnings: [] }),
+  stop: () => {},
+};
+
+/** Windows image names carry an extension (`explorer.exe`); nothing else does. */
+export function stripExecutableExtension(name: string): string {
+  return name.replace(/\.(exe|com|scr|bat|cmd)$/i, "");
+}