verifiers 0.1.15.dev416__tar.gz → 0.1.15.dev418__tar.gz

{verifiers-0.1.15.dev416 → verifiers-0.1.15.dev418}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: verifiers
-Version: 0.1.15.dev416
+Version: 0.1.15.dev418
 Summary: Verifiers: Environments for LLM Reinforcement Learning
 Project-URL: Homepage, https://github.com/primeintellect-ai/verifiers
 Project-URL: Documentation, https://github.com/primeintellect-ai/verifiers

{verifiers-0.1.15.dev416 → verifiers-0.1.15.dev418}/tests/v1/test_e2e.py

@@ -9,8 +9,8 @@ carries a pytest mark, so subsets select with `-m` (see `conftest.py`).
 `test_user` and `test_tool` fan a server's own runtime against the harness runtime (the full
 reachability matrix); `test_single_turn`/`test_agentic` fan the harness against the harness runtime.
 `test_shared_tool_isolation` runs two concurrent rollouts against one SHARED writable tool server
-(fork off/on) across the full `harness_runtime` x (shared server's own) `tool_runtime` matrix —
-incl. mixed-locality combos — asserting each keeps its own state.
+across the full `harness_runtime` x (shared server's own) `tool_runtime` matrix — incl. mixed-locality
+combos — asserting each keeps its own `self.state`.
 """
 
 import pytest
@@ -126,23 +126,16 @@ async def test_tool_state(run_v1, harness_runtime, tool_runtime, tmp_path):
 
 
 @pytest.mark.e2e
-@pytest.mark.parametrize(
-    "fork",
-    [pytest.param(False, id="fork-off"), pytest.param(True, id="fork-on")],
-)
 async def test_shared_tool_isolation(
-    run_v1_server, harness_runtime, tool_runtime, fork, tmp_path
+    run_v1_server, harness_runtime, tool_runtime, tmp_path
 ):
-    """A SHARED, writable tool server keeps each rollout's state isolated across concurrent rollouts,
-    over the FULL `harness_runtime` x (shared server's own) `tool_runtime` x fork matrix — including
+    """A SHARED, writable tool server keeps each rollout's `self.state` isolated across concurrent
+    rollouts, over the FULL `harness_runtime` x (shared server's own) `tool_runtime` matrix — including
     the mixed-locality combos (e.g. a local harness with a remote shared tool), which is exactly where
-    the rollout's `/state` + `/task` channel must be bridged to the tool's runtime. `scratchpad-v1`
-    gives each task a unique word and rewards 1.0 iff the rollout reads back its OWN word, so two
-    concurrent rollouts (two distinct words on the ONE shared instance) both scoring 1.0 proves no
-    cross-rollout corruption. Each fork mode exercises a different isolation path: fork=off keeps
-    `isolate=True` (the per-rollout `self.state` channel); fork=on sets `isolate=False` (the server
-    writes a process-global slot), so ONLY the forked-child process isolation can keep it correct.
-    `isolate` is a config field (not an env var), so it reaches the shared server in any runtime.
+    the rollout's `/state` channel must be bridged to the tool's runtime. `scratchpad-v1` gives each
+    task a unique word and rewards 1.0 iff the rollout reads back its OWN word, so two concurrent
+    rollouts (two distinct words on the ONE shared instance) both scoring 1.0 proves the per-rollout
+    `self.state` channel keeps them isolated with no cross-rollout corruption.
 
     Placement is fixed to `shared`, so only the own-runtime cases of `tool_runtime` apply (the
     colocated/shared params have no distinct runtime to fan — skipped). Runs through the env-server
@@ -158,13 +151,6 @@ async def test_shared_tool_isolation(
         pytest.skip(
             "tool server in a prime sandbox needs prime port exposure (unreachable from host here)"
         )
-    # A prime harness relays every model call through the sandbox, so two concurrent rollouts driving
-    # the EXPERIMENTAL fork-per-rollout server can't finish within the rollout cap (reward stays 0).
-    # The fork-isolation path is covered by the subprocess/docker harness cases.
-    if harness_runtime == "prime" and fork:
-        pytest.skip(
-            "prime harness + experimental fork-per-rollout is too slow under concurrency to finish in the rollout cap"
-        )
     traces = await run_v1_server(
         "scratchpad-v1",
         harness="null",
@@ -176,8 +162,6 @@ async def test_shared_tool_isolation(
         taskset_overrides={
             "tools": {
                 "shared": True,
-                "fork": fork,
-                "isolate": not fork,  # fork=on: write a global slot so ONLY fork can isolate it
                 **tool_runtime,  # the shared tool's own runtime ({"runtime": {"type": ...}})
             }
         },

{verifiers-0.1.15.dev416 → verifiers-0.1.15.dev418}/verifiers/v1/GUIDE.md

@@ -511,19 +511,17 @@ the default is the cheapest correct thing; the rest trade setup cost for isolati
 | **own runtime** *(default)* | *(nothing; `runtime = {type = "docker"\|"prime"}` for a sandbox)* | own runtime per rollout — `subprocess` on the host (default), or a `docker`/`prime` sandbox over a tunnel | full per-rollout isolation; a sandbox also isolates untrusted code / deps / network | pays `setup` every rollout (a sandbox adds spin-up + env install) |
 | **colocated** | `colocated = true` | inside the harness's runtime, one per rollout (no tunnel) | no extra runtime/tunnel; can touch the harness's filesystem | couples to the harness; `setup` per rollout |
 | **shared** | `shared = true` | one instance for the whole eval | `setup` once; writable per-rollout if state lives in `self.state` | state outside `self.state` corrupts across rollouts; `setup_task` skipped |
-| **shared + fork** | `shared = true, fork = true` | warm parent + forked child per rollout (copy-on-write) | `setup` once **and** isolates arbitrary in-process/on-disk state; runs `setup_task` per child | a process per concurrent rollout; Linux only |
 | **remote** *(tools only)* | `url = "https://…"` | connects to an already-running MCP endpoint | zero hosting; use a public/third-party server | no isolation, state, or lifecycle control |
 
-`shared` (and `fork`) work on any runtime — the framework makes the rollout's `/state` channel
-reachable from the shared server (localhost, or a host tunnel when remote). Keep big shared data
-off the Python heap (numpy / mmap / an on-disk index) so fork's copy-on-write actually saves
-memory.
+`shared` works on any runtime — the framework makes the rollout's `/state` channel reachable from the
+shared server (localhost, or a host tunnel when remote). Keep big shared data off the Python heap
+(numpy / mmap / an on-disk index) so one instance scales across rollouts.
 
 **Choosing per-rollout state:** read-only resource → `shared`; state that fits a `State` model →
 `shared` + `self.state` (no extra process, the scalable default); state that can't (module globals,
-on-disk scratch, a stateful C library) → `shared + fork` or a per-rollout placement that pays
-`setup` each time; cheap `setup` → just use the default. **User simulators** support only the
-per-rollout placements (own runtime or `colocated`); `shared` / `fork` / `url` are tools-only.
+on-disk scratch, a stateful C library) → a per-rollout placement (own runtime or `colocated`) that
+pays `setup` each time; cheap `setup` → just use the default. **User simulators** support only the
+per-rollout placements (own runtime or `colocated`); `shared` / `url` are tools-only.
 
 ## Learn from the examples
 

{verifiers-0.1.15.dev416 → verifiers-0.1.15.dev418}/verifiers/v1/interception/server.py

@@ -216,8 +216,8 @@ class InterceptionServer:
         # GET/PUT their `self.state` here, keyed by the same bearer secret as the model routes.
         app.router.add_get("/state", self.handle_state_get)
         app.router.add_put("/state", self.handle_state_put)
-        # A forked shared server (see `verifiers.v1.mcp.multiplex`) fetches its rollout's task here
-        # to run `setup_task` per child — a shared server gets no task via env, keyed by the secret.
+        # A launched tool/user server fetches its rollout's task here to run `setup_task` — the task
+        # is never passed via env, only over this channel, keyed by the same bearer secret.
         app.router.add_get("/task", self.handle_task_get)
         self.runner = web.AppRunner(app)
         await self.runner.setup()
@@ -585,7 +585,7 @@ class InterceptionServer:
         )
 
     async def handle_task_get(self, request: web.Request) -> web.Response:
-        """Hand a forked shared server the rollout's task (class ref + JSON) so its child can run
+        """Hand a launched tool/user server the rollout's task (class ref + JSON) so it can run
         `setup_task` for this rollout — keyed by the same bearer secret as the state channel."""
         session = self._session_for(request)
         if session is None:

{verifiers-0.1.15.dev416 → verifiers-0.1.15.dev418}/verifiers/v1/mcp/launch.py

@@ -287,23 +287,11 @@ async def serve(
             "is built once for the whole eval and must be task-agnostic — it receives no task. "
             "Drop `shared` to run it per-rollout (with the task), or make its `setup` task-independent."
         )
-    if (
-        shared
-        and not getattr(cfg, "fork", False)
-        and type(server).setup_task is not ServerBase.setup_task
-    ):
+    if shared and type(server).setup_task is not ServerBase.setup_task:
         logger.warning(
             "shared server %r overrides `setup_task`, but `setup_task` is NEVER called for a shared "
             "server (it's built once, task-agnostic) — its per-task logic will not run. Move "
-            "task-agnostic work into `setup`, drop `shared` to run it per-rollout, or set `fork=True` "
-            "(each rollout gets a forked child that runs `setup_task`).",
-            server.server_name,
-        )
-    if shared and getattr(cfg, "fork", False):
-        # `serve_tools` makes the rollout's /state + /task channel reachable from the shared server's
-        # runtime (a host tunnel when it's remote), so any harness/runtime combo works.
-        logger.warning(
-            "shared server %r uses fork-per-rollout isolation, which is EXPERIMENTAL",
+            "task-agnostic work into `setup`, or drop `shared` to run it per-rollout.",
             server.server_name,
         )
     async with contextlib.AsyncExitStack() as stack:
@@ -383,11 +371,11 @@ async def serve_shared(toolsets: list[Toolset], harness_is_local: bool = True):
 
 def _shared_url_for_rollout(url: str, state_base: str | None, state_secret: str) -> str:
     """Tag a `shared` server's eval-level URL with this rollout's state-channel coordinates, so the
-    one shared process serves each rollout its OWN `self.state` (and a forked child fetches its task).
-    `state_base` is the interception server's reachable base for THIS rollout, chosen by the caller to
-    be reachable from the shared server's runtime (localhost, or a host tunnel for a remote runtime).
-    The secret is the bearer the harness already holds, so it's no new exposure — but it must not be
-    logged (callers log the untagged base)."""
+    one shared process serves each rollout its OWN `self.state`. `state_base` is the interception
+    server's reachable base for THIS rollout, chosen by the caller to be reachable from the shared
+    server's runtime (localhost, or a host tunnel for a remote runtime). The secret is the bearer the
+    harness already holds, so it's no new exposure — but it must not be logged (callers log the
+    untagged base)."""
     if not state_base:
         return url
     parts = urlsplit(url)
@@ -397,19 +385,6 @@ def _shared_url_for_rollout(url: str, state_base: str | None, state_secret: str)
     return urlunsplit(parts._replace(query=urlencode(query)))
 
 
-async def reap_forked_child(shared_url: str, secret: str) -> None:
-    """Best-effort: POST `/vf/close` to reap this rollout's forked child on teardown (a `fork` shared
-    server, see `multiplex`); the multiplexer otherwise only reaps a child when it exits."""
-    close_url = (
-        f"{shared_url.rsplit('/mcp', 1)[0]}/vf/close?{STATE_SECRET_PARAM}={secret}"
-    )
-    with contextlib.suppress(Exception):
-        import httpx
-
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            await client.post(close_url)
-
-
 @contextlib.asynccontextmanager
 async def serve_tools(
     toolsets: list[Toolset],
@@ -456,11 +431,6 @@ async def serve_tools(
                 # log the untagged base, NOT urls[name] — the per-rollout tag carries the rollout's
                 # bearer secret (`vf_state_secret`), which must not reach a log sink
                 logger.info("tool server '%s' (shared): %s", name, shared_urls[name])
-                if getattr(cfg, "fork", False) and state_secret:
-                    # reap this rollout's forked child when the rollout's tool-serving scope exits
-                    stack.push_async_callback(
-                        reap_forked_child, shared_urls[name], state_secret
-                    )
             else:
                 urls[name] = await stack.enter_async_context(
                     serve(

{verifiers-0.1.15.dev416 → verifiers-0.1.15.dev418}/verifiers/v1/mcp/server.py

@@ -118,8 +118,7 @@ def _request_query(name: str) -> str | None:
 def _die_with_parent() -> None:
     """Ask the kernel to SIGKILL this process when its parent (the launcher) dies, so a server is
     never orphaned if its launcher is torn down without stopping it (a backstop to the runtime's
-    own cleanup). Linux-only; a no-op elsewhere. Cleared across `fork`, so a forked child must call
-    it again."""
+    own cleanup). Linux-only; a no-op elsewhere."""
     import ctypes
     import signal
 
@@ -241,9 +240,8 @@ class ServerBase(Generic[ConfigT, StateT]):
         self, state_url: str | None, secret: str
     ) -> None:
         """Fetch this rollout's task over the state channel and run `setup_task` for it — a no-op
-        without a channel or task (a shared, task-agnostic server). The single place task setup
-        happens: `_serve` calls it with the env channel; a forked child calls it with its per-request
-        channel (see `verifiers.v1.mcp.multiplex`)."""
+        without a channel or task (a shared, task-agnostic server). Called by `_serve` with the
+        per-rollout env channel a launched server carries."""
         task = await self._fetch_task(state_url, secret)
         if task is not None:
             await self.setup_task(task)
@@ -332,8 +330,8 @@ class ServerBase(Generic[ConfigT, StateT]):
         async def _setup() -> None:
             await self.setup()
             # Per-rollout servers carry the rollout's state channel in their env; fetch this rollout's
-            # task over it and run `setup_task`. A shared server has no env channel (its forked
-            # children fetch /task per-request instead — see multiplex), so this is a no-op for it.
+            # task over it and run `setup_task`. A shared server has no env channel, so this is a
+            # no-op for it (it's task-agnostic — one instance for the whole eval).
             await self._setup_task_from_channel(*self._state_channel())
 
         asyncio.run(_setup())
@@ -369,13 +367,6 @@ class ServerBase(Generic[ConfigT, StateT]):
                 self._state_client = None
 
         app.router.lifespan_context = serving_lifespan
-        if getattr(self.config, "fork", False):
-            # `setup` ran once above (warm); fork a child per rollout that inherits it and runs
-            # `setup_task` for the rollout's task (see multiplex).
-            from verifiers.v1.mcp.multiplex import serve_forked
-
-            serve_forked(app, sock, self)
-            return
         server = uvicorn.Server(uvicorn.Config(app, log_level="critical"))
         asyncio.run(server.serve(sockets=[sock]))
 

{verifiers-0.1.15.dev416 → verifiers-0.1.15.dev418}/verifiers/v1/mcp/toolset.py

@@ -32,8 +32,6 @@ class ToolsetConfig(BaseConfig):
         costs a per-rollout install.
       - shared: one instance for the whole eval, in its own `runtime` (pays `setup` once; per-rollout
         writable state stays isolated via `self.state`).
-      - shared + fork: like shared, but a forked child per rollout (copy-on-write) also isolates
-        state that can't live in `self.state`.
     See the placement/isolation section of `verifiers/v1/GUIDE.md` for the trade-offs of each.
     Subclass to add the server's own knobs (the data its `@tool` methods read). The server name is
     the class's `TOOL_PREFIX` ClassVar, not a field here — it's an identity (the model sees
@@ -51,15 +49,6 @@ class ToolsetConfig(BaseConfig):
     server's URL), so concurrent rollouts don't corrupt each other — provided the shared server runs
     on a local runtime (the default), which can reach the host's interception server. Mutually
     exclusive with `colocated`."""
-    fork: bool = False
-    """For a `shared` server: fork a child process per rollout (copy-on-write memory + a private
-    working dir), so per-rollout state that can't live in `self.state` — module globals, a mutated
-    in-memory object, relative-path on-disk writes — is isolated per rollout automatically. The
-    expensive `setup` runs once in the parent; each child inherits it warm and runs `setup_task` for
-    its rollout's task (see `verifiers.v1.mcp.multiplex`) — so a stateful per-rollout server pays its
-    `setup` once yet stays isolated. Requires `shared`; works on any runtime (a remote one reaches the
-    rollout's state/task channel over a host tunnel). Linux/fork only; not for CUDA/GPU state or
-    background threads in the server."""
     runtime: RuntimeConfig = SubprocessConfig()
     """The server's own runtime, used unless `colocated` (host/subprocess by default — always
     reachable from any harness runtime; set docker/prime to isolate it in its own sandbox)."""
@@ -72,10 +61,6 @@ class ToolsetConfig(BaseConfig):
     def _validate_placement(self) -> "ToolsetConfig":
         if self.colocated and self.shared:
             raise ValueError("colocated and shared are mutually exclusive")
-        if self.fork and not self.shared:
-            raise ValueError(
-                "fork requires shared — a per-rollout server already runs in its own process"
-            )
         return self
 
 

{verifiers-0.1.15.dev416 → verifiers-0.1.15.dev418}/verifiers/v1/tasksets/harbor/taskset.py

@@ -90,6 +90,10 @@ class HarborTask(Task):
     tags: list[str] = []
     task_dir: str = Field(exclude=True)
     """Host path to the task dir; used to stage tests/ to verify, not serialized."""
+    verifier_env: dict[str, str] = {}
+    """Raw [verifier.env] entries (literals or `${VAR}`/`${VAR:-default}` templates).
+    Resolved against the host environment at scoring time, like `harbor run` — so a
+    verifier that needs judge API keys or configuration actually receives them."""
 
 
 def harbor_cli() -> str:
@@ -268,9 +272,23 @@ def parse_task(task_dir: Path, idx: int, harbor_config: HarborConfig) -> HarborT
         category=meta.get("category"),
         tags=meta.get("tags", []),
         task_dir=str(task_dir),
+        verifier_env=config.get("verifier", {}).get("env", {}),
     )
 
 
+def verifier_env(task: HarborTask) -> dict[str, str]:
+    """The env a task's verifier runs with: its [verifier.env] templates resolved against
+    the host environment (`${VAR}` / `${VAR:-default}`, harbor's own semantics). Resolution
+    is deferred to scoring time so resolved secrets never land on the serialized task."""
+    if not task.verifier_env:
+        return {}
+    # Lazy: `harbor` is the optional extra, but scoring implies the dataset was
+    # downloaded, which already required it.
+    from harbor.utils.env import resolve_env_vars
+
+    return resolve_env_vars(task.verifier_env)
+
+
 # Harbor test directories are immutable after download, so repeated rollouts can reuse
 # the latest archive. One entry bounds retained memory to one task.
 @lru_cache(maxsize=1)
@@ -315,7 +333,7 @@ class HarborTaskset(Taskset[HarborTask, HarborConfig]):
             ],
             {},
         )
-        await runtime.run(["sh", "-c", "cd /tests && bash test.sh"], {})
+        await runtime.run(["sh", "-c", "cd /tests && bash test.sh"], verifier_env(task))
         try:
             reward = (await runtime.read("/logs/verifier/reward.txt")).decode().strip()
             return float(reward or 0)

verifiers-0.1.15.dev416/verifiers/v1/mcp/multiplex.py

@@ -1,302 +0,0 @@
-"""Fork-per-rollout isolation for a SHARED tool server.
-
-A `shared` server is one process for the whole eval; `self.state` isolates its per-rollout state over
-the interception channel (see `server`), but state that DOESN'T live in `self.state` — module globals,
-a mutated in-memory object (an index the tool edits), relative-path on-disk writes — is still shared
-across rollouts. `ToolsetConfig(fork=True)` isolates those too: the expensive `setup` runs ONCE in a
-parent process, then a child is forked per rollout on first contact — the child inherits the warm
-state copy-on-write (in-memory state isolated on write), runs in a private working directory
-(relative-path writes isolated), and runs `setup_task` for its rollout's task (fetched from the
-interception server's `/task` channel — a shared server gets no task via env). The parent is a thin
-async reverse proxy that pins each rollout to its child and streams MCP traffic (so SSE works). So an
-ordinary stateful per-rollout server (expensive `setup` + per-rollout `setup_task`) is isolated
-per rollout with no rollout-aware code.
-
-The rollout key is the per-rollout secret the framework tags onto a shared server's URL
-(`STATE_SECRET_PARAM`, see `serve_tools`), alongside the reachable interception base
-(`STATE_URL_PARAM`) for this rollout's `/state` + `/task`. The proxy routes by the key (intra-sandbox,
-no host needed); the child reaches `/state` + `/task` over that base, which `serve_tools` makes
-reachable from the shared server's runtime (localhost, or a host tunnel when it's remote) — so fork
-works on any harness/runtime combo. A child lives for its whole rollout: it is reaped on a `POST
-/vf/close?<key>` from rollout teardown, and on parent exit (each child also dies with the parent via
-`PR_SET_PDEATHSIG`). There is no idle reaper — idle time can't tell a slow-but-live rollout from a
-leaked one, and reaping a live rollout's child would re-run `setup_task` on the next call and wipe its
-in-process state.
-
-Caveats: Linux/fork only; do NOT use with CUDA/GPU state or background threads in the server (fork
-copies neither safely) — the fork here is from a single-threaded loop, before any such state. Writes
-to absolute paths outside the private CWD are not isolated.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import concurrent.futures
-import contextlib
-import hashlib
-import logging
-import os
-import shutil
-import signal
-import socket
-import tempfile
-import time
-from urllib.parse import parse_qs
-
-from verifiers.v1.mcp.server import (
-    STATE_SECRET_PARAM,
-    STATE_URL_PARAM,
-    _die_with_parent,
-)
-
-logger = logging.getLogger(__name__)
-
-CLOSE_PATH = "/vf/close"
-"""The framework POSTs here (with the rollout key) on rollout teardown to reap that child promptly."""
-
-_HOP_BY_HOP = {
-    "connection",
-    "keep-alive",
-    "transfer-encoding",
-    "content-length",
-    "host",
-}
-
-
-class _Child:
-    def __init__(self, pid: int, port: int, cwd: str) -> None:
-        self.pid, self.port, self.cwd = pid, port, cwd
-        # set once the child is serving; reap() also sets it, to wake any waiter
-        self.ready = asyncio.Event()
-
-
-def _serve_child(
-    app, sock: socket.socket, cwd: str, server, state_url: str, secret: str
-) -> None:
-    """In the forked child: die with the parent, move to a private CWD, run `setup_task` for this
-    rollout's task (over the per-request state channel), and serve `app` on the inherited (already
-    bound) `sock` with a fresh event loop (the inherited parent loop is abandoned). Never returns."""
-    import uvicorn
-
-    _die_with_parent()  # SIGKILL this child when the parent multiplexer dies (cleared by fork)
-    os.chdir(cwd)
-    loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(loop)
-    try:
-        loop.run_until_complete(server._setup_task_from_channel(state_url, secret))
-        loop.run_until_complete(
-            uvicorn.Server(
-                uvicorn.Config(
-                    app,
-                    log_level="critical",
-                    # exit promptly on SIGTERM at teardown — don't hang waiting on the long-lived
-                    # MCP SSE connection to close (the parent SIGKILLs us / PR_SET_PDEATHSIG fires).
-                    timeout_graceful_shutdown=0,
-                )
-            ).serve(sockets=[sock])
-        )
-    finally:
-        os._exit(0)
-
-
-async def _wait_up(port: int, timeout: float = 30.0) -> None:
-    deadline = time.monotonic() + timeout
-    while time.monotonic() < deadline:
-        try:
-            _, writer = await asyncio.open_connection("127.0.0.1", port)
-            writer.close()
-            return
-        except OSError:
-            await asyncio.sleep(0.05)
-    raise RuntimeError(f"fork child on port {port} did not come up")
-
-
-def serve_forked(app, sock: socket.socket, server) -> None:
-    """Serve `app` on the bound `sock` as a fork-per-rollout multiplexer (see module docstring).
-    `app` is the warm MCP ASGI app, built once in the parent after `setup`; forked children inherit
-    it copy-on-write. `server` is the `ServerBase` whose tools the app exposes — each child runs its
-    `setup_task` for the rollout's task. `sock` is the socket the launcher reads the port back from."""
-    import httpx
-    import uvicorn
-
-    base = tempfile.mkdtemp(prefix="vf_fork_")
-    children: dict[str, _Child] = {}
-    forking = asyncio.Lock()
-    client = httpx.AsyncClient(timeout=None)
-
-    def _spawn(key: str, state_url: str) -> _Child:
-        # Bind the child's port HERE and keep it bound across the fork — the child serves on this exact
-        # (inherited) socket, so the port is never released: no TOCTOU window. Fully synchronous (no
-        # await), so it runs entirely under `forking`, which serializes the fork() from a single loop.
-        child_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        child_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        child_sock.bind(("127.0.0.1", 0))  # 0 = an OS-assigned free port
-        port = child_sock.getsockname()[1]
-        # name the private dir by a hash, not `key` — `key` is the rollout's bearer secret, which
-        # shouldn't appear as a filesystem path
-        slug = hashlib.sha256(key.encode()).hexdigest()[:16] if key else "_default"
-        cwd = os.path.join(base, slug)
-        os.makedirs(cwd, exist_ok=True)
-        pid = os.fork()
-        if pid == 0:
-            # child: serves on the inherited socket (setup_task first); never returns
-            _serve_child(app, child_sock, cwd, server, state_url, key)
-        child_sock.close()  # parent: the child owns the socket fd now
-        return _Child(pid, port, cwd)
-
-    async def ensure(key: str, state_url: str) -> _Child:
-        # Fast path: a live child — no lock, no readiness probe.
-        child = children.get(key)
-        if child is not None and child.ready.is_set():
-            return child
-        # Readiness waits stay outside the lock, so traffic to ready children remains lock-free.
-        async with forking:
-            child = children.get(key)
-            creating = child is None
-            if creating:
-                children[key] = child = _spawn(key, state_url)
-        if not creating:
-            # Another task is bringing this key up — wait for it, don't re-fork.
-            await child.ready.wait()
-            if (
-                children.get(key) is not child
-            ):  # reaped / failed to start meanwhile → retry
-                return await ensure(key, state_url)
-            return child
-        # We created it: wait for it to serve OUTSIDE the lock, so other keys fork in parallel.
-        try:
-            await _wait_up(child.port)
-        except BaseException:
-            await reap(
-                key
-            )  # dead on arrival: drop it (wakes any waiter to re-fork), then propagate
-            raise
-        child.ready.set()
-        # log only the pid (it correlates spawn<->reap) — the key is the rollout's bearer secret
-        logger.info("fork: spawned child pid=%d", child.pid)
-        return child
-
-    async def reap(key: str) -> None:
-        # Keep fork() out of the cleanup thread's lifetime; ready children bypass this lock.
-        async with forking:
-            child = children.pop(key, None)
-            if not child:
-                return
-            child.ready.set()  # wake waiters; they re-check `children` before re-forking
-            with contextlib.suppress(Exception):
-                os.kill(child.pid, signal.SIGKILL)
-
-            def cleanup() -> None:
-                with contextlib.suppress(Exception):
-                    os.waitpid(child.pid, 0)
-                shutil.rmtree(child.cwd, ignore_errors=True)
-
-            # One worker keeps cleanup ordered and lets it finish if this task is cancelled.
-            loop = asyncio.get_running_loop()
-            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
-                future = loop.run_in_executor(executor, cleanup)
-                try:
-                    await asyncio.shield(future)
-                except asyncio.CancelledError:
-                    await future
-                    raise
-        logger.info("fork: reaped child pid=%d", child.pid)
-
-    async def _respond(send, status: int, body: bytes) -> None:
-        await send({"type": "http.response.start", "status": status, "headers": []})
-        await send({"type": "http.response.body", "body": body})
-
-    async def proxy(scope, receive, send) -> None:
-        if scope["type"] == "lifespan":
-            # Drive the proxy app's own (empty) lifespan; each child runs the real app's lifespan.
-            while True:
-                msg = await receive()
-                if msg["type"] == "lifespan.startup":
-                    await send({"type": "lifespan.startup.complete"})
-                elif msg["type"] == "lifespan.shutdown":
-                    await send({"type": "lifespan.shutdown.complete"})
-                    return
-        if scope["type"] != "http":
-            return
-        params = parse_qs(scope.get("query_string", b"").decode())
-        key = (params.get(STATE_SECRET_PARAM) or [""])[0]
-        state_url = (params.get(STATE_URL_PARAM) or [""])[0]
-        if scope["path"] == CLOSE_PATH:
-            await reap(key)
-            await _respond(send, 200, b"closed")
-            return
-        body: list[bytes] = []
-        more = True
-        while more:  # read the request body, then forward to the rollout's child
-            msg = await receive()
-            body.append(msg.get("body", b""))
-            more = msg.get("more_body", False)
-        # Bring the child up and stream its response back. Any failure here (child never came up,
-        # `ensure` timed out, upstream errored mid-stream) must not leave the ASGI caller hanging:
-        # send a clean 502 if nothing was sent yet, else end the started body so the client stops.
-        started = False
-        try:
-            child = await ensure(key, state_url)
-            headers = [
-                (k.decode(), v.decode())
-                for k, v in scope["headers"]
-                if k.decode().lower() not in _HOP_BY_HOP
-            ]
-            qs = scope.get("query_string", b"").decode()
-            url = f"http://127.0.0.1:{child.port}{scope['path']}" + (
-                f"?{qs}" if qs else ""
-            )
-            req = client.build_request(
-                scope["method"], url, headers=headers, content=b"".join(body)
-            )
-            resp = await client.send(req, stream=True)
-            try:
-                out = [
-                    (k.encode(), v.encode())
-                    for k, v in resp.headers.items()
-                    if k.lower() not in _HOP_BY_HOP
-                ]
-                await send(
-                    {
-                        "type": "http.response.start",
-                        "status": resp.status_code,
-                        "headers": out,
-                    }
-                )
-                started = True
-                async for chunk in resp.aiter_raw():
-                    await send(
-                        {"type": "http.response.body", "body": chunk, "more_body": True}
-                    )
-                await send(
-                    {"type": "http.response.body", "body": b"", "more_body": False}
-                )
-            finally:
-                await resp.aclose()
-        except Exception as exc:
-            logger.warning("fork: proxy error forwarding to child: %s", exc)
-            if started:
-                with contextlib.suppress(Exception):
-                    await send(
-                        {"type": "http.response.body", "body": b"", "more_body": False}
-                    )
-            else:
-                await _respond(send, 502, b"fork proxy error")
-
-    async def _serve() -> None:
-        # timeout_graceful_shutdown=0: exit promptly on SIGTERM (the runtime's teardown) instead of
-        # hanging on the long-lived proxied SSE — so `finally` below SIGKILLs the children.
-        try:
-            await uvicorn.Server(
-                uvicorn.Config(proxy, log_level="critical", timeout_graceful_shutdown=0)
-            ).serve(sockets=[sock])
-        finally:
-            await client.aclose()
-
-    try:
-        asyncio.run(_serve())
-    finally:
-        for key in list(children):
-            with contextlib.suppress(Exception):
-                os.kill(children[key].pid, signal.SIGKILL)
-        shutil.rmtree(base, ignore_errors=True)