gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/host.py

@@ -0,0 +1,2437 @@
+"""The World Host: one long-lived process that serves many world sessions.
+
+Where the pod engine boots a container per session, the host keeps each
+world VERSION cached once and opens a SESSION as a copy-on-write clone of that
+version's snapshot — a file operation, not a scheduling one. One process
+answers for every session it owns, routed by the ``w-<sid>[-api]`` Host header
+the platform already mints (``worldSurfaces.sessionOrigins``), so there is
+nothing per session in Kubernetes or the load balancer.
+
+Two planes on one HTTP server:
+
+* the **control plane** (``/__host/*``, behind ``X-Host-Secret``) is the
+  platform's half: open, close, reset, seed, state, grade, call. It is
+  synchronous — a ``seed`` or ``grade`` completes in the response, not over a
+  poll — because the host holds the world in memory.
+* the **data plane** (everything else) is the end user's half: the world's own
+  vendor routes, selected by session and checked against that session's token,
+  answered in-process by :class:`WorldApp`.
+
+Every session carries a lease. Control calls and data-plane requests renew it;
+a session the platform stops touching expires on the host and is unlinked, so
+a missed reconcile tick on the platform is recovered, not leaked.
+
+A session's state is one sqlite file, so it is also its own durable form: the
+platform asks the host to **export** a session (a consistent copy, hashed) and
+to **upload** that copy to a presigned URL the platform holds the key for, and
+later **opens** the same session id on any host with ``restore`` naming the
+export, which is how a session survives the host that held it.
+
+The host serves schema worlds (a ``gateway-world/1`` tree :class:`WorldState`
+can open) with the ``tools`` and ``api`` surfaces. A world with no code of its
+own is answered in this process. A world that brings an ``api/handlers.py`` is
+placed on a **version worker** (:mod:`workers`): a subprocess of this host, one
+per version, reached over a unix socket, with rlimits and a scrubbed
+environment, running the same :class:`WorldHost` with ``run_handlers`` on. The
+supervisor keeps the registry, the leases and the token gate; the worker keeps
+the world. The **ui** surface is the version's prebuilt static app, served from
+the cache by the supervisor with its ``api_path`` rewritten onto the session's
+api; the **browser** surface is a websocket tunnel to the pool Chromium the
+platform leased for the session (:mod:`host_surfaces`). Custom-server worlds
+stay on pods; this module refuses a version it cannot open rather than
+guessing.
+"""
+
+from __future__ import annotations
+
+import base64
+import fcntl
+import hashlib
+import hmac
+import http.client
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+import tarfile
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from collections import Counter
+from collections.abc import Callable, Iterable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Protocol
+
+from .._tar import safe_tar_extract
+from . import snapshot as snapshots
+from .api import (
+    SCENARIOS,
+    ApiSettings,
+    Handler,
+    Router,
+    WorldApp,
+    WorldState,
+    load_api_settings,
+    load_handlers,
+    send_response,
+)
+from .compiler import check_bundle
+from .connector import Spec, load_spec
+from .host_surfaces import (
+    HOP_HEADER,
+    UiSurface,
+    api_target,
+    cookie_token,
+    load_ui_surface,
+    matches,
+    mint_live_grant,
+    query_token,
+    session_cookie,
+    static_file,
+    tunnel,
+    verify_live_grant,
+    without_query_token,
+)
+from .tasks import (
+    TaskSpec,
+    evaluate_assertions,
+    parse_task_spec,
+    unknown_task_entities,
+    unknown_task_tools,
+    write_task_dir,
+)
+from .tools_world import ToolsVersion, ToolsWorld, is_tools_bundle, load_tools_version
+from .validation import ContractError, fail
+from .workers import (
+    DEFAULT_WORKER_BUDGET_MB,
+    DEFAULT_WORKER_MEMORY_MB,
+    Worker,
+    WorkerCapacity,
+    WorkerGone,
+    WorkerPool,
+    confined_command,
+    verifier_environment,
+)
+
+#: The world tree inside an api bundle, or the bundle root for a bare tree.
+BUNDLED_WORLD = "server/world"
+API_BUNDLE = "gateway-api-world.toml"
+VERIFY_TIMEOUT_S = 30.0
+#: How long a session lives with no control call or request renewing it.
+DEFAULT_LEASE_S = 3600.0
+#: How often the host sweeps expired leases.
+LEASE_SWEEP_S = 30.0
+#: How long an owner lookup answer is trusted before asking the platform again.
+#: An owner that does not answer a proxied request is asked about again at once.
+OWNER_CACHE_S = 60.0
+#: How long "no owner" is trusted: long enough that a client hammering a closed
+#: session costs the platform one call at a time, short enough that a session
+#: recovered onto another host is reached at once.
+OWNER_MISS_S = 2.0
+#: How many sessions one host takes before the platform places elsewhere.
+DEFAULT_MAX_SESSIONS = 1500
+#: The error code (and a 404) a control call gets for a session this host does
+#: not hold. The platform treats exactly this answer as "the host lost it".
+UNKNOWN_SESSION = "unknown_session"
+#: How often a host tells the platform it is alive and what it holds.
+HEARTBEAT_S = 10.0
+#: How long a draining host waits for its sessions to close before it exits.
+DEFAULT_DRAIN_S = 45.0
+#: Response headers a relayed answer does NOT keep: the framing is this
+#: connection's, everything else the world set (its ``page_headers``, a
+#: handler's own headers) passes through, from a worker and from an owner alike.
+FRAMING_HEADERS = frozenset({"content-length", "connection", "transfer-encoding", "server", "date"})
+#: Hop-by-hop headers (RFC 9110 §7.6.1) an owner's answer does not carry past
+#: the proxying replica.
+HOP_BY_HOP_HEADERS = frozenset(
+    {"keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "upgrade", "proxy-connection"}
+)
+PROXIED_DROP_HEADERS = FRAMING_HEADERS | HOP_BY_HOP_HEADERS
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """An owner's redirect is the client's to follow, not the proxy's: the ui
+    token exchange answers 303 with the session cookie, and following it here
+    would drop the cookie and land on the owner's 401."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+#: The opener the one-hop proxy uses: relays the owner's answer as is, a
+#: redirect included, rather than following it.
+_PROXY_OPENER = urllib.request.build_opener(_NoRedirect)
+#: How long the grant the host mints towards the relay lives: the viewer's own
+#: grant was already checked, this one only has to survive the handshake.
+LIVE_RELAY_GRANT_MS = 60_000
+#: What a session export is: the session's sqlite file, as the store wrote it.
+EXPORT_CONTENT_TYPE = "application/vnd.sqlite3"
+#: How long one export upload or restore download may take.
+TRANSFER_TIMEOUT_S = 300.0
+#: The most a version bundle may weigh, compressed and extracted, before the
+#: host refuses it: the cache is one shared disk and a build's memory is the
+#: supervisor's.
+DEFAULT_MAX_BUNDLE_MB = 2048
+MAX_BUNDLE_MEMBERS = 200_000
+#: The largest request body the host reads, on either plane. A body is held
+#: in memory whole (the seed rows, a tool call's args, a vendor route's
+#: payload), and the memory is the supervisor's, shared by every session on
+#: the replica; a client cannot be let size that allocation.
+DEFAULT_MAX_BODY_MB = 32
+
+
+# --------------------------------------------------------------------------- #
+# Reflink: a session's state is a copy-on-write clone of the version snapshot.
+# --------------------------------------------------------------------------- #
+
+_FICLONE = 0x40049409  # ioctl: clone one file's extents into another (btrfs/XFS)
+
+
+def clone_file(src: Path, dst: Path) -> None:
+    """Copy ``src`` to ``dst`` cheaply. A reflink (``FICLONE``) shares the
+    version snapshot's blocks copy-on-write, so opening a session costs the
+    same whatever the snapshot's size; a filesystem without reflink falls back
+    to a plain copy, which is what the pod engine does today."""
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with open(src, "rb") as s, open(dst, "wb") as d:
+            fcntl.ioctl(d.fileno(), _FICLONE, s.fileno())
+        return
+    except OSError:
+        pass  # not supported here (tmpfs, ext4, cross-device) — copy instead
+    shutil.copyfile(src, dst)
+
+
+OBJECT_STORE_ANY = "any"
+_ORIGIN_HOST = re.compile(r"^[A-Za-z0-9.-]+(:[0-9]+)?$")
+
+
+def parse_origins(value: str | None) -> frozenset[str] | None:
+    """``WORLDS_HOST_OBJECT_STORE``: the origins (``scheme://host[:port]``,
+    comma-separated) the platform's presigned URLs may point at, or the word
+    ``any`` for a dev host reading ``file://`` bundles (``None``: every URL
+    admitted). Unset is refused rather than read as ``any``: a deployed host
+    with no allowlist is a host whose secret can aim it anywhere, and a
+    template's placeholder (``https://<bucket>.s3...``) is refused by name."""
+    if value is None or not value.strip():
+        fail(
+            "host",
+            "WORLDS_HOST_OBJECT_STORE is unset; name the object store's origins "
+            f"(https://bucket.s3.amazonaws.com) or {OBJECT_STORE_ANY!r} for a dev host",
+        )
+        raise AssertionError  # fail() never returns
+    if value.strip().lower() == OBJECT_STORE_ANY:
+        return None
+    origins = set()
+    for item in value.split(","):
+        item = item.strip()
+        if not item:
+            continue
+        parts = urllib.parse.urlsplit(item)
+        if parts.scheme not in ("http", "https") or not parts.netloc or parts.path not in ("", "/"):
+            fail(
+                "host",
+                f"WORLDS_HOST_OBJECT_STORE entries are origins like https://bucket.s3.amazonaws.com, not {item!r}",
+            )
+        if not _ORIGIN_HOST.match(parts.netloc):
+            fail(
+                "host",
+                f"WORLDS_HOST_OBJECT_STORE names a placeholder, not a host: {item!r}; set the real bucket origin",
+            )
+        origins.add(f"{parts.scheme}://{parts.netloc}".lower())
+    return frozenset(origins)
+
+
+def check_object_store_url(url: object, origins: frozenset[str] | None, what: str) -> str:
+    """The presigned URL the control plane handed us, once it is a string on one
+    of the object store's origins. The control plane is trusted with the host
+    secret, not with the host's network: a URL pointing anywhere else (the
+    metadata service, a cluster Service, the internet) is refused before a
+    byte moves, so a leaked secret cannot turn a session's state or the host's
+    reach into someone else's download."""
+    if not isinstance(url, str) or not url:
+        fail("host", f"{what} must be a presigned url")
+        raise AssertionError  # fail() never returns
+    if origins is None:
+        return url
+    parts = urllib.parse.urlsplit(url)
+    origin = f"{parts.scheme}://{parts.netloc}".lower()
+    if origin not in origins:
+        fail("host", f"{what} must be on the object store ({', '.join(sorted(origins))}), not {origin}")
+    return url
+
+
+def file_digest(path: Path) -> tuple[str, int]:
+    """The hex sha256 and size of a file, streamed."""
+    digest = hashlib.sha256()
+    size = 0
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            digest.update(chunk)
+            size += len(chunk)
+    return digest.hexdigest(), size
+
+
+def download_verified(url: str, sha256: str, dest: Path) -> Path:
+    """Fetch ``url`` into ``dest`` and refuse it unless its bytes hash to
+    ``sha256``; a mismatch leaves nothing behind."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    staging = dest.with_name(f".{dest.name}.{uuid.uuid4().hex}")
+    try:
+        try:
+            with (
+                urllib.request.urlopen(urllib.request.Request(url), timeout=TRANSFER_TIMEOUT_S) as r,
+                open(staging, "wb") as out,
+            ):
+                shutil.copyfileobj(r, out)
+        except Exception as error:  # noqa: BLE001 - name the stage in the message
+            fail("host", f"could not download the session export: {error}")
+        actual, _ = file_digest(staging)
+        if actual != sha256.lower():
+            fail("host", f"session export checksum mismatch: expected {sha256}, got {actual}")
+        os.replace(staging, dest)
+    finally:
+        staging.unlink(missing_ok=True)
+    return dest
+
+
+def upload_file(url: str, path: Path, sha256: str, size: int, content_type: str = EXPORT_CONTENT_TYPE) -> None:
+    """PUT a file to a presigned URL, sending exactly the headers the platform
+    signed for it: content type, length and the base64 sha256 the object store
+    verifies on receipt."""
+    headers = {
+        "Content-Type": content_type,
+        "Content-Length": str(size),
+        "x-amz-checksum-sha256": base64.b64encode(bytes.fromhex(sha256)).decode("ascii"),
+    }
+    with open(path, "rb") as fh:
+        request = urllib.request.Request(url, data=fh, method="PUT", headers=headers)
+        try:
+            with urllib.request.urlopen(request, timeout=TRANSFER_TIMEOUT_S) as response:
+                response.read()
+        except urllib.error.HTTPError as error:
+            fail("host", f"the export upload was refused: HTTP {error.code} {error.read()[:200]!r}")
+        except urllib.error.URLError as error:
+            fail("host", f"could not upload the export: {error.reason}")
+
+
+# --------------------------------------------------------------------------- #
+# Locating and reading a world tree.
+# --------------------------------------------------------------------------- #
+
+
+def world_tree(bundle: Path) -> Path:
+    """The gateway-world tree inside an extracted bundle. ``bench push`` packages
+    a schema world as its api bundle with the tree under ``server/world``; a bare
+    tree is its own root."""
+    nested = bundle / BUNDLED_WORLD
+    if (bundle / API_BUNDLE).is_file() and (nested / "schema/world.json").is_file():
+        return nested
+    if (bundle / "schema/world.json").is_file():
+        return bundle
+    fail(
+        "host",
+        f"{bundle} holds no schema world the host can open (no {BUNDLED_WORLD}/schema/world.json "
+        "nor schema/world.json); custom-server worlds run on the pod engine",
+    )
+    raise AssertionError  # fail() never returns
+
+
+def _scenario_dir(bundle: Path, tree: Path, task: str) -> Path | None:
+    """A task's scenario directory, checked at the bundle root first (where
+    ``build_api_bundle`` writes them) then in the tree."""
+    for root in (bundle / SCENARIOS / task, tree / SCENARIOS / task):
+        if (root / "scenario.toml").is_file():
+            return root
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# Per-version cache: bundle + snapshot + parsed spec, fetched once per host.
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class CachedVersion:
+    """One cached version, of either kind the host serves: an api world (a
+    connector ``spec`` and ``settings``, sessions cloned from ``snapshot``) or a
+    mock-tools world (``tools``: handlers, tasks and verifiers, sessions copied
+    from its template). Exactly one of ``spec`` and ``tools`` is set."""
+
+    version_id: str
+    bundle: Path
+    tree: Path
+    spec: Spec | None
+    settings: ApiSettings | None
+    snapshot: Path | None
+    #: The world's own code, imported once per version — only in a process
+    #: that runs handlers (a worker). None in the supervisor.
+    handlers: dict[str, Handler] | None = None
+    #: The version's prebuilt static ui, when its manifest declares one.
+    ui: UiSurface | None = None
+    #: A mock-tools version; None for an api world.
+    tools: ToolsVersion | None = None
+
+    @property
+    def needs_worker(self) -> bool:
+        """Whether the version runs world-authored code: a mock-tools world
+        always (its tools ARE handlers), an api world when it declares some."""
+        if self.tools is not None:
+            return True
+        return self.settings is not None and self.settings.handlers is not None
+
+    def router(self) -> Router:
+        """A fresh router per session: routes are compiled from the shared spec,
+        but the oauth2 tokens a world mints must stay that session's own."""
+        assert self.spec is not None and self.settings is not None
+        return Router(self.spec, self.settings)
+
+
+class VersionCache:
+    """Every world version this host has seen, on local disk. The first session
+    of a version pays for the download and extract; the rest clone its
+    snapshot. Nothing here is per session, so a hot version is cheap to serve
+    many times over."""
+
+    def __init__(self, root: Path, *, run_handlers: bool = False, max_bundle_mb: int = DEFAULT_MAX_BUNDLE_MB):
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+        #: Whether this process imports a version's ``handlers.py``. Off in the
+        #: supervisor, on in a version worker.
+        self.run_handlers = run_handlers
+        self.max_bundle_bytes = max_bundle_mb * (1 << 20)
+        self._lock = threading.Lock()
+        self._versions: dict[str, CachedVersion] = {}
+        #: One build at a time per version: the first open of a version does the
+        #: download, concurrent opens of the same version wait for it.
+        self._building: dict[str, threading.Lock] = {}
+
+    def ensure(
+        self,
+        version_id: str,
+        bundle_url: str,
+        snapshot: dict[str, str] | None,
+    ) -> CachedVersion:
+        with self._lock:
+            hit = self._versions.get(version_id)
+            if hit is not None:
+                return hit
+            building = self._building.setdefault(version_id, threading.Lock())
+        with building:
+            with self._lock:
+                hit = self._versions.get(version_id)
+                if hit is not None:
+                    return hit
+            try:
+                cached = self._build(version_id, bundle_url, snapshot)
+                with self._lock:
+                    self._versions[version_id] = cached
+                return cached
+            finally:
+                # Success or failure, the build slot is over: a failed build
+                # leaves nothing behind, and the next open of the version starts
+                # a fresh one.
+                with self._lock:
+                    self._building.pop(version_id, None)
+
+    def has(self, version_id: str) -> bool:
+        with self._lock:
+            return version_id in self._versions
+
+    def version_ids(self) -> list[str]:
+        with self._lock:
+            return sorted(self._versions)
+
+    def _build(self, version_id: str, bundle_url: str, snapshot: dict[str, str] | None) -> CachedVersion:
+        bundle = self.root / version_id / "bundle"
+        if not bundle.is_dir():
+            self._download(bundle_url, bundle)
+        if is_tools_bundle(bundle):
+            tools = load_tools_version(
+                bundle, self.root / version_id / "template.db", snapshot, run_handlers=self.run_handlers
+            )
+            return CachedVersion(
+                version_id=version_id,
+                bundle=bundle,
+                tree=bundle,
+                spec=None,
+                settings=None,
+                snapshot=None,
+                tools=tools,
+            )
+        tree = world_tree(bundle)
+        contract = check_bundle(tree)
+        if snapshot:
+            snapshots.fetch(tree, contract, snapshot["url"], snapshot["sha256"], snapshot["digest"])
+        spec = load_spec(tree)
+        settings = load_api_settings(tree, spec)
+        handlers = load_handlers(settings) if self.run_handlers and settings.handlers is not None else None
+        snap = snapshots.default_snapshot(tree)
+        if not snap.is_file():
+            fail(
+                "host",
+                f"version {version_id} has no compiled snapshot (db/state.sqlite); "
+                "publish a data snapshot or pin one on the version",
+            )
+        return CachedVersion(
+            version_id=version_id,
+            bundle=bundle,
+            tree=tree,
+            spec=spec,
+            settings=settings,
+            snapshot=snap,
+            handlers=handlers,
+            ui=load_ui_surface(bundle),
+        )
+
+    def _download(self, url: str, dest: Path) -> None:
+        """Fetch and extract into a sibling staging directory, then rename it into
+        place: ``dest`` exists only once it is complete, so a download that dies
+        halfway is never mistaken for a cached bundle on the next open."""
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        staging = dest.parent / f".{dest.name}.{uuid.uuid4().hex}"
+        tgz = staging.with_suffix(".tar.gz")
+        limit = self.max_bundle_bytes
+        try:
+            try:
+                with (
+                    urllib.request.urlopen(urllib.request.Request(url), timeout=TRANSFER_TIMEOUT_S) as r,
+                    open(tgz, "wb") as out,
+                ):
+                    copied = 0
+                    for chunk in iter(lambda: r.read(1 << 20), b""):
+                        copied += len(chunk)
+                        if copied > limit:
+                            raise ValueError(f"the bundle is larger than {limit} bytes")
+                        out.write(chunk)
+            except Exception as error:  # noqa: BLE001 - name the stage in the message
+                fail("host", f"could not download the bundle from {url}: {error}")
+            staging.mkdir()
+            with tarfile.open(tgz, "r:gz") as t:
+                members = t.getmembers()
+                if len(members) > MAX_BUNDLE_MEMBERS:
+                    fail("host", f"the bundle holds {len(members)} files, more than the {MAX_BUNDLE_MEMBERS} allowed")
+                extracted = sum(m.size for m in members)
+                if extracted > limit:
+                    fail("host", f"the bundle extracts to {extracted} bytes, more than the {limit} allowed")
+                safe_tar_extract(t, staging)
+            os.replace(staging, dest)
+        finally:
+            tgz.unlink(missing_ok=True)
+            shutil.rmtree(staging, ignore_errors=True)
+
+
+# --------------------------------------------------------------------------- #
+# Session state: the cached snapshot, cloned into this session's own file.
+# --------------------------------------------------------------------------- #
+
+
+class HostWorldState(WorldState):
+    """A session's world, opened by cloning the version's cached snapshot into a
+    file on the host's own volume — the reflink is the whole per-session cost.
+    Otherwise a plain :class:`WorldState`."""
+
+    def __init__(self, cached: CachedVersion, session_dir: Path):
+        self._session_dir = Path(session_dir)
+        self._session_dir.mkdir(parents=True, exist_ok=True)
+        self._cached = cached
+        self._database: Path | None = None
+        super().__init__(cached.tree)
+
+    @property
+    def session_dir(self) -> Path:
+        return self._session_dir
+
+    def _open(self, snapshot: Path | None, *, initial: bool = True) -> None:
+        # A snapshot start is a clone of the version's cached snapshot into this
+        # session's file; the legacy no-snapshot path stays as the base class runs it.
+        if snapshot is None:
+            return super()._open(None, initial=initial)
+        if self.store is not None:
+            self.store.close()
+        if self._database is not None:
+            self._database.unlink(missing_ok=True)
+        database = self._session_dir / f"{uuid.uuid4().hex}.db"
+        clone_file(snapshot, database)
+        self.store = snapshots.SQLiteStore.open(database, self.contract, audit=False)
+        self._database = database
+
+    def export(self, destination: Path) -> Path:
+        """The session's state as one sqlite file: the store's own audited
+        online backup, consistent while requests keep writing."""
+        assert self.store is not None
+        with self._lock:
+            return self.store.snapshot(destination)
+
+    def restore(self, source: Path) -> None:
+        """Continue from a file :meth:`export` wrote. The file is audited row by
+        row on open: it came over the network, not from this store."""
+        with self._lock:
+            if self.store is not None:
+                self.store.close()
+            if self._database is not None:
+                self._database.unlink(missing_ok=True)
+            database = self._session_dir / f"{uuid.uuid4().hex}.db"
+            clone_file(source, database)
+            self.store = snapshots.SQLiteStore.open(database, self.contract, audit=True)
+            self._database = database
+
+    def close(self) -> None:
+        super().close()
+        shutil.rmtree(self._session_dir, ignore_errors=True)
+
+
+@dataclass
+class Export:
+    """A session's state copied to a file on this host, hashed, waiting for the
+    platform to hand over the presigned URL it goes to."""
+
+    export_id: str
+    path: Path
+    sha256: str
+    bytes: int
+
+    def describe(self) -> dict:
+        return {
+            "exportId": self.export_id,
+            "sha256": self.sha256,
+            "bytes": self.bytes,
+            "contentType": EXPORT_CONTENT_TYPE,
+        }
+
+
+@dataclass
+class Session:
+    session_id: str
+    version_id: str
+    #: The bundled task (a ``scenarios/<task>`` of the version), or None for a
+    #: session opened on a task of its own.
+    task: str | None
+    #: The api world's connector spec; None for a mock-tools world, which has
+    #: no http surface (its data plane is 404, its tools are ``call``).
+    spec: Spec | None
+    token: str | None
+    bundle: Path
+    tree: Path
+    #: Unix time the lease runs out unless renewed.
+    lease_until: float
+    #: The world, when this process serves it. None for a session placed on a
+    #: worker, whose state lives in that process.
+    state: HostWorldState | None = None
+    app: WorldApp | None = None
+    #: The mock-tools world, when this process (a worker) serves one.
+    tools: ToolsWorld | None = None
+    #: The version worker serving this session, or None for in-process.
+    worker: Worker | None = None
+    #: The version's static ui, served by the supervisor for this session.
+    ui: UiSurface | None = None
+    #: The pool browser leased for this session: its relay's ``ws://ip:port``
+    #: and the token that relay answers to. None when the session has no
+    #: browser surface.
+    browser_url: str | None = None
+    browser_token: str | None = None
+    #: For an oauth2 world: the bearer this world minted for the host itself,
+    #: presented on behalf of a caller who authenticated with the session token.
+    grant: str | None = None
+    #: Requests inside the world right now. A session is only torn down once
+    #: this reaches zero, so a close or an expiry never pulls the database out
+    #: from under a handler mid-request.
+    inflight: int = 0
+    #: Set once the session has left the registry; the last request out closes
+    #: the state.
+    closing: bool = False
+    #: Unix time the session was opened; its session-seconds are counted on close.
+    opened_at: float = field(default_factory=time.time)
+    #: Unix time of the last request that used the world: a data-plane call or
+    #: a control operation (seed, reset, grade, call, state). A renewal or an
+    #: export is the platform looking, not the session working, and does not
+    #: move it. Reported on renew so the platform's idle clock follows traffic
+    #: that never passes through it.
+    touched_at: float = field(default_factory=time.time)
+    #: The last export taken and not yet uploaded, if any.
+    export: Export | None = None
+    #: Set when the session was opened from an export rather than the snapshot.
+    restored: bool = False
+    #: The task supplied at open, when the session has one instead of a
+    #: bundled task: its seed is applied after the clone, its grader answers
+    #: ``grade``, and it lives under ``<session>/task/`` (:mod:`tasks`).
+    task_spec: TaskSpec | None = None
+
+    @property
+    def task_key(self) -> tuple[str | None, dict | None]:
+        """What an open retry must match: the bundled name or the spec itself."""
+        return self.task, self.task_spec.raw if self.task_spec is not None else None
+
+    def renew(self, lease_s: float) -> None:
+        self.lease_until = time.time() + lease_s
+
+    @property
+    def seconds(self) -> float:
+        return max(0.0, time.time() - self.opened_at)
+
+
+def browser_lease(browser: dict[str, str] | None) -> tuple[str | None, str | None]:
+    """The ``browser`` field of an open request: the leased relay's ``url`` and
+    ``token``, both required when either is given, or ``(None, None)``."""
+    if not browser:
+        return None, None
+    url, token = browser.get("url"), browser.get("token")
+    if not isinstance(url, str) or not url.startswith("ws://") or not isinstance(token, str) or not token:
+        fail("host", "browser must be {url: 'ws://host:port', token: <relay token>}")
+        raise AssertionError  # fail() never returns
+    return url.rstrip("/"), token
+
+
+# --------------------------------------------------------------------------- #
+# The host: the session registry and the control operations.
+# --------------------------------------------------------------------------- #
+
+
+class WorldHost:
+    """The session registry and the control operations, in one of two roles:
+
+    * the **supervisor** (the deployed host): serves code-free worlds in
+      process and places worlds with handlers on its :class:`WorkerPool`;
+    * a **worker** (``run_handlers=True``, ``pinned_version=...``): serves one
+      version, handlers included, for its supervisor.
+    """
+
+    def __init__(
+        self,
+        cache_root: Path,
+        *,
+        lease_s: float = DEFAULT_LEASE_S,
+        advertise_url: str | None = None,
+        workers: WorkerPool | None = None,
+        versions_root: Path | None = None,
+        run_handlers: bool = False,
+        pinned_version: str | None = None,
+        limits: dict[str, int] | None = None,
+        max_sessions: int = DEFAULT_MAX_SESSIONS,
+        max_bundle_mb: int = DEFAULT_MAX_BUNDLE_MB,
+        object_store: frozenset[str] | None = None,
+    ):
+        #: Where every presigned URL the control plane hands this host must
+        #: point (bundle, snapshot, export upload, restore); None admits any.
+        self.object_store = object_store
+        self.cache = VersionCache(
+            versions_root or Path(cache_root) / "versions", run_handlers=run_handlers, max_bundle_mb=max_bundle_mb
+        )
+        self.sessions_root = Path(cache_root) / "sessions"
+        # Sessions live in this process; whatever a previous one left on disk is
+        # unreachable, so a start begins with an empty sessions tree.
+        shutil.rmtree(self.sessions_root, ignore_errors=True)
+        self.sessions_root.mkdir(parents=True, exist_ok=True)
+        self.lease_s = lease_s
+        #: The address the platform pins a session to, so control calls reach
+        #: this replica and not the Service's round-robin. None = one replica.
+        self.advertise_url = advertise_url
+        self.workers = workers
+        self.run_handlers = run_handlers
+        self.pinned_version = pinned_version
+        #: The rlimits this process runs under (a worker's), for ``/healthz``.
+        self.limits = limits
+        #: Sessions this host admits before ``open`` answers 503 and the
+        #: platform places elsewhere; the heartbeat advertises it as capacity.
+        self.max_sessions = max_sessions
+        #: Set on SIGTERM: no new sessions, existing ones served until they
+        #: close or the drain grace runs out.
+        self.draining = False
+        self.started_at = time.time()
+        self._lock = threading.Lock()
+        self._sessions: dict[str, Session] = {}
+        #: Ids of sessions being opened: each holds one of ``max_sessions`` from
+        #: the moment its open is admitted, so concurrent opens cannot all pass
+        #: the capacity check and land past the limit.
+        self._opening: set[str] = set()
+        #: Opens the platform closed before they finished: it gave up waiting
+        #: and told this host to forget the session, so the session is closed
+        #: the moment it exists rather than held until its lease runs out.
+        self._abandoned: set[str] = set()
+        #: Lifetime counts for ``/metrics``: opens, closes by reason, requests
+        #: by surface, session-seconds of closed sessions.
+        self._counters: Counter[str] = Counter()
+        self._session_seconds = 0.0
+
+    # -- lifecycle ---------------------------------------------------------- #
+
+    def open(
+        self,
+        session_id: str,
+        version_id: str,
+        bundle_url: str,
+        task: str | None,
+        token: str | None,
+        snapshot: dict[str, str] | None,
+        browser: dict[str, str] | None = None,
+        restore: dict[str, str] | None = None,
+        task_spec: Any = None,
+    ) -> dict:
+        """Open ``session_id`` on ``version_id``, either on the bundled ``task``
+        or on ``task_spec``, a session task of its own (:mod:`tasks`); exactly
+        one of the two."""
+        if self.pinned_version is not None and version_id != self.pinned_version:
+            fail("host", f"this worker serves version {self.pinned_version} only, not {version_id}")
+        if (task is None) == (task_spec is None):
+            fail("host", "an open names a bundled task or carries a task spec, one of the two")
+        if task is not None and not isinstance(task, str):
+            fail("host", "task is the bundled task's name")
+        spec = parse_task_spec(task_spec) if task_spec is not None else None
+        with self._lock:
+            existing = self._sessions.get(session_id)
+            if existing is None:
+                # A retry of an open this host already served is answered even
+                # while draining: refusing it would send the platform to open
+                # the same id elsewhere while this copy holds the live writes.
+                if self.draining:
+                    fail("draining", "this host is draining and takes no new sessions")
+                self._admit(session_id)
+        if existing is not None:
+            # The platform retried an open that already succeeded: the same
+            # session is the answer, never a rebuild that drops its writes.
+            wanted = (version_id, (task, spec.raw if spec is not None else None), token)
+            if (existing.version_id, existing.task_key, existing.token) != wanted:
+                fail("host", f"session {session_id} is already open as another version, task or token")
+            return self._describe(existing)
+        try:
+            described = self._open(session_id, version_id, bundle_url, task, spec, token, snapshot, browser, restore)
+        except Exception:
+            self.tally("open_failures")
+            with self._lock:
+                self._opening.discard(session_id)
+                self._abandoned.discard(session_id)
+            raise
+        with self._lock:
+            self._opening.discard(session_id)
+            abandoned = session_id in self._abandoned
+            self._abandoned.discard(session_id)
+        if abandoned:
+            self.close(session_id)
+            fail(UNKNOWN_SESSION, f"session {session_id} was closed while it opened")
+        return described
+
+    def _admit(self, session_id: str) -> None:
+        """Reserve one of this host's ``max_sessions`` for ``session_id`` while it
+        opens. Under ``_lock``."""
+        if session_id in self._opening:
+            fail("host", f"session {session_id} is being opened already")
+        if len(self._sessions) + len(self._opening) >= self.max_sessions:
+            fail("at_capacity", f"this host holds its {self.max_sessions} sessions; place elsewhere")
+        self._opening.add(session_id)
+
+    def _open(
+        self,
+        session_id: str,
+        version_id: str,
+        bundle_url: str,
+        task: str | None,
+        spec: TaskSpec | None,
+        token: str | None,
+        snapshot: dict[str, str] | None,
+        browser: dict[str, str] | None,
+        restore: dict[str, str] | None,
+    ) -> dict:
+        cached = self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
+        if spec is not None and (cached.tools is not None or cached.spec is None):
+            fail("host", "a session task needs an api world; a mock-tools world takes its bundled tasks only")
+        if cached.spec is not None:
+            unsupported = unsupported_auth(cached.spec)
+            if unsupported:
+                fail("host", unsupported)
+            if spec is not None:
+                self._check_task_tools(spec, cached.spec)
+        browser_url, browser_token = browser_lease(browser)
+        if cached.needs_worker and not self.run_handlers:
+            if self.workers is None:
+                fail(
+                    "host",
+                    f"version {version_id} runs world-authored code ({_code_of(cached)}); "
+                    "this host runs none in its process and has no version workers",
+                )
+            return self._open_on_worker(
+                cached, session_id, bundle_url, task, spec, token, browser_url, browser_token, restore
+            )
+        if cached.tools is not None:
+            assert task is not None
+            return self._open_tools(cached, cached.tools, session_id, task, token, restore)
+        assert cached.snapshot is not None and cached.spec is not None
+        state = HostWorldState(cached, self.sessions_root / session_id)
+        try:
+            if spec is not None:
+                self._check_task_entities(spec, state)
+                write_task_dir(spec, state.session_dir)
+                self._apply_task_seed(state, spec)
+            else:
+                assert task is not None
+                self._apply_scenario(cached, state, task)
+            restored = self._restore_into(restore, self.sessions_root / session_id, state.restore)
+        except Exception:
+            state.close()
+            raise
+        # ``handlers={}`` for a code-free world: WorldApp would otherwise import
+        # the module itself, and only a worker may do that.
+        app = WorldApp(
+            state,
+            cached.router(),
+            token,
+            handlers=cached.handlers or {},
+            allowed=frozenset(spec.tools) if spec is not None and spec.tools is not None else None,
+        )
+        session = Session(
+            session_id=session_id,
+            version_id=version_id,
+            task=task,
+            spec=cached.spec,
+            token=token,
+            bundle=cached.bundle,
+            tree=cached.tree,
+            lease_until=time.time() + self.lease_s,
+            state=state,
+            app=app,
+            ui=cached.ui,
+            browser_url=browser_url,
+            browser_token=browser_token,
+            restored=restored,
+            task_spec=spec,
+        )
+        if cached.spec.scheme == "oauth2":
+            # The host's own client-credentials grant, so a caller admitted by
+            # the session token is presented to the world as a granted client.
+            issued = app.router.issue_token(
+                {"grant_type": "client_credentials", "client_secret": token or ""},
+                token,
+            )
+            session.grant = issued["access_token"] if issued else None
+        self._register(session)
+        return self._describe(session)
+
+    def _open_tools(
+        self,
+        cached: CachedVersion,
+        tools: ToolsVersion,
+        session_id: str,
+        task: str,
+        token: str | None,
+        restore: dict[str, str] | None,
+    ) -> dict:
+        """A mock-tools session in this (worker) process: a copy of the version's
+        template, executed through its handlers. No http surface, so no ui and
+        no browser: the agent reaches it through ``call``."""
+        world = ToolsWorld(tools, self.sessions_root / session_id, task)
+        try:
+            restored = self._restore_into(restore, self.sessions_root / session_id, world.restore)
+        except Exception:
+            world.close()
+            raise
+        session = Session(
+            session_id=session_id,
+            version_id=cached.version_id,
+            task=task,
+            spec=None,
+            token=token,
+            bundle=cached.bundle,
+            tree=cached.tree,
+            lease_until=time.time() + self.lease_s,
+            tools=world,
+            restored=restored,
+        )
+        self._register(session)
+        return self._describe(session)
+
+    def _open_on_worker(
+        self,
+        cached: CachedVersion,
+        session_id: str,
+        bundle_url: str,
+        task: str | None,
+        spec: TaskSpec | None,
+        token: str | None,
+        browser_url: str | None,
+        browser_token: str | None,
+        restore: dict[str, str] | None,
+    ) -> dict:
+        """Place the session on the version's worker. The worker opens it from
+        the bundle this process already cached (no snapshot to fetch: the file
+        is on disk), and the supervisor records only where it went. The ui and
+        browser surfaces are the supervisor's own (static files, a tunnel), so
+        the worker hears nothing of them. An export to restore from is fetched
+        and verified here too, then handed to the worker as a local file.
+        A worker every one of whose peers holds sessions cannot be started
+        past the pool's memory budget: that is ``at_capacity``, and the
+        platform places the session on another replica."""
+        assert self.workers is not None
+        try:
+            worker = self.workers.get(cached.version_id)
+        except WorkerCapacity as error:
+            fail("at_capacity", str(error))
+        # The session is the worker's from here, so another version's open
+        # cannot stop this worker as session-less while it is being placed.
+        with self._lock:
+            worker.sessions.add(session_id)
+        source = None
+        try:
+            source = self._restore_source(restore, self._worker_session_dir(worker, session_id))
+            self._worker_control(
+                worker,
+                "POST",
+                "/__host/sessions",
+                {
+                    "sessionId": session_id,
+                    "versionId": cached.version_id,
+                    "bundleUrl": bundle_url,
+                    "task": task,
+                    "taskSpec": spec.raw if spec is not None else None,
+                    "token": token,
+                    "restore": {"path": str(source)} if source is not None else None,
+                },
+            )
+        except BaseException:
+            with self._lock:
+                worker.sessions.discard(session_id)
+                if not worker.sessions:
+                    worker.idle_since = time.time()
+            raise
+        finally:
+            if source is not None:
+                source.unlink(missing_ok=True)
+        session = Session(
+            session_id=session_id,
+            version_id=cached.version_id,
+            task=task,
+            spec=cached.spec,
+            token=token,
+            bundle=cached.bundle,
+            tree=cached.tree,
+            lease_until=time.time() + self.lease_s,
+            worker=worker,
+            ui=cached.ui,
+            browser_url=browser_url,
+            browser_token=browser_token,
+            restored=source is not None,
+            task_spec=spec,
+        )
+        self._register(session)
+        return self._describe(session)
+
+    def _worker_session_dir(self, worker: Worker, session_id: str) -> Path:
+        """Where a worker keeps a session's files: its own ``WorldHost`` runs
+        under ``workers/<version>`` of this host's cache root (:mod:`worker`)."""
+        assert self.workers is not None
+        return self.workers.root / "workers" / worker.version_id / "sessions" / session_id
+
+    def _restore_into(self, restore: dict[str, str] | None, session_dir: Path, load: Callable[[Path], None]) -> bool:
+        """Load the export ``restore`` names into a freshly opened world, then
+        drop the fetched file. False when there was nothing to restore."""
+        source = self._restore_source(restore, session_dir)
+        if source is None:
+            return False
+        try:
+            load(source)
+        finally:
+            source.unlink(missing_ok=True)
+        return True
+
+    def _restore_source(self, restore: dict[str, str] | None, session_dir: Path) -> Path | None:
+        """The export a session continues from, as a local file, or None for a
+        fresh session. The platform names it by ``{url, sha256}`` and the file is
+        fetched into the session's directory and verified; a supervisor names it
+        to its worker by ``{path}``, already verified, and only the supervisor
+        reaches a worker's control socket."""
+        if not restore:
+            return None
+        path = restore.get("path")
+        if path is not None:
+            if not self.run_handlers:
+                fail("host", "restore by path is a worker's; name the export by {url, sha256}")
+            source = Path(path)
+            if not source.is_file():
+                fail("host", f"restore file {path} is missing")
+            return source
+        url, sha256 = restore.get("url"), restore.get("sha256")
+        if not isinstance(url, str) or not isinstance(sha256, str) or len(sha256) != 64:
+            fail("host", "restore must be {url: <presigned export url>, sha256: <hex digest>}")
+            raise AssertionError  # fail() never returns
+        check_object_store_url(url, self.object_store, "restore.url")
+        return download_verified(url, sha256, session_dir / "restore.sqlite")
+
+    def _trusted_version(self, bundle_url: str, snapshot: dict[str, str] | None) -> tuple[str, dict[str, str] | None]:
+        check_object_store_url(bundle_url, self.object_store, "bundleUrl")
+        if snapshot:
+            check_object_store_url(snapshot.get("url"), self.object_store, "snapshot.url")
+        return bundle_url, snapshot
+
+    def _register(self, session: Session) -> None:
+        with self._lock:
+            replaced = self._retire(self._sessions.pop(session.session_id, None))
+            self._sessions[session.session_id] = session
+            self._counters["opened"] += 1
+        if replaced is not None:
+            self._finish(replaced, reason="replaced")
+
+    def _describe(self, session: Session) -> dict:
+        return {
+            "sessionId": session.session_id,
+            "versionId": session.version_id,
+            "task": session.task,
+            "taskName": session.task if session.task_spec is None else session.task_spec.name,
+            "taskSource": "bundled" if session.task_spec is None else "inline",
+            "tools": (
+                list(session.task_spec.tools)
+                if session.task_spec is not None and session.task_spec.tools is not None
+                else None
+            ),
+            "ready": True,
+            "hostUrl": self.advertise_url,
+            "leaseSeconds": self.lease_s,
+            "leaseUntil": session.lease_until,
+            "workerPid": session.worker.pid if session.worker is not None else None,
+            "ui": {"entry": session.ui.entry, "apiPath": session.ui.api_path} if session.ui is not None else None,
+            "browser": session.browser_url is not None,
+            "restored": session.restored,
+            "openedAt": session.opened_at,
+            "sessionSeconds": session.seconds,
+            "touchedAt": session.touched_at,
+        }
+
+    def close(self, session_id: str) -> dict:
+        with self._lock:
+            session = self._sessions.pop(session_id, None)
+            idle = self._retire(session)
+            if session is None and session_id in self._opening:
+                self._abandoned.add(session_id)
+        if idle is not None:
+            self._finish(idle, reason="closed")
+        if session is None:
+            return {"closed": True, "openedAt": None, "sessionSeconds": 0.0}
+        return {"closed": True, "openedAt": session.opened_at, "sessionSeconds": session.seconds}
+
+    # -- durability: a session's state as a file the platform keeps ---------- #
+
+    def export(self, session_id: str, known_sha256: str | None = None) -> dict:
+        """Copy the session's state to a file on this host and hash it. The copy
+        is consistent (sqlite's online backup under the store's lock) and waits
+        for :meth:`upload_export`; taking a new one discards the last. A copy
+        that hashes to ``known_sha256`` (the platform's last export of the
+        session) is thrown away and reported ``unchanged``: nothing to upload."""
+        with self.using(session_id, touch=False) as session:
+            if session.worker is not None:
+                answer = self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/export", {})
+                path = self._worker_export_path(session, answer)
+            else:
+                exports = self.sessions_root / session_id / "exports"
+                shutil.rmtree(exports, ignore_errors=True)
+                path = exports / f"{uuid.uuid4().hex}.sqlite"
+                if session.tools is not None:
+                    session.tools.export(path)
+                else:
+                    assert session.state is not None
+                    session.state.export(path)
+            sha256, size = file_digest(path)
+            if known_sha256 is not None and sha256 == known_sha256:
+                path.unlink(missing_ok=True)
+                with self._lock:
+                    session.export = None
+                    self._counters["exports_unchanged"] += 1
+                return {"exportId": None, "sha256": sha256, "bytes": size, "unchanged": True}
+            export = Export(export_id=path.stem, path=path, sha256=sha256, bytes=size)
+            with self._lock:
+                session.export = export
+                self._counters["exports"] += 1
+        described = export.describe()
+        if self.run_handlers:
+            described["path"] = str(path)  # for the supervisor, which uploads on the worker's behalf
+        return described
+
+    def _worker_export_path(self, session: Session, answer: dict) -> Path:
+        """The file a worker's export landed in, admitted only from inside that
+        worker's directory for this session: the worker runs tenant code, so
+        what it names is checked, and the bytes are hashed here, not trusted."""
+        assert session.worker is not None
+        exports = self._worker_session_dir(session.worker, session.session_id) / "exports"
+        path = Path(str(answer.get("path") or ""))
+        try:
+            resolved = path.resolve(strict=True)
+            resolved.relative_to(exports.resolve())
+        except (OSError, ValueError):
+            fail("host", f"the worker's export is not where a worker's exports go: {path}")
+            raise AssertionError  # fail() never returns
+        return resolved
+
+    def upload_export(self, session_id: str, export_id: str, url: str) -> dict:
+        """PUT the export :meth:`export` took to the presigned URL the platform
+        signed for its hash and size; the local copy goes once it is up."""
+        check_object_store_url(url, self.object_store, "url")
+        with self.using(session_id, touch=False) as session:
+            export = session.export
+            if export is None or export.export_id != export_id:
+                fail("host", f"no export {export_id} for session {session_id}; take one first")
+                raise AssertionError  # fail() never returns
+            upload_file(url, export.path, export.sha256, export.bytes)
+            export.path.unlink(missing_ok=True)
+            with self._lock:
+                session.export = None
+                self._counters["exports_uploaded"] += 1
+        return {"uploaded": True, **export.describe()}
+
+    def renew(self, session_id: str) -> dict:
+        with self.using(session_id, touch=False) as session:
+            return self._describe(session)
+
+    def expire_leases(self, now: float | None = None) -> list[str]:
+        """Close every session whose lease has run out; returns their ids. The
+        check and the removal happen under one lock, so a renewal that lands
+        in between keeps its session, and a session with a request in flight
+        is left for the next sweep (the request renewed it anyway)."""
+        now = time.time() if now is None else now
+        with self._lock:
+            expired = [s for s in self._sessions.values() if s.lease_until <= now and s.inflight == 0]
+            for session in expired:
+                del self._sessions[session.session_id]
+                self._retire(session)
+        for session in expired:
+            self._finish(session, reason="expired")
+        return [s.session_id for s in expired]
+
+    def _retire(self, session: Session | None) -> Session | None:
+        """Mark a session that has left the registry; returns it when nobody is
+        inside it, so the caller closes the state now. Otherwise the last
+        request out does (see :meth:`_release`). Call under the lock."""
+        if session is None:
+            return None
+        session.closing = True
+        return session if session.inflight == 0 else None
+
+    def _finish(self, session: Session, *, reason: str = "closed") -> None:
+        """Free a session that has left the registry and has nobody inside it:
+        close its state here, or tell its worker to."""
+        with self._lock:
+            self._counters[f"closed.{reason}"] += 1
+            self._session_seconds += session.seconds
+        if session.worker is None:
+            if session.tools is not None:
+                session.tools.close()
+                return
+            assert session.state is not None
+            session.state.close()
+            return
+        worker = session.worker
+        with self._lock:
+            worker.sessions.discard(session.session_id)
+            if not worker.sessions:
+                worker.idle_since = time.time()
+        try:
+            self._worker_control(worker, "DELETE", f"/__host/sessions/{session.session_id}", None)
+        except (WorkerGone, ContractError):
+            pass  # the worker is gone, or already forgot it: either way the session is over
+
+    def _worker_control(self, worker: Worker, method: str, path: str, body: dict | None) -> dict:
+        """One control call to a worker, its answer as this host would give it:
+        the worker's refusal is re-raised as ours, and a worker that has died
+        takes every session it held with it."""
+        raw = json.dumps(body).encode("utf-8") if body is not None else b""
+        try:
+            status, _, payload = worker.request(method, path, {"content-type": "application/json"}, raw, control=True)
+        except WorkerGone:
+            self.lose_worker(worker)
+            raise
+        answer = json.loads(payload or b"null")
+        if status != 200:
+            detail = answer if isinstance(answer, dict) else {}
+            fail(str(detail.get("error") or "host"), str(detail.get("detail") or answer))
+        return answer if isinstance(answer, dict) else {"result": answer}
+
+    def lose_worker(self, worker: Worker) -> list[str]:
+        """A worker exited: forget it and every session it held. Returns the
+        session ids, which are now gone from this host (the platform learns of
+        it on the next renew)."""
+        if self.workers is not None:
+            self.workers.drop(worker.version_id)
+        with self._lock:
+            lost = [sid for sid, s in self._sessions.items() if s.worker is worker]
+            for sid in lost:
+                session = self._sessions.pop(sid)
+                session.closing = True
+                self._counters["closed.lost"] += 1
+                self._session_seconds += session.seconds
+            worker.sessions.clear()
+        return lost
+
+    def reap_workers(self) -> list[str]:
+        """Stop version workers that have had no session for a while."""
+        return self.workers.reap_idle() if self.workers is not None else []
+
+    def session_count(self) -> int:
+        with self._lock:
+            return len(self._sessions)
+
+    def worker_count(self) -> int:
+        return len(self.workers._workers) if self.workers is not None else 0
+
+    # -- fleet: warming, draining, what the platform and prometheus see ------- #
+
+    def warm(self, version_id: str, bundle_url: str, snapshot: dict[str, str] | None) -> dict:
+        """Cache a version before any session asks for it, so the first open
+        pays nothing. Idempotent: a version already here is reported, not
+        rebuilt."""
+        already = self.cache.has(version_id)
+        if not already:
+            self.cache.ensure(version_id, *self._trusted_version(bundle_url, snapshot))
+        return {"versionId": version_id, "cached": True, "alreadyCached": already}
+
+    def drain(self) -> None:
+        """Stop taking sessions; the ones here are served until they close."""
+        self.draining = True
+
+    def tally(self, key: str) -> None:
+        with self._lock:
+            self._counters[key] += 1
+
+    def stats(self) -> dict:
+        """What this host is and holds, for the heartbeat and ``/__host/stats``:
+        the placement inputs (address, load, capacity, draining, which versions
+        are already cached) plus the lifetime counters."""
+        with self._lock:
+            sessions = len(self._sessions)
+            versions_in_use = sorted({s.version_id for s in self._sessions.values()})
+            counters = dict(self._counters)
+            session_seconds = self._session_seconds
+        return {
+            "hostUrl": self.advertise_url,
+            "sessions": sessions,
+            "capacity": self.max_sessions,
+            "draining": self.draining,
+            "workers": self.worker_count(),
+            "versions": self.cache.version_ids(),
+            "versionsInUse": versions_in_use,
+            "uptimeSeconds": time.time() - self.started_at,
+            "counters": counters,
+            "sessionSeconds": session_seconds,
+            "pid": os.getpid(),
+            "limits": self.limits,
+        }
+
+    def metrics_text(self) -> str:
+        """The prometheus exposition of :meth:`stats`. ``worlds_host_sessions``
+        is the number the fleet scales on (sessions per host, not cpu)."""
+        stats = self.stats()
+        counters: dict[str, int] = stats["counters"]
+        lines = [
+            "# TYPE worlds_host_sessions gauge",
+            f"worlds_host_sessions {stats['sessions']}",
+            "# TYPE worlds_host_capacity gauge",
+            f"worlds_host_capacity {stats['capacity']}",
+            "# TYPE worlds_host_draining gauge",
+            f"worlds_host_draining {int(stats['draining'])}",
+            "# TYPE worlds_host_workers gauge",
+            f"worlds_host_workers {stats['workers']}",
+            "# TYPE worlds_host_versions_cached gauge",
+            f"worlds_host_versions_cached {len(stats['versions'])}",
+            "# TYPE worlds_host_uptime_seconds gauge",
+            f"worlds_host_uptime_seconds {stats['uptimeSeconds']:.0f}",
+            "# TYPE worlds_host_sessions_opened_total counter",
+            f"worlds_host_sessions_opened_total {counters.get('opened', 0)}",
+            "# TYPE worlds_host_open_failures_total counter",
+            f"worlds_host_open_failures_total {counters.get('open_failures', 0)}",
+            "# TYPE worlds_host_session_seconds_total counter",
+            f"worlds_host_session_seconds_total {stats['sessionSeconds']:.0f}",
+            "# TYPE worlds_host_exports_total counter",
+            f"worlds_host_exports_total {counters.get('exports', 0)}",
+            "# TYPE worlds_host_exports_uploaded_total counter",
+            f"worlds_host_exports_uploaded_total {counters.get('exports_uploaded', 0)}",
+            "# TYPE worlds_host_sessions_closed_total counter",
+        ]
+        for reason in ("closed", "expired", "lost", "replaced"):
+            lines.append(
+                f'worlds_host_sessions_closed_total{{reason="{reason}"}} {counters.get(f"closed.{reason}", 0)}'
+            )
+        lines.append("# TYPE worlds_host_requests_total counter")
+        for surface in ("api", "ui", "browser", "proxied"):
+            lines.append(f'worlds_host_requests_total{{surface="{surface}"}} {counters.get(f"requests.{surface}", 0)}')
+        return "\n".join(lines) + "\n"
+
+    def _apply_scenario(self, cached: CachedVersion, state: HostWorldState, task: str) -> None:
+        """Start the session in its task's scenario. The compiled snapshot the
+        session is cloned from IS the base state, so a scenario with no seed
+        overlay (the synthesized ``default``) needs nothing; one with an overlay
+        applies it on top of the pinned snapshot the way the runner does."""
+        scenario = _scenario_dir(cached.bundle, cached.tree, task)
+        if scenario is None:
+            if task in state.scenarios():
+                state.apply_scenario(task)  # a tree-authored scenario
+                return
+            fail(
+                "host",
+                f"no scenario '{task}' in this world; it has {', '.join(state.scenarios()) or 'default'}",
+            )
+        overlay = snapshots.scenario_overlay(scenario)
+        if not overlay:
+            return  # base state; the cloned snapshot already holds it
+        digest = state.digest
+        if digest is None:
+            fail("host", "a scenario overlay needs a compiled snapshot to apply against")
+        state.seed({"base": digest, "rows": overlay, "mode": "replace"})
+
+    @staticmethod
+    def _check_task_entities(spec: TaskSpec, state: HostWorldState) -> None:
+        """A task is refused for a world that does not define every entity it
+        names. The seed would fail on its own; an assertion over an unknown
+        entity would not, selecting no rows, so `absent` or `count: eq 0`
+        checks would pass on a typo and grade a task that can never be graded."""
+        unknown = unknown_task_entities(spec, state.contract.entities)
+        if unknown:
+            defined = ", ".join(sorted(state.contract.entities)) or "none"
+            fail(
+                "task",
+                f"the task names {', '.join(unknown)}, which this world does not define; its entities are {defined}",
+                "/task",
+            )
+
+    @staticmethod
+    def _check_task_tools(spec: TaskSpec, world: Spec) -> None:
+        """A task's allow-list names tools the world serves, every one of them:
+        a misspelt name would narrow the list without anyone noticing."""
+        unknown = unknown_task_tools(spec, world.operations)
+        if unknown:
+            served = ", ".join(sorted(world.operations)) or "none"
+            fail(
+                "task",
+                f"the task allows {', '.join(unknown)}, which this world does not serve; its tools are {served}",
+                "/task/tools",
+            )
+
+    def _apply_task_seed(self, state: HostWorldState, spec: TaskSpec) -> None:
+        """Start the session in its own task's state: the version's snapshot
+        (already cloned) with the task's rows on top, as a session seed lands
+        them. A task without a seed starts on the base data."""
+        if spec.seed is None:
+            return
+        state.seed_live(spec.seed["rows"], spec.seed["mode"])
+
+    @contextmanager
+    def using(self, session_id: str, *, touch: bool = True) -> Iterator[Session]:
+        """The session for the duration of one request: its lease renewed (any
+        traffic keeps it alive), its ``touched_at`` moved unless ``touch`` is
+        off (a renewal or export observing the session, not using it), and its
+        teardown held off until the block ends."""
+        with self._lock:
+            session = self._sessions.get(session_id)
+            if session is not None:
+                session.renew(self.lease_s)
+                if touch:
+                    session.touched_at = time.time()
+                session.inflight += 1
+        if session is None:
+            fail(UNKNOWN_SESSION, f"no session {session_id} on this host")
+            raise AssertionError  # fail() never returns
+        try:
+            yield session
+        finally:
+            self._release(session)
+
+    def _release(self, session: Session) -> None:
+        with self._lock:
+            session.inflight -= 1
+            last_out = session.closing and session.inflight == 0
+        if last_out:
+            self._finish(session)
+
+    def owns(self, session_id: str) -> bool:
+        with self._lock:
+            return session_id in self._sessions
+
+    # -- control operations (the platform's rendezvous, run in-process) ----- #
+
+    def reset(self, session_id: str) -> dict:
+        with self.using(session_id) as session:
+            if session.worker is not None:
+                return self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/reset", {})
+            if session.tools is not None:
+                return session.tools.reset()
+            assert session.state is not None
+            # Back to the task's starting state: re-clone the snapshot, then
+            # re-apply the task's seed or the scenario overlay if it had one.
+            session.state.reset()
+            if session.task_spec is not None:
+                self._apply_task_seed(session.state, session.task_spec)
+            else:
+                assert session.task is not None
+                self._apply_scenario(self.cache._versions[session.version_id], session.state, session.task)
+        return {"reset": True}
+
+    def seed(self, session_id: str, args: dict) -> dict:
+        rows = args.get("rows")
+        if not isinstance(rows, dict):
+            fail("host", "seed needs args.rows as {entity: [row, ...]}")
+        mode = args.get("mode", "append")
+        with self.using(session_id) as session:
+            if session.worker is not None:
+                return self._worker_control(
+                    session.worker, "POST", f"/__host/sessions/{session_id}/seed", {"args": args}
+                )
+            if session.tools is not None:
+                return session.tools.seed(args)
+            assert session.state is not None
+            # Onto the live state, the way the runner's session seed lands: an
+            # append upserts by key, a replace swaps the named entities.
+            session.state.seed_live(rows, mode)
+            return {
+                "seeded": sum(len(v) for v in rows.values()),
+                "mode": mode,
+                "entity_counts": {
+                    entity: len(session.state.rows(entity))
+                    for entity in rows
+                    if entity in session.state.contract.entities
+                },
+            }
+
+    def state(self, session_id: str) -> dict:
+        with self.using(session_id) as session:
+            if session.worker is not None:
+                return self._worker_control(session.worker, "GET", f"/__host/sessions/{session_id}/state", None)
+            if session.tools is not None:
+                return session.tools.state()
+            assert session.state is not None
+            return {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
+
+    def grade(self, session_id: str) -> dict:
+        with self.using(session_id) as session:
+            if session.worker is not None:
+                return self._worker_control(session.worker, "POST", f"/__host/sessions/{session_id}/grade", {})
+            if session.tools is not None:
+                return session.tools.grade()
+            return self._grade(session)
+
+    def _grade(self, session: Session) -> dict:
+        assert session.state is not None
+        state = {**session.state.dump(), "snapshot": session.state.describe_snapshot()}
+        spec = session.task_spec
+        if spec is not None:
+            # The session's own task: its assertions are evaluated here, pure
+            # Python over the dump; its verify.py runs as a bundled one would.
+            if spec.grader is None:
+                return {"reward": None, "rewards": {}}
+            if spec.grader["kind"] == "assertions":
+                return evaluate_assertions(spec.grader["checks"], state)
+            if spec.graded_on_platform:
+                # A rubric is an LLM judge's brief. The host has no model, no
+                # key and no business calling one from a tenant's session: the
+                # platform grades it from the state and the calls log.
+                return {"reward": None, "rewards": {}, "pending": True, "grader": "rubric"}
+            verify = session.state.session_dir / "task" / "checks" / "verify.py"
+            return self._run_verifier(session, verify, state, spec.grader.get("timeoutSeconds") or VERIFY_TIMEOUT_S)
+        assert session.task is not None
+        scenario = _scenario_dir(session.bundle, session.tree, session.task)
+        verify = scenario / "checks" / "verify.py" if scenario else None
+        if verify is None or not verify.is_file():
+            return {"reward": None, "rewards": {}}
+        return self._run_verifier(session, verify, state, VERIFY_TIMEOUT_S)
+
+    def _run_verifier(self, session: Session, verify: Path, state: dict, timeout_s: float) -> dict:
+        assert session.state is not None
+        if not verify.is_file():
+            fail("host", f"the task's verify.py is missing at {verify}")
+        dump = json.dumps(state)
+        # The verifier is the world's code: it runs confined like a worker, with
+        # a scrubbed environment, and is told the state on stdin. It sees no
+        # secret of this process, be it the host's or a worker's.
+        home = session.state.session_dir / "verify"
+        home.mkdir(parents=True, exist_ok=True)
+        try:
+            proc = subprocess.run(
+                confined_command(verify),
+                input=dump,
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=timeout_s,
+                cwd=str(verify.parent),
+                env=verifier_environment(home=home),
+            )
+        except subprocess.TimeoutExpired:
+            fail("host", f"verify.py timed out after {timeout_s:g}s")
+        if proc.returncode != 0:
+            fail(
+                "host",
+                f"verify.py exited {proc.returncode}: {proc.stderr.strip()[-800:]}",
+            )
+        try:
+            rewards = json.loads(proc.stdout.strip().splitlines()[-1])
+        except (json.JSONDecodeError, IndexError):
+            fail(
+                "host",
+                f"verify.py printed no rewards JSON: {proc.stdout.strip()[-400:]}",
+            )
+        if not isinstance(rewards, dict):
+            fail("host", "verify.py rewards output is not an object")
+        # The runner's shape (``api_runner.grade_scenario``): the scalar under
+        # ``reward``, every other key the verifier printed under ``rewards``.
+        reward = rewards.get("reward")
+        return {
+            "reward": float(reward) if isinstance(reward, (int, float)) else None,
+            "rewards": {
+                k: (float(v) if isinstance(v, (int, float)) else None) for k, v in rewards.items() if k != "reward"
+            },
+        }
+
+    def call(self, session_id: str, tool: str, args: dict) -> dict:
+        """Invoke one of the world's vendor routes by operation name, in process.
+        The arg shape mirrors the runner's ``execute_route``: ``path``/``query``/
+        ``body``, or leftover top-level keys as the body."""
+        with self.using(session_id) as session:
+            if session.worker is not None:
+                return self._worker_control(
+                    session.worker,
+                    "POST",
+                    f"/__host/sessions/{session_id}/call",
+                    {"tool": tool, "args": args},
+                )
+            if session.tools is not None:
+                return session.tools.call(tool, args)
+            return self._call(session, tool, args)
+
+    def _call(self, session: Session, tool: str, args: dict) -> dict:
+        assert session.app is not None and session.spec is not None
+        operation = session.spec.operations.get(tool)
+        if operation is None:
+            known = ", ".join(sorted(session.spec.operations)) or "(none)"
+            fail("host", f"unknown tool '{tool}'; this world serves: {known}")
+        if session.task_spec is not None and not session.task_spec.allows_tool(tool):
+            allowed = ", ".join(session.task_spec.tools or ())
+            fail("tool_not_allowed", f"tool '{tool}' is not allowed by this session's task; it allows: {allowed}")
+        path = operation.path  # type: ignore[union-attr]
+        path_params = args.get("path") if isinstance(args.get("path"), dict) else {}
+        for key, value in (path_params or {}).items():
+            path = path.replace("{" + str(key) + "}", urllib.parse.quote(str(value), safe=""))
+        query = args.get("query") if isinstance(args.get("query"), dict) else {}
+        if query:
+            path = f"{path}?" + urllib.parse.urlencode(query)
+        body = args.get("body") if isinstance(args.get("body"), dict) else None
+        if body is None:
+            leftovers = {k: v for k, v in args.items() if k not in ("path", "query", "body")}
+            body = leftovers or None
+        method = operation.method  # type: ignore[union-attr]
+        raw = json.dumps(body).encode("utf-8") if body is not None and method != "GET" else b""
+        base = urllib.parse.urlsplit(session.spec.base_url).path.rstrip("/")
+        headers, credential_query = world_credential(session)
+        target = with_query(f"{base}{path}", credential_query)
+        status, answer, _ = session.app.handle(method, target, headers, raw, "127.0.0.1")
+        return {"status": status, "body": answer}
+
+
+# --------------------------------------------------------------------------- #
+# The HTTP server: control plane by secret, data plane by Host header.
+# --------------------------------------------------------------------------- #
+
+
+def public_host(host_header: str | None, worlds_domain: str) -> bool:
+    """True when ``Host`` names something under the worlds domain: a session,
+    or any other label the wildcard ALB forwarded. That is the public side.
+    Prometheus, the kubelet and the ALB health check address the pod itself
+    (``ip:port``), which is not."""
+    name = (host_header or "").split(":")[0].rstrip(".").lower()
+    domain = worlds_domain.rstrip(".").lower()
+    return bool(domain) and (name == domain or name.endswith("." + domain))
+
+
+def session_from_host(host_header: str | None) -> tuple[str, str] | None:
+    """``w-<sid>-api.<domain>`` / ``w-<sid>.<domain>`` → (session id, surface).
+    Returns None when the host does not name a session."""
+    if not host_header:
+        return None
+    label = host_header.split(":")[0].split(".")[0]
+    if not label.startswith("w-"):
+        return None
+    rest = label[2:]
+    if rest.endswith("-api"):
+        return rest[: -len("-api")], "api"
+    if rest.endswith("-cdp"):
+        return rest[: -len("-cdp")], "browser"
+    return rest, "ui"
+
+
+#: Auth schemes the host can present a world's own credential for. Everything
+#: in ``connector.SCHEMES`` is here; the list is explicit so a new scheme is
+#: refused at open rather than admitted with no credential.
+SUPPORTED_AUTH_SCHEMES = ("none", "header", "bearer", "basic", "query", "oauth2")
+
+#: A caller that satisfies the host's session-token gate has already been
+#: authorized; the host then presents the credential the WORLD itself expects,
+#: so the emulated vendor's own auth check passes. The session token is that
+#: credential; with no session token a sentinel satisfies the world's
+#: non-empty check (the host's gate is the real access control either way).
+_WORLD_AUTH_SENTINEL = "gateway-session"
+
+
+def _code_of(cached: CachedVersion) -> str:
+    """What world-authored code a version runs, for a refusal message."""
+    if cached.tools is not None:
+        return "mock-tools handlers"
+    assert cached.settings is not None and cached.settings.handlers is not None
+    return f"api handlers module {cached.settings.handlers.name}"
+
+
+def unsupported_auth(spec: Spec) -> str | None:
+    if spec.scheme in SUPPORTED_AUTH_SCHEMES:
+        return None
+    return (
+        f"the host cannot present auth.scheme '{spec.scheme}' to a world; it serves {', '.join(SUPPORTED_AUTH_SCHEMES)}"
+    )
+
+
+def world_credential(session: Session) -> tuple[dict[str, str], dict[str, str]]:
+    """(headers, query) carrying the world's own credential for this session.
+    A ``query`` world reads its key from the query string, so that half is a
+    query parameter; an ``oauth2`` world accepts only a bearer it minted, so
+    the host presents its own grant."""
+    spec = session.spec
+    assert spec is not None, "a mock-tools session has no http surface to present a credential on"
+    presented = session.token or _WORLD_AUTH_SENTINEL
+    if spec.scheme == "none":
+        return {}, {}
+    if spec.scheme == "header":
+        return {(spec.auth_name or "x-api-key").lower(): presented}, {}
+    if spec.scheme == "bearer":
+        return {"authorization": f"Bearer {presented}"}, {}
+    if spec.scheme == "oauth2":
+        return {"authorization": f"Bearer {session.grant or ''}"}, {}
+    if spec.scheme == "basic":
+        import base64 as _b64
+
+        return {"authorization": "Basic " + _b64.b64encode(f"{presented}:".encode()).decode()}, {}
+    if spec.scheme == "query":
+        return {}, {spec.auth_name or "api_key": presented}
+    fail("host", unsupported_auth(spec) or spec.scheme)
+    raise AssertionError  # fail() never returns
+
+
+def with_query(target: str, extra: dict[str, str]) -> str:
+    """``target`` with ``extra`` merged into its query string."""
+    if not extra:
+        return target
+    url = urllib.parse.urlsplit(target)
+    query = {k: v[0] for k, v in urllib.parse.parse_qs(url.query, keep_blank_values=True).items()}
+    query.update(extra)
+    return urllib.parse.urlunsplit(url._replace(query=urllib.parse.urlencode(query)))
+
+
+def bearer_of(headers: dict[str, str]) -> str | None:
+    auth = headers.get("authorization", "")
+    return auth[7:] if auth.lower().startswith("bearer ") else None
+
+
+def vendor_shaped_token(spec: Spec, headers: dict[str, str], token: str) -> bool:
+    """Whether the request carries ``token`` the way the world's own auth scheme
+    carries a credential: the declared header for ``header``, the user of a
+    Basic authorization for ``basic``. A ``query`` scheme is not honoured here (a
+    token in the URL outlives the request in logs); ``bearer`` is the gate's
+    own shape and ``oauth2`` has its grant."""
+    if spec.scheme == "header":
+        presented = headers.get((spec.auth_name or "x-api-key").lower())
+        return presented is not None and hmac.compare_digest(presented, token)
+    if spec.scheme == "basic":
+        auth = headers.get("authorization", "")
+        if not auth.lower().startswith("basic "):
+            return False
+        import base64 as _b64
+
+        try:
+            decoded = _b64.b64decode(auth[6:].strip().encode("ascii"), validate=True).decode("utf-8")
+        except (ValueError, UnicodeDecodeError):
+            return False
+        user = decoded.split(":", 1)[0]
+        return hmac.compare_digest(user, token)
+    return False
+
+
+def admits(session: Session, path: str, headers: dict[str, str]) -> str | None:
+    """How the host's gate admits a data-plane request, or None to refuse.
+
+    ``"session"``: the caller presented the session token as a bearer and the
+    host will present the world's credential for it. Only the header counts: a
+    token in the URL would outlive the request in access logs and referrers.
+    ``"world"``: an oauth2 caller doing the vendor's own dance — the grant
+    request (the world checks ``client_secret`` against the session token) or
+    a bearer this session's world minted — whose headers pass through as sent.
+    """
+    if session.token is None:
+        return "session"
+    bearer = bearer_of(headers)
+    if bearer is not None and hmac.compare_digest(bearer, session.token):
+        return "session"
+    if session.spec is not None and vendor_shaped_token(session.spec, headers, session.token):
+        # The vendor's own wire shape carrying the session token: a client
+        # written against the real vendor (`x-api-key: …`, a Basic user) works
+        # unchanged with the session token as its key. The same secret as the
+        # bearer, in the header the world declares — never in the URL.
+        return "session"
+    if session.spec is not None and session.spec.scheme == "oauth2":
+        if session.app is None:
+            return "world"  # the world's tokens live in its worker, which runs this same gate  # the world's tokens live in its worker, which runs this same gate
+        token_path = session.app.settings.token_path
+        if token_path and session.app._strip(path) == token_path:
+            return "world"
+        if bearer is not None and session.app.router.authorized(headers, {}, session.token):
+            return "world"
+    return None
+
+
+class OwnerLookup(Protocol):
+    """Which host owns a session this replica does not: its control-plane
+    URL, or None for a closed or unknown one. ``fresh`` bypasses whatever the
+    lookup remembers, for a caller that has just found the remembered owner
+    dead."""
+
+    def __call__(self, sid: str, *, fresh: bool = False) -> str | None: ...
+
+
+def platform_owner_lookup(platform_url: str, secret: str | None, self_url: str | None) -> OwnerLookup:
+    """Ask the platform which host owns a session the caller reached us for.
+    ``GET /api/public/world-sessions/{sid}/host`` is host-secret authenticated
+    and answers ``{hostUrl}``; a 404 is a closed or unknown session. Answers are
+    held briefly so a busy session does not cost one platform call per request.
+    Our own address answers None: a session we do not hold but the platform
+    says is ours is gone, not one hop away."""
+    cache: dict[str, tuple[float, str | None]] = {}
+    lock = threading.Lock()
+    base = platform_url.rstrip("/")
+
+    def lookup(sid: str, *, fresh: bool = False) -> str | None:
+        now = time.time()
+        if not fresh:
+            with lock:
+                hit = cache.get(sid)
+                if hit and hit[0] > now:
+                    return hit[1]
+        owner: str | None = None
+        req = urllib.request.Request(
+            f"{base}/api/public/world-sessions/{urllib.parse.quote(sid, safe='')}/host",
+            headers={"X-Host-Secret": secret or ""},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=5) as r:
+                answer = json.loads(r.read() or b"{}")
+                url = answer.get("hostUrl") if isinstance(answer, dict) else None
+                owner = url if isinstance(url, str) and url else None
+        except urllib.error.HTTPError as e:
+            if e.code != 404:
+                raise
+        if owner and self_url and owner.rstrip("/") == self_url.rstrip("/"):
+            owner = None
+        with lock:
+            cache[sid] = (now + (OWNER_CACHE_S if owner else OWNER_MISS_S), owner)
+        return owner
+
+    return lookup
+
+
+class OwnerUnreachable(Exception):
+    """The owner a request was proxied to did not answer: no connection, or
+    none in time. Not an answer of any status."""
+
+
+class BodyRefused(Exception):
+    """A request body the host will not read: the answer's status and error."""
+
+    def __init__(self, status: int, error: str):
+        super().__init__(error)
+        self.status = status
+        self.error = error
+
+
+def make_host_handler(
+    host: WorldHost,
+    secret: str,
+    worlds_domain: str,
+    owner_lookup: OwnerLookup | None = None,
+    *,
+    max_body_mb: int = DEFAULT_MAX_BODY_MB,
+    secure_cookies: bool = True,
+):
+    """The request handler class for one host. ``secret`` is required: the
+    control plane is the only trust boundary, so a host with no secret has no
+    control plane at all rather than an open one. ``secure_cookies`` is off
+    only for a host whose public surface is reached over plain http (a dev
+    host); it is the deployment's word, not the request's, since a client
+    writes the forwarding headers a request arrives with."""
+    if not secret:
+        raise ValueError("the world host needs a control-plane secret (WORLDS_HOST_SECRET)")
+    if max_body_mb <= 0:
+        raise ValueError(f"the request body cap must be positive (WORLDS_HOST_MAX_BODY_MB={max_body_mb})")
+    max_body_bytes = max_body_mb * (1 << 20)
+
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "gateway-world-host/1"
+
+        def log_message(self, format: str, *args: object) -> None:
+            pass
+
+        # -- plumbing ------------------------------------------------------- #
+
+        def _read(self) -> bytes:
+            declared = self.headers.get("Content-Length")
+            if declared is None:
+                return b""
+            try:
+                length = int(declared)
+            except ValueError:
+                raise BodyRefused(400, "Content-Length is not a number") from None
+            if length < 0:
+                raise BodyRefused(400, "Content-Length is negative")
+            if length > max_body_bytes:
+                raise BodyRefused(413, f"request body over {max_body_mb} MiB")
+            return self.rfile.read(length) if length else b""
+
+        def _reply(self, status: int, body: Any, extra: dict[str, str] | None = None) -> None:
+            send_response(self, status, body, extra, "application/json")
+
+        def _headers(self) -> dict[str, str]:
+            return {k.lower(): v for k, v in self.headers.items()}
+
+        # -- dispatch ------------------------------------------------------- #
+
+        def do_GET(self):
+            self._dispatch("GET")
+
+        def do_POST(self):
+            self._dispatch("POST")
+
+        def do_PUT(self):
+            self._dispatch("PUT")
+
+        def do_PATCH(self):
+            self._dispatch("PATCH")
+
+        def do_DELETE(self):
+            self._dispatch("DELETE")
+
+        def _dispatch(self, method: str) -> None:
+            url = urllib.parse.urlsplit(self.path)
+            # The public side is whatever arrives under the worlds domain. It
+            # gets sessions and nothing about the host: the probes' answer is
+            # a bare ok, the counters and the rest live on the pod address
+            # (prometheus) or behind the control-plane secret (/__host/stats).
+            if url.path == "/healthz":
+                return self._reply(200, {"ok": True})
+            if url.path == "/metrics" and not public_host(self.headers.get("Host"), worlds_domain):
+                payload = host.metrics_text().encode("utf-8")
+                return self._relay(
+                    200, [("Content-Type", "text/plain; version=0.0.4; charset=utf-8")], payload, drop=FRAMING_HEADERS
+                )
+            try:
+                if url.path.startswith("/__host/"):
+                    return self._control(method, url)
+                return self._data(method, url)
+            except BodyRefused as refused:
+                # The body was not read, so the connection cannot carry another
+                # request: answer and hang up.
+                self.close_connection = True
+                return self._reply(refused.status, {"error": refused.error}, {"Connection": "close"})
+
+        # -- control plane -------------------------------------------------- #
+
+        def _control(self, method: str, url) -> None:
+            if not hmac.compare_digest(self.headers.get("X-Host-Secret") or "", secret):
+                return self._reply(403, {"error": "forbidden"})
+            raw = self._read()
+            try:
+                body = json.loads(raw) if raw else {}
+            except ValueError as error:
+                return self._reply(400, {"error": "malformed json", "detail": str(error)})
+            if not isinstance(body, dict):
+                return self._reply(400, {"error": "malformed json", "detail": "the body must be a json object"})
+            parts = url.path.strip("/").split("/")  # __host, sessions, [sid], [verb]
+            try:
+                if method == "GET" and parts == ["__host", "stats"]:
+                    return self._reply(200, host.stats())
+                if method == "POST" and parts == ["__host", "drain"]:
+                    host.drain()
+                    return self._reply(200, {"draining": True, "sessions": host.session_count()})
+                if method == "GET" and parts == ["__host", "versions"]:
+                    return self._reply(200, {"versions": host.cache.version_ids()})
+                if method == "POST" and parts == ["__host", "versions"]:
+                    return self._reply(
+                        200,
+                        host.warm(body["versionId"], body["bundleUrl"], body.get("snapshot")),
+                    )
+                if method == "POST" and parts == ["__host", "sessions"]:
+                    return self._reply(
+                        200,
+                        host.open(
+                            session_id=body["sessionId"],
+                            version_id=body["versionId"],
+                            bundle_url=body["bundleUrl"],
+                            task=body.get("task"),
+                            token=body.get("token"),
+                            snapshot=body.get("snapshot"),
+                            browser=body.get("browser"),
+                            restore=body.get("restore"),
+                            task_spec=body.get("taskSpec"),
+                        ),
+                    )
+                if len(parts) >= 3 and parts[:2] == ["__host", "sessions"]:
+                    sid = parts[2]
+                    verb = parts[3] if len(parts) > 3 else None
+                    if method == "DELETE" and verb is None:
+                        return self._reply(200, host.close(sid))
+                    if method == "POST" and verb == "renew":
+                        return self._reply(200, host.renew(sid))
+                    if method == "POST" and verb == "reset":
+                        return self._reply(200, host.reset(sid))
+                    if method == "POST" and verb == "seed":
+                        return self._reply(200, host.seed(sid, body.get("args") or {}))
+                    if method == "POST" and verb == "export" and len(parts) == 4:
+                        known = body.get("knownSha256")
+                        return self._reply(200, host.export(sid, known if isinstance(known, str) else None))
+                    if method == "POST" and verb == "export" and len(parts) == 5:
+                        url = body.get("url")
+                        if not isinstance(url, str) or not url.startswith(("https://", "http://")):
+                            return self._reply(400, {"error": "url must be the presigned upload url"})
+                        return self._reply(200, host.upload_export(sid, parts[4], url))
+                    if method == "GET" and verb == "state":
+                        return self._reply(200, host.state(sid))
+                    if method == "POST" and verb == "grade":
+                        return self._reply(200, host.grade(sid))
+                    if method == "POST" and verb == "call":
+                        tool = body.get("tool")
+                        if not isinstance(tool, str):
+                            return self._reply(400, {"error": "tool must be a string"})
+                        return self._reply(200, host.call(sid, tool, body.get("args") or {}))
+                return self._reply(404, {"error": "unknown control route"})
+            except ContractError as error:
+                code = error.detail.get("code", "host")
+                # A host that will not take the session is not a bad request:
+                # the platform places it on another replica. A session this
+                # host does not hold is the one answer the platform may read
+                # as "lost"; every other refusal is about the request.
+                if code in ("draining", "at_capacity"):
+                    status = 503
+                elif code == UNKNOWN_SESSION:
+                    status = 404
+                else:
+                    status = 400
+                return self._reply(status, {"error": code, "detail": str(error)})
+            except KeyError as error:
+                return self._reply(400, {"error": "missing field", "field": str(error)})
+            except WorkerGone as error:
+                return self._reply(502, {"error": "worker exited", "detail": str(error)})
+
+        # -- data plane ----------------------------------------------------- #
+
+        def _data(self, method: str, url) -> None:
+            headers = self._headers()
+            named = session_from_host(headers.get("host"))
+            if named is None:
+                return self._reply(404, {"error": "no session named by Host"})
+            sid, surface = named
+            if not host.owns(sid):
+                # Another host owns it (or it is closed). Proxy one hop when the
+                # platform can point us at the owner; a request that already
+                # hopped once is not sent on again.
+                hopped = HOP_HEADER in headers
+                owner = owner_lookup(sid) if owner_lookup and not hopped else None
+                if owner and owner_lookup:
+                    host.tally("requests.proxied")
+                    return self._proxy(sid, owner, owner_lookup, method, headers)
+                return self._reply(404, {"error": "unknown or closed session"})
+            host.tally(f"requests.{surface}")
+            try:
+                with host.using(sid) as session:
+                    if session.spec is None:
+                        return self._reply(
+                            404, {"error": "this world has no http surface; reach its tools through call"}
+                        )
+                    if surface == "browser":
+                        self._serve_browser(session, url, headers)
+                    elif surface == "ui":
+                        self._serve_ui(session, method, url, headers)
+                    else:
+                        self._serve(session, method, url, headers)
+            except ContractError:
+                # Closed between the ownership check and the lookup.
+                self._reply(404, {"error": "unknown or closed session"})
+
+        def _serve(self, session: Session, method: str, url, headers: dict[str, str]) -> None:
+            admitted = admits(session, url.path, headers)
+            if admitted is None:
+                return self._reply(401, {"error": "invalid session token"})
+            self._serve_api(session, method, self.path, headers, admitted)
+
+        def _serve_api(
+            self, session: Session, method: str, target: str, headers: dict[str, str], admitted: str
+        ) -> None:
+            """Answer ``target`` (a path plus query) from the session's world,
+            in this process or its worker, once the gate has admitted it."""
+            sid = session.session_id
+            raw = self._read()
+            if session.worker is not None:
+                # The gate passed here; the worker runs it again and presents the
+                # world its credential, so the request goes over as it came.
+                try:
+                    status, answer_headers, payload = session.worker.request(method, target, headers, raw)
+                except WorkerGone as error:
+                    host.lose_worker(session.worker)
+                    return self._reply(502, {"error": "worker exited", "detail": str(error)})
+                return self._relay(status, answer_headers, payload, drop=FRAMING_HEADERS)
+            assert session.app is not None
+            world_headers = headers
+            if admitted == "session":
+                # The host's token gate is the access control; present the world
+                # its OWN expected credential so the emulated vendor auth passes.
+                credential_headers, credential_query = world_credential(session)
+                world_headers = {**headers, **credential_headers}
+                target = with_query(target, credential_query)
+            status, body, extra = session.app.handle(method, target, world_headers, raw, f"w-{sid}-api.{worlds_domain}")
+            self._reply(status, body, extra)
+
+        # -- the ui surface -------------------------------------------------- #
+
+        def _serve_ui(self, session: Session, method: str, url, headers: dict[str, str]) -> None:
+            ui = session.ui
+            if ui is None:
+                return self._reply(404, {"error": "this world has no static ui"})
+            token = session.token
+            if token is not None:
+                if matches(query_token(url.query), token):
+                    # The way in: trade the one-time ``?token=`` for the cookie
+                    # and land on the same page without it.
+                    landing = without_query_token(url)
+                    return self._reply(
+                        303,
+                        {"location": landing},
+                        {
+                            "Location": landing,
+                            "Set-Cookie": session_cookie(token, secure=secure_cookies, max_age_s=host.lease_s),
+                        },
+                    )
+                if not matches(cookie_token(headers), token) and not matches(bearer_of(headers), token):
+                    return self._reply(401, {"error": "invalid session token"})
+            route = api_target(ui, url.path)
+            if route is not None:
+                # The SPA's same-origin api call: strip the prefix and answer it
+                # as the api surface would for a caller holding the session
+                # token (the cookie stood in for the bearer here).
+                target = urllib.parse.urlunsplit(("", "", route, url.query, ""))
+                api_headers = {k: v for k, v in headers.items() if k not in ("cookie", "authorization")}
+                if token is not None:
+                    api_headers["authorization"] = f"Bearer {token}"
+                return self._serve_api(session, method, target, api_headers, "session")
+            if method != "GET":
+                return self._reply(405, {"error": "the static ui answers GET only"})
+            status, static_headers, payload = static_file(ui, url.path)
+            self._relay(status, static_headers.items(), payload, drop=FRAMING_HEADERS)
+
+        # -- the browser surface --------------------------------------------- #
+
+        def _serve_browser(self, session: Session, url, headers: dict[str, str]) -> None:
+            """``/cdp/<session token>`` and ``/live/<grant>`` on the session's
+            cdp host: check the credential against the SESSION, then tunnel
+            the websocket to the leased relay with the POOL credential the
+            relay knows. The relay's token never leaves the host."""
+            if session.browser_url is None or session.browser_token is None:
+                return self._reply(404, {"error": "this session has no browser surface"})
+            parts = url.path.strip("/").split("/")
+            if len(parts) != 2 or parts[0] not in ("cdp", "live"):
+                return self._reply(404, {"error": "browser routes are /cdp/<token> and /live/<grant>"})
+            kind, credential = parts
+            token = session.token or ""
+            if kind == "cdp":
+                if not matches(credential, token):
+                    return self._reply(401, {"error": "invalid session token"})
+                # The relay decodes the path segment, so a token with '/' or
+                # '=' (openssl rand -base64) must travel percent-encoded.
+                upstream_path = f"/cdp/{urllib.parse.quote(session.browser_token, safe='')}"
+            else:
+                scope = verify_live_grant(credential, token)
+                if scope is None:
+                    return self._reply(401, {"error": "invalid or expired live grant"})
+                upstream_path = f"/live/{mint_live_grant(session.browser_token, LIVE_RELAY_GRANT_MS, scope)}"
+            if headers.get("upgrade", "").lower() != "websocket":
+                return self._reply(400, {"error": "the browser surface is a websocket"})
+            self.close_connection = True
+            try:
+                tunnel(self.connection, session.browser_url, upstream_path, headers)
+            except OSError as error:
+                self._reply(502, {"error": "browser unreachable", "detail": str(error)})
+
+        def _proxy(self, sid: str, owner: str, lookup: OwnerLookup, method: str, headers: dict[str, str]) -> None:
+            """Send the request on to ``owner``. An owner that does not answer
+            at all may be a host that died with the session since recovered
+            elsewhere, so the platform is asked once more, uncached, and the
+            request goes to the owner it names now; only then is it a 502.
+            The retry stays one hop (the hop header goes with it)."""
+            websocket = headers.get("upgrade", "").lower() == "websocket"
+            raw = b"" if websocket else self._read()
+            try:
+                return self._forward(owner, method, headers, raw, websocket)
+            except OwnerUnreachable as stale:
+                current = lookup(sid, fresh=True)
+                if not current or current.rstrip("/") == owner.rstrip("/"):
+                    return self._reply(502, {"error": "owner unreachable", "detail": str(stale)})
+            host.tally("requests.rerouted")
+            try:
+                self._forward(current, method, headers, raw, websocket)
+            except OwnerUnreachable as error:
+                self._reply(502, {"error": "owner unreachable", "detail": str(error)})
+
+        def _forward(self, owner: str, method: str, headers: dict[str, str], raw: bytes, websocket: bool) -> None:
+            """One attempt at ``owner``; raises :class:`OwnerUnreachable` when it
+            did not answer, before anything has been written to the client."""
+            if websocket:
+                # A browser session on another host: the owner runs the
+                # credential check; this hop only carries bytes. ``tunnel``
+                # fails before the 101 or not at all.
+                owner_ws = "ws://" + owner.split("://", 1)[-1].rstrip("/")
+                self.close_connection = True
+                try:
+                    tunnel(self.connection, owner_ws, self.path, {**headers, HOP_HEADER: "1"}, host=headers.get("host"))
+                except OSError as error:
+                    raise OwnerUnreachable(str(error)) from error
+                return
+            target = f"{owner.rstrip('/')}{self.path}"
+            forward = {k: v for k, v in headers.items() if k not in ("host", "content-length")}
+            forward["host"] = headers.get("host", "")
+            forward[HOP_HEADER] = "1"
+            req = urllib.request.Request(target, data=raw or None, method=method, headers=forward)
+            try:
+                with _PROXY_OPENER.open(req, timeout=60) as r:
+                    self._relay(r.status, r.headers.items(), r.read(), drop=PROXIED_DROP_HEADERS)
+            except urllib.error.HTTPError as e:
+                self._relay(e.code, e.headers.items(), e.read(), drop=PROXIED_DROP_HEADERS)
+            except (OSError, http.client.HTTPException) as error:
+                # URLError is an OSError: no connection, or none in time.
+                raise OwnerUnreachable(str(error)) from error
+
+        def _relay(
+            self,
+            status: int,
+            headers: Iterable[tuple[str, str]],
+            payload: bytes,
+            *,
+            drop: frozenset[str],
+        ) -> None:
+            """Write another process's answer through as it came: same status,
+            same body bytes, every header the world set except ``drop`` (the
+            framing, which is this connection's, and from an owner the
+            hop-by-hop headers too). The world's contract, its ``page_headers``
+            included, reads the same from every replica."""
+            self.send_response(status)
+            content_type = None
+            for name, value in headers:
+                lower = name.lower()
+                if lower == "content-type":
+                    content_type = value
+                elif lower not in drop:
+                    self.send_header(name, value)
+            self.send_header("Content-Type", content_type or "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+            self.end_headers()
+            self.wfile.write(payload)
+
+    return Handler
+
+
+def start_lease_sweeper(world_host: WorldHost, interval_s: float = LEASE_SWEEP_S) -> threading.Event:
+    """Expire leases every ``interval_s`` until the returned event is set."""
+    stop = threading.Event()
+
+    def sweep() -> None:
+        while not stop.wait(interval_s):
+            for sid in world_host.expire_leases():
+                print(
+                    f"world host: lease expired, closed session {sid}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+            for version_id in world_host.reap_workers():
+                print(
+                    f"world host: stopped idle worker for version {version_id}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+
+    threading.Thread(target=sweep, name="world-host-leases", daemon=True).start()
+    return stop
+
+
+def heartbeat_once(world_host: WorldHost, platform_url: str, secret: str, timeout_s: float = 5.0) -> bool:
+    """Tell the platform what this host is and holds (:meth:`WorldHost.stats`).
+    The platform's registry is what places new sessions: a host it has not
+    heard from lately gets none. Returns whether the platform took it."""
+    body = json.dumps(world_host.stats()).encode("utf-8")
+    req = urllib.request.Request(
+        f"{platform_url.rstrip('/')}/api/public/world-hosts",
+        data=body,
+        method="POST",
+        headers={"content-type": "application/json", "x-host-secret": secret},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as r:
+            return 200 <= r.status < 300
+    except (urllib.error.URLError, OSError, ValueError) as error:
+        print(f"world host: heartbeat failed: {error}", file=sys.stderr, flush=True)
+        return False
+
+
+def start_heartbeat(
+    world_host: WorldHost, platform_url: str, secret: str, interval_s: float = HEARTBEAT_S
+) -> threading.Event:
+    """Heartbeat every ``interval_s`` until the returned event is set; the
+    first beat goes out at once so a fresh replica is placeable immediately,
+    and a last one goes out on stop so the registry sees it draining."""
+    stop = threading.Event()
+
+    def beat() -> None:
+        heartbeat_once(world_host, platform_url, secret)
+        while not stop.wait(interval_s):
+            heartbeat_once(world_host, platform_url, secret)
+        heartbeat_once(world_host, platform_url, secret)
+
+    threading.Thread(target=beat, name="world-host-heartbeat", daemon=True).start()
+    return stop
+
+
+class HostServer(ThreadingHTTPServer):
+    """The listening socket plus what shutdown has to stop: the lease sweeper,
+    the heartbeat and the version workers."""
+
+    def __init__(
+        self,
+        address: tuple[str, int],
+        handler: type[BaseHTTPRequestHandler],
+        world_host: WorldHost,
+        *,
+        heartbeat: tuple[str, str] | None = None,
+        heartbeat_s: float = HEARTBEAT_S,
+        drain_s: float = DEFAULT_DRAIN_S,
+    ):
+        super().__init__(address, handler)
+        self.world_host = world_host
+        self.lease_sweeper = start_lease_sweeper(world_host)
+        #: ``(platform url, secret)`` to report to; None runs unregistered (one
+        #: replica behind WORLDS_HOST_URL needs no registry).
+        self.heartbeat = start_heartbeat(world_host, *heartbeat, interval_s=heartbeat_s) if heartbeat else None
+        self.drain_s = drain_s
+
+    def drain(self) -> None:
+        """SIGTERM: refuse new sessions, announce it, serve what is here until
+        it closes or the grace runs out, then stop. Runs off the signal thread
+        so ``serve_forever`` keeps answering meanwhile."""
+        self.world_host.drain()
+        if self.heartbeat is not None:
+            self.heartbeat.set()  # its last beat carries ``draining: true``
+
+        def wait_then_stop() -> None:
+            deadline = time.time() + self.drain_s
+            while self.world_host.session_count() > 0 and time.time() < deadline:
+                time.sleep(0.5)
+            self.shutdown()
+
+        threading.Thread(target=wait_then_stop, name="world-host-drain", daemon=True).start()
+
+
+def serve(cache_root: str | Path, *, port: int = 8080, host_addr: str = "0.0.0.0") -> HostServer:
+    """The host as deployed, configured from the environment:
+
+    ``WORLDS_HOST_SECRET`` gates the control plane; ``WORLDS_INGRESS_DOMAIN`` is
+    the domain the session hostnames live under; ``WORLDS_HOST_ADVERTISE_URL`` is
+    this replica's own address (``http://<pod ip>:<port>``), returned on open so
+    the platform pins the session to it; ``WORLDS_PLATFORM_URL`` lets a
+    non-owner replica ask the platform who owns a session and proxy one hop;
+    ``WORLDS_HOST_LEASE_S`` is how long an untouched session lives;
+    ``WORLDS_HOST_MAX_SESSIONS`` is how many it takes before answering 503;
+    ``WORLDS_HOST_HEARTBEAT_S`` is how often it reports to the platform (with
+    ``WORLDS_PLATFORM_URL`` and an advertised address, else no heartbeat);
+    ``WORLDS_HOST_DRAIN_S`` is how long a SIGTERM waits for sessions to close;
+    ``WORLDS_WORKER_MEMORY_MB`` caps each version worker's address space and
+    ``WORLDS_WORKER_BUDGET_MB`` all of them together (their count is the
+    quotient; one more version answers 503 ``at_capacity``),
+    ``WORLDS_HOST_OBJECT_STORE`` is where every presigned URL it is handed
+    may point (required; ``any`` for a dev host),
+    ``WORLDS_HOST_MAX_BUNDLE_MB`` is the largest version bundle the cache
+    accepts, ``WORLDS_HOST_MAX_BODY_MB`` the largest request body it reads,
+    ``WORLDS_HOST_PLAIN_HTTP=1`` says the public surface is reached over plain
+    http (a dev host: the ui cookie is not marked ``Secure``) and
+    ``WORLDS_HOST_WORKERS=0`` runs without workers (handler worlds refused)."""
+    secret = os.environ.get("WORLDS_HOST_SECRET") or ""
+    if not secret:
+        raise SystemExit("world host: WORLDS_HOST_SECRET is unset; refusing to start without a control-plane secret")
+    try:
+        object_store = parse_origins(os.environ.get("WORLDS_HOST_OBJECT_STORE"))
+    except ContractError as error:
+        raise SystemExit(f"world host: {error}; refusing to start") from error
+    advertise = os.environ.get("WORLDS_HOST_ADVERTISE_URL") or None
+    platform_url = os.environ.get("WORLDS_PLATFORM_URL") or None
+    lease_s = float(os.environ.get("WORLDS_HOST_LEASE_S") or DEFAULT_LEASE_S)
+    worlds_domain = os.environ.get("WORLDS_INGRESS_DOMAIN", "worlds.local")
+    workers = None
+    if os.environ.get("WORLDS_HOST_WORKERS", "1") != "0":
+        workers = WorkerPool(
+            Path(cache_root),
+            worlds_domain=worlds_domain,
+            memory_mb=int(os.environ.get("WORLDS_WORKER_MEMORY_MB") or DEFAULT_WORKER_MEMORY_MB),
+            budget_mb=int(os.environ.get("WORLDS_WORKER_BUDGET_MB") or DEFAULT_WORKER_BUDGET_MB),
+        )
+    world_host = WorldHost(
+        Path(cache_root),
+        lease_s=lease_s,
+        advertise_url=advertise,
+        workers=workers,
+        max_sessions=int(os.environ.get("WORLDS_HOST_MAX_SESSIONS") or DEFAULT_MAX_SESSIONS),
+        max_bundle_mb=int(os.environ.get("WORLDS_HOST_MAX_BUNDLE_MB") or DEFAULT_MAX_BUNDLE_MB),
+        object_store=object_store,
+    )
+    handler = make_host_handler(
+        world_host,
+        secret=secret,
+        worlds_domain=worlds_domain,
+        owner_lookup=platform_owner_lookup(platform_url, secret, advertise) if platform_url else None,
+        max_body_mb=int(os.environ.get("WORLDS_HOST_MAX_BODY_MB") or DEFAULT_MAX_BODY_MB),
+        secure_cookies=os.environ.get("WORLDS_HOST_PLAIN_HTTP", "0") != "1",
+    )
+    return HostServer(
+        (host_addr, port),
+        handler,
+        world_host,
+        heartbeat=(platform_url, secret) if platform_url and advertise else None,
+        heartbeat_s=float(os.environ.get("WORLDS_HOST_HEARTBEAT_S") or HEARTBEAT_S),
+        drain_s=float(os.environ.get("WORLDS_HOST_DRAIN_S") or DEFAULT_DRAIN_S),
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="gateway-world-host")
+    parser.add_argument("--cache-root", default=os.environ.get("WORLDS_HOST_CACHE", "/cache"))
+    parser.add_argument("--port", type=int, default=int(os.environ.get("PORT") or 8080))
+    args = parser.parse_args(argv)
+    server = serve(args.cache_root, port=args.port)
+    print(
+        f"world host listening on :{args.port}, cache {args.cache_root}",
+        file=sys.stderr,
+        flush=True,
+    )
+    signal.signal(signal.SIGTERM, lambda *_: server.drain())
+    try:
+        server.serve_forever()
+    finally:
+        server.lease_sweeper.set()
+        if server.heartbeat is not None:
+            server.heartbeat.set()
+        if server.world_host.workers is not None:
+            server.world_host.workers.stop_all()
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())