@hienlh/ppm 0.18.8 → 0.18.10

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, "");
+}

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