A Windows dup2 (UCRT before Windows 11) closes its target before
duplicating, so an OSError from the divert can leave the standard
descriptor closed rather than still carrying the wire. Run the same
dup2(private_fd, fd) restore the exit path uses before serving in
place: an idempotent no-op when fd is already on the wire, and a
re-materialization from the private duplicate when the target was
closed. Adds a regression variant that closes the target as UCRT does.
Also scopes the real-host logging note to the default stderr handler.
The wire duplicate is allocated above the standard range atomically only
via F_DUPFD; Windows has no atomic minfd dup, so with fd 2 closed the
duplicate can land in the hole and the transport degrades to serving in
place. That degradation is safe, but it leaves fd 0 on the planted pipe,
and the test's blocking read of it then never returns on Windows.
No-Verification-Needed: test-only platform scoping
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.
The claim registry maps each standard descriptor to at most one owning
transport; the wire duplicate is allocated where it cannot land in the
standard range (F_DUPFD_CLOEXEC above fd 2 on POSIX) and recorded on
the claim before the descriptor is moved; release restores with a
single dup2 and deregisters only on success. Every failure, modeled or
not, lands on the safe side: the claim is retained and later
transports are refused rather than handed a diverted descriptor.
Deleted by the same design: the roll-forward path (its premise, a
reliably reportable dup2 outcome, does not exist on Windows), and the
restore-time flush (user flush() side effects can destroy the wire;
unflushed stray output now drains after the session instead). The
design was validated through three adversarial verification passes;
the write-up with invariants and accepted residues is on the PR.
If a mid-claim OSError is followed by a rollback failure, fd is stuck
on the diversion but the private duplicate still holds the wire, so
the transport now keeps the claim and serves from the duplicate like a
completed claim; the restore at exit gets another chance. Previously
the claim was released while fd stayed diverted, letting a later
stdio_server() claim the diversion as its wire.
A failed exit-time restore is still swallowed so it never masks what
ended the transport, but the fd now stays in the claimed set: a later
stdio_server() in that process is refused instead of claiming the
diversion and serving the null device as its wire.
A transport that falls back to serving the real stdin or stdout in
place (incomplete descriptor table, or a claim that failed with
OSError) now keeps its fd in the claimed set for its lifetime, so a
second concurrent stdio_server() is refused in every shape rather than
only after a successful diversion. The sentinel now means a transport
owns the stream, not that the fd is currently diverted.
The stdin/stdout claim now engages only in a normal process: the sys
stream backed by its real descriptor and fds 0-2 all open, which makes
it impossible for the private wire duplicates to land in the standard
range. Anything else - replaced streams, an incomplete descriptor
table, a failed dup - is served in place exactly as v1 was, and a
second concurrent stdio_server() raises RuntimeError instead of
contending for the streams.
This replaces the previous hardening (the dup-above-standard-range
loop, stderr-merge detection, and nested transports serving into the
diversion) with guards, and removes the migration entry: no working
code changes behavior, so there is nothing to migrate. Comments and
docstrings trimmed throughout the diff.
While serving on the process's real stdout, stdio_server now moves the
protocol pipe to a private descriptor and points fd 1 - and, on
Windows, the standard output handle - at stderr, restoring it when the
transport exits. A stray print() in handler code or a child process
writing to its inherited stdout lands in the client's log instead of
corrupting the JSON-RPC stream. The null device stands in when stderr
is unusable or, on POSIX, is detected as merged into stdout (2>&1).
The stdin claim generalizes into the shared _claim_fd mechanism: one
lock-guarded sentinel table covers both descriptors, private wire
duplicates are forced above the standard descriptor range so a process
started with a standard descriptor closed cannot hand the wire out as
its "stderr", and a failed claim degrades to serving the sys stream's
buffer in place exactly as v1 did.
Docs now describe the guarded behavior with its remaining gaps (output
flushed before serving begins, injected streams, merged stderr on
Windows), and the transport:stdio:stream-purity divergence narrows
accordingly.
While serving on the process's real stdin, stdio_server() now reads the
protocol from a private duplicate of fd 0 and points fd 0 (and, on
Windows, the standard input handle) at the null device, restoring both
on exit. Children spawned by handler code then inherit the null device
instead of the protocol pipe.
A child that inherited the pipe could consume protocol bytes on any
platform, and on Windows a Python child hangs inside interpreter
startup behind the transport's pending read (CPython gh-78961) until
the next request arrives, so any tool that ran a subprocess without
stdin=DEVNULL appeared to hang until timeout.
Isolation engages only when sys.stdin is backed by the real fd 0, at
most once per process, and degrades to reading stdin in place when the
descriptor table cannot be rearranged.
Fixes#671.
* refactor: improve typing with memory stream type aliases
Move memory stream type definitions to models.py and use them throughout
the codebase for better type safety and maintainability.
GitHub-Issue:#201
* refactor: move streams to ParsedMessage
* refactor: update test files to use ParsedMessage
Updates test files to work with the ParsedMessage stream type aliases
and fixes a line length issue in test_201_client_hangs_on_logging.py.
Github-Issue:#201
* refactor: rename ParsedMessage to MessageFrame for clarity
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: move MessageFrame class to types.py for better code organization
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix pyright
* refactor: update websocket client to use MessageFrame
Modified the websocket client to work with the new MessageFrame type,
preserving raw message text and properly extracting the root JSON-RPC
message when sending.
Github-Issue:#204
* fix: use NoneType instead of None for type parameters in MessageFrame
🤖 Generated with [Claude Code](https://claude.ai/code)
* refactor: rename root to message
Max Isbey