@@ -0,0 +1,96 @@
+# © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for shared signing-key resolution (``vgi.serve``).
+
+The signing key seals HTTP state tokens. Every process that might serve a
+continuation has to hold the same one, and when they do not the failure is
+load-dependent: a pinned connection works, a reconnect mid-stream does not.
+These tests pin the resolution rules so that cannot regress into silence.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from vgi.serve import (
+    SIGNING_KEY_ENV,
+    _warn_if_ephemeral_signing_key,
+    resolve_shared_signing_key,
+)
+
+
+def test_configured_key_is_used_verbatim(monkeypatch: pytest.MonkeyPatch) -> None:
+    """An operator-set key wins and is reported as not ephemeral."""
+    monkeypatch.setenv(SIGNING_KEY_ENV, "a-shared-secret")
+    key, ephemeral = resolve_shared_signing_key(propagate_to_children=False)
+    assert key == b"a-shared-secret"
+    assert ephemeral is False
+
+
+def test_unset_key_is_minted_and_flagged(monkeypatch: pytest.MonkeyPatch) -> None:
+    """With nothing configured we mint one and say so."""
+    monkeypatch.delenv(SIGNING_KEY_ENV, raising=False)
+    key, ephemeral = resolve_shared_signing_key(propagate_to_children=False)
+    assert len(key) >= 32
+    assert ephemeral is True
+    # Not exported: this process starts no children that would need it.
+    assert SIGNING_KEY_ENV not in os.environ
+
+
+def test_minted_key_is_exported_for_children(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A pre-fork parent exports the key so its workers inherit one value.
+
+    This is the whole point: without it each forked worker imports the app
+    and mints its own, and tokens stop being portable between them.
+    """
+    monkeypatch.delenv(SIGNING_KEY_ENV, raising=False)
+    key, ephemeral = resolve_shared_signing_key(propagate_to_children=True)
+    assert ephemeral is True
+    exported = os.environ.get(SIGNING_KEY_ENV)
+    assert exported is not None
+    assert exported.encode() == key
+
+    # A child re-resolving from the inherited environment gets the same key.
+    child_key, child_ephemeral = resolve_shared_signing_key(propagate_to_children=True)
+    assert child_key == key
+    assert child_ephemeral is False
+
+
+def test_independent_processes_disagree_without_configuration(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Two unrelated processes mint different keys -- the bug being prevented.
+
+    Documents *why* propagation exists: absent a configured key and absent
+    export, two resolutions produce keys that cannot open each other's
+    tokens.
+    """
+    from vgi_rpc import crypto
+
+    monkeypatch.delenv(SIGNING_KEY_ENV, raising=False)
+    key_a, _ = resolve_shared_signing_key(propagate_to_children=False)
+    key_b, _ = resolve_shared_signing_key(propagate_to_children=False)
+    assert key_a != key_b
+
+    sealed = crypto.seal_bytes(b"stream-cursor", key_a, aad=b"aad", version=5)
+    assert crypto.open_bytes(sealed, key_a, aad=b"aad", version=5) == b"stream-cursor"
+    with pytest.raises(crypto.SealError):
+        crypto.open_bytes(sealed, key_b, aad=b"aad", version=5)
+
+
+def test_ephemeral_warning_is_loud_for_single_process(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A per-process key warns, naming the env var and the symptom."""
+    with caplog.at_level("INFO", logger="vgi.serve"):
+        _warn_if_ephemeral_signing_key(is_ephemeral=True, multiprocess=False)
+    assert any(r.levelname == "WARNING" for r in caplog.records)
+    assert SIGNING_KEY_ENV in caplog.text
+
+
+def test_configured_key_does_not_warn(caplog: pytest.LogCaptureFixture) -> None:
+    """Nothing to say when the operator configured a key."""
+    with caplog.at_level("INFO", logger="vgi.serve"):
+        _warn_if_ephemeral_signing_key(is_ephemeral=False, multiprocess=False)
+    assert not caplog.records
@@ -29,6 +29,7 @@
 import importlib.util
 import logging
 import os
+import secrets
 import sys
 from collections.abc import Callable
 from types import ModuleType
@@ -262,10 +263,11 @@ def create_app(
     # Resolve the signing key once, here, so the worker (which seals catalog
     # opaque-data envelopes) and the HTTP state-token machinery share the same
     # key. When the operator did not configure VGI_SIGNING_KEY, generate an
-    # ephemeral per-process key: sealed values are then valid for the life of
-    # this process and clients re-ATTACH after a restart.
+    # key. See resolve_shared_signing_key for why every process serving this
+    # deployment has to agree on it.
     if signing_key is None:
-        signing_key = os.urandom(32)
+        signing_key, is_ephemeral = resolve_shared_signing_key(propagate_to_children=False)
+        _warn_if_ephemeral_signing_key(is_ephemeral=is_ephemeral, multiprocess=False)
 
     if proxy_proof_required is None:
         proxy_proof_required = (os.environ.get("VGI_PROXY_PROOF_MODE") or "").strip().lower() == "require"
@@ -412,14 +414,89 @@ def serve(
     app()
 
 
+SIGNING_KEY_ENV = "VGI_SIGNING_KEY"
+
+
 def _resolve_signing_key() -> bytes | None:
     """Read ``VGI_SIGNING_KEY`` from the environment."""
-    raw = os.environ.get("VGI_SIGNING_KEY")
+    raw = os.environ.get(SIGNING_KEY_ENV)
     if raw:
         return raw.encode()
     return None
 
 
+def resolve_shared_signing_key(*, propagate_to_children: bool) -> tuple[bytes, bool]:
+    """Resolve the signing key every process in this deployment must agree on.
+
+    The key seals HTTP state tokens and catalog opaque data. Every process
+    that might serve a continuation for a stream has to hold the *same* one:
+    a token sealed by one key fails the AEAD check under another, and the
+    failure is load-dependent rather than deterministic. A client whose
+    connection stays pinned to one process never notices; one that reconnects
+    mid-stream -- ``seek_to_token``, a load balancer, a respawned worker --
+    hits an intermittent 400 that looks like flakiness.
+
+    Resolution:
+
+    - ``VGI_SIGNING_KEY`` set: use it. Tokens survive restarts and are valid
+      across every process configured with the same value. This is the only
+      correct setting for a load-balanced or multi-instance deployment,
+      because nothing here can reach a peer we did not start.
+    - Unset: mint a random key for this deployment. Tokens are then valid for
+      the life of these processes and clients re-ATTACH after a restart.
+
+    Args:
+        propagate_to_children: True when this process will start worker
+            processes that import the app themselves (a pre-fork server).
+            A minted key is then exported to the environment so those
+            children inherit it instead of each minting its own -- which is
+            the bug this function exists to prevent.
+
+    Returns:
+        ``(key, is_ephemeral)``. ``is_ephemeral`` is True when the key was
+        minted here rather than configured, so callers can say so out loud.
+
+    """
+    configured = _resolve_signing_key()
+    if configured is not None:
+        return configured, False
+
+    minted = secrets.token_urlsafe(32)
+    if propagate_to_children:
+        # Children inherit os.environ, so exporting before we start them is
+        # what makes them agree. Same channel the operator would use, so this
+        # adds no exposure they did not already have by setting it.
+        os.environ[SIGNING_KEY_ENV] = minted
+    return minted.encode(), True
+
+
+def _warn_if_ephemeral_signing_key(*, is_ephemeral: bool, multiprocess: bool) -> None:
+    """Say plainly when state tokens will not be portable.
+
+    Silence here is what makes the failure mode expensive: an operator who
+    scales to two instances gets a server that works until a request lands
+    on the wrong one.
+    """
+    if not is_ephemeral:
+        return
+    if multiprocess:
+        _logger.info(
+            "No %s configured; minted one for this deployment and exported it to worker processes. "
+            "State tokens are valid until restart. Set %s to keep them valid across restarts.",
+            SIGNING_KEY_ENV,
+            SIGNING_KEY_ENV,
+        )
+        return
+    _logger.warning(
+        "No %s configured; using a per-process key. State tokens and catalog handles are valid only "
+        "for this process. If you run more than one instance behind a load balancer, set %s to the "
+        "same value in every one -- otherwise a client that reconnects mid-stream gets an "
+        "intermittent 400.",
+        SIGNING_KEY_ENV,
+        SIGNING_KEY_ENV,
+    )
+
+
 def _resolve_describe(cli_value: bool) -> bool:
     """Apply ``VGI_ENABLE_DESCRIBE`` env var override.