feat: source-aware power.total, headline it instead of the CPU package

The POWER panel headlined power.pkg (CPU only), so an rtx-pro pulling 506W on
the GPU looked like it was sipping 32W. Add power.total computed where the
collector knows the source, so it never double-counts:
- Apple: pkg alone (SMC PSTR is already whole-system)
- NVIDIA / GB10: pkg + gpu + npu (the GPU is a separate rail)
- AMD APU / integrated: pkg alone (the iGPU is inside the package)

Panel now shows total / cpu-gpu-npu / CPU pkg, which also makes the cpu (cores)
vs pkg (whole socket) distinction explicit.

GB10 (Grace/ARM) exposes no RAPL/INA/SoC power sensor at all — checked hwmon,
powercap, i2c, nvidia-smi — so power.pkg now reads unavailable with a reason
and power.total is the GPU rail alone.

Author: kinncj

CHANGELOG.md

@@ -7,6 +7,26 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.2.9] - 2026-07-01
+
+### Added
+- **`power.total` — a source-aware whole-machine power figure**, now headlined by
+  the top-view POWER panel. The headline used to be `power.pkg` (CPU package
+  only), so a workstation pulling 506 W on the GPU read as ~32 W. `power.total`
+  sums the right rails per platform **without double-counting**: Apple =
+  `power.pkg` (SMC `PSTR` is already whole-system); NVIDIA / GB10 =
+  `pkg + gpu + npu` (the GPU is a separate rail); AMD APU / integrated = `pkg`
+  (the iGPU is already inside the package). rtx-pro now reads ~538 W, GB10 ~50 W.
+- **`power.pkg` on a no-RAPL SoC now says why.** GB10 (Grace/ARM) exposes no
+  RAPL, INA, or any CPU/module power sensor, so `power.pkg` reads Unavailable with
+  `no RAPL power sensor (SoC/ARM)` instead of a silent blank; there `power.total`
+  is the GPU rail alone.
+
+### Changed
+- POWER panel layout: a `total` headline, then `cpu / gpu / npu`, then `CPU pkg`
+  — making the CPU-cores (`cpu`) vs CPU-package (`pkg`) distinction explicit
+  (`cpu` is the cores, a subset of the whole `pkg` socket).
+
 ## [2.2.8] - 2026-06-30
 
 ### Added

app/internal/helper/collect.go

@@ -39,13 +39,21 @@ func PrivilegedMetrics(ctx context.Context) []domain.Metric {
 	out = mergeByName(out, linuxPrivileged(ctx))
 	// Windows privileged sources (WMI thermal zones); no-op off Windows.
 	out = mergeByName(out, windowsPrivileged(ctx))
+	// gpuSeparate marks the GPU as its own power rail (a discrete card, or the GB10
+	// superchip where the Blackwell GPU is metered apart from the Grace CPU). Only
+	// nvidia-smi reports such a rail here; an integrated GPU (Apple, AMD APU) is
+	// already inside the CPU package, so its power must not be added to the total.
+	gpuSeparate := false
 	if nv, present, err := runNvidiaSMI(ctx); present {
 		if err != nil {
 			// nvidia-smi is installed but broke (e.g. driver/library mismatch after
 			// an un-rebooted driver upgrade) — surface why instead of blanking GPU.
 			out = mergeByName(out, nvidiaErrorMetrics(nv))
 		} else {
 			ms := parseNvidiaSMI(nv)
+			if hasName(ms, "power.gpu") {
+				gpuSeparate = true
+			}
 			// Unified-memory NVIDIA (GB10 Grace-Blackwell) has no aggregate VRAM
 			// counter — nvidia-smi memory.* reads [N/A]. Derive gpu.vram from the
 			// per-process compute-apps memory over the system RAM total.
@@ -65,6 +73,7 @@ func PrivilegedMetrics(ctx context.Context) []domain.Metric {
 	// only add names not already set, so an NVIDIA or Apple reading is never
 	// shadowed, and a non-AMD host contributes nothing.
 	out = mergeByName(out, amdGPU(ctx))
+	out = withTotalPower(out, runtime.GOOS, gpuSeparate)
 	out = ensureNPUUtil(out)
 	if !hasOK(out) {
 		return []domain.Metric{
@@ -75,6 +84,43 @@ func PrivilegedMetrics(ctx context.Context) []domain.Metric {
 	return out
 }
 
+// withTotalPower appends a source-aware power.total so the panel can headline
+// real whole-machine draw instead of just the CPU package. It must never
+// double-count: Apple's power.pkg is SMC PSTR (already whole-system), and an
+// integrated GPU is already inside the CPU package — only a separate GPU rail
+// (discrete NVIDIA, or the GB10 Grace+Blackwell split) is added.
+func withTotalPower(ms []domain.Metric, goos string, gpuSeparate bool) []domain.Metric {
+	pkg, hasPkg := okGauge(ms, "power.pkg")
+	gpu, hasGPU := okGauge(ms, "power.gpu")
+	npu, _ := okGauge(ms, "power.npu")
+	var total float64
+	switch {
+	case goos == "darwin":
+		total = pkg // SMC PSTR is already whole-system
+	case gpuSeparate:
+		total = pkg + gpu + npu // CPU package + a discrete/superchip GPU rail
+	default:
+		total = pkg // integrated GPU is already counted inside the package
+		if !hasPkg && hasGPU {
+			total = gpu
+		}
+	}
+	if total <= 0 {
+		return ms
+	}
+	return append(ms, domain.Metric{Name: "power.total", Unit: "watts", Status: domain.StatusOK, Gauge: total, Detail: "system total"})
+}
+
+// okGauge returns the gauge of an OK metric by name.
+func okGauge(ms []domain.Metric, name string) (float64, bool) {
+	for _, m := range ms {
+		if m.Name == name && m.Status == domain.StatusOK {
+			return m.Gauge, true
+		}
+	}
+	return 0, false
+}
+
 // ensureNPUUtil guarantees an npu.util reading. NPUs (Apple ANE, Intel AI Boost,
 // AMD XDNA) expose no utilisation counter, so if no source set it, report it
 // Unavailable-with-reason rather than leaving a bare dash. A reading already set

app/internal/helper/collect_linux.go

@@ -26,6 +26,10 @@ func linuxPrivileged(ctx context.Context) []domain.Metric {
 	var out []domain.Metric
 	if w, ok := raplPackageWatts(ctx); ok {
 		out = append(out, domain.Metric{Name: "power.pkg", Unit: "watts", Status: domain.StatusOK, Gauge: w, Detail: "CPU package"})
+	} else if len(raplDomainDirs()) == 0 {
+		// No powercap tree at all — the SoC exposes no RAPL (e.g. GB10 Grace/ARM).
+		// Say so rather than leaving CPU power a silent blank.
+		out = append(out, domain.Metric{Name: "power.pkg", Status: domain.StatusUnavailable, Detail: "no RAPL power sensor (SoC/ARM)"})
 	}
 	if w, ok := raplCoreWatts(ctx); ok {
 		out = append(out, domain.Metric{Name: "power.cpu", Unit: "watts", Status: domain.StatusOK, Gauge: w, Detail: "CPU cores"})

app/internal/helper/total_power_test.go

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Kinn Coelho Juliao <kinncj@gmail.com>
+
+package helper
+
+import (
+	"testing"
+
+	"heimdall/app/internal/domain"
+)
+
+// power.total must be source-aware so it never double-counts an integrated GPU
+// (already inside the CPU package) nor Apple's SMC PSTR (already whole-system).
+func TestWithTotalPower(t *testing.T) {
+	watts := func(name string, w float64) domain.Metric {
+		return domain.Metric{Name: name, Unit: "watts", Status: domain.StatusOK, Gauge: w}
+	}
+
+	// Linux + discrete/superchip NVIDIA: CPU package + a separate GPU rail.
+	got := byName(withTotalPower([]domain.Metric{watts("power.pkg", 32), watts("power.gpu", 506)}, "linux", true))
+	if m := got["power.total"]; m.Status != domain.StatusOK || m.Gauge != 538 {
+		t.Errorf("nvidia total = %+v, want 538", m)
+	}
+
+	// GB10 (ARM, no RAPL package): only the GPU rail is measurable.
+	got = byName(withTotalPower([]domain.Metric{watts("power.gpu", 50)}, "linux", true))
+	if m := got["power.total"]; m.Status != domain.StatusOK || m.Gauge != 50 {
+		t.Errorf("gb10 total = %+v, want 50", m)
+	}
+
+	// Apple: power.pkg is SMC PSTR (already whole-system) — do not add the GPU.
+	got = byName(withTotalPower([]domain.Metric{watts("power.pkg", 20), watts("power.gpu", 5)}, "darwin", false))
+	if m := got["power.total"]; m.Gauge != 20 {
+		t.Errorf("apple total = %+v, want 20 (pkg only)", m)
+	}
+
+	// AMD APU (integrated GPU inside the package): total is the package alone.
+	got = byName(withTotalPower([]domain.Metric{watts("power.pkg", 40), watts("power.gpu", 15)}, "linux", false))
+	if m := got["power.total"]; m.Gauge != 40 {
+		t.Errorf("apu total = %+v, want 40 (no double-count)", m)
+	}
+
+	// Nothing to total → no metric rather than a phantom 0.
+	if _, ok := byName(withTotalPower(nil, "linux", true))["power.total"]; ok {
+		t.Error("no power sources should yield no power.total")
+	}
+}

app/internal/tui/topview/panels.go

@@ -166,24 +166,27 @@ func (m Model) powerPanel(t tier, w int) panelSpec {
 	cpu := m.numVal("power.cpu", " W", "%.1f")
 	gpu := m.numVal("power.gpu", " W", "%.1f")
 	npu := m.numVal("power.npu", " W", "%.1f")
-	pwrVal := m.numVal("power.pkg", " W", "%.0f")
+	// Headline the whole-machine total (source-aware, from the collector) so a
+	// busy GPU isn't hidden behind the much smaller CPU-package figure.
+	totalVal := m.numVal("power.total", " W", "%.0f")
 
 	if t == tierNarrow {
 		return panelSpec{title: "POWER", lines: []string{
-			lab("pkg ") + pkg + "  " + lab("cpu ") + cpu + "  " + lab("gpu ") + gpu + "  " + lab("npu ") + npu,
-			lab("pwr ") + m.sparkW("power.pkg", w) + "  " + pwrVal,
+			lab("cpu ") + cpu + "  " + lab("gpu ") + gpu + "  " + lab("npu ") + npu,
+			lab("total ") + m.sparkW("power.total", w) + "  " + totalVal,
 		}}
 	}
 	if t == tierMedium {
 		return panelSpec{title: "POWER", lines: []string{
-			lab("pkg ") + pkg + "   " + lab("cpu ") + cpu + "   " + lab("gpu ") + gpu + "   " + lab("npu ") + npu,
-			lab("pwr ") + m.sparkW("power.pkg", w) + "  " + pwrVal,
+			lab("cpu ") + cpu + "   " + lab("gpu ") + gpu + "   " + lab("npu ") + npu,
+			lab("total ") + m.sparkW("power.total", w) + "  " + totalVal,
+			lab("CPU pkg ") + pkg,
 		}}
 	}
 	return panelSpec{title: "POWER", lines: []string{
-		lab("pkg ") + pkg,
+		lab("total ") + m.sparkW("power.total", w) + "  " + totalVal,
 		lab("cpu ") + cpu + "   " + lab("gpu ") + gpu + "   " + lab("npu ") + npu,
-		lab("pwr ") + m.sparkW("power.pkg", w) + "  " + pwrVal,
+		lab("CPU pkg ") + pkg,
 	}}
 }
 

docs/guides/14-privileged-linux-nvidia.md

@@ -77,11 +77,21 @@ privileged sources served by `heimdall-helper`:
 - **`temp.pkg`** from a trusted hwmon chip.
 
 > **Why `power.pkg` can read *below* `power.gpu`.** Both `power.pkg` and
-> `power.cpu` are the **CPU socket only**. A discrete NVIDIA card is a separate
-> power rail reported as `power.gpu`, so a workstation happily shows e.g.
-> `power.cpu 12W`, `power.pkg 17W`, `power.gpu 61W` — the GPU is not part of the
-> CPU package figure. Unlike macOS (where `power.pkg` is SMC `PSTR`, the true
-> whole-system total), Linux has no single "whole machine" power counter.
+> `power.cpu` are the **CPU socket only** (`power.cpu` is the cores, a subset of
+> the whole `power.pkg` package). A discrete NVIDIA card is a separate power rail
+> reported as `power.gpu`, so a workstation happily shows e.g. `power.cpu 12W`,
+> `power.pkg 17W`, `power.gpu 61W` — the GPU is not part of the CPU package
+> figure. **`power.total`** is the source-aware whole-machine sum the top view
+> headlines: on a discrete-NVIDIA host it is `pkg + gpu (+ npu)`; on Apple it is
+> `pkg` alone (SMC `PSTR` already covers everything); on an AMD APU it is `pkg`
+> alone (the iGPU is inside the package).
+
+### GB10 (Grace/ARM) has no CPU power sensor
+
+A GB10 exposes **no** RAPL, INA, or SoC power sensor to the OS — only the GPU
+rail via `nvidia-smi`. So `power.pkg` reads `unavailable` (`no RAPL power sensor
+(SoC/ARM)`) and `power.total` is the GPU power alone. The Grace CPU / module draw
+is simply not measurable from userspace on this platform.
 >
 > `power.npu` stays `unavailable` on Intel/AMD hosts — their NPUs expose no
 > power counter yet, same as Apple's ANE.