audit/housekeeping: close Wave A done-but-open issues + land Wave B-1 docs

[AndresL230]

Summary

Audit of open issues against the current main finds that several were fully resolved by Wave A (PRs #29, #30, #31) but never received a Closes #N reference in their PR descriptions, so they're still sitting in the open list. This PR closes them via magic phrases and bundles the Wave B-1 spec + plan docs that drove the audit.

Closes (Wave A — fully resolved on main)

• Closes Code hygiene: unused import, raise exc drops traceback context #13 — Code hygiene: unused MAX_BUCKETS import removed in _transport.py; every raise exc replaced with bare raise in _interceptor.py. Verified on main post-Wave A.
• Closes Middleware silently drops windows on 401, no escalation path #14 — 401 escalation with RecostAuthError → RecostFatalAuthError after 5 consecutive failures; transport suspends. Implemented in _transport.py::_handle_cloud_result. Tests: test_first_401_emits_recost_auth_error, test_fifth_consecutive_401_emits_fatal_and_suspends.
• Closes Python interceptor reentrancy guard is task-local, not thread-local #15 — Reentrancy guard now spans both ContextVar (async task) and threading.local (OS thread). Implemented in _interceptor.py::_is_in_interceptor / _enter_interceptor / _exit_interceptor. Tests in test_reentrancy.py.
• Closes Mode detection is silent — invalid API key auto-enters cloud mode and fails #17 — init() validates api_key starts with rc- and is a non-empty string; raises ValueError otherwise. Implemented in _init.py:176-186. Tests: test_init_rejects_string_undefined_as_api_key, test_init_rejects_non_string_api_key, test_init_accepts_valid_rc_prefix.
• Closes Rate-limit 429 is not honored — drop window with no Retry-After, no typed event #18 — 429 honored: Retry-After parsed (int seconds + HTTP-date), RecostRateLimitError emitted, window re-queued via defer_callback, next flush deferred. Implemented in _transport.py::_handle_cloud_result + _init.py::_defer. Tests: test_429_emits_rate_limit_error_and_invokes_defer, test_429_does_not_increment_auth_counter, test_post_cloud_parses_retry_after_seconds_on_429.

Closes (Wave B-1 audit)

• Closes urllib3 wrapper maintenance: dead kwargs + brittle import-time defaults #11 — _UNSET sentinel in _interceptor.py:48 defers urllib3.util.Timeout.DEFAULT_TIMEOUT lookup to function-body time (no longer at import); dead pool_connections / pool_maxsize kwargs are gone from the _patched_urlopen signature. See audit comment.

Diff

Pure docs — no production code changes. Adds the Wave B-1 design spec and implementation plan that drove this audit:

• docs/superpowers/specs/2026-05-13-wave-b1-test-fortification-design.md
• docs/superpowers/plans/2026-05-13-wave-b1-test-fortification.md

These are reference material for the test-fortification work in PR #33 (merged) and PR #34 (open). Landing them on main keeps the doc trail co-located with the Wave A spec/plan already on main.

Test plan

• CI green (docs-only change; tests should be unaffected).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@AndresL230 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 38 minutes and 41 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f6059d3c-36e2-4915-9caa-238c6bf934e2

📥 Commits

Reviewing files that changed from the base of the PR and between 83d8784 and 1ecf7df.

📒 Files selected for processing (2)

• docs/superpowers/plans/2026-05-13-wave-b1-test-fortification.md
• docs/superpowers/specs/2026-05-13-wave-b1-test-fortification-design.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch audit/housekeeping

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}