fix(adapters): read in-process first so a slow macOS helper can't blank metrics

v2.4.1 bounded the helper call but left too little of the 1s budget for the
fallback, so a slow powermetrics helper on an M3 Max still timed out the whole
privileged adapter (verified: removing the helper was the only way to recover).

Flip the strategy: collect in-process first, and consult the helper only when the
daemon couldn't read a CPU power rail itself (power.cpu/total/pkg). On macOS the
daemon reads SMC/IOReport unprivileged, so it has power without the helper and
never calls it — running the helper on Apple Silicon is now harmless. On an
unprivileged Linux daemon there's no RAPL in-process, so the helper is still
consulted for it (bounded, so a slow one can't hang). GPU power alone doesn't
count, so a Linux+NVIDIA box still gets the helper for RAPL.

Author: kinncj

CHANGELOG.md

@@ -7,6 +7,20 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.4.2] - 2026-07-01
+
+### Fixed
+- **macOS: running the helper no longer blanks power/GPU — the real fix.** v2.4.1
+  only bounded the helper call, which still left too little of the 1 s budget for
+  the fallback, so a slow `powermetrics` helper on an M-series Pro/Max kept timing
+  out the whole privileged adapter. The adapter now reads **in-process first** and
+  consults the helper only when the daemon can't read a CPU power rail itself
+  (`power.cpu`/`power.total`/`power.pkg`) — i.e. an unprivileged Linux daemon that
+  needs the root helper for RAPL. On macOS the daemon already has power from
+  SMC/IOReport, so the helper is never on the critical path: running it on Apple
+  Silicon is finally harmless, not destructive. (GPU power alone doesn't count as
+  "has power" — a Linux box with an NVIDIA GPU still needs the helper for RAPL.)
+
 ## [2.4.1] - 2026-07-01
 
 ### Fixed

app/internal/adapters/helper.go

@@ -43,38 +43,61 @@ func (Helper) Describe() domain.AdapterInfo {
 }
 
 func (h Helper) Collect(ctx context.Context) ([]domain.Metric, error) {
+	direct := h.Direct
+	if direct == nil {
+		direct = helper.PrivilegedMetrics
+	}
+
+	// In-process first. Where the daemon can already read a privileged CPU power
+	// rail itself — macOS (SMC/IOReport are unprivileged) or a root daemon reading
+	// RAPL — the helper can only duplicate it, so we return the in-process read and
+	// never call the helper. That's what makes running the helper on Apple Silicon
+	// harmless: the daemon has power without it, so a slow helper (macOS
+	// powermetrics can take ~1s) is never on the critical path.
+	inproc := direct(ctx)
+	if hasOKPower(inproc) {
+		return inproc, nil
+	}
+
+	// Otherwise the daemon is unprivileged and can't read the CPU power rail
+	// (typically a Linux daemon that needs the root helper for RAPL). Consult the
+	// helper, bounded so a slow or hung one can't stall the collection cycle. A
+	// reachable-but-empty helper must never shadow the in-process read, so we only
+	// take the helper's result when it has an ok metric; else we fall back to
+	// whatever in-process produced.
 	var client metricCollector = h.Client
 	if client == nil {
 		client = helper.Client{}
 	}
-	// Use the helper only when it actually produced an ok reading. A reachable
-	// helper that returns nothing ok (e.g. a non-cgo helper, or one that can't
-	// read IOReport) must NOT shadow a working in-process source — otherwise
-	// running the helper on a Mac, where IOReport is unprivileged, blanks out the
-	// power/gpu the daemon was reading itself.
-	//
-	// The helper call is bounded to a slice of the deadline so a *slow* helper
-	// (e.g. macOS powermetrics, which can take ~1s) can't consume the whole
-	// adapter budget and starve the in-process fallback below — the helper stays
-	// additive, never subtractive, even under latency.
 	hctx, cancel := helperCallContext(ctx)
 	defer cancel()
 	if ms, err := client.Collect(hctx); err == nil && anyOK(ms) {
 		return ms, nil
 	}
-	direct := h.Direct
-	if direct == nil {
-		direct = helper.PrivilegedMetrics
-	}
-	if ms := direct(ctx); anyOK(ms) {
-		return ms, nil
+	if anyOK(inproc) {
+		return inproc, nil
 	}
 	return []domain.Metric{
 		{Name: "power.cpu", Status: domain.StatusInsufficientPermission, Detail: "needs helper"},
 		{Name: "gpu.util", Status: domain.StatusInsufficientPermission, Detail: "needs helper"},
 	}, nil
 }
 
+// hasOKPower reports whether the metrics already include a privileged CPU power
+// rail the daemon read itself — the signal that the helper would only duplicate.
+func hasOKPower(ms []domain.Metric) bool {
+	for _, m := range ms {
+		if m.Status != domain.StatusOK {
+			continue
+		}
+		switch m.Name {
+		case "power.total", "power.cpu", "power.pkg":
+			return true
+		}
+	}
+	return false
+}
+
 // helperCallContext caps the helper socket call so it leaves budget for the
 // in-process fallback within the adapter deadline. Without a deadline it applies
 // a sane default; when the deadline is already near, the helper still gets a

app/internal/adapters/helper_test.go

@@ -144,20 +144,30 @@ func TestHelperEmptyReplyFallsBackToDirect(t *testing.T) {
 	}
 }
 
-// A reachable helper WITH ok metrics is authoritative — Direct must not run.
-func TestHelperOKReplyIsUsedWithoutDirect(t *testing.T) {
-	directRan := false
+// When the daemon can't read a privileged CPU power rail in-process (an
+// unprivileged Linux daemon: RAPL needs root — note GPU power alone doesn't
+// count, since RAPL still requires the helper), the helper is consulted and its
+// ok reading is used.
+func TestHelperUsedWhenInProcessLacksCPUPower(t *testing.T) {
 	a := Helper{
 		Client: fakeMetricClient{ms: []domain.Metric{
 			{Name: "power.cpu", Unit: "W", Status: domain.StatusOK, Gauge: 15},
+			{Name: "gpu.util", Unit: "%", Status: domain.StatusOK, Gauge: 40},
 		}},
-		Direct: func(context.Context) []domain.Metric { directRan = true; return nil },
+		Direct: func(context.Context) []domain.Metric {
+			// In-process sees the GPU (nvidia) but not the root-only CPU rail.
+			return []domain.Metric{
+				{Name: "gpu.util", Unit: "%", Status: domain.StatusOK, Gauge: 40},
+				{Name: "power.gpu", Unit: "W", Status: domain.StatusOK, Gauge: 60},
+			}
+		},
 	}
 	ms, _ := a.Collect(context.Background())
-	if directRan {
-		t.Fatal("Direct must not run when the helper already has ok metrics")
+	got := make(map[string]domain.Metric, len(ms))
+	for _, m := range ms {
+		got[m.Name] = m
 	}
-	if len(ms) != 1 || ms[0].Name != "power.cpu" || ms[0].Status != domain.StatusOK {
-		t.Fatalf("want helper power.cpu ok, got %+v", ms)
+	if got["power.cpu"].Status != domain.StatusOK || got["power.cpu"].Gauge != 15 {
+		t.Fatalf("want helper power.cpu 15 (in-process had no CPU rail), got %+v", got["power.cpu"])
 	}
 }