Fix graceful websocket EOF reconnect and release 0.2.2

[nekrasovp]

Defect

In predxt 0.2.1, messages() in PolymarketWsClient, KalshiWsClient, and OpinionWsClient handles ConnectionClosed/OSError, but normal exhaustion of the websocket async iterator immediately re-enters the read loop. Connection health remains true, reconnect_count is unchanged, no backoff/reconnect/resubscribe occurs, and Opinion's heartbeat remains active.

Risks: ingestion stops while reporting healthy; repeatedly iterating an exhausted stream can spin without yielding and consume CPU, preventing timely cancellation.

Downstream evidence reported by the integration task: an application snapshot passed 696 tests (1 skipped) with a runtime substitution using predxt, but test_messages_backoff_when_stream_ends_normally reproducibly hung. This issue addresses the SDK only; no downstream application or production changes are included.

Acceptance criteria

• All three clients mark connection health false on graceful EOF, increment reconnect_count once, wait for backoff, reconnect and restore the subscription.
• Opinion stops the old heartbeat before waiting and creates a heartbeat for the recovered connection.
• Explicit close, manager stop and cancellation do not initiate reconnect; shutdown is prompt and repeatable, including during backoff.
• Deterministic regression tests cover all three venues, bounded iteration/no busy loop, exact reconnect/resubscribe counts, health, heartbeat and raw payload/import compatibility.
• Full AGENTS.md validation passes, plus clean clone and isolated wheel/sdist installation checks.
• Release next patch via the repository's release.yml Trusted Publishing workflow; verify CI and publish success.
• Install the released package from public PyPI in a fresh environment, verify version, all client imports, graceful reconnect regression smoke and artifact SHA256 against PyPI JSON.
• Attach PR, exact commit, tag, GitHub Release, PyPI and validation evidence; close only after successful public installation.

Release target

Live PyPI JSON checked on 2026-09-11: latest 0.2.1; existing versions 0.1.0, 0.2.0, 0.2.1. Target patch: 0.2.2. Starting origin/main: 80d80a0556cb30d8c4622cc6c92c2f980822d59b.

Released

Resolved in PR #13, commit e2bc5ed4b73272dfa414aafb133f718176b09283, tag v0.2.2. GitHub Release and PyPI 0.2.2 are public. Fresh public wheel and sdist installations each passed all 36 lifecycle regressions; full validation and artifact hashes are recorded in the closing evidence comment.

[nekrasovp]

Implementation and validation are ready in PR #13.

• Base: 80d80a0556cb30d8c4622cc6c92c2f980822d59b (v0.2.1)
• Exact PR head: 0c60aa9b95fc9fb47ad8c8d8b289a72460bc506f
• CI: https://github.com/hzprotocol/predxt/actions/runs/34606084326 — both Python 3.12 and 3.13 jobs succeeded.
• Full local and clean git clone --no-local gates: 94 tests passed (36 new regressions), ruff, mypy (25 files), build, twine wheel/sdist checks, strict docs build.
• Baseline defect proof: all three graceful-EOF cases fail against 0.2.1 with the bounded exhausted-socket iteration assertion; all pass on the PR head.
• Independent wheel and sdist installs in fresh Python 3.12 environments: version/import checks and 36/36 regression cases passed in each. All 25 packaged source files in both artifacts exactly match committed HEAD.

Normal merge was rejected by GitHub because the branch requires one approving review. An exact-head administrative merge requires maintainer authorization. No tag, GitHub Release or PyPI publication has occurred yet, and this issue remains open until successful public PyPI installation.

[nekrasovp]

Released and verified from public PyPI: predxt 0.2.2.

Identities and links

• PR: Fix graceful websocket reconnect and release 0.2.2 #13 (merged after maintainer authorization for the exact-head administrative merge)
• PR head: 0c60aa9b95fc9fb47ad8c8d8b289a72460bc506f
• Release/main commit: e2bc5ed4b73272dfa414aafb133f718176b09283
• Tag: v0.2.2, pointing to that exact release commit
• GitHub Release: https://github.com/hzprotocol/predxt/releases/tag/v0.2.2
• PyPI: https://pypi.org/project/predxt/0.2.2/
• PyPI JSON: https://pypi.org/pypi/predxt/0.2.2/json

Validation

• PR CI: https://github.com/hzprotocol/predxt/actions/runs/34606084326 — Python 3.12 and 3.13, 94 passed each.
• Main CI: https://github.com/hzprotocol/predxt/actions/runs/34620467855 — Python 3.12 and 3.13, 94 passed each.
• Pages: https://github.com/hzprotocol/predxt/actions/runs/34620467791 — success.
• Release: https://github.com/hzprotocol/predxt/actions/runs/34620593107 — build 94 passed, publish success, PyPI Trusted Publishing and attestations confirmed.
• Full AGENTS.md gate on a clean git clone --no-local at the release commit: uv sync, ruff, mypy (25 files), 94 tests passed, build, twine wheel/sdist checks; strict docs build also passed; clean before/after.
• Three graceful-EOF cases reproduce the busy-loop defect on 0.2.1 with a bounded exhausted-socket assertion; all 36 added lifecycle cases pass on 0.2.2.

Public installation proof

After publication, created two fresh Python 3.12 environments and used isolated pip with --no-cache-dir --index-url https://pypi.org/simple predxt==0.2.2; the second install additionally used --no-binary=predxt to build the public sdist. No local source override or editable install was used.

Both installed environments report importlib.metadata.version("predxt") == predxt.__version__ == "0.2.2", import all three public websocket clients from site-packages, have no direct_url.json, and pass 36/36 regression cases. The tests cover exact EOF backoff/reconnect/resubscribe, health/counters, heartbeat replacement, cancellation, explicit close/stop during idle reads and retry waits, idempotence, imports and raw payload compatibility. Wheel dependency check also passes.

Pip installation reports identify files.pythonhosted.org artifacts selected through the public index. Their SHA256 values match PyPI JSON, downloaded GitHub Release assets, and the release workflow artifacts. All 25 packaged source files in both distributions match the release commit byte for byte.

Artifact	SHA256	Bytes
predxt-0.2.2-py3-none-any.whl	8124965b5ac7031cb59bb164d226baae52ef4fcb85ffcf04e53f5fc5c7f993af	37299
predxt-0.2.2.tar.gz	120cc93cd8f68f062e1dfe3de5ba471616e8f9327c21d7de8e3a34fc6f143916	62720

The project page, version JSON, simple index and revalidated latest JSON all show 0.2.2. The initial simple-index propagation delay was resolved before the successful public installs.

No release blocker remains. Live venue availability/authentication were not exercised by these deterministic offline tests. The workflow has existing Node.js action deprecation annotations, but all jobs completed successfully. No prediction-platform or production ArbLense changes were made.

All acceptance criteria are satisfied; closing only after these successful public installations.