[maxdubrinsky]

Summary

Add sandbox watches that retain event variants, warnings, and resume cursors, plus bounded completion waits that distinguish terminal outcomes and detect same-name replacement. Early stream closure cancels the RPC; reconnect and cursor reset remain explicit.

Stack 3/4; depends on #5169.

Related Issue

Closes #5166

Changes

• Expose complete watch messages and explicit resume cursors without hidden reconnects.
• Cancel sync and async watches on iterator closure.
• Add identity-aware wait_completed with bounded polling and terminal-state handling.

Release Notes

Testing

• Clean-checkout Python suite: 282 passed.
• Ruff lint/format and ty checks, including consumer signatures and generated async methods.
• Loopback gRPC transport tests for the affected sync/async behavior.
• SDK wheel built, verified, and imported from a clean checkout at stack head.
• Fern check: zero errors; documentation navigation passes.
• Live gateway integration (not run; this change does not modify sandbox infrastructure).

Checklist

• Follows Conventional Commits.
• Commits are signed off (DCO).
• Python implementation and public SDK documentation updated.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-5170.docs.buildwithfern.com/openshell