feat(reliability+network): SR-174 — network-state pre-click gate

Adds three new modules + extends runner_policy with PROVIDER_NETWORK_TUNING.

- survey/network/beacon_filter.py: regex-based filter for analytics
  beacons (Google Analytics, DoubleClick, Segment, Mixpanel, etc.).
  Configurable, extensible, with negative tests against survey-tracking
  URLs to prevent over-matching (e.g. 'survey-analytics-provider.com'
  must NOT match).

- survey/network/cdp_network_tracker.py: Playwright-CDPSession-based
  network monitor. Subscribes to Network.requestWillBeSent /
  responseReceived / loadingFailed / loadingFinished. Per-page-scoped,
  detaches cleanly on close (try/finally + async context manager).
  Beacons filtered out of pending count. Snapshot is monotonic-clock
  based, immutable, safe to take during traffic.

- survey/reliability/network_gate.py: async wait_for_network_quiet()
  that polls the tracker on a 10 ms cadence until pending_count <=
  max_pending AND last_response_age >= quiet_ms. On timeout, emits a
  'network_never_quiet' event (NOT a hang) and returns force_proceed=
  True — caller decides escalation. Strict caps: max_wait_ms hard
  upper-bound, no infinite waits possible.

- survey/runner_policy.py: PROVIDER_NETWORK_TUNING table with profiles
  for pollfish (strict), cint (relaxed for beacons), lucid (tight),
  qualtrics (medium). Default fallback. get_network_tuning() is
  pure-function.

Tests (45 cases, all green on Python 3.13):

- test_beacon_filter.py (8 cases): default beacon match, survey-tracking
  preservation, custom-pattern injection, regex-compile-once perf.
- test_cdp_network_tracker.py (17 cases): full CDP event lifecycle,
  beacon-exclusion, finish + fail event paths, monotonic ordering,
  context-manager attach/detach, idempotent close, race-condition
  detach-during-event, snapshot-immutability.
- test_network_gate.py (20 cases): immediate-pass when already quiet,
  wait-for-pending-to-finish, beacon-doesn't-block, timeout +
  force-proceed semantics, EventEmitter integration, provider-tuning
  end-to-end (pollfish vs cint vs lucid behavior demonstrated).

Latency (micro-benchmark, in-process FakePage):
  best-case (already quiet)  : p50=0.00ms  p95=0.02ms
  after 1 request settles    : p50=30.78ms p95=30.93ms
(quiet_ms=10, single 20ms request -> ~30ms total = correct)

Path-doctrine: 100% inside survey-cli/survey/. No new top-level dirs.

Scope intentionally NOT included (separate work):
- safe_executor.py integration: deferred until SR-169 lands (composes
  DOM-stability + network-quiet behind one stability.py facade). This
  PR ships the gate as a primitive, ready to be wired in.
- proxy hot-rotation telemetry: out of scope.

Refs: #179 (SR-174), depends-on #175 (SR-169) for full integration.

Co-authored-by: v0-agent <v0-agent@stealth-runner.local>

Author: Delqhi

survey-cli/survey/network/__init__.py

@@ -1,38 +1,46 @@
 """
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║              STEALTH-RUNNER — Network Module (SR-151)                        ║
-║                                                                              ║
-╠══════════════════════════════════════════════════════════════════════════════╣
-║                                                                              ║
-║  Package marker and public exports for the network module.                  ║
-║                                                                              ║
-║  EXPORTS:                                                                    ║
-║  ────────                                                                    ║
-║  ProxyEntry      - Dataclass representing a single proxy                    ║
-║  ProxyPool       - Thread-safe pool manager with score-based selection      ║
-║  get_proxy_pool  - Singleton getter for global pool instance               ║
-║  score           - Calculate IP quality score                               ║
-║  persist_event   - Log proxy event to JSONL                                ║
-║  is_cold         - Check if score is below cold threshold                  ║
-║                                                                              ║
-╚══════════════════════════════════════════════════════════════════════════════╝
+Stealth-Runner — Network Module.
 
-Closes #151
+SR-151: Proxy pool, IP-quality scoring.
+SR-174: Per-page CDP network tracker + beacon filter (pre-click gate input).
+
+Exports:
+    Proxy pool (SR-151):
+        ProxyEntry, ProxyPool, get_proxy_pool
+        score, persist_event, is_cold, load_events, aggregate_stats
+
+    Pre-click gate inputs (SR-174):
+        BeaconFilter, DEFAULT_BEACON_PATTERNS, get_default_filter, is_beacon
+        CdpNetworkTracker, NetworkActivity
 """
 
 from .proxy_pool import ProxyEntry, ProxyPool, get_proxy_pool
 from .ip_quality import score, persist_event, is_cold, load_events, aggregate_stats
+from .beacon_filter import (
+    BeaconFilter,
+    DEFAULT_BEACON_PATTERNS,
+    get_default_filter,
+    is_beacon,
+)
+from .cdp_network_tracker import CdpNetworkTracker, NetworkActivity
 
 __all__ = [
-    # proxy_pool.py exports
+    # proxy_pool.py exports (SR-151)
     "ProxyEntry",
     "ProxyPool",
     "get_proxy_pool",
-    # ip_quality.py exports
+    # ip_quality.py exports (SR-151)
     "score",
     "persist_event",
     "is_cold",
     "load_events",
     "aggregate_stats",
+    # beacon_filter.py exports (SR-174)
+    "BeaconFilter",
+    "DEFAULT_BEACON_PATTERNS",
+    "get_default_filter",
+    "is_beacon",
+    # cdp_network_tracker.py exports (SR-174)
+    "CdpNetworkTracker",
+    "NetworkActivity",
 ]

survey-cli/survey/network/beacon_filter.py

@@ -0,0 +1,122 @@
+"""
+Beacon filter — URL classification for non-essential network requests.
+
+SR-174: Pre-Click Network Gate.
+
+Analytics pings, telemetry beacons, and similar fire-and-forget requests must
+NOT count toward "pending request" totals — otherwise chatty providers like Cint
+would never satisfy a `pending == 0` gate.
+
+Design notes:
+    - Patterns are anchored to specific known-analytics signatures, not greedy
+      substring matches. The regex ``analytics`` alone would erroneously match
+      ``survey-analytics-provider.com`` and break survey progress-tracking.
+    - All patterns are precompiled at module import (no per-request compile cost).
+    - The filter is conservative: when in doubt, count the request. False
+      positives (beacons treated as real) only slow us down. False negatives
+      (real requests treated as beacons) silently break the gate.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Pattern
+
+# Public default patterns. Order does not matter (any match -> beacon).
+# Each pattern is anchored to a domain or path fragment that we have observed
+# in production logs across pollfish/cint/lucid/qualtrics traffic.
+DEFAULT_BEACON_PATTERNS: tuple[str, ...] = (
+    # Major analytics providers (full domain match).
+    r"^https?://(?:[a-z0-9-]+\.)*google-analytics\.com/",
+    r"^https?://(?:[a-z0-9-]+\.)*googletagmanager\.com/",
+    r"^https?://(?:[a-z0-9-]+\.)*doubleclick\.net/",
+    r"^https?://(?:[a-z0-9-]+\.)*facebook\.com/tr[/?]",
+    r"^https?://(?:[a-z0-9-]+\.)*hotjar\.com/",
+    r"^https?://(?:[a-z0-9-]+\.)*mixpanel\.com/",
+    r"^https?://(?:[a-z0-9-]+\.)*segment\.(?:io|com)/",
+    r"^https?://(?:[a-z0-9-]+\.)*amplitude\.com/",
+    r"^https?://(?:[a-z0-9-]+\.)*sentry\.io/api/[0-9]+/(?:envelope|store)",
+    r"^https?://(?:[a-z0-9-]+\.)*bugsnag\.com/",
+    r"^https?://(?:[a-z0-9-]+\.)*newrelic\.com/",
+    # Path fragments that are conventionally beacons regardless of host.
+    # Anchored to "/beacon", "/telemetry", "/_/log" etc. — must be a path
+    # segment, not a substring.
+    r"(?:^|/)beacon(?:/|$|\?)",
+    r"(?:^|/)telemetry(?:/|$|\?)",
+    r"(?:^|/)_/log(?:/|$|\?)",
+    r"(?:^|/)collect(?:/|$|\?)",  # GA4 endpoint
+    r"(?:^|/)gtag/js",
+    # Pixel-style trackers and click pixels with utm/track/click query keys.
+    r"\.gif\?(?:[a-z0-9_=&%-]*&)*(?:utm|track|click)",
+)
+
+
+class BeaconFilter:
+    """Classify request URLs as 'beacon' (analytics) or 'real' (foreground).
+
+    Patterns are compiled once at construction. The instance is thread-safe
+    because compiled regex objects are immutable.
+
+    Args:
+        patterns: Iterable of regex pattern strings. If omitted, uses
+            ``DEFAULT_BEACON_PATTERNS``. Patterns are matched case-insensitively.
+        extra: Additional patterns to extend the default set. Used by
+            provider-specific configuration without losing the defaults.
+    """
+
+    __slots__ = ("_compiled",)
+
+    def __init__(
+        self,
+        patterns: Iterable[str] | None = None,
+        *,
+        extra: Iterable[str] | None = None,
+    ) -> None:
+        base = tuple(patterns) if patterns is not None else DEFAULT_BEACON_PATTERNS
+        if extra:
+            base = base + tuple(extra)
+        self._compiled: tuple[Pattern[str], ...] = tuple(
+            re.compile(p, re.IGNORECASE) for p in base
+        )
+
+    def is_beacon(self, url: str) -> bool:
+        """Return True if ``url`` matches any beacon pattern.
+
+        Empty/None-like URLs are treated as non-beacon to avoid silently
+        absorbing malformed events.
+        """
+        if not url:
+            return False
+        for pat in self._compiled:
+            if pat.search(url):
+                return True
+        return False
+
+
+# Module-level singleton for callers that don't need custom patterns.
+_default_filter: BeaconFilter | None = None
+
+
+def get_default_filter() -> BeaconFilter:
+    """Return a shared :class:`BeaconFilter` using ``DEFAULT_BEACON_PATTERNS``.
+
+    Constructed lazily on first call. Subsequent calls return the same
+    instance (compiled patterns are immutable and reusable).
+    """
+    global _default_filter
+    if _default_filter is None:
+        _default_filter = BeaconFilter()
+    return _default_filter
+
+
+def is_beacon(url: str) -> bool:
+    """Convenience: classify ``url`` using the default beacon filter."""
+    return get_default_filter().is_beacon(url)
+
+
+__all__ = [
+    "BeaconFilter",
+    "DEFAULT_BEACON_PATTERNS",
+    "get_default_filter",
+    "is_beacon",
+]