fix(server): fix register_lazy+resolve disabled-state inconsistencies

Two correctness issues found in pre-PR review:

1. register_lazy(await_first_validation=True) + validator returns False:
   the platform was being written to _platforms even though the tenant
   is disabled, and the factory was left in _factories. Mirrors the
   resolve() cold-path: on validator failure, discard the platform and
   clear the factory so the disabled tenant behaves consistently
   regardless of how it reached that state.

2. resolve() docstring claimed it returns None when validator returns
   False — only true for the lazy cold-path. The fast-path (eager or
   previously-resolved lazy) returns TenantResolution(health="disabled").
   Rewritten to make the contract unambiguous and to warn against
   gating solely on result is None.

Also adds:
- Class docstring: do-not-use-as-SubdomainTenantRouter warning (same
  resolve(host) signature, incompatible return type)
- recheck() docstring: lazy-pending and lazy-disabled caveats (recheck
  on pending-lazy advances health without building the platform; recheck
  on factory-disabled is insufficient — re-register is required)
- Test: register_lazy + await_first_validation + validator=False must
  not cache platform and must not retry factory on subsequent resolve()

https://claude.ai/code/session_01DRv6qahN7Jjt3Q4oxGBXkd

Author: claude

src/adcp/server/tenant_registry.py

@@ -115,6 +115,12 @@ class TenantRegistry:
     before ``unregister()`` was called completes safely — zombie-entry
     guards in both methods prevent stale writes after removal.
 
+    **Do not pass a TenantRegistry as a SubdomainTenantRouter.**
+    Both classes expose ``async def resolve(host)``, but the return types
+    are incompatible (:class:`TenantResolution` vs :class:`Tenant`).
+    Mypy will flag the mismatch; duck-typing and ``isinstance`` checks
+    will not.
+
     :param validator: Optional validation callable (sync or async).
         ``None`` → principal-token mode; validation always succeeds.
     :param default_serve_options: Optional dict of defaults to store for
@@ -364,9 +370,18 @@ async def register_lazy(
                         exc_info=True,
                     )
                     self._health[tenant_id] = "disabled"
+                    self._factories.pop(tenant_id, None)
                     return
-                self._platforms[tenant_id] = platform
-                self._health[tenant_id] = "healthy" if ok else "disabled"
+                if ok:
+                    self._platforms[tenant_id] = platform
+                    self._factories.pop(tenant_id, None)
+                    self._health[tenant_id] = "healthy"
+                else:
+                    # Validator rejected the platform — discard it and clear the
+                    # factory to mirror resolve() cold-path behavior: a disabled
+                    # lazy tenant needs register_lazy() + recheck() to recover.
+                    self._health[tenant_id] = "disabled"
+                    self._factories.pop(tenant_id, None)
 
     def unregister(self, tenant_id: str) -> None:
         """Remove a tenant from the registry.
@@ -402,6 +417,21 @@ async def recheck(self, tenant_id: str) -> None:
         The health state is updated before any exception propagates, so
         the state is always consistent even when the validator raises.
 
+        **Lazy-tenant caveats:**
+
+        * For a lazy tenant in ``pending`` state (factory never invoked),
+          ``recheck()`` runs the validator against the registered
+          ``agent_url`` only. If it succeeds, health advances to
+          ``healthy`` — but the platform has not been built yet.
+          :meth:`resolve_by_host` still returns ``None``; use the async
+          :meth:`resolve` which triggers the factory on first call.
+        * For a lazy tenant that reached ``disabled`` via factory failure,
+          the factory has been cleared. Calling ``recheck()`` alone is
+          insufficient to recover — the validator may succeed but there
+          is no platform to serve. To retry platform construction, call
+          :meth:`register_lazy` again with the same factory, then call
+          :meth:`recheck` if you also need to re-run the validator.
+
         :raises KeyError: when ``tenant_id`` is not registered.
         :raises Exception: re-raises any exception from the validator
             after updating the health state.
@@ -492,14 +522,18 @@ async def resolve(self, host: str) -> TenantResolution | None:
         Concurrent first-hit resolves for the same tenant serialize on
         the per-tenant lock — only one factory invocation occurs.
 
-        Returns ``None`` when:
+        Returns ``None`` when no tenant is registered for this host, or when
+        a lazy tenant's factory/validator fails on this call (health set to
+        ``disabled`` in both cases).
 
-        * No tenant is registered for this host.
-        * The factory raised (health is set to ``disabled``).
-        * The validator returned ``False`` (health is set to ``disabled``).
+        Returns a :class:`TenantResolution` — which may have
+        ``health="disabled"`` — when the platform was already built (eager
+        registration, lazy + ``await_first_validation=True``, or a previous
+        :meth:`resolve` call). **Always check ``result.health`` before
+        serving; never gate solely on ``result is None``.**
 
-        The caller is responsible for checking ``result.health`` and
-        gating traffic — the registry does not 503 automatically.
+        The caller is responsible for gating traffic — the registry does
+        not 503 automatically.
 
         :param host: Raw ``Host`` header value. Port suffixes are stripped;
             full URLs are also accepted. See :meth:`_normalize_host` for

tests/test_tenant_registry.py

@@ -694,6 +694,31 @@ async def factory(tid: str) -> Any:
     assert result.platform is new_platform
 
 
+@pytest.mark.asyncio
+async def test_register_lazy_await_first_validation_validator_false_does_not_cache() -> None:
+    """When validator returns False in register_lazy(await_first_validation=True),
+    platform must NOT be cached and factory must be cleared — mirrors resolve()
+    cold-path behavior so disabled tenants are consistent regardless of how they
+    were registered."""
+    platform = _mock_platform()
+
+    async def factory(tid: str) -> Any:
+        return platform
+
+    registry = TenantRegistry(validator=lambda tid, url: False)
+    await registry.register_lazy(
+        "acme",
+        agent_url="https://acme.example.com",
+        factory=factory,
+        await_first_validation=True,
+    )
+    assert registry.health("acme") == "disabled"
+    # Sync path must return None (platform not cached).
+    assert registry.resolve_by_host("acme.example.com") is None
+    # Async path must also return None (factory was cleared, no retry).
+    assert await registry.resolve("acme.example.com") is None
+
+
 @pytest.mark.asyncio
 async def test_resolve_factory_failure_does_not_retry_on_subsequent_calls() -> None:
     """After factory failure sets health=disabled, subsequent resolve() calls