(new): expand runtime APIs

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

plugins_test.go

@@ -49,6 +49,39 @@ func TestAsyncMiddlewareRecoversPanic(t *testing.T) {
 	}
 }
 
+func TestAsyncMiddlewareUsesContextTaskTracker(t *testing.T) {
+	bot := new(Bot[NoData])
+	started := make(chan struct{})
+	release := make(chan struct{})
+	ctx := &MessageContext{asyncTask: bot.startAsyncTask}
+	middleware := NewMiddleware[NoData]("tracked", func(*MessageContext, NoData) bool {
+		close(started)
+		<-release
+		return true
+	}).SetAsync(true)
+
+	if !middleware.Execute(ctx, NoData{}) {
+		t.Fatal("async middleware blocked execution")
+	}
+	<-started
+	waited := make(chan struct{})
+	go func() {
+		bot.middlewareWG.Wait()
+		close(waited)
+	}()
+	select {
+	case <-waited:
+		t.Fatal("task tracker finished before middleware returned")
+	case <-time.After(20 * time.Millisecond):
+	}
+	close(release)
+	select {
+	case <-waited:
+	case <-time.After(time.Second):
+		t.Fatal("task tracker did not finish after middleware returned")
+	}
+}
+
 func TestSyncMiddlewareRecoversPanic(t *testing.T) {
 	observer := &middlewareErrorObserver{errors: make(chan ErrorEvent, 1)}
 	ctx := &MessageContext{observer: observer}