fix: close remaining audit lifecycle gaps

[yisding]

Stack

This is a follow-up to #704 and intentionally targets agent/fix-subagent-audit-bugs. Merge #704 first, then retarget this PR to main if GitHub does not do so automatically.

Problem

The final post-#704 audit found a small set of remaining lifecycle gaps:

• shared teardown helpers could still misclassify child cancellation versus a newly cancelled caller
• persistent multi-context TTS could close contexts/sockets while an admitted send was still in progress
• WebTransport handler cleanup failures could lose the exact transport needed for retry
• WebTransport accepted invalid session caps and audio geometry that the raw mono PCM16 wire protocol cannot represent

Changes

• use per-await cancellation baselines in RuntimeScope.drain, server _safe_await, and session-manager owned-stop joins
• make persistent TTS close wait for admitted sends, close send admission synchronously, and reject queued/late sends after closure begins
• retain failed WebTransport handler transports in server-owned cleanup state and retry them during stop
• count pending WebTransport cleanup against admission and block restart until cleanup succeeds
• validate positive integer WebTransport session caps and mono PCM16 audio format
• remove the now-stale debug/bundle.py Ruff complexity exemption
• add deterministic regressions for every behavior

Impact

These fixes prevent false caller cancellation, replay state being armed after a context has closed, leaked WebTransport sessions after teardown failure, and invalid raw-audio configurations reaching runtime.

Validation

• full non-live suite: 7341 passed, 306 skipped
• full TTS suite: 340 passed, 4 skipped
• all WebTransport tests: 97 passed, 15 skipped
• cancellation-helper focused suites: 90 passed
• full-source mypy: 278 source files clean
• changed-file Ruff lint/format: clean
• git diff --check: clean

Summary by CodeRabbit

• Bug Fixes
  • Improved cancellation handling so existing cancellation requests are preserved while cleanup completes.
  • WebTransport sessions now enforce valid concurrency and mono PCM16 audio settings.
  • Failed WebTransport disconnect cleanup is retained and retried during shutdown.
  • Improved WebSocket send and close coordination to prevent sends from reaching a closing connection.
• Tests
  • Added coverage for cancellation, cleanup retries, audio configuration, session limits, and concurrent WebSocket shutdown behavior.

[coderabbitai]

Warning

Review limit reached

@yisding, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 59 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 808d8b96-0759-40fb-aa55-5f72f4a22322

📥 Commits

Reviewing files that changed from the base of the PR and between 4e9b34a and e68da53.

📒 Files selected for processing (10)

• src/easycat/runtime/scope.py
• src/easycat/server/transports.py
• src/easycat/session_manager.py
• src/easycat/transports/webtransport.py
• src/easycat/tts/_multi_context_ws.py
• tests/runtime/test_scope.py
• tests/server/test_capacity_gate_drain.py
• tests/session/test_session_manager.py
• tests/transports/test_webtransport_server_protocol.py
• tests/tts/test_multi_context_ws.py

📝 Walkthrough

Walkthrough

Changes

Cancellation-aware cleanup

Layer / File(s)	Summary
Cancellation-count-aware cleanup helpers src/easycat/runtime/scope.py, src/easycat/server/transports.py, src/easycat/session_manager.py, tests/runtime/test_scope.py, tests/server/test_capacity_gate_drain.py, tests/session/test_session_manager.py	Cleanup helpers preserve pre-existing cancellation and propagate cancellation received during cleanup. Tests cover both cases.

WebTransport lifecycle

Layer / File(s)	Summary
Configuration and admission checks src/easycat/transports/webtransport.py, tests/transports/test_webtransport_connection_transport.py	Configuration validates session capacity and mono PCM16 audio. Pending cleanup transports count toward capacity.
Transport cleanup retry lifecycle src/easycat/transports/webtransport.py, tests/transports/test_webtransport_server_protocol.py	Failed transport cleanup remains tracked and is retried during shutdown until it succeeds.

Multi-context WebSocket lifecycle

Layer / File(s)	Summary
Serialized send admission src/easycat/tts/_multi_context_ws.py, tests/tts/test_multi_context_ws.py	Sends use shared locking and lifecycle validation. Queued sends revalidate admission before writing.
Close transaction and fallback cleanup src/easycat/tts/_multi_context_ws.py	Close operations use ordered locks, bounded close writes, and coordinated fallback socket cleanup.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ContextSend
  participant MultiContextWebSocket
  participant WebSocket
  participant CloseTransaction
  ContextSend->>MultiContextWebSocket: request send
  MultiContextWebSocket->>MultiContextWebSocket: acquire send lock and validate admission
  MultiContextWebSocket->>WebSocket: write frames
  CloseTransaction->>MultiContextWebSocket: acquire close locks
  CloseTransaction->>WebSocket: send bounded close frame
  CloseTransaction->>WebSocket: close captured socket

Loading

Possibly related PRs

• yisding/easycat#443: Related TTS task cancellation and lifecycle cleanup logic.
• yisding/easycat#446: Related timeout and speculative TTS task cancellation behavior.
• yisding/easycat#631: Related barge-in cleanup and session shutdown behavior.

Suggested reviewers: claude

Poem

A rabbit checks each cancel call,
Keeps cleanup paths from losing all.
WebTransport tries its close once more,
While sends wait safely by the door.
PCM16 hops in tune. 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the pull request’s main purpose: fixing remaining audit-related lifecycle and cleanup gaps.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/fix-audit-followups

---

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.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4355d3779a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/easycat/tts/_multi_context_ws.py`:
- Around line 635-644: In _close_socket_only, keep incrementing
_fallback_close_waiters before awaiting _connect_lock, but move the _closing =
True assignment inside that lock and after the self._closed early return.
Preserve the existing lock ordering and permanent-close guard so unexpected
socket failures during the lock wait still reach _finalize_reader as errors.
- Around line 411-414: Move the snapshot-related comment to the `ws` capture
around the existing snapshot assignment, documenting that it occurs before
cancelling the reader. Replace the current comment above
`_cancel_background_tasks()` with a concise note that the reader’s `finally`
block nulls `self._ws`, preserving the existing cancellation and cleanup
behavior.

In `@tests/tts/test_multi_context_ws.py`:
- Around line 699-702: Bound the teardown awaits in this test with short
asyncio.wait_for timeouts, including the await sending and await closing joins
shown here and the corresponding teardown join around line 734. Preserve the
existing RuntimeError assertion while ensuring a wedged send or close fails fast
instead of hanging indefinitely.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d7b2fea8-d9e6-4305-ac62-888b814e5d29

📥 Commits

Reviewing files that changed from the base of the PR and between 3069431 and 4e9b34a.

📒 Files selected for processing (11)

• src/easycat/runtime/scope.py
• src/easycat/server/transports.py
• src/easycat/session_manager.py
• src/easycat/transports/webtransport.py
• src/easycat/tts/_multi_context_ws.py
• tests/runtime/test_scope.py
• tests/server/test_capacity_gate_drain.py
• tests/session/test_session_manager.py
• tests/transports/test_webtransport_connection_transport.py
• tests/transports/test_webtransport_server_protocol.py
• tests/tts/test_multi_context_ws.py