@securecoms/agent-bridge 0.7.0 → 0.8.0

package/README.md

@@ -208,6 +208,8 @@ Three ways to receive, in order of preference for a long-running agent: the WebS
 
 `GET /v1/ws` upgrades to a single persistent bidirectional socket. The agent receives live messages and sends/reports status over the same connection — no polling, no separate send channel. This is the interface to use for an always-on agent.
 
+Two reference connectors speak this protocol today: openclaw (JavaScript) and hermes (Python), both implementing the same ADR-0009 connection-file + two-anchor-gate contract.
+
 Authenticate with the bearer token either as a query param (`ws://127.0.0.1:7077/v1/ws?token=<BRIDGE_TOKEN>`) or an `Authorization: Bearer` header on the upgrade request. The same loopback/Origin/Host rules as the HTTP API apply; an unauthorized upgrade is accepted and then closed with code `1008`.
 
 All frames are JSON text.

package/connectors/hermes/__init__.py

@@ -0,0 +1,60 @@
+"""SecureComs platform plugin for Hermes Agent.
+
+Bridges the local SecureComs Agent Bridge daemon (loopback) to the Hermes
+gateway, speaking the ADR-0009 connector contract (connection-file
+resolution, the two-anchor gate, the echo guard). See adapter.py for the
+BasePlatformAdapter implementation and the register(ctx) entry point;
+securecoms_transport.py and securecoms_gate.py carry all contract logic and
+are gateway-import-free.
+
+Packaging notes (task-3 review, DEFECT 1 + DEFECT 2 fold):
+
+Hermes's real plugin loader (hermes_cli/plugins.py's ``_load_directory_module``)
+imports this file via ``importlib.util.spec_from_file_location(module_name,
+init_file, submodule_search_locations=[plugin_dir])`` and sets
+``module.__path__ = [plugin_dir]`` on the resulting module BEFORE executing
+it - that gives a relative import here (``from .adapter import ...``) enough
+to find sibling files via the package's ``__path__``, WITHOUT ever adding
+``plugin_dir`` to ``sys.path``. But adapter.py/securecoms_transport.py import
+each other as bare top-level modules (``import securecoms_transport``,
+``from securecoms_gate import ...``) - the shape shared with their standalone
+unit tests (tests/test_securecoms_gate.py, tests/test_securecoms_transport.py
+import ``securecoms_gate``/``securecoms_transport`` directly, no package
+prefix) - and a bare absolute import resolves via ``sys.path``, not a
+package's ``__path__``. So we bootstrap ``sys.path`` here, once, before
+anything below needs it (DEFECT 1's fix).
+
+The `register` entry point below defers importing adapter.py (and therefore
+adapter.py's `gateway.*` imports, which don't exist outside a real Hermes
+install) until Hermes actually CALLS `register(ctx)` to activate the plugin -
+not merely when this file is imported. That matters because merely
+IMPORTING this `__init__.py` also happens as a side effect of pytest
+collecting any test file under `tests/` (pytest's Package collector runs
+`__init__.py` for any directory containing one, independent of which test
+file was asked for - see tests/test_securecoms_gate.py's docstring). A
+module-level `from .adapter import register` would make every solo `pytest
+tests/test_x.py` invocation require `gateway.*` to be importable in the CI
+backend venv, which spec §6 forbids for securecoms_gate.py/
+securecoms_transport.py's tests (DEFECT 2's fix).
+"""
+
+import os
+import sys
+
+_PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
+if _PLUGIN_DIR not in sys.path:
+    sys.path.insert(0, _PLUGIN_DIR)
+
+
+def register(ctx):
+    """Plugin entry point: called by the Hermes plugin system.
+
+    Deferred import - see module docstring. Only reached when Hermes
+    actually activates this plugin, never merely by importing this file.
+    """
+    from .adapter import register as _register
+
+    return _register(ctx)
+
+
+__all__ = ["register"]

package/connectors/hermes/adapter.py

@@ -0,0 +1,470 @@
+"""
+SecureComs Platform Adapter for Hermes Agent.
+
+Bridges the local SecureComs Agent Bridge daemon to the Hermes gateway over
+loopback. The daemon (a separate process started with
+``connect-agent-bridge --credential <agent>.json``) holds the agent credential
+and performs ALL MLS key agreement and AEAD encryption. This adapter speaks
+plaintext to the daemon on 127.0.0.1, guarded by the daemon's bearer token,
+and never touches cryptographic keys.
+
+Flow:
+    inbound:  daemon  --WS {type:message}-->  this adapter  -->  handle_message()
+              -->  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.
+
+This is the universal daemon-client pattern wearing a Hermes BasePlatformAdapter
+shim. The same daemon serves any framework; only this thin shim is
+Hermes-specific - ALL contract logic (connection-file/binding resolution, the
+two-anchor gate, the echo guard, per-channel status) lives in
+securecoms_transport.py and securecoms_gate.py, which are gateway-import-free
+and unit tested (see tests/test_securecoms_transport.py,
+tests/test_securecoms_gate.py). This module is covered by
+glue-wiring tests (tests/test_adapter_wiring.py, a stubbed gateway.*) plus
+live validation - it cannot run gateway.* imports in backend CI (spec §6).
+
+Wiring is a positive act (ADR-0009 C1): a ``securecoms.binding.json`` file
+beside this plugin (or the ``SECURECOMS_CONNECTION_FILE`` env override) names
+the identity_id this connector is bound to. That binding is resolved EXACTLY
+ONCE, at connect() - never re-derived on a reconnect - so a binding-file
+rewrite while the connector is running cannot silently re-bind it to a
+different agent (task-3 review, "BINDING-STABILITY fold"; see
+securecoms_transport.probe_and_gate_bound). Once bound, every (re)connect
+attempt re-reads ``~/.securecoms/connections/<identity_id>.json`` and the token file
+it points to from scratch, probes ``GET /healthz``, and runs the two-anchor
+gate before ever opening a websocket - so a daemon port move or a rotated
+token is picked up on the very next attempt (securecoms_gate.py's
+``evaluate_gate``).
+
+Config:
+    securecoms.binding.json (beside this plugin)   {"identity_id": "..."}
+    SECURECOMS_CONNECTION_FILE                     override: an alternate
+                                                    binding-shaped file to
+                                                    read identity_id from
+    SECURECOMS_ALLOW_ALL_USERS                     true to accept any
+                                                    admitted channel member
+    SECURECOMS_ALLOWED_USERS                       comma-separated sender
+                                                    identity_ids
+
+Deliberately NOT read here (dead config as of this promotion - see spec §5):
+``SECURECOMS_BRIDGE_URL``, ``SECURECOMS_BRIDGE_TOKEN``,
+``SECURECOMS_BRIDGE_TOKEN_FILE``. The daemon's address and bearer token are
+never accepted by value or cached across attempts - they come from the
+connection file and token file, re-read on every attempt, exactly like every
+other contract detail.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import time
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    SendResult,
+    MessageEvent,
+    MessageType,
+)
+from gateway.config import Platform
+
+import securecoms_transport
+from securecoms_gate import resolve_bound_identity
+
+logger = logging.getLogger(__name__)
+
+_PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
+_BINDING_PATH = os.path.join(_PLUGIN_DIR, "securecoms.binding.json")
+_CONNECTIONS_DIR = os.path.expanduser("~/.securecoms/connections")
+
+
+def _read_file_text(path: str) -> str:
+    with open(path, "r") as f:
+        return f.read()
+
+
+def _new_client_session():
+    """Seam for tests: the real implementation is a fresh aiohttp session
+    per connect attempt (see _open_ws's docstring for why per-attempt, not
+    per-adapter-life)."""
+    import aiohttp
+
+    return aiohttp.ClientSession()
+
+
+class SecureComsAdapter(BasePlatformAdapter):
+    """Hermes platform adapter fronting the local SecureComs daemon."""
+
+    def __init__(self, config, **kwargs):
+        super().__init__(config=config, platform=Platform("securecoms"))
+
+        # channel_id -> {"name": str, "is_dm": bool}
+        self._channels: Dict[str, Dict[str, Any]] = {}
+
+        # Resolved EXACTLY ONCE, by connect() - see the BINDING-STABILITY
+        # fold in the module docstring. None until connect() runs.
+        self._bound_identity: Optional[str] = None
+
+        self.bridge_url: Optional[str] = None
+        self.ws_url: Optional[str] = None
+        self._token: Optional[str] = None
+
+        self._session = None  # aiohttp.ClientSession - the CURRENT connected link
+        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
+
+        self._status = securecoms_transport.ChannelStatusManager(
+            self._send_status_frame, now=time.monotonic
+        )
+
+    @property
+    def name(self) -> str:
+        return "SecureComs"
+
+    def _auth(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._token}"}
+
+    # ── Connection lifecycle ──────────────────────────────────────────────
+
+    async def connect(self) -> bool:
+        self._stopped = False
+
+        # BINDING-STABILITY fold: resolve bound_identity here, ONCE, for the
+        # entire process life of this adapter instance. Every subsequent
+        # attempt (below, and every supervisor reconnect) passes this SAME
+        # value into securecoms_transport.probe_and_gate_bound, which takes no
+        # env/binding_path argument at all and so structurally cannot
+        # re-derive it.
+        self._bound_identity = resolve_bound_identity(
+            os.environ, _read_file_text, _BINDING_PATH
+        )
+        if not self._bound_identity:
+            # Boot-time check_requirements() already gates on the binding
+            # file's presence, so reaching connect() without a resolvable
+            # identity is a genuine config error (e.g. the file lost its
+            # identity_id field mid-race), not a transient daemon-not-up
+            # condition - non-retryable, matching the prior config_missing
+            # precedent.
+            self._set_fatal_error(
+                "unwired",
+                "no securecoms.binding.json (run `agent-bridge wire`)",
+                retryable=False,
+            )
+            return False
+
+        ok = await self._open_ws()
+        if not ok:
+            # _open_ws already reported the hold via _set_fatal_error
+            # (retryable=True); the gateway's reconnect watcher owns retry
+            # cadence from here (spec H1).
+            return False
+
+        # Supervisor owns the receive pump AND reconnection: any daemon-side
+        # drop (daemon restart, network blip) is recovered automatically
+        # with backoff, so presence and message flow self-heal without a
+        # gateway restart. A lightweight periodic tick keeps per-channel
+        # status honest even when a turn's send_typing refreshes stop
+        # arriving (handler error, silently-abandoned turn).
+        self._recv_task = asyncio.create_task(self._supervise())
+        self._tick_task = asyncio.create_task(self._tick_loop())
+        self._mark_connected()
+        logger.info("SecureComs: connected to daemon at %s", self.bridge_url)
+        return True
+
+    async def _open_ws(self) -> bool:
+        """One connect attempt: fresh session -> probe_and_gate_bound (the
+        FIXED self._bound_identity - never re-derived) -> ws_connect.
+
+        Every failed attempt closes its OWN per-attempt session (the #37011
+        fd-leak class this design engineers against) before returning; only
+        a successful attempt installs its session as self._session. Reports
+        exactly one log line per hold-state CHANGE (spec H1), via
+        _enter_hold/_leave_hold, not per retry.
+        """
+        session = _new_client_session()
+        target, reason = await securecoms_transport.probe_and_gate_bound(
+            session, self._bound_identity, _read_file_text, _CONNECTIONS_DIR
+        )
+        if target is None:
+            await session.close()
+            self._enter_hold(reason)
+            return False
+
+        try:
+            ws = await session.ws_connect(
+                target.ws_url,
+                headers={"Authorization": f"Bearer {target.token}"},
+                heartbeat=30.0,
+            )
+        except Exception as e:
+            await session.close()
+            self._enter_hold(f"daemon unreachable at {target.bridge_url}: {e}")
+            return False
+
+        self._session = session
+        self._ws = ws
+        self.bridge_url = target.bridge_url
+        self.ws_url = target.ws_url
+        self._token = target.token
+        self._leave_hold()
+        await self._refresh_channels()
+        return True
+
+    def _enter_hold(self, reason: str) -> None:
+        changed = self._hold_reason != reason
+        self._hold_reason = reason
+        if changed:
+            logger.warning("SecureComs: waiting for SecureComs daemon: %s", reason)
+        self._set_fatal_error(
+            "waiting_for_daemon",
+            f"waiting for SecureComs daemon: {reason}",
+            retryable=True,
+        )
+
+    def _leave_hold(self) -> None:
+        self._hold_reason = None
+
+    async def _supervise(self) -> None:
+        """Receive pump + auto-reconnect loop. Runs until disconnect() sets
+        _stopped. On a WS drop it marks the channel disconnected (so
+        presence reflects the gap), tears down the dead link, then retries
+        _open_ws with capped exponential backoff. Mirrors the OpenClaw
+        connector."""
+        backoff = 1.0
+        while not self._stopped:
+            try:
+                await self._pump()  # returns when the WS closes
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                logger.warning("SecureComs: receive error: %s", e)
+            if self._stopped:
+                break
+            self._mark_disconnected()
+            await self._teardown_link()
+            while not self._stopped:
+                logger.info(
+                    "SecureComs: daemon link dropped; reconnecting in %.0fs", backoff
+                )
+                await asyncio.sleep(backoff)
+                if self._stopped:
+                    break
+                if await self._open_ws():
+                    self._mark_connected()
+                    backoff = 1.0
+                    logger.info("SecureComs: reconnected to daemon")
+                    break
+                backoff = min(backoff * 2, 30.0)
+
+    async def _teardown_link(self) -> None:
+        try:
+            if self._ws and not self._ws.closed:
+                await self._ws.close()
+        except Exception:
+            pass
+        try:
+            if self._session and not self._session.closed:
+                await self._session.close()
+        except Exception:
+            pass
+        self._ws = None
+        self._session = None
+
+    async def disconnect(self) -> None:
+        self._stopped = True  # stop the reconnect supervisor before tearing down
+        self._mark_disconnected()
+        for task_attr in ("_recv_task", "_tick_task"):
+            task = getattr(self, task_attr)
+            if task and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+        await self._teardown_link()
+
+    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")),
+                        }
+        except Exception as e:
+            logger.debug("SecureComs: channel refresh failed: %s", e)
+
+    # ── Status emit ───────────────────────────────────────────────────────
+
+    async def _send_status_frame(self, frame: dict) -> None:
+        if self._ws is None:
+            return
+        try:
+            await self._ws.send_json(frame)
+        except Exception as e:
+            logger.debug("SecureComs: status frame send failed: %s", e)
+
+    async def _tick_loop(self) -> None:
+        """Drives ChannelStatusManager.tick() so a channel goes idle after
+        20s of silence even when no send()/send_typing() fires again for it
+        (turn ended without a reply, handler raised, etc.)."""
+        while not self._stopped:
+            try:
+                await asyncio.sleep(5.0)
+                await self._status.tick()
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                logger.debug("SecureComs: status tick error: %s", e)
+
+    # ── Inbound ───────────────────────────────────────────────────────────
+
+    async def _pump(self) -> None:
+        """Receive frames until the WS closes, then RETURN so the supervisor
+        reconnects. Does NOT signal a fatal error - a dropped daemon link is
+        recoverable and the supervisor heals it."""
+        import aiohttp
+
+        async for msg in self._ws:
+            if msg.type == aiohttp.WSMsgType.TEXT:
+                try:
+                    frame = json.loads(msg.data)
+                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: %s", e)
+            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:
+            return
+        if securecoms_transport.should_drop_inbound(frame, self._bound_identity):
+            return  # 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", "")
+        meta = self._channels.get(channel_id, {})
+        chat_type = "dm" if meta.get("is_dm", True) else "group"
+
+        source = self.build_source(
+            chat_id=channel_id,
+            chat_name=meta.get("name", channel_id),
+            chat_type=chat_type,
+            user_id=sender_id,
+            user_name=sender_id,
+        )
+        event = MessageEvent(
+            text=text,
+            message_type=MessageType.TEXT,
+            source=source,
+            message_id=str(frame.get("message_id") or int(time.time() * 1000)),
+            timestamp=datetime.now(),
+        )
+        await self.handle_message(event)
+
+    # ── Outbound ──────────────────────────────────────────────────────────
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        if not self._session or self._session.closed:
+            return SendResult(success=False, error="not connected")
+        try:
+            async with self._session.post(
+                f"{self.bridge_url}/v1/send",
+                headers=self._auth(),
+                json={"channel_id": chat_id, "text": content},
+            ) as r:
+                if r.status == 200:
+                    j = await r.json()
+                    await self._status.on_reply_posted(chat_id)
+                    return SendResult(success=True, message_id=str(j.get("message_id")))
+                if r.status == 503:
+                    # daemon not yet admitted to the channel — retryable upstream
+                    return SendResult(success=False, error="channel_pending")
+                body = await r.text()
+                return SendResult(success=False, error=f"send failed: {r.status} {body[:200]}")
+        except Exception as e:
+            return SendResult(success=False, error=str(e))
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        await self._status.on_typing(chat_id)
+
+    async def send_image(self, chat_id: str, image_url: str, caption: str = "", **kwargs) -> SendResult:
+        # The daemon's text send is the only modality wired today; degrade to
+        # sending the URL + caption as text rather than failing the turn.
+        text = f"{caption}\n{image_url}".strip() if caption else image_url
+        return await self.send(chat_id, text)
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        meta = self._channels.get(chat_id)
+        if not meta:
+            await self._refresh_channels()
+            meta = self._channels.get(chat_id, {})
+        return {
+            "name": meta.get("name", chat_id),
+            "type": "dm" if meta.get("is_dm", True) else "group",
+            "chat_id": chat_id,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Plugin registration
+# ---------------------------------------------------------------------------
+
+def check_requirements() -> bool:
+    """Wiring is a positive act (ADR-0009 C1): the connector is enabled at
+    boot only when its binding file is present - unwired hosts stay quietly
+    disabled, exactly like today's env-gated quiet. This does NOT probe the
+    daemon; connect() alone decides connected vs. holding.
+
+    Also honors the SECURECOMS_CONNECTION_FILE override (task-3 review,
+    reviewer one-liner (a)): a host wired purely via that env var - no
+    securecoms.binding.json on disk - must still show as enabled at boot,
+    matching gate.resolve_bound_identity's own env-first precedence."""
+    return os.path.isfile(os.getenv("SECURECOMS_CONNECTION_FILE") or _BINDING_PATH)
+
+
+def register(ctx):
+    """Plugin entry point: called by the Hermes plugin system."""
+    ctx.register_platform(
+        name="securecoms",
+        label="SecureComs",
+        adapter_factory=lambda cfg: SecureComsAdapter(cfg),
+        check_fn=check_requirements,
+        is_connected=check_requirements,
+        install_hint="Run `agent-bridge wire --harness hermes` to write securecoms.binding.json",
+        allowed_users_env="SECURECOMS_ALLOWED_USERS",
+        allow_all_env="SECURECOMS_ALLOW_ALL_USERS",
+        emoji="🔒",
+        pii_safe=True,
+        allow_update_command=False,
+        platform_hint=(
+            "You are chatting via SecureComs, an end-to-end encrypted channel. "
+            "Messages are relayed through a local encryption daemon; the server "
+            "never sees plaintext. Respond normally and conversationally."
+        ),
+    )

package/connectors/hermes/plugin.yaml

@@ -0,0 +1,25 @@
+name: securecoms-platform
+label: SecureComs
+kind: platform
+version: 0.2.0
+description: >
+  SecureComs gateway adapter for Hermes Agent. Bridges the local SecureComs
+  Agent Bridge daemon (end-to-end MLS encrypted messaging) to the Hermes
+  gateway over loopback. The daemon holds the credential and does all
+  cryptography; this adapter speaks plaintext to the daemon on 127.0.0.1 and
+  never touches keys. Inbound SecureComs messages are dispatched to the agent;
+  the agent's replies are sent back through the daemon. Wiring is a
+  securecoms.binding.json file written by `agent-bridge wire` - there is no
+  token env var to configure; the daemon address and bearer token are read
+  fresh from ~/.securecoms/connections/<identity_id>.json on every connect
+  attempt.
+author: AgentVault
+optional_env:
+  - name: SECURECOMS_ALLOW_ALL_USERS
+    description: "Allow any member of an admitted SecureComs channel to talk to the agent (the channel is already E2E-restricted to admitted members)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: SECURECOMS_ALLOWED_USERS
+    description: "Comma-separated SecureComs sender identity_ids allowed to talk to the agent"
+    prompt: "Allowed sender identity_ids"
+    password: false

package/connectors/hermes/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+asyncio_mode = auto
+addopts = --import-mode=importlib

package/connectors/hermes/securecoms_gate.py

@@ -0,0 +1,70 @@
+# packages/connect-agent-bridge/connectors/hermes/securecoms_gate.py
+#
+# Python port of ../openclaw/gate.js. Pure functions, no I/O, stdlib only.
+# Proves the ADR-0009 connector contract isn't language-shaped.
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Callable, Mapping, Optional, Tuple
+
+
+def resolve_bound_identity(
+    env: Mapping[str, str],
+    read_file_text: Callable[[str], str],
+    binding_path: str,
+) -> Optional[str]:
+    """bound_identity: explicit binding ONLY.
+
+    There is no directory-census / auto-discovery path here (audit C1) -
+    bound_identity must be a positive act (an env var or a binding file),
+    never inferred by scanning a connections directory for a sole entry.
+    Any read_file_text exception (missing file, bad JSON, ...) is treated
+    as "absent" and falls through.
+    """
+    conn_file = env.get("SECURECOMS_CONNECTION_FILE") if env else None
+    if conn_file:
+        try:
+            identity_id = json.loads(read_file_text(conn_file)).get("identity_id")
+            if identity_id:
+                return identity_id
+        except Exception:
+            pass  # fall through
+    try:
+        identity_id = json.loads(read_file_text(binding_path)).get("identity_id")
+        if identity_id:
+            return identity_id
+    except Exception:
+        pass  # no binding
+    return None
+
+
+def evaluate_gate(
+    bound_identity: Optional[str],
+    file_identity: Optional[str],
+    healthz_identity: Optional[str],
+) -> Tuple[bool, str]:
+    """The two-anchor gate: refuse unless the connector's own binding, the
+    on-disk connection file, and the daemon's live healthz identity all
+    agree. Order matters (see the check-order mutation in the task brief) -
+    check 1 must run before check 2.
+    """
+    if not bound_identity:
+        return False, "unwired: no binding (refusing to guess)"
+    if file_identity != healthz_identity:
+        return False, "check 1 failed: file identity != daemon identity (stale port reuse)"
+    if bound_identity != healthz_identity:
+        return False, "check 2 failed: bound identity != daemon identity (wrong file / compartment)"
+    return True, ""
+
+
+def backoff_delay_ms(attempt: int, rand: Callable[[], float]) -> int:
+    """Full-jitter exponential backoff, capped at 30s. `rand` is injected
+    (rather than reaching for the stdlib `random` module) so tests can pin
+    the jitter and assert the ceiling deterministically (F6).
+    """
+    base = 250
+    cap = 30000
+    exp = min(cap, base * (2 ** max(0, attempt)))
+    return math.floor(rand() * exp)