fix(socket): auto-bind an unbound TCP socket on listen() (X3)

listen() on a socket with no prior bind() built a TcpSession on
the invalid local port 0 — a broken listener. The backlog planned
to reject this with EINVAL, but that contradicts Linux, which
auto-binds an unbound TCP socket to an ephemeral port on listen()
(inet_csk_listen_start -> get_port with port 0). Per the
Linux-parity north star, mirror the auto-bind instead of the
deviation.

TcpSocket.listen() now, when the socket is unbound (local port not
in 1..65535), picks an ephemeral port via pick_local_port() and
re-registers the socket before starting the listener — the same
unregister/pick/register dance bind() uses. A socket already bound
to a specific port keeps it.

Not a breaking change: the examples all bind() before listen(), so
none needed updating (the reason the EINVAL variant was flagged as
example-breaking).

Tests-first: listen() on an unbound socket auto-binds an ephemeral
port and registers the listener; listen() on a bound socket keeps
its port and does not re-pick. Verified red (port stayed 0) before
the fix.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ccie18643

docs/refactor/host_refinements_backlog.md

@@ -178,8 +178,8 @@ self._signal_readable()
   asserting the behavioural effect (not just the stored value). This is a
   series of small red-tests-first commits — good "one by one" cadence.
 - **Known members of this bucket:** `SO_SNDBUF` (see R3), `SO_SNDTIMEO`
-  (see R3), `X3` listen()-on-unbound → `EINVAL` (breaks examples; land as
-  an explicit breaking-change commit + update `examples/`).
+  (see R3), `X3` listen()-on-unbound (DONE — shipped as Linux-parity
+  auto-bind, not the originally-planned `EINVAL`; see the R3 section).
 - **Effort:** open-ended (do a few per session). **Risk:** low per fix.
 - **Audit (done):** swept every stored setsockopt attribute for a data-path
   read. Result: almost everything is HONORED. The only strictly-DEAD
@@ -274,8 +274,8 @@ self._signal_readable()
   is now either honoured or documented-inert; the remaining true gaps are
   scoped to their proper track: `IP_MULTICAST_IF`/`_IF6` → Phase-2 (egress
   selection), `SO_RCVBUF`-on-TCP → R3 (receive-window), `SO_SNDBUF` /
-  `SO_SNDTIMEO` → R3 (send buffer accounting), the `X3` listen()-on-unbound
-  `EINVAL` breaking-change remains an explicit opt-in item.
+  `SO_SNDTIMEO` → R3 (send buffer accounting; DONE), and `X3`
+  listen()-on-unbound (DONE — Linux-parity auto-bind, see R3).
 
 ### R3 — `SO_SNDBUF` accounting + `SO_SNDTIMEO` (UDP) — DONE
 
@@ -323,11 +323,20 @@ self._signal_readable()
   round-trip + integer-still-accepted regression). This makes the R3
   blocking-send `SO_SNDTIMEO` fully usable at sub-second granularity via
   the public API.
+- **Shipped (X3 — listen() on an unbound socket):** the backlog originally
+  planned `EINVAL` here, but that **contradicts Linux**, which auto-binds an
+  unbound TCP socket to an ephemeral port on `listen()`
+  (`inet_csk_listen_start` → `get_port`). Per the Linux-parity north star we
+  shipped the auto-bind: `TcpSocket.listen()` on a socket with no prior
+  `bind()` now picks an ephemeral port (`pick_local_port`) and registers the
+  listener, instead of building the previously-broken port-0 listener. Not a
+  breaking change (the examples already bind first), so no `examples/` update
+  was needed. Tests: `test__tcp_socket__listen_unbound_autobinds_ephemeral_port`
+  + `test__tcp_socket__listen_bound_keeps_port_and_does_not_repick`.
 - **Still scoped out (follow-ons):** TCP `SO_SNDBUF` (TCP has its own send
   buffering / retransmit queue, released on ACK, not on wire-write — a
   separate model, wrong to fold into this counter); `SO_RCVBUF`-on-TCP
-  (receive-window derivation); the `X3` `listen()`-on-unbound → `EINVAL`
-  breaking change (updates `examples/`).
+  (receive-window derivation).
 
 ### R4 — IPv6 per-socket source filters = MLDv2 SSM track — DONE (P1-P5 shipped)
 

packages/pytcp/pytcp/runtime/socket/tcp__socket.py

@@ -766,6 +766,16 @@ def listen(self, *, backlog: int = TCP__DEFAULT_BACKLOG) -> None:
 
         assert backlog > 0, f"The 'backlog' argument must be positive. Got: {backlog!r}"
 
+        # Linux 'inet_csk_listen_start' auto-binds an unbound socket to
+        # an ephemeral local port before it starts listening; PyTCP
+        # mirrors that rather than requiring an explicit prior bind()
+        # (which would otherwise leave the listener on the invalid port
+        # 0). A socket already bound to a specific port keeps it.
+        if self._local_port not in range(1, 65536):
+            stack.sockets.unregister(self)
+            self._local_port = pick_local_port()
+            stack.sockets.register(self)
+
         self._backlog = backlog
         self._tcp_session = TcpSession(
             local_ip_address=self._local_ip_address,

packages/pytcp/pytcp/tests/unit/runtime/socket/test__runtime__socket__tcp__socket.py

@@ -569,6 +569,53 @@ def test__tcp_socket__listen_registers_and_starts_session(self) -> None:
         )
         self._session_cls.return_value.listen.assert_called_once_with()
 
+    def test__tcp_socket__listen_unbound_autobinds_ephemeral_port(self) -> None:
+        """
+        Ensure listen() on a socket with no prior bind() auto-binds an
+        ephemeral local port and registers the listener — mirroring
+        Linux rather than listening on the invalid port 0.
+
+        Reference: Linux net/ipv4/inet_connection_sock.c
+        inet_csk_listen_start (auto-bind an unbound listener).
+        """
+
+        s = TcpSocket(family=AddressFamily.INET4)
+        self.assertEqual(s.local_port, 0, msg="A fresh TCP socket is unbound (port 0).")
+
+        with patch("pytcp.runtime.socket.tcp__socket.pick_local_port", return_value=45000):
+            s.listen()
+
+        self.assertEqual(
+            s.local_port,
+            45000,
+            msg="listen() on an unbound socket must auto-bind an ephemeral port.",
+        )
+        self.assertIn(
+            s.socket_id,
+            self._sockets,
+            msg="An auto-bound listener must be registered under its ephemeral port.",
+        )
+        self._session_cls.return_value.listen.assert_called_once_with()
+
+    def test__tcp_socket__listen_bound_keeps_port_and_does_not_repick(self) -> None:
+        """
+        Ensure listen() on an already-bound socket keeps its bound port
+        and does not re-pick an ephemeral one — the auto-bind path
+        applies only to an unbound socket.
+
+        Reference: Linux net/ipv4/inet_connection_sock.c
+        inet_csk_listen_start (a bound listener keeps its port).
+        """
+
+        s = TcpSocket(family=AddressFamily.INET4)
+        s.bind(("0.0.0.0", 8080))
+
+        with patch("pytcp.runtime.socket.tcp__socket.pick_local_port", return_value=99999) as pick:
+            s.listen()
+
+        self.assertEqual(s.local_port, 8080, msg="listen() must keep the bound port.")
+        pick.assert_not_called()
+
     def test__tcp_socket__accept_returns_socket_and_address(self) -> None:
         """
         Ensure accept() returns a '(socket, (remote_ip_str, port))'