(new): expand runtime APIs

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

scene_handler.go

@@ -1,24 +1,37 @@
 package laniakea
 
 import (
-	"errors"
 	"fmt"
 	"strings"
 	"time"
 )
 
 func (bot *Bot[T]) tryHandleScene(ctx *MessageContext) (bool, error) {
-	key, session, err := bot.findSceneSession(ctx)
-	if err != nil {
-		if errors.Is(err, ErrCantFindSession) {
-			return false, nil
+	for _, scope := range bot.sceneScopePriority {
+		key, ok := buildSceneKey(scope, ctx)
+		if !ok {
+			continue
 		}
-		return false, err
-	}
-	if session.Scene == "" {
-		return false, nil
-	}
 
+		unlock := bot.sceneLocks.lock([]string{key})
+		session, err := bot.sessionStore.Get(key)
+		if err != nil {
+			unlock()
+			return false, err
+		}
+		if session.Scene == "" {
+			unlock()
+			continue
+		}
+
+		handled, err := bot.tryHandleSceneSession(ctx, key, session)
+		unlock()
+		return handled, err
+	}
+	return false, nil
+}
+
+func (bot *Bot[T]) tryHandleSceneSession(ctx *MessageContext, key string, session SceneSession) (bool, error) {
 	for _, plugin := range bot.plugins {
 		scene, ok := plugin.scenes[session.Scene]
 		if !ok {