Wire subint_forkserver as first-class backend

Promote `_subint_forkserver` from primitives-only into a
registered spawn backend: `'subint_forkserver'` is now a
`SpawnMethodKey` literal, dispatched via `_methods` to
the new `subint_forkserver_proc()` target, feature-gated
under the existing `subint`-family py3.14+ case, and
selectable via `--spawn-backend=subint_forkserver`.

Deats,
- new `subint_forkserver_proc()` spawn target in
  `_subint_forkserver`:
  - mirrors `trio_proc()`'s supervision model — real OS
    subprocess so `Portal.cancel_actor()` + `soft_kill()`
    on graceful teardown, `os.kill(SIGKILL)` on hard-reap
    (no `_interpreters.destroy()` race to fuss over bc the
    child lives in its own process)
  - only real diff from `trio_proc` is the spawn mechanism:
    fork from a main-interp worker thread via
    `fork_from_worker_thread()` (off-loaded to trio's
    thread pool) instead of `trio.lowlevel.open_process()`
  - child-side `_child_target` closure runs
    `tractor._child._actor_child_main()` with
    `spawn_method='trio'` — the child is a regular trio
    actor, "subint_forkserver" names how the parent
    spawned, not what the child runs
- new `_ForkedProc` class — thin `trio.Process`-compatible
  shim around a raw OS pid: `.poll()` via
  `waitpid(WNOHANG)`, async `.wait()` off-loaded to a trio
  cache thread, `.kill()` via `SIGKILL`, `.returncode`
  cached for repeat calls. `.stdin`/`.stdout`/`.stderr`
  are `None` (fork-w/o-exec inherits parent FDs; we don't
  marshal them) which matches `soft_kill()`'s `is not None`
  guards

Also, new backend-tier test
`test_subint_forkserver_spawn_basic` drives the registered
backend end-to-end via `open_root_actor` + `open_nursery` +
`run_in_actor` w/ a trivial portal-RPC round-trip. Uses a
`forkserver_spawn_method` fixture to flip
`_spawn_method`/`_ctx` for the test's duration + restore on
teardown (so other session-level tests don't observe the
global flip). Test module docstring reworked to describe
the three tiers now covered: (1) primitive-level, (2)
parent-trio-driven primitives, (3) full registered backend.

Status: still-open work (tracked on `tractor#379`) doc'd
inline in the module docstring — no cancel/hard-kill stress
coverage yet, child-side subint-hosted root runtime still
future (gated on `msgspec#563`), thread-hygiene audit
pending the same unblock.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code

Author: goodboy

tests/spawn/test_subint_forkserver.py

@@ -1,9 +1,17 @@
 '''
 Integration exercises for the `tractor.spawn._subint_forkserver`
-primitives (`fork_from_worker_thread()` + `run_subint_in_worker_thread()`)
-driven from inside a real `trio.run()` in the parent process —
-the runtime shape tractor will need when we move toward wiring
-up a `subint_forkserver` spawn backend proper.
+submodule at three tiers:
+
+1. the low-level primitives
+   (`fork_from_worker_thread()` +
+   `run_subint_in_worker_thread()`) driven from inside a real
+   `trio.run()` in the parent process,
+
+2. the full `subint_forkserver_proc` spawn backend wired
+   through tractor's normal actor-nursery + portal-RPC
+   machinery — i.e. `open_root_actor` + `open_nursery` +
+   `run_in_actor` against a subactor spawned via fork from a
+   main-interp worker thread.
 
 Background
 ----------
@@ -16,17 +24,20 @@
 host its own `trio.run()` inside a fresh subint.
 
 Those smoke-test scenarios are standalone — no trio runtime
-in the *parent*. These tests exercise the same primitives
-from inside `trio.run()` in the parent, proving out the
-piece actually needed for a working spawn backend.
+in the *parent*. Tiers (1)+(2) here cover the primitives
+driven from inside `trio.run()` in the parent, and tier (3)
+(the `*_spawn_basic` test) drives the registered
+`subint_forkserver` spawn backend end-to-end against the
+tractor runtime.
 
 Gating
 ------
 - py3.14+ (via `concurrent.interpreters` presence)
-- no backend restriction (these tests don't use
-  `--spawn-backend` — they drive the forkserver primitives
-  directly rather than going through tractor's spawn-method
-  registry).
+- no `--spawn-backend` restriction — the backend-level test
+  flips `tractor.spawn._spawn._spawn_method` programmatically
+  (via `try_set_start_method('subint_forkserver')`) and
+  restores it on teardown, so these tests are independent of
+  the session-level CLI backend choice.
 
 '''
 from __future__ import annotations
@@ -36,6 +47,7 @@
 import pytest
 import trio
 
+import tractor
 from tractor.devx import dump_on_hang
 
 
@@ -50,6 +62,8 @@
     run_subint_in_worker_thread,
     wait_child,
 )
+from tractor.spawn import _spawn as _spawn_mod  # noqa: E402
+from tractor.spawn._spawn import try_set_start_method  # noqa: E402
 
 
 # ----------------------------------------------------------------
@@ -212,3 +226,104 @@ def test_fork_and_run_trio_in_child() -> None:
             ),
         )
     assert isinstance(pid, int) and pid > 0
+
+
+# ----------------------------------------------------------------
+# tier-3 backend test: drive the registered `subint_forkserver`
+# spawn backend end-to-end through tractor's actor-nursery +
+# portal-RPC machinery.
+# ----------------------------------------------------------------
+
+
+async def _trivial_rpc() -> str:
+    '''
+    Minimal subactor-side RPC body: just return a sentinel
+    string the parent can assert on.
+
+    '''
+    return 'hello from subint-forkserver child'
+
+
+async def _happy_path_forkserver(
+    reg_addr: tuple[str, int | str],
+    deadline: float,
+) -> None:
+    '''
+    Parent-side harness: stand up a root actor, open an actor
+    nursery, spawn one subactor via the currently-selected
+    spawn backend (which this test will have flipped to
+    `subint_forkserver`), run a trivial RPC through its
+    portal, assert the round-trip result.
+
+    '''
+    with trio.fail_after(deadline):
+        async with (
+            tractor.open_root_actor(
+                registry_addrs=[reg_addr],
+            ),
+            tractor.open_nursery() as an,
+        ):
+            portal: tractor.Portal = await an.run_in_actor(
+                _trivial_rpc,
+                name='subint-forkserver-child',
+            )
+            result: str = await portal.wait_for_result()
+            assert result == 'hello from subint-forkserver child'
+
+
+@pytest.fixture
+def forkserver_spawn_method():
+    '''
+    Flip `tractor.spawn._spawn._spawn_method` to
+    `'subint_forkserver'` for the duration of a test, then
+    restore whatever was in place before (usually the
+    session-level CLI choice, typically `'trio'`).
+
+    Without this, other tests in the same session would
+    observe the global flip and start spawning via fork —
+    which is almost certainly NOT what their assertions were
+    written against.
+
+    '''
+    prev_method: str = _spawn_mod._spawn_method
+    prev_ctx = _spawn_mod._ctx
+    try_set_start_method('subint_forkserver')
+    try:
+        yield
+    finally:
+        _spawn_mod._spawn_method = prev_method
+        _spawn_mod._ctx = prev_ctx
+
+
+@pytest.mark.timeout(60, method='thread')
+def test_subint_forkserver_spawn_basic(
+    reg_addr: tuple[str, int | str],
+    forkserver_spawn_method,
+) -> None:
+    '''
+    Happy-path: spawn ONE subactor via the
+    `subint_forkserver` backend (parent-side fork from a
+    main-interp worker thread), do a trivial portal-RPC
+    round-trip, tear the nursery down cleanly.
+
+    If this passes, the "forkserver + tractor runtime" arch
+    is proven end-to-end: the registered
+    `subint_forkserver_proc` spawn target successfully
+    forks a child, the child runs `_actor_child_main()` +
+    completes IPC handshake + serves an RPC, and the parent
+    reaps via `_ForkedProc.wait()` without regressing any of
+    the normal nursery teardown invariants.
+
+    '''
+    deadline: float = 20.0
+    with dump_on_hang(
+        seconds=deadline,
+        path='/tmp/subint_forkserver_spawn_basic.dump',
+    ):
+        trio.run(
+            partial(
+                _happy_path_forkserver,
+                reg_addr,
+                deadline,
+            ),
+        )

tractor/spawn/_spawn.py

@@ -72,6 +72,13 @@
     # `ai/conc-anal/subint_fork_blocked_by_cpython_post_fork_issue.md`
     # + issue #379 for the full analysis.
     'subint_fork',
+    # EXPERIMENTAL — the `subint_fork` workaround. `os.fork()`
+    # from a non-trio worker thread (never entered a subint)
+    # is CPython-legal and works cleanly; forked child runs
+    # `tractor._child._actor_child_main()` against a trio
+    # runtime, exactly like `trio_proc` but via fork instead
+    # of subproc-exec. See `tractor.spawn._subint_forkserver`.
+    'subint_forkserver',
 ]
 _spawn_method: SpawnMethodKey = 'trio'
 
@@ -124,13 +131,14 @@ def try_set_start_method(
         case 'trio':
             _ctx = None
 
-        case 'subint' | 'subint_fork':
-            # Both subint backends need no `mp.context`; both
-            # feature-gate on the py3.14 public
+        case 'subint' | 'subint_fork' | 'subint_forkserver':
+            # All subint-family backends need no `mp.context`;
+            # all three feature-gate on the py3.14 public
             # `concurrent.interpreters` wrapper (PEP 734). See
             # `tractor.spawn._subint` for the detailed
-            # reasoning and the distinction between the two
-            # (`subint_fork` is WIP/experimental).
+            # reasoning. `subint_fork` is blocked at the
+            # CPython level (raises `NotImplementedError`);
+            # `subint_forkserver` is the working workaround.
             from ._subint import _has_subints
             if not _has_subints:
                 raise RuntimeError(
@@ -469,6 +477,7 @@ async def new_proc(
 from ._mp import mp_proc
 from ._subint import subint_proc
 from ._subint_fork import subint_fork_proc
+from ._subint_forkserver import subint_forkserver_proc
 
 
 # proc spawning backend target map
@@ -483,4 +492,8 @@ async def new_proc(
     # clean `NotImplementedError` with pointer to the analysis,
     # rather than an "invalid backend" error.
     'subint_fork': subint_fork_proc,
+    # WIP — fork-from-non-trio-worker-thread, works on py3.14+
+    # (validated via `ai/conc-anal/subint_fork_from_main_thread_smoketest.py`).
+    # See `tractor.spawn._subint_forkserver`.
+    'subint_forkserver': subint_forkserver_proc,
 }