docs: justify 0.5 margin factor and clarify threshold changes in tests

Author: prince8273

distributed/stealing.py

@@ -488,7 +488,9 @@ def balance(self) -> None:
                     comm_cost_victim = self.scheduler.get_comm_cost(ts, victim)
                     compute = self.scheduler._get_prefix_duration(ts.prefix)
 
-                    # Require at least 50% ROI on the network transfer cost to prevent thrashing
+                    # Be conservative about marginal steals: require headroom equal
+                    # to 50% of the thief's transfer cost to absorb estimation noise
+                    # and routine network jitter.
                     margin = comm_cost_thief * 0.5
 
                     would_steal_without_margin = (

distributed/tests/test_steal.py

@@ -1449,6 +1449,8 @@ def func(*args):
     "cost, ntasks, expect_steal",
     [
         pytest.param(10, 10, False, id="not enough work to steal"),
+        # The 50% margin heuristic raises the minimum backlog needed to justify
+        # stealing these expensive tasks; 12 was enough before, 17 is enough now.
         pytest.param(10, 17, True, id="enough work to steal"),
         pytest.param(20, 17, False, id="not enough work for increased cost"),
     ],
@@ -2028,6 +2030,9 @@ async def test_reject_count_margin_metric(c, s, a, b):
     steal = s.extensions["stealing"]
     await steal.stop()
 
+    # Use enough short tasks to satisfy Scheduler.check_idle_saturated() for a
+    # single busy worker while still keeping the steal in the margin-rejection
+    # window once get_comm_cost() is patched below.
     futures = c.map(
         slowidentity,
         range(21),