fix(adapters): a slow helper no longer blanks power/gpu metrics

The helper socket call and the in-process fallback shared the adapter's 1s
deadline, so a slow helper — macOS powermetrics can take ~1s on an M-series
Pro/Max — ate the whole budget and the fallback never ran. The privileged
adapter timed out and reported power/gpu/vram/npu as errored (seen live on an
M3 Max the moment the helper was started).

Bound the helper call to a slice of the deadline so there's always time left
for the in-process read. The helper stays additive under latency, not just when
it returns empty. On Apple Silicon the daemon reads SMC/IOReport unprivileged,
so running the helper there is now harmless rather than destructive.

Author: kinncj

CHANGELOG.md

@@ -7,6 +7,19 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.4.1] - 2026-07-01
+
+### Fixed
+- **A slow privileged helper no longer blanks every power/GPU metric.** The
+  helper socket call and the in-process fallback shared the adapter's 1 s
+  deadline, so a slow helper — notably macOS `powermetrics`, which can take ~1 s
+  on an M-series Pro/Max — consumed the whole budget and the fallback never ran:
+  the privileged adapter timed out and reported power/GPU/VRAM/NPU as errored.
+  The helper call is now bounded to a slice of the deadline, leaving time for the
+  in-process read, so the helper stays additive under latency. Matters most on
+  Apple Silicon, where the daemon reads SMC/IOReport unprivileged and the helper
+  is optional — running it must never make things worse.
+
 ## [2.4.0] - 2026-07-01
 
 ### Added

app/internal/adapters/helper.go

@@ -5,6 +5,7 @@ package adapters
 
 import (
 	"context"
+	"time"
 
 	"heimdall/app/internal/domain"
 	"heimdall/app/internal/helper"
@@ -51,7 +52,14 @@ func (h Helper) Collect(ctx context.Context) ([]domain.Metric, error) {
 	// 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.
-	if ms, err := client.Collect(ctx); err == nil && anyOK(ms) {
+	//
+	// 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
@@ -67,6 +75,23 @@ func (h Helper) Collect(ctx context.Context) ([]domain.Metric, error) {
 	}, nil
 }
 
+// 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
+// token slice so a healthy helper isn't starved on a tight cycle.
+func helperCallContext(ctx context.Context) (context.Context, context.CancelFunc) {
+	const reserve = 350 * time.Millisecond
+	dl, ok := ctx.Deadline()
+	if !ok {
+		return context.WithTimeout(ctx, 650*time.Millisecond)
+	}
+	remaining := time.Until(dl)
+	if remaining <= reserve {
+		return context.WithTimeout(ctx, remaining/2)
+	}
+	return context.WithTimeout(ctx, remaining-reserve)
+}
+
 func anyOK(ms []domain.Metric) bool {
 	for _, m := range ms {
 		if m.Status == domain.StatusOK {

app/internal/adapters/helper_test.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"path/filepath"
 	"testing"
+	"time"
 
 	"heimdall/app/internal/domain"
 	"heimdall/app/internal/helper"
@@ -40,6 +41,44 @@ func TestHelperAdapterNeedsHelperWhenAbsent(t *testing.T) {
 	}
 }
 
+// blockingClient models a reachable but slow helper (e.g. macOS powermetrics):
+// it never answers, blocking until its context is cancelled.
+type blockingClient struct{}
+
+func (blockingClient) Collect(ctx context.Context) ([]domain.Metric, error) {
+	<-ctx.Done()
+	return nil, ctx.Err()
+}
+
+// A slow helper must not consume the whole adapter deadline and blank every
+// privileged metric — the adapter bounds the helper call and falls back to the
+// in-process reading with time to spare.
+func TestHelperAdapterFallsBackWhenHelperSlow(t *testing.T) {
+	a := Helper{
+		Client: blockingClient{},
+		Direct: func(context.Context) []domain.Metric {
+			return []domain.Metric{{Name: "power.total", Status: domain.StatusOK, Gauge: 42}}
+		},
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	ms, err := a.Collect(ctx)
+	if err != nil {
+		t.Fatalf("collect: %v", err)
+	}
+	if time.Since(start) >= 500*time.Millisecond {
+		t.Error("did not fall back before the adapter deadline (helper ate the budget)")
+	}
+	got := make(map[string]domain.Metric, len(ms))
+	for _, m := range ms {
+		got[m.Name] = m
+	}
+	if m := got["power.total"]; m.Status != domain.StatusOK || m.Gauge != 42 {
+		t.Fatalf("power.total = %+v, want the in-process 42W fallback", m)
+	}
+}
+
 // With no helper socket but in-process privilege (e.g. sudo), the adapter
 // returns the directly collected metrics instead of needs-helper.
 func TestHelperAdapterUsesDirectWhenPrivileged(t *testing.T) {