@securecoms/agent-bridge 0.37.0 → 0.39.0

package/connectors/hermes/adapter.py

@@ -13,6 +13,9 @@ Flow:
               -->  Hermes gateway  -->  LLM  -->  send()  -->  daemon  --MLS-->  owner
     outbound: the agent's reply is delivered to send(), which POSTs it to the
               daemon's /v1/send; the daemon encrypts and relays it.
+    ack:      an inbound frame is acked to the daemon once Hermes has durably
+              accepted its turn (see _receive_message); after that, crash
+              recovery is Hermes's own (its persisted active-turn marker).
 
 This is the universal daemon-client pattern wearing a Hermes BasePlatformAdapter
 shim. The same daemon serves any framework; only this thin shim is
@@ -60,6 +63,7 @@ import json
 import logging
 import os
 import time
+from collections import OrderedDict
 from datetime import datetime
 from typing import Any, Dict, Optional
 
@@ -108,6 +112,57 @@ _REFUSAL_NOTICE_SENT: set = set()
 _REFUSAL_NOTICE_MAX = 4096
 # Inbound frames seen without an authorization block (daemon too old).
 _FRAMES_WITHOUT_AUTHORIZATION = 0
+# Inbound attachments dropped by securecoms_transport.scan_inbound_attachments.
+_ATTACHMENTS_DROPPED = 0
+# Unknown-channel lookups (review r2): one /v1/channels refresh per unknown
+# channel per minute, each bounded so a slow daemon cannot stall a turn.
+_UNKNOWN_CHANNEL_RETRY_S = 60.0
+_UNKNOWN_CHANNEL_LOOKUPS_MAX = 4096
+_CHANNEL_REFRESH_TIMEOUT_S = 5.0
+
+# Ack on durable acceptance (see _receive_message). Hermes's handle_message
+# returns as soon as it has spawned the turn as a background task, so an ack
+# sent when it returned could reach the daemon before Hermes held the message
+# anywhere durable: a crash then lost it (the daemon never redelivers an acked
+# row). Acking after the WHOLE turn is wrong too: the daemon delivers one
+# message per channel and the next only after the ack (ws-server.ts F2), which
+# would hold back /stop, /approve and clarify answers until the turn ended, and
+# Hermes already resumes a crashed turn from its own durable marker, so a
+# daemon redelivery on top would run it twice. So the ack goes out once Hermes
+# has persisted its active-turn marker for this event, or finished with it.
+# Redeliveries are deduped by message_id in a bounded ledger.
+_DEDUP_MAX_ENTRIES = 2048
+_DEDUP_TTL_S = 600.0
+# How long to wait for Hermes to accept a turn that starts its own session
+# task before acking anyway (holding the ack holds the channel, F2).
+_ACCEPT_WAIT_S = 10.0
+_ACCEPT_POLL_S = 0.02
+# One warning per process when this Hermes lacks the acceptance signal.
+_TURN_TRACKING_WARNED = False
+
+# H0: Hermes session key -> [(ledger token, runner key)] for every ungranted
+# event dispatched into that session and not yet released. Module-level, like
+# _TURN_AUTHZ, so a replaced adapter instance or a task cancelled before its
+# first step cannot strand a count: the next completion that finds the session
+# idle releases it, whichever adapter instance observes it.
+_ATTACHED: Dict[Any, list] = {}
+# One warning per process each: an idle input Hermes does not expose (so no
+# count can be released), and H0.2b's shared room sessions.
+_IDLE_INPUTS_WARNED = False
+_SHARED_ROOMS_WARNED = False
+
+# Hermes's Signal adapter mapping (_MEDIA_TYPE_BY_MIME_PREFIX): first matching
+# prefix wins; anything else is a DOCUMENT so Hermes surfaces the file path.
+_MEDIA_TYPE_BY_MIME_PREFIX = (("audio/", "VOICE"), ("image/", "PHOTO"), ("video/", "VIDEO"))
+
+
+def _message_type_for_mimes(mimes):
+    name = next(
+        (n for prefix, n in _MEDIA_TYPE_BY_MIME_PREFIX if any(m.startswith(prefix) for m in mimes)),
+        "DOCUMENT",
+    )
+    return getattr(MessageType, name, MessageType.TEXT)
+
 
 _PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
 _BINDING_PATH = os.path.join(_PLUGIN_DIR, "securecoms.binding.json")
@@ -146,6 +201,69 @@ def _error_class(error: object) -> str:
     return name
 
 
+class _DeliveryLedger:
+    """Bounded record of inbound message_ids that are in flight or done.
+
+    begin() answers "new" (record it in flight and dispatch), "in_flight" (a
+    redelivery of a turn still running: do not dispatch, the original's ack
+    covers it) or "done" (already finished: ack again, no turn). An in-flight
+    entry is never evicted or expired, since dropping it would let a
+    redelivery run the turn twice; the daemon keeps at most one message per
+    channel in flight, so those stay few. Done entries expire after ttl_s and
+    the oldest go first once the ledger holds more than max_entries, except
+    pinned ones (acked by us but never delivered to the daemon).
+    """
+
+    def __init__(self, max_entries: int, ttl_s: float, now) -> None:
+        self._max = max_entries
+        self._ttl = ttl_s
+        self._now = now
+        # message_id -> monotonic finish time, or None while in flight.
+        self._entries: "OrderedDict[str, Optional[float]]" = OrderedDict()
+        # Done ids whose ack never reached the daemon: kept past TTL and LRU,
+        # so a redelivery after a long outage is acked, never re-run.
+        self._pinned: set = set()
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def begin(self, message_id: str) -> str:
+        self._prune()
+        if message_id in self._entries:
+            return "in_flight" if self._entries[message_id] is None else "done"
+        self._entries[message_id] = None
+        return "new"
+
+    def finish(self, message_id: str) -> None:
+        self._entries.pop(message_id, None)
+        self._entries[message_id] = self._now()
+        self._prune()
+
+    def forget(self, message_id: str) -> None:
+        self._entries.pop(message_id, None)
+        self._pinned.discard(message_id)
+
+    def pin(self, message_id: str) -> None:
+        if message_id in self._entries:
+            self._pinned.add(message_id)
+
+    def unpin(self, message_id: str) -> None:
+        self._pinned.discard(message_id)
+
+    def _prune(self) -> None:
+        now = self._now()
+        excess = len(self._entries) - self._max
+        for mid, done_at in list(self._entries.items()):
+            if done_at is None or mid in self._pinned:
+                continue
+            if now - done_at > self._ttl:
+                del self._entries[mid]
+                excess -= 1
+            elif excess > 0:
+                del self._entries[mid]
+                excess -= 1
+
+
 def _read_file_text(path: str) -> str:
     with open(path, "r") as f:
         return f.read()
@@ -180,16 +298,35 @@ class SecureComsAdapter(BasePlatformAdapter):
         # SEC-06 #18: reply_to -> {"seq": n, "pending": text|None}; see _block_key.
         self._block_seq: Dict[str, Dict[str, Any]] = {}
         self._session = None  # aiohttp.ClientSession - the CURRENT connected link
+        # channel_id -> monotonic time of the last lookup for an unknown channel.
+        self._unknown_channel_lookups: Dict[str, float] = {}
         self._ws = None
         self._recv_task: Optional[asyncio.Task] = None
         self._tick_task: Optional[asyncio.Task] = None
         self._stopped = False  # set by disconnect(); stops the reconnect supervisor
         self._hold_reason: Optional[str] = None  # None == not holding
+        # Inbound message_ids awaiting their ack or acked, and the tasks that
+        # each wait for Hermes to accept one turn and then send its ack.
+        self._deliveries = _DeliveryLedger(_DEDUP_MAX_ENTRIES, _DEDUP_TTL_S, time.monotonic)
+        self._ack_waiters: set = set()
+        # message_ids whose ack was dropped (no link, or the send raised), in
+        # order; flushed on the next successful connect.
+        self._unsent_acks: "OrderedDict[str, None]" = OrderedDict()
 
         self._status = securecoms_transport.ChannelStatusManager(
             self._send_status_frame, now=time.monotonic
         )
 
+        # H0.2b: Hermes shares ONE room session across every sender when
+        # group_sessions_per_user is off; every room turn is then ungranted.
+        self._room_sessions_shared = self._group_sessions_shared()
+
+    def _group_sessions_shared(self) -> bool:
+        extra = getattr(self.config, "extra", None)
+        if not isinstance(extra, dict):
+            return True
+        return extra.get("group_sessions_per_user", True) is not True
+
     @property
     def name(self) -> str:
         return "SecureComs"
@@ -211,6 +348,14 @@ class SecureComsAdapter(BasePlatformAdapter):
         """
         del is_reconnect  # accepted for contract parity; nothing to preserve
         self._stopped = False
+        self._room_sessions_shared = self._group_sessions_shared()
+        global _SHARED_ROOMS_WARNED
+        if self._room_sessions_shared and not _SHARED_ROOMS_WARNED:
+            _SHARED_ROOMS_WARNED = True
+            logger.warning(
+                "SecureComs: group_sessions_per_user is off, so a room shares one Hermes session "
+                "across senders; every room turn runs without tools"
+            )
 
         # BINDING-STABILITY fold: resolve bound_identity here, ONCE, for the
         # entire process life of this adapter instance. Every subsequent
@@ -291,6 +436,7 @@ class SecureComsAdapter(BasePlatformAdapter):
         self._token = target.token
         self._leave_hold()
         await self._send_hello()
+        await self._flush_unsent_acks()
         await self._refresh_channels()
         return True
 
@@ -389,19 +535,33 @@ class SecureComsAdapter(BasePlatformAdapter):
                     await task
                 except asyncio.CancelledError:
                     pass
+        # Unsent acks are dropped on purpose: the daemon re-buffers whatever is
+        # unacked when the socket closes and redelivers it to the next consumer.
+        waiters = list(self._ack_waiters)
+        for task in waiters:
+            task.cancel()
+        if waiters:
+            await asyncio.gather(*waiters, return_exceptions=True)
+        self._ack_waiters.clear()
         await self._teardown_link()
 
+    async def _fetch_channels(self) -> None:
+        async with self._session.get(
+            f"{self.bridge_url}/v1/channels", headers=self._auth()
+        ) as r:
+            if r.status == 200:
+                for c in await r.json():
+                    self._channels[c["channel_id"]] = {
+                        # Member-chosen and reaches the prompt (chat_name,
+                        # get_chat_info): sanitized once, here (R3).
+                        "name": securecoms_transport.display_name(c.get("name")) or c["channel_id"],
+                        "is_dm": bool(c.get("is_dm")),
+                    }
+
     async def _refresh_channels(self) -> None:
         try:
-            async with self._session.get(
-                f"{self.bridge_url}/v1/channels", headers=self._auth()
-            ) as r:
-                if r.status == 200:
-                    for c in await r.json():
-                        self._channels[c["channel_id"]] = {
-                            "name": c.get("name") or c["channel_id"],
-                            "is_dm": bool(c.get("is_dm")),
-                        }
+            # Bounded: an inbound turn may wait on this (review r2).
+            await asyncio.wait_for(self._fetch_channels(), timeout=_CHANNEL_REFRESH_TIMEOUT_S)
         except Exception as e:
             logger.debug(
                 "SecureComs: channel refresh failed (error_class=%s)",
@@ -452,34 +612,377 @@ class SecureComsAdapter(BasePlatformAdapter):
                 except (ValueError, TypeError):
                     continue
                 if frame.get("type") == "message":
-                    await self._dispatch(frame)
-                    # at-least-once: ack every accepted frame, dropped or not
-                    # (echo-guard drops still need the daemon to stop
-                    # redelivering them).
-                    try:
-                        await self._ws.send_json(
-                            {"type": "ack", "message_id": frame.get("message_id")}
-                        )
-                    except Exception as e:
-                        logger.warning(
-                            "SecureComs: ack failed (error_class=%s)",
-                            _error_class(e),
-                        )
+                    await self._receive_message(frame)
             elif msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR):
                 return  # WS closed → supervisor reconnects
 
-    async def _dispatch(self, frame: Dict[str, Any]) -> None:
-        if not self._message_handler:
+    async def _receive_message(self, frame: Dict[str, Any]) -> None:
+        """At-least-once intake for one `message` frame.
+
+        Ack timing:
+          - dropped before Hermes (echo guard, refused ungranted turn, no
+            handler): at once, as before, so the daemon stops redelivering;
+          - handled inline by Hermes, queued behind a busy session, or not
+            queued for a turn (a /stop, an /approve, a clarify answer, a
+            follow-up, a steer, a queue-mode debounce): at once;
+          - starting its own Hermes turn: once Hermes has durably accepted
+            it (_await_acceptance), at most _ACCEPT_WAIT_S later.
+        The wait runs in its own task, so this pump keeps reading and other
+        channels keep flowing; handle_message is still called here, in frame
+        order. A redelivery of an id still waiting is not dispatched (the
+        original's ack covers it); one already acked is acked again with no
+        turn. A frame without a message_id is not deduped (unchanged).
+        """
+        mid = frame.get("message_id")
+        key = mid if isinstance(mid, str) and mid else None
+        if key is not None:
+            state = self._deliveries.begin(key)
+            if state == "done":
+                await self._send_ack(mid)
+                return
+            if state == "in_flight":
+                return
+        try:
+            event = await self._dispatch(frame)
+        except BaseException:
+            # Unacked, exactly as before: the supervisor reconnects and the
+            # daemon redelivers, which must then run the turn again.
+            if key is not None:
+                self._deliveries.forget(key)
+            raise
+        if event is None or not self._awaits_acceptance(event):
+            if key is not None:
+                self._deliveries.finish(key)
+            await self._send_ack(mid)
+            return
+        task = asyncio.create_task(self._ack_on_acceptance(mid, key, event))
+        self._ack_waiters.add(task)
+        task.add_done_callback(self._ack_waiters.discard)
+
+    # Hermes internals this relies on (v2026.9.24), all read-only:
+    #   - MessageEvent._gateway_accepted: reset to False on entry to
+    #     handle_message (gateway/platforms/base.py:3953), True when the event
+    #     starts a session task (:3990) or is queued for one (:4052, :4064,
+    #     gateway/run_busy.py:88-97 _enqueue_fifo).
+    #   - _event_session_key / _active_sessions / _session_tasks: read before
+    #     handle_message to tell "starts its own turn" from "queued behind a
+    #     busy session" (base.py:2488, 1924, 1928, 3983-3987).
+    #   - MessageEvent._gateway_active_turn_token: set by the runner's
+    #     _mark_durable_active_turn (gateway/run_inbound.py:1754-1767) only
+    #     after SessionStore.mark_turn_active has persisted the marker
+    #     (gateway/session_lifecycle.py:115-145, write before publish), at
+    #     gateway/run_turn.py:2090. An unclean restart promotes the marker to
+    #     resume_pending (session_lifecycle.py:156-185) and resumes the
+    #     session (gateway/run_startup.py:575-620).
+    #   - on_processing_complete(event, outcome): called on every exit of
+    #     _process_message_background (base.py:4520-4540).
+    # Without _gateway_accepted this degrades to acking at dispatch, the old
+    # behaviour, with one warning.
+    #
+    # Accepted gaps (each no worse than acking at dispatch, as main does):
+    #   - The marker is written at run_turn.py:2090, but the user's message
+    #     reaches the transcript only in _persist_turn_start just before the
+    #     first LLM call (agent/turn_context.py:963, called at :1152). In
+    #     between: the transcript load, _hmwa_run_session_hygiene (which can
+    #     make a compression LLM call, run_turn.py:1346) and the agent build.
+    #     A crash there resumes the session with an empty-text event
+    #     (run_startup.py:610) and the acked message is lost.
+    #   - A clean shutdown while the session's agent is still
+    #     _AGENT_PENDING_SENTINEL (before the agent build) does not mark it
+    #     resume_pending (gateway/run_shutdown.py:858-871), and a clean start
+    #     discards orphan markers (session_lifecycle.py:189): acked, then lost.
+    #   - A follow-up queued behind a busy session, a queue-mode debounce
+    #     (base.py:3766-3796) or a steer is acked at once: Hermes holds it
+    #     only in memory until its own turn starts (its pending queue is saved
+    #     on clean shutdown only).
+
+    def _awaits_acceptance(self, event: Any) -> bool:
+        accepted = getattr(event, "_gateway_accepted", None)
+        if not isinstance(accepted, bool):
+            self._warn_no_turn_tracking()
+            return False
+        # Queued behind a busy session: not durable until its own turn
+        # starts, which may be minutes away, so waiting buys nothing and
+        # would hold the channel (a /stop typed next would wait the bound).
+        return accepted and not getattr(event, "_securecoms_session_was_busy", False)
+
+    def _session_was_busy(self, event: Any) -> bool:
+        """Read BEFORE handle_message: does this event's Hermes session
+        already have a live owner? Mirrors handle_message's own check
+        (base.py:3983-3987): a guard in _active_sessions whose owner task in
+        _session_tasks has not exited (a done owner is healed on entry)."""
+        key_fn = getattr(self, "_event_session_key", None)
+        active = getattr(self, "_active_sessions", None)
+        if not callable(key_fn) or not isinstance(active, dict):
+            return False
+        try:
+            key = key_fn(event)
+        except Exception:
+            return False
+        if key not in active:
+            return False
+        tasks = getattr(self, "_session_tasks", None)
+        task = tasks.get(key) if isinstance(tasks, dict) else None
+        done = getattr(task, "done", None)
+        return not (callable(done) and done())
+
+    @staticmethod
+    def _warn_no_turn_tracking() -> None:
+        global _TURN_TRACKING_WARNED
+        if _TURN_TRACKING_WARNED:
+            return
+        _TURN_TRACKING_WARNED = True
+        logger.warning(
+            "SecureComs: Hermes turn acceptance signal unavailable; acking at dispatch "
+            "(a crash before the turn starts can lose that message)"
+        )
+
+    async def on_processing_complete(self, event: Any, outcome: Any) -> None:
+        """Hermes lifecycle hook (base.py:3448): record the outcome on the
+        event for _await_acceptance, run the H0 release check, then keep the
+        base behaviour."""
+        try:
+            event._securecoms_outcome = getattr(outcome, "name", None) or "UNKNOWN"
+        except Exception:
+            pass
+        try:
+            self._settle_on_completion(event)
+        except Exception as e:
+            logger.warning(
+                "SecureComs: ungranted-turn release check failed; its sender stays without tools "
+                "(error_class=%s)",
+                _error_class(e),
+            )
+        base = getattr(super(), "on_processing_complete", None)
+        if callable(base):
+            await base(event, outcome)
+
+    # ── H0: ungranted turns in flight ─────────────────────────────────────
+    #
+    # Hermes v2026.9.24 (read on the Mini): on_processing_complete fires once
+    # per started task, for the event that started it only (base.py:4520-4540),
+    # before the debounce flush and the pending pop. An event can reach a turn
+    # without starting it (redirect, steer, base merge, runner FIFO, debounce),
+    # and an event that DID start its own base task can still be parked by the
+    # runner behind a pending sentinel (run_inbound.py:690-697) or swapped for
+    # an orphaned FIFO head, so its own completion does not prove its text has
+    # run. Every ungranted event's count is therefore attached to its Hermes
+    # session at dispatch and comes down only when the event never reached
+    # Hermes, or at a moment its session is idle: no other running task, no
+    # command guard, nothing pending or debounced, an empty runner FIFO and no
+    # runner turn. Never on a grant. Anything unreadable counts as busy.
+
+    def _session_key_of(self, event: Any) -> Optional[str]:
+        key_fn = getattr(self, "_event_session_key", None)
+        if not callable(key_fn):
+            return None
+        try:
+            key = key_fn(event)
+        except Exception:
+            return None
+        return key if isinstance(key, str) and key else None
+
+    def _runner_key_of(self, event: Any) -> Optional[str]:
+        runner = getattr(self, "gateway_runner", None)
+        key_fn = getattr(runner, "_session_key_for_source", None)
+        if not callable(key_fn):
+            return None
+        try:
+            key = key_fn(event.source)
+        except Exception:
+            return None
+        return key if isinstance(key, str) and key else None
+
+    @staticmethod
+    def _warn_idle_inputs_missing() -> None:
+        global _IDLE_INPUTS_WARNED
+        if _IDLE_INPUTS_WARNED:
             return
+        _IDLE_INPUTS_WARNED = True
+        logger.warning(
+            "SecureComs: this Hermes does not expose its session idle state; a sender whose "
+            "turn ran without tools stays without tools"
+        )
+
+    def _session_idle(self, session_key: str, completing: Any, runner_keys=()) -> bool:
+        """True only when nothing in this Hermes session can still be
+        processing an event's text. ``completing`` is the task whose
+        on_processing_complete is running (it is ending, so it is not busy)."""
+        try:
+            active = getattr(self, "_active_sessions", None)
+            tasks = getattr(self, "_session_tasks", None)
+            pending = getattr(self, "_pending_messages", None)
+            store_fn = getattr(self, "_text_debounce_store", None)
+            runner = getattr(self, "gateway_runner", None)
+            peek = getattr(runner, "_peek_session_state", None)
+            if (
+                not isinstance(active, dict) or not isinstance(tasks, dict) or not isinstance(pending, dict)
+                or not callable(store_fn) or not callable(peek)
+            ):
+                self._warn_idle_inputs_missing()
+                return False
+            if session_key in pending:
+                return False
+            store = store_fn()
+            if not isinstance(store, dict) or session_key in store:
+                return False
+            task = tasks.get(session_key)
+            if task is not None and task is not completing and not task.done():
+                return False
+            if session_key in active and task is None:
+                return False  # a guard with no owner task: a command is running
+            for key in {session_key, *(k for k in runner_keys if k)}:
+                state = peek(key)
+                if state is None:
+                    continue
+                if state.turn.agent is not None:
+                    return False
+                if state.conversation.queued_events:
+                    return False
+            return True
+        except Exception:
+            return False
+
+    def _release_if_idle(self, session_key: Optional[str], completing: Any, runner_key: Optional[str] = None) -> None:
+        """Release every count attached to this session once it is idle."""
+        if session_key is None:
+            return
+        waiting = _ATTACHED.get(session_key)
+        if not waiting:
+            return
+        runner_keys = tuple(rk for _, rk in waiting) + (runner_key,)
+        if self._session_idle(session_key, completing, runner_keys):
+            for token, _ in _ATTACHED.pop(session_key, []):
+                _TURN_AUTHZ.end_ungranted(*token)
+
+    def _settle_on_completion(self, event: Any) -> None:
+        """H0.2 (d)+(e): at every completion in a session, release what is
+        attached to it if the session is idle."""
+        self._release_if_idle(self._session_key_of(event), asyncio.current_task(), self._runner_key_of(event))
+
+    async def _await_acceptance(self, event: Any) -> str:
+        """"accepted" once Hermes holds the turn durably (marker persisted) or
+        has finished it; "cancelled" when Hermes cancelled it before that
+        (gateway shutdown: cancel_background_tasks); "timeout" after
+        _ACCEPT_WAIT_S."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + _ACCEPT_WAIT_S
+        while True:
+            if getattr(event, "_gateway_active_turn_token", None):
+                return "accepted"
+            outcome = getattr(event, "_securecoms_outcome", None)
+            if outcome == "CANCELLED":
+                return "cancelled"
+            if outcome is not None:
+                return "accepted"  # finished (success or failure): never redeliver a poison turn
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                return "timeout"
+            await asyncio.sleep(min(_ACCEPT_POLL_S, remaining))
+
+    async def _ack_on_acceptance(self, mid: Any, key: Optional[str], event: Any) -> None:
+        try:
+            result = await self._await_acceptance(event)
+        except BaseException:
+            # Cancelled (disconnect) or broken: unacked, and forgotten so a
+            # redelivery to this same adapter runs the turn.
+            if key is not None:
+                self._deliveries.forget(key)
+            raise
+        if result == "cancelled":
+            # Hermes dropped it before persisting a marker: no Hermes resume
+            # will cover it. Fail it back to the daemon, which requeues it
+            # behind its backoff (ws-server.ts nack) instead of holding the
+            # channel until this socket closes.
+            if key is not None:
+                self._deliveries.forget(key)
+            await self._send_nack(mid)
+            return
+        if result == "timeout":
+            logger.info("SecureComs: turn not yet accepted by Hermes at the ack bound; acking it")
+        # Done BEFORE the send: a redelivery racing in is acked, never re-run.
+        if key is not None:
+            self._deliveries.finish(key)
+        await self._send_ack(mid)
+
+    async def _send_ack(self, mid: Any) -> None:
+        """Ack on the CURRENT socket. The daemon's ack handler retires the id
+        durably for the agent (ackRuntimeMessages), not per socket, and also
+        clears it from that socket's in-flight map, which after a reconnect
+        holds the redelivered copy. With no socket the ack is dropped: the
+        ledger already says done, so the redelivery is acked on arrival."""
+        key = mid if isinstance(mid, str) and mid else None
+        ws = self._ws
+        if ws is None:
+            logger.debug("SecureComs: no daemon link for an ack; it is sent on reconnect")
+            self._hold_unsent_ack(key)
+            return
+        try:
+            await ws.send_json({"type": "ack", "message_id": mid})
+        except Exception as e:
+            logger.warning(
+                "SecureComs: ack failed (error_class=%s)",
+                _error_class(e),
+            )
+            self._hold_unsent_ack(key)
+            return
+        if key is not None:
+            self._unsent_acks.pop(key, None)
+            self._deliveries.unpin(key)
+
+    def _hold_unsent_ack(self, key: Optional[str]) -> None:
+        if key is None:
+            return
+        self._unsent_acks.pop(key, None)
+        self._unsent_acks[key] = None
+        self._deliveries.pin(key)
+
+    async def _flush_unsent_acks(self) -> None:
+        """Send acks dropped while the link was down, on the new socket."""
+        for key in list(self._unsent_acks):
+            if self._ws is None:
+                return
+            await self._send_ack(key)
+            if key in self._unsent_acks:
+                return  # the send failed again; keep the rest for next time
+
+    async def _send_nack(self, mid: Any) -> None:
+        ws = self._ws
+        if ws is None or not isinstance(mid, str) or not mid:
+            return  # the daemon re-buffers whatever is unacked when the socket closes
+        try:
+            await ws.send_json({"type": "nack", "message_id": mid})
+        except Exception as e:
+            logger.debug(
+                "SecureComs: nack failed (error_class=%s)",
+                _error_class(e),
+            )
+
+    async def _dispatch(self, frame: Dict[str, Any]) -> Optional[Any]:
+        """Hand one frame to Hermes. Returns the MessageEvent passed to
+        handle_message, or None when the frame was dropped before Hermes."""
+        if not self._message_handler:
+            return None
         if securecoms_transport.should_drop_inbound(frame, self._bound_identity):
-            return  # echo guard (contract §4.4): never re-feed our own sends
+            return None  # echo guard (contract §4.4): never re-feed our own sends
         channel_id = frame.get("channel_id", "")
         sender_id = frame.get("sender_id", "")
         text = frame.get("text", "")
+        if channel_id not in self._channels and self._session is not None and self._may_look_up(channel_id):
+            # A channel created after connect: look it up before guessing, at
+            # most once per _UNKNOWN_CHANNEL_RETRY_S per channel (review r2).
+            await self._refresh_channels()
         meta = self._channels.get(channel_id, {})
-        chat_type = "dm" if meta.get("is_dm", True) else "group"
-
-        global _FRAMES_WITHOUT_AUTHORIZATION
+        # Review r1 M3: a channel whose metadata is not cached yet is a GROUP
+        # (Hermes keys group sessions per user), never a DM: guessing DM would
+        # put a room's messages into a direct-chat session.
+        chat_type = "dm" if meta.get("is_dm") is True else "group"
+        if securecoms_authz.block_says_dm(frame):
+            # Audit r2: the daemon's block marks a DM whatever this cache says
+            # (a cache miss or a failed refresh must not skip the H0.2c split).
+            chat_type = "dm"
+
+        global _FRAMES_WITHOUT_AUTHORIZATION, _ATTACHMENTS_DROPPED
         if not isinstance(frame.get("authorization"), dict):
             _FRAMES_WITHOUT_AUTHORIZATION += 1
             if _FRAMES_WITHOUT_AUTHORIZATION % 100 == 1:
@@ -489,32 +992,80 @@ class SecureComsAdapter(BasePlatformAdapter):
                     "Upgrade @securecoms/agent-bridge"
                 )
         tools_allowed = securecoms_authz.tools_allowed(frame)
-        _TURN_AUTHZ.record(channel_id, sender_id, tools_allowed)
+        if tools_allowed and self._room_sessions_shared and chat_type != "dm":
+            tools_allowed = False  # H0.2b: one room session for every sender
+        # H0.2c: Hermes keys a DM session by chat only. Every non-owner DM turn
+        # runs in its own session (thread NON_OWNER_THREAD), so its text never
+        # enters the transcript the owner's granted turns run in.
+        thread_id = None
+        if chat_type == "dm":
+            thread_id = securecoms_authz.dm_thread(frame)
+        if thread_id is not None:
+            # Defence in depth only: no non-owner or unclassified frame passes
+            # securecoms_authz.tools_allowed, and the ledger forces these
+            # threads off. Removing this line is an equivalent mutant (N4).
+            tools_allowed = False
+        _TURN_AUTHZ.record(channel_id, sender_id, tools_allowed, thread_id)
         if not tools_allowed and not _TOOL_VETO_ACTIVE:
             # This Hermes cannot be made to refuse tool calls, so a turn the
-            # daemon did not grant tools never reaches it. Acked by _pump.
+            # daemon did not grant tools never reaches it. Acked at once by
+            # _receive_message.
             logger.warning("SecureComs: refused a turn without a tool grant (tool veto unavailable)")
             await self._notify_refused(channel_id, frame)
-            return
+            return None
 
         source = self.build_source(
             chat_id=channel_id,
-            chat_name=meta.get("name", channel_id),
+            # The room name is member-chosen and reaches the prompt: same
+            # sanitizer as the sender label, falling back to the channel id.
+            chat_name=securecoms_transport.display_name(meta.get("name")) or channel_id,
             chat_type=chat_type,
+            # user_id (Hermes's session and the tool ledger key) is the
+            # relay-attributed sender_id; user_name is a sanitized label of
+            # that same sender (R3). thread_id: H0.2c above.
             user_id=sender_id,
-            user_name=sender_id,
+            thread_id=thread_id,
+            user_name=securecoms_transport.own_label(frame),
         )
+        speaker = securecoms_transport.speaker_label(frame)
+        if speaker and isinstance(text, str):
+            # A relayed voice room: one Hermes session (the relay's) holds
+            # several speakers, and Hermes pins user_name in the per-session
+            # system prompt, so the real speaker rides each turn's text, the
+            # way Hermes's own shared sessions prefix "[sender name]". The
+            # label's name part cannot contain "[]()" (R3, M2).
+            text = f"[{speaker}] {text}"
         if not tools_allowed and isinstance(text, str):
             # An ungranted sender must never drive gateway commands. EVERY
             # ungranted text is escaped: Hermes strips leading @url:/@file:
             # refs before its "/" check, so "@url:x /reset" is a command too.
             text = securecoms_authz.COMMAND_ESCAPE + text
+        # Image/file attachments the daemon decrypted to disk ride as Hermes
+        # media, the same shape Hermes's own Signal adapter emits
+        # (gateway/platforms/signal.py): media_urls = local file paths,
+        # media_types = mimes, message_type from the first matching MIME
+        # prefix, else DOCUMENT. An image with no caption still runs a turn.
+        attachments, dropped = securecoms_transport.scan_inbound_attachments(frame)
+        if dropped:
+            # Content-free: a fixed line plus a process counter, never a path,
+            # name or mime (tests/test_logging_privacy.py bars dynamic args).
+            _ATTACHMENTS_DROPPED += dropped
+            logger.info("SecureComs: dropped inbound attachment(s) that failed validation")
+        media_kw: Dict[str, Any] = {}
+        message_type = MessageType.TEXT
+        if attachments:
+            media_kw = {
+                "media_urls": [p for p, _ in attachments],
+                "media_types": [m for _, m in attachments],
+            }
+            message_type = _message_type_for_mimes(media_kw["media_types"])
         event = MessageEvent(
-            text=text,
-            message_type=MessageType.TEXT,
+            text=text if isinstance(text, str) else "",
+            message_type=message_type,
             source=source,
             message_id=str(frame.get("message_id") or int(time.time() * 1000)),
             timestamp=datetime.now(),
+            **media_kw,
         )
         # Sender role rides as event metadata, never in the user text.
         metadata = getattr(event, "metadata", None)
@@ -532,7 +1083,63 @@ class SecureComsAdapter(BasePlatformAdapter):
         prompts = [p for p in (voice_prompt_of(frame), None if tools_allowed else securecoms_authz.NO_TOOLS_TURN_NOTE) if p]
         if prompts:
             event.channel_prompt = "\n\n".join(prompts)
-        await self.handle_message(event)
+        token = None
+        session_key = None
+        if not tools_allowed:
+            # H0.2 (a): this key has no tools until no turn in its session can
+            # still be processing this event's text. Attached to the session
+            # now; released only when the session is idle.
+            token = (channel_id, sender_id, thread_id, self._room_sessions_shared and chat_type != "dm")
+            _TURN_AUTHZ.begin_ungranted(*token)
+            session_key = self._session_key_of(event)
+            if session_key is None:
+                logger.warning(
+                    "SecureComs: an ungranted turn's Hermes session is unknown; its sender stays without tools"
+                )
+            else:
+                _ATTACHED.setdefault(session_key, []).append((token, self._runner_key_of(event)))
+        reached = False
+        try:
+            event._securecoms_session_was_busy = self._session_was_busy(event)
+            reached = True
+            await self.handle_message(event)
+        except BaseException:
+            if token is not None and not reached:
+                self._detach(session_key, token)  # never reached Hermes
+                _TURN_AUTHZ.end_ungranted(*token)
+            elif token is not None:
+                self._release_if_idle(session_key, None)
+            raise
+        if token is not None:
+            # (b)/(c): released now only if nothing in the session can still
+            # be processing it; else at a later idle completion (d)/(e).
+            self._release_if_idle(session_key, None)
+        return event
+
+    @staticmethod
+    def _detach(session_key: Optional[str], token: tuple) -> None:
+        waiting = _ATTACHED.get(session_key) if session_key is not None else None
+        if not waiting:
+            return
+        for i, (t, _) in enumerate(waiting):
+            if t is token:
+                del waiting[i]
+                break
+        if not waiting:
+            _ATTACHED.pop(session_key, None)
+
+    def _may_look_up(self, channel_id: str) -> bool:
+        """Negative cache for unknown channels: True at most once per
+        _UNKNOWN_CHANNEL_RETRY_S per channel (bounded map, oldest evicted)."""
+        now = time.monotonic()
+        last = self._unknown_channel_lookups.get(channel_id)
+        if last is not None and now - last < _UNKNOWN_CHANNEL_RETRY_S:
+            return False
+        self._unknown_channel_lookups.pop(channel_id, None)
+        self._unknown_channel_lookups[channel_id] = now
+        while len(self._unknown_channel_lookups) > _UNKNOWN_CHANNEL_LOOKUPS_MAX:
+            self._unknown_channel_lookups.pop(next(iter(self._unknown_channel_lookups)))
+        return True
 
     async def _notify_refused(self, channel_id: str, frame: Dict[str, Any]) -> None:
         """One short notice per channel that this agent cannot respond there.
@@ -553,12 +1160,14 @@ class SecureComsAdapter(BasePlatformAdapter):
     def toolsets_for_source(self, source) -> Optional[list]:
         """Hermes per-turn toolset override (gateway run_turn
         _resolve_enabled_toolsets_for_source). None keeps the configured
-        toolsets: only for a (chat, sender) whose latest turn was granted
-        tools. Anything else, including an unknown source, gets the no-tools
-        override."""
+        toolsets: only for a (chat, sender, thread) whose latest turn was
+        granted tools and that has no ungranted turn still in flight (H0).
+        Anything else, including an unknown source and every turn in the
+        non-owner DM thread, gets the no-tools override."""
         chat_id = getattr(source, "chat_id", None)
         user_id = getattr(source, "user_id", None)
-        if _TURN_AUTHZ.tools_allowed(chat_id, user_id):
+        thread_id = getattr(source, "thread_id", None)
+        if _TURN_AUTHZ.tools_allowed(chat_id, user_id, thread_id):
             return None
         return list(securecoms_authz.NO_TOOLS_TOOLSETS)
 
@@ -639,7 +1248,7 @@ class SecureComsAdapter(BasePlatformAdapter):
             meta = self._channels.get(chat_id, {})
         return {
             "name": meta.get("name", chat_id),
-            "type": "dm" if meta.get("is_dm", True) else "group",
+            "type": "dm" if meta.get("is_dm") is True else "group",
             "chat_id": chat_id,
         }
 
@@ -705,7 +1314,21 @@ def _install_tool_veto(ctx) -> bool:
         ):
             return False
         from gateway import session_context
-        from gateway.session_context import get_session_env
+
+        # Read the turn's task-local ContextVars directly: Hermes's own
+        # get_session_env falls back to os.environ, which a concurrent turn or
+        # the process can set. Unset (_UNSET) reads as None, never as a value.
+        var_map = getattr(session_context, "_VAR_MAP", None)
+        unset = getattr(session_context, "_UNSET", None)
+        names = ("HERMES_SESSION_PLATFORM", "HERMES_SESSION_CHAT_ID", "HERMES_SESSION_USER_ID", "HERMES_SESSION_THREAD_ID")
+        if unset is None or not isinstance(var_map, dict) or not all(
+            callable(getattr(var_map.get(n), "get", None)) for n in names
+        ):
+            return False
+
+        def get_session_env(name, default=""):
+            value = var_map[name].get()
+            return None if value is unset else value
 
         engaged = getattr(session_context, "session_context_engaged", None)
         _SESSION_ENGAGED = engaged if callable(engaged) else None