fix(transcript_mirror): handle CancelledError in eager-flush done callback (#931)

## Summary

Fixes #930.

The `add_done_callback` lambda on the eager-flush `_flush_task` called
`t.exception()` unconditionally. In Python 3.8+, `Task.exception()`
raises `CancelledError` for cancelled tasks, and the raise from inside a
done-callback surfaces as a noisy `Exception in callback` log every time
the SDK shuts down with pending eager flushes — visible in #928's
failing-test `Captured log teardown` block.

## Changes

- `src/claude_agent_sdk/_internal/transcript_mirror_batcher.py`: replace
`lambda t: t.exception()` with a module-level `_swallow_done_exception`
helper that no-ops on cancelled tasks and otherwise retrieves the
exception so asyncio doesn't warn.
- `tests/test_transcript_mirror.py`: add `TestSwallowDoneException` with
three cases — cancelled task (must not raise), failed task (retrieves
exception, doesn't re-raise), successful task (no-op).

## Test plan

- [x] `uv run pytest
tests/test_transcript_mirror.py::TestSwallowDoneException` — 3 passed
- [x] `uv run mypy src/` — clean
- [x] `ruff check / ruff format` — clean
- [x] Pre-existing #928 failures still present (unaffected by this
change — different bug)

## Notes

The fix is intentionally narrow — same call site, same intent (silence
"Task exception was never retrieved" warnings), just cancellation-safe.
No behavior change on the happy path.

Co-authored-by: Xian Zheng <xian.zheng@challenger.gauntletai.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: 3 people

src/claude_agent_sdk/_internal/transcript_mirror_batcher.py

@@ -33,6 +33,17 @@
 MIRROR_APPEND_BACKOFF_S = (0.2, 0.8)
 
 
+def _swallow_done_exception(t: asyncio.Task[None]) -> None:
+    # Retrieve the task's exception (if any) so asyncio doesn't warn about an
+    # unretrieved exception on a fire-and-forget task. Skip cancelled tasks:
+    # Task.exception() raises CancelledError on those (Python 3.8+), and the
+    # raise from inside a done-callback surfaces as a noisy "Exception in
+    # callback" log on every cancellation.
+    if t.cancelled():
+        return
+    t.exception()
+
+
 @dataclass
 class _MirrorEntry:
     file_path: str
@@ -88,7 +99,7 @@ def enqueue(self, file_path: str, entries: list[SessionStoreEntry]) -> None:
             # so append ordering holds. drain() never raises, but guard anyway
             # so a future regression can't surface as an unhandled exception.
             self._flush_task = asyncio.ensure_future(self._drain())
-            self._flush_task.add_done_callback(lambda t: t.exception())
+            self._flush_task.add_done_callback(_swallow_done_exception)
 
     async def flush(self) -> None:
         """Flush all pending entries. Awaits any in-flight eager flush first."""

tests/test_transcript_mirror.py

@@ -33,6 +33,7 @@
     MAX_PENDING_BYTES,
     MAX_PENDING_ENTRIES,
     TranscriptMirrorBatcher,
+    _swallow_done_exception,
 )
 from claude_agent_sdk._internal.transport.subprocess_cli import SubprocessCLITransport
 
@@ -523,6 +524,52 @@ async def append(self, key, entries):
         assert order == [1, 2, 3]
 
 
+# ---------------------------------------------------------------------------
+# _swallow_done_exception
+# ---------------------------------------------------------------------------
+
+
+class TestSwallowDoneException:
+    """Regression for issue #930: the eager-flush task's done-callback used
+    ``lambda t: t.exception()``, which raises ``CancelledError`` for cancelled
+    tasks (Python 3.8+) and surfaces as a noisy "Exception in callback" log
+    every time the SDK shuts down with pending eager flushes.
+    """
+
+    @pytest.mark.asyncio
+    async def test_returns_none_for_cancelled_task(self) -> None:
+        async def _hang() -> None:
+            await asyncio.sleep(3600)
+
+        task = asyncio.ensure_future(_hang())
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert task.cancelled()
+        # Must NOT raise — this is the whole point of the fix.
+        assert _swallow_done_exception(task) is None
+
+    @pytest.mark.asyncio
+    async def test_retrieves_exception_for_failed_task(self) -> None:
+        async def _boom() -> None:
+            raise RuntimeError("kaboom")
+
+        task = asyncio.ensure_future(_boom())
+        with pytest.raises(RuntimeError, match="kaboom"):
+            await task
+        # Retrieves the exception so asyncio doesn't warn — does not re-raise.
+        assert _swallow_done_exception(task) is None
+
+    @pytest.mark.asyncio
+    async def test_returns_none_for_successful_task(self) -> None:
+        async def _ok() -> None:
+            return None
+
+        task = asyncio.ensure_future(_ok())
+        await task
+        assert _swallow_done_exception(task) is None
+
+
 # ---------------------------------------------------------------------------
 # build_mirror_batcher / session_store_flush
 # ---------------------------------------------------------------------------