fix(telegram): add panic recovery to HandleUpdate and handleChatMessage

- HandleUpdate now recovers from panics in handler callbacks via defer recoverFromPanic()
- Logs panic errors and fires OnError to notify users of internal errors
- handleChatMessage recovers from panics in agent goroutine to prevent
  per-chat mutex deadlock — sends error message to user with /new suggestion
- 3 new tests: TestHandleUpdate_RecoverFromPanic, _Callback, _Command

Author: molty3000

cmd/odek/telegram.go

@@ -570,7 +570,7 @@ func handleChatMessage(
 	bot *telegram.Bot,
 	handler *telegram.Handler,
 	sessionManager *telegram.SessionManager,
-	resolved	config.ResolvedConfig,
+	resolved config.ResolvedConfig,
 	systemMessage string,
 	log telegram.Logger,
 ) {
@@ -584,6 +584,16 @@ func handleChatMessage(
 	}
 	defer mu.Unlock()
 
+	// Recover from panics so a single bad agent run doesn't deadlock the chat.
+	defer func() {
+		if r := recover(); r != nil {
+			log.Error("panic in handleChatMessage", "chat_id", chatID, "panic", r)
+			reportError(bot, chatID, messageID, fmt.Sprintf(
+				"Internal error: %v\n\nThe bot is still running. Use /new to start a fresh session.", r,
+			))
+		}
+	}()
+
 	// Create a per-chat TelegramApprover for inline keyboard approval.
 	approver := telegram.NewTelegramApprover(bot, chatID)
 	handler.SetApprover(chatID, approver)

internal/telegram/handler.go

@@ -158,7 +158,10 @@ func defaultPhotoHandler(bot *Bot) func(int64, int, []string) (string, error) {
 // ─── Update Routing ───────────────────────────────────────────────────────
 
 // HandleUpdate routes an incoming Telegram update to the appropriate handler.
+// Recovers from panics in handler callbacks to prevent a single bad update
+// from crashing the entire bot loop.
 func (h *Handler) HandleUpdate(upd Update) {
+	defer h.recoverFromPanic("HandleUpdate", upd.ID)
 	switch {
 	case upd.Message != nil:
 		h.handleMessage(upd.Message)
@@ -169,6 +172,20 @@ func (h *Handler) HandleUpdate(upd Update) {
 	}
 }
 
+// recoverFromPanic catches panics in handler callbacks, logs them, and fires
+// OnError if configured. Use as: defer h.recoverFromPanic("method", id).
+func (h *Handler) recoverFromPanic(method string, updateID int) {
+	if r := recover(); r != nil {
+		h.log.Error("panic recovered", "method", method, "update_id", updateID, "panic", r)
+		if h.OnError != nil {
+			// Try to extract a chat ID from the panic context, but
+			// we don't have it here — use 0 and let the callback
+			// decide how to handle it.
+			h.OnError(0, fmt.Errorf("telegram: panic in %s (update %d): %v", method, updateID, r))
+		}
+	}
+}
+
 // handleMessage routes a single message based on content type and permissions.
 func (h *Handler) handleMessage(msg *Message) {
 	if msg.Chat == nil || msg.From == nil {

internal/telegram/handler_recover_test.go

@@ -0,0 +1,149 @@
+package telegram
+
+import (
+	"sync/atomic"
+	"testing"
+)
+
+// TestHandleUpdate_RecoverFromPanic verifies that HandleUpdate catches panics
+// in the handler callbacks and continues processing subsequent updates.
+func TestHandleUpdate_RecoverFromPanic(t *testing.T) {
+	ts := testServer(t, nil)
+	defer ts.Close()
+	bot := testBot(t, ts)
+	h := NewHandler(bot)
+
+	// Set up a text handler that panics.
+	var panicCaught atomic.Bool
+	h.OnTextMessage = func(chatID int64, messageID int, text string) (string, error) {
+		panic("simulated handler panic")
+	}
+
+	// Set up OnError to verify it fires.
+	var errorFired atomic.Bool
+	h.OnError = func(chatID int64, err error) {
+		errorFired.Store(true)
+	}
+
+	// Wrap HandleUpdate to catch the panic (so the test doesn't crash).
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				panicCaught.Store(true)
+				// This is what the test verifies — the panic should NOT
+				// escape HandleUpdate. When the fix is applied, HandleUpdate
+				// itself catches the panic, so this defer should never fire.
+			}
+		}()
+		h.HandleUpdate(Update{
+			ID: 1,
+			Message: &Message{
+				ID:   42,
+				Chat: &Chat{ID: 123},
+				From: &User{ID: 456},
+				Text: "hello",
+			},
+		})
+	}()
+
+	if panicCaught.Load() {
+		t.Error("HandleUpdate did not recover from panic — panic escaped to caller")
+	}
+
+	if !errorFired.Load() {
+		t.Error("OnError was not called after panic recovery")
+	}
+}
+
+// TestHandleUpdate_RecoverFromPanicCallback verifies panic recovery
+// in callback query handlers.
+func TestHandleUpdate_RecoverFromPanicCallback(t *testing.T) {
+	ts := testServer(t, nil)
+	defer ts.Close()
+	bot := testBot(t, ts)
+	h := NewHandler(bot)
+
+	h.OnCallbackQuery = func(chatID int64, data string) (string, error) {
+		panic("simulated callback panic")
+	}
+
+	var errorFired atomic.Bool
+	h.OnError = func(chatID int64, err error) {
+		errorFired.Store(true)
+	}
+
+	var panicEscaped atomic.Bool
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				panicEscaped.Store(true)
+			}
+		}()
+		h.HandleUpdate(Update{
+			ID: 2,
+			CallbackQuery: &CallbackQuery{
+				ID:   "cq_test",
+				From: &User{ID: 456},
+				Message: &Message{
+					Chat: &Chat{ID: 789},
+				},
+				Data: "test_data",
+			},
+		})
+	}()
+
+	if panicEscaped.Load() {
+		t.Error("HandleUpdate did not recover from callback handler panic")
+	}
+
+	if !errorFired.Load() {
+		t.Error("OnError was not called after callback panic recovery")
+	}
+}
+
+// TestHandleUpdate_RecoverFromPanicCommand verifies panic recovery
+// in command handlers.
+func TestHandleUpdate_RecoverFromPanicCommand(t *testing.T) {
+	ts := testServer(t, nil)
+	defer ts.Close()
+	bot := testBot(t, ts)
+	h := NewHandler(bot)
+
+	h.OnCommand = func(chatID int64, messageID int, cmd string, args string) (string, error) {
+		panic("simulated command panic")
+	}
+
+	var errorFired atomic.Bool
+	h.OnError = func(chatID int64, err error) {
+		errorFired.Store(true)
+	}
+
+	var panicEscaped atomic.Bool
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				panicEscaped.Store(true)
+			}
+		}()
+		h.HandleUpdate(Update{
+			ID: 3,
+			Message: &Message{
+				ID:   99,
+				Chat: &Chat{ID: 111},
+				From: &User{ID: 222},
+				Text: "/start",
+				Entities: []MessageEntity{
+					{Type: "bot_command", Offset: 0, Length: 6},
+				},
+			},
+		})
+	}()
+
+	if panicEscaped.Load() {
+		t.Error("HandleUpdate did not recover from command handler panic")
+	}
+
+	if !errorFired.Load() {
+		t.Error("OnError was not called after command panic recovery")
+	}
+}