fix(gateway): keep Telegram heartbeat + interim commentary on; edit heartbeat in place (#33187)

#33151 flipped THREE Telegram display defaults to false:
  - tool_progress: new -> off            (kept: per-tool stream is too chatty)
  - interim_assistant_messages: T -> F   (REVERTED here)
  - long_running_notifications: T -> F   (REVERTED here)
  - busy_ack_detail: T -> F              (kept: verbose iteration counter)

The two reverts were wrong. interim_assistant_messages = the model's REAL
words mid-turn ("I'll inspect the repo first.", "Let me check both files
in parallel"). That is signal, not noise. Suppressing it left Telegram
users staring at "typing..." for the entire turn duration with no
feedback. long_running_notifications = the periodic heartbeat. Silent
agent for 30 minutes is worse than one bubble updating every 3 minutes.

Changes:
  - gateway/display_config.py: Telegram tier-1 inbox keeps both defaults
    on (only tool_progress and busy_ack_detail stay off).
  - gateway/run.py _notify_long_running(): edit a single heartbeat
    message in place (where the adapter supports it) instead of posting
    a new "Still working..." bubble each interval. Telegram, Discord,
    Slack, Matrix all qualify. Falls back to send-new when edit fails.
  - gateway/run.py: tighten heartbeat text. "⏳ Still working... (12 min
    elapsed — iteration 21/60, running: terminal)" -> "⏳ Working — 12
    min, terminal". Verbose iteration detail moves behind busy_ack_detail
    (one knob now controls both busy acks AND heartbeat verbosity).
  - tests/, cli-config.yaml.example, website/docs/user-guide/messaging:
    updated to reflect the corrected story.

tests/gateway/test_display_config.py

@@ -228,34 +228,44 @@ class TestPlatformDefaults:
 
         assert resolve_display_setting({}, "telegram", "streaming") is None
 
-    def test_telegram_mobile_chatter_defaults_off(self):
-        """Telegram suppresses operational chat noise unless opted in."""
+    def test_telegram_mobile_chatter_defaults(self):
+        """Telegram keeps real mid-turn signal (interim commentary + heartbeats)
+        but skips the verbose busy-ack iteration counter by default."""
         from gateway.display_config import resolve_display_setting
 
-        assert resolve_display_setting({}, "telegram", "interim_assistant_messages") is False
-        assert resolve_display_setting({}, "telegram", "long_running_notifications") is False
+        # Real model voice — keep on. Without this, Telegram users see
+        # "typing..." for the entire turn duration with no feedback.
+        assert resolve_display_setting({}, "telegram", "interim_assistant_messages") is True
+        # Periodic "Working — N min" heartbeat — keep on. Otherwise long
+        # turns appear completely silent.
+        assert resolve_display_setting({}, "telegram", "long_running_notifications") is True
+        # Verbose iteration counter in busy-ack and heartbeat — off by
+        # default on Telegram (mobile chat is cramped enough without
+        # "iteration 21/60" debug detail).
         assert resolve_display_setting({}, "telegram", "busy_ack_detail") is False
+        # Discord keeps all of these on (desktop-first, more vertical space).
         assert resolve_display_setting({}, "discord", "interim_assistant_messages") is True
         assert resolve_display_setting({}, "discord", "long_running_notifications") is True
         assert resolve_display_setting({}, "discord", "busy_ack_detail") is True
 
     def test_telegram_mobile_chatter_can_opt_in(self):
-        """Per-platform config can re-enable Telegram status chatter."""
+        """Per-platform config can re-enable Telegram busy-ack detail
+        and re-disable the kept-on defaults."""
         from gateway.display_config import resolve_display_setting
 
         config = {
             "display": {
                 "platforms": {
                     "telegram": {
-                        "interim_assistant_messages": True,
-                        "long_running_notifications": "yes",
+                        "interim_assistant_messages": False,
+                        "long_running_notifications": False,
                         "busy_ack_detail": "on",
                     }
                 }
             }
         }
-        assert resolve_display_setting(config, "telegram", "interim_assistant_messages") is True
-        assert resolve_display_setting(config, "telegram", "long_running_notifications") is True
+        assert resolve_display_setting(config, "telegram", "interim_assistant_messages") is False
+        assert resolve_display_setting(config, "telegram", "long_running_notifications") is False
         assert resolve_display_setting(config, "telegram", "busy_ack_detail") is True
 
 

tests/gateway/test_run_cleanup_progress.py

@@ -2,7 +2,7 @@
 
 When ``display.platforms.<plat>.cleanup_progress: true`` is set for a
 platform whose adapter supports message deletion (e.g. Telegram), the
-tool-progress bubble, "⏳ Still working..." notices, and status-callback
+tool-progress bubble, "⏳ Working — N min" heartbeats, and status-callback
 messages sent during a run are deleted after the final response is
 delivered.
 

tests/gateway/test_run_progress_topics.py

@@ -784,13 +784,12 @@ async def test_run_agent_surfaces_real_interim_commentary(monkeypatch, tmp_path)
 
 
 @pytest.mark.asyncio
-async def test_run_agent_surfaces_interim_commentary_when_globally_enabled(monkeypatch, tmp_path):
+async def test_run_agent_surfaces_interim_commentary_by_default(monkeypatch, tmp_path):
     adapter, result = await _run_with_agent(
         monkeypatch,
         tmp_path,
         CommentaryAgent,
-        session_id="sess-commentary-global-on",
-        config_data={"display": {"interim_assistant_messages": True}},
+        session_id="sess-commentary-default-on",
     )
 
     assert any(call["content"] == "I'll inspect the repo first." for call in adapter.sent)