Summary

Fixes #30411. Commit ede47a54b added _recover_telegram_topic_thread_id() in gateway/run.py and wired it unconditionally for every inbound Telegram DM whenever topic mode is on. That silently broke the documented root-DM → new-topic → auto-rename → tool-call routing flow: a fresh message from the root Telegram DM (thread_id missing/General) gets rewritten to the user's most-recent bound topic before the session store ever sees it, so a brand-new topic is never spawned and the new session's auto-rename + tool-call payloads land in the wrong topic.

The pinning behavior is still genuinely useful for the original use case (cross-topic Reply leaks, stripped plain replies that would otherwise land in the lobby), so this PR does not revert it — it makes it opt-in behind a new flag, restoring the pre-ede47a54b default.

gateway:
  platforms:
    telegram:
      extra:
        pin_root_dm_replies: true   # default: false

Before / after

Reproduction (from the issue)

1. Run Hermes gateway with Telegram enabled, telegram.extra.disable_topic_auto_rename unset (defaults to false).
2. Send a message from the Telegram root DM — a new topic should be created.
3. Reply in that topic — it should get auto-renamed after one turn.
4. Send a new message from the root DM again — pre-fix, the response appears in the topic from step 2; post-fix, a fresh topic is created.

Root cause

Commit ede47a54b ("fix(gateway): pin Telegram DM-topic routing to user's current topic") added _recover_telegram_topic_thread_id() and wired it into the inbound-message path in GatewayRunner so it ran whenever:

• platform is Telegram,
• chat_type is dm,
• topic mode is enabled for the chat.

The function rewrites source.thread_id to the most recently bound topic whenever the inbound thread_id is missing/General or otherwise unknown. That matches the cross-topic Reply leak case it was written for, but the same conditions also fire for every genuinely fresh root-DM message — lobby thread_id is exactly how Telegram delivers a brand-new root-DM. There's no signal in the inbound payload that distinguishes "stripped plain reply" from "intentional new conversation in the lobby", so the always-on rewrite collapsed both into the pinned-to-last-topic branch.

That cascaded into two secondary bugs that look unrelated at the call site but share the same root:

• Auto-rename: _telegram_topic_auto_rename_disabled defaults to False, but the rename path operates on the post-recovery source.thread_id. After the rewrite, the helper "renames" the already-named older topic instead of the brand-new topic that was supposed to be created, so the rename appears silently broken.
• Tool-call routing: progress events use source from the inbound message; once it's been rewritten to the pinned topic, tool-call output surfaces in that pinned topic regardless of which topic the user actually replied in.

Design — why opt-in instead of revert

ede47a54b solves a real problem (Telegram delivering message_thread_id for a foreign topic on cross-topic Replies, and _build_message_event stripping thread_id on plain replies via #3206). Reverting would re-break that for anyone who deployed against newer Hermes versions and started relying on the pinning. Instead:

• Default pin_root_dm_replies = false restores the pre-ede47a54b behavior — root-DM lobby messages flow through unmodified, new topics get created, auto-rename runs against the right topic, tool calls route to the originating topic.
• Operators who explicitly want pinning (the original use case in ede47a54b's tests) opt in via extra.pin_root_dm_replies: true. The function body is otherwise unchanged.
• The flag is read via a small dedicated helper (_telegram_pin_root_dm_replies_enabled) that mirrors the shape of the sibling _telegram_topic_auto_rename_disabled: accepts bool, plus YAML-friendly truthy strings (true/yes/on/1).

Migration note

If you previously relied on the recovery rewrite (root-DM lobby messages or cross-topic Replies getting pinned to your last active topic), add:

gateway:
  platforms:
    telegram:
      extra:
        pin_root_dm_replies: true

If you didn't know that behavior existed (or actively wanted root-DM messages to spawn new topics), do nothing — the default now matches the pre-ede47a54b behavior.

Architecture affected

inbound Telegram update
        │
        ▼
GatewayRunner.handle_message_event
        │
        ▼   ← recovery hook (this PR makes it opt-in)
_recover_telegram_topic_thread_id ──gated by─▶ extra.pin_root_dm_replies
        │
        ▼
source.thread_id (possibly rewritten)
        │
        ▼
SessionStore.get_or_create_session  ──▶ binding lookup / new topic spawn
        │
        ▼
session run ──▶ _schedule_telegram_topic_title_rename ──gated by─▶ extra.disable_topic_auto_rename
        │
        ▼
tool-call progress events ──▶ adapter.send(..., thread_id=source.thread_id)

The two extra flags are intentionally decoupled (covered by a dedicated test): flipping one must not silently mutate the other's effective behavior.

Tests

All in tests/gateway/test_telegram_topic_mode.py. Existing 5 recovery tests were updated to opt in via the new flag (_pin_root_dm_replies(runner)). New tests pin the bug-fix contract:

• test_pin_root_dm_replies_default_off — [Bug]: Telegram DM auto-topic-rename and tool-call routing broken by _recover_telegram_topic_thread_id() #30411 regression: flag unset → lobby + unknown inbound thread_ids are no longer rewritten.
• test_pin_root_dm_replies_explicit_false — parity check: explicit false matches the default.
• test_pin_root_dm_replies_truthy_string_opts_in[true|True|1|yes|on] — YAML-friendly string parsing, parametrized to match the sibling disable_topic_auto_rename flag's accepted shapes.
• test_pin_root_dm_replies_disable_topic_auto_rename_decoupled — second half of the bug report: the two flags are independent; flipping one must not change the other's effective state.
• test_pin_root_dm_replies_tool_call_routing_default — edge case: a tool-call inbound carrying an older topic's thread_id is never rewritten to the most-recent topic, in either default or opt-in mode.

Test run on this branch:

tests/gateway/test_telegram_topic_mode.py ........................... 51 passed

Verified the new tests fail on the parent commit without the gateway/run.py change (test_pin_root_dm_replies_default_off asserts None, gets '222' from the unconditional pinning) and pass with it.

Fixes #30411