docs: align the stall window comments with the new metering

_validate_stall still guards stall_window_s >= max ttft_timeout_s, but its
stated reason no longer holds: TTFT waiting is productive time and never
reaches the stall account. The check is harmless and stays, so the
docstring now says why it is kept rather than implying a live hazard.
.env.example dropped the "must be >= max TTFT" advice for what the window
actually measures.

.env.example

@@ -38,7 +38,7 @@ LLM_CIRCUIT_BREAKER_COOLDOWN=60          # 或 LLM__BREAKER__COOLDOWN_S
 # LLM_TTFT_TIMEOUT=30                    # 平铺看门狗缺省(成对生效)
 # LLM_INTER_TOKEN_TIMEOUT=15
 # LLM__BREAKER__PROBE_TTL_S=240          # 缺省派生: max(2×最大源超时, cooldown, 最大源超时+5);显式值须 ≥ 最大源超时+5
-# LLM__BACKPRESSURE__STALL_WINDOW_S=300  # stall 双条件判死窗口;须 ≥ 最大源 TTFT
+# LLM__BACKPRESSURE__STALL_WINDOW_S=300  # stall 双条件判死窗口;只计非生产性等待(429 退避/配额轮询/熔断冷却),与 TIMEOUT_S 无耦合,无需按 timeout×retries 放大
 # LLM__BACKPRESSURE__POLL_INTERVAL_S=0.05
 # LLM__SELECTOR=health_aware             # health_aware(默认,M2.5) | round_robin | least_inflight
 # ── M2.5 失败率熔断通道(可选,缺省即生产推荐值)──

src/polygateway/config.py

@@ -238,7 +238,14 @@ class GatewaySettings:
             )
 
     def _validate_stall(self) -> None:
-        """stall 窗口须 ≥ 最慢源 TTFT 上限,防把正常慢首包误判为卡死。"""
+        """stall 窗口须 ≥ 最慢源 TTFT 上限(保守冗余,见下)。
+
+        原理由是"防把正常慢首包误判为卡死"。issue #8 起 stall 只累计**非
+        生产性等待**(429 退避、配额轮询、熔断冷却),TTFT 等待属生产性时间、
+        已不计入 stall 账,该误判在机制上不再可能。校验本身无害且不会误拒
+        任何合理配置,故保留——删除它需同步改动 ARCHITECTURE.md §7.3 的契约
+        补强 G6,超出 issue #8 的范围(2026-08-06 人类定夺)。
+        """
         ttfts = [s.ttft_timeout_s for s in self.sources if s.ttft_timeout_s is not None]
         if ttfts and self.backpressure.stall_window_s < max(ttfts):
             raise ValueError(