Persist Quick Tunnel rate-limit cooldown across supervised restarts

[RobLe3]

Context

FORGE WQ-186 / iicp.network#570 researched stable relay fallback beyond accountless Cloudflare Quick Tunnel rate limits.

The Python client already detects Cloudflare Quick Tunnel rate limits such as HTTP 429 / error code 1015 and applies an in-process cooldown via IICP_TUNNEL_RATE_LIMIT_COOLDOWN_S. That prevents churn inside one running process.

Remaining gap

The cooldown is process-local. Under service or Docker supervision, a crash or restart loop can forget the cooldown and attempt another accountless Quick Tunnel creation immediately, recreating rate-limit pressure.

Desired behavior

• Persist a coarse quick_tunnel_rate_limited_until marker in the node state/config directory.
• Check the persisted marker before spawning accountless cloudflared tunnel --url ....
• Keep IICP_TUNNEL_RATE_LIMIT_COOLDOWN_S as the operator override.
• Preserve verified direct endpoints and IICP_PUBLIC_ENDPOINT behavior exactly as-is.
• Keep accountless Quick Tunnel as a fallback, not a production relay requirement.
• Add tests proving supervised restarts respect the persisted cooldown and do not affect direct/public-endpoint paths.

Acceptance

• A rate-limited tunnel attempt suppresses later attempts after process restart until the cooldown expires.
• Existing reachability/tunnel tests still pass.
• Error/log output remains operator-actionable: configure a stable public endpoint / named tunnel for production relay use.

Related: RobLe3/iicp.network#570 and #538.

[RobLe3]

FORGE WQ-203 implementation complete (2026-06-27).

Implemented:

• Python Quick Tunnel cooldown now persists a coarse quick_tunnel_rate_limited_until marker under the IICP state directory (IICP_HOME/state/quick_tunnel_rate_limit.json, or IICP_TUNNEL_RATE_LIMIT_STATE_FILE when explicitly overridden).
• open_quick_tunnel() checks both process-local cooldown and persisted cooldown before spawning accountless cloudflared.
• Rate-limit detection still honors IICP_TUNNEL_RATE_LIMIT_COOLDOWN_S.
• Persistence failures are non-fatal: the current process still keeps its in-memory cooldown.
• Added regression coverage for a supervised restart: process-local state cleared, persisted cooldown still suppresses a new Quick Tunnel spawn.
• Existing direct/public-endpoint behavior remains covered by reachability-plan tests.

Validation:

• .venv/bin/python -m pytest tests/test_tunnel.py tests/test_reachability_plan.py — 21 passed.
• .venv/bin/python -m pytest — 953 passed, 2 skipped.
• git diff --check — passed.

Note: this repository does not have .sentrux/rules.toml, so sentrux check . is not applicable here.

[RobLe3]

Closing after WQ-203 implementation: persistent Quick Tunnel rate-limit cooldown added and full Python test suite passed (953 passed, 2 skipped).