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/client/screenshot_linux.go

@@ -1,5 +1,17 @@
 //go:build linux
 
+// Headless Linux hosts (Docker, CI, VPS) have no DISPLAY. Install Xvfb + scrot:
+//
+//	apt-get install -y xvfb scrot
+//	Xvfb :99 -screen 0 1280x720x24 &
+//	export DISPLAY=:99
+//
+// Or pass a one-shot custom command via Crucible screenshot (command field), e.g.:
+//
+//	DISPLAY=:99 scrot -q 55 -o /tmp/s.jpg && base64 -w0 /tmp/s.jpg
+//
+// See docs/E2E_VALIDATION.md § Linux headless screenshot.
+
 package client
 
 import (
@@ -76,5 +88,5 @@ func captureLinuxScreenshotJPEG() ([]byte, error) {
 		return os.ReadFile(path)
 	}
 
-	return nil, fmt.Errorf("no screenshot tool found (scrot, import, gnome-screenshot)")
+	return nil, fmt.Errorf("no screenshot tool found (scrot, import, gnome-screenshot); headless hosts need xvfb — see docs/E2E_VALIDATION.md")
 }

agent/client/screenshot_linux_test.go

@@ -0,0 +1,28 @@
+//go:build linux
+
+package client
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestLinuxScreenshotErrorMentionsHeadlessXvfb(t *testing.T) {
+	_, err := captureLinuxScreenshotJPEG()
+	if err == nil {
+		t.Skip("screenshot tool present on this host")
+	}
+	if !strings.Contains(strings.ToLower(err.Error()), "xvfb") {
+		t.Fatalf("headless error should mention xvfb, got %q", err.Error())
+	}
+}
+
+func TestLinuxScreenshotCustomCommandEmptyRejected(t *testing.T) {
+	_, err := capturePlatformScreenshot("   ")
+	if err == nil {
+		t.Skip("default capture succeeded without custom command")
+	}
+	if !strings.Contains(err.Error(), "scrot") && !strings.Contains(err.Error(), "xvfb") {
+		t.Fatalf("expected tool or xvfb hint, got %q", err.Error())
+	}
+}

agent/client/screenshot_stub_test.go

@@ -0,0 +1,28 @@
+//go:build !windows && !linux && !darwin
+
+package client
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestScreenshotStubReturnsUnsupportedError(t *testing.T) {
+	b64, err := capturePlatformScreenshot("")
+	if b64 != "" {
+		t.Fatalf("expected empty base64, got len=%d", len(b64))
+	}
+	if err == nil {
+		t.Fatal("expected error from screenshot stub")
+	}
+	if !strings.Contains(err.Error(), "not supported") {
+		t.Fatalf("error should mention unsupported platform, got %q", err.Error())
+	}
+}
+
+func TestScreenshotStubIgnoresCustomCommand(t *testing.T) {
+	_, err := capturePlatformScreenshot("echo fake")
+	if err == nil {
+		t.Fatal("stub must reject custom screenshot commands on unsupported platforms")
+	}
+}