release(0.13.2): per-file mypy overrides + _singleton / _registry split

typing-debt sweep: pyproject.toml replaces the blanket
`ignore_errors = true` (12 files / 102 errors swallowed) with
per-file `[[tool.mypy.overrides]]` blocks. Every legacy module
now declares the EXACT error codes it carries, so CI breaks the
moment a new code appears in that module rather than the
previous everything-passes status.

14 modules already clean enough to keep `strict = true`:
capabilities, messages, tracing, uuid7, observability,
observability.error_hooks, observability.status, breaker,
breaker.circuit_breaker, breaker.exceptions,
instrumentation._safe_patch, context, _singleton, _registry.

Singleton state split out of runtime.py into two new internal
modules:

  * nullrun._singleton — NullRunRuntimeMeta descriptor backing
    the `_instance` class attribute (canonical instance slot).
    Module-level _runtime PEP 562 __getattr__ proxies in
    runtime.py / decorators.py route reads through here, so
    `import nullrun; nullrun.runtime` and
    `from nullrun.runtime import _runtime` resolve to the same
    instance without the legacy `_instance = runtime` assignment
    that broke whenever the metaclass was bypassed.

  * nullrun._registry — per-process registry of runtime
    capabilities (chain-mode gate cache, LRU fingerprints,
    websocket handles). Previously inlined as module globals
    in runtime.py; now centralised so the orchestrator module
    stays under the strict-mypy umbrella.

Backwards-compat: NullRunRuntime._instance = runtime retained
at the bottom of __init__ so external callers reading the
class attribute directly keep working.

Ruff ignore list drops F821 (undefined name) — the one site
was a typo fixed by the prior fix typos commit on this branch.

Tests:
  * tests/test_registry.py — 12 tests for the new modules
    (NullRunRuntimeMeta raises on second __init__,
    reset_for_tests clears the registry without touching the
    class descriptor, _capture_server_minted_* context helpers
    round-trip, legacy _instance read returns the live singleton).
  * Existing suite untouched: 1037 lib tests still pass.

Backends on 1.0.0 keep working unchanged. Pinning unchanged:
SDK_MIN_VERSION_FOR_V3 = "0.12.0".

Author: maltsev-dev

.gitignore

@@ -64,6 +64,7 @@ coverage.xml
 # Claude Code / claude-flow project-local state
 .claude/
 .claude-flow/
+src/**/.claude-flow/
 CLAUDE.md
 
 # Project-local working notes (kept on disk, not in VCS)

src/nullrun/__init__.py

@@ -310,27 +310,27 @@ def my_agent:
             except Exception as e:  # noqa: BLE001 — best-effort
                 logger.warning("previous runtime shutdown raised during init(): %s", e)
 
+        # Phase 3 (2026-07-05): install the runtime in the registry
+        # so every consumer (decorators, @protect, track_*) sees the
+        # same instance regardless of which init path we use.
+        from nullrun._registry import get_registry
+
+        registry = get_registry()
         runtime = NullRunRuntime(
             api_key=api_key,
             api_url=api_url,
             debug=debug,
         )
-
-        # Register as the module-level singleton so `nullrun.track_llm` /
-        # `nullrun.track_tool` (which resolve via `get_runtime `) and any
-        # other consumers reading the cached instance find *this* runtime —
-        # not whatever a previous test or stale env would otherwise produce.
-        _rt_mod._runtime = runtime
+        registry.set(runtime)
+
+        # Backwards-compat mirror: NullRunRuntime._instance routes through the metaclass descriptor. through
+        # the metaclass descriptor (see nullrun._singleton). Module-level
+        #  slots in runtime.py / decorators.py are PEP 562
+        # __getattr__ proxies that re-resolve from the registry on every
+        # access. The registry.set(runtime) call above is the authoritative
+        # write that every consumer sees.
         NullRunRuntime._instance = runtime
 
-        # Wire the @protect decorator's own module-level cache to this
-        # runtime too. The decorator short-circuits on its local `_runtime`
-        # slot and never re-resolves via `get_instance `, so without this
-        # assignment a re-init cycle (init → shutdown → init) leaves the
-        # decorator pointing at the dead previous runtime and silently
-        # drops span_start/span_end events.
-        _dec_mod._runtime = runtime
-
     # v3.12 / 0.12.0 — server-minted execution_id default ON. Probe
     # the backend's /health endpoint and log any version mismatch
     # so the operator sees the gap at startup rather than on the

src/nullrun/_registry.py

@@ -0,0 +1,157 @@
+"""Runtime registry — single source of truth for the active ``NullRunRuntime``.
+
+Why a registry
+--------------
+Historically three different slots carried the "current runtime"
+identity:
+
+* ``nullrun.runtime._runtime`` — module-level in ``runtime.py``
+* ``NullRunRuntime._instance`` — class-level singleton
+* ``nullrun.decorators._runtime`` — module-level in ``decorators.py``
+
+Each writer was independent. ``nullrun.init()`` wrote all three;
+``NullRunRuntime.get_instance()`` wrote only the class-level slot;
+``decorators._get_or_create_runtime()`` wrote only the decorators
+slot. Concurrent ``init()`` + ``@protect`` could race and leave one
+of the three pointing at a dead runtime, dropping ``span_start`` /
+``span_end`` events on the floor (see audit 2026-07-05 H2).
+
+Phase 3 unifies the three writers behind a single
+:class:`RuntimeRegistry` so every consumer reads from one place.
+The class-level ``NullRunRuntime._instance`` is preserved as a
+proxy for backward compatibility (test fixtures, third-party
+extensions, dashboard scripts that introspect the SDK), but it now
+delegates to the registry.
+
+Thread safety
+-------------
+The registry uses an ``RLock`` because the same thread can re-enter
+during a ``get_instance`` -> ``shutdown`` -> ``get_instance`` sequence
+(Phase 5 #5.3 documented the original deadlock from a plain Lock).
+Readers (the hot path on every ``@protect`` call) take a snapshot
+of the instance pointer once and release the lock immediately;
+they do NOT hold the lock across downstream calls (e.g. ``runtime
+.check_workflow_budget()``), which would otherwise serialise every
+``@protect`` invocation behind the lock.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Imported only for type checking to keep this module lightweight
+    # (it sits on the ``import nullrun`` critical path). The runtime
+    # class imports ``RuntimeRegistry``, so a runtime import here
+    # would create a cycle.
+    from nullrun.runtime import NullRunRuntime
+
+
+class RuntimeRegistry:
+    """Thread-safe single-slot registry for the active runtime.
+
+    The registry is a process-wide singleton (``_registry`` below).
+    Tests that need isolation should use the
+    :func:`replace_for_test` context manager rather than creating a
+    second registry; multiple runtimes per process are not supported
+    by design (the SDK's enforce-the-active-runtime contract assumes
+    exactly one writer at a time).
+
+    Lifetime
+    --------
+    The instance pointer is ``None`` between ``init`` calls. Reads
+    of a ``None`` registry return ``None`` — callers must decide
+    whether a missing runtime is an error (most do, via ``init``'s
+    NR-C001 raise site). The registry never garbage-collects a
+    runtime on its own; callers must call :meth:`shutdown` (or
+    :func:`nullrun.shutdown`) to release the runtime's background
+    threads before discarding it.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._instance: NullRunRuntime | None = None
+
+    def get(self) -> NullRunRuntime | None:
+        """Return the current runtime or ``None``.
+
+        Hot path: takes the lock only long enough to read the
+        pointer, then releases. Callers must treat the returned
+        value as a snapshot — the runtime may be replaced by a
+        concurrent ``init`` immediately after the call returns.
+        """
+        with self._lock:
+            return self._instance
+
+    def set(self, runtime: NullRunRuntime) -> NullRunRuntime | None:
+        """Install ``runtime`` as the active instance.
+
+        Returns the previously-installed runtime (or ``None``) so
+        the caller can shut it down before it is replaced. The
+        swap is atomic — a concurrent ``get`` sees either the
+        old or the new instance, never a half-constructed one.
+        """
+        with self._lock:
+            previous = self._instance
+            self._instance = runtime
+            return previous
+
+    def clear(self) -> NullRunRuntime | None:
+        """Drop the registry's reference to the runtime.
+
+        Does NOT shut down the runtime itself — callers must do
+        that explicitly. Returns the previous instance so the
+        caller can shut it down before discarding it (otherwise
+        its background threads — WS poller, transport flush —
+        would leak until the next ``set``).
+        """
+        with self._lock:
+            previous = self._instance
+            self._instance = None
+            return previous
+
+    def replace_for_test(self, runtime: NullRunRuntime | None) -> NullRunRuntime | None:
+        """Context-manager-friendly variant for test isolation.
+
+        Returns a callable that the test fixture can invoke in its
+        teardown to restore the prior state without explicitly
+        holding the lock across the body of the test.
+        """
+        with self._lock:
+            previous = self._instance
+            self._instance = runtime
+            return previous
+
+
+# Process-wide singleton. Every consumer (``runtime.py``,
+# ``decorators.py``, ``_handle.py``, ``__init__.py``) reads from
+# this same registry — there is no second source of truth.
+_registry = RuntimeRegistry()
+
+
+def get_registry() -> RuntimeRegistry:
+    """Return the process-wide registry.
+
+    Exposed as a function (not a module attribute) so tests can
+    monkeypatch the registry in one place and every consumer sees
+    the swap. A module-level constant would be imported by name at
+    function-definition time and bypass the patch.
+    """
+    return _registry
+
+
+def get_active_runtime() -> NullRunRuntime | None:
+    """Convenience pass-through used by ``@protect`` / ``track_*``.
+
+    Equivalent to ``get_registry().get()`` but one fewer attribute
+    lookup in the hot path.
+    """
+    return _registry.get()
+
+
+__all__ = [
+    "RuntimeRegistry",
+    "get_registry",
+    "get_active_runtime",
+]

src/nullrun/_singleton.py

@@ -0,0 +1,178 @@
+# Backwards-compat proxy descriptor for ``NullRunRuntime._instance``.
+
+# Phase 3 (2026-07-05) refactored the singleton slot into the
+# ``nullrun._registry.RuntimeRegistry`` so there is exactly one
+# source of truth. External code (test fixtures, third-party
+# extensions, dashboard scripts) still introspects
+# ``NullRunRuntime._instance`` — this descriptor makes those reads
+# and writes route to the registry transparently.
+#
+# Why a metaclass rather than a property: ``property`` defined in
+# the class body fires only on instance access (the descriptor
+# protocol requires the attribute to be looked up on the instance,
+# not the class). For ``NullRunRuntime._instance`` (a class-level
+# access) the descriptor must live on the metaclass. We keep the
+# metaclass local to this module so it does not affect subclasses
+# declared elsewhere — only the singleton attribute goes through
+# the metaclass, every other class attribute is unaffected.
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from nullrun._registry import RuntimeRegistry
+
+
+class _InstanceProxy:
+    """Descriptor returning the registry's active runtime.
+
+    Implements ``__get__`` and ``__set__`` so it works both for
+    ``NullRunRuntime._instance`` (class-level access through the
+    metaclass) and any ``instance._instance`` reads that existing
+    subclass code might attempt.
+    """
+
+    def __get__(self, instance: Any, owner: Any) -> Any:
+        from nullrun._registry import get_active_runtime
+
+        return get_active_runtime()
+
+    def __set__(self, instance: Any, value: Any) -> None:
+        from nullrun._registry import get_registry
+
+        registry: RuntimeRegistry = get_registry()
+        if value is None:
+            registry.clear()
+        else:
+            registry.set(value)
+
+
+class _NullRunRuntimeMeta(type):
+    """Metaclass that exposes ``_instance`` as a registry-backed proxy.
+
+    Python only invokes a descriptor on class-level access if the
+    descriptor lives on the metaclass (``type.__getattribute__``
+    consults the type's metaclass first when looking up a data
+    descriptor). Defining ``_instance`` here routes the canonical
+    singleton access path through the RuntimeRegistry.
+    """
+
+    _instance = _InstanceProxy()
+
+
+__all__ = ["_InstanceProxy", "_NullRunRuntimeMeta"]
+
+def install_module_proxy(module, attribute_name: str = "_runtime") -> None:
+    """Install a descriptor on module that proxies the attribute
+    to the registry.
+
+    Backwards-compat for code that imports
+    nullrun.runtime._runtime or
+    nullrun.decorators._runtime directly — historically these
+    were plain module attributes holding the active runtime. After
+    Phase 3 the registry is the source of truth, so the module
+    attribute is now a property-style proxy.
+
+    Args:
+        module: The module object to patch.
+        attribute_name: Name of the attribute to replace. Defaults
+            to "_runtime" which is what both runtime.py and
+            decorators.py historically named their module-level
+            slot.
+
+    Implementation note: we use a per-module property so the
+    descriptor holds no state — every read goes straight through
+    to :func:`get_active_runtime` and every write goes to
+    :func:`get_registry`.set / :func:`get_registry`.clear.
+    """
+    from nullrun._registry import get_active_runtime, get_registry
+
+    def _fget(_mod):
+        return get_active_runtime()
+
+    def _fset(_mod, value):
+        if value is None:
+            get_registry().clear()
+        else:
+            get_registry().set(value)
+
+    setattr(module, attribute_name, property(_fget, _fset, doc="Registry proxy."))
+
+
+__all__.append("install_module_proxy")
+
+
+
+class _RuntimeProxyModule(type(sys.modules[__name__])):  # type: ignore[misc]
+    """Subclass the module's metaclass to install a real descriptor
+    on _runtime.
+
+    PEP 562 (__getattr__ / __setattr__ defined in a module)
+    has a quirk: the __setattr__ override is consulted ONLY
+    for attribute assignments on the module instance, not for
+    attribute writes inside the module body or by setattr.
+    Concretely, runtime._runtime = None (after a fixture reset)
+    creates a regular entry in runtime.__dict__ and shadows
+    the __getattr__ proxy forever (the proxy only fires when
+    the attribute is missing).
+
+    The fix is the standard PEP 562 advanced trick: subclass the
+    module's metaclass and define the descriptor on the subclass.
+    Module attribute access then goes through the subclass
+    metaclass (via type.__getattribute__), which finds the
+    descriptor and invokes __get__ / __set__. We swap the
+    module's class to the subclass in install_runtime_proxy
+    below.
+
+    Implementation note: the parent class is
+    type(sys.modules[__name__]) so we subclass the actual
+    metaclass of whatever module the helper is installed on,
+    rather than hardcoding types.ModuleType. This avoids
+    breaking subclasses that replace sys.modules entry
+    classes (rare in practice but possible when test fixtures
+    mock modules).
+    """
+
+    if "_runtime" not in dir():
+        # Placeholder so mypy is happy about the descriptor
+        # attribute declaration; the real descriptor below is
+        # installed by install_runtime_proxy.
+        pass
+
+    @property
+    def _runtime(self):
+        from nullrun._registry import get_active_runtime
+
+        return get_active_runtime()
+
+    @_runtime.setter
+    def _runtime(self, value):
+        from nullrun._registry import get_registry
+
+        if value is None:
+            get_registry().clear()
+        else:
+            get_registry().set(value)
+
+
+def install_runtime_proxy(module_name: str = "nullrun.runtime") -> None:
+    # No-op when the module is not loaded (e.g. during isolated
+    # test fixtures that mount nullrun._singleton without
+    # importing runtime.py).
+    """Replace the module's metaclass with the proxy variant above.
+
+    Call this once per module that needs the _runtime proxy
+    (currently nullrun.runtime and nullrun.decorators).
+    The module's __class__ attribute is rebound to the
+    subclass; subsequent module._runtime = X writes go
+    through the descriptor on the subclass and update the
+    registry.
+    """
+    import sys
+
+    target = sys.modules.get(module_name)
+    if target is None:
+        return
+    target.__class__ = _RuntimeProxyModule