feat(windows): read CPU power from Scaphandre instead of LibreHardwareMonitor

LibreHardwareMonitor is a GUI app — awkward to install and keep running on a
headless box. Scaphandre is the tool the WinPowerMonitor ecosystem already uses:
it installs the signed Hubblo RAPL driver and runs as a Windows service with a
Prometheus endpoint. Heimdall now scrapes that (sum of
scaph_socket_power_microwatts) and reports power.cpu — Intel + AMD, pure Go, no
cgo. HEIMDALL_SCAPHANDRE_URL overrides the endpoint. Without it, power.cpu says
to run Scaphandre. Windows guide + metrics doc updated.

Author: kinncj

CHANGELOG.md

@@ -7,6 +7,17 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.3.2] - 2026-07-01
+
+### Changed
+- **Windows CPU power now comes from Scaphandre, not LibreHardwareMonitor.**
+  Scaphandre installs the signed Hubblo RAPL driver and runs as a Windows service
+  exposing a Prometheus endpoint — a far cleaner install than a GUI monitor.
+  Heimdall scrapes it (`scaph_socket_power_microwatts`, summed) and reports
+  `power.cpu` (Intel + AMD, pure Go, no cgo). Point it at a non-default endpoint
+  with `HEIMDALL_SCAPHANDRE_URL`. Without Scaphandre, `power.cpu` reads
+  `no RAPL on Windows — run Scaphandre for CPU power`. See guide 16.
+
 ## [2.3.1] - 2026-07-01
 
 ### Added

app/internal/helper/collect_windows.go

@@ -7,27 +7,34 @@ package helper
 
 import (
 	"context"
+	"io"
+	"net/http"
+	"os"
 	"os/exec"
-	"strconv"
+	"time"
 
 	"heimdall/app/internal/domain"
 )
 
+// scaphandreDefaultURL is Scaphandre's Prometheus exporter default. Override with
+// HEIMDALL_SCAPHANDRE_URL when it runs elsewhere.
+const scaphandreDefaultURL = "http://127.0.0.1:8080/metrics"
+
 // windowsPrivileged reports CPU power and package temperature on Windows.
 //
 // Windows exposes no RAPL to user space — reading the CPU energy MSRs needs a
-// ring-0 driver, which Heimdall does not ship. So CPU power comes from a
-// driver-backed monitor the operator already runs: LibreHardwareMonitor publishes
-// CPU package power over WMI (root/LibreHardwareMonitor), which we read here (no
-// cgo, Intel + AMD). When it isn't running, power.cpu is Unavailable with a reason
-// pointing at how to enable it. Package temperature still comes from the ACPI
-// thermal zone via WMI.
+// ring-0 driver, which Heimdall does not ship. Scaphandre installs the signed
+// Hubblo RAPL driver and runs as a service exposing power over a Prometheus
+// endpoint; when it's up we scrape it and report CPU-package power as power.cpu
+// (Intel + AMD, pure Go, no cgo). When it isn't, power.cpu is Unavailable with a
+// reason pointing at it. Package temperature still comes from the ACPI thermal
+// zone via WMI.
 func windowsPrivileged(ctx context.Context) []domain.Metric {
 	var out []domain.Metric
-	if w, ok := lhmCPUPackageWatts(ctx); ok {
-		out = append(out, domain.Metric{Name: "power.cpu", Unit: "watts", Status: domain.StatusOK, Gauge: w, Detail: "CPU package (LibreHardwareMonitor)"})
+	if w, ok := scaphandreCPUWatts(ctx); ok {
+		out = append(out, domain.Metric{Name: "power.cpu", Unit: "watts", Status: domain.StatusOK, Gauge: w, Detail: "CPU package (Scaphandre)"})
 	} else {
-		out = append(out, domain.Metric{Name: "power.cpu", Status: domain.StatusUnavailable, Detail: "no RAPL on Windows — run LibreHardwareMonitor for CPU power"})
+		out = append(out, domain.Metric{Name: "power.cpu", Status: domain.StatusUnavailable, Detail: "no RAPL on Windows — run Scaphandre for CPU power"})
 	}
 	if b, err := exec.CommandContext(ctx, "powershell", "-NoProfile", "-Command",
 		"Get-CimInstance -Namespace root/wmi -ClassName MSAcpi_ThermalZoneTemperature "+
@@ -39,25 +46,28 @@ func windowsPrivileged(ctx context.Context) []domain.Metric {
 	return out
 }
 
-// lhmCPUPackageWatts reads CPU package power from a running LibreHardwareMonitor
-// via its WMI provider. LHM ships a signed driver that reads the RAPL MSRs Windows
-// won't expose otherwise, and surfaces them as Sensor instances. Absent (0, false)
-// when LHM isn't running or exposes no CPU package power sensor.
-func lhmCPUPackageWatts(ctx context.Context) (float64, bool) {
-	out, err := exec.CommandContext(ctx, "powershell", "-NoProfile", "-Command",
-		"$s = Get-CimInstance -Namespace root/LibreHardwareMonitor -ClassName Sensor -ErrorAction SilentlyContinue "+
-			"| Where-Object { $_.SensorType -eq 'Power' -and $_.Name -like '*Package*' } "+
-			"| Select-Object -First 1 -ExpandProperty Value; if ($s) { $s }").Output()
+// scaphandreCPUWatts scrapes a running Scaphandre Prometheus exporter for CPU
+// package power. Absent (0, false) when Scaphandre isn't reachable.
+func scaphandreCPUWatts(ctx context.Context) (float64, bool) {
+	url := os.Getenv("HEIMDALL_SCAPHANDRE_URL")
+	if url == "" {
+		url = scaphandreDefaultURL
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return 0, false
+	}
+	resp, err := (&http.Client{Timeout: 2 * time.Second}).Do(req)
 	if err != nil {
 		return 0, false
 	}
-	line := firstNonEmptyLine(string(out))
-	if line == "" {
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
 		return 0, false
 	}
-	w, err := strconv.ParseFloat(line, 64)
-	if err != nil || w <= 0 {
+	b, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
 		return 0, false
 	}
-	return w, true
+	return parseScaphandreCPUWatts(string(b))
 }

app/internal/helper/parse_scaphandre.go

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Kinn Coelho Juliao <kinncj@gmail.com>
+
+package helper
+
+import (
+	"strconv"
+	"strings"
+)
+
+// parseScaphandreCPUWatts sums Scaphandre's per-socket CPU power from its
+// Prometheus exposition and returns watts. Scaphandre reports
+// scaph_socket_power_microwatts per CPU socket (the RAPL package domain) in
+// microwatts; summing the sockets and dividing by 1e6 gives CPU-package power —
+// the Windows equivalent of the RAPL package read directly on Linux. No socket
+// line means no reading.
+func parseScaphandreCPUWatts(promText string) (float64, bool) {
+	var micro float64
+	found := false
+	for _, ln := range strings.Split(promText, "\n") {
+		ln = strings.TrimSpace(ln)
+		if ln == "" || strings.HasPrefix(ln, "#") {
+			continue
+		}
+		if !strings.HasPrefix(ln, "scaph_socket_power_microwatts") {
+			continue
+		}
+		f := strings.Fields(ln)
+		if len(f) < 2 {
+			continue
+		}
+		v, err := strconv.ParseFloat(f[len(f)-1], 64)
+		if err != nil {
+			continue
+		}
+		micro += v
+		found = true
+	}
+	if !found {
+		return 0, false
+	}
+	return micro / 1e6, true
+}

app/internal/helper/parse_scaphandre_test.go

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Kinn Coelho Juliao <kinncj@gmail.com>
+
+package helper
+
+import "testing"
+
+// Scaphandre's Prometheus exporter reports per-socket CPU power in microwatts;
+// power.cpu is their sum in watts.
+func TestParseScaphandreCPUWatts(t *testing.T) {
+	text := `# HELP scaph_socket_power_microwatts Power measured per CPU socket
+# TYPE scaph_socket_power_microwatts gauge
+scaph_host_power_microwatts 45000000
+scaph_socket_power_microwatts{socket_id="0"} 30000000
+scaph_socket_power_microwatts{socket_id="1"} 10000000
+`
+	w, ok := parseScaphandreCPUWatts(text)
+	if !ok || w != 40 { // (30M + 10M) µW ÷ 1e6 = 40 W
+		t.Fatalf("got %v %v, want 40 W", w, ok)
+	}
+
+	// Scientific notation (Scaphandre emits floats) is accepted.
+	w, ok = parseScaphandreCPUWatts("scaph_socket_power_microwatts{socket_id=\"0\"} 1.25e7\n")
+	if !ok || w != 12.5 {
+		t.Fatalf("got %v %v, want 12.5 W", w, ok)
+	}
+
+	// No socket metric present → no reading (not a phantom 0).
+	if _, ok := parseScaphandreCPUWatts("# nothing here\nscaph_host_power_microwatts 1000000\n"); ok {
+		t.Error("no socket power metric should yield no reading")
+	}
+}

docs/guides/16-privileged-windows.md

@@ -35,17 +35,23 @@ yet exercised on Windows).
 ## CPU power
 
 Windows exposes no RAPL to user space — reading the CPU energy MSRs needs a
-ring-0 driver, which Heimdall does not ship (that's exactly what tools like
-Scaphandre and WinPowerMonitor install). Rather than sign our own driver,
-Heimdall reads CPU power from a **driver-backed monitor you already run**:
+ring-0 driver, which Heimdall does not ship. Rather than sign our own driver,
+Heimdall reads CPU power from **[Scaphandre](https://github.com/hubblo-org/scaphandre)**,
+which installs the signed Hubblo RAPL driver and runs as a Windows service.
 
-- **[LibreHardwareMonitor](https://github.com/LibreHardwareMonitor/LibreHardwareMonitor)**
-  — start it (its signed driver reads the RAPL MSRs on Intel **and** AMD) and
-  leave "Remote Web Server / WMI" enabled. Heimdall queries its WMI provider
-  (`root/LibreHardwareMonitor`) and reports the CPU-package sensor as `power.cpu`.
+Set it up once:
 
-When no such monitor is running, `power.cpu` reads `unavailable` with
-`no RAPL on Windows — run LibreHardwareMonitor for CPU power` rather than failing.
+1. Download **Scaphandre ≥ 1.0.0** for Windows (its installer bundles the Hubblo
+   RAPL driver — Intel and AMD since Ryzen).
+2. Run the Prometheus exporter, e.g. `scaphandre prometheus` (default
+   `http://127.0.0.1:8080/metrics`), ideally as a service so it starts at boot.
+
+Heimdall scrapes that endpoint and reports the summed per-socket power
+(`scaph_socket_power_microwatts`) as `power.cpu` — pure Go, no cgo. If Scaphandre
+listens elsewhere, point Heimdall at it with `HEIMDALL_SCAPHANDRE_URL`.
+
+When Scaphandre isn't reachable, `power.cpu` reads `unavailable` with
+`no RAPL on Windows — run Scaphandre for CPU power` rather than failing.
 
 ## How the helper works on Windows
 
@@ -61,7 +67,7 @@ daemon** can't. Here's what each Windows source needs:
 |---|---|---|
 | `nvidia-smi` (`gpu.util/vram/temp`, `power.gpu`) | normally **no** | richest panel on Windows when an NVIDIA GPU is present |
 | WMI `temp.pkg` (`MSAcpi_ThermalZoneTemperature`) | usually **yes** | only if the firmware exposes an ACPI thermal zone — many laptops don't |
-| `power.cpu` | no (reads WMI) | needs **LibreHardwareMonitor** running (its driver reads RAPL); else `unavailable` |
+| `power.cpu` | no (scrapes HTTP) | needs **Scaphandre** running (installs the RAPL driver, exposes Prometheus); else `unavailable` |
 
 `nvidia-smi` is normally unprivileged, so a daemon running as your user *should*
 collect the GPU panel without the helper. But account/PATH setups vary — don't

docs/metrics.md

@@ -72,7 +72,7 @@ rather than failing. See [Privileged Metrics](guides/04-privileged-metrics.md).
 | `temp.pkg` | °C | CPU package temperature |
 | `gpu.temp` | °C | GPU temperature |
 | `power.total` | W | whole-machine power — `cpu + gpu (+ npu)`, or the SMC whole-system total on macOS |
-| `power.cpu` | W | CPU power (RAPL package on Linux; IOReport CPU on macOS) |
+| `power.cpu` | W | CPU power — RAPL package (Linux), IOReport CPU (macOS), Scaphandre (Windows, when running); Unavailable-with-reason where no source exists (Apple Pro/Max, Windows without Scaphandre, GB10) |
 | `power.gpu` | W | GPU power |
 | `power.npu` | W | NPU / accelerator power (Apple Silicon ANE today). The legacy `power.ane` key is accepted and normalised to `power.npu` on ingest. |
 | `npu.util` | percent | NPU utilisation (where the platform exposes it; otherwise unavailable) |