docs: record the surface review in the changelog and handoffs

Adds the changelog entries for the four namespaces, the shared Host, the
loop guards, profile=/main_thread_only and the aio cancellation fix, and
corrects the two earlier entries that still advertised execnet.portal.

The phase C handoff gains a "Surface review" section that wins over
everything below it, and the boundary-protocol handoff is marked
superseded where it promised a Wakener extension point.  Also drops the
EXECMODEL_PROFILES entry from the gateway_base shim: that name was added
on this branch, so it never existed pre-Trio and nothing can be
forwarding to it.

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

Author: RonnyPfannschmidt

CHANGELOG.rst

@@ -1,6 +1,61 @@
 2.2.0 (UNRELEASED)
 ------------------
 
+* One namespace per concurrency library you drive execnet from:
+  ``execnet.sync`` (plain threads; the top-level ``execnet.*`` aliases),
+  ``execnet.trio``, ``execnet.aio`` and the new ``execnet.gevent``, whose blocking
+  waits park the calling greenlet instead of its OS thread (needs ``execnet[gevent]``).
+
+  ``execnet.trio`` is the only surface that runs gateways *directly*, as tasks in your
+  own nursery. The others drive a Trio host thread, so their blocking calls now raise
+  when made from inside a running asyncio or trio loop -- naming the namespace to use
+  instead -- rather than stalling that loop. Channels inside a worker are exempt:
+  exec'd code may run its own event loop and talk to its channel from within it.
+* The ``execnet.portal`` namespace is gone. It exposed the ``Wakener`` protocol and the
+  ``Mailbox``/``OneShot``/``LoopPortal`` primitives but not the registry needed to plug
+  a ``Wakener`` in, and execnet does not offer third-party event-loop integration: a new
+  concurrency library gets a namespace of its own, as gevent just did. The primitives
+  are internal again.
+* Gateway groups share one Trio host thread per process instead of starting one each.
+  Pass ``execnet.Host()`` as ``Group(host=...)`` (or ``AsyncGroup(host=...)``) for an
+  isolated loop with deterministic teardown -- ``Host`` is a context manager and joins
+  its thread on exit, where the shared one stops at interpreter exit.
+* The ``execmodel=`` spec key is now ``profile=``; ``execmodel=`` remains an accepted
+  alias. It always selected the *worker* profile -- where exec'd code runs relative to
+  the worker's protocol loop -- while the local execution model it was named after no
+  longer exists. Accordingly ``Group(execmodel=...)``, ``Group.set_execmodel()``,
+  ``Group.execmodel`` and ``Group.remote_execmodel`` are deprecated in favour of
+  ``Group(profile=...)``, ``Group.set_profile()`` and ``Group.profile``; only the
+  remote default they set has any effect. ``remote_status()`` reports both
+  ``profile`` and ``execmodel``.
+* The ``main_thread_only`` profile is deprecated and now behaves like ``thread``, which
+  already hands the first ``remote_exec`` the worker's real main thread -- the
+  GUI/signal-safety property it was added for in 2.1.0. Its other behaviour is gone:
+  a second concurrent ``remote_exec`` used to close the channel with
+  ``concurrent remote_exec would cause deadlock``, and now runs on a pool thread. That
+  guard was a one-second timeout that reported a merely slow predecessor as a deadlock.
+* The ``wait=`` spec key added earlier in this release cycle is gone. Which primitive a
+  blocking wait parks on describes the *caller*, which is what choosing a namespace
+  already says; a worker's own backend is derived from its profile.
+* ``execnet.aio`` now propagates cancellation. Cancelling an awaited ``receive`` (with
+  ``asyncio.timeout``, say) cancels the host-side operation, where it previously
+  abandoned only the asyncio side and let the operation consume an item that was then
+  discarded. ``send``, ``send_eof``, ``aclose`` and ``terminate`` are shielded instead,
+  so they cannot tear halfway.
+
+  Its classes gained the ``Async`` prefix -- ``AsyncGroup``, ``AsyncGateway``,
+  ``AsyncChannel`` -- matching ``execnet.trio``, and ``AsyncGroup`` can be driven with
+  ``start()``/``aclose()`` from application lifespan hooks instead of ``async with``.
+  ``open_popen_gateway`` is renamed ``open_gateway`` on both async namespaces, since it
+  always accepted any spec.
+* ``execnet.dumps``, the temporary pytest-xdist compatibility shim, now warns once per
+  process rather than on every access. xdist reaches it from ``serialize_warning_message``,
+  i.e. from inside pytest's warning-recording hook, so a single ``DeprecationWarning``
+  raised in a worker made recording that warning record another, unbounded, wedging the
+  run.
+* ``Gateway.remote_init_threads()`` raises a ``DeprecationWarning`` instead of printing
+  to stdout. It has been a no-operation since execnet 1.2.
+
 * `#380 <https://github.com/pytest-dev/execnet/pull/380>`__: Add support for Python 3.13 and 3.14, and drop EOL 3.8 and 3.9.
 * Trio host-thread Message IO for local ``popen`` + import bootstrap (coordinator and
   worker). Adds a hard ``trio`` dependency. Disable with ``EXECNET_TRIO_HOST=0``.
@@ -31,7 +86,8 @@
   load. Opcode bytes are unchanged for every type that survives.
 * The supported API is now exactly five namespaces: ``execnet`` (aliases of
   ``execnet.sync``), ``execnet.sync``, ``execnet.trio``, ``execnet.aio`` and
-  ``execnet.portal``. The pre-Trio modules ``execnet.gateway_base``, ``execnet.gateway``,
+  ``execnet.gevent`` -- one per concurrency library you drive execnet from. The
+  pre-Trio modules ``execnet.gateway_base``, ``execnet.gateway``,
   ``execnet.multi``, ``execnet.rsync``, ``execnet.rsync_remote`` and ``execnet.xspec``
   were only ever reachable because ``import execnet`` pulled them in transitively; they
   are now deprecated forwarding shims that warn on attribute access and will be removed
@@ -55,8 +111,7 @@
   ``can_send``.
 * ``execnet.trio`` no longer exports ``ByteStream``, ``RawChannel``,
   ``RawChannelStream`` or ``serve_gateway``; the raw-channel layer is internal routing
-  detail. No names were added to ``execnet.sync``, ``execnet.aio`` or
-  ``execnet.portal``.
+  detail. No names were added to ``execnet.sync`` or ``execnet.aio``.
 
 
 2.1.2 (2025-11-11)

handoff-boundary-protocol-rethink.md

@@ -128,9 +128,23 @@ port.  Phase E (anyio-native core) becomes optional purity/perf work.
    in the first waiter's hub (carriers may be constructed on the host
    loop); tests behind the `gevent` dependency group.
 
-Next: Phase C `loop=main` / `exec=task` on the smaller core
-(handoff-phase-c-worker-axes.md), and Phase D docs cover the four
-namespaces + the axes/presets.
+## SUPERSEDED 2026-07-29 by the surface review
+
+Phase C landed, and reviewing the whole public surface at once (before
+Phase D docs froze it) retired several of the decisions above.  See
+"Surface review" in `handoff-phase-c-worker-axes.md` for what stands.  In
+short:
+
+- **The Wakener extension point is gone.**  There was never a plan to let
+  third parties add event loops, and the asyncio wakener sketched here was
+  deliberately never built (P4 chose per-call bridging).  What is left is
+  two wait backends, threads and gevent, behind a two-branch
+  `make_wakener`.  `execnet.portal` is now private `execnet._portal`.
+- **`wait=` is gone as a spec key.**  It described the *caller's*
+  concurrency library, which is what picking a namespace already says.
+  gevent got the facade it was missing: `execnet.gevent`.
+- **The `loop=` / `exec=` axes stayed dropped**; `execmodel=` became
+  `profile=` (see below).
 
 ## Invariants (unchanged, re-mapped)
 

handoff-phase-c-worker-axes.md

@@ -17,6 +17,63 @@ pytest testing/ -n 12` passes (~7s) since the session-attach race fix
 `testing/test_ssh_local.py` (asyncssh server; system ssh client needed).
 Known flake: `test_socket_installvia` EOFs rarely under load.
 
+## Surface review — LANDED 2026-07-29 (`7aa17fe..e75cd0a`)
+
+The public surface had settled commit by commit and was never reviewed as
+a whole.  Doing that before the Phase D docs froze it produced the
+following, which **wins over anything below or in
+`handoff-boundary-protocol-rethink.md` that contradicts it**.
+
+**Namespaces are now one per concurrency library you drive execnet from**:
+`execnet.sync` (threads; the top-level aliases), `execnet.trio`,
+`execnet.aio`, `execnet.gevent`.  `execnet.portal` is gone --
+`execnet._portal` plus the trio-free `execnet._boundary`.
+
+| was | is | why |
+|---|---|---|
+| `execnet.portal` public | `execnet._portal` private | it exported `Wakener`/`Mailbox`/`OneShot`/`LoopPortal` but *not* `register_wakener`, so the advertised extension point was unreachable -- and there is no plan to let third parties add event loops at all |
+| Wakener registry (`register_wakener`, lazy module table) | two-branch `make_wakener(Literal["thread","gevent"])` | exactly two backends exist; every other library gets a facade |
+| `wait=` spec key | gone; `Group._wait_backend`, set by the facade | it described the *caller*, which the namespace already says.  Worker-side wait was always derived from the profile |
+| gevent via `wait=gevent` | `execnet.gevent.Group` | symmetric with the other surfaces |
+| `execmodel=` spec key | `profile=` (`execmodel=` a permanent alias) | the key selects the *worker profile*; the local execution model it was named after no longer exists |
+| `Group(execmodel=)`, `set_execmodel`, `group.execmodel` | deprecated; only the remote default survives | they had no behavioural effect.  **xdist passes `Group(execmodel=...)` as a keyword** -- that must keep working |
+| `main_thread_only` profile | deprecated alias for `thread` | `HybridExec` already gives the first remote_exec the real main thread.  Its extra behaviour (refusing a second concurrent remote_exec) was a 1s-timeout deadlock guard, now deleted |
+| one `TrioHost` per `Group` | one shared `execnet.Host` per process, `Group(host=...)` to override | a host is a thread and a loop, not something groups need isolated |
+| blocking inside a running loop hangs | raises, naming `execnet.aio` / `execnet.trio` | worker-side channels stay exempt: exec'd code may run its own loop |
+| `aio.Group`/`Gateway`/`Channel` | `aio.AsyncGroup`/`AsyncGateway`/`AsyncChannel` | matches `execnet.trio`; swapping the import ports the code |
+| `open_popen_gateway` | `open_gateway` (both async surfaces) | it always accepted any spec |
+
+Behaviour changes worth a changelog line:
+
+- a second concurrent `remote_exec` under `main_thread_only` used to close
+  the channel with `MAIN_THREAD_ONLY_DEADLOCK_TEXT`; it now runs on a pool
+  thread.  `_executetask_complete`, `MAIN_THREAD_ONLY_ADMIT_TIMEOUT` and
+  the error text are deleted; `MainExec` became `PrimaryThreadPump`.
+- `execnet.aio` cancellation is now real: a cancelled `receive` cancels
+  the host-side operation instead of consuming and discarding an item.
+  `send`/`send_eof`/`aclose`/`terminate` are shielded instead.
+- the boundary carriers raise `execnet.TimeoutError`, not the builtin;
+  `OneShot` double-resolve is a `RuntimeError`, not an `assert`.
+- `STATUS` answers both `profile` and (legacy) `execmodel`.
+- **Latent livelock fixed**: `execnet.dumps` warned on *every* access, and
+  xdist calls it from `serialize_warning_message` -- i.e. from inside
+  pytest's warning-recording hook.  One DeprecationWarning in a worker
+  therefore recorded a warning that recorded a warning, unbounded, and
+  wedged the run.  The shim warns once per process
+  (`execnet._xdist_compat_warned`).  Anything that warns in a worker can
+  hit this class of bug; keep it in mind.
+
+New tests: `testing/test_host.py` (sharing, explicit `Host`, fork, the
+loop guards), `testing/test_boundary.py` (renamed from `test_portal.py`),
+aio cancellation contracts in `testing/test_aio.py`.  The `execmodel`
+fixture parametrization collapsed to a single `profile` fixture, so the
+suite is ~540 items rather than ~765.
+
+Still open from the review, deliberately not done: the async surfaces have
+no `remote_status()`, no `MultiChannel`, no group iteration, and no
+`RSync`.  `AsyncGroup.makegateway` defaults workers to the `thread`
+profile (the coordinator's shape does not dictate the worker's).
+
 ## Where the repo stands (2026-07-25, after `a69b844`)
 
 One protocol engine: `AsyncGateway` (`_trio_gateway.py`).  The sync API
@@ -45,12 +102,12 @@ File map (src/execnet/):
 
 | file | role |
 |---|---|
-| `gateway_base.py` | `Message` wire protocol + sans-IO `FrameDecoder`, serializer (CHANNEL opcode incl. duck-typed `save_AsyncChannel`), sync `Channel`/`ChannelFactory` (raw-receiver registry), `BaseGateway`/`WorkerGateway` (`_send` via bridge, `_send_nonblocking` for GC), `ExecModel`, `WorkerPool`, `HostNotFound` |
+| `_message.py` / `_serialize.py` / `_channel.py` / `_gateway_base.py` / `_errors.py` / `_execmodel.py` | split by concern since this table was written: wire protocol + sans-IO `FrameDecoder`; serializer (CHANNEL opcode incl. duck-typed `save_AsyncChannel`); sync `Channel`/`ChannelFactory`; `BaseGateway`/`WorkerGateway`; error types; `WORKER_PROFILES` + `resolve_profile` + the deprecated `ExecModel` xdist shim.  `gateway_base.py` is now only a warning shim |
 | `_trio_gateway.py` | async core: `ByteStream` Protocol, `RawChannel`/`AsyncChannel`, `AsyncGateway` (outbound queue of `(frame, on_written)`; `_finalize` hook), `AsyncGroup` (all transports, overridable `_make_gateway`/`_open_via_stream`/`_resolve_socket_address`, reapers, bounded terminate), stream/argv helpers |
 | `_trio_host.py` | `TrioHost` (loop thread), `SyncBridgeGateway`, `FacadeAsyncGroup`, `makegateway_trio`, `SyncIOHandle`, `RawTunnelStream` (via tunnel; `aclose` feeds own reader EOF), `GATEWAY_START_*` handlers |
 | `_trio_worker.py` | worker entry (`_main`/`serve_popen_trio`/`serve_socket_trio`), `TrioWorkerExec` (FIFO `_pump` admission; `integrate_as_primary_thread`), `_prepare_protocol_fds`, `_check_version` |
 | `gateway.py` / `multi.py` | sync `Gateway` / sync `Group` facade, `MultiChannel`, `safe_terminate` (WorkerPool-based, kept for tests) |
-| `sync.py` / `trio.py` / `portal.py` | the three public namespaces |
+| `sync.py` / `trio.py` / `aio.py` / `gevent.py` | the four public namespaces; `_host.py` holds the shared `Host`, `_portal.py`/`_boundary.py` the (private) boundary kit |
 | `_exec_source.py`, `_provision.py`, `xspec.py`, `rsync.py` | source normalization, uv provisioning + argv builders, spec parsing, rsync |
 
 ## Semantics that MUST survive (xdist depends on them)
@@ -84,20 +141,23 @@ different use-cases get named profiles, `execmodel=` is the public mode
 key (xdist already passes it), and `wait=` is the only other public
 knob.  Implemented in commits `b2f43c3..cbce183`:
 
-| `execmodel=` | loop thread | exec'd code runs | channel | worker wait | extra deps |
+| `profile=` (was `execmodel=`) | loop thread | exec'd code runs | channel | worker wait | extra deps |
 |---|---|---|---|---|---|
 | `thread` (default) | side thread | **classic hybrid restored**: primary on the main thread, overflow on pool threads (claim decided during FIFO admission) | sync | thread | — |
-| `main_thread_only` | side thread | main thread, serialized (deadlock guard) | sync | thread | — |
+| ~~`main_thread_only`~~ | *deprecated 2026-07-29, aliases to `thread`* | | | | |
 | `trio` (new) | **main thread** | async sources as tasks — one single thread total; top-level await or async def; sync sources rejected; termination cancels tasks | AsyncChannel | (loop) | — |
 | `gevent` (revived) | side thread | greenlets on a main-thread hub, one per remote_exec | sync | gevent (derived) | `execnet[gevent]`, auto-added by uv provisioning |
 
+(The coordinator-side counterpart of the last row is now `execnet.gevent`,
+not `wait=gevent`.)
+
 Architecture: `TrioWorkerExec` is a pure FIFO admission pump delegating
 to strategy objects (`WORKER_EXEC_STRATEGIES` in `_trio_worker.py`:
 PoolExec building block, MainExec, HybridExec, GreenletExec; TaskExec
 serves a plain AsyncGateway via its pluggable `_exec_handler` — no sync
 bridge at all in the trio profile).  Subinterpreters: future strategy
-slot, not built.  `EXECMODEL_PROFILES` (gateway_base) validates
-coordinator-side in makegateway.
+slot, not built.  `WORKER_PROFILES` (`_execmodel.py`) validates
+coordinator-side in makegateway, via `resolve_profile`.
 
 **Native info/setup** (the pytest fix): `Message.GATEWAY_INFO` (code 10)
 answers `_rinfo()` from the dispatch loop; chdir/nice/env ship in the
@@ -108,9 +168,9 @@ post-start remote_exec setup block are gone.
 
 Coordinator-gevent integration: `TrioHost.call_pending` (OneShot from a
 host task) backs makegateway / `SyncIOHandle.wait/kill` /
-`Group.terminate` whenever the wait backend is not `thread`, so a gevent
-app's management ops park only the calling greenlet.  `wait=thread`
-keeps the KI-deferred `portal.run` path.
+`Group.terminate` whenever the group's wait backend is not `thread`, so a
+gevent app's management ops park only the calling greenlet.  The default
+`thread` backend keeps the KI-deferred `portal.run` path.
 
 Still decided/standing: core stays trio-only (anyio/asyncio-core port
 rejected; asyncio apps use `execnet.aio`); eventlet stays dead; exec'd

src/execnet/_execmodel.py

@@ -110,9 +110,7 @@ def resolve_profile(name: str) -> str:
         )
         return replacement
     if name not in WORKER_PROFILES:
-        raise ValueError(
-            f"unknown profile {name!r} (known: {list(WORKER_PROFILES)})"
-        )
+        raise ValueError(f"unknown profile {name!r} (known: {list(WORKER_PROFILES)})")
     return name
 
 

src/execnet/_host.py

@@ -27,8 +27,12 @@
 import sys
 import threading
 from types import TracebackType
+from typing import TYPE_CHECKING
 from typing import Any
 
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
 __all__ = ["Host", "check_not_in_event_loop", "default_host"]
 
 #: default cap on concurrent threadpool threads running receiver callbacks
@@ -142,7 +146,7 @@ def close(self, timeout: float | None = 5.0) -> None:
         if trio_host is not None:
             trio_host.stop(timeout=timeout)
 
-    def __enter__(self) -> Host:
+    def __enter__(self) -> Self:
         return self
 
     def __exit__(

src/execnet/_multi.py

@@ -167,9 +167,7 @@ def set_execmodel(
             DeprecationWarning,
             stacklevel=2,
         )
-        self.set_profile(
-            execmodel if remote_execmodel is None else remote_execmodel
-        )
+        self.set_profile(execmodel if remote_execmodel is None else remote_execmodel)
 
     def __repr__(self) -> str:
         idgateways = [gw.id for gw in self]
@@ -273,9 +271,7 @@ def _cleanup_atexit(self) -> None:
         self.terminate(timeout=1.0)
         if self._async_group is not None:
             with suppress(Exception):
-                self._host._ensure_started().call_sync(
-                    self._async_group.shutdown.set
-                )
+                self._host._ensure_started().call_sync(self._async_group.shutdown.set)
             self._async_group = None
 
     def terminate(self, timeout: float | None = None) -> None:

src/execnet/_trio_gateway.py

@@ -42,8 +42,8 @@
 from ._errors import HostNotFound
 from ._errors import RemoteError
 from ._errors import TimeoutError
-from ._execmodel import resolve_profile
 from ._exec_source import normalize_exec_source
+from ._execmodel import resolve_profile
 from ._message import FrameDecoder
 from ._message import Message
 from ._message import gateway_info

src/execnet/_trio_host.py

@@ -32,9 +32,12 @@
 from ._errors import RemoteError
 from ._execmodel import ExecModel
 from ._execmodel import get_execmodel
+from ._host import DEFAULT_CALLBACK_THREADS
 from ._message import FrameDecoder
 from ._message import Message
 from ._message import gateway_info
+from ._portal import LoopPortal
+from ._portal import OneShot
 from ._serialize import dumps_internal
 from ._serialize import loads_internal
 from ._trace import trace
@@ -46,9 +49,6 @@
 from ._trio_gateway import open_popen_process
 from ._trio_gateway import read_handshake_ack
 from ._trio_gateway import ssh_transport_args
-from ._host import DEFAULT_CALLBACK_THREADS
-from ._portal import LoopPortal
-from ._portal import OneShot
 
 #: bound on how long the endmarker callback may run during host shutdown
 CONSUMER_ENDMARKER_GRACE = 10.0