@agentsdock/server 1.0.7-beta.5

package/server/team_mail_grants.py

@@ -0,0 +1,136 @@
+"""Bounded, secret-free durable chat-to-server mail grant projections.
+
+Only server-authored admission code may create these records. Runtime authority
+is deliberately absent: every use must intersect a fresh live capability.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+import re
+from typing import Any
+
+ROUTES_KEY = "provider_team_mail_routes"
+PENDING_KEY = "_pending_provider_team_mail_grant"
+MAX_ROUTES = 16
+ROUTE_RE = re.compile(r"mailgrant_[0-9a-f]{32}")
+REVISION_RE = re.compile(r"rev_[0-9a-f]{32}")
+ADMISSION_RE = re.compile(r"grant_admission_[0-9a-f]{32}")
+
+
+def text(value: Any, limit: int = 256) -> str:
+    return value if isinstance(value, str) and 0 < len(value) <= limit and not any(
+        ord(char) < 32 for char in value
+    ) else ""
+
+
+def normalize_routes(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list) or len(value) > MAX_ROUTES:
+        return []
+    result: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    route_ids: set[str] = set()
+    for raw in value:
+        if not isinstance(raw, dict):
+            return []
+        route_id, revision = text(raw.get("route_id")), text(raw.get("revision"))
+        team_id, target_id = text(raw.get("team_id")), text(raw.get("target_id"))
+        binding = raw.get("durable_server_binding")
+        # Runtime supplies a strictly projected identity-only binding. Keep
+        # this parser independent of credentials and transient run authority.
+        if (not ROUTE_RE.fullmatch(route_id) or not REVISION_RE.fullmatch(revision)
+                or not team_id or not target_id or (team_id, target_id) in seen
+                or route_id in route_ids or raw.get("recipient_kind") != "server"
+                or not isinstance(binding, dict)
+                or set(binding) != {"version", "team_id", "hub_id", "target_id", "server_identity", "lifecycle_id"}
+                or type(binding.get("version")) is not int or binding["version"] != 1
+                or any(not text(binding.get(key), 512) for key in (
+                    "team_id", "hub_id", "target_id", "server_identity", "lifecycle_id"))
+                or binding["team_id"] != team_id or binding["target_id"] != target_id
+                or not text(raw.get("display_name"))):
+            return []
+        seen.add((team_id, target_id))
+        route_ids.add(route_id)
+        result.append({
+            "route_id": route_id, "revision": revision,
+            "team_id": team_id, "target_id": target_id,
+            "recipient_kind": "server", "display_name": raw["display_name"],
+            "durable_server_binding": dict(binding),
+            "created_at": text(raw.get("created_at"), 40),
+            "updated_at": text(raw.get("updated_at"), 40),
+        })
+    return result
+
+
+def snapshot(value: Any) -> list[dict[str, str]]:
+    if not isinstance(value, list) or len(value) > MAX_ROUTES * 2:
+        return []
+    result: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for raw in value:
+        if not isinstance(raw, dict):
+            return []
+        if raw.get("kind") == "legacy_reference":
+            if (set(raw) != {"kind", "team_id", "target_id", "display_name"}
+                    or not all(text(raw.get(key)) for key in ("team_id", "target_id", "display_name"))):
+                return []
+            key = "legacy:" + raw["team_id"] + "\0" + raw["target_id"]
+            if key in seen:
+                return []
+            seen.add(key)
+            result.append(dict(raw))
+            continue
+        route_id, revision = text(raw.get("route_id")), text(raw.get("revision"))
+        if not ROUTE_RE.fullmatch(route_id) or not REVISION_RE.fullmatch(revision) or route_id in seen:
+            return []
+        seen.add(route_id)
+        result.append({"route_id": route_id, "revision": revision})
+    return result
+
+
+def admission_snapshot(mutation: dict[str, Any] | None, session: dict[str, Any] | None) -> list[dict[str, str]]:
+    return snapshot([
+        *snapshot(mutation["after"] if mutation else live_routes(session)),
+        *((mutation or {}).get("legacy_references") or []),
+    ])
+
+
+def pending(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict) or not ADMISSION_RE.fullmatch(text(value.get("admission_id"))):
+        return None
+    if value.get("event_type") not in {"turn_started", "turn_queued"}:
+        return None
+    before, after = normalize_routes(value.get("before")), normalize_routes(value.get("after"))
+    if before != value.get("before") or after != value.get("after") or before == after:
+        return None
+    return {"admission_id": value["admission_id"], "event_type": value["event_type"],
+            "before": before, "after": after}
+
+
+def live_routes(session: dict[str, Any] | None) -> list[dict[str, Any]]:
+    session = session or {}
+    if session.get("archived"):
+        return []
+    routes = normalize_routes(session.get(ROUTES_KEY, []))
+    if session.get(PENDING_KEY) is None:
+        return routes
+    staged = pending(session[PENDING_KEY])
+    # A malformed or concurrently replaced marker cannot prove permission.
+    return deepcopy(staged["before"]) if staged and routes == staged["after"] else []
+
+
+def intersect(session: dict[str, Any] | None, ceiling: Any) -> list[dict[str, Any]]:
+    allowed = {(item["route_id"], item["revision"]) for item in snapshot(ceiling) if "route_id" in item}
+    return [route for route in live_routes(session) if (route["route_id"], route["revision"]) in allowed]
+
+
+def settle(session: dict[str, Any], admission_id: str, *, accepted: bool) -> bool:
+    staged = pending(session.get(PENDING_KEY))
+    if staged is None or staged["admission_id"] != admission_id:
+        return False
+    if normalize_routes(session.get(ROUTES_KEY)) != staged["after"]:
+        # Never resurrect an older revision over a later policy mutation.
+        session[ROUTES_KEY] = []
+    elif not accepted:
+        session[ROUTES_KEY] = deepcopy(staged["before"])
+    session.pop(PENDING_KEY, None)
+    return True

package/server/team_mail_runtime.py

@@ -0,0 +1,302 @@
+"""Passive Mail stream ownership for one AgentsServer runtime.
+
+This module is dormant unless its owner explicitly enables the next-beta
+transport. One Member upstream serves all local subscribers. It owns a bounded
+dedicated reader thread, never an interactive executor or request lease. A
+failed upstream closes that cohort; client transport reconnects request a fresh
+scalar proof. There is no reconnect timer, Inbox read, or background refresh.
+"""
+from __future__ import annotations
+
+from contextlib import suppress
+import threading
+from typing import Any
+
+from agentsdock_team_hub.mail_hints import MailArrival, MailHintBroker, MailHintClosed
+from agentsdock_team_hub.mail_hint_streams import MailHintLease, MailHintScopeChanged, MailHintUnsupported, owned_mail_snapshot
+from agentsdock_team_hub.notification_hints import NotificationBroker, NotificationCursor, NotificationLease, owned_notification_snapshot
+
+
+class _MemberFeed:
+    def __init__(self, owner: RuntimeMailHints, realm: dict[str, Any]) -> None:
+        self.owner, self.realm = owner, dict(realm)
+        self.broker = MailHintBroker(max_subscriptions=16, max_per_recipient=16)
+        self.notifications = NotificationBroker(max_subscriptions=16, max_per_recipient=16)
+        self.version = 2 if owner._member_negotiated(realm, version=2) else 1
+        self.ready = threading.Event()
+        self.guard = threading.RLock()
+        self.stream = None
+        self.snapshot = None
+        self.closed = False
+        self.close_code = 1012
+        self.thread = threading.Thread(target=self._read, name="agentsdock-mail-upstream", daemon=True)
+
+    def _read(self) -> None:
+        try:
+            opener = (self.owner.runtime.client.open_notification_hint_stream if self.version == 2
+                      else self.owner.runtime.client.open_mail_hint_stream)
+            stream = opener(self.realm["connection_id"])
+            with self.guard:
+                if self.closed:
+                    stream.close()
+                    return
+                self.stream = stream
+            first = True
+            previous_mail = previous_bulletin = None
+            while True:
+                frame = stream.read()
+                if frame is None:
+                    break
+                cursor = (NotificationCursor.from_dict(frame["cursor"]) if self.version == 2
+                          else MailArrival.from_dict(frame["cursor"]))
+                mail = cursor.mail if self.version == 2 else cursor
+                if frame["hub_id"] != self.realm["hub_id"] or mail.team_id != self.realm["team_id"]:
+                    raise MailHintClosed("Member Mail stream changed realm")
+                if first:
+                    if frame["type"] != "snapshot":
+                        raise MailHintClosed("Member Mail stream omitted snapshot")
+                    with self.guard:
+                        self.snapshot = dict(frame["cursor"])
+                    first = False
+                elif frame["type"] != "hint" or (self.version == 1 and frame["cursor"].get("reset") is not False) or (
+                        self.version == 2 and any(frame["cursor"][lane].get("reset") is not False for lane in ("mail", "bulletin"))):
+                    raise MailHintClosed("Member Mail stream changed generation")
+                if mail != previous_mail:
+                    self.broker.publish(mail)
+                if self.version == 2:
+                    if mail != previous_mail:
+                        self.notifications.publish_mail(mail)
+                    if cursor.bulletin != previous_bulletin:
+                        self.notifications.publish_bulletin(cursor.bulletin)
+                    previous_bulletin = cursor.bulletin
+                previous_mail = mail
+                self.ready.set()
+        except Exception as exc:
+            # The local sockets close without serializing peer errors/tokens.
+            if getattr(exc, "status_code", None) in (401, 403):
+                self.close_code = 4403
+            elif getattr(exc, "status_code", None) in (404, 501):
+                self.close_code = 4406
+            elif isinstance(exc, ValueError) or getattr(exc, "code", None) == "remote_invalid":
+                self.close_code = 1008
+        finally:
+            self.close()
+
+    def close(self) -> None:
+        with self.guard:
+            self.closed = True
+            stream, self.stream = self.stream, None
+        self.broker.close()
+        self.notifications.close()
+        self.ready.set()
+        if stream is not None:
+            with suppress(Exception):
+                stream.close()
+
+
+class RuntimeMailHints:
+    def __init__(self, runtime: Any, *, enabled: bool = False) -> None:
+        self.runtime = runtime
+        self.enabled = enabled is True
+        self.guard = threading.RLock()
+        self.leases: set[MailHintLease | NotificationLease] = set()
+        self.pending = 0
+        self.member: _MemberFeed | None = None
+        self._scope: dict[str, Any] | None = None
+        self._generation = 0
+
+    def _member_negotiated(self, realm: dict[str, Any], *, version: int = 1) -> bool:
+        # The client getter is a bounded in-memory authenticated health receipt,
+        # not discovery I/O. Missing/expired/other-certificate receipts fail shut.
+        getter = getattr(self.runtime.client, "notification_hint_capability" if version == 2 else "mail_hint_capability", None)
+        if not callable(getter):
+            return False
+        try:
+            return getter(realm["connection_id"], realm["certificate_fingerprint"]) is True
+        except Exception:
+            return False
+
+    def _capture(self, team_id: str | None = None, *, version: int = 1) -> dict[str, Any]:
+        if not self.enabled or self.runtime._completion_closing:
+            raise MailHintClosed("Mail notifications are unavailable")
+        realms = self.runtime.team_realms()
+        choices = [realm for realm in realms if team_id is None or realm["team_id"] == team_id]
+        if len(choices) != 1:
+            raise MailHintScopeChanged("Mail notification realm is unavailable")
+        with self.guard:
+            generation = self._generation
+        realm = {**choices[0], "epoch": self.runtime._team_authority_epoch,
+                "generation": generation, "admission_epoch": getattr(self.runtime, "_host_admission_epoch", 0)}
+        # Cache only metadata even if capability is not negotiated yet. Later
+        # health renders can inspect the receipt without another realm DB read.
+        with self.guard:
+            if realm["generation"] == self._generation:
+                self._scope = realm
+        if realm["realm"] == "secure_peer" and not self._member_negotiated(realm, version=version):
+            raise MailHintUnsupported("Member Mail notifications are not negotiated")
+        return realm
+
+    def capability(self, *, version: int = 1) -> dict[str, Any]:
+        result = {"enabled": False, "version": version, "websocket_path": "/api/team-mail-hints/events",
+                  "websocket_protocol": f"agentsdock.team-mail-hints.v{version}", "mailbox_coverage": True,
+                  "mailbox": None}
+        if version == 2:
+            result["bulletin_coverage"] = True
+        if not self.enabled:
+            return result
+        try:
+            # Metadata discovery is cached, not an arrival query in health.
+            with self.guard:
+                scope = self._scope
+            if scope is None:
+                scope = self._capture(version=version)
+                with self.guard:
+                    if scope["generation"] != self._generation:
+                        return result
+                    self._scope = scope
+            if scope["realm"] == "secure_peer" and not self._member_negotiated(scope, version=version):
+                return result
+            result.update(enabled=True, mailbox={"hub_id": scope["hub_id"],
+                "team_id": scope["team_id"], "recipient_server_id": None})
+        except Exception:
+            pass
+        return result
+
+    def _authorize(self, realm: dict[str, Any], store=None, *, version: int = 1) -> None:
+        runtime = self.runtime
+        if (not self.enabled or runtime._completion_closing
+                or runtime._team_authority_epoch != realm["epoch"]
+                or realm["generation"] != self._generation):
+            raise MailHintClosed("Mail notification authority changed")
+        if realm["realm"] == "host":
+            if (runtime._host_admission_closed or runtime._hub_store is not store
+                    or store.hub_id != realm["hub_id"]
+                    or runtime._host_admission_epoch != realm["admission_epoch"]):
+                raise MailHintClosed("Host Mail admission closed")
+        else:
+            if runtime._host_role_active:
+                raise MailHintClosed("Member Mail authority changed")
+            if not self._member_negotiated(realm, version=version):
+                raise MailHintUnsupported("Member Mail notifications are not negotiated")
+            active = runtime._require_active_proxy_connection(realm["connection_id"])
+            if (active.get("status") != "connected" or "teamspace.read" not in active.get("scopes", ())
+                    or any(active.get(key) != realm.get(key) for key in (
+                        "hub_id", "team_id", "host_server_identity", "certificate_fingerprint"))):
+                raise MailHintClosed("Member Mail binding changed")
+
+    def subscribe(self, team_id: str, previous_cursor=None, *, version: int = 1) -> MailHintLease | NotificationLease:
+        if type(version) is not int or version not in (1, 2):
+            raise ValueError("Unsupported notification version")
+        realm = self._capture(team_id, version=version)
+        with self.guard:
+            if self.pending + len(self.leases) >= 16:
+                raise MailHintClosed("Local Mail stream capacity reached")
+            self.pending += 1
+        subscription = lease = None
+        feed = None
+        try:
+            if realm["realm"] == "host":
+                store = self.runtime._hub_store
+                self._authorize(realm, store, version=version)
+                claims = store.local_agent_mail_claims(team_id)
+                owned = owned_notification_snapshot if version == 2 else owned_mail_snapshot
+                _owned, retained = owned(store, claims, team_id, previous_cursor)
+                subscriber = store.subscribe_team_notifications if version == 2 else store.subscribe_team_mail_arrivals
+                subscription, snapshot = subscriber(claims, team_id, previous_cursor=retained)
+
+                def authorize():
+                    self._authorize(realm, store, version=version)
+                    live = store.team_mail_arrival_snapshot(store.local_agent_mail_claims(team_id), team_id)
+                    mail_snapshot = snapshot["mail"] if version == 2 else snapshot
+                    if live["recipient_server_id"] != mail_snapshot["recipient_server_id"]:
+                        raise MailHintClosed("Host Mail recipient changed")
+
+                expires_at = None  # Local control is role-owned, not a bearer lease.
+            else:
+                self._authorize(realm, version=version)
+                with self.guard:
+                    feed = self.member
+                    if feed is not None and not feed.closed and feed.realm == realm and version > feed.version:
+                        # Retire an older negotiated cohort before opening its
+                        # replacement. Existing v1 sockets reconnect onto the
+                        # same v2 feed; never keep both upstreams alive.
+                        feed.close()
+                    if feed is None or feed.closed:
+                        feed = _MemberFeed(self, realm)
+                        self.member = feed
+                        feed.thread.start()
+                    elif feed.realm != realm or version > feed.version:
+                        raise MailHintClosed("Member Mail generation changed")
+                if not feed.ready.wait(timeout=15) or feed.closed or feed.snapshot is None:
+                    if feed.close_code == 4406:
+                        raise MailHintUnsupported("Member Mail notifications are unsupported")
+                    if feed.close_code == 4403:
+                        raise MailHintScopeChanged("Member Mail authority is unavailable")
+                    if feed.close_code == 1008:
+                        raise ValueError("Member Mail protocol is unavailable")
+                    raise MailHintClosed("Member Mail stream unavailable")
+                # Subscribe BEFORE the per-desktop scalar proof. An upstream
+                # cursor alone cannot validate this desktop's retained anchor.
+                feed_mail = feed.snapshot["mail"] if feed.version == 2 else feed.snapshot
+                broker = feed.notifications if version == 2 else feed.broker
+                subscription = broker.subscribe(team_id, feed_mail["recipient_server_id"])
+                snapshotter = (self.runtime.client.team_notification_hint_snapshot if version == 2
+                               else self.runtime.client.team_mail_hint_snapshot)
+                result = snapshotter(realm["connection_id"], previous_cursor)
+                snapshot = result["cursor"]
+                mail_snapshot = snapshot["mail"] if version == 2 else snapshot
+                if result["hub_id"] != realm["hub_id"] or mail_snapshot["recipient_server_id"] != subscription.mailbox[1]:
+                    raise MailHintClosed("Member Mail snapshot changed realm")
+
+                def authorize():
+                    self._authorize(realm, version=version)
+                    if feed.closed or self.member is not feed:
+                        raise MailHintClosed("Member Mail upstream closed")
+
+                active = self.runtime._require_active_proxy_connection(realm["connection_id"])
+                expires_at = float(active["certificate_expires_at"])
+
+            def retired():
+                with self.guard:
+                    self.leases.discard(lease)
+                    last = not self.leases and not self.pending
+                    old = self.member if last else None
+                    if last:
+                        self.member = None
+                if old is not None:
+                    old.close()
+
+            lease_type = NotificationLease if version == 2 else MailHintLease
+            lease = lease_type(subscription, snapshot, hub_id=realm["hub_id"],
+                authorize=authorize, expires_at=expires_at, on_close=retired,
+                close_code=(lambda: feed.close_code) if feed is not None else None)
+            with self.guard:
+                self.leases.add(lease)
+            lease.revalidate()
+            return lease
+        except BaseException:
+            if lease is not None:
+                lease.close()
+            elif subscription is not None:
+                subscription.close()
+            raise
+        finally:
+            with self.guard:
+                self.pending -= 1
+                if not self.pending and not self.leases:
+                    old, self.member = self.member, None
+                else:
+                    old = None
+            if old is not None:
+                old.close()
+
+    def invalidate(self) -> None:
+        with self.guard:
+            self._generation += 1
+            self._scope = None
+            leases = tuple(self.leases)
+            old, self.member = self.member, None
+        if old is not None:
+            old.close()
+        for lease in leases:
+            lease.close()

package/server/team_mail_websocket.py

@@ -0,0 +1,211 @@
+"""Authenticated local passive Mail socket, outside managed Hub ASGI drains.
+
+No global subscription copies, mailbox fetches, shared executor waits or idle
+queries. At most sixteen dedicated Mail workers each own one coalescing broker
+lease and one serial bounded ASGI writer. Production remains feature-gated.
+"""
+from __future__ import annotations
+
+import asyncio
+from contextlib import suppress
+import json
+import threading
+import uuid
+from typing import Any, Callable
+
+from agentsdock_team_hub.mail_hints import MAIL_IDENTIFIER_RE, MailArrival
+from agentsdock_team_hub.notification_hints import NotificationCursor
+
+MAIL_WEBSOCKET_PROTOCOL = "agentsdock.team-mail-hints.v1"
+NOTIFICATION_WEBSOCKET_PROTOCOL = "agentsdock.team-mail-hints.v2"
+_SLOTS = threading.BoundedSemaphore(16)
+
+
+class _MailSocketWriter:
+    """Bridge one dedicated worker to an actual event-loop Task completion.
+
+    A cancelled concurrent Future is not proof its asyncio Task settled. Keep
+    the worker's lease/slot until a Task done callback proves completion, even
+    if an ASGI implementation resists cancellation. That consumes only this
+    bounded Mail capacity, never a control request slot or event-loop wait.
+    """
+    def __init__(self, loop, *, timeout=5):
+        self.loop, self.timeout = loop, timeout
+        self.guard = threading.Lock()
+        self.stopped = False
+        self.task = None
+
+    def cancel(self):
+        with self.guard:
+            self.stopped = True
+
+        def cancel_task():
+            with self.guard:
+                task = self.task
+            if task is not None:
+                task.cancel()
+        with suppress(RuntimeError):
+            self.loop.call_soon_threadsafe(cancel_task)
+
+    def send(self, coroutine_factory):
+        settled = threading.Event()
+        outcome = {}
+
+        def finished(task):
+            try:
+                outcome["result"] = task.result()
+            except BaseException as exc:
+                outcome["error"] = exc
+            with self.guard:
+                if self.task is task:
+                    self.task = None
+            settled.set()
+
+        def start():
+            try:
+                task = self.loop.create_task(coroutine_factory())
+                # This callback also runs when cancelled before its first step.
+                task.add_done_callback(finished)
+                with self.guard:
+                    self.task = task
+                    stopped = self.stopped
+                if stopped:
+                    task.cancel()
+            except BaseException as exc:
+                outcome["error"] = exc
+                settled.set()
+
+        self.loop.call_soon_threadsafe(start)
+        if not settled.wait(self.timeout):
+            self.cancel()
+        settled.wait()
+        if "error" in outcome:
+            raise outcome["error"]
+
+
+async def serve_team_mail_hints(ws: Any, runtime: Any, *, server_identity: str,
+                                authorized: Callable[[], bool], protocols: list[str]) -> None:
+    protocol = (NOTIFICATION_WEBSOCKET_PROTOCOL if NOTIFICATION_WEBSOCKET_PROTOCOL in protocols
+                else MAIL_WEBSOCKET_PROTOCOL if MAIL_WEBSOCKET_PROTOCOL in protocols else None)
+    version = 2 if protocol == NOTIFICATION_WEBSOCKET_PROTOCOL else 1
+    await ws.accept(subprotocol=protocol)
+    if not authorized() or ws.query_params:
+        await ws.close(code=4401)
+        return
+    capability = (getattr(runtime, "team_notification_hint_capability", lambda: {}) if version == 2
+                  else runtime.team_mail_hint_capability)
+    if protocol is None or not capability().get("enabled"):
+        await ws.close(code=4406)
+        return
+    if not _SLOTS.acquire(blocking=False):
+        await ws.close(code=1013)
+        return
+    loop = asyncio.get_running_loop()
+    done = asyncio.Event()
+    stopped = threading.Event()
+    guard = threading.Lock()
+    holder: dict[str, Any] = {}
+    writer = _MailSocketWriter(loop)
+    stream_id = uuid.uuid4().hex
+    worker = None
+    try:
+        raw = await asyncio.wait_for(ws.receive_text(), timeout=5)
+        if len(raw.encode("utf-8")) > 4096:
+            raise ValueError("Mail subscription frame is too large")
+        request = json.loads(raw)
+        if (not isinstance(request, dict) or set(request) != {"version", "team_id", "previous_cursor"}
+                or type(request["version"]) is not int or request["version"] != version
+                or not isinstance(request["team_id"], str) or MAIL_IDENTIFIER_RE.fullmatch(request["team_id"]) is None):
+            raise ValueError("Mail subscription frame is invalid")
+        if request["previous_cursor"] is not None:
+            previous = (NotificationCursor.from_dict(request["previous_cursor"]) if version == 2
+                        else MailArrival.from_dict(request["previous_cursor"]))
+            if previous.mailbox[0] != request["team_id"]:
+                await ws.close(code=4403)
+                return
+
+        def abort():
+            stopped.set()
+            writer.cancel()
+
+        def run():
+            lease = None
+            try:
+                subscriber = (runtime.subscribe_team_notification_hints if version == 2
+                              else runtime.subscribe_team_mail_hints)
+                lease = subscriber(request["team_id"], request["previous_cursor"])
+                with guard:
+                    holder["lease"] = lease
+                lease.set_aborter(abort)
+                if stopped.is_set():
+                    return
+
+                def write(kind, cursor):
+                    async def send():
+                        if stopped.is_set() or lease.closed or not authorized():
+                            raise RuntimeError("Mail socket authority changed")
+                        frame = {"type": kind, "server_identity": server_identity,
+                                 "hub_id": lease.hub_id, "stream_id": stream_id, "cursor": cursor}
+                        data = json.dumps(frame, separators=(",", ":"))
+                        if len(data.encode("utf-8")) > 4096:
+                            raise ValueError("Mail socket metadata is too large")
+                        await ws.send_text(data)
+                    writer.send(send)
+
+                lease.write(lambda cursor: write("snapshot", cursor), lease.snapshot)
+                while not stopped.is_set():
+                    arrival = lease.take()
+                    if arrival is None:
+                        break
+                    lease.write(lambda cursor: write("hint", cursor), arrival.as_dict(reset=False))
+            except asyncio.CancelledError:
+                pass
+            except Exception as exc:
+                holder["close_code"] = (4403 if getattr(exc, "status_code", None) in (401, 403)
+                    else 4406 if getattr(exc, "status_code", None) in (404, 501)
+                    else 1008 if isinstance(exc, ValueError) or getattr(exc, "code", None) == "remote_invalid"
+                    else 1012)
+            finally:
+                if lease is not None:
+                    holder.setdefault("close_code", lease.close_code)
+                    lease.close()
+                _SLOTS.release()
+                with suppress(RuntimeError):
+                    loop.call_soon_threadsafe(done.set)
+
+        pending_worker = threading.Thread(target=run, name="agentsdock-mail-local", daemon=True)
+        pending_worker.start()
+        worker = pending_worker
+        receive = asyncio.create_task(ws.receive_text())
+        finished = asyncio.create_task(done.wait())
+        try:
+            completed, _pending = await asyncio.wait((receive, finished), return_when=asyncio.FIRST_COMPLETED)
+            if receive in completed:
+                # Subscriptions have no command channel or acknowledgement.
+                receive.result()
+                await ws.close(code=1008)
+            else:
+                await ws.close(code=holder.get("close_code", 1012))
+        finally:
+            for task in (receive, finished):
+                task.cancel()
+                with suppress(BaseException):
+                    await task
+    except (ValueError, asyncio.TimeoutError):
+        with suppress(Exception):
+            await ws.close(code=1008)
+    except Exception:
+        pass
+    finally:
+        stopped.set()
+        with guard:
+            lease = holder.get("lease")
+        if lease is not None:
+            lease.cancel()
+        if worker is not None:
+            # No join/default executor on the event loop. The socket's bounded
+            # worker signals completion after closing its subscription.
+            with suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(done.wait(), timeout=15)
+        else:
+            _SLOTS.release()