fix(lifecycle): additive-scene entry point ownership handoff (F-14)

A second CoreAIGameEntryPoint in an additive scene now registers as a standby owner;
when the owning scope is destroyed the next live standby is promoted (its facade
initialization re-runs) instead of the static CoreAI facade being reset with a live
scope still present. Reset only happens when no standby remains.
+PlayMode handoff test (two entry points, destroy first, facade still resolves).

Author: NeoXider

Assets/CoreAiUnity/Runtime/Source/Composition/CoreAIGameEntryPoint.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using CoreAI.Ai;
 using CoreAI.Logging;
 using VContainer.Unity;
@@ -8,9 +9,16 @@ namespace CoreAI.Composition
     /// <summary>
     /// VContainer entry point that initializes and resets the global CoreAI facade.
     /// </summary>
+    /// <remarks>
+    /// When an additive scene spins up a second entry point, it is registered as a standby
+    /// owner rather than dropped: if the current owner is disposed (e.g. its scope/scene is
+    /// unloaded), ownership hands off to the next live standby so the CoreAI facade keeps
+    /// resolving instead of going stale until someone re-initializes it manually.
+    /// </remarks>
     public sealed class CoreAIGameEntryPoint : IStartable, IDisposable
     {
         private static readonly object StartGate = new();
+        private static readonly List<CoreAIGameEntryPoint> StandbyInstances = new();
         private static bool _isInitialized;
 
         /// <summary>
@@ -23,6 +31,7 @@ public sealed class CoreAIGameEntryPoint : IStartable, IDisposable
         private readonly AgentMemoryPolicy _policy;
         private readonly IAgentMemoryStore _memoryStore;
         private bool _started;
+        private bool _isOwner;
 
         /// <summary>Initializes a new instance of CoreAIGameEntryPoint.</summary>
         public CoreAIGameEntryPoint(ILog logger, IAiOrchestrationService orchestrator, AgentMemoryPolicy policy,
@@ -37,25 +46,45 @@ public CoreAIGameEntryPoint(ILog logger, IAiOrchestrationService orchestrator, A
         /// <summary>Starts the entry point and registers CoreAI services for runtime use.</summary>
         public void Start()
         {
+            bool becomeOwner;
+
             lock (StartGate)
             {
                 if (_started)
                 {
                     return;
                 }
 
+                _started = true;
+
                 if (_isInitialized)
                 {
-                    _logger.Debug(
-                        "CoreAI already initialized in this process. Duplicate CoreAIGameEntryPoint start skipped.",
-                        LogTag.Composition);
-                    return;
+                    // Another entry point already owns the facade; register as a standby owner
+                    // so we can take over if that owner is later disposed (e.g. additive scene unload).
+                    StandbyInstances.Add(this);
+                    becomeOwner = false;
                 }
+                else
+                {
+                    _isInitialized = true;
+                    _isOwner = true;
+                    becomeOwner = true;
+                }
+            }
 
-                _isInitialized = true;
-                _started = true;
+            if (!becomeOwner)
+            {
+                _logger.Debug(
+                    "CoreAI already initialized in this process. This CoreAIGameEntryPoint is registered as a standby owner.",
+                    LogTag.Composition);
+                return;
             }
 
+            InitializeAsOwner();
+        }
+
+        private void InitializeAsOwner()
+        {
             CoreAIAgent.Initialize(_orchestrator, _policy, _memoryStore);
 
             _logger.Info(
@@ -76,6 +105,9 @@ public void Start()
 
         public void Dispose()
         {
+            bool wasOwner;
+            CoreAIGameEntryPoint promoted = null;
+
             lock (StartGate)
             {
                 if (!_started)
@@ -84,17 +116,57 @@ public void Dispose()
                 }
 
                 _started = false;
-                _isInitialized = false;
+                wasOwner = _isOwner;
+
+                if (wasOwner)
+                {
+                    _isOwner = false;
+                    _isInitialized = false;
+
+                    while (StandbyInstances.Count > 0)
+                    {
+                        CoreAIGameEntryPoint candidate = StandbyInstances[0];
+                        StandbyInstances.RemoveAt(0);
+
+                        // Skip standbys that were disposed while still waiting (never became owner).
+                        if (!candidate._started)
+                        {
+                            continue;
+                        }
+
+                        candidate._isOwner = true;
+                        _isInitialized = true;
+                        promoted = candidate;
+                        break;
+                    }
+                }
+                else
+                {
+                    StandbyInstances.Remove(this);
+                }
             }
 
-            CoreAIAgent.Reset();
+            if (!wasOwner)
+            {
+                return;
+            }
+
+            if (promoted != null)
+            {
+                promoted.InitializeAsOwner();
+            }
+            else
+            {
+                CoreAIAgent.Reset();
+            }
         }
 
         internal static void ResetInitializationGuardForTests()
         {
             lock (StartGate)
             {
                 _isInitialized = false;
+                StandbyInstances.Clear();
             }
         }
 

Assets/CoreAiUnity/Tests/PlayMode/FastNoLlm/CoreAIGameEntryPointOwnershipHandoffPlayModeTests.cs

@@ -0,0 +1,169 @@
+using System.Collections;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using CoreAI.Ai;
+using CoreAI.Composition;
+using CoreAI.Logging;
+using NUnit.Framework;
+using UnityEngine;
+using UnityEngine.TestTools;
+
+namespace CoreAI.Tests.PlayModeTest
+{
+    /// <summary>
+    /// Covers F-14: when the owning CoreAIGameEntryPoint is destroyed (e.g. its additive scene is
+    /// unloaded), a standby entry point registered earlier must be promoted so the CoreAI facade
+    /// keeps resolving instead of going stale.
+    /// </summary>
+    [TestFixture]
+    public sealed class CoreAIGameEntryPointOwnershipHandoffPlayModeTests
+    {
+        private readonly List<GameObject> _spawned = new();
+
+        [SetUp]
+        public void SetUp()
+        {
+            CoreAIAgent.Reset();
+            CoreAIGameEntryPoint.ResetInitializationGuardForTests();
+            CoreAIGameEntryPoint.AutoBootstrap = false;
+        }
+
+        [TearDown]
+        public void TearDown()
+        {
+            foreach (GameObject go in _spawned)
+            {
+                if (go != null)
+                {
+                    Object.Destroy(go);
+                }
+            }
+
+            _spawned.Clear();
+
+            CoreAIAgent.Reset();
+            CoreAIGameEntryPoint.ResetInitializationGuardForTests();
+            CoreAIGameEntryPoint.AutoBootstrap = false;
+        }
+
+        [UnityTest]
+        public IEnumerator DestroyingOwner_PromotesStandbyEntryPoint_FacadeStaysResolvable()
+        {
+            yield return null;
+
+            GameObject firstOwnerObject = CreateOwnerGameObject("FirstAdditiveSceneEntryPoint");
+            GameObject secondOwnerObject = CreateOwnerGameObject("SecondAdditiveSceneEntryPoint");
+
+            StubOrchestrator orchestrator1 = new();
+            AgentMemoryPolicy policy1 = new();
+            StubMemoryStore memoryStore1 = new();
+            CoreAIGameEntryPoint first = new(new TestLogger(), orchestrator1, policy1, memoryStore1);
+
+            StubOrchestrator orchestrator2 = new();
+            AgentMemoryPolicy policy2 = new();
+            StubMemoryStore memoryStore2 = new();
+            CoreAIGameEntryPoint second = new(new TestLogger(), orchestrator2, policy2, memoryStore2);
+
+            // Simulate two additive scenes each spinning up their own composition root.
+            first.Start();
+            second.Start();
+
+            Assert.AreSame(orchestrator1, CoreAIAgent.Orchestrator,
+                "The first entry point should own the facade after both are started.");
+
+            yield return null;
+
+            // Simulate the first additive scene being unloaded: its GameObject and entry point are destroyed.
+            Object.Destroy(firstOwnerObject);
+            first.Dispose();
+
+            yield return null;
+
+            Assert.AreSame(orchestrator2, CoreAIAgent.Orchestrator,
+                "The facade must hand off to the standby second entry point instead of going stale.");
+            Assert.AreSame(policy2, CoreAIAgent.Policy);
+            Assert.AreSame(memoryStore2, CoreAIAgent.MemoryStore);
+
+            second.Dispose();
+            Object.Destroy(secondOwnerObject);
+        }
+
+        private GameObject CreateOwnerGameObject(string name)
+        {
+            GameObject go = new(name);
+            _spawned.Add(go);
+            return go;
+        }
+
+        private sealed class TestLogger : ILog
+        {
+            public void Debug(string message, string tag = null)
+            {
+            }
+
+            public void Info(string message, string tag = null)
+            {
+            }
+
+            public void Warn(string message, string tag = null)
+            {
+            }
+
+            public void Error(string message, string tag = null)
+            {
+            }
+        }
+
+        private sealed class StubOrchestrator : IAiOrchestrationService
+        {
+            public Task<string> RunTaskAsync(AiTaskRequest task, CancellationToken cancellationToken = default)
+            {
+                return Task.FromResult(string.Empty);
+            }
+
+            public async IAsyncEnumerable<LlmStreamChunk> RunStreamingAsync(
+                AiTaskRequest task,
+                [System.Runtime.CompilerServices.EnumeratorCancellation]
+                CancellationToken cancellationToken = default)
+            {
+                yield return new LlmStreamChunk { IsDone = true };
+                await Task.CompletedTask;
+            }
+
+            public void CancelTasks(string cancellationScope)
+            {
+            }
+        }
+
+        private sealed class StubMemoryStore : IAgentMemoryStore
+        {
+            public bool TryLoad(string roleId, out AgentMemoryState state)
+            {
+                state = null;
+                return false;
+            }
+
+            public void Save(string roleId, AgentMemoryState state)
+            {
+            }
+
+            public void Clear(string roleId)
+            {
+            }
+
+            public void ClearChatHistory(string roleId)
+            {
+            }
+
+            public void AppendChatMessage(string roleId, string role, string content, bool persistToDisk = true)
+            {
+            }
+
+            public ChatMessage[] GetChatHistory(string roleId, int maxMessages = 0)
+            {
+                return System.Array.Empty<ChatMessage>();
+            }
+        }
+    }
+}