Merge branch 'main' of github.com:NousResearch/hermes-agent into feat/ink-refactor

gateway/config.py

@@ -63,6 +63,7 @@ class Platform(Enum):
     WEBHOOK = "webhook"
     FEISHU = "feishu"
     WECOM = "wecom"
+    WECOM_CALLBACK = "wecom_callback"
     WEIXIN = "weixin"
     BLUEBUBBLES = "bluebubbles"
 
@@ -291,9 +292,14 @@ class GatewayConfig:
             # Feishu uses extra dict for app credentials
             elif platform == Platform.FEISHU and config.extra.get("app_id"):
                 connected.append(platform)
-            # WeCom uses extra dict for bot credentials
+            # WeCom bot mode uses extra dict for bot credentials
             elif platform == Platform.WECOM and config.extra.get("bot_id"):
                 connected.append(platform)
+            # WeCom callback mode uses corp_id or apps list
+            elif platform == Platform.WECOM_CALLBACK and (
+                config.extra.get("corp_id") or config.extra.get("apps")
+            ):
+                connected.append(platform)
             # BlueBubbles uses extra dict for local server config
             elif platform == Platform.BLUEBUBBLES and config.extra.get("server_url") and config.extra.get("password"):
                 connected.append(platform)
@@ -987,6 +993,23 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 name=os.getenv("WECOM_HOME_CHANNEL_NAME", "Home"),
             )
 
+    # WeCom callback mode (self-built apps)
+    wecom_callback_corp_id = os.getenv("WECOM_CALLBACK_CORP_ID")
+    wecom_callback_corp_secret = os.getenv("WECOM_CALLBACK_CORP_SECRET")
+    if wecom_callback_corp_id and wecom_callback_corp_secret:
+        if Platform.WECOM_CALLBACK not in config.platforms:
+            config.platforms[Platform.WECOM_CALLBACK] = PlatformConfig()
+        config.platforms[Platform.WECOM_CALLBACK].enabled = True
+        config.platforms[Platform.WECOM_CALLBACK].extra.update({
+            "corp_id": wecom_callback_corp_id,
+            "corp_secret": wecom_callback_corp_secret,
+            "agent_id": os.getenv("WECOM_CALLBACK_AGENT_ID", ""),
+            "token": os.getenv("WECOM_CALLBACK_TOKEN", ""),
+            "encoding_aes_key": os.getenv("WECOM_CALLBACK_ENCODING_AES_KEY", ""),
+            "host": os.getenv("WECOM_CALLBACK_HOST", "0.0.0.0"),
+            "port": int(os.getenv("WECOM_CALLBACK_PORT", "8645")),
+        })
+
     # Weixin (personal WeChat via iLink Bot API)
     weixin_token = os.getenv("WEIXIN_TOKEN")
     weixin_account_id = os.getenv("WEIXIN_ACCOUNT_ID")

gateway/display_config.py

@@ -0,0 +1,206 @@
+"""Per-platform display/verbosity configuration resolver.
+
+Provides ``resolve_display_setting()`` — the single entry-point for reading
+display settings with platform-specific overrides and sensible defaults.
+
+Resolution order (first non-None wins):
+    1. ``display.platforms.<platform>.<key>``  — explicit per-platform user override
+    2. ``display.<key>``                       — global user setting
+    3. ``_PLATFORM_DEFAULTS[<platform>][<key>]``  — built-in sensible default
+    4. ``_GLOBAL_DEFAULTS[<key>]``              — built-in global default
+
+Backward compatibility: ``display.tool_progress_overrides`` is still read as a
+fallback for ``tool_progress`` when no ``display.platforms`` entry exists.  A
+config migration (version bump) automatically moves the old format into the new
+``display.platforms`` structure.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Overrideable display settings and their global defaults
+# ---------------------------------------------------------------------------
+# These are the settings that can be configured per-platform.
+# Other display settings (compact, personality, skin, etc.) are CLI-only
+# and don't participate in per-platform resolution.
+
+_GLOBAL_DEFAULTS: dict[str, Any] = {
+    "tool_progress": "all",
+    "show_reasoning": False,
+    "tool_preview_length": 0,
+    "streaming": None,  # None = follow top-level streaming config
+}
+
+# ---------------------------------------------------------------------------
+# Sensible per-platform defaults — tiered by platform capability
+# ---------------------------------------------------------------------------
+# Tier 1 (high): Supports message editing, typically personal/team use
+# Tier 2 (medium): Supports editing but often workspace/customer-facing
+# Tier 3 (low): No edit support — each progress msg is permanent
+# Tier 4 (minimal): Batch/non-interactive delivery
+
+_TIER_HIGH = {
+    "tool_progress": "all",
+    "show_reasoning": False,
+    "tool_preview_length": 40,
+    "streaming": None,  # follow global
+}
+
+_TIER_MEDIUM = {
+    "tool_progress": "new",
+    "show_reasoning": False,
+    "tool_preview_length": 40,
+    "streaming": None,
+}
+
+_TIER_LOW = {
+    "tool_progress": "off",
+    "show_reasoning": False,
+    "tool_preview_length": 40,
+    "streaming": False,
+}
+
+_TIER_MINIMAL = {
+    "tool_progress": "off",
+    "show_reasoning": False,
+    "tool_preview_length": 0,
+    "streaming": False,
+}
+
+_PLATFORM_DEFAULTS: dict[str, dict[str, Any]] = {
+    # Tier 1 — full edit support, personal/team use
+    "telegram":    _TIER_HIGH,
+    "discord":     _TIER_HIGH,
+
+    # Tier 2 — edit support, often customer/workspace channels
+    "slack":           _TIER_MEDIUM,
+    "mattermost":      _TIER_MEDIUM,
+    "matrix":          _TIER_MEDIUM,
+    "feishu":          _TIER_MEDIUM,
+
+    # Tier 3 — no edit support, progress messages are permanent
+    "signal":          _TIER_LOW,
+    "whatsapp":        _TIER_LOW,
+    "bluebubbles":     _TIER_LOW,
+    "weixin":          _TIER_LOW,
+    "wecom":           _TIER_LOW,
+    "wecom_callback":  _TIER_LOW,
+    "dingtalk":        _TIER_LOW,
+
+    # Tier 4 — batch or non-interactive delivery
+    "email":           _TIER_MINIMAL,
+    "sms":             _TIER_MINIMAL,
+    "webhook":         _TIER_MINIMAL,
+    "homeassistant":   _TIER_MINIMAL,
+    "api_server":      {**_TIER_HIGH, "tool_preview_length": 0},
+}
+
+# Canonical set of per-platform overrideable keys (for validation).
+OVERRIDEABLE_KEYS = frozenset(_GLOBAL_DEFAULTS.keys())
+
+
+def resolve_display_setting(
+    user_config: dict,
+    platform_key: str,
+    setting: str,
+    fallback: Any = None,
+) -> Any:
+    """Resolve a display setting with per-platform override support.
+
+    Parameters
+    ----------
+    user_config : dict
+        The full parsed config.yaml dict.
+    platform_key : str
+        Platform config key (e.g. ``"telegram"``, ``"slack"``).  Use
+        ``_platform_config_key(source.platform)`` from gateway/run.py.
+    setting : str
+        Display setting name (e.g. ``"tool_progress"``, ``"show_reasoning"``).
+    fallback : Any
+        Fallback value when the setting isn't found anywhere.
+
+    Returns
+    -------
+    The resolved value, or *fallback* if nothing is configured.
+    """
+    display_cfg = user_config.get("display") or {}
+
+    # 1. Explicit per-platform override (display.platforms.<platform>.<key>)
+    platforms = display_cfg.get("platforms") or {}
+    plat_overrides = platforms.get(platform_key)
+    if isinstance(plat_overrides, dict):
+        val = plat_overrides.get(setting)
+        if val is not None:
+            return _normalise(setting, val)
+
+    # 1b. Backward compat: display.tool_progress_overrides.<platform>
+    if setting == "tool_progress":
+        legacy = display_cfg.get("tool_progress_overrides")
+        if isinstance(legacy, dict):
+            val = legacy.get(platform_key)
+            if val is not None:
+                return _normalise(setting, val)
+
+    # 2. Global user setting (display.<key>)
+    val = display_cfg.get(setting)
+    if val is not None:
+        return _normalise(setting, val)
+
+    # 3. Built-in platform default
+    plat_defaults = _PLATFORM_DEFAULTS.get(platform_key)
+    if plat_defaults:
+        val = plat_defaults.get(setting)
+        if val is not None:
+            return val
+
+    # 4. Built-in global default
+    val = _GLOBAL_DEFAULTS.get(setting)
+    if val is not None:
+        return val
+
+    return fallback
+
+
+def get_platform_defaults(platform_key: str) -> dict[str, Any]:
+    """Return the built-in default display settings for a platform.
+
+    Falls back to ``_GLOBAL_DEFAULTS`` for unknown platforms.
+    """
+    return dict(_PLATFORM_DEFAULTS.get(platform_key, _GLOBAL_DEFAULTS))
+
+
+def get_effective_display(user_config: dict, platform_key: str) -> dict[str, Any]:
+    """Return the fully-resolved display settings for a platform.
+
+    Useful for status commands that want to show all effective settings.
+    """
+    return {
+        key: resolve_display_setting(user_config, platform_key, key)
+        for key in OVERRIDEABLE_KEYS
+    }
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _normalise(setting: str, value: Any) -> Any:
+    """Normalise YAML quirks (bare ``off`` → False in YAML 1.1)."""
+    if setting == "tool_progress":
+        if value is False:
+            return "off"
+        if value is True:
+            return "all"
+        return str(value).lower()
+    if setting in ("show_reasoning", "streaming"):
+        if isinstance(value, str):
+            return value.lower() in ("true", "1", "yes", "on")
+        return bool(value)
+    if setting == "tool_preview_length":
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return 0
+    return value

gateway/platforms/discord.py

@@ -456,6 +456,7 @@ class DiscordAdapter(BasePlatformAdapter):
         # show the standard typing gateway event for bots)
         self._typing_tasks: Dict[str, asyncio.Task] = {}
         self._bot_task: Optional[asyncio.Task] = None
+        self._post_connect_task: Optional[asyncio.Task] = None
         # Dedup cache: prevents duplicate bot responses when Discord
         # RESUME replays events after reconnects.
         self._dedup = MessageDeduplicator()
@@ -545,15 +546,14 @@ class DiscordAdapter(BasePlatformAdapter):
 
                 # Resolve any usernames in the allowed list to numeric IDs
                 await adapter_self._resolve_allowed_usernames()
-
-                # Sync slash commands with Discord
-                try:
-                    synced = await adapter_self._client.tree.sync()
-                    logger.info("[%s] Synced %d slash command(s)", adapter_self.name, len(synced))
-                except Exception as e:  # pragma: no cover - defensive logging
-                    logger.warning("[%s] Slash command sync failed: %s", adapter_self.name, e, exc_info=True)
                 adapter_self._ready_event.set()
 
+                if adapter_self._post_connect_task and not adapter_self._post_connect_task.done():
+                    adapter_self._post_connect_task.cancel()
+                adapter_self._post_connect_task = asyncio.create_task(
+                    adapter_self._run_post_connect_initialization()
+                )
+
             @self._client.event
             async def on_message(message: DiscordMessage):
                 # Dedup: Discord RESUME replays events after reconnects (#4777)
@@ -686,14 +686,36 @@ class DiscordAdapter(BasePlatformAdapter):
             except Exception as e:  # pragma: no cover - defensive logging
                 logger.warning("[%s] Error during disconnect: %s", self.name, e, exc_info=True)
 
+        if self._post_connect_task and not self._post_connect_task.done():
+            self._post_connect_task.cancel()
+            try:
+                await self._post_connect_task
+            except asyncio.CancelledError:
+                pass
+
         self._running = False
         self._client = None
         self._ready_event.clear()
+        self._post_connect_task = None
 
         self._release_platform_lock()
 
         logger.info("[%s] Disconnected", self.name)
 
+    async def _run_post_connect_initialization(self) -> None:
+        """Finish non-critical startup work after Discord is connected."""
+        if not self._client:
+            return
+        try:
+            synced = await asyncio.wait_for(self._client.tree.sync(), timeout=30)
+            logger.info("[%s] Synced %d slash command(s)", self.name, len(synced))
+        except asyncio.TimeoutError:
+            logger.warning("[%s] Slash command sync timed out after 30s", self.name)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:  # pragma: no cover - defensive logging
+            logger.warning("[%s] Slash command sync failed: %s", self.name, e, exc_info=True)
+
     async def _add_reaction(self, message: Any, emoji: str) -> bool:
         """Add an emoji reaction to a Discord message."""
         if not message or not hasattr(message, "add_reaction"):

gateway/platforms/matrix.py

@@ -18,6 +18,7 @@ Environment variables:
     MATRIX_REQUIRE_MENTION      Require @mention in rooms (default: true)
     MATRIX_FREE_RESPONSE_ROOMS  Comma-separated room IDs exempt from mention requirement
     MATRIX_AUTO_THREAD          Auto-create threads for room messages (default: true)
+    MATRIX_RECOVERY_KEY         Recovery key for cross-signing verification after device key rotation
     MATRIX_DM_MENTION_THREADS   Create a thread when bot is @mentioned in a DM (default: false)
 """
 
@@ -104,7 +105,7 @@ MAX_MESSAGE_LENGTH = 4000
 # Uses get_hermes_home() so each profile gets its own Matrix store.
 from hermes_constants import get_hermes_dir as _get_hermes_dir
 _STORE_DIR = _get_hermes_dir("platforms/matrix/store", "matrix/store")
-_CRYPTO_PICKLE_PATH = _STORE_DIR / "crypto_store.pickle"
+_CRYPTO_DB_PATH = _STORE_DIR / "crypto.db"
 
 # Grace period: ignore messages older than this many seconds before startup.
 _STARTUP_GRACE_SECONDS = 5
@@ -165,6 +166,33 @@ def check_matrix_requirements() -> bool:
     return True
 
 
+class _CryptoStateStore:
+    """Adapter that satisfies the mautrix crypto StateStore interface.
+
+    OlmMachine requires a StateStore with ``is_encrypted``,
+    ``get_encryption_info``, and ``find_shared_rooms``.  The basic
+    ``MemoryStateStore`` from ``mautrix.client`` doesn't implement these,
+    so we provide simple implementations that consult the client's room
+    state.
+    """
+
+    def __init__(self, client_state_store: Any, joined_rooms: set):
+        self._ss = client_state_store
+        self._joined_rooms = joined_rooms
+
+    async def is_encrypted(self, room_id: str) -> bool:
+        return (await self.get_encryption_info(room_id)) is not None
+
+    async def get_encryption_info(self, room_id: str):
+        if hasattr(self._ss, "get_encryption_info"):
+            return await self._ss.get_encryption_info(room_id)
+        return None
+
+    async def find_shared_rooms(self, user_id: str) -> list:
+        # Return all joined rooms — simple but correct for a single-user bot.
+        return list(self._joined_rooms)
+
+
 class MatrixAdapter(BasePlatformAdapter):
     """Gateway adapter for Matrix (any homeserver)."""
 
@@ -199,6 +227,7 @@ class MatrixAdapter(BasePlatformAdapter):
         )
 
         self._client: Any = None  # mautrix.client.Client
+        self._crypto_db: Any = None  # mautrix.util.async_db.Database
         self._sync_task: Optional[asyncio.Task] = None
         self._closing = False
         self._startup_ts: float = 0.0
@@ -252,6 +281,92 @@ class MatrixAdapter(BasePlatformAdapter):
         self._processed_events_set.add(event_id)
         return False
 
+    # ------------------------------------------------------------------
+    # E2EE helpers
+    # ------------------------------------------------------------------
+
+    async def _verify_device_keys_on_server(self, client: Any, olm: Any) -> bool:
+        """Verify our device keys are on the homeserver after loading crypto state.
+
+        Returns True if keys are valid or were successfully re-uploaded.
+        Returns False if verification fails (caller should refuse E2EE).
+        """
+        try:
+            resp = await client.query_keys({client.mxid: [client.device_id]})
+        except Exception as exc:
+            logger.error(
+                "Matrix: cannot verify device keys on server: %s — refusing E2EE", exc,
+            )
+            return False
+
+        # query_keys returns typed objects (QueryKeysResponse, DeviceKeys
+        # with KeyID keys).  Normalise to plain strings for comparison.
+        device_keys_map = getattr(resp, "device_keys", {}) or {}
+        our_user_devices = device_keys_map.get(str(client.mxid)) or {}
+        our_keys = our_user_devices.get(str(client.device_id))
+
+        if not our_keys:
+            logger.warning("Matrix: device keys missing from server — re-uploading")
+            olm.account.shared = False
+            try:
+                await olm.share_keys()
+            except Exception as exc:
+                logger.error("Matrix: failed to re-upload device keys: %s", exc)
+                return False
+            return True
+
+        # DeviceKeys.keys is a dict[KeyID, str].  Iterate to find the
+        # ed25519 key rather than constructing a KeyID for lookup.
+        server_ed25519 = None
+        keys_dict = getattr(our_keys, "keys", {}) or {}
+        for key_id, key_value in keys_dict.items():
+            if str(key_id).startswith("ed25519:"):
+                server_ed25519 = str(key_value)
+                break
+        local_ed25519 = olm.account.identity_keys.get("ed25519")
+
+        if server_ed25519 != local_ed25519:
+            if olm.account.shared:
+                # Restored account from DB but server has different keys — corrupted state.
+                logger.error(
+                    "Matrix: server has different identity keys for device %s — "
+                    "local crypto state is stale. Delete %s and restart.",
+                    client.device_id,
+                    _CRYPTO_DB_PATH,
+                )
+                return False
+
+            # Fresh account (never uploaded). Server has stale keys from a
+            # previous installation. Try to delete the old device and re-upload.
+            logger.warning(
+                "Matrix: server has stale keys for device %s — attempting re-upload",
+                client.device_id,
+            )
+            try:
+                await client.api.request(
+                    client.api.Method.DELETE
+                    if hasattr(client.api, "Method")
+                    else "DELETE",
+                    f"/_matrix/client/v3/devices/{client.device_id}",
+                )
+                logger.info("Matrix: deleted stale device %s from server", client.device_id)
+            except Exception:
+                # Device deletion often requires UIA or may simply not be
+                # permitted — that's fine, share_keys will try to overwrite.
+                pass
+            try:
+                await olm.share_keys()
+            except Exception as exc:
+                logger.error(
+                    "Matrix: cannot upload device keys for %s: %s. "
+                    "Try generating a new access token to get a fresh device.",
+                    client.device_id,
+                    exc,
+                )
+                return False
+
+        return True
+
     # ------------------------------------------------------------------
     # Required overrides
     # ------------------------------------------------------------------
@@ -350,54 +465,67 @@ class MatrixAdapter(BasePlatformAdapter):
                 return False
             try:
                 from mautrix.crypto import OlmMachine
-                from mautrix.crypto.store import MemoryCryptoStore
+                from mautrix.crypto.store.asyncpg import PgCryptoStore
+                from mautrix.util.async_db import Database
+
+                _STORE_DIR.mkdir(parents=True, exist_ok=True)
+
+                # Remove legacy pickle file from pre-SQLite era.
+                legacy_pickle = _STORE_DIR / "crypto_store.pickle"
+                if legacy_pickle.exists():
+                    logger.info("Matrix: removing legacy crypto_store.pickle (migrated to SQLite)")
+                    legacy_pickle.unlink()
+
+                # Open SQLite-backed crypto store.
+                crypto_db = Database.create(
+                    f"sqlite:///{_CRYPTO_DB_PATH}",
+                    upgrade_table=PgCryptoStore.upgrade_table,
+                )
+                await crypto_db.start()
+                self._crypto_db = crypto_db
 
-                # account_id and pickle_key are required by mautrix ≥0.21.
-                # Use the Matrix user ID as account_id for stable identity.
-                # pickle_key secures in-memory serialisation; derive from
-                # the same user_id:device_id pair used for the on-disk HMAC.
                 _acct_id = self._user_id or "hermes"
-                _pickle_key = f"{_acct_id}:{self._device_id}"
-                crypto_store = MemoryCryptoStore(
+                _pickle_key = f"{_acct_id}:{self._device_id or 'default'}"
+                crypto_store = PgCryptoStore(
                     account_id=_acct_id,
                     pickle_key=_pickle_key,
+                    db=crypto_db,
                 )
+                await crypto_store.open()
 
-                # Restore persisted crypto state from a previous run.
-                # Uses HMAC to verify integrity before unpickling.
-                pickle_path = _CRYPTO_PICKLE_PATH
-                if pickle_path.exists():
-                    try:
-                        import hashlib, hmac, pickle
-                        raw = pickle_path.read_bytes()
-                        # Format: 32-byte HMAC-SHA256 signature + pickle data.
-                        if len(raw) > 32:
-                            sig, payload = raw[:32], raw[32:]
-                            # Key is derived from the device_id + user_id (stable per install).
-                            hmac_key = f"{self._user_id}:{self._device_id}".encode()
-                            expected = hmac.new(hmac_key, payload, hashlib.sha256).digest()
-                            if hmac.compare_digest(sig, expected):
-                                saved = pickle.loads(payload)  # noqa: S301
-                                if isinstance(saved, MemoryCryptoStore):
-                                    crypto_store = saved
-                                    logger.info("Matrix: restored E2EE crypto store from %s", pickle_path)
-                            else:
-                                logger.warning("Matrix: crypto store HMAC mismatch — ignoring stale/tampered file")
-                    except Exception as exc:
-                        logger.warning("Matrix: could not restore crypto store: %s", exc)
+                crypto_state = _CryptoStateStore(state_store, self._joined_rooms)
+                olm = OlmMachine(client, crypto_store, crypto_state)
 
-                olm = OlmMachine(client, crypto_store, state_store)
-
-                # Set trust policy: accept unverified devices so senders
-                # share Megolm session keys with us automatically.
+                # Accept unverified devices so senders share Megolm
+                # session keys with us automatically.
                 olm.share_keys_min_trust = TrustState.UNVERIFIED
                 olm.send_keys_min_trust = TrustState.UNVERIFIED
 
                 await olm.load()
+
+                # Verify our device keys are still on the homeserver.
+                if not await self._verify_device_keys_on_server(client, olm):
+                    await crypto_db.stop()
+                    await api.session.close()
+                    return False
+
+                # Import cross-signing private keys from SSSS and self-sign
+                # the current device. Required after any device-key rotation
+                # (fresh crypto.db, share_keys re-upload) — otherwise the
+                # device's self-signing signature is stale and peers refuse
+                # to share Megolm sessions with the rotated device.
+                recovery_key = os.getenv("MATRIX_RECOVERY_KEY", "").strip()
+                if recovery_key:
+                    try:
+                        await olm.verify_with_recovery_key(recovery_key)
+                        logger.info("Matrix: cross-signing verified via recovery key")
+                    except Exception as exc:
+                        logger.warning("Matrix: recovery key verification failed: %s", exc)
+
                 client.crypto = olm
                 logger.info(
                     "Matrix: E2EE enabled (store: %s%s)",
-                    str(_STORE_DIR),
+                    str(_CRYPTO_DB_PATH),
                     f", device_id={client.device_id}" if client.device_id else "",
                 )
             except Exception as exc:
@@ -438,6 +566,15 @@ class MatrixAdapter(BasePlatformAdapter):
                 )
                 # Build DM room cache from m.direct account data.
                 await self._refresh_dm_cache()
+
+                # Dispatch events from the initial sync so the OlmMachine
+                # receives to-device key shares queued while we were offline.
+                try:
+                    tasks = client.handle_sync(sync_data)
+                    if tasks:
+                        await asyncio.gather(*tasks)
+                except Exception as exc:
+                    logger.warning("Matrix: initial sync event dispatch error: %s", exc)
             else:
                 logger.warning("Matrix: initial sync returned unexpected type %s", type(sync_data).__name__)
         except Exception as exc:
@@ -466,21 +603,12 @@ class MatrixAdapter(BasePlatformAdapter):
             except (asyncio.CancelledError, Exception):
                 pass
 
-        # Persist E2EE crypto store before closing so the next restart
-        # can decrypt events using sessions from this run.
-        if self._client and self._encryption and getattr(self._client, "crypto", None):
+        # Close the SQLite crypto store database.
+        if hasattr(self, "_crypto_db") and self._crypto_db:
             try:
-                import hashlib, hmac, pickle
-                crypto_store = self._client.crypto.crypto_store
-                _STORE_DIR.mkdir(parents=True, exist_ok=True)
-                pickle_path = _CRYPTO_PICKLE_PATH
-                payload = pickle.dumps(crypto_store)
-                hmac_key = f"{self._user_id}:{self._device_id}".encode()
-                sig = hmac.new(hmac_key, payload, hashlib.sha256).digest()
-                pickle_path.write_bytes(sig + payload)
-                logger.info("Matrix: persisted E2EE crypto store to %s", pickle_path)
+                await self._crypto_db.stop()
             except Exception as exc:
-                logger.debug("Matrix: could not persist crypto store on disconnect: %s", exc)
+                logger.debug("Matrix: could not close crypto DB on disconnect: %s", exc)
 
         if self._client:
             try:
@@ -853,13 +981,6 @@ class MatrixAdapter(BasePlatformAdapter):
                     except Exception as exc:
                         logger.warning("Matrix: sync event dispatch error: %s", exc)
 
-                # Share keys periodically if E2EE is enabled.
-                if self._encryption and getattr(client, "crypto", None):
-                    try:
-                        await client.crypto.share_keys()
-                    except Exception as exc:
-                        logger.warning("Matrix: E2EE key share failed: %s", exc)
-
                 # Retry any buffered undecrypted events.
                 if self._pending_megolm:
                     await self._retry_pending_decryptions()

gateway/platforms/webhook.py

@@ -201,6 +201,7 @@ class WebhookAdapter(BasePlatformAdapter):
             "dingtalk",
             "feishu",
             "wecom",
+            "wecom_callback",
             "weixin",
             "bluebubbles",
         ):

gateway/platforms/wecom_callback.py

@@ -0,0 +1,387 @@
+"""WeCom callback-mode adapter for self-built enterprise applications.
+
+Unlike the bot/websocket adapter in ``wecom.py``, this handles the standard
+WeCom callback flow: WeCom POSTs encrypted XML to an HTTP endpoint, the
+adapter decrypts it, queues the message for the agent, and immediately
+acknowledges.  The agent's reply is delivered later via the proactive
+``message/send`` API using an access-token.
+
+Supports multiple self-built apps under one gateway instance, scoped by
+``corp_id:user_id`` to avoid cross-corp collisions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import socket as _socket
+import time
+from typing import Any, Dict, List, Optional
+from xml.etree import ElementTree as ET
+
+try:
+    from aiohttp import web
+
+    AIOHTTP_AVAILABLE = True
+except ImportError:
+    web = None  # type: ignore[assignment]
+    AIOHTTP_AVAILABLE = False
+
+try:
+    import httpx
+
+    HTTPX_AVAILABLE = True
+except ImportError:
+    httpx = None  # type: ignore[assignment]
+    HTTPX_AVAILABLE = False
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import BasePlatformAdapter, MessageEvent, MessageType, SendResult
+from gateway.platforms.wecom_crypto import WXBizMsgCrypt, WeComCryptoError
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_HOST = "0.0.0.0"
+DEFAULT_PORT = 8645
+DEFAULT_PATH = "/wecom/callback"
+ACCESS_TOKEN_TTL_SECONDS = 7200
+MESSAGE_DEDUP_TTL_SECONDS = 300
+
+
+def check_wecom_callback_requirements() -> bool:
+    return AIOHTTP_AVAILABLE and HTTPX_AVAILABLE
+
+
+class WecomCallbackAdapter(BasePlatformAdapter):
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.WECOM_CALLBACK)
+        extra = config.extra or {}
+        self._host = str(extra.get("host") or DEFAULT_HOST)
+        self._port = int(extra.get("port") or DEFAULT_PORT)
+        self._path = str(extra.get("path") or DEFAULT_PATH)
+        self._apps: List[Dict[str, Any]] = self._normalize_apps(extra)
+        self._runner: Optional[web.AppRunner] = None
+        self._site: Optional[web.TCPSite] = None
+        self._app: Optional[web.Application] = None
+        self._http_client: Optional[httpx.AsyncClient] = None
+        self._message_queue: asyncio.Queue[MessageEvent] = asyncio.Queue()
+        self._poll_task: Optional[asyncio.Task] = None
+        self._seen_messages: Dict[str, float] = {}
+        self._user_app_map: Dict[str, str] = {}
+        self._access_tokens: Dict[str, Dict[str, Any]] = {}
+
+    # ------------------------------------------------------------------
+    # App normalisation
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _user_app_key(corp_id: str, user_id: str) -> str:
+        return f"{corp_id}:{user_id}" if corp_id else user_id
+
+    @staticmethod
+    def _normalize_apps(extra: Dict[str, Any]) -> List[Dict[str, Any]]:
+        apps = extra.get("apps")
+        if isinstance(apps, list) and apps:
+            return [dict(app) for app in apps if isinstance(app, dict)]
+        if extra.get("corp_id"):
+            return [
+                {
+                    "name": extra.get("name") or "default",
+                    "corp_id": extra.get("corp_id", ""),
+                    "corp_secret": extra.get("corp_secret", ""),
+                    "agent_id": str(extra.get("agent_id", "")),
+                    "token": extra.get("token", ""),
+                    "encoding_aes_key": extra.get("encoding_aes_key", ""),
+                }
+            ]
+        return []
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        if not self._apps:
+            logger.warning("[WecomCallback] No callback apps configured")
+            return False
+        if not check_wecom_callback_requirements():
+            logger.warning("[WecomCallback] aiohttp/httpx not installed")
+            return False
+
+        # Quick port-in-use check.
+        try:
+            with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as sock:
+                sock.settimeout(1)
+                sock.connect(("127.0.0.1", self._port))
+            logger.error("[WecomCallback] Port %d already in use", self._port)
+            return False
+        except (ConnectionRefusedError, OSError):
+            pass
+
+        try:
+            self._http_client = httpx.AsyncClient(timeout=20.0)
+            self._app = web.Application()
+            self._app.router.add_get("/health", self._handle_health)
+            self._app.router.add_get(self._path, self._handle_verify)
+            self._app.router.add_post(self._path, self._handle_callback)
+            self._runner = web.AppRunner(self._app)
+            await self._runner.setup()
+            self._site = web.TCPSite(self._runner, self._host, self._port)
+            await self._site.start()
+            self._poll_task = asyncio.create_task(self._poll_loop())
+            self._mark_connected()
+            logger.info(
+                "[WecomCallback] HTTP server listening on %s:%s%s",
+                self._host, self._port, self._path,
+            )
+            for app in self._apps:
+                try:
+                    await self._refresh_access_token(app)
+                except Exception as exc:
+                    logger.warning(
+                        "[WecomCallback] Initial token refresh failed for app '%s': %s",
+                        app.get("name", "default"), exc,
+                    )
+            return True
+        except Exception:
+            await self._cleanup()
+            logger.exception("[WecomCallback] Failed to start")
+            return False
+
+    async def disconnect(self) -> None:
+        self._running = False
+        if self._poll_task:
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+            self._poll_task = None
+        await self._cleanup()
+        self._mark_disconnected()
+        logger.info("[WecomCallback] Disconnected")
+
+    async def _cleanup(self) -> None:
+        self._site = None
+        if self._runner:
+            await self._runner.cleanup()
+            self._runner = None
+        self._app = None
+        if self._http_client:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    # ------------------------------------------------------------------
+    # Outbound: proactive send via access-token API
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        app = self._resolve_app_for_chat(chat_id)
+        touser = chat_id.split(":", 1)[1] if ":" in chat_id else chat_id
+        try:
+            token = await self._get_access_token(app)
+            payload = {
+                "touser": touser,
+                "msgtype": "text",
+                "agentid": int(str(app.get("agent_id") or 0)),
+                "text": {"content": content[:2048]},
+                "safe": 0,
+            }
+            resp = await self._http_client.post(
+                f"https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={token}",
+                json=payload,
+            )
+            data = resp.json()
+            if data.get("errcode") != 0:
+                return SendResult(success=False, error=str(data))
+            return SendResult(
+                success=True,
+                message_id=str(data.get("msgid", "")),
+                raw_response=data,
+            )
+        except Exception as exc:
+            return SendResult(success=False, error=str(exc))
+
+    def _resolve_app_for_chat(self, chat_id: str) -> Dict[str, Any]:
+        """Pick the app associated with *chat_id*, falling back sensibly."""
+        app_name = self._user_app_map.get(chat_id)
+        if not app_name and ":" not in chat_id:
+            # Legacy bare user_id — try to find a unique match.
+            matching = [k for k in self._user_app_map if k.endswith(f":{chat_id}")]
+            if len(matching) == 1:
+                app_name = self._user_app_map.get(matching[0])
+        app = self._get_app_by_name(app_name) if app_name else None
+        return app or self._apps[0]
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        return {"name": chat_id, "type": "dm"}
+
+    # ------------------------------------------------------------------
+    # Inbound: HTTP callback handlers
+    # ------------------------------------------------------------------
+
+    async def _handle_health(self, request: web.Request) -> web.Response:
+        return web.json_response({"status": "ok", "platform": "wecom_callback"})
+
+    async def _handle_verify(self, request: web.Request) -> web.Response:
+        """GET endpoint — WeCom URL verification handshake."""
+        msg_signature = request.query.get("msg_signature", "")
+        timestamp = request.query.get("timestamp", "")
+        nonce = request.query.get("nonce", "")
+        echostr = request.query.get("echostr", "")
+        for app in self._apps:
+            try:
+                crypt = self._crypt_for_app(app)
+                plain = crypt.verify_url(msg_signature, timestamp, nonce, echostr)
+                return web.Response(text=plain, content_type="text/plain")
+            except Exception:
+                continue
+        return web.Response(status=403, text="signature verification failed")
+
+    async def _handle_callback(self, request: web.Request) -> web.Response:
+        """POST endpoint — receive an encrypted message callback."""
+        msg_signature = request.query.get("msg_signature", "")
+        timestamp = request.query.get("timestamp", "")
+        nonce = request.query.get("nonce", "")
+        body = await request.text()
+
+        for app in self._apps:
+            try:
+                decrypted = self._decrypt_request(
+                    app, body, msg_signature, timestamp, nonce,
+                )
+                event = self._build_event(app, decrypted)
+                if event is not None:
+                    # Record which app this user belongs to.
+                    if event.source and event.source.user_id:
+                        map_key = self._user_app_key(
+                            str(app.get("corp_id") or ""), event.source.user_id,
+                        )
+                        self._user_app_map[map_key] = app["name"]
+                    await self._message_queue.put(event)
+                # Immediately acknowledge — the agent's reply will arrive
+                # later via the proactive message/send API.
+                return web.Response(text="success", content_type="text/plain")
+            except WeComCryptoError:
+                continue
+            except Exception:
+                logger.exception("[WecomCallback] Error handling message")
+                break
+        return web.Response(status=400, text="invalid callback payload")
+
+    async def _poll_loop(self) -> None:
+        """Drain the message queue and dispatch to the gateway runner."""
+        while True:
+            event = await self._message_queue.get()
+            try:
+                task = asyncio.create_task(self.handle_message(event))
+                self._background_tasks.add(task)
+                task.add_done_callback(self._background_tasks.discard)
+            except Exception:
+                logger.exception("[WecomCallback] Failed to enqueue event")
+
+    # ------------------------------------------------------------------
+    # XML / crypto helpers
+    # ------------------------------------------------------------------
+
+    def _decrypt_request(
+        self, app: Dict[str, Any], body: str,
+        msg_signature: str, timestamp: str, nonce: str,
+    ) -> str:
+        root = ET.fromstring(body)
+        encrypt = root.findtext("Encrypt", default="")
+        crypt = self._crypt_for_app(app)
+        return crypt.decrypt(msg_signature, timestamp, nonce, encrypt).decode("utf-8")
+
+    def _build_event(self, app: Dict[str, Any], xml_text: str) -> Optional[MessageEvent]:
+        root = ET.fromstring(xml_text)
+        msg_type = (root.findtext("MsgType") or "").lower()
+        # Silently acknowledge lifecycle events.
+        if msg_type == "event":
+            event_name = (root.findtext("Event") or "").lower()
+            if event_name in {"enter_agent", "subscribe"}:
+                return None
+        if msg_type not in {"text", "event"}:
+            return None
+
+        user_id = root.findtext("FromUserName", default="")
+        corp_id = root.findtext("ToUserName", default=app.get("corp_id", ""))
+        scoped_chat_id = self._user_app_key(corp_id, user_id)
+        content = root.findtext("Content", default="").strip()
+        if not content and msg_type == "event":
+            content = "/start"
+        msg_id = (
+            root.findtext("MsgId")
+            or f"{user_id}:{root.findtext('CreateTime', default='0')}"
+        )
+        source = self.build_source(
+            chat_id=scoped_chat_id,
+            chat_name=user_id,
+            chat_type="dm",
+            user_id=user_id,
+            user_name=user_id,
+        )
+        return MessageEvent(
+            text=content,
+            message_type=MessageType.TEXT,
+            source=source,
+            raw_message=xml_text,
+            message_id=msg_id,
+        )
+
+    def _crypt_for_app(self, app: Dict[str, Any]) -> WXBizMsgCrypt:
+        return WXBizMsgCrypt(
+            token=str(app.get("token") or ""),
+            encoding_aes_key=str(app.get("encoding_aes_key") or ""),
+            receive_id=str(app.get("corp_id") or ""),
+        )
+
+    def _get_app_by_name(self, name: Optional[str]) -> Optional[Dict[str, Any]]:
+        if not name:
+            return None
+        for app in self._apps:
+            if app.get("name") == name:
+                return app
+        return None
+
+    # ------------------------------------------------------------------
+    # Access-token management
+    # ------------------------------------------------------------------
+
+    async def _get_access_token(self, app: Dict[str, Any]) -> str:
+        cached = self._access_tokens.get(app["name"])
+        now = time.time()
+        if cached and cached.get("expires_at", 0) > now + 60:
+            return cached["token"]
+        return await self._refresh_access_token(app)
+
+    async def _refresh_access_token(self, app: Dict[str, Any]) -> str:
+        resp = await self._http_client.get(
+            "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
+            params={
+                "corpid": app.get("corp_id"),
+                "corpsecret": app.get("corp_secret"),
+            },
+        )
+        data = resp.json()
+        if data.get("errcode") != 0:
+            raise RuntimeError(f"WeCom token refresh failed: {data}")
+        token = data["access_token"]
+        expires_in = int(data.get("expires_in", ACCESS_TOKEN_TTL_SECONDS))
+        self._access_tokens[app["name"]] = {
+            "token": token,
+            "expires_at": time.time() + expires_in,
+        }
+        logger.info(
+            "[WecomCallback] Token refreshed for app '%s' (corp=%s), expires in %ss",
+            app.get("name", "default"),
+            app.get("corp_id", ""),
+            expires_in,
+        )
+        return token

gateway/platforms/wecom_crypto.py

@@ -0,0 +1,142 @@
+"""WeCom BizMsgCrypt-compatible AES-CBC encryption for callback mode.
+
+Implements the same wire format as Tencent's official ``WXBizMsgCrypt``
+SDK so that WeCom can verify, encrypt, and decrypt callback payloads.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import secrets
+import socket
+import struct
+from typing import Optional
+from xml.etree import ElementTree as ET
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+
+class WeComCryptoError(Exception):
+    pass
+
+
+class SignatureError(WeComCryptoError):
+    pass
+
+
+class DecryptError(WeComCryptoError):
+    pass
+
+
+class EncryptError(WeComCryptoError):
+    pass
+
+
+class PKCS7Encoder:
+    block_size = 32
+
+    @classmethod
+    def encode(cls, text: bytes) -> bytes:
+        amount_to_pad = cls.block_size - (len(text) % cls.block_size)
+        if amount_to_pad == 0:
+            amount_to_pad = cls.block_size
+        pad = bytes([amount_to_pad]) * amount_to_pad
+        return text + pad
+
+    @classmethod
+    def decode(cls, decrypted: bytes) -> bytes:
+        if not decrypted:
+            raise DecryptError("empty decrypted payload")
+        pad = decrypted[-1]
+        if pad < 1 or pad > cls.block_size:
+            raise DecryptError("invalid PKCS7 padding")
+        if decrypted[-pad:] != bytes([pad]) * pad:
+            raise DecryptError("malformed PKCS7 padding")
+        return decrypted[:-pad]
+
+
+def _sha1_signature(token: str, timestamp: str, nonce: str, encrypt: str) -> str:
+    parts = sorted([token, timestamp, nonce, encrypt])
+    return hashlib.sha1("".join(parts).encode("utf-8")).hexdigest()
+
+
+class WXBizMsgCrypt:
+    """Minimal WeCom callback crypto helper compatible with BizMsgCrypt semantics."""
+
+    def __init__(self, token: str, encoding_aes_key: str, receive_id: str):
+        if not token:
+            raise ValueError("token is required")
+        if not encoding_aes_key:
+            raise ValueError("encoding_aes_key is required")
+        if len(encoding_aes_key) != 43:
+            raise ValueError("encoding_aes_key must be 43 chars")
+        if not receive_id:
+            raise ValueError("receive_id is required")
+
+        self.token = token
+        self.receive_id = receive_id
+        self.key = base64.b64decode(encoding_aes_key + "=")
+        self.iv = self.key[:16]
+
+    def verify_url(self, msg_signature: str, timestamp: str, nonce: str, echostr: str) -> str:
+        plain = self.decrypt(msg_signature, timestamp, nonce, echostr)
+        return plain.decode("utf-8")
+
+    def decrypt(self, msg_signature: str, timestamp: str, nonce: str, encrypt: str) -> bytes:
+        expected = _sha1_signature(self.token, timestamp, nonce, encrypt)
+        if expected != msg_signature:
+            raise SignatureError("signature mismatch")
+        try:
+            cipher_text = base64.b64decode(encrypt)
+        except Exception as exc:
+            raise DecryptError(f"invalid base64 payload: {exc}") from exc
+        try:
+            cipher = Cipher(algorithms.AES(self.key), modes.CBC(self.iv), backend=default_backend())
+            decryptor = cipher.decryptor()
+            padded = decryptor.update(cipher_text) + decryptor.finalize()
+            plain = PKCS7Encoder.decode(padded)
+            content = plain[16:]  # skip 16-byte random prefix
+            xml_length = socket.ntohl(struct.unpack("I", content[:4])[0])
+            xml_content = content[4:4 + xml_length]
+            receive_id = content[4 + xml_length:].decode("utf-8")
+        except WeComCryptoError:
+            raise
+        except Exception as exc:
+            raise DecryptError(f"decrypt failed: {exc}") from exc
+
+        if receive_id != self.receive_id:
+            raise DecryptError("receive_id mismatch")
+        return xml_content
+
+    def encrypt(self, plaintext: str, nonce: Optional[str] = None, timestamp: Optional[str] = None) -> str:
+        nonce = nonce or self._random_nonce()
+        timestamp = timestamp or str(int(__import__("time").time()))
+        encrypt = self._encrypt_bytes(plaintext.encode("utf-8"))
+        signature = _sha1_signature(self.token, timestamp, nonce, encrypt)
+        root = ET.Element("xml")
+        ET.SubElement(root, "Encrypt").text = encrypt
+        ET.SubElement(root, "MsgSignature").text = signature
+        ET.SubElement(root, "TimeStamp").text = timestamp
+        ET.SubElement(root, "Nonce").text = nonce
+        return ET.tostring(root, encoding="unicode")
+
+    def _encrypt_bytes(self, raw: bytes) -> str:
+        try:
+            random_prefix = os.urandom(16)
+            msg_len = struct.pack("I", socket.htonl(len(raw)))
+            payload = random_prefix + msg_len + raw + self.receive_id.encode("utf-8")
+            padded = PKCS7Encoder.encode(payload)
+            cipher = Cipher(algorithms.AES(self.key), modes.CBC(self.iv), backend=default_backend())
+            encryptor = cipher.encryptor()
+            encrypted = encryptor.update(padded) + encryptor.finalize()
+            return base64.b64encode(encrypted).decode("utf-8")
+        except Exception as exc:
+            raise EncryptError(f"encrypt failed: {exc}") from exc
+
+    @staticmethod
+    def _random_nonce(length: int = 10) -> str:
+        alphabet = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+        return "".join(secrets.choice(alphabet) for _ in range(length))

gateway/platforms/weixin.py

@@ -734,6 +734,42 @@ def _split_delivery_units_for_weixin(content: str) -> List[str]:
     return [unit for unit in units if unit]
 
 
+def _looks_like_chatty_line_for_weixin(line: str) -> bool:
+    """Return True when a line looks like a standalone chat utterance."""
+    stripped = line.strip()
+    if not stripped:
+        return False
+    if len(stripped) > 48:
+        return False
+    if line.startswith((" ", "\t")):
+        return False
+    if stripped.startswith((">", "-", "*", "【")):
+        return False
+    if re.match(r"^\*\*[^*]+\*\*$", stripped):
+        return False
+    if re.match(r"^\d+\.\s", stripped):
+        return False
+    return True
+
+
+def _looks_like_heading_line_for_weixin(line: str) -> bool:
+    """Return True when a short line behaves like a plain-text heading."""
+    stripped = line.strip()
+    if not stripped:
+        return False
+    return len(stripped) <= 24 and stripped.endswith((":", "："))
+
+
+def _should_split_short_chat_block_for_weixin(block: str) -> bool:
+    """Split only chat-like multiline blocks into separate bubbles."""
+    lines = [line for line in block.splitlines() if line.strip()]
+    if not 2 <= len(lines) <= 6:
+        return False
+    if _looks_like_heading_line_for_weixin(lines[0]):
+        return False
+    return all(_looks_like_chatty_line_for_weixin(line) for line in lines)
+
+
 def _pack_markdown_blocks_for_weixin(content: str, max_length: int) -> List[str]:
     if len(content) <= max_length:
         return [content]
@@ -787,9 +823,15 @@ def _split_text_for_weixin_delivery(
             chunks.extend(_pack_markdown_blocks_for_weixin(unit, max_length))
         return chunks or [content]
 
-    # Compact (default): single message when under the limit.
+    # Compact (default): single message when under the limit — unless the
+    # content looks like a short chatty exchange, in which case split into
+    # separate bubbles for a more natural chat feel.
     if len(content) <= max_length:
-        return [content]
+        return (
+            _split_delivery_units_for_weixin(content)
+            if _should_split_short_chat_block_for_weixin(content)
+            else [content]
+        )
     return _pack_markdown_blocks_for_weixin(content, max_length) or [content]
 
 

gateway/run.py

@@ -76,7 +76,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 
 # Resolve Hermes home directory (respects HERMES_HOME override)
 from hermes_constants import get_hermes_home
-from utils import atomic_yaml_write
+from utils import atomic_yaml_write, is_truthy_value
 _hermes_home = get_hermes_home()
 
 # Load environment variables from ~/.hermes/.env first.
@@ -206,6 +206,15 @@ if _config_path.exists():
     except Exception:
         pass  # Non-fatal; gateway can still run with .env values
 
+# Apply IPv4 preference if configured (before any HTTP clients are created).
+try:
+    from hermes_constants import apply_ipv4_preference
+    _network_cfg = (_cfg if '_cfg' in dir() else {}).get("network", {})
+    if isinstance(_network_cfg, dict) and _network_cfg.get("force_ipv4"):
+        apply_ipv4_preference(force=True)
+except Exception:
+    pass
+
 # Validate config structure early — log warnings so gateway operators see problems
 try:
     from hermes_cli.config import print_config_warnings
@@ -867,13 +876,47 @@ class GatewayRunner:
                 "api_mode": override.get("api_mode"),
             }
             if override_runtime.get("api_key"):
+                logger.debug(
+                    "Session model override (fast): session=%s config_model=%s -> override_model=%s provider=%s",
+                    (resolved_session_key or "")[:30], model, override_model,
+                    override_runtime.get("provider"),
+                )
                 return override_model, override_runtime
+            # Override exists but has no api_key — fall through to env-based
+            # resolution and apply model/provider from the override on top.
+            logger.debug(
+                "Session model override (no api_key, fallback): session=%s config_model=%s override_model=%s",
+                (resolved_session_key or "")[:30], model, override_model,
+            )
+        else:
+            logger.debug(
+                "No session model override: session=%s config_model=%s override_keys=%s",
+                (resolved_session_key or "")[:30], model,
+                list(self._session_model_overrides.keys())[:5] if self._session_model_overrides else "[]",
+            )
 
         runtime_kwargs = _resolve_runtime_agent_kwargs()
         if override and resolved_session_key:
             model, runtime_kwargs = self._apply_session_model_override(
                 resolved_session_key, model, runtime_kwargs
             )
+
+        # When the config has no model.default but a provider was resolved
+        # (e.g. user ran `hermes auth add openai-codex` without `hermes model`),
+        # fall back to the provider's first catalog model so the API call
+        # doesn't fail with "model must be a non-empty string".
+        if not model and runtime_kwargs.get("provider"):
+            try:
+                from hermes_cli.models import get_default_model_for_provider
+                model = get_default_model_for_provider(runtime_kwargs["provider"])
+                if model:
+                    logger.info(
+                        "No model configured — defaulting to %s for provider %s",
+                        model, runtime_kwargs["provider"],
+                    )
+            except Exception:
+                pass
+
         return model, runtime_kwargs
 
     def _resolve_turn_agent_config(self, user_message: str, model: str, runtime_kwargs: dict) -> dict:
@@ -916,6 +959,12 @@ class GatewayRunner:
             adapter.fatal_error_code or "unknown",
             adapter.fatal_error_message or "unknown error",
         )
+        self._update_platform_runtime_status(
+            adapter.platform.value,
+            platform_state="retrying" if adapter.fatal_error_retryable else "fatal",
+            error_code=adapter.fatal_error_code,
+            error_message=adapter.fatal_error_message,
+        )
 
         existing = self.adapters.get(adapter.platform)
         if existing is adapter:
@@ -993,6 +1042,25 @@ class GatewayRunner:
             )
         except Exception:
             pass
+
+    def _update_platform_runtime_status(
+        self,
+        platform: str,
+        *,
+        platform_state: Optional[str] = None,
+        error_code: Optional[str] = None,
+        error_message: Optional[str] = None,
+    ) -> None:
+        try:
+            from gateway.status import write_runtime_status
+            write_runtime_status(
+                platform=platform,
+                platform_state=platform_state,
+                error_code=error_code,
+                error_message=error_message,
+            )
+        except Exception:
+            pass
     
     @staticmethod
     def _load_prefill_messages() -> List[Dict[str, Any]]:
@@ -1426,6 +1494,7 @@ class GatewayRunner:
                        "MATRIX_ALLOWED_USERS", "DINGTALK_ALLOWED_USERS",
                        "FEISHU_ALLOWED_USERS",
                        "WECOM_ALLOWED_USERS",
+                       "WECOM_CALLBACK_ALLOWED_USERS",
                        "WEIXIN_ALLOWED_USERS",
                        "BLUEBUBBLES_ALLOWED_USERS",
                        "GATEWAY_ALLOWED_USERS")
@@ -1439,6 +1508,7 @@ class GatewayRunner:
                        "MATRIX_ALLOW_ALL_USERS", "DINGTALK_ALLOW_ALL_USERS",
                        "FEISHU_ALLOW_ALL_USERS",
                        "WECOM_ALLOW_ALL_USERS",
+                       "WECOM_CALLBACK_ALLOW_ALL_USERS",
                        "WEIXIN_ALLOW_ALL_USERS",
                        "BLUEBUBBLES_ALLOW_ALL_USERS")
         )
@@ -1465,12 +1535,25 @@ class GatewayRunner:
         # This prevents stuck sessions from being blindly resumed on restart,
         # which can create an unrecoverable loop (#7536).  Suspended sessions
         # auto-reset on the next incoming message, giving the user a clean start.
-        try:
-            suspended = self.session_store.suspend_recently_active()
-            if suspended:
-                logger.info("Suspended %d in-flight session(s) from previous run", suspended)
-        except Exception as e:
-            logger.warning("Session suspension on startup failed: %s", e)
+        #
+        # SKIP suspension after a clean (graceful) shutdown — the previous
+        # process already drained active agents, so sessions aren't stuck.
+        # This prevents unwanted auto-resets after `hermes update`,
+        # `hermes gateway restart`, or `/restart`.
+        _clean_marker = _hermes_home / ".clean_shutdown"
+        if _clean_marker.exists():
+            logger.info("Previous gateway exited cleanly — skipping session suspension")
+            try:
+                _clean_marker.unlink()
+            except Exception:
+                pass
+        else:
+            try:
+                suspended = self.session_store.suspend_recently_active()
+                if suspended:
+                    logger.info("Suspended %d in-flight session(s) from previous run", suspended)
+            except Exception as e:
+                logger.warning("Session suspension on startup failed: %s", e)
 
         connected_count = 0
         enabled_platform_count = 0
@@ -1496,16 +1579,34 @@ class GatewayRunner:
             
             # Try to connect
             logger.info("Connecting to %s...", platform.value)
+            self._update_platform_runtime_status(
+                platform.value,
+                platform_state="connecting",
+                error_code=None,
+                error_message=None,
+            )
             try:
                 success = await adapter.connect()
                 if success:
                     self.adapters[platform] = adapter
                     self._sync_voice_mode_state_to_adapter(adapter)
                     connected_count += 1
+                    self._update_platform_runtime_status(
+                        platform.value,
+                        platform_state="connected",
+                        error_code=None,
+                        error_message=None,
+                    )
                     logger.info("✓ %s connected", platform.value)
                 else:
                     logger.warning("✗ %s failed to connect", platform.value)
                     if adapter.has_fatal_error:
+                        self._update_platform_runtime_status(
+                            platform.value,
+                            platform_state="retrying" if adapter.fatal_error_retryable else "fatal",
+                            error_code=adapter.fatal_error_code,
+                            error_message=adapter.fatal_error_message,
+                        )
                         target = (
                             startup_retryable_errors
                             if adapter.fatal_error_retryable
@@ -1522,6 +1623,12 @@ class GatewayRunner:
                                 "next_retry": time.monotonic() + 30,
                             }
                     else:
+                        self._update_platform_runtime_status(
+                            platform.value,
+                            platform_state="retrying",
+                            error_code=None,
+                            error_message="failed to connect",
+                        )
                         startup_retryable_errors.append(
                             f"{platform.value}: failed to connect"
                         )
@@ -1533,6 +1640,12 @@ class GatewayRunner:
                         }
             except Exception as e:
                 logger.error("✗ %s error: %s", platform.value, e)
+                self._update_platform_runtime_status(
+                    platform.value,
+                    platform_state="retrying",
+                    error_code=None,
+                    error_message=str(e),
+                )
                 startup_retryable_errors.append(f"{platform.value}: {e}")
                 # Unexpected exceptions are typically transient — queue for retry
                 self._failed_platforms[platform] = {
@@ -1811,6 +1924,12 @@ class GatewayRunner:
                         self._sync_voice_mode_state_to_adapter(adapter)
                         self.delivery_router.adapters = self.adapters
                         del self._failed_platforms[platform]
+                        self._update_platform_runtime_status(
+                            platform.value,
+                            platform_state="connected",
+                            error_code=None,
+                            error_message=None,
+                        )
                         logger.info("✓ %s reconnected successfully", platform.value)
 
                         # Rebuild channel directory with the new adapter
@@ -1822,12 +1941,24 @@ class GatewayRunner:
                     else:
                         # Check if the failure is non-retryable
                         if adapter.has_fatal_error and not adapter.fatal_error_retryable:
+                            self._update_platform_runtime_status(
+                                platform.value,
+                                platform_state="fatal",
+                                error_code=adapter.fatal_error_code,
+                                error_message=adapter.fatal_error_message,
+                            )
                             logger.warning(
                                 "Reconnect %s: non-retryable error (%s), removing from retry queue",
                                 platform.value, adapter.fatal_error_message,
                             )
                             del self._failed_platforms[platform]
                         else:
+                            self._update_platform_runtime_status(
+                                platform.value,
+                                platform_state="retrying",
+                                error_code=adapter.fatal_error_code,
+                                error_message=adapter.fatal_error_message or "failed to reconnect",
+                            )
                             backoff = min(30 * (2 ** (attempt - 1)), _BACKOFF_CAP)
                             info["attempts"] = attempt
                             info["next_retry"] = time.monotonic() + backoff
@@ -1836,6 +1967,12 @@ class GatewayRunner:
                                 platform.value, backoff,
                             )
                 except Exception as e:
+                    self._update_platform_runtime_status(
+                        platform.value,
+                        platform_state="retrying",
+                        error_code=None,
+                        error_message=str(e),
+                    )
                     backoff = min(30 * (2 ** (attempt - 1)), _BACKOFF_CAP)
                     info["attempts"] = attempt
                     info["next_retry"] = time.monotonic() + backoff
@@ -1942,6 +2079,15 @@ class GatewayRunner:
             from gateway.status import remove_pid_file
             remove_pid_file()
 
+            # Write a clean-shutdown marker so the next startup knows this
+            # wasn't a crash.  suspend_recently_active() only needs to run
+            # after unexpected exits — graceful shutdowns already drain
+            # active agents, so there's no stuck-session risk.
+            try:
+                (_hermes_home / ".clean_shutdown").touch()
+            except Exception:
+                pass
+
             if self._restart_requested and self._restart_via_service:
                 self._exit_code = GATEWAY_SERVICE_RESTART_EXIT_CODE
                 self._exit_reason = self._exit_reason or "Gateway restart requested"
@@ -2043,6 +2189,16 @@ class GatewayRunner:
                 return None
             return FeishuAdapter(config)
 
+        elif platform == Platform.WECOM_CALLBACK:
+            from gateway.platforms.wecom_callback import (
+                WecomCallbackAdapter,
+                check_wecom_callback_requirements,
+            )
+            if not check_wecom_callback_requirements():
+                logger.warning("WeComCallback: aiohttp/httpx not installed")
+                return None
+            return WecomCallbackAdapter(config)
+
         elif platform == Platform.WECOM:
             from gateway.platforms.wecom import WeComAdapter, check_wecom_requirements
             if not check_wecom_requirements():
@@ -2132,6 +2288,7 @@ class GatewayRunner:
             Platform.DINGTALK: "DINGTALK_ALLOWED_USERS",
             Platform.FEISHU: "FEISHU_ALLOWED_USERS",
             Platform.WECOM: "WECOM_ALLOWED_USERS",
+            Platform.WECOM_CALLBACK: "WECOM_CALLBACK_ALLOWED_USERS",
             Platform.WEIXIN: "WEIXIN_ALLOWED_USERS",
             Platform.BLUEBUBBLES: "BLUEBUBBLES_ALLOWED_USERS",
         }
@@ -2148,6 +2305,7 @@ class GatewayRunner:
             Platform.DINGTALK: "DINGTALK_ALLOW_ALL_USERS",
             Platform.FEISHU: "FEISHU_ALLOW_ALL_USERS",
             Platform.WECOM: "WECOM_ALLOW_ALL_USERS",
+            Platform.WECOM_CALLBACK: "WECOM_CALLBACK_ALLOW_ALL_USERS",
             Platform.WEIXIN: "WEIXIN_ALLOW_ALL_USERS",
             Platform.BLUEBUBBLES: "BLUEBUBBLES_ALLOW_ALL_USERS",
         }
@@ -3454,8 +3612,18 @@ class GatewayRunner:
             if agent_result.get("session_id") and agent_result["session_id"] != session_entry.session_id:
                 session_entry.session_id = agent_result["session_id"]
 
-            # Prepend reasoning/thinking if display is enabled
-            if getattr(self, "_show_reasoning", False) and response:
+            # Prepend reasoning/thinking if display is enabled (per-platform)
+            try:
+                from gateway.display_config import resolve_display_setting as _rds
+                _show_reasoning_effective = _rds(
+                    _load_gateway_config(),
+                    _platform_config_key(source.platform),
+                    "show_reasoning",
+                    getattr(self, "_show_reasoning", False),
+                )
+            except Exception:
+                _show_reasoning_effective = getattr(self, "_show_reasoning", False)
+            if _show_reasoning_effective and response:
                 last_reasoning = agent_result.get("last_reasoning")
                 if last_reasoning:
                     # Collapse long reasoning to keep messages readable
@@ -3860,9 +4028,16 @@ class GatewayRunner:
         except Exception:
             pass
 
+        # Append a random tip to the reset message
+        try:
+            from hermes_cli.tips import get_random_tip
+            _tip_line = f"\n✦ Tip: {get_random_tip()}"
+        except Exception:
+            _tip_line = ""
+
         if session_info:
-            return f"{header}\n\n{session_info}"
-        return header
+            return f"{header}\n\n{session_info}{_tip_line}"
+        return f"{header}{_tip_line}"
     
     async def _handle_profile_command(self, event: MessageEvent) -> str:
         """Handle /profile — show active profile name and home directory."""
@@ -4282,6 +4457,11 @@ class GatewayRunner:
                             "api_mode": result.api_mode,
                         }
 
+                        # Evict cached agent so the next turn creates a fresh
+                        # agent from the override rather than relying on the
+                        # stale cache signature to trigger a rebuild.
+                        _self._evict_cached_agent(_session_key)
+
                         # Build confirmation text
                         plabel = result.provider_label or result.target_provider
                         lines = [f"Model switched to `{result.new_model}`"]
@@ -4395,6 +4575,10 @@ class GatewayRunner:
             "api_mode": result.api_mode,
         }
 
+        # Evict cached agent so the next turn creates a fresh agent from the
+        # override rather than relying on cache signature mismatch detection.
+        self._evict_cached_agent(session_key)
+
         # Persist to config if --global
         if persist_global:
             try:
@@ -5531,16 +5715,20 @@ class GatewayRunner:
                 "_Usage:_ `/reasoning <none|minimal|low|medium|high|xhigh|show|hide>`"
             )
 
-        # Display toggle
+        # Display toggle (per-platform)
+        platform_key = _platform_config_key(event.source.platform)
         if args in ("show", "on"):
             self._show_reasoning = True
-            _save_config_key("display.show_reasoning", True)
-            return "🧠 ✓ Reasoning display: **ON**\nModel thinking will be shown before each response."
+            _save_config_key(f"display.platforms.{platform_key}.show_reasoning", True)
+            return (
+                "🧠 ✓ Reasoning display: **ON**\n"
+                f"Model thinking will be shown before each response on **{platform_key}**."
+            )
 
         if args in ("hide", "off"):
             self._show_reasoning = False
-            _save_config_key("display.show_reasoning", False)
-            return "🧠 ✓ Reasoning display: **OFF**"
+            _save_config_key(f"display.platforms.{platform_key}.show_reasoning", False)
+            return f"🧠 ✓ Reasoning display: **OFF** for **{platform_key}**"
 
         # Effort level change
         effort = args.strip()
@@ -5643,11 +5831,14 @@ class GatewayRunner:
 
         Gated by ``display.tool_progress_command`` in config.yaml (default off).
         When enabled, cycles the tool progress mode through off → new → all →
-        verbose → off, same as the CLI.
+        verbose → off for the *current platform*.  The setting is saved to
+        ``display.platforms.<platform>.tool_progress`` so each channel can
+        have its own verbosity level independently.
         """
         import yaml
 
         config_path = _hermes_home / "config.yaml"
+        platform_key = _platform_config_key(event.source.platform)
 
         # --- check config gate ------------------------------------------------
         try:
@@ -5666,7 +5857,7 @@ class GatewayRunner:
                 "display:\n  tool_progress_command: true\n```"
             )
 
-        # --- cycle mode -------------------------------------------------------
+        # --- cycle mode (per-platform) ----------------------------------------
         cycle = ["off", "new", "all", "verbose"]
         descriptions = {
             "off": "⚙️ Tool progress: **OFF** — no tool activity shown.",
@@ -5675,32 +5866,40 @@ class GatewayRunner:
             "verbose": "⚙️ Tool progress: **VERBOSE** — every tool call with full arguments.",
         }
 
-        raw_progress = user_config.get("display", {}).get("tool_progress", "all")
-        # YAML 1.1 parses bare "off" as boolean False — normalise back
-        if raw_progress is False:
-            current = "off"
-        elif raw_progress is True:
-            current = "all"
-        else:
-            current = str(raw_progress).lower()
+        # Read current effective mode for this platform via the resolver
+        from gateway.display_config import resolve_display_setting
+        current = resolve_display_setting(user_config, platform_key, "tool_progress", "all")
         if current not in cycle:
             current = "all"
         idx = (cycle.index(current) + 1) % len(cycle)
         new_mode = cycle[idx]
 
-        # Save to config.yaml
+        # Save to display.platforms.<platform>.tool_progress
         try:
             if "display" not in user_config or not isinstance(user_config.get("display"), dict):
                 user_config["display"] = {}
-            user_config["display"]["tool_progress"] = new_mode
+            display = user_config["display"]
+            if "platforms" not in display or not isinstance(display.get("platforms"), dict):
+                display["platforms"] = {}
+            if platform_key not in display["platforms"] or not isinstance(display["platforms"].get(platform_key), dict):
+                display["platforms"][platform_key] = {}
+            display["platforms"][platform_key]["tool_progress"] = new_mode
             atomic_yaml_write(config_path, user_config)
-            return f"{descriptions[new_mode]}\n_(saved to config — takes effect on next message)_"
+            return (
+                f"{descriptions[new_mode]}\n"
+                f"_(saved for **{platform_key}** — takes effect on next message)_"
+            )
         except Exception as e:
             logger.warning("Failed to save tool_progress mode: %s", e)
             return f"{descriptions[new_mode]}\n_(could not save to config: {e})_"
 
     async def _handle_compress_command(self, event: MessageEvent) -> str:
-        """Handle /compress command -- manually compress conversation context."""
+        """Handle /compress command -- manually compress conversation context.
+
+        Accepts an optional focus topic: ``/compress <focus>`` guides the
+        summariser to preserve information related to *focus* while being
+        more aggressive about discarding everything else.
+        """
         source = event.source
         session_entry = self.session_store.get_or_create_session(source)
         history = self.session_store.load_transcript(session_entry.session_id)
@@ -5708,6 +5907,9 @@ class GatewayRunner:
         if not history or len(history) < 4:
             return "Not enough conversation to compress (need at least 4 messages)."
 
+        # Extract optional focus topic from command args
+        focus_topic = (event.get_command_args() or "").strip() or None
+
         try:
             from run_agent import AIAgent
             from agent.manual_compression_feedback import summarize_manual_compression
@@ -5749,7 +5951,7 @@ class GatewayRunner:
             loop = asyncio.get_event_loop()
             compressed, _ = await loop.run_in_executor(
                 None,
-                lambda: tmp_agent._compress_context(msgs, "", approx_tokens=approx_tokens)
+                lambda: tmp_agent._compress_context(msgs, "", approx_tokens=approx_tokens, focus_topic=focus_topic)
             )
 
             # _compress_context already calls end_session() on the old session
@@ -5773,7 +5975,10 @@ class GatewayRunner:
                 approx_tokens,
                 new_tokens,
             )
-            lines = [f"🗜️ {summary['headline']}", summary["token_line"]]
+            lines = [f"🗜️ {summary['headline']}"]
+            if focus_topic:
+                lines.append(f"Focus: \"{focus_topic}\"")
+            lines.append(summary["token_line"])
             if summary["note"]:
                 lines.append(summary["note"])
             return "\n".join(lines)
@@ -6315,7 +6520,7 @@ class GatewayRunner:
         Platform.TELEGRAM, Platform.DISCORD, Platform.SLACK, Platform.WHATSAPP,
         Platform.SIGNAL, Platform.MATTERMOST, Platform.MATRIX,
         Platform.HOMEASSISTANT, Platform.EMAIL, Platform.SMS, Platform.DINGTALK,
-        Platform.FEISHU, Platform.WECOM, Platform.WEIXIN, Platform.BLUEBUBBLES, Platform.LOCAL,
+        Platform.FEISHU, Platform.WECOM, Platform.WECOM_CALLBACK, Platform.WEIXIN, Platform.BLUEBUBBLES, Platform.LOCAL,
     })
 
     async def _handle_update_command(self, event: MessageEvent) -> str:
@@ -6560,8 +6765,12 @@ class GatewayRunner:
             if buffer.strip() and (loop.time() - last_stream_time) >= stream_interval:
                 await _flush_buffer()
 
-            # Check for prompts
-            if prompt_path.exists() and session_key:
+            # Check for prompts — only forward if we haven't already sent
+            # one that's still awaiting a response.  Without this guard the
+            # watcher would re-read the same .update_prompt.json every poll
+            # cycle and spam the user with duplicate prompt messages.
+            if (prompt_path.exists() and session_key
+                    and not self._update_prompt_pending.get(session_key)):
                 try:
                     prompt_data = json.loads(prompt_path.read_text())
                     prompt_text = prompt_data.get("prompt", "")
@@ -6593,6 +6802,11 @@ class GatewayRunner:
                                 f"or type your answer directly."
                             )
                         self._update_prompt_pending[session_key] = True
+                        # Remove the prompt file so it isn't re-read on the
+                        # next poll cycle.  The update process only needs
+                        # .update_response to continue — it doesn't re-check
+                        # .update_prompt.json while waiting.
+                        prompt_path.unlink(missing_ok=True)
                         logger.info("Forwarded update prompt to %s: %s", session_key, prompt_text[:80])
                 except (json.JSONDecodeError, OSError) as e:
                     logger.debug("Failed to read update prompt: %s", e)
@@ -6720,6 +6934,7 @@ class GatewayRunner:
             thread_id=str(context.source.thread_id) if context.source.thread_id else "",
             user_id=str(context.source.user_id) if context.source.user_id else "",
             user_name=str(context.source.user_name) if context.source.user_name else "",
+            session_key=context.session_key,
         )
 
     def _clear_session_env(self, tokens: list) -> None:
@@ -6965,7 +7180,9 @@ class GatewayRunner:
 
             if session.exited:
                 # --- Agent-triggered completion: inject synthetic message ---
-                if agent_notify:
+                # Skip if the agent already consumed the result via wait/poll/log
+                from tools.process_registry import process_registry as _pr_check
+                if agent_notify and not _pr_check.is_completion_consumed(session_id):
                     from tools.ansi_strip import strip_ansi
                     _out = strip_ansi(session.output_buffer[-2000:]) if session.output_buffer else ""
                     synth_text = (
@@ -7161,31 +7378,27 @@ class GatewayRunner:
         from hermes_cli.tools_config import _get_platform_tools
         enabled_toolsets = sorted(_get_platform_tools(user_config, platform_key))
 
+        display_config = user_config.get("display", {})
+        if not isinstance(display_config, dict):
+            display_config = {}
+
+        # Per-platform display settings — resolve via display_config module
+        # which checks display.platforms.<platform>.<key> first, then
+        # display.<key> global, then built-in platform defaults.
+        from gateway.display_config import resolve_display_setting
+
         # Apply tool preview length config (0 = no limit)
         try:
             from agent.display import set_tool_preview_max_len
-            _tpl = user_config.get("display", {}).get("tool_preview_length", 0)
+            _tpl = resolve_display_setting(user_config, platform_key, "tool_preview_length", 0)
             set_tool_preview_max_len(int(_tpl) if _tpl else 0)
         except Exception:
             pass
 
-        # Tool progress mode from config.yaml: "all", "new", "verbose", "off"
-        # Falls back to env vars for backward compatibility.
-        # YAML 1.1 parses bare `off` as boolean False — normalise before
-        # the `or` chain so it doesn't silently fall through to "all".
-        #
-        # Per-platform overrides (display.tool_progress_overrides) take
-        # priority over the global setting — e.g. Signal users can set
-        # tool_progress to "off" while keeping Telegram on "all".
-        _display_cfg = user_config.get("display", {})
-        _overrides = _display_cfg.get("tool_progress_overrides", {})
-        _raw_tp = _overrides.get(platform_key)
-        if _raw_tp is None:
-            _raw_tp = _display_cfg.get("tool_progress")
-        if _raw_tp is False:
-            _raw_tp = "off"
+        # Tool progress mode — resolved per-platform with env var fallback
+        _resolved_tp = resolve_display_setting(user_config, platform_key, "tool_progress")
         progress_mode = (
-            _raw_tp
+            _resolved_tp
             or os.getenv("HERMES_TOOL_PROGRESS_MODE")
             or "all"
         )
@@ -7193,6 +7406,16 @@ class GatewayRunner:
         # so each progress line would be sent as a separate message.
         from gateway.config import Platform
         tool_progress_enabled = progress_mode != "off" and source.platform != Platform.WEBHOOK
+        # Natural assistant status messages are intentionally independent from
+        # tool progress and token streaming. Users can keep tool_progress quiet
+        # in chat platforms while opting into concise mid-turn updates.
+        interim_assistant_messages_enabled = (
+            source.platform != Platform.WEBHOOK
+            and is_truthy_value(
+                display_config.get("interim_assistant_messages"),
+                default=True,
+            )
+        )
         
         # Queue for progress messages (thread-safe)
         progress_queue = queue.Queue() if tool_progress_enabled else None
@@ -7462,8 +7685,8 @@ class GatewayRunner:
             # `_resolve_turn_agent_config(message, …)`.
             nonlocal message
 
-            # Pass session_key to process registry via env var so background
-            # processes can be mapped back to this gateway session
+            # session_key is now set via contextvars in _set_session_env()
+            # (concurrency-safe). Keep os.environ as fallback for CLI/cron.
             os.environ["HERMES_SESSION_KEY"] = session_key or ""
 
             # Read from env var or use default (same as CLI)
@@ -7493,6 +7716,10 @@ class GatewayRunner:
                     session_key=session_key,
                     user_config=user_config,
                 )
+                logger.debug(
+                    "run_agent resolved: model=%s provider=%s session=%s",
+                    model, runtime_kwargs.get("provider"), (session_key or "")[:30],
+                )
             except Exception as exc:
                 return {
                     "final_response": f"⚠️ Provider authentication failed: {exc}",
@@ -7505,7 +7732,7 @@ class GatewayRunner:
             reasoning_config = self._load_reasoning_config()
             self._reasoning_config = reasoning_config
             self._service_tier = self._load_service_tier()
-            # Set up streaming consumer if enabled
+            # Set up stream consumer for token streaming or interim commentary.
             _stream_consumer = None
             _stream_delta_cb = None
             _scfg = getattr(getattr(self, 'config', None), 'streaming', None)
@@ -7513,7 +7740,22 @@ class GatewayRunner:
                 from gateway.config import StreamingConfig
                 _scfg = StreamingConfig()
 
-            if _scfg.enabled and _scfg.transport != "off":
+            # Per-platform streaming gate: display.platforms.<plat>.streaming
+            # can disable streaming for specific platforms even when the global
+            # streaming config is enabled.
+            _plat_streaming = resolve_display_setting(
+                user_config, platform_key, "streaming"
+            )
+            # None = no per-platform override → follow global config
+            _streaming_enabled = (
+                _scfg.enabled and _scfg.transport != "off"
+                if _plat_streaming is None
+                else bool(_plat_streaming)
+            )
+            _want_stream_deltas = _streaming_enabled
+            _want_interim_messages = interim_assistant_messages_enabled
+            _want_interim_consumer = _want_interim_messages
+            if _want_stream_deltas or _want_interim_consumer:
                 try:
                     from gateway.stream_consumer import GatewayStreamConsumer, StreamConsumerConfig
                     _adapter = self.adapters.get(source.platform)
@@ -7529,11 +7771,33 @@ class GatewayRunner:
                             config=_consumer_cfg,
                             metadata={"thread_id": _progress_thread_id} if _progress_thread_id else None,
                         )
-                        _stream_delta_cb = _stream_consumer.on_delta
+                        if _want_stream_deltas:
+                            _stream_delta_cb = _stream_consumer.on_delta
                         stream_consumer_holder[0] = _stream_consumer
                 except Exception as _sc_err:
                     logger.debug("Could not set up stream consumer: %s", _sc_err)
 
+            def _interim_assistant_cb(text: str, *, already_streamed: bool = False) -> None:
+                if _stream_consumer is not None:
+                    if already_streamed:
+                        _stream_consumer.on_segment_break()
+                    else:
+                        _stream_consumer.on_commentary(text)
+                    return
+                if already_streamed or not _status_adapter or not str(text or "").strip():
+                    return
+                try:
+                    asyncio.run_coroutine_threadsafe(
+                        _status_adapter.send(
+                            _status_chat_id,
+                            text,
+                            metadata=_status_thread_metadata,
+                        ),
+                        _loop_for_step,
+                    )
+                except Exception as _e:
+                    logger.debug("interim_assistant_callback error: %s", _e)
+
             turn_route = self._resolve_turn_agent_config(message, model, runtime_kwargs)
 
             # Check agent cache — reuse the AIAgent from the previous message
@@ -7591,6 +7855,7 @@ class GatewayRunner:
             agent.tool_progress_callback = progress_callback if tool_progress_enabled else None
             agent.step_callback = _step_callback_sync if _hooks_ref.loaded_hooks else None
             agent.stream_delta_callback = _stream_delta_cb
+            agent.interim_assistant_callback = _interim_assistant_cb if _want_interim_messages else None
             agent.status_callback = _status_callback_sync
             agent.reasoning_config = reasoning_config
             agent.service_tier = self._service_tier
@@ -7894,6 +8159,7 @@ class GatewayRunner:
                 "output_tokens": _output_toks,
                 "model": _resolved_model,
                 "session_id": effective_session_id,
+                "response_previewed": result.get("response_previewed", False),
             }
         
         # Start progress message sender if enabled
@@ -7928,26 +8194,51 @@ class GatewayRunner:
         
         tracking_task = asyncio.create_task(track_agent())
         
-        # Monitor for interrupts from the adapter (new messages arriving)
+        # Monitor for interrupts from the adapter (new messages arriving).
+        # This is the PRIMARY interrupt path for regular text messages —
+        # Level 1 (base.py) catches them before _handle_message() is reached,
+        # so the Level 2 running_agent.interrupt() path never fires.
+        # The inactivity poll loop below has a BACKUP check in case this
+        # task dies (no error handling = silent death = lost interrupts).
+        _interrupt_detected = asyncio.Event()  # shared with backup check
+
         async def monitor_for_interrupt():
-            adapter = self.adapters.get(source.platform)
-            if not adapter or not session_key:
+            if not session_key:
                 return
-            
+
             while True:
                 await asyncio.sleep(0.2)  # Check every 200ms
-                # Check if adapter has a pending interrupt for this session.
-                # Must use session_key (build_session_key output) — NOT
-                # source.chat_id — because the adapter stores interrupt events
-                # under the full session key.
-                if hasattr(adapter, 'has_pending_interrupt') and adapter.has_pending_interrupt(session_key):
-                    agent = agent_holder[0]
-                    if agent:
-                        pending_event = adapter.get_pending_message(session_key)
-                        pending_text = pending_event.text if pending_event else None
-                        logger.debug("Interrupt detected from adapter, signaling agent...")
-                        agent.interrupt(pending_text)
-                        break
+                try:
+                    # Re-resolve adapter each iteration so reconnects don't
+                    # leave us holding a stale reference.
+                    _adapter = self.adapters.get(source.platform)
+                    if not _adapter:
+                        continue
+                    # Check if adapter has a pending interrupt for this session.
+                    # Must use session_key (build_session_key output) — NOT
+                    # source.chat_id — because the adapter stores interrupt events
+                    # under the full session key.
+                    if hasattr(_adapter, 'has_pending_interrupt') and _adapter.has_pending_interrupt(session_key):
+                        agent = agent_holder[0]
+                        if agent:
+                            # Peek at the pending message text WITHOUT consuming it.
+                            # The message must remain in _pending_messages so the
+                            # post-run dequeue at _dequeue_pending_event() can
+                            # retrieve the full MessageEvent (with media metadata).
+                            # If we pop here, a race exists: the agent may finish
+                            # before checking _interrupt_requested, and the message
+                            # is lost — neither the interrupt path nor the dequeue
+                            # path finds it.
+                            _peek_event = _adapter._pending_messages.get(session_key)
+                            pending_text = _peek_event.text if _peek_event else None
+                            logger.debug("Interrupt detected from adapter, signaling agent...")
+                            agent.interrupt(pending_text)
+                            _interrupt_detected.set()
+                            break
+                except asyncio.CancelledError:
+                    raise
+                except Exception as _mon_err:
+                    logger.debug("monitor_for_interrupt error (will retry): %s", _mon_err)
         
         interrupt_monitor = asyncio.create_task(monitor_for_interrupt())
 
@@ -8012,8 +8303,34 @@ class GatewayRunner:
             _POLL_INTERVAL = 5.0
 
             if _agent_timeout is None:
-                # Unlimited — just await the result.
-                response = await _executor_task
+                # Unlimited — still poll periodically for backup interrupt
+                # detection in case monitor_for_interrupt() silently died.
+                response = None
+                while True:
+                    done, _ = await asyncio.wait(
+                        {_executor_task}, timeout=_POLL_INTERVAL
+                    )
+                    if done:
+                        response = _executor_task.result()
+                        break
+                    # Backup interrupt check: if the monitor task died or
+                    # missed the interrupt, catch it here.
+                    if not _interrupt_detected.is_set() and session_key:
+                        _backup_adapter = self.adapters.get(source.platform)
+                        _backup_agent = agent_holder[0]
+                        if (_backup_adapter and _backup_agent
+                                and hasattr(_backup_adapter, 'has_pending_interrupt')
+                                and _backup_adapter.has_pending_interrupt(session_key)):
+                            _bp_event = _backup_adapter._pending_messages.get(session_key)
+                            _bp_text = _bp_event.text if _bp_event else None
+                            logger.info(
+                                "Backup interrupt detected for session %s "
+                                "(monitor task state: %s)",
+                                session_key[:20],
+                                "done" if interrupt_monitor.done() else "running",
+                            )
+                            _backup_agent.interrupt(_bp_text)
+                            _interrupt_detected.set()
             else:
                 # Poll loop: check the agent's built-in activity tracker
                 # (updated by _touch_activity() on every tool call, API
@@ -8057,6 +8374,23 @@ class GatewayRunner:
                     if _idle_secs >= _agent_timeout:
                         _inactivity_timeout = True
                         break
+                    # Backup interrupt check (same as unlimited path).
+                    if not _interrupt_detected.is_set() and session_key:
+                        _backup_adapter = self.adapters.get(source.platform)
+                        _backup_agent = agent_holder[0]
+                        if (_backup_adapter and _backup_agent
+                                and hasattr(_backup_adapter, 'has_pending_interrupt')
+                                and _backup_adapter.has_pending_interrupt(session_key)):
+                            _bp_event = _backup_adapter._pending_messages.get(session_key)
+                            _bp_text = _bp_event.text if _bp_event else None
+                            logger.info(
+                                "Backup interrupt detected for session %s "
+                                "(monitor task state: %s)",
+                                session_key[:20],
+                                "done" if interrupt_monitor.done() else "running",
+                            )
+                            _backup_agent.interrupt(_bp_text)
+                            _interrupt_detected.set()
 
             if _inactivity_timeout:
                 # Build a diagnostic summary from the agent's activity tracker.
@@ -8216,12 +8550,36 @@ class GatewayRunner:
                     # response before processing the queued follow-up.
                     # Skip if streaming already delivered it.
                     _sc = stream_consumer_holder[0]
-                    _already_streamed = _sc and getattr(_sc, "already_sent", False)
+                    if _sc and stream_task:
+                        try:
+                            await asyncio.wait_for(stream_task, timeout=5.0)
+                        except (asyncio.TimeoutError, asyncio.CancelledError):
+                            stream_task.cancel()
+                            try:
+                                await stream_task
+                            except asyncio.CancelledError:
+                                pass
+                        except Exception as e:
+                            logger.debug("Stream consumer wait before queued message failed: %s", e)
+                    _response_previewed = bool(result.get("response_previewed"))
+                    _already_streamed = bool(
+                        _sc
+                        and (
+                            getattr(_sc, "final_response_sent", False)
+                            or (
+                                _response_previewed
+                                and getattr(_sc, "already_sent", False)
+                            )
+                        )
+                    )
                     first_response = result.get("final_response", "")
                     if first_response and not _already_streamed:
                         try:
-                            await adapter.send(source.chat_id, first_response,
-                                               metadata={"thread_id": source.thread_id} if source.thread_id else None)
+                            await adapter.send(
+                                source.chat_id,
+                                first_response,
+                                metadata=_status_thread_metadata,
+                            )
                         except Exception as e:
                             logger.warning("Failed to send first response before queued message: %s", e)
                 # else: interrupted — discard the interrupted response ("Operation
@@ -8294,8 +8652,15 @@ class GatewayRunner:
         # message is new content the user hasn't seen, and it must reach
         # them even if streaming had sent earlier partial output.
         _sc = stream_consumer_holder[0]
-        if _sc and _sc.already_sent and isinstance(response, dict):
-            if not response.get("failed"):
+        if _sc and isinstance(response, dict) and not response.get("failed"):
+            _response_previewed = bool(response.get("response_previewed"))
+            if (
+                getattr(_sc, "final_response_sent", False)
+                or (
+                    _response_previewed
+                    and getattr(_sc, "already_sent", False)
+                )
+            ):
                 response["already_sent"] = True
         
         return response
@@ -8444,23 +8809,11 @@ async def start_gateway(config: Optional[GatewayConfig] = None, replace: bool =
     except Exception:
         pass
 
-    # Centralized logging — agent.log (INFO+) and errors.log (WARNING+).
+    # Centralized logging — agent.log (INFO+), errors.log (WARNING+),
+    # and gateway.log (INFO+, gateway-component records only).
     # Idempotent, so repeated calls from AIAgent.__init__ won't duplicate.
     from hermes_logging import setup_logging
-    log_dir = setup_logging(hermes_home=_hermes_home, mode="gateway")
-
-    # Gateway-specific rotating log — captures all gateway-level messages
-    # (session management, platform adapters, slash commands, etc.).
-    from agent.redact import RedactingFormatter
-    from hermes_logging import _add_rotating_handler
-    _add_rotating_handler(
-        logging.getLogger(),
-        log_dir / 'gateway.log',
-        level=logging.INFO,
-        max_bytes=5 * 1024 * 1024,
-        backup_count=3,
-        formatter=RedactingFormatter('%(asctime)s %(levelname)s %(name)s: %(message)s'),
-    )
+    setup_logging(hermes_home=_hermes_home, mode="gateway")
 
     # Optional stderr handler — level driven by -v/-q flags on the CLI.
     # verbosity=None (-q/--quiet): no stderr output
@@ -8468,6 +8821,8 @@ async def start_gateway(config: Optional[GatewayConfig] = None, replace: bool =
     # verbosity=1    (-v):         INFO and above
     # verbosity=2+   (-vv/-vvv):   DEBUG
     if verbosity is not None:
+        from agent.redact import RedactingFormatter
+
         _stderr_level = {0: logging.WARNING, 1: logging.INFO}.get(verbosity, logging.DEBUG)
         _stderr_handler = logging.StreamHandler()
         _stderr_handler.setLevel(_stderr_level)

gateway/session.py

@@ -807,9 +807,9 @@ class SessionStore:
         to avoid resetting long-idle sessions that are harmless to resume.
         Returns the number of sessions that were suspended.
         """
-        import time as _time
+        from datetime import timedelta
 
-        cutoff = _time.time() - max_age_seconds
+        cutoff = _now() - timedelta(seconds=max_age_seconds)
         count = 0
         with self._lock:
             self._ensure_loaded_locked()

gateway/session_context.py

@@ -48,6 +48,7 @@ _SESSION_CHAT_NAME: ContextVar[str] = ContextVar("HERMES_SESSION_CHAT_NAME", def
 _SESSION_THREAD_ID: ContextVar[str] = ContextVar("HERMES_SESSION_THREAD_ID", default="")
 _SESSION_USER_ID: ContextVar[str] = ContextVar("HERMES_SESSION_USER_ID", default="")
 _SESSION_USER_NAME: ContextVar[str] = ContextVar("HERMES_SESSION_USER_NAME", default="")
+_SESSION_KEY: ContextVar[str] = ContextVar("HERMES_SESSION_KEY", default="")
 
 _VAR_MAP = {
     "HERMES_SESSION_PLATFORM": _SESSION_PLATFORM,
@@ -56,6 +57,7 @@ _VAR_MAP = {
     "HERMES_SESSION_THREAD_ID": _SESSION_THREAD_ID,
     "HERMES_SESSION_USER_ID": _SESSION_USER_ID,
     "HERMES_SESSION_USER_NAME": _SESSION_USER_NAME,
+    "HERMES_SESSION_KEY": _SESSION_KEY,
 }
 
 
@@ -66,6 +68,7 @@ def set_session_vars(
     thread_id: str = "",
     user_id: str = "",
     user_name: str = "",
+    session_key: str = "",
 ) -> list:
     """Set all session context variables and return reset tokens.
 
@@ -82,6 +85,7 @@ def set_session_vars(
         _SESSION_THREAD_ID.set(thread_id),
         _SESSION_USER_ID.set(user_id),
         _SESSION_USER_NAME.set(user_name),
+        _SESSION_KEY.set(session_key),
     ]
     return tokens
 
@@ -97,6 +101,7 @@ def clear_session_vars(tokens: list) -> None:
         _SESSION_THREAD_ID,
         _SESSION_USER_ID,
         _SESSION_USER_NAME,
+        _SESSION_KEY,
     ]
     for var, token in zip(vars_in_order, tokens):
         var.reset(token)

gateway/status.py

@@ -26,6 +26,7 @@ _GATEWAY_KIND = "hermes-gateway"
 _RUNTIME_STATUS_FILE = "gateway_state.json"
 _LOCKS_DIRNAME = "gateway-locks"
 _IS_WINDOWS = sys.platform == "win32"
+_UNSET = object()
 
 
 def _get_pid_path() -> Path:
@@ -218,14 +219,14 @@ def write_pid_file() -> None:
 
 def write_runtime_status(
     *,
-    gateway_state: Optional[str] = None,
-    exit_reason: Optional[str] = None,
-    restart_requested: Optional[bool] = None,
-    active_agents: Optional[int] = None,
-    platform: Optional[str] = None,
-    platform_state: Optional[str] = None,
-    error_code: Optional[str] = None,
-    error_message: Optional[str] = None,
+    gateway_state: Any = _UNSET,
+    exit_reason: Any = _UNSET,
+    restart_requested: Any = _UNSET,
+    active_agents: Any = _UNSET,
+    platform: Any = _UNSET,
+    platform_state: Any = _UNSET,
+    error_code: Any = _UNSET,
+    error_message: Any = _UNSET,
 ) -> None:
     """Persist gateway runtime health information for diagnostics/status."""
     path = _get_runtime_status_path()
@@ -236,22 +237,22 @@ def write_runtime_status(
     payload["start_time"] = _get_process_start_time(os.getpid())
     payload["updated_at"] = _utc_now_iso()
 
-    if gateway_state is not None:
+    if gateway_state is not _UNSET:
         payload["gateway_state"] = gateway_state
-    if exit_reason is not None:
+    if exit_reason is not _UNSET:
         payload["exit_reason"] = exit_reason
-    if restart_requested is not None:
+    if restart_requested is not _UNSET:
         payload["restart_requested"] = bool(restart_requested)
-    if active_agents is not None:
+    if active_agents is not _UNSET:
         payload["active_agents"] = max(0, int(active_agents))
 
-    if platform is not None:
+    if platform is not _UNSET:
         platform_payload = payload["platforms"].get(platform, {})
-        if platform_state is not None:
+        if platform_state is not _UNSET:
             platform_payload["state"] = platform_state
-        if error_code is not None:
+        if error_code is not _UNSET:
             platform_payload["error_code"] = error_code
-        if error_message is not None:
+        if error_message is not _UNSET:
             platform_payload["error_message"] = error_message
         platform_payload["updated_at"] = _utc_now_iso()
         payload["platforms"][platform] = platform_payload

gateway/stream_consumer.py

@@ -32,6 +32,10 @@ _DONE = object()
 # new one so that subsequent text appears below tool progress messages.
 _NEW_SEGMENT = object()
 
+# Queue marker for a completed assistant commentary message emitted between
+# API/tool iterations (for example: "I'll inspect the repo first.").
+_COMMENTARY = object()
+
 
 @dataclass
 class StreamConsumerConfig:
@@ -75,20 +79,43 @@ class GatewayStreamConsumer:
         self._accumulated = ""
         self._message_id: Optional[str] = None
         self._already_sent = False
-        self._edit_supported = True  # Disabled on first edit failure (Signal/Email/HA)
+        self._edit_supported = True  # Disabled when progressive edits are no longer usable
         self._last_edit_time = 0.0
         self._last_sent_text = ""   # Track last-sent text to skip redundant edits
         self._fallback_final_send = False
         self._fallback_prefix = ""
         self._flood_strikes = 0         # Consecutive flood-control edit failures
         self._current_edit_interval = self.cfg.edit_interval  # Adaptive backoff
+        self._final_response_sent = False
 
     @property
     def already_sent(self) -> bool:
-        """True if at least one message was sent/edited — signals the base
-        adapter to skip re-sending the final response."""
+        """True if at least one message was sent or edited during the run."""
         return self._already_sent
 
+    @property
+    def final_response_sent(self) -> bool:
+        """True when the stream consumer delivered the final assistant reply."""
+        return self._final_response_sent
+
+    def on_segment_break(self) -> None:
+        """Finalize the current stream segment and start a fresh message."""
+        self._queue.put(_NEW_SEGMENT)
+
+    def on_commentary(self, text: str) -> None:
+        """Queue a completed interim assistant commentary message."""
+        if text:
+            self._queue.put((_COMMENTARY, text))
+
+    def _reset_segment_state(self, *, preserve_no_edit: bool = False) -> None:
+        if preserve_no_edit and self._message_id == "__no_edit__":
+            return
+        self._message_id = None
+        self._accumulated = ""
+        self._last_sent_text = ""
+        self._fallback_final_send = False
+        self._fallback_prefix = ""
+
     def on_delta(self, text: str) -> None:
         """Thread-safe callback — called from the agent's worker thread.
 
@@ -99,7 +126,7 @@ class GatewayStreamConsumer:
         if text:
             self._queue.put(text)
         elif text is None:
-            self._queue.put(_NEW_SEGMENT)
+            self.on_segment_break()
 
     def finish(self) -> None:
         """Signal that the stream is complete."""
@@ -116,6 +143,7 @@ class GatewayStreamConsumer:
                 # Drain all available items from the queue
                 got_done = False
                 got_segment_break = False
+                commentary_text = None
                 while True:
                     try:
                         item = self._queue.get_nowait()
@@ -125,6 +153,9 @@ class GatewayStreamConsumer:
                         if item is _NEW_SEGMENT:
                             got_segment_break = True
                             break
+                        if isinstance(item, tuple) and len(item) == 2 and item[0] is _COMMENTARY:
+                            commentary_text = item[1]
+                            break
                         self._accumulated += item
                     except queue.Empty:
                         break
@@ -135,11 +166,13 @@ class GatewayStreamConsumer:
                 should_edit = (
                     got_done
                     or got_segment_break
+                    or commentary_text is not None
                     or (elapsed >= self._current_edit_interval
                         and self._accumulated)
                     or len(self._accumulated) >= self.cfg.buffer_threshold
                 )
 
+                current_update_visible = False
                 if should_edit and self._accumulated:
                     # Split overflow: if accumulated text exceeds the platform
                     # limit, split into properly sized chunks.
@@ -161,6 +194,7 @@ class GatewayStreamConsumer:
                         self._last_sent_text = ""
                         self._last_edit_time = time.monotonic()
                         if got_done:
+                            self._final_response_sent = self._already_sent
                             return
                         if got_segment_break:
                             self._message_id = None
@@ -192,10 +226,10 @@ class GatewayStreamConsumer:
                         self._last_sent_text = ""
 
                     display_text = self._accumulated
-                    if not got_done and not got_segment_break:
+                    if not got_done and not got_segment_break and commentary_text is None:
                         display_text += self.cfg.cursor
 
-                    await self._send_or_edit(display_text)
+                    current_update_visible = await self._send_or_edit(display_text)
                     self._last_edit_time = time.monotonic()
 
                 if got_done:
@@ -206,12 +240,20 @@ class GatewayStreamConsumer:
                     if self._accumulated:
                         if self._fallback_final_send:
                             await self._send_fallback_final(self._accumulated)
+                        elif current_update_visible:
+                            self._final_response_sent = True
                         elif self._message_id:
-                            await self._send_or_edit(self._accumulated)
+                            self._final_response_sent = await self._send_or_edit(self._accumulated)
                         elif not self._already_sent:
-                            await self._send_or_edit(self._accumulated)
+                            self._final_response_sent = await self._send_or_edit(self._accumulated)
                     return
 
+                if commentary_text is not None:
+                    self._reset_segment_state()
+                    await self._send_commentary(commentary_text)
+                    self._last_edit_time = time.monotonic()
+                    self._reset_segment_state()
+
                 # Tool boundary: reset message state so the next text chunk
                 # creates a fresh message below any tool-progress messages.
                 #
@@ -220,17 +262,14 @@ class GatewayStreamConsumer:
                 # github_comment delivery).  Resetting to None would re-enter
                 # the "first send" path on every tool boundary and post one
                 # platform message per tool call — that is what caused 155
-                # comments under a single PR.  Instead, keep all state so the
-                # full continuation is delivered once via _send_fallback_final.
+                # comments under a single PR.  Instead, preserve the sentinel
+                # so the full continuation is delivered once via
+                # _send_fallback_final.
                 # (When editing fails mid-stream due to flood control the id is
                 # a real string like "msg_1", not "__no_edit__", so that case
                 # still resets and creates a fresh segment as intended.)
-                if got_segment_break and self._message_id != "__no_edit__":
-                    self._message_id = None
-                    self._accumulated = ""
-                    self._last_sent_text = ""
-                    self._fallback_final_send = False
-                    self._fallback_prefix = ""
+                if got_segment_break:
+                    self._reset_segment_state(preserve_no_edit=True)
 
                 await asyncio.sleep(0.05)  # Small yield to not busy-loop
 
@@ -339,6 +378,7 @@ class GatewayStreamConsumer:
         if not continuation.strip():
             # Nothing new to send — the visible partial already matches final text.
             self._already_sent = True
+            self._final_response_sent = True
             return
 
         raw_limit = getattr(self.adapter, "MAX_MESSAGE_LENGTH", 4096)
@@ -373,6 +413,7 @@ class GatewayStreamConsumer:
                     # the base gateway final-send path so we don't resend the
                     # full response and create another duplicate.
                     self._already_sent = True
+                    self._final_response_sent = True
                     self._message_id = last_message_id
                     self._last_sent_text = last_successful_chunk
                     self._fallback_prefix = ""
@@ -390,6 +431,7 @@ class GatewayStreamConsumer:
 
         self._message_id = last_message_id
         self._already_sent = True
+        self._final_response_sent = True
         self._last_sent_text = chunks[-1]
         self._fallback_prefix = ""
 
@@ -420,6 +462,24 @@ class GatewayStreamConsumer:
         except Exception:
             pass  # best-effort — don't let this block the fallback path
 
+    async def _send_commentary(self, text: str) -> bool:
+        """Send a completed interim assistant commentary message."""
+        text = self._clean_for_display(text)
+        if not text.strip():
+            return False
+        try:
+            result = await self.adapter.send(
+                chat_id=self.chat_id,
+                content=text,
+                metadata=self.metadata,
+            )
+            if result.success:
+                self._already_sent = True
+                return True
+        except Exception as e:
+            logger.error("Commentary send error: %s", e)
+        return False
+
     async def _send_or_edit(self, text: str) -> bool:
         """Send or edit the streaming message.
 
@@ -501,23 +561,21 @@ class GatewayStreamConsumer:
                     content=text,
                     metadata=self.metadata,
                 )
-                if result.success and result.message_id:
-                    self._message_id = result.message_id
+                if result.success:
+                    if result.message_id:
+                        self._message_id = result.message_id
+                    else:
+                        self._edit_supported = False
                     self._already_sent = True
                     self._last_sent_text = text
+                    if not result.message_id:
+                        self._fallback_prefix = self._visible_prefix()
+                        self._fallback_final_send = True
+                        # Sentinel prevents re-entering the first-send path on
+                        # every delta/tool boundary when platforms accept a
+                        # message but do not return an editable message id.
+                        self._message_id = "__no_edit__"
                     return True
-                elif result.success:
-                    # Platform accepted the message but returned no message_id
-                    # (e.g. Signal).  Can't edit without an ID — switch to
-                    # fallback mode: suppress intermediate deltas, send only
-                    # the missing tail once the final response is ready.
-                    self._already_sent = True
-                    self._edit_supported = False
-                    self._fallback_prefix = self._clean_for_display(text)
-                    self._fallback_final_send = True
-                    # Sentinel prevents re-entering this branch on every delta
-                    self._message_id = "__no_edit__"
-                    return True  # platform accepted, just can't edit
                 else:
                     # Initial send failed — disable streaming for this session
                     self._edit_supported = False