Fix exotic CPU stub idle-mining guard and document Linux headless screenshots.

Return sane fallback CPU percent after first sample on unknown Unix platforms; add xvfb/scrot docs and stub tests; clear PROBLEMS.md open bugs.

agent/stats/cpu_common.go

@@ -1,5 +1,21 @@
 package stats
 
+// StubFallbackCPUPercent is returned after the first sample on platforms without
+// OS CPU counters (cpu_stub.go). Kept below the default idle threshold (20%).
+const StubFallbackCPUPercent = 5.0
+
+// stubSystemCPUPercent implements idle-mining-safe defaults when real counters
+// are unavailable: first sample returns 0 (no delta yet), then a low busy %.
+func (r *Reporter) stubSystemCPUPercent() float64 {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if !r.hasSample {
+		r.hasSample = true
+		return 0
+	}
+	return StubFallbackCPUPercent
+}
+
 func cpuBusyPercentFromDeltas(idleDelta, totalDelta float64) float64 {
 	if totalDelta <= 0 {
 		return 0

agent/stats/cpu_common_test.go

@@ -0,0 +1,30 @@
+package stats
+
+import "testing"
+
+func TestStubSystemCPUPercentFirstSampleZero(t *testing.T) {
+	r := NewReporter()
+	if got := r.stubSystemCPUPercent(); got != 0 {
+		t.Fatalf("first sample want 0 got %v", got)
+	}
+}
+
+func TestStubSystemCPUPercentFallbackBelowIdleThreshold(t *testing.T) {
+	r := NewReporter()
+	_ = r.stubSystemCPUPercent()
+	got := r.stubSystemCPUPercent()
+	if got != StubFallbackCPUPercent {
+		t.Fatalf("fallback want %v got %v", StubFallbackCPUPercent, got)
+	}
+	if got >= 20 {
+		t.Fatalf("fallback %v must stay below default idle threshold 20", got)
+	}
+}
+
+func TestStubSystemCPUPercentSubsequentNonZero(t *testing.T) {
+	r := NewReporter()
+	_ = r.stubSystemCPUPercent()
+	if got := r.stubSystemCPUPercent(); got <= 0 {
+		t.Fatalf("subsequent stub sample must be >0 for idle guard, got %v", got)
+	}
+}

agent/stats/cpu_stub.go

@@ -3,5 +3,5 @@
 package stats
 
 func (r *Reporter) SystemCPUPercent() float64 {
-	return 0
+	return r.stubSystemCPUPercent()
 }

agent/stats/cpu_stub_test.go

@@ -0,0 +1,15 @@
+//go:build !windows && !linux && !darwin
+
+package stats
+
+import "testing"
+
+func TestStubPlatformSystemCPUPercentUsesFallback(t *testing.T) {
+	r := NewReporter()
+	if got := r.SystemCPUPercent(); got != 0 {
+		t.Fatalf("first SystemCPUPercent want 0 got %v", got)
+	}
+	if got := r.SystemCPUPercent(); got != StubFallbackCPUPercent {
+		t.Fatalf("second SystemCPUPercent want %v got %v", StubFallbackCPUPercent, got)
+	}
+}