@hienlh/ppm 0.18.7 → 0.18.9

package/src/services/system-metrics/disk-net-collector-darwin.ts

@@ -0,0 +1,75 @@
+/**
+ * macOS disk + net cumulative counters via `ioreg` and `netstat -ib`.
+ * Runner-injected; parsers are pure. UNVERIFIED on real macOS hardware — on any
+ * parse failure the result is `null` (→ `available:false` + warning), never 0.
+ */
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+import type { CounterSample } from "./rate-delta.ts";
+import type { DiskNetCounters } from "./disk-net-collector-linux.ts";
+
+/** Sum every `"Bytes (Read)"=N` / `"Bytes (Write)"=N` pair from `ioreg -rc IOBlockStorageDriver -w0`. */
+export function parseIoregBytes(text: string): { inBytes: number; outBytes: number } | null {
+  let read = 0;
+  let written = 0;
+  let matched = false;
+  for (const m of text.matchAll(/"Bytes \((Read|Write)\)"\s*=\s*(\d+)/g)) {
+    const n = Number(m[2]);
+    if (!Number.isFinite(n)) continue;
+    matched = true;
+    if (m[1] === "Read") read += n;
+    else written += n;
+  }
+  return matched ? { inBytes: read, outBytes: written } : null;
+}
+
+/**
+ * `netstat -ib` repeats an interface once per address family; only the
+ * `<Link#N>` row (the first per interface) carries the hardware counters, so
+ * summing every row would double-count. The Address column is blank on some
+ * virtual interfaces, so Ibytes/Obytes are located from the right-hand end.
+ */
+export function parseNetstatIb(text: string): { inBytes: number; outBytes: number } | null {
+  let rx = 0;
+  let tx = 0;
+  let matched = false;
+  const seen = new Set<string>();
+  for (const line of text.split("\n")) {
+    const f = line.trim().split(/\s+/);
+    if (f.length < 10) continue;
+    const iface = f[0]!;
+    if (iface === "Name" || iface.startsWith("lo") || seen.has(iface)) continue;
+    if (!(f[2] ?? "").startsWith("<Link#")) continue;
+    const ibytes = Number(f[f.length - 5]);
+    const obytes = Number(f[f.length - 2]);
+    if (!Number.isFinite(ibytes) || !Number.isFinite(obytes)) continue;
+    seen.add(iface);
+    matched = true;
+    rx += ibytes;
+    tx += obytes;
+  }
+  return matched ? { inBytes: rx, outBytes: tx } : null;
+}
+
+export async function collectDarwinDiskNet(run: Runner = defaultRunner, now: () => number = Date.now): Promise<DiskNetCounters> {
+  const warnings: string[] = [];
+  const atSec = now() / 1000;
+  let disk: CounterSample | null = null;
+  let net: CounterSample | null = null;
+
+  try {
+    const r = await run(["ioreg", "-rc", "IOBlockStorageDriver", "-w0"], 3000);
+    const parsed = r.code === 0 ? parseIoregBytes(r.stdout) : null;
+    if (parsed) disk = { ...parsed, atSec };
+  } catch { /* fall through to the warning */ }
+  if (!disk) warnings.push("Disk throughput unavailable: ioreg IOBlockStorageDriver statistics not readable");
+
+  try {
+    const r = await run(["netstat", "-ib"], 3000);
+    const parsed = r.code === 0 ? parseNetstatIb(r.stdout) : null;
+    if (parsed) net = { ...parsed, atSec };
+  } catch { /* fall through to the warning */ }
+  if (!net) warnings.push("Network throughput unavailable: netstat -ib not readable");
+
+  return { disk, net, warnings };
+}

package/src/services/system-metrics/disk-net-collector-linux.ts

@@ -0,0 +1,88 @@
+/**
+ * Linux disk + net cumulative counters from `/proc`. No subprocess; the reader
+ * is injectable so the parsers are fixture-tested without a real `/proc`.
+ */
+import { readFileSync } from "node:fs";
+import type { CounterSample } from "./rate-delta.ts";
+
+export interface DiskNetCounters {
+  disk: CounterSample | null;
+  net: CounterSample | null;
+  warnings: string[];
+}
+
+export type FileReader = (path: string) => string | null;
+
+const SECTOR_BYTES = 512;
+/** Whole devices only — partitions, `loop*`, `dm-*` would double-count every byte. */
+const WHOLE_DEVICE = /^(sd[a-z]+|nvme\d+n\d+|vd[a-z]+|mmcblk\d+|xvd[a-z]+)$/;
+
+/** `/proc/diskstats`: field 6 = sectors read, field 10 = sectors written (1-based after major/minor/name). */
+export function parseDiskstats(text: string): { inBytes: number; outBytes: number } | null {
+  let read = 0;
+  let written = 0;
+  let matched = false;
+  for (const line of text.split("\n")) {
+    const f = line.trim().split(/\s+/);
+    if (f.length < 10) continue;
+    const name = f[2] ?? "";
+    if (!WHOLE_DEVICE.test(name)) continue;
+    const r = Number(f[5]);
+    const w = Number(f[9]);
+    if (!Number.isFinite(r) || !Number.isFinite(w)) continue;
+    matched = true;
+    read += r;
+    written += w;
+  }
+  return matched ? { inBytes: read * SECTOR_BYTES, outBytes: written * SECTOR_BYTES } : null;
+}
+
+/** `/proc/net/dev`: `iface: rx_bytes … tx_bytes …` with rx at col 0 and tx at col 8 after the colon. `lo` excluded. */
+export function parseNetDev(text: string): { inBytes: number; outBytes: number } | null {
+  let rx = 0;
+  let tx = 0;
+  let matched = false;
+  for (const line of text.split("\n")) {
+    const colon = line.indexOf(":");
+    if (colon < 0) continue;
+    const iface = line.slice(0, colon).trim();
+    if (!iface || iface === "lo") continue;
+    const f = line.slice(colon + 1).trim().split(/\s+/);
+    if (f.length < 9) continue;
+    const r = Number(f[0]);
+    const t = Number(f[8]);
+    if (!Number.isFinite(r) || !Number.isFinite(t)) continue;
+    matched = true;
+    rx += r;
+    tx += t;
+  }
+  return matched ? { inBytes: rx, outBytes: tx } : null;
+}
+
+export const defaultFileReader: FileReader = (path) => {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+};
+
+/** `/proc` carries no counter clock, so the wall clock is the only option here. */
+export function collectLinuxDiskNet(read: FileReader = defaultFileReader, now: () => number = Date.now): DiskNetCounters {
+  const warnings: string[] = [];
+  const atSec = now() / 1000;
+
+  const diskText = read("/proc/diskstats");
+  const diskRaw = diskText ? parseDiskstats(diskText) : null;
+  if (!diskRaw) warnings.push("Disk throughput unavailable: /proc/diskstats has no whole-device rows");
+
+  const netText = read("/proc/net/dev");
+  const netRaw = netText ? parseNetDev(netText) : null;
+  if (!netRaw) warnings.push("Network throughput unavailable: /proc/net/dev unreadable");
+
+  return {
+    disk: diskRaw ? { ...diskRaw, atSec } : null,
+    net: netRaw ? { ...netRaw, atSec } : null,
+    warnings,
+  };
+}

package/src/services/system-metrics/disk-net-collector-windows.ts

@@ -0,0 +1,57 @@
+/**
+ * Windows disk + net counters — a PURE parser over the tagged lines the
+ * PowerShell session returns inside the per-tick process round trip. Spawns
+ * nothing; the raw `Win32_PerfRawData_*` classes cost 22 ms in-session versus
+ * a hard ≥1 s block for `Get-Counter`, and their class/property names are
+ * culture-invariant, so a localised Windows needs no special case.
+ *
+ *   D<TAB>DiskReadBytesPerSec<TAB>DiskWriteBytesPerSec<TAB>Timestamp_PerfTime<TAB>Frequency_PerfTime
+ *   N<TAB>Name<TAB>BytesReceivedPersec<TAB>BytesSentPersec<TAB>Timestamp_Sys100NS
+ */
+import type { CounterSample } from "./rate-delta.ts";
+
+/** Pseudo-adapters that would count local traffic; virtual NICs (Tailscale,
+ *  Hyper-V) stay in on purpose — dropping them would hide real tunnel traffic. */
+const EXCLUDED_NIC = /^(Loopback|isatap|Teredo)/i;
+
+export interface WindowsDiskNetCounters {
+  disk: CounterSample | null;
+  net: CounterSample | null;
+}
+
+export function parsePerfRawDiskNet(lines: readonly string[]): WindowsDiskNetCounters {
+  let disk: CounterSample | null = null;
+  let rx = 0;
+  let tx = 0;
+  let netTs = 0;
+  let nics = 0;
+
+  for (const line of lines) {
+    const f = line.split("\t");
+    if (f[0] === "D" && f.length >= 5) {
+      const read = Number(f[1]);
+      const write = Number(f[2]);
+      const ts = Number(f[3]);
+      const freq = Number(f[4]);
+      if ([read, write, ts, freq].every(Number.isFinite) && freq > 0) {
+        disk = { inBytes: read, outBytes: write, atSec: ts / freq };
+      }
+    } else if (f[0] === "N" && f.length >= 5) {
+      const name = f[1] ?? "";
+      if (EXCLUDED_NIC.test(name)) continue;
+      const recv = Number(f[2]);
+      const sent = Number(f[3]);
+      const ts = Number(f[4]);
+      if (![recv, sent, ts].every(Number.isFinite)) continue;
+      nics++;
+      rx += recv;
+      tx += sent;
+      netTs = Math.max(netTs, ts);
+    }
+  }
+
+  const net = nics > 0 && netTs > 0
+    ? { inBytes: rx, outBytes: tx, atSec: netTs / 1e7 }
+    : null;
+  return { disk, net };
+}

package/src/services/system-metrics/gpu-collector-nvidia.ts

@@ -0,0 +1,78 @@
+/**
+ * NVIDIA GPU utilisation + VRAM via a one-shot `nvidia-smi` per full-tier tick
+ * (measured 31 ms, ~60 bytes). No long-lived child: loop mode would keep an
+ * Optimus dGPU awake permanently, and the per-spawn leak this repo knows about
+ * concerns building a PowerShell process map inside Bun, not a tiny read.
+ */
+import type { GpuMetrics } from "../../types/system-metrics.ts";
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+
+export const NVIDIA_SMI_ARGV = [
+  "nvidia-smi",
+  "--query-gpu=name,utilization.gpu,memory.used,memory.total",
+  "--format=csv,noheader,nounits",
+];
+
+const SPAWN_TIMEOUT_MS = 3000;
+/** After this many consecutive failures the machine is treated as GPU-less for
+ *  the rest of the server's life — a machine does not grow a GPU. */
+const MAX_FAILURES = 3;
+
+/** One row per GPU: `name, util, memUsed, memTotal`. `[N/A]` fields become 0
+ *  rather than NaN; a row without a name is dropped. */
+export function parseNvidiaSmiCsv(text: string): GpuMetrics[] {
+  const out: GpuMetrics[] = [];
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const f = line.split(",").map((s) => s.trim());
+    const name = f[0] ?? "";
+    if (!name || f.length < 4) continue;
+    out.push({
+      name,
+      utilPercent: clampPercent(num(f[1])),
+      vramUsedMB: Math.max(0, Math.round(num(f[2]))),
+      vramTotalMB: Math.max(0, Math.round(num(f[3]))),
+    });
+  }
+  return out;
+}
+
+function num(s: string | undefined): number {
+  if (s === undefined || /^\[?N\/A\]?$/i.test(s)) return 0;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function clampPercent(v: number): number {
+  return Math.round(Math.min(100, Math.max(0, v)) * 10) / 10;
+}
+
+export interface GpuCollector {
+  collect(): Promise<GpuMetrics[]>;
+  /** True once the collector has given up (no binary / repeated failures). */
+  isDisabled(): boolean;
+}
+
+export function createNvidiaGpuCollector(run: Runner = defaultRunner): GpuCollector {
+  let failures = 0;
+  let disabled = false;
+  return {
+    isDisabled: () => disabled,
+    async collect() {
+      if (disabled) return [];
+      try {
+        const r = await run(NVIDIA_SMI_ARGV, SPAWN_TIMEOUT_MS);
+        if (r.code !== 0 || r.timedOut) throw new Error(r.stderr || `exit ${r.code}`);
+        failures = 0;
+        return parseNvidiaSmiCsv(r.stdout);
+      } catch {
+        // ENOENT (no NVIDIA driver) throws synchronously from the spawn; a
+        // present-but-broken nvidia-smi fails a few times, then is given up on.
+        if (++failures >= MAX_FAILURES) disabled = true;
+        return [];
+      }
+    },
+  };
+}

package/src/services/system-metrics/gpu-process-memory-nvidia.ts

@@ -0,0 +1,66 @@
+/**
+ * Per-process VRAM on NVIDIA via one `nvidia-smi --query-compute-apps` per
+ * full-tier tick (same one-shot shape and give-up rule as the whole-GPU
+ * collector next door).
+ *
+ * There is deliberately no per-process utilisation here: NVML exposes
+ * per-process SM utilisation only through accounting mode / MIG, which is off
+ * on consumer cards, so `gpuPct` stays undefined on Linux and only the memory
+ * column is filled.
+ */
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+
+export const NVIDIA_COMPUTE_APPS_ARGV = [
+  "nvidia-smi",
+  "--query-compute-apps=pid,used_memory",
+  "--format=csv,noheader,nounits",
+];
+
+const SPAWN_TIMEOUT_MS = 3000;
+/** A machine does not grow a GPU: after this many failures, stop asking. */
+const MAX_FAILURES = 3;
+
+/** `pid, usedMB` per row. A pid appearing twice (two GPUs) is summed. */
+export function parseComputeAppsCsv(text: string): Map<number, number> {
+  const byPid = new Map<number, number>();
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const f = line.split(",").map((s) => s.trim());
+    const pid = Number(f[0]);
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    // "[N/A]" / "[Not Supported]" appear on some drivers: the pid is real but
+    // the figure is not, so the row contributes 0 rather than NaN.
+    const mb = /^\d+(\.\d+)?$/.test(f[1] ?? "") ? Number(f[1]) : 0;
+    byPid.set(pid, (byPid.get(pid) ?? 0) + Math.max(0, Math.round(mb * 10) / 10));
+  }
+  return byPid;
+}
+
+export interface ProcessGpuMemoryCollector {
+  /** Null when the query is unavailable (no binary, repeated failures) — the
+   *  caller then leaves `gpuMemMB` undefined instead of publishing zeros. */
+  collect(): Promise<Map<number, number> | null>;
+  isDisabled(): boolean;
+}
+
+export function createNvidiaProcessMemoryCollector(run: Runner = defaultRunner): ProcessGpuMemoryCollector {
+  let failures = 0;
+  let disabled = false;
+  return {
+    isDisabled: () => disabled,
+    async collect() {
+      if (disabled) return null;
+      try {
+        const r = await run(NVIDIA_COMPUTE_APPS_ARGV, SPAWN_TIMEOUT_MS);
+        if (r.code !== 0 || r.timedOut) throw new Error(r.stderr || `exit ${r.code}`);
+        failures = 0;
+        return parseComputeAppsCsv(r.stdout);
+      } catch {
+        if (++failures >= MAX_FAILURES) disabled = true;
+        return null;
+      }
+    },
+  };
+}

package/src/services/system-metrics/gpu-process-usage-windows.ts

@@ -0,0 +1,138 @@
+/**
+ * Per-process GPU busy % and dedicated VRAM on Windows — a PURE parser plus the
+ * rate maths over the two tagged sections the per-tick PowerShell round trip
+ * already returns. Spawns nothing.
+ *
+ *   G<TAB>Name<TAB>UtilizationPercentage<TAB>Timestamp_Sys100NS   (busy > 0 only)
+ *   M<TAB>Name<TAB>DedicatedUsage
+ *
+ * `Name` is an instance path, not a friendly name:
+ *   pid_29876_luid_0x00000000_0x0000A1B2_phys_0_eng_3_engtype_3D   (GPUEngine)
+ *   pid_29876_luid_0x00000000_0x0000A1B2_phys_0                   (GPUProcessMemory)
+ *
+ * `UtilizationPercentage` is NOT a percentage despite the name: it is a raw
+ * cumulative 100 ns busy-time counter, which is why an absolute read is
+ * meaningless and it has to be differentiated against the counter's own
+ * `Timestamp_Sys100NS` clock rather than the tick's wall interval.
+ */
+import { toRate, type CounterSample } from "./rate-delta.ts";
+
+/** Both classes prefix the instance with the owning pid. */
+const PID_IN_INSTANCE = /(?:^|_)pid_(\d+)_/;
+const HUNDRED_NS_PER_SEC = 1e7;
+/** busy-100ns/second → percent: (bps / 1e7) × 100. */
+const BPS_PER_PERCENT = HUNDRED_NS_PER_SEC / 100;
+const BYTES_PER_MB = 1024 * 1024;
+
+export interface GpuEngineSample {
+  pid: number;
+  /** The full instance path: unique per (pid, adapter, engine), so it is the
+   *  delta key. Two engines of the same pid stay separate samples and are
+   *  summed only after each has its own rate. */
+  engine: string;
+  busy100ns: number;
+  /** Counter's own clock, seconds. */
+  atSec: number;
+}
+
+export interface ParsedGpuLines {
+  engines: GpuEngineSample[];
+  /** pid → dedicated VRAM bytes, summed across physical adapters. */
+  memBytesByPid: Map<number, number>;
+  /** True when the tick carried either section at all — i.e. the host has the
+   *  GPU perf provider. An all-idle machine emits no `G` lines but still emits
+   *  `M` lines, so absence of BOTH is what means "unavailable". */
+  present: boolean;
+}
+
+export interface GpuUsageState {
+  byKey: Map<string, CounterSample>;
+}
+
+export function pidFromInstanceName(name: string): number | null {
+  const m = PID_IN_INSTANCE.exec(name);
+  if (!m) return null;
+  const pid = Number(m[1]);
+  return Number.isFinite(pid) && pid > 0 ? pid : null;
+}
+
+export function parseGpuLines(lines: readonly string[]): ParsedGpuLines {
+  const engines: GpuEngineSample[] = [];
+  const memBytesByPid = new Map<number, number>();
+  let present = false;
+
+  for (const line of lines) {
+    const f = line.split("\t");
+    if (f[0] === "G" && f.length >= 4) {
+      present = true;
+      const pid = pidFromInstanceName(f[1] ?? "");
+      const busy = Number(f[2]);
+      const ts = Number(f[3]);
+      if (pid === null || !Number.isFinite(busy) || !Number.isFinite(ts) || ts <= 0) continue;
+      engines.push({ pid, engine: f[1] ?? "", busy100ns: busy, atSec: ts / HUNDRED_NS_PER_SEC });
+    } else if (f[0] === "M" && f.length >= 3) {
+      present = true;
+      const pid = pidFromInstanceName(f[1] ?? "");
+      const bytes = Number(f[2]);
+      if (pid === null || !Number.isFinite(bytes) || bytes < 0) continue;
+      memBytesByPid.set(pid, (memBytesByPid.get(pid) ?? 0) + bytes);
+    }
+  }
+  return { engines, memBytesByPid, present };
+}
+
+/**
+ * Cumulative engine busy counters → per-pid busy %.
+ *
+ * - Delta key is `<engine instance>:<startedAt>` so a recycled pid inheriting a
+ *   dead process's instance name gets a fresh baseline instead of its busy time.
+ * - A pid absent from this tick's process table is dropped: the table is what
+ *   the UI shows, and the perf provider keeps instances of exited processes
+ *   around for a while.
+ * - Per pid the figure is the BUSIEST engine, not the sum across engines — the
+ *   same definition Task Manager's GPU column uses. Engines run in parallel, so
+ *   a sum would exceed 100 % for any process that renders and copies at once
+ *   and would pin at the clamp instead of showing a real load figure.
+ * - First observation of an engine → 0 (never a guess), like `cpu`.
+ * - Counter going backwards → 0 and a fresh baseline. These are 64-bit 100 ns
+ *   counters, so a decrease is a provider restart, never a wrap.
+ * - Dead keys are dropped from `next` every tick, so a long session with a lot
+ *   of short-lived GPU clients cannot grow the map without bound.
+ */
+export function computeGpuPercents(
+  prev: GpuUsageState | null,
+  engines: readonly GpuEngineSample[],
+  startedAtOf: (pid: number) => number | undefined,
+): { pctByPid: Map<number, number>; next: GpuUsageState } {
+  const pctByPid = new Map<number, number>();
+  const nextByKey = new Map<string, CounterSample>();
+
+  for (const e of engines) {
+    const startedAt = startedAtOf(e.pid);
+    if (startedAt === undefined) continue;
+    const key = `${e.engine}:${startedAt}`;
+    const sample: CounterSample = { inBytes: e.busy100ns, outBytes: 0, atSec: e.atSec };
+    const before = prev?.byKey.get(key);
+    nextByKey.set(key, sample);
+    const pct = enginePercent(before ?? null, sample);
+    pctByPid.set(e.pid, Math.max(pctByPid.get(e.pid) ?? 0, pct));
+  }
+
+  for (const [pid, pct] of pctByPid) pctByPid.set(pid, clampPercent(pct));
+  return { pctByPid, next: { byKey: nextByKey } };
+}
+
+function enginePercent(prev: CounterSample | null, next: CounterSample): number {
+  if (!prev || next.inBytes < prev.inBytes) return 0;
+  const rate = toRate(prev, next);
+  if (!rate.available) return 0;
+  return rate.inBps / BPS_PER_PERCENT;
+}
+
+function clampPercent(v: number): number {
+  return Math.round(Math.min(100, Math.max(0, v)) * 10) / 10;
+}
+
+export function memBytesToMB(bytes: number): number {
+  return Math.round((bytes / BYTES_PER_MB) * 10) / 10;
+}

package/src/services/system-metrics/kill-executor.ts

@@ -0,0 +1,85 @@
+/**
+ * Ends a process (or its tree) after the guard has already said yes. POSIX reuses the
+ * repo's process-tree helpers, whose own `killable()` filter (never init, never
+ * ourselves) is a second, independent guard. Pids are validated integers and
+ * only ever passed as argv elements or to `process.kill` — never interpolated
+ * into a shell string.
+ */
+import type { KillProcessResult } from "../../types/system-metrics.ts";
+import type { Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+import { collectProcessTree, terminateTree } from "../windows-process-tree.ts";
+
+/** Grace between SIGTERM and SIGKILL on POSIX. */
+const GRACE_MS = 3000;
+
+export interface KillExecutorDeps {
+  platform: NodeJS.Platform;
+  run: Runner;
+  signal: (pid: number, sig: NodeJS.Signals | 0) => void;
+  collectTree: (pid: number) => number[];
+  terminateTree: (pids: number[], graceMs: number) => Promise<void>;
+  sleep: (ms: number) => Promise<void>;
+}
+
+export const defaultKillExecutorDeps: KillExecutorDeps = {
+  platform: process.platform,
+  run: defaultRunner,
+  signal: (pid, sig) => { process.kill(pid, sig); },
+  collectTree: collectProcessTree,
+  terminateTree,
+  sleep: (ms) => Bun.sleep(ms),
+};
+
+function assertPid(pid: number): void {
+  if (!Number.isInteger(pid) || pid <= 0) throw new Error(`Invalid PID ${pid}`);
+}
+
+/** Throws on executor failure; the route maps that to 500. */
+export async function executeKill(
+  pid: number,
+  tree: boolean,
+  deps: KillExecutorDeps = defaultKillExecutorDeps,
+): Promise<KillProcessResult> {
+  assertPid(pid);
+
+  if (deps.platform === "win32") {
+    // Async spawn, never execFileSync: taskkill can block up to its timeout and
+    // the event loop must keep serving. A non-zero exit (access denied on an
+    // elevated target is common) is reported, never masked by a fallback kill.
+    // `taskkill /T` walks the tree inside the OS and reports no member list, so
+    // `[pid]` is the only honest value for the tree case.
+    const argv = tree ? ["taskkill", "/PID", String(pid), "/T", "/F"] : ["taskkill", "/PID", String(pid), "/F"];
+    const r = await deps.run(argv, 5000);
+    if (r.code !== 0 || r.timedOut) {
+      throw new Error((r.stderr || r.stdout || `taskkill exited ${r.timedOut ? "on timeout" : r.code}`).trim());
+    }
+    return { pid, tree, method: "taskkill", killed: [pid] };
+  }
+
+  if (tree) {
+    // Enumerate BEFORE signalling: once the root dies its children reparent to
+    // init and the tree can no longer be recovered.
+    const pids = deps.collectTree(pid);
+    await deps.terminateTree(pids, GRACE_MS);
+    return { pid, tree: true, method: "signal", killed: pids };
+  }
+
+  deps.signal(pid, "SIGTERM");
+  const deadline = Date.now() + GRACE_MS;
+  while (Date.now() < deadline) {
+    if (!isAlive(pid, deps)) return { pid, tree: false, method: "signal", killed: [pid] };
+    await deps.sleep(100);
+  }
+  try { deps.signal(pid, "SIGKILL"); } catch { /* exited between the check and the kill */ }
+  return { pid, tree: false, method: "signal", killed: [pid] };
+}
+
+function isAlive(pid: number, deps: KillExecutorDeps): boolean {
+  try {
+    deps.signal(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}