[ShivaniSharma14]

## Summary

Fixes #509, where docket watch may exit with code 0 while the task is still running.

Problem

The timeout handling in iterate_with_timeout() used asyncio.wait_for() to await the next item from the subscription iterator. When the timeout expired, wait_for() cancelled the pending read. This could terminate the async subscription iterator, causing the watch command to stop waiting before the task reached a terminal state.

Changes

• Keep the pending iterator read alive across polling timeouts.
• Yield None when a timeout occurs, allowing the caller to continue its polling behavior.
• Cancel any remaining pending read and close the iterator during cleanup.
• Add a regression test verifying that the iterator continues and returns its result after a timeout.

Testing

python -m pytest -q -n0 --no-cov --confcutdir=python/tests/cli python/tests/cli/test_iterate_with_timeout.py — 7 passed.

The broader CLI test run encountered fixture setup errors, so the full CLI suite has not been verified successfully.

Closes #509

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T19:13:43.127959Z	dcef2ea	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dcef2ea40e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Always close the iterator after pending-read errors

When the consumer stops after a timeout and the outstanding __anext__ completes with an ordinary exception before aclose() runs, await pending re-raises that exception because the handler only catches cancellation/end-of-iteration, so execution skips the final iterator.aclose() entirely. This regresses the helper's guaranteed-cleanup contract for iterators whose failed read does not close themselves; place aclose() in a nested finally while still allowing the read exception to propagate.

Useful? React with 👍 / 👎.

[ShivaniSharma14]

Thanks for pointing this out! I've updated the cleanup logic to ensure iterator.aclose() runs in a nested finally block even if awaiting the pending read raises an exception. I've also added a regression test for this case, and all focused tests pass.