@securecoms/agent-bridge 0.36.0 → 0.38.0

package/connectors/hermes/tests/test_adapter_wiring.py

@@ -45,7 +45,12 @@ def _install_gateway_stub():
             self.value = value
 
     class MessageType(Enum):
+        # Real Hermes gateway/platforms/event.py MessageType (subset).
         TEXT = "text"
+        PHOTO = "photo"
+        VIDEO = "video"
+        VOICE = "voice"
+        DOCUMENT = "document"
 
     @dataclass
     class MessageEvent:
@@ -61,6 +66,9 @@ def _install_gateway_stub():
         # Real Hermes: may this event resolve gateway commands / control
         # prompts? False keeps untrusted payload text conversational.
         allow_gateway_control: bool = True
+        # Real Hermes: local file paths (or URLs) of inbound media + mimes.
+        media_urls: list = field(default_factory=list)
+        media_types: list = field(default_factory=list)
 
     @dataclass
     class SendResult:
@@ -466,6 +474,7 @@ def fresh_gate(monkeypatch):
     monkeypatch.setattr(adapter, "_HARNESS_VERSION", None)
     monkeypatch.setattr(adapter, "_REFUSAL_NOTICE_SENT", set())
     monkeypatch.setattr(adapter, "_FRAMES_WITHOUT_AUTHORIZATION", 0)
+    monkeypatch.setattr(adapter, "_ATTACHMENTS_DROPPED", 0)
 
 
 class TestToolGate:
@@ -1107,3 +1116,881 @@ class TestConnectSignatureContract:
         code, _message, retryable = a.fatal_errors[-1]
         assert code == "unwired"
         assert retryable is False
+
+
+PNG = b"\x89PNG\r\n\x1a\n\x00\x00\x00\r"
+JPEG = b"\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01"
+
+
+@pytest.fixture
+def att_dir(tmp_path):
+    d = tmp_path / "attachments" / "dm"
+    d.mkdir(parents=True)
+    return d
+
+
+def _att(att_dir, name, data=JPEG, mime="image/jpeg"):
+    p = att_dir / f"m-{name}"
+    p.write_bytes(data)
+    return {"filename": name, "mime": mime, "size": len(data), "path": str(p), "sha256": "x"}
+
+
+class TestInboundAttachments:
+    async def _handled(self, monkeypatch, frames, channels=None, refresh=None):
+        monkeypatch.setattr(adapter, "_TOOL_VETO_ACTIVE", True)
+        a, _ = make_adapter(monkeypatch)
+        a._bound_identity = "A"
+        if channels:
+            a._channels.update(channels)
+        if refresh is not None:
+            a._session = object()
+
+            async def fake_refresh():
+                a._channels.update(refresh)
+
+            a._refresh_channels = fake_refresh
+        handled = []
+
+        async def handler(event):
+            handled.append(event)
+
+        a.set_message_handler(handler)
+        ws = await _pump_frames(a, frames)
+        return handled, ws
+
+    @pytest.mark.asyncio
+    async def test_image_frame_becomes_a_photo_event_with_the_local_path(self, monkeypatch, fresh_gate, att_dir):
+        a = _att(att_dir, "IMG_3375.jpeg")
+        handled, ws = await self._handled(monkeypatch, [
+            _frame("m1", "owner", "dm", "what is this?", OWNER_AUTH, attachments=[a]),
+        ])
+        assert len(handled) == 1
+        ev = handled[0]
+        assert ev.message_type == adapter.MessageType.PHOTO
+        assert ev.media_urls == [a["path"]]
+        assert ev.media_types == ["image/jpeg"]
+        assert ev.text == "what is this?"
+        assert [f for f in ws.sent if f.get("type") == "ack"][0]["message_id"] == "m1"
+        assert adapter._ATTACHMENTS_DROPPED == 0
+
+    @pytest.mark.asyncio
+    async def test_image_only_frame_still_runs_a_turn(self, monkeypatch, fresh_gate, att_dir):
+        a = _att(att_dir, "a.png", PNG, "image/png")
+        handled, _ = await self._handled(monkeypatch, [_frame("m1", "owner", "dm", "", OWNER_AUTH, attachments=[a])])
+        assert len(handled) == 1
+        assert handled[0].text == ""
+        assert handled[0].message_type == adapter.MessageType.PHOTO
+        assert handled[0].media_urls == [a["path"]]
+
+    @pytest.mark.asyncio
+    async def test_a_pdf_is_dropped_and_counted(self, monkeypatch, fresh_gate, att_dir):
+        a = _att(att_dir, "r.pdf", b"%PDF-1.7\n....", "application/pdf")
+        handled, _ = await self._handled(monkeypatch, [_frame("m1", "owner", "dm", "", OWNER_AUTH, attachments=[a])])
+        assert handled[0].message_type == adapter.MessageType.TEXT
+        assert handled[0].media_urls == []
+        assert adapter._ATTACHMENTS_DROPPED == 1
+
+    @pytest.mark.asyncio
+    async def test_bad_path_is_dropped_and_the_turn_is_text(self, monkeypatch, fresh_gate, att_dir):
+        a = {**_att(att_dir, "x.jpg"), "path": "/etc/passwd"}
+        handled, _ = await self._handled(monkeypatch, [_frame("m1", "owner", "dm", "look", OWNER_AUTH, attachments=[a])])
+        assert len(handled) == 1
+        assert handled[0].message_type == adapter.MessageType.TEXT
+        assert handled[0].media_urls == []
+        assert handled[0].media_types == []
+
+    @pytest.mark.asyncio
+    async def test_text_only_frame_is_unchanged(self, monkeypatch, fresh_gate):
+        handled, _ = await self._handled(monkeypatch, [_frame("m1", "owner", "dm", "hi", OWNER_AUTH)])
+        ev = handled[0]
+        assert ev.text == "hi"
+        assert ev.message_type == adapter.MessageType.TEXT
+        assert ev.media_urls == [] and ev.media_types == []
+        assert adapter._ATTACHMENTS_DROPPED == 0
+
+    @pytest.mark.asyncio
+    async def test_ungranted_sender_image_keeps_the_command_escape(self, monkeypatch, fresh_gate, att_dir):
+        a = _att(att_dir, "a.jpg")
+        handled, _ = await self._handled(monkeypatch, [
+            _frame("m1", "member", "dm", "/reset", _no_grant("team_room"), attachments=[a]),
+        ])
+        ev = handled[0]
+        assert ev.text == adapter.securecoms_authz.COMMAND_ESCAPE + "/reset"
+        assert ev.allow_gateway_control is False
+        assert ev.media_urls == [a["path"]]
+
+
+class TestChatTypeDefault:
+    """Review r1 M3: an uncached channel is a group (per-user session), never a DM."""
+
+    async def _chat_type(self, monkeypatch, **kw):
+        handled, _ = await TestInboundAttachments()._handled(
+            monkeypatch, [_frame("m1", "owner", "c1", "hi", OWNER_AUTH)], **kw)
+        return handled[0].source.chat_type
+
+    @pytest.mark.asyncio
+    async def test_uncached_channel_is_a_group(self, monkeypatch, fresh_gate):
+        assert await self._chat_type(monkeypatch) == "group"
+
+    @pytest.mark.asyncio
+    async def test_cached_dm_is_still_a_dm(self, monkeypatch, fresh_gate):
+        assert await self._chat_type(monkeypatch, channels={"c1": {"name": "c1", "is_dm": True}}) == "dm"
+
+    @pytest.mark.asyncio
+    async def test_cached_room_is_a_group(self, monkeypatch, fresh_gate):
+        assert await self._chat_type(monkeypatch, channels={"c1": {"name": "c1", "is_dm": False}}) == "group"
+
+    @pytest.mark.asyncio
+    async def test_a_dm_created_after_connect_is_looked_up_first(self, monkeypatch, fresh_gate):
+        assert await self._chat_type(monkeypatch, refresh={"c1": {"name": "c1", "is_dm": True}}) == "dm"
+
+    @pytest.mark.asyncio
+    async def test_an_unknown_channel_is_looked_up_at_most_once_a_minute(self, monkeypatch, fresh_gate):
+        monkeypatch.setattr(adapter, "_TOOL_VETO_ACTIVE", True)
+        a, _ = make_adapter(monkeypatch)
+        a._bound_identity = "A"
+        a._session = object()
+        calls = []
+
+        async def fake_refresh():
+            calls.append(1)
+
+        a._refresh_channels = fake_refresh
+        clock = [1000.0]
+        monkeypatch.setattr(adapter.time, "monotonic", lambda: clock[0])
+        handled = []
+
+        async def handler(event):
+            handled.append(event)
+
+        a.set_message_handler(handler)
+        await _pump_frames(a, [_frame(f"m{i}", "owner", "c1", "hi", OWNER_AUTH) for i in range(3)])
+        assert len(calls) == 1
+        assert [e.source.chat_type for e in handled] == ["group"] * 3
+        clock[0] += adapter._UNKNOWN_CHANNEL_RETRY_S
+        await _pump_frames(a, [_frame("m9", "owner", "c1", "hi", OWNER_AUTH)])
+        assert len(calls) == 2
+        # another unknown channel has its own budget
+        await _pump_frames(a, [_frame("n1", "owner", "c2", "hi", OWNER_AUTH)])
+        assert len(calls) == 3
+        assert adapter._UNKNOWN_CHANNEL_RETRY_S == 60.0
+
+    @pytest.mark.asyncio
+    async def test_a_slow_channel_refresh_is_bounded(self, monkeypatch, fresh_gate):
+        a, _ = make_adapter(monkeypatch)
+        monkeypatch.setattr(adapter, "_CHANNEL_REFRESH_TIMEOUT_S", 0.05)
+
+        async def slow_fetch():
+            await asyncio.sleep(30)
+
+        a._fetch_channels = slow_fetch
+        await asyncio.wait_for(a._refresh_channels(), timeout=2)  # returns, never raises
+        assert adapter._CHANNEL_REFRESH_TIMEOUT_S == 0.05
+
+    def test_refresh_timeout_default_is_short(self):
+        assert adapter._CHANNEL_REFRESH_TIMEOUT_S == 5.0
+
+    @pytest.mark.asyncio
+    async def test_get_chat_info_defaults_to_group(self, monkeypatch, fresh_gate):
+        a, _ = make_adapter(monkeypatch)
+
+        async def no_refresh():
+            return None
+
+        a._refresh_channels = no_refresh
+        assert (await a.get_chat_info("unknown"))["type"] == "group"
+
+
+# ---------------------------------------------------------------------------
+# Ack on durable acceptance + redelivery dedup.
+#
+# _HermesSessions mirrors the Hermes v2026.9.24 paths the adapter relies on
+# (gateway/platforms/base.py unless noted):
+#   - handle_message (3950) resets event._gateway_accepted (3953); an idle
+#     session starts a tracked task and sets it True (3990, 3862, 3876);
+#   - a busy session runs a bypass command (/stop, /approve) inline, leaving
+#     _gateway_accepted False (_handle_message_while_active, 3995-4013; /stop
+#     cancels the owner task, cancel_session_processing 3891), and queues
+#     anything else in _pending_messages with _gateway_accepted True (4058-4064);
+#   - _process_message_background (4438) calls on_processing_start, awaits the
+#     runner, then on_processing_complete with SUCCESS / FAILURE / CANCELLED on
+#     every exit (4520-4540), and hands a queued follow-up to a fresh drain
+#     task (_spawn_drain_task 4560);
+#   - cancel_background_tasks (4593) cancels every tracked task on shutdown.
+# _Runner mirrors the runner side: it persists the active-turn marker and only
+# then publishes event._gateway_active_turn_token (gateway/run_inbound.py
+# 1754-1767, called at gateway/run_turn.py:2090 before the model call), and
+# clears it when the turn ends (run_inbound.py:1382, 1769-1795).
+# F2DaemonWS mirrors the daemon (ws-server.ts F2): at most one message per
+# channel in flight; the next one for that channel goes out only after the ack.
+# The module stub above (inline handle_message, no _gateway_accepted) is the
+# "this Hermes has none of it" fallback case.
+# ---------------------------------------------------------------------------
+
+
+class ProcessingOutcome(Enum):
+    SUCCESS = "success"
+    FAILURE = "failure"
+    CANCELLED = "cancelled"
+
+
+_BYPASS = ("/stop", "/approve")
+
+
+class _HermesSessions:
+    async def handle_message(self, event):
+        event._gateway_accepted = False
+        if not self._message_handler:
+            return
+        key = self._event_session_key(event)
+        # On-entry self-heal (base.py:3983-3985, _heal_stale_session_lock 3849):
+        # a guard whose recorded owner task already exited is cleared.
+        owner = self._session_tasks.get(key)
+        if key in self._active_sessions and owner is not None and owner.done():
+            self._active_sessions.pop(key, None)
+            self._pending_messages.pop(key, None)
+            self._session_tasks.pop(key, None)
+        if key in self._active_sessions:
+            cmd = (event.text or "").strip().split(" ")[0]
+            if cmd in _BYPASS:
+                self.inline_commands.append(cmd)
+                if cmd == "/stop":
+                    await self.cancel_session_processing(key)
+                else:
+                    self.approvals.setdefault(key, asyncio.get_running_loop().create_future()).set_result(True)
+                return
+            # merge_pending_message_event(merge_text=True) (base.py:1739-1781):
+            # TEXT appends to the queued event, which keeps its own message_id.
+            existing = self._pending_messages.get(key)
+            if existing is None:
+                self._pending_messages[key] = event
+            else:
+                existing.text = existing.text + "\n" + event.text
+            event._gateway_accepted = True
+            return
+        self._active_sessions[key] = asyncio.Event()
+        self._track(key, asyncio.create_task(self._process_message_background(event, key)))
+        event._gateway_accepted = True
+
+    def _track(self, key, task):
+        self._session_tasks[key] = task
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+
+    async def _process_message_background(self, event, key):
+        try:
+            await self._run_processing_hook("on_processing_start", event)
+            await self._message_handler(event)
+            await self._run_processing_hook("on_processing_complete", event, ProcessingOutcome.SUCCESS)
+        except asyncio.CancelledError:
+            await self._run_processing_hook("on_processing_complete", event, ProcessingOutcome.CANCELLED)
+            raise
+        except Exception:
+            await self._run_processing_hook("on_processing_complete", event, ProcessingOutcome.FAILURE)
+        finally:
+            pending = self._pending_messages.pop(key, None)
+            if pending is not None and not self._shutting_down:
+                self._track(key, asyncio.create_task(self._process_message_background(pending, key)))
+            else:
+                self._active_sessions.pop(key, None)
+                self._session_tasks.pop(key, None)
+
+    async def on_processing_start(self, event):
+        pass
+
+    async def _run_processing_hook(self, hook_name, *args, **kwargs):
+        # base.py:3470-3477: a failing hook never breaks message flow.
+        hook = getattr(self, hook_name, None)
+        if not callable(hook):
+            return
+        try:
+            await hook(*args, **kwargs)
+        except Exception:
+            pass
+
+    async def cancel_session_processing(self, key):
+        task = self._session_tasks.pop(key, None)
+        if task is not None and not task.done():
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+        self._active_sessions.pop(key, None)
+
+    async def cancel_background_tasks(self):
+        self._shutting_down = True
+        tasks = [t for t in self._background_tasks if not t.done()]
+        for t in tasks:
+            t.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+    def _event_session_key(self, event):
+        s = event.source
+        return f"agent:main:securecoms:{s.chat_type}:{s.chat_id}:{s.user_id}"
+
+
+class _Runner:
+    """The gateway runner's message handler. marker_gates hold a turn before
+    its marker is persisted (lease wait); turn_gates hold it after (the model
+    call). A turn whose text names 'approval' waits for an /approve."""
+
+    def __init__(self, adapter_ref):
+        self.a = adapter_ref
+        self.started = []
+        self.marker_gates = {}
+        self.turn_gates = {}
+        self.raise_before_marker = set()
+
+    def gate(self, kind, mid):
+        return getattr(self, kind).setdefault(mid, asyncio.Event())
+
+    def release(self, kind, mid):
+        self.gate(kind, mid).set()
+
+    async def __call__(self, event):
+        mid = event.message_id
+        self.started.append(mid)
+        if mid in self.marker_gates:
+            await self.marker_gates[mid].wait()
+        if mid in self.raise_before_marker:
+            raise RuntimeError("history unreadable")
+        event._gateway_active_turn_token = "tok-" + mid  # persisted, then published
+        try:
+            if "approval" in (event.text or ""):
+                key = self.a._event_session_key(event)
+                await self.a.approvals.setdefault(key, asyncio.get_running_loop().create_future())
+            else:
+                await self.gate("turn_gates", mid).wait()
+        finally:
+            del event._gateway_active_turn_token
+
+
+class F2DaemonWS:
+    def __init__(self, frames):
+        self.frames = list(frames)
+        self.next = 0
+        self.inflight = {}  # channel_id -> message_id
+        self.delivered = []
+        self.sent = []
+        self.closed = False
+        self._acked = asyncio.Event()
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        while True:
+            if self.next >= len(self.frames):
+                return _FakeWSMsg(aiohttp.WSMsgType.CLOSED)
+            f = self.frames[self.next]
+            if f["channel_id"] not in self.inflight:
+                self.next += 1
+                self.inflight[f["channel_id"]] = f.get("message_id")
+                self.delivered.append(f.get("message_id"))
+                return _FakeWSMsg(aiohttp.WSMsgType.TEXT, json.dumps(f))
+            self._acked.clear()
+            await self._acked.wait()
+
+    async def send_json(self, payload):
+        self.sent.append(payload)
+        if payload.get("type") in ("ack", "nack"):
+            for ch, mid in list(self.inflight.items()):
+                if mid == payload.get("message_id"):
+                    del self.inflight[ch]
+            self._acked.set()
+
+    async def close(self):
+        self.closed = True
+
+
+def make_hermes_adapter(monkeypatch):
+    class HermesFaithfulAdapter(_HermesSessions, adapter.SecureComsAdapter):
+        pass
+
+    monkeypatch.setattr(adapter, "_read_file_text", make_fs({}))
+    a = HermesFaithfulAdapter(types.SimpleNamespace(extra={}))
+    a._active_sessions = {}
+    a._pending_messages = {}
+    a._session_tasks = {}
+    a._background_tasks = set()
+    a._shutting_down = False
+    a.inline_commands = []
+    a.approvals = {}
+    a._bound_identity = "A"
+    runner = _Runner(a)
+    a.set_message_handler(runner)
+    return a, runner
+
+
+async def _settle():
+    for _ in range(20):
+        await asyncio.sleep(0)
+
+
+async def _drain_waiters(a, timeout=2.0):
+    async def drain():
+        while a._ack_waiters:
+            await asyncio.gather(*list(a._ack_waiters))
+
+    await asyncio.wait_for(drain(), timeout=timeout)
+
+
+async def _pump(a, ws, timeout=2.0):
+    a._ws = ws
+    await asyncio.wait_for(a._pump(), timeout=timeout)
+
+
+def _acks(ws):
+    return [f["message_id"] for f in ws.sent if f.get("type") == "ack"]
+
+
+def _nacks(ws):
+    return [f["message_id"] for f in ws.sent if f.get("type") == "nack"]
+
+
+def _turns_done(a):
+    return [t for t in a._background_tasks if not t.done()] == []
+
+
+@pytest.fixture
+def ack_state(monkeypatch, fresh_gate):
+    monkeypatch.setattr(adapter, "_TOOL_VETO_ACTIVE", True)
+    # raising=False so a pre-change adapter fails these tests on behaviour, not setup.
+    monkeypatch.setattr(adapter, "_TURN_TRACKING_WARNED", False, raising=False)
+
+
+class TestAckOnAcceptance:
+    @pytest.mark.asyncio
+    async def test_ack_waits_for_the_durable_marker_not_for_the_turn_end(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.gate("marker_gates", "m1")
+        ws = F2DaemonWS([_frame("m1", "owner", "c1", "hi", OWNER_AUTH)])
+        await _pump(a, ws)
+        await _settle()
+        assert r.started == ["m1"]
+        assert _acks(ws) == []  # running, but no durable marker yet
+        r.release("marker_gates", "m1")
+        await _drain_waiters(a)
+        assert _acks(ws) == ["m1"]
+        assert not _turns_done(a)  # acked while the turn is still running
+        r.release("turn_gates", "m1")
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("command", ["/stop", "/approve"])
+    async def test_a_mid_turn_command_in_the_same_channel_is_delivered_and_runs(
+        self, monkeypatch, ack_state, command
+    ):
+        # H1: with the daemon's one-in-flight-per-channel rule, the command is
+        # delivered only once the running turn's frame is acked. It must get
+        # through while that turn is still running.
+        a, r = make_hermes_adapter(monkeypatch)
+        first = "long job" if command == "/stop" else "needs approval"
+        ws = F2DaemonWS([_frame("m1", "owner", "c1", first, OWNER_AUTH),
+                         _frame("m2", "owner", "c1", command, OWNER_AUTH)])
+        await _pump(a, ws)  # times out if m1's ack waits for the turn to end
+        assert ws.delivered == ["m1", "m2"]
+        assert a.inline_commands == [command]
+        await _drain_waiters(a)
+        await _settle()
+        assert _acks(ws) == ["m1", "m2"]
+        assert _turns_done(a)  # /stop cancelled the turn; /approve let it finish
+        assert r.started == ["m1"]
+
+    @pytest.mark.asyncio
+    async def test_a_turn_that_fails_before_its_marker_is_acked(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.raise_before_marker.add("m1")
+        ws = F2DaemonWS([_frame("m1", "owner", "c1", "hi", OWNER_AUTH)])
+        await _pump(a, ws)
+        await _drain_waiters(a, timeout=1)  # on the outcome, not the 10 s bound
+        assert _acks(ws) == ["m1"]  # a poison turn is never redelivered forever
+
+    @pytest.mark.asyncio
+    async def test_dropped_frames_ack_at_once(self, monkeypatch, ack_state):
+        monkeypatch.setattr(adapter, "_TOOL_VETO_ACTIVE", False)  # ungranted turns are refused
+        a, r = make_hermes_adapter(monkeypatch)
+
+        async def no_send(*args, **kwargs):
+            return None
+
+        a.send = no_send
+        ws = F2DaemonWS([
+            _frame("echo", "A", "c1", "my own send", OWNER_AUTH),  # echo guard
+            _frame("refused", "member", "room", "hi", _no_grant("team_room")),  # no grant, no veto
+        ])
+        await _pump(a, ws)
+        assert r.started == []
+        assert _acks(ws) == ["echo", "refused"]
+        assert not a._ack_waiters
+
+    @pytest.mark.asyncio
+    async def test_a_redelivery_before_acceptance_is_not_dispatched_again(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.gate("marker_gates", "m1")
+        f = _frame("m1", "owner", "c1", "hi", OWNER_AUTH)
+        ws1 = F2DaemonWS([f])
+        await _pump(a, ws1)
+        await _settle()
+        ws2 = F2DaemonWS([f])  # socket flap: the daemon redelivers the unacked frame
+        await _pump(a, ws2)
+        assert r.started == ["m1"]
+        assert _acks(ws2) == []
+        r.release("marker_gates", "m1")
+        await _drain_waiters(a)
+        assert r.started == ["m1"]
+        assert _acks(ws1) == []
+        assert _acks(ws2) == ["m1"]  # the original's ack, on the current socket
+        r.release("turn_gates", "m1")
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_a_redelivery_after_the_ack_is_acked_without_a_turn(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.release("turn_gates", "m1")
+        f = _frame("m1", "owner", "c1", "hi", OWNER_AUTH)
+        ws1 = F2DaemonWS([f])
+        await _pump(a, ws1)
+        await _drain_waiters(a)
+        assert _acks(ws1) == ["m1"]
+        ws2 = F2DaemonWS([f])
+        await _pump(a, ws2)
+        assert r.started == ["m1"]
+        assert _acks(ws2) == ["m1"]
+        assert not a._ack_waiters
+
+    @pytest.mark.asyncio
+    async def test_no_socket_at_acceptance_then_the_redelivery_is_acked(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.gate("marker_gates", "m1")
+        f = _frame("m1", "owner", "c1", "hi", OWNER_AUTH)
+        await _pump(a, F2DaemonWS([f]))
+        await _settle()
+        a._ws = None  # link down when Hermes accepts: the ack is dropped
+        r.release("marker_gates", "m1")
+        await _drain_waiters(a)
+        ws2 = F2DaemonWS([f])
+        await _pump(a, ws2)
+        assert r.started == ["m1"]
+        assert _acks(ws2) == ["m1"]
+        r.release("turn_gates", "m1")
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_a_frame_without_a_message_id_is_not_deduped(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        f = {k: v for k, v in _frame("x", "owner", "c1", "hi", OWNER_AUTH).items() if k != "message_id"}
+        g = dict(f, channel_id="c2")
+        ws = F2DaemonWS([f, g])
+        await _pump(a, ws)
+        await _drain_waiters(a)
+        assert len(r.started) == 2
+        assert _acks(ws) == [None, None]  # unchanged wire shape for an id-less frame
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_two_channels_progress_independently(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.gate("marker_gates", "slow")
+        ws = F2DaemonWS([_frame("slow", "owner", "c1", "hi", OWNER_AUTH),
+                         _frame("fast", "owner", "c2", "hi", OWNER_AUTH)])
+        await _pump(a, ws)
+        await _settle()
+        assert r.started == ["slow", "fast"]
+        await _settle()
+        assert _acks(ws) == ["fast"]
+        r.release("marker_gates", "slow")
+        await _drain_waiters(a)
+        assert _acks(ws) == ["fast", "slow"]
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_a_follow_up_queued_behind_a_busy_session_is_acked_at_once(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        ws = F2DaemonWS([_frame("m1", "owner", "c1", "one", OWNER_AUTH),
+                         _frame("m2", "owner", "c1", "two", OWNER_AUTH)])
+        await _pump(a, ws)  # m1 accepted -> acked -> m2 delivered mid-turn and queued
+        assert ws.delivered == ["m1", "m2"]
+        assert a._pending_messages  # m2 waits behind m1 in Hermes's pending slot
+        assert _acks(ws) == ["m1", "m2"]  # no wait for a turn that may be minutes away
+        assert not a._ack_waiters
+        r.release("turn_gates", "m1")  # m1 ends; the drain turn still runs m2
+        await _settle()
+        assert r.started == ["m1", "m2"]
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_a_stop_after_a_queued_follow_up_is_dispatched_promptly(self, monkeypatch, ack_state):
+        # Round-2 M1: the queued follow-up must not hold the channel for the
+        # 10 s acceptance bound, or the /stop behind it waits that long.
+        assert adapter._ACCEPT_WAIT_S == 10.0
+        a, r = make_hermes_adapter(monkeypatch)
+        ws = F2DaemonWS([_frame("m1", "owner", "c1", "long job", OWNER_AUTH),
+                         _frame("m2", "owner", "c1", "also do X", OWNER_AUTH),
+                         _frame("m3", "owner", "c1", "/stop", OWNER_AUTH)])
+        loop = asyncio.get_running_loop()
+        t0 = loop.time()
+        await _pump(a, ws, timeout=2.0)
+        assert loop.time() - t0 < 1.0
+        assert ws.delivered == ["m1", "m2", "m3"]
+        assert a.inline_commands == ["/stop"]
+        assert _acks(ws) == ["m1", "m2", "m3"]
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_a_stale_session_guard_does_not_count_as_busy(self, monkeypatch, ack_state):
+        # Hermes heals a guard whose owner task exited and starts a fresh turn,
+        # so the event is not "queued behind a busy session": wait for its marker.
+        a, r = make_hermes_adapter(monkeypatch)
+        f = _frame("m1", "owner", "c1", "hi", OWNER_AUTH)
+        done = asyncio.get_running_loop().create_future()
+        done.set_result(None)
+        key = "agent:main:securecoms:group:c1:owner"
+        a._active_sessions[key] = asyncio.Event()
+        a._session_tasks[key] = done
+        r.gate("marker_gates", "m1")
+        ws = F2DaemonWS([f])
+        await _pump(a, ws)
+        await _settle()
+        assert r.started == ["m1"]
+        assert _acks(ws) == []  # its own turn: the ack waits for the marker
+        r.release("marker_gates", "m1")
+        await _drain_waiters(a)
+        assert _acks(ws) == ["m1"]
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_a_turn_never_accepted_is_acked_at_the_bound(self, monkeypatch, ack_state):
+        monkeypatch.setattr(adapter, "_ACCEPT_WAIT_S", 0.05)
+        a, r = make_hermes_adapter(monkeypatch)
+        r.gate("marker_gates", "m1")  # e.g. stuck waiting for the turn lease
+        ws = F2DaemonWS([_frame("m1", "owner", "c1", "hi", OWNER_AUTH)])
+        await _pump(a, ws)
+        await _drain_waiters(a)
+        assert _acks(ws) == ["m1"]
+        await a.cancel_background_tasks()
+
+    def test_the_bound_default(self):
+        assert adapter._ACCEPT_WAIT_S == 10.0
+
+    @pytest.mark.asyncio
+    async def test_a_turn_cancelled_by_shutdown_before_acceptance_stays_unacked(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.gate("marker_gates", "m1")
+        f = _frame("m1", "owner", "c1", "hi", OWNER_AUTH)
+        ws = F2DaemonWS([f])
+        await _pump(a, ws)
+        await _settle()
+        await a.cancel_background_tasks()  # Hermes shutdown cancels the owner task
+        await _drain_waiters(a)
+        assert _acks(ws) == []  # no marker, so no Hermes resume: the daemon must redeliver
+        assert _nacks(ws) == ["m1"]  # failed back at once, not held until the socket closes
+        a._shutting_down = False
+        ws2 = F2DaemonWS([f])
+        await _pump(a, ws2)
+        assert r.started == ["m1", "m1"]  # the ledger forgot it: the redelivery runs
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_a_turn_cancelled_after_acceptance_was_already_acked(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        ws = F2DaemonWS([_frame("m1", "owner", "c1", "hi", OWNER_AUTH)])
+        await _pump(a, ws)
+        await _drain_waiters(a)
+        assert _acks(ws) == ["m1"]
+        await a.cancel_background_tasks()  # recovery is Hermes's own from here
+        assert _acks(ws) == ["m1"]
+
+    @pytest.mark.asyncio
+    async def test_disconnect_cancels_the_wait_and_forgets_the_id(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.gate("marker_gates", "m1")
+        f = _frame("m1", "owner", "c1", "hi", OWNER_AUTH)
+        ws = F2DaemonWS([f])
+        await _pump(a, ws)
+        await _settle()
+        waiters = list(a._ack_waiters)
+        assert len(waiters) == 1
+        await asyncio.wait_for(a.disconnect(), timeout=2)
+        assert all(t.cancelled() for t in waiters)
+        assert not a._ack_waiters
+        await a.cancel_background_tasks()
+        r.release("marker_gates", "m1")
+        assert _acks(ws) == []
+        # M3: the same adapter instance, reconnected, runs the redelivery.
+        a._shutting_down = False
+        a._stopped = False
+        ws2 = F2DaemonWS([f])
+        await _pump(a, ws2)
+        assert r.started == ["m1", "m1"]
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_a_dispatch_error_forgets_the_id_so_the_redelivery_runs(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        calls = []
+        real = a._dispatch
+
+        async def flaky(frame):
+            calls.append(frame["message_id"])
+            if len(calls) == 1:
+                raise RuntimeError("boom")
+            return await real(frame)
+
+        a._dispatch = flaky
+        r.release("turn_gates", "m1")
+        f = _frame("m1", "owner", "c1", "hi", OWNER_AUTH)
+        ws1 = F2DaemonWS([f])
+        with pytest.raises(RuntimeError):
+            await _pump(a, ws1)  # unchanged: the supervisor reconnects, no ack
+        assert _acks(ws1) == []
+        ws2 = F2DaemonWS([f])
+        await _pump(a, ws2)
+        await _drain_waiters(a)
+        assert calls == ["m1", "m1"]
+        assert _acks(ws2) == ["m1"]
+
+    @pytest.mark.asyncio
+    async def test_an_ack_dropped_during_a_long_outage_still_blocks_a_rerun(self, monkeypatch, ack_state):
+        # Round-2 M2: link down for longer than the dedup TTL.
+        a, r = make_hermes_adapter(monkeypatch)
+        clock = [0.0]
+        a._deliveries._now = lambda: clock[0]
+        r.gate("marker_gates", "m1")
+        f = _frame("m1", "owner", "c1", "hi", OWNER_AUTH)
+        await _pump(a, F2DaemonWS([f]))
+        await _settle()
+        a._ws = None  # link down when Hermes accepts: the ack cannot go out
+        r.release("marker_gates", "m1")
+        await _drain_waiters(a)
+        assert list(a._unsent_acks) == ["m1"]
+        r.release("turn_gates", "m1")  # the turn ends: a re-run would start a fresh turn
+        await _settle()
+        assert _turns_done(a)
+        clock[0] += adapter._DEDUP_TTL_S * 3
+        for i in range(adapter._DEDUP_MAX_ENTRIES + 5):  # and LRU pressure
+            a._deliveries.begin(f"x{i}")
+            a._deliveries.finish(f"x{i}")
+        ws2 = F2DaemonWS([f])
+        await _pump(a, ws2)
+        await _settle()
+        assert r.started == ["m1"]  # not re-run
+        assert _acks(ws2) == ["m1"]
+        assert not a._unsent_acks
+
+    @pytest.mark.asyncio
+    async def test_dropped_acks_are_flushed_on_the_next_connect(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+        r.gate("marker_gates", "m1")
+        await _pump(a, F2DaemonWS([_frame("m1", "owner", "c1", "hi", OWNER_AUTH)]))
+        await _settle()
+        a._ws = None
+        r.release("marker_gates", "m1")
+        await _drain_waiters(a)
+        files = {CONNECTIONS_DIR + "/A.json": conn_file(identity_id="A"), "/tok/A": "token-A"}
+        monkeypatch.setattr(adapter, "_read_file_text", make_fs(files))
+        monkeypatch.setattr(adapter, "_CONNECTIONS_DIR", CONNECTIONS_DIR)
+        ws = FakeWS()
+        session = FakeSession(healthz_by_url={"http://127.0.0.1:9001/healthz": {"identity_id": "A"}}, ws=ws)
+        monkeypatch.setattr(adapter, "_new_client_session", lambda: session)
+        assert await a._open_ws() is True
+        assert [f["type"] for f in ws.sent][:2] == ["hello", "ack"]
+        assert _acks(ws) == ["m1"]
+        assert not a._unsent_acks
+        r.release("turn_gates", "m1")
+        await a.cancel_background_tasks()
+
+    @pytest.mark.asyncio
+    async def test_an_ack_send_that_raises_is_kept_for_the_next_connect(self, monkeypatch, ack_state):
+        a, r = make_hermes_adapter(monkeypatch)
+
+        class BrokenWS(FakeWS):
+            async def send_json(self, payload):
+                raise ConnectionResetError("gone")
+
+        a._ws = BrokenWS()
+        await a._send_ack("m9")
+        assert list(a._unsent_acks) == ["m9"]
+        a._ws = ws = FakeWS()
+        await a._flush_unsent_acks()
+        assert _acks(ws) == ["m9"]
+        assert not a._unsent_acks
+
+    @pytest.mark.asyncio
+    async def test_without_the_hermes_acceptance_signal_it_acks_at_dispatch_and_warns_once(
+        self, monkeypatch, ack_state, caplog
+    ):
+        a, _ = make_adapter(monkeypatch)  # the plain stub: inline handler, no _gateway_accepted
+        a._bound_identity = "A"
+        seen = []
+
+        async def handler(event):
+            seen.append(event.message_id)
+
+        a.set_message_handler(handler)
+        with caplog.at_level("WARNING", logger=adapter.logger.name):
+            ws = await _pump_frames(a, [_frame("m1", "owner", "c1", "hi", OWNER_AUTH),
+                                        _frame("m2", "owner", "c2", "hi", OWNER_AUTH)])
+        assert seen == ["m1", "m2"]
+        assert _acks(ws) == ["m1", "m2"]
+        assert not a._ack_waiters
+        warned = [r for r in caplog.records if "acceptance signal unavailable" in r.getMessage()]
+        assert len(warned) == 1
+
+
+class TestDeliveryLedger:
+    def _ledger(self, max_entries=3, ttl=10.0):
+        clock = [0.0]
+        return adapter._DeliveryLedger(max_entries, ttl, lambda: clock[0]), clock
+
+    def test_states(self):
+        led, _ = self._ledger()
+        assert led.begin("a") == "new"
+        assert led.begin("a") == "in_flight"
+        led.finish("a")
+        assert led.begin("a") == "done"
+        led.forget("a")
+        assert led.begin("a") == "new"
+
+    def test_lru_bound_evicts_the_oldest_completed_entry(self):
+        led, _ = self._ledger(max_entries=3)
+        for mid in ("a", "b", "c", "d"):
+            led.begin(mid)
+            led.finish(mid)
+        assert len(led) == 3
+        assert led.begin("a") == "new"  # evicted, oldest first
+        assert led.begin("d") == "done"
+
+    def test_in_flight_entries_are_never_evicted(self):
+        led, _ = self._ledger(max_entries=2)
+        led.begin("live")
+        for mid in ("a", "b", "c"):
+            led.begin(mid)
+            led.finish(mid)
+        assert led.begin("live") == "in_flight"
+        assert len(led) <= 3
+
+    def test_completed_entries_expire_after_the_ttl_in_flight_ones_do_not(self):
+        led, clock = self._ledger(ttl=10.0)
+        led.begin("done")
+        led.finish("done")
+        led.begin("live")
+        clock[0] = 11.0
+        assert led.begin("done") == "new"
+        assert led.begin("live") == "in_flight"
+
+    def test_pinned_entries_survive_ttl_and_lru_until_unpinned(self):
+        led, clock = self._ledger(max_entries=2, ttl=10.0)
+        led.begin("p")
+        led.finish("p")
+        led.pin("p")
+        for mid in ("a", "b", "c"):
+            led.begin(mid)
+            led.finish(mid)
+        clock[0] = 100.0
+        assert led.begin("p") == "done"
+        led.unpin("p")
+        clock[0] = 200.0
+        assert led.begin("p") == "new"
+
+    def test_defaults(self):
+        assert adapter._DEDUP_MAX_ENTRIES == 2048
+        assert adapter._DEDUP_TTL_S == 600.0