refactor(helper): hardcode GPU throttle; refuse integrated GPUs

Two related cleanups around the helper's GPU-sharing model.

Drop the GpuLimitPercent setting (5..75, default 25). The knob name read
as "max % of GPU the helper uses," but the implementation actually
controlled when to yield based on overall GPU-busy %. Everyone who saw
"25" reasonably worried the helper would constantly pin a quarter of
their GPU, which it never did. The dedicated encoder block (NVENC,
AMD VCN) runs in parallel with the game's render pipeline, so a low
yield threshold cost helper throughput for no measurable game-FPS
benefit. Helper now uses a hardcoded 95% back-off threshold internally
and exposes no equivalent knob.

Refuse Intel QSV and Windows MediaFoundation at encoder selection.
Both run on integrated graphics on the vast majority of installs,
where the encoder shares silicon with the render pipeline and
accepting a lease costs real frames in-headset. Helper opts out of
co-watching entirely when only integrated encoders are available;
the rest of WKVRCProxy (relay, watchdog, mesh client) continues to
run normally. A helper_encoder_refused log line lists the rejected
encoders so operators see why their iGPU machine isn't sharing.

Wire field gpu_limit_percent retained on HelperStatusFrame for
backward compat with older servers that still log it; always emitted
as 0 from this build (no user override).

Author: RealWhyKnot

src/WKVRCProxy.Tests/AppSettingsTests.cs

@@ -13,14 +13,24 @@ public void Defaults_EnableSharingWithConservativeLimits()
         var settings = new AppSettings().Normalize();
 
         Assert.True(settings.Helper.GpuSharing);
-        Assert.Equal(25, settings.Helper.GpuLimitPercent);
         Assert.Equal(0, settings.Helper.UploadLimitMbps);
         Assert.False(settings.Helper.AllowOnBattery);
         Assert.Equal("auto", settings.Helper.EncodingQuality);
         Assert.True(settings.Terminal.StatusLine);
         Assert.True(settings.Terminal.Animations);
     }
 
+    [Fact]
+    public void GpuLimitSetting_NoLongerExposed()
+    {
+        // Removed 2026-05-22: GpuLimitPercent was confusingly named (read as
+        // "max % the helper uses" but actually a back-off sensitivity knob).
+        // Helper now uses a hardcoded internal threshold; no user-facing knob.
+        Assert.False(AppSettingsRegistry.TryFind("gpu-limit", out _));
+        Assert.False(AppSettingsRegistry.TryFind("gpu", out _));
+        Assert.False(AppSettingsRegistry.TryFind("gpu-percent", out _));
+    }
+
     [Fact]
     public void Clone_RepairsMissingSections()
     {
@@ -42,8 +52,6 @@ public void Clone_RepairsMissingSections()
     }
 
     [Theory]
-    [InlineData("gpu-limit", "5", "5%")]
-    [InlineData("gpu-limit", "37", "37%")]
     [InlineData("upload-limit", "0", "automatic")]
     [InlineData("upload-limit", "5", "5 MB/s")]
     [InlineData("upload-limit", "12", "12 MB/s")]
@@ -58,10 +66,6 @@ public void Settings_AcceptNumericInputsAndRenderUnits(string key, string input,
     }
 
     [Theory]
-    [InlineData("gpu-limit", "4")]
-    [InlineData("gpu-limit", "76")]
-    [InlineData("gpu-limit", "37%")]
-    [InlineData("gpu-limit", "a lot")]
     [InlineData("upload-limit", "-1")]
     [InlineData("upload-limit", "501")]
     [InlineData("upload-limit", "12 MB/s")]

src/WKVRCProxy.Tests/FfmpegCapabilityProbeTests.cs

@@ -6,18 +6,21 @@ namespace WKVRCProxy.Tests;
 public class FfmpegCapabilityProbeTests
 {
     // Simulate a smoke runner where the first encoder (nvenc) always fails,
-    // second (qsv) always passes. Verifies the demotion + retry logic.
+    // second (amf) always passes. Verifies the demotion + retry logic
+    // across the two discrete-GPU backends. Integrated backends (qsv, mf)
+    // are no longer eligible at all, so they don't participate in the
+    // demote-and-retry chain.
     [Fact]
     public async Task SmokeTest_DemotesFailingEncoderAndTriesNext()
     {
         var nvenc = new HardwareEncoderCapability("h264_nvenc", HardwareEncoderBackend.Nvenc, "NVIDIA NVENC");
-        var qsv = new HardwareEncoderCapability("h264_qsv", HardwareEncoderBackend.Qsv, "Intel QSV");
+        var amf = new HardwareEncoderCapability("h264_amf", HardwareEncoderBackend.Amf, "AMD AMF");
         var location = new FfmpegLocation("ffmpeg.exe", FfmpegLocationKind.Bundled);
 
         var base_ = new FfmpegCapabilityProbeResult(
             location,
             new FfmpegVersionInfo("ffmpeg version 7.1", "7.1"),
-            new[] { nvenc, qsv },
+            new[] { nvenc, amf },
             nvenc,
             FfmpegCapabilityProbeStatus.Ready,
             "ok");
@@ -30,21 +33,60 @@ public async Task SmokeTest_DemotesFailingEncoderAndTriesNext()
             int cvIdx = argList.IndexOf("-c:v");
             string enc = cvIdx >= 0 ? argList[cvIdx + 1] : "?";
             attemptLog.Add(enc);
-            bool pass = enc == "h264_qsv";
+            bool pass = enc == "h264_amf";
             return Task.FromResult(new SmokeTestRunResult(pass ? 0 : 1, false, pass ? "" : "driver error"));
         };
 
         FfmpegCapabilityProbeResult result = await FfmpegCapabilityProbe.RunSmokeTestAsync(
             base_, runner, CancellationToken.None);
 
         Assert.True(result.SmokeTestPassed);
-        Assert.Equal("h264_qsv", result.SmokeTestEncoder);
+        Assert.Equal("h264_amf", result.SmokeTestEncoder);
         Assert.NotNull(result.PreferredEncoder);
-        Assert.Equal("h264_qsv", result.PreferredEncoder!.Value.EncoderName);
+        Assert.Equal("h264_amf", result.PreferredEncoder!.Value.EncoderName);
 
         Assert.Equal(2, attemptLog.Count);
         Assert.Equal("h264_nvenc", attemptLog[0]);
-        Assert.Equal("h264_qsv", attemptLog[1]);
+        Assert.Equal("h264_amf", attemptLog[1]);
+    }
+
+    // When the only fallback candidate after a smoke failure is an integrated
+    // backend, the smoke loop must stop -- not retry on Qsv/MediaFoundation
+    // (which we refuse) and not silently report success.
+    [Fact]
+    public async Task SmokeTest_RefusesIntegratedFallbackWhenDiscreteFails()
+    {
+        var nvenc = new HardwareEncoderCapability("h264_nvenc", HardwareEncoderBackend.Nvenc, "NVIDIA NVENC");
+        var qsv = new HardwareEncoderCapability("h264_qsv", HardwareEncoderBackend.Qsv, "Intel QSV");
+        var location = new FfmpegLocation("ffmpeg.exe", FfmpegLocationKind.Bundled);
+
+        var base_ = new FfmpegCapabilityProbeResult(
+            location,
+            new FfmpegVersionInfo("ffmpeg version 7.1", "7.1"),
+            new[] { nvenc, qsv },
+            nvenc,
+            FfmpegCapabilityProbeStatus.Ready,
+            "ok");
+
+        var attemptLog = new List<string>();
+        FfmpegSmokeRunner runner = (_, args, _, _) =>
+        {
+            var argList = args.ToList();
+            int cvIdx = argList.IndexOf("-c:v");
+            string enc = cvIdx >= 0 ? argList[cvIdx + 1] : "?";
+            attemptLog.Add(enc);
+            return Task.FromResult(new SmokeTestRunResult(1, false, "driver error"));
+        };
+
+        FfmpegCapabilityProbeResult result = await FfmpegCapabilityProbe.RunSmokeTestAsync(
+            base_, runner, CancellationToken.None);
+
+        Assert.False(result.SmokeTestPassed);
+        Assert.Null(result.SmokeTestEncoder);
+        // Only nvenc was tried -- qsv was filtered out of the candidate pool
+        // before the retry loop reached it.
+        Assert.Single(attemptLog);
+        Assert.Equal("h264_nvenc", attemptLog[0]);
     }
 
     [Fact]

src/WKVRCProxy.Tests/FfmpegHelperTests.cs

@@ -33,12 +33,14 @@ V....D h264_amf             AMD AMF H.264 Encoder
     }
 
     [Fact]
-    public void HardwareEncoderProbe_PrefersQsvWhenAvailableToReduceDiscreteGpuContention()
+    public void ChoosePreferred_PicksNvencOverEverything()
     {
         var encoders = new[]
         {
+            new HardwareEncoderCapability("h264_amf", HardwareEncoderBackend.Amf, "AMD AMF"),
             new HardwareEncoderCapability("h264_nvenc", HardwareEncoderBackend.Nvenc, "NVIDIA NVENC"),
             new HardwareEncoderCapability("h264_qsv", HardwareEncoderBackend.Qsv, "Intel QSV"),
+            new HardwareEncoderCapability("h264_mf", HardwareEncoderBackend.MediaFoundation, "Windows MF"),
         };
 
         HardwareEncoderCapability? selected = HardwareEncoderProbe.ChoosePreferred(encoders);
@@ -47,6 +49,69 @@ public void HardwareEncoderProbe_PrefersQsvWhenAvailableToReduceDiscreteGpuConte
         Assert.Equal(HardwareEncoderBackend.Nvenc, selected!.Value.Backend);
     }
 
+    [Fact]
+    public void ChoosePreferred_PicksAmfWhenNvencAbsent()
+    {
+        var encoders = new[]
+        {
+            new HardwareEncoderCapability("h264_amf", HardwareEncoderBackend.Amf, "AMD AMF"),
+            new HardwareEncoderCapability("h264_qsv", HardwareEncoderBackend.Qsv, "Intel QSV"),
+        };
+
+        HardwareEncoderCapability? selected = HardwareEncoderProbe.ChoosePreferred(encoders);
+
+        Assert.NotNull(selected);
+        Assert.Equal(HardwareEncoderBackend.Amf, selected!.Value.Backend);
+    }
+
+    // Integrated-GPU-only systems (Intel iGPU via QSV, or generic MediaFoundation
+    // fallback) refuse to participate as helpers: the encoder block shares
+    // silicon with the user's game render pipeline and accepting work would
+    // cost real frames in-headset. The helper opts out of co-watching entirely
+    // on these systems rather than offering a degraded share.
+    [Fact]
+    public void ChoosePreferred_ReturnsNull_WhenOnlyIntelQsvAvailable()
+    {
+        var encoders = new[]
+        {
+            new HardwareEncoderCapability("h264_qsv", HardwareEncoderBackend.Qsv, "Intel QSV"),
+        };
+
+        Assert.Null(HardwareEncoderProbe.ChoosePreferred(encoders));
+    }
+
+    [Fact]
+    public void ChoosePreferred_ReturnsNull_WhenOnlyMediaFoundationAvailable()
+    {
+        var encoders = new[]
+        {
+            new HardwareEncoderCapability("h264_mf", HardwareEncoderBackend.MediaFoundation, "Windows MF"),
+        };
+
+        Assert.Null(HardwareEncoderProbe.ChoosePreferred(encoders));
+    }
+
+    [Fact]
+    public void ChoosePreferred_ReturnsNull_WhenOnlyQsvAndMfAvailable()
+    {
+        var encoders = new[]
+        {
+            new HardwareEncoderCapability("h264_qsv", HardwareEncoderBackend.Qsv, "Intel QSV"),
+            new HardwareEncoderCapability("h264_mf", HardwareEncoderBackend.MediaFoundation, "Windows MF"),
+        };
+
+        Assert.Null(HardwareEncoderProbe.ChoosePreferred(encoders));
+    }
+
+    [Fact]
+    public void IsDedicatedGpuBackend_AcceptsDiscreteEncodersOnly()
+    {
+        Assert.True(HardwareEncoderProbe.IsDedicatedGpuBackend(HardwareEncoderBackend.Nvenc));
+        Assert.True(HardwareEncoderProbe.IsDedicatedGpuBackend(HardwareEncoderBackend.Amf));
+        Assert.False(HardwareEncoderProbe.IsDedicatedGpuBackend(HardwareEncoderBackend.Qsv));
+        Assert.False(HardwareEncoderProbe.IsDedicatedGpuBackend(HardwareEncoderBackend.MediaFoundation));
+    }
+
     [Fact]
     public void FfmpegLocator_PrefersBundledBinary()
     {
@@ -89,6 +154,29 @@ V..... h264_qsv             Intel Quick Sync Video H.264 encoder
         Assert.Equal("7.1.1-full_build-www.gyan.dev", result.Version!.Value.Version);
     }
 
+    [Fact]
+    public void FfmpegCapabilityProbe_FromOutputsRefusesIntegratedOnlySystem()
+    {
+        var location = new FfmpegLocation("ffmpeg.exe", FfmpegLocationKind.Path);
+        FfmpegCapabilityProbeResult result = FfmpegCapabilityProbe.FromOutputs(
+            location,
+            "ffmpeg version 7.1.1",
+            """
+            Encoders:
+             V..... h264_qsv             Intel Quick Sync Video H.264 encoder
+             V..... h264_mf              Windows MediaFoundation H.264 encoder
+            """);
+
+        Assert.True(result.HasFfmpeg);
+        Assert.False(result.CanUseHardwareH264);
+        Assert.Equal(FfmpegCapabilityProbeStatus.NoHardwareEncoder, result.Status);
+        Assert.Null(result.PreferredEncoder);
+        Assert.Contains("integrated-GPU", result.Message);
+        // The encoders list is still populated so logs / telemetry see what
+        // was found before it was refused.
+        Assert.Equal(2, result.Encoders.Count);
+    }
+
     [Fact]
     public async Task FfmpegCapabilityProbe_ReportsMissingWhenExecutableIsUnavailable()
     {
@@ -445,6 +533,50 @@ public void HelperSelfThrottle_AllowsWorkWhenSignalsAreHealthy()
         Assert.Equal("idle", decision.State);
     }
 
+    // The previous configurable GpuLimitPercent (5..75) is gone -- helper now
+    // uses a hardcoded back-off threshold. Pin both the runs-at-typical-load
+    // case (was previously rejected at default 25 / 88% threshold) and the
+    // pauses-at-near-saturation case so future tweaks to the constant remain
+    // visible in CI.
+    [Fact]
+    public void HelperSelfThrottle_RunsAtModerateGpuLoad()
+    {
+        var settings = new AppSettings().Normalize();
+
+        HelperThrottleDecision decision = HelperSelfThrottle.Evaluate(
+            settings,
+            new HelperRuntimeSignals(
+                OnBattery: false,
+                VrChatRunning: true,
+                GpuBusyPercent: 80, // game using most of the GPU; helper still allowed
+                CpuBusyPercent: 30,
+                ThermalHeadroomPercent: 50,
+                UploadQueueBytes: 0,
+                ConsecutiveFailures: 0));
+
+        Assert.True(decision.CanAcceptWork);
+    }
+
+    [Fact]
+    public void HelperSelfThrottle_PausesWhenGpuNearSaturation()
+    {
+        var settings = new AppSettings().Normalize();
+
+        HelperThrottleDecision decision = HelperSelfThrottle.Evaluate(
+            settings,
+            new HelperRuntimeSignals(
+                OnBattery: false,
+                VrChatRunning: true,
+                GpuBusyPercent: 96, // system genuinely saturated -- helper yields
+                CpuBusyPercent: 30,
+                ThermalHeadroomPercent: 50,
+                UploadQueueBytes: 0,
+                ConsecutiveFailures: 0));
+
+        Assert.False(decision.CanAcceptWork);
+        Assert.Equal("GPU busy", decision.Reason);
+    }
+
     private static TranscodeLease NewLease()
     {
         return new TranscodeLease(

src/WKVRCProxy.Tests/ProtocolRoundTripTests.cs

@@ -278,9 +278,9 @@ public void HelperStatus_frame_matches_mesh_contract()
             CanEncodeH264 = true,
             Status = "idle",
             FfmpegVersion = "7.1.1",
-            Encoder = "h264_qsv",
-            EncoderBackend = "qsv",
-            GpuLimitPercent = 25,
+            Encoder = "h264_nvenc",
+            EncoderBackend = "nvenc",
+            GpuLimitPercent = 0,
             UploadLimitMbps = 0,
             AllowOnBattery = false,
         };
@@ -291,8 +291,10 @@ public void HelperStatus_frame_matches_mesh_contract()
         Assert.Equal("helper_status", doc.RootElement.GetProperty("action").GetString());
         Assert.True(doc.RootElement.GetProperty("sharing").GetBoolean());
         Assert.True(doc.RootElement.GetProperty("can_encode_h264").GetBoolean());
-        Assert.Equal("h264_qsv", doc.RootElement.GetProperty("encoder").GetString());
-        Assert.Equal(25, doc.RootElement.GetProperty("gpu_limit_percent").GetInt32());
+        Assert.Equal("h264_nvenc", doc.RootElement.GetProperty("encoder").GetString());
+        // Wire field retained (older servers still read it). Always 0 now;
+        // the client no longer exposes a user-tunable GPU limit.
+        Assert.Equal(0, doc.RootElement.GetProperty("gpu_limit_percent").GetInt32());
     }
 
     [Fact]

src/WKVRCProxy/AppSettings.cs

@@ -127,9 +127,6 @@ internal sealed class HelperAppSettings
     [JsonPropertyName("gpu_sharing")]
     public bool GpuSharing { get; set; } = true;
 
-    [JsonPropertyName("gpu_limit_percent")]
-    public int GpuLimitPercent { get; set; } = 25;
-
     [JsonPropertyName("upload_limit_mbps")]
     public int UploadLimitMbps { get; set; }
 
@@ -148,7 +145,6 @@ internal sealed class HelperAppSettings
     public HelperAppSettings Clone() => new()
     {
         GpuSharing = GpuSharing,
-        GpuLimitPercent = GpuLimitPercent,
         UploadLimitMbps = UploadLimitMbps,
         AllowOnBattery = AllowOnBattery,
         EncodingQuality = EncodingQuality,
@@ -157,7 +153,6 @@ internal sealed class HelperAppSettings
 
     public void Normalize()
     {
-        GpuLimitPercent = Math.Clamp(GpuLimitPercent, 5, 75);
         UploadLimitMbps = Math.Clamp(UploadLimitMbps, 0, 500);
         EncodingQuality = HelperEncodingQualityNames.Format(
             HelperEncodingQualityNames.ParseOrAuto(EncodingQuality));

src/WKVRCProxy/AppSettingsRegistry.cs

@@ -23,21 +23,6 @@ internal static class AppSettingsRegistry
             completionValues: ["on", "off"],
             aliases: ["gpu-sharing", "helper.gpu-sharing"]),
 
-        new AppSettingDefinition(
-            "gpu-limit",
-            "Maximum GPU share used for video repair.",
-            ["number from 5 to 75; shown as %"],
-            static s => s.Helper.GpuLimitPercent.ToString(CultureInfo.InvariantCulture) + "%",
-            static (AppSettings s, string value, out string error) =>
-            {
-                if (!TryParsePercent(value, 5, 75, out int parsed, out error)) return false;
-                s.Helper.GpuLimitPercent = parsed;
-                return true;
-            },
-            static s => s.Helper.GpuLimitPercent = s_defaults.Helper.GpuLimitPercent,
-            completionValues: ["5", "10", "25", "50", "75"],
-            aliases: ["gpu", "gpu-percent", "helper.gpu-limit"]),
-
         new AppSettingDefinition(
             "upload-limit",
             "Maximum upload speed used for sharing.",