shadow: per-pod start jitter knob (start_jitter_ms)

Lockstep process starts make every peer pair dial each other at the same
simulated instant, forcing simultaneous-dial collisions that never occur on
real hosts. pod-i now starts at 5000 + i*start_jitter_ms ms (default 0 keeps
lockstep).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: radiken

src/deployments/experiments/libp2p/shadow_gossipsub.py

@@ -47,6 +47,8 @@ class ExpConfig(BaseModel):
     # Floor (µs) for lsquic engine tick re-arms; needs the tick-floor node image.
     # 0 = stock lsquic behavior (which livelocks quic under Shadow).
     lsquic_tick_floor_us: NonNegativeInt = 0
+    # Per-pod process start stagger (pod-i starts at 5000 + i*jitter ms); 0 = lockstep.
+    start_jitter_ms: NonNegativeInt = 0
     # Job-pod resources, sized for ~10 peers; bump for bigger sims.
     cpu_request: str = "2"
     cpu_limit: str = "4"
@@ -91,6 +93,7 @@ async def _run(self):
             model_unblocked_syscall_latency=cfg.model_unblocked_syscall_latency,
             strace_logging_mode=cfg.strace_logging_mode,
             lsquic_tick_floor_us=cfg.lsquic_tick_floor_us,
+            start_jitter_ms=cfg.start_jitter_ms,
         )
         publisher_config = render_publisher_config(
             num_nodes=cfg.num_nodes,

src/deployments/shadow/builders.py

@@ -56,6 +56,7 @@ def render_shadow_yaml(
     model_unblocked_syscall_latency: bool = False,
     strace_logging_mode: str = "off",
     lsquic_tick_floor_us: int = 0,
+    start_jitter_ms: int = 0,
     requester_app_path: str = _REQUESTER_APP_PATH,
 ) -> dict:
     """Build the shadow.yaml dict: N peer hosts running `./main` + a publisher host
@@ -85,16 +86,21 @@ def render_shadow_yaml(
     if discovery == "kad-dht":
         peer_env["NODE_ROLE"] = "RoleNormal"
         peer_env["SERVICE"] = "bootstrap-0"
-    peer_process = {
-        "path": "./main",
-        "start_time": "5s",
-        "expected_final_state": "running",  # daemon: don't error when alive at stop_time
-        "environment": peer_env,
-    }
+    # start_jitter_ms staggers per-pod process start so peers don't wake and dial at
+    # one simulated instant (lockstep wakes force simultaneous-dial collisions that
+    # never occur on real hosts).
     hosts = {
         f"pod-{i}": {
             "network_node_id": 0,
-            "processes": [peer_process],
+            "processes": [
+                {
+                    "path": "./main",
+                    "start_time": f"{5000 + i * start_jitter_ms}ms",
+                    # daemon: don't error when alive at stop_time
+                    "expected_final_state": "running",
+                    "environment": peer_env,
+                }
+            ],
         }
         for i in range(num_nodes)
     }

src/deployments/shadow/tests/test_builders.py

@@ -108,7 +108,7 @@ def test_peer_process_is_daemon_with_env(self):
         )
         peer = sy["hosts"]["pod-0"]["processes"][0]
         assert peer["path"] == "./main"
-        assert peer["start_time"] == "5s"
+        assert peer["start_time"] == "5000ms"
         assert peer["expected_final_state"] == "running"
         env = peer["environment"]
         assert env["PEERS"] == "3"