Never close a buffer the transport does not own

The transport's text layers now detach instead of closing on garbage
collection. In the in-place paths the wrapped buffer is the sys
stream's own, and closing it destroyed sys.stdout for the rest of the
process (the issue #1933 class, which the claimed path had already
fixed incidentally via the private descriptor).

Also strengthens the fd 0 watchdog migration note (the null device
reports permanently readable, so any-event watchers misfire at startup
rather than merely never firing) and restores the note about child
output volume flowing into the client's stderr channel.

Author: maxisbey

docs/migration.md

@@ -1864,12 +1864,21 @@ handler code can no longer read protocol bytes or write into the stream (the
 servers have nothing to do, and code that inspects or manipulates fd 0/1 directly
 during a session now sees the diversions, not the wire.
 
-One pattern needs migrating: a watchdog thread that `poll()`s fd 0 for `POLLHUP` to
-detect a vanished client will no longer fire, because the null device never reports
-it (a POSIX-specific pattern; `select.poll` does not exist on Windows). Watch the
-parent process instead: on POSIX, exit when `os.getppid()` changes, which happens
-when the client dies because orphaned processes are reparented. That works on both
-v1 and v2 and does not depend on descriptor layout.
+One pattern needs migrating: watchdog threads that watch fd 0 to detect a vanished
+client (a POSIX-specific pattern; `select.poll` does not exist on Windows). The null
+device does not behave like the old pipe: it never reports `POLLHUP`, and it reports
+readable immediately and permanently (`POLLIN|POLLERR` from `poll()` on Linux, ready
+from `select()`, and macOS can report `POLLNVAL` for devices). A watcher waiting for
+`POLLHUP` is silently disarmed; a watcher that treats any event as "client gone" now
+fires at startup instead of never. Watch the parent process instead: on POSIX, exit
+when `os.getppid()` changes, which happens when the client dies because orphaned
+processes are reparented. That works on both v1 and v2 and does not depend on
+descriptor layout.
+
+Also worth knowing: a child process that streams large output to its inherited
+stdout now streams it into the client's stderr channel. Capture output you do not
+want in the client's logs, and be aware that a client which never drains its stderr
+pipe applies back-pressure to the server (true of stderr logging on v1 as well).
 
 ### WebSocket transport removed
 

src/mcp/server/stdio.py

@@ -49,6 +49,19 @@ class _StreamClaim:
     private_fd: int | None = None
 
 
+class _UnownedTextWrapper(TextIOWrapper):
+    """Text layer whose close never closes the underlying buffer.
+
+    The buffer is not the transport's to close: in the in-place paths it is the
+    sys stream's own buffer, and closing it at garbage collection destroyed
+    sys.stdout for the rest of the process (issue #1933).
+    """
+
+    def close(self) -> None:
+        with suppress(ValueError):
+            self.detach()
+
+
 def _is_backed_by_fd(stream: TextIO, fd: int) -> bool:
     try:
         return stream.buffer.fileno() == fd
@@ -158,10 +171,10 @@ async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.
     try:
         if not stdin:
             stdin_buffer, restore_stdin = _claim_fd(0, sys.stdin, "rb", _open_stdin_diversion)
-            stdin = anyio.wrap_file(TextIOWrapper(stdin_buffer, encoding="utf-8", errors="replace"))
+            stdin = anyio.wrap_file(_UnownedTextWrapper(stdin_buffer, encoding="utf-8", errors="replace"))
         if not stdout:
             stdout_buffer, restore_stdout = _claim_fd(1, sys.stdout, "wb", _open_stdout_diversion)
-            stdout = anyio.wrap_file(TextIOWrapper(stdout_buffer, encoding="utf-8"))
+            stdout = anyio.wrap_file(_UnownedTextWrapper(stdout_buffer, encoding="utf-8"))
 
         read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0)
         write_stream, write_stream_reader = create_context_streams[SessionMessage](0)

tests/server/test_stdio.py

@@ -1,3 +1,4 @@
+import gc
 import io
 import os
 import sys
@@ -502,6 +503,34 @@ def failing_diversion() -> int:
                     await write_stream.aclose()
 
 
+@pytest.mark.anyio
+async def test_a_degraded_session_does_not_close_the_sys_stream_it_served(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The transport's text layer never closes a buffer it does not own.
+
+    Regression for the issue #1933 class: in the in-place paths the transport wraps
+    the sys stream's own buffer, and wrapper garbage collection must not close it.
+    """
+    with _pipe_planted_on_fd0(monkeypatch) as (_, in_w):
+        os.close(in_w)
+        monkeypatch.setattr(sys, "stdout", TextIOWrapper(io.BytesIO(), encoding="utf-8"))
+
+        def failing_dup_above_std(fd: int) -> int:
+            raise OSError("forced degrade")
+
+        monkeypatch.setattr("mcp.server.stdio._dup_above_std", failing_dup_above_std)
+
+        with anyio.fail_after(5):
+            async with stdio_server() as (read_stream, write_stream):
+                read_stream.close()
+                await write_stream.aclose()
+
+        gc.collect()
+        assert not sys.stdin.buffer.closed
+        assert not sys.stdout.buffer.closed
+
+
 class _GatedStdin(io.RawIOBase):
     """Raw stdin double: serves its frames, then blocks until released before EOF.