(new): expand runtime APIs

(fix): harden concurrent lifecycle
(tests): add regression coverage
(doc): update v1.2 guidance

observer.go

@@ -228,7 +228,8 @@ func (ErrorEvent) isEvent()           {}
 // During RunWithContext and RunWebhookWithContext, callbacks execute on a
 // dedicated dispatcher goroutine in enqueue order and never block update
 // handlers. The queue is bounded; overload drops events and emits sampled
-// warnings. Runtime shutdown drains events that were already queued.
+// warnings. Runtime shutdown cancels callback contexts and drains queued events;
+// Bot.Close returns ErrObserverShutdownTimeout if a callback ignores cancellation.
 type Observer interface {
 	OnUpdateReceived(ctx context.Context, event UpdateReceivedEvent)
 	OnUpdateHandled(ctx context.Context, event UpdateHandledEvent)