docs: clarify tor_nodes overrides listener first hop

The first hop in each listener's chain is replaced at connection time
by round-robin selection from tor_nodes. Added comments in both the
example config and the server code to make this precedence explicit.

config/example.yaml

@@ -32,8 +32,8 @@ chain:
 #     state_file: /data/pool-clean.json
 #     refresh: 300
 #     test_interval: 120
-#     test_timeout: 8
+#     test_timeout: 12
-#     max_fails: 3
+#     max_fails: 5
 #   mitm:                             # MITM-capable proxies
 #     sources:
 #       - url: http://10.200.1.250:8081/proxies/all
@@ -41,8 +41,8 @@ chain:
 #     state_file: /data/pool-mitm.json
 #     refresh: 300
 #     test_interval: 120
-#     test_timeout: 8
+#     test_timeout: 12
-#     max_fails: 3
+#     max_fails: 5
 
 # Single proxy pool (legacy, still supported -- becomes pool "default"):
 # proxy_pool:
@@ -75,8 +75,11 @@ chain:
 #   newnym_interval: 0             # periodic NEWNYM (seconds, 0 = manual only)
 
 # Multi-Tor round-robin -- distribute traffic across multiple Tor nodes.
-# When present, the first hop in each listener's chain is replaced at
+# When present, the first hop in each listener's chain is REPLACED at
-# connection time by round-robin selection from this list.
+# connection time by round-robin selection from this list. The first hop
+# specified in each listener's chain acts as a fallback only; tor_nodes
+# takes precedence for both client traffic and pool health tests.
+# Connection pools are pre-warmed for every node listed here.
 # tor_nodes:
 #   - socks5://10.200.1.1:9050
 #   - socks5://10.200.1.254:9050
@@ -110,7 +113,7 @@ chain:
 #       - localhost                      # exact hostname
 #       - .local                         # domain suffix
 #     chain:
-#       - socks5://127.0.0.1:9050
+#       - socks5://127.0.0.1:9050        # first hop (overridden by tor_nodes)
 #       - [pool:clean, pool:mitm]        # random choice per connection
 #       - [pool:clean, pool:mitm]        # independent random choice
 #

src/s5p/server.py

@@ -208,6 +208,7 @@ async def _handle_client(
             else:
                 effective_chain = list(listener.chain)
                 fhp = first_hop_pool
+                # tor_nodes round-robin overrides the listener's first hop
                 if tor_rr and effective_chain:
                     node = tor_rr.next()
                     effective_chain[0] = node