@alpsckr/unitycli 0.4.3 → 0.4.4

package/unitypkg/Editor/Infrastructure/UnityCliOcclusionBakeCoordinator.cs

@@ -60,13 +60,13 @@ namespace UnityCli
                 protected override string OperationDisplayName { get { return "Occlusion bake"; } }
                 protected override int CommandTimeoutMs { get { return 600000; } }
                 protected override bool IncludeAcceptedInStatus { get { return true; } }
-                protected override IEnumerable<(string name, bool destructive)> AdditionalCommands
+                protected override IEnumerable<(string name, bool destructive, UnityCliBridgeQueuePolicy.WorkClass queueClass)> AdditionalCommands
                 {
                     get
                     {
-                        yield return (PlanCommand, false);
-                        yield return (SnapshotCommand, false);
-                        yield return (CancelCommand, true);
+                        yield return (PlanCommand, false, UnityCliBridgeQueuePolicy.WorkClass.Mutation);
+                        yield return (SnapshotCommand, false, UnityCliBridgeQueuePolicy.WorkClass.OrdinaryRead);
+                        yield return (CancelCommand, true, UnityCliBridgeQueuePolicy.WorkClass.Control);
                     }
                 }
 

package/unitypkg/Editor/Infrastructure/UnityCliOperationCoordinator.cs

@@ -50,6 +50,9 @@ namespace UnityCli
         /// </summary>
         private static async Task<string> ExecuteCoordinatedRequest(BridgeRequest request, byte[] rawRequestBytes, Func<bool> tryAcceptJournal, CancellationToken cancellationToken)
         {
+            // durable status只读active journal或terminal cache，必须绕开通用direct completion路径。
+            if (UnityCliDurableStatusCoordinator.IsCommand(request.Command))
+                return await UnityCliDurableStatusCoordinator.Execute(request, cancellationToken);
             // 私有 compile start/status 必须绕开通用 completion 路径；start 的 accepted 不是公开 terminal。
             if (UnityCliCompileCoordinator.IsCommand(request.Command))
                 return await UnityCliCompileCoordinator.Execute(request, rawRequestBytes, tryAcceptJournal, cancellationToken);
@@ -97,7 +100,7 @@ namespace UnityCli
                 object durableTerminal;
                 if (UnityCliActiveOperation.TryGetTerminal(DirectMutationTerminalScope, request.RequestId, requestDigest, out durableTerminal))
                 {
-                    CleanupPublishedDirectMutation(request.RequestId, requestDigest, AdmissionTerminalIsOutcomeUnknown(durableTerminal));
+                    CleanupPublishedDirectMutation(request.RequestId, requestDigest);
                     return UnityCliSerializer.Serialize(durableTerminal);
                 }
             }
@@ -128,7 +131,7 @@ namespace UnityCli
                 return ExecutionTimeoutEnvelope(request.RequestId, "The request was not accepted before the execution deadline elapsed.");
             }
 
-            try { SaveDirectMutationAcceptedRoot(request.RequestId, requestDigest); }
+            try { SaveDirectMutationAcceptedRoot(request, requestDigest, contract.ToolName); }
             catch (Exception exception)
             {
                 ScheduleDirectMutationPreEffectCleanup(request.RequestId, requestDigest);
@@ -192,40 +195,73 @@ namespace UnityCli
             try { UnityCliActiveOperation.BeginExactTerminalCleanup(DirectMutationTerminalScope, requestId, requestDigest); } catch { }
         }
 
-        /// <summary>effect后的direct terminal先做字节admission，再进入active root与共享cache；超限统一替换为紧凑终态。</summary>
+        /// <summary>effect后的direct terminal先冻结first terminal，再由exact cleanup marker驱动root、lease与admission收敛。</summary>
         private static string PersistDirectMutationTerminal(string requestId, string requestDigest, string serializedEnvelope)
+        {
+            return PublishDirectMutationTerminal(ProductionQueueState, requestId, requestDigest, serializedEnvelope);
+        }
+
+        internal static string PublishDirectMutationTerminalForTests(BridgeQueueState state, string requestId, string requestDigest, string serializedEnvelope)
+        {
+            if (state == null || state.IsolatedExecution == null) throw new ArgumentException("Direct mutation test state must be isolated.", "state");
+            return PublishDirectMutationTerminal(state, requestId, requestDigest, serializedEnvelope);
+        }
+
+        private static string PublishDirectMutationTerminal(BridgeQueueState state, string requestId, string requestDigest, string serializedEnvelope)
         {
             try
             {
                 bool isOwned;
-                if (!UnityCliSessionMutationLease.TryIsOwnedBy(requestId, requestDigest, out isOwned) || !isOwned)
+                if (!state.TryIsLeaseOwned(requestId, requestDigest, out isOwned) || !isOwned)
                     serializedEnvelope = ExecutionTimeoutEnvelope(requestId, "The direct mutation lost its exact lease after effect; outcome is unknown. Inspect the affected business state.");
                 if (Encoding.UTF8.GetByteCount(serializedEnvelope ?? string.Empty) > MaxDirectMutationTerminalBytes)
                     serializedEnvelope = ExecutionTimeoutEnvelope(requestId, "The direct mutation completed, but its terminal exceeded the durable byte budget; inspect the affected business state.");
                 object envelope = UnityCliSerializer.Parse(serializedEnvelope) as Dictionary<string, object>;
                 if (envelope == null)
                     envelope = ProtocolEnvelopeFactory.Error(requestId, "E_EXECUTION_TIMEOUT", "The direct mutation terminal could not be decoded after effect; outcome is unknown.");
-                var root = LoadDirectMutationRoot();
+                var root = LoadDirectMutationRoot(state);
                 RequireDirectMutationRoot(root, requestId, requestDigest);
                 root["phase"] = "terminal_pending";
                 root["terminalEnvelope"] = envelope;
-                UnityCliActiveOperation.Save(DirectMutationTerminalScope, root);
-                var first = UnityCliActiveOperation.StoreTerminalFirst(DirectMutationTerminalScope, requestId, requestDigest, envelope);
-                UnityCliActiveOperation.Clear(DirectMutationTerminalScope);
+                state.SaveOperation(DirectMutationTerminalScope, root);
+                var first = state.StoreTerminalFirst(DirectMutationTerminalScope, requestId, requestDigest, null, root["toolName"] as string, envelope);
+                CleanupPublishedDirectMutation(state, requestId, requestDigest);
                 return UnityCliSerializer.Serialize(first);
             }
             catch (BridgeCommandException exception) { return SerializeBridgeExceptionEnvelope(requestId, exception); }
             catch (Exception exception) { return SerializeBridgeExceptionEnvelope(requestId, new BridgeCommandException("E_EXECUTION_TIMEOUT", "Direct mutation terminal publication is incomplete; the exact owner is retained: " + exception.GetType().Name + ".")); }
         }
 
-        private static void SaveDirectMutationAcceptedRoot(string requestId, string requestDigest)
+        private static void SaveDirectMutationAcceptedRoot(BridgeRequest request, string requestDigest, string toolName)
         {
             UnityCliActiveOperation.Save(DirectMutationTerminalScope, new Dictionary<string, object>
             {
-                { "requestId", requestId }, { "requestDigest", requestDigest }, { "editorSessionId", EditorSessionId() }, { "phase", "accepted_before_effect" }
+                { "requestId", request.RequestId }, { "requestDigest", requestDigest }, { "toolName", toolName },
+                { "editorSessionId", EditorSessionId() }, { "absoluteDeadlineUtc", request.Execution.AbsoluteDeadlineUtc },
+                { "phase", "accepted_before_effect" }
             });
         }
 
+        /// <summary>editor.play-mode.status只读取editor.play/editor.stop的direct owner或其已发布终态。</summary>
+        private static object ReadEditorPlayModeStatus(string requestId)
+        {
+            string requestDigest;
+            string statusDomain;
+            object terminal;
+            if (UnityCliActiveOperation.TryGetTerminalByRequestId(DirectMutationTerminalScope, requestId, out requestDigest, out statusDomain, out terminal))
+            {
+                if (statusDomain != "editor.play" && statusDomain != "editor.stop")
+                    throw new BridgeCommandException("E_REQUEST_NOT_FOUND", "The requested Play Mode operation was not found in this status domain.");
+                return UnityCliDurableStatusCoordinator.Terminal(requestId, terminal);
+            }
+            var root = LoadDirectMutationRoot();
+            var toolName = root == null ? null : root.ContainsKey("toolName") ? root["toolName"] as string : null;
+            if (root == null || !string.Equals(root["requestId"] as string, requestId, StringComparison.Ordinal)
+                || (toolName != "editor.play" && toolName != "editor.stop"))
+                throw new BridgeCommandException("E_REQUEST_NOT_FOUND", "The requested Play Mode operation was not found in this Editor session.");
+            return UnityCliDurableStatusCoordinator.Running(requestId, root["phase"] as string);
+        }
+
         private static void MarkDirectMutationEffectStarted(string requestId, string requestDigest)
         {
             var root = LoadDirectMutationRoot();
@@ -233,20 +269,29 @@ namespace UnityCli
             if (!string.Equals(root["phase"] as string, "accepted_before_effect", StringComparison.Ordinal)
                 && !string.Equals(root["phase"] as string, "effect_started", StringComparison.Ordinal))
                 throw new BridgeCommandException("E_EXECUTION_TIMEOUT", "Direct mutation active state cannot cross its effect barrier.");
+            var toolName = root["toolName"] as string;
+            if ((string.Equals(toolName, "editor.play", StringComparison.Ordinal) || string.Equals(toolName, "editor.stop", StringComparison.Ordinal))
+                && !root.ContainsKey("playModeWasPlaying"))
+                root["playModeWasPlaying"] = EditorApplication.isPlaying;
             root["phase"] = "effect_started";
             UnityCliActiveOperation.Save(DirectMutationTerminalScope, root);
         }
 
         private static Dictionary<string, object> LoadDirectMutationRoot()
+        {
+            return LoadDirectMutationRoot(ProductionQueueState);
+        }
+
+        private static Dictionary<string, object> LoadDirectMutationRoot(BridgeQueueState state)
         {
             try
             {
-                var root = UnityCliActiveOperation.Load(DirectMutationTerminalScope);
+                var root = state.LoadOperation(DirectMutationTerminalScope);
                 if (root == null) return null;
-                object requestId; object requestDigest; object editorSessionId; object phase;
+                object requestId; object requestDigest; object toolName; object editorSessionId; object phase;
                 if (!root.TryGetValue("requestId", out requestId) || !root.TryGetValue("requestDigest", out requestDigest)
-                    || !root.TryGetValue("editorSessionId", out editorSessionId) || !root.TryGetValue("phase", out phase)
-                    || !(requestId is string) || !(requestDigest is string) || !(editorSessionId is string) || !(phase is string))
+                    || !root.TryGetValue("toolName", out toolName) || !root.TryGetValue("editorSessionId", out editorSessionId) || !root.TryGetValue("phase", out phase)
+                    || !(requestId is string) || !(requestDigest is string) || !(toolName is string) || !(editorSessionId is string) || !(phase is string))
                     throw new InvalidDataException("Direct mutation active state is incomplete.");
                 return root;
             }
@@ -262,6 +307,51 @@ namespace UnityCli
                 throw new BridgeCommandException("E_EXECUTION_TIMEOUT", "Direct mutation active identity cannot be proven; outcome is unknown.");
         }
 
+        internal enum DirectMutationReloadOutcome { NotApplicable, WaitingExactOwner, SettledEffectBefore, IdentityBlocked }
+
+        /// <summary>旧domain不再执行effect；CleanupPending先释放旧lease，再冻结terminal并执行exact cleanup。</summary>
+        internal static DirectMutationReloadOutcome ReconcileAcceptedDirectMutationAfterReload(BridgeQueueState state, string requestId, string requestDigest)
+        {
+            return ReconcileAcceptedDirectMutationAfterReload(state, requestId, requestDigest,
+                DirectMutationCleanupPendingForIdentity(requestId, requestDigest));
+        }
+
+        internal static DirectMutationReloadOutcome ReconcileAcceptedDirectMutationAfterReload(BridgeQueueState state, string requestId, string requestDigest, bool releaseExactOwnerBeforeSettlement)
+        {
+            if (state == null) throw new ArgumentNullException("state");
+            var root = LoadDirectMutationRoot(state);
+            if (root == null) return DirectMutationReloadOutcome.NotApplicable;
+            RequireDirectMutationRoot(root, requestId, requestDigest);
+            if (!string.Equals(root["phase"] as string, "accepted_before_effect", StringComparison.Ordinal))
+                return DirectMutationReloadOutcome.NotApplicable;
+            string leaseRequestId;
+            string leaseRequestDigest;
+            if (!state.TryGetCurrentLeaseOwner(out leaseRequestId, out leaseRequestDigest))
+                return DirectMutationReloadOutcome.IdentityBlocked;
+            if (string.Equals(leaseRequestId, requestId, StringComparison.Ordinal)
+                && string.Equals(leaseRequestDigest, requestDigest, StringComparison.Ordinal))
+            {
+                if (!releaseExactOwnerBeforeSettlement) return DirectMutationReloadOutcome.WaitingExactOwner;
+                if (object.ReferenceEquals(state, ProductionQueueState)) ReleaseDirectMutationLease(requestId, requestDigest);
+                else state.ReleaseLease(requestId, requestDigest);
+                if (!state.TryGetCurrentLeaseOwner(out leaseRequestId, out leaseRequestDigest))
+                    return DirectMutationReloadOutcome.IdentityBlocked;
+            }
+            if (!string.IsNullOrEmpty(leaseRequestId) || !string.IsNullOrEmpty(leaseRequestDigest))
+                return DirectMutationReloadOutcome.IdentityBlocked;
+            var owner = CaptureAdmissionOwner(state, requestId, requestDigest);
+            if (owner.OwnerState != UnityCliAdmissionPool.AdmissionOwnerState.WorkItem
+                && owner.OwnerState != UnityCliAdmissionPool.AdmissionOwnerState.Recovery)
+                return DirectMutationReloadOutcome.IdentityBlocked;
+            var terminal = ProtocolEnvelopeFactory.Error(requestId, "E_EXECUTION_TIMEOUT", "Direct mutation was accepted before domain reload but never crossed its effect barrier; no effect was executed.", null, new[] { "Submit a new request only after inspecting the exact terminal." });
+            root["phase"] = "terminal_pending";
+            root["terminalEnvelope"] = terminal;
+            state.SaveOperation(DirectMutationTerminalScope, root);
+            state.StoreTerminalFirst(DirectMutationTerminalScope, requestId, requestDigest, null, root["toolName"] as string, terminal);
+            UnityCliActiveOperation.BeginExactTerminalCleanup(DirectMutationTerminalScope, requestId, requestDigest, state);
+            return DirectMutationReloadOutcome.SettledEffectBefore;
+        }
+
         private static string TryResumeDirectMutation(string requestId, string requestDigest)
         {
             Dictionary<string, object> root;
@@ -284,35 +374,74 @@ namespace UnityCli
             bool recovered;
             try { if (!UnityCliSessionMutationLease.TryRecoverExact(requestId, requestDigest, out recovered)) return UnityCliSerializer.Serialize(ProtocolEnvelopeFactory.Error(requestId, "E_UNITY_BUSY", "Another mutation owns the selected Unity instance.", null, null, true, 250)); }
             catch (BridgeCommandException exception) { return SerializeBridgeExceptionEnvelope(requestId, exception); }
+            var toolName = root["toolName"] as string;
+            if (string.Equals(phase, "effect_started", StringComparison.Ordinal)
+                && (string.Equals(toolName, "editor.play", StringComparison.Ordinal) || string.Equals(toolName, "editor.stop", StringComparison.Ordinal)))
+            {
+                if (!TryFinalizeRecoveredPlayModeRoot(
+                    ProductionQueueState, requestId, requestDigest,
+                    EditorApplication.isPlaying, EditorApplication.isPaused, IsPlayModeChanging(),
+                    EditorToolSupport.BuildEditorState, DateTimeOffset.UtcNow))
+                    return UnityCliSerializer.Serialize(ProtocolEnvelopeFactory.Error(
+                        requestId, "E_UNITY_BUSY", "The Play Mode transition is still active for this exact request.",
+                        null, new[] { "Run tools run editor.play-mode.status with the same requestId." }, true, 100));
+                object recoveredTerminal;
+                if (UnityCliActiveOperation.TryGetTerminal(DirectMutationTerminalScope, requestId, requestDigest, out recoveredTerminal))
+                    return UnityCliSerializer.Serialize(recoveredTerminal);
+                return ExecutionTimeoutEnvelope(requestId, "The recovered Play Mode terminal could not be read after publication.");
+            }
             object pending;
             var envelope = string.Equals(phase, "terminal_pending", StringComparison.Ordinal) && root.TryGetValue("terminalEnvelope", out pending) && pending != null
                 ? pending
                 : (object)ProtocolEnvelopeFactory.Error(requestId, "E_EXECUTION_TIMEOUT", "Direct mutation effect was interrupted before a terminal was frozen; outcome is unknown.");
             var result = PersistDirectMutationTerminal(requestId, requestDigest, UnityCliSerializer.Serialize(envelope));
-            CleanupPublishedDirectMutation(requestId, requestDigest, AdmissionTerminalIsOutcomeUnknown(envelope));
+            CleanupPublishedDirectMutation(requestId, requestDigest);
             return result;
         }
 
-        private static void CleanupPublishedDirectMutation(string requestId, string requestDigest, bool completeAdmission)
+        /// <summary>主循环重试已发布direct terminal的exact cleanup；失败保留固定marker等待下一帧。</summary>
+        private static void RetryDirectMutationTerminalCleanup()
+        {
+            RetryDirectMutationTerminalCleanup(ProductionQueueState);
+        }
+
+        internal static void RetryDirectMutationTerminalCleanupForTests(BridgeQueueState state)
+        {
+            if (state == null || state.IsolatedExecution == null) throw new ArgumentException("Direct mutation test state must be isolated.", "state");
+            RetryDirectMutationTerminalCleanup(state);
+        }
+
+        private static void RetryDirectMutationTerminalCleanup(BridgeQueueState state)
+        {
+            try { UnityCliActiveOperation.RetryExactTerminalCleanup(DirectMutationTerminalScope, state); }
+            catch (Exception exception) { state.Sinks.WriteLog("direct_mutation_cleanup_retry_failed " + exception.GetType().Name); }
+        }
+
+        /// <summary>terminal类型不决定slot释放；exact marker必须在root清理前durable存在。</summary>
+        private static void CleanupPublishedDirectMutation(string requestId, string requestDigest)
+        {
+            CleanupPublishedDirectMutation(ProductionQueueState, requestId, requestDigest);
+        }
+
+        private static void CleanupPublishedDirectMutation(BridgeQueueState state, string requestId, string requestDigest)
         {
             try
             {
                 object terminal;
-                if (!UnityCliActiveOperation.TryGetTerminal(DirectMutationTerminalScope, requestId, requestDigest, out terminal)) return;
-                UnityCliActiveOperation.BeginExactTerminalCleanup(DirectMutationTerminalScope, requestId, requestDigest, completeAdmission);
+                if (!state.TryGetTerminal(DirectMutationTerminalScope, requestId, requestDigest, out terminal)) return;
+                AdmissionOwnerIdentity owner;
+                var completeAdmission = TryCaptureExactAdmissionOwner(state, requestId, requestDigest, out owner);
+                UnityCliActiveOperation.BeginExactTerminalCleanup(DirectMutationTerminalScope, requestId, requestDigest, state, completeAdmission);
             }
             catch { }
         }
 
-        private static bool AdmissionTerminalIsOutcomeUnknown(object envelope)
+        internal static string RecoverPublishedDirectMutationForTests(BridgeQueueState state, string requestId, string requestDigest)
         {
-            var value = envelope as IDictionary<string, object>;
-            object ok;
-            if (value == null || !value.TryGetValue("ok", out ok) || !(ok is bool) || (bool)ok) return false;
-            object rawError;
-            var error = value.TryGetValue("error", out rawError) ? rawError as IDictionary<string, object> : null;
-            object code;
-            return error != null && error.TryGetValue("code", out code) && string.Equals(code as string, "E_EXECUTION_TIMEOUT", StringComparison.Ordinal);
+            object terminal;
+            if (state == null || state.IsolatedExecution == null || !state.TryGetTerminal(DirectMutationTerminalScope, requestId, requestDigest, out terminal)) return null;
+            CleanupPublishedDirectMutation(state, requestId, requestDigest);
+            return UnityCliSerializer.Serialize(terminal);
         }
 
         private static void FinalizeDirectMutationExecution(string requestId, string requestDigest)
@@ -341,12 +470,13 @@ namespace UnityCli
             ReleaseDirectMutationLease(requestId, requestDigest);
         }
 
-        /// <summary>主循环恢复direct terminal发布或精确lease清理，I/O不确定时保持root与owner。</summary>
+        /// <summary>主循环只对可直接观察的PlayMode root冻结原类型终态；其余direct effect仍保持unknown。</summary>
         private static bool TryFinalizeRecoveredPlayModeRoot(string requestId, string requestDigest)
         {
+            Dictionary<string, object> root;
             try
             {
-                var root = LoadDirectMutationRoot();
+                root = LoadDirectMutationRoot();
                 if (root != null && SessionState.GetBool(DirectMutationCleanupPendingSessionKey, false)
                     && DirectMutationBindingMatches(requestId, requestDigest)
                     && string.Equals(root["requestId"] as string, requestId, StringComparison.Ordinal)
@@ -355,19 +485,110 @@ namespace UnityCli
                     UnityCliActiveOperation.Clear(DirectMutationTerminalScope);
             }
             catch { return false; }
-            var resumed = TryResumeDirectMutation(requestId, requestDigest);
-            if (resumed != null)
+
+            var finalized = TryFinalizeRecoveredPlayModeRoot(
+                ProductionQueueState, requestId, requestDigest,
+                EditorApplication.isPlaying, EditorApplication.isPaused, IsPlayModeChanging(),
+                EditorToolSupport.BuildEditorState, DateTimeOffset.UtcNow);
+            if (!finalized)
+            {
+                try { root = LoadDirectMutationRoot(); }
+                catch { root = null; }
+                var toolName = root == null ? null : root["toolName"] as string;
+                if (toolName != "editor.play" && toolName != "editor.stop")
+                    finalized = TryResumeDirectMutation(requestId, requestDigest) != null;
+            }
+            if (finalized)
             {
                 try { if (!UnityCliActiveOperation.Exists(DirectMutationTerminalScope)) ReleaseDirectMutationLease(requestId, requestDigest); }
                 catch { }
             }
             if (!SessionState.GetBool(DirectMutationCleanupPendingSessionKey, false)
-                || !DirectMutationBindingMatches(requestId, requestDigest)) return resumed != null;
+                || !DirectMutationBindingMatches(requestId, requestDigest)) return finalized;
             ReleaseDirectMutationLease(requestId, requestDigest);
             bool isOwned;
             return UnityCliSessionMutationLease.TryIsOwnedBy(requestId, requestDigest, out isOwned) && !isOwned;
         }
 
+        internal static bool TryFinalizeRecoveredPlayModeRootForTests(
+            BridgeQueueState state, string requestId, string requestDigest,
+            bool isPlaying, bool isPaused, bool isChanging, DateTimeOffset utcNow)
+        {
+            return TryFinalizeRecoveredPlayModeRoot(state, requestId, requestDigest, isPlaying, isPaused, isChanging,
+                () => new EditorStateInfo
+                {
+                    PlayMode = new PlayModeInfo
+                    {
+                        IsPlaying = isPlaying,
+                        IsPaused = isPaused,
+                        IsPlayingOrWillChangePlaymode = isPlaying || isChanging
+                    },
+                    Busy = new BusyInfo { PlayModeChanging = isChanging }
+                }, utcNow);
+        }
+
+        /// <summary>固定root中的before/deadline与当前主线程状态共同构成跨reload完成证明。</summary>
+        private static bool TryFinalizeRecoveredPlayModeRoot(
+            BridgeQueueState state, string requestId, string requestDigest,
+            bool isPlaying, bool isPaused, bool isChanging,
+            Func<EditorStateInfo> readState, DateTimeOffset utcNow)
+        {
+            Dictionary<string, object> root;
+            try
+            {
+                root = LoadDirectMutationRoot(state);
+                RequireDirectMutationRoot(root, requestId, requestDigest);
+            }
+            catch { return false; }
+            if (!string.Equals(root["phase"] as string, "effect_started", StringComparison.Ordinal)) return false;
+            var toolName = root["toolName"] as string;
+            var enterPlayMode = string.Equals(toolName, "editor.play", StringComparison.Ordinal);
+            if (!enterPlayMode && !string.Equals(toolName, "editor.stop", StringComparison.Ordinal)) return false;
+
+            object beforeValue;
+            object deadlineValue;
+            DateTimeOffset deadline;
+            if (!root.TryGetValue("playModeWasPlaying", out beforeValue) || !(beforeValue is bool)
+                || !root.TryGetValue("absoluteDeadlineUtc", out deadlineValue) || !(deadlineValue is string)
+                || !DateTimeOffset.TryParse((string)deadlineValue, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind, out deadline))
+            {
+                PublishDirectMutationTerminal(state, requestId, requestDigest,
+                    ExecutionTimeoutEnvelope(requestId, "Play Mode recovery state is incomplete; outcome is unknown."));
+                object invalidTerminal;
+                return state.TryGetTerminal(DirectMutationTerminalScope, requestId, requestDigest, out invalidTerminal);
+            }
+
+            object terminal;
+            if (!isChanging && isPlaying == enterPlayMode)
+            {
+                var before = (bool)beforeValue;
+                var result = new PlayModeResult
+                {
+                    Changed = enterPlayMode ? !before : before,
+                    IsPlaying = isPlaying,
+                    IsPaused = isPaused
+                };
+                terminal = enterPlayMode
+                    ? (object)new EditorPlayTool.Response { Result = result, State = readState(), PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "editor.play" } } }
+                    : new EditorStopTool.Response { Result = result, State = readState(), PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "editor.stop" } } };
+                PublishDirectMutationTerminal(state, requestId, requestDigest,
+                    UnityCliSerializer.Serialize(ProtocolEnvelopeFactory.Success(requestId, terminal)));
+            }
+            else
+            {
+                if (utcNow < deadline) return false;
+                var code = enterPlayMode ? "E_PLAY_MODE_TERMINAL_NOT_OBSERVED" : "E_EDIT_MODE_TERMINAL_NOT_OBSERVED";
+                var message = enterPlayMode
+                    ? "Play Mode did not reach a stable playing state before the immutable deadline."
+                    : "The Editor did not reach stable Edit Mode before the immutable deadline.";
+                terminal = ProtocolEnvelopeFactory.Error(requestId, code, message, null,
+                    new[] { "Run tools run editor.play-mode.status with the same requestId before deciding whether to submit a new request." });
+                PublishDirectMutationTerminal(state, requestId, requestDigest, UnityCliSerializer.Serialize(terminal));
+            }
+            object published;
+            return state.TryGetTerminal(DirectMutationTerminalScope, requestId, requestDigest, out published);
+        }
+
         /// <summary>绑定本domain正在执行的direct mutation；SessionState只跨本次Editor启动的domain reload存活。</summary>
         private static void BindDirectMutationLease(string requestId, string requestDigest)
         {
@@ -407,6 +628,12 @@ namespace UnityCli
                 && string.Equals(SessionState.GetString(DirectMutationRequestDigestSessionKey, string.Empty), requestDigest, StringComparison.Ordinal);
         }
 
+        private static bool DirectMutationCleanupPendingForIdentity(string requestId, string requestDigest)
+        {
+            return DirectMutationBindingMatches(requestId, requestDigest)
+                && SessionState.GetBool(DirectMutationCleanupPendingSessionKey, false);
+        }
+
         /// <summary>普通 Tool 的 effect 提交只保留 runner 协调语义，不写请求级持久状态。</summary>
         private static object PrepareToolEffect(BridgeRequest request, UnityCliToolCompletionContract contract, object typedInput)
         {
@@ -611,45 +838,113 @@ namespace UnityCli
             return request == null ? null : request.Command;
         }
 
-        /// <summary>queue 只需保守判断资源所有权；解析失败按 mutation 串行，最终错误仍由 coordinator 结构化返回。</summary>
-        private static bool CoordinatedRequestIsMutation(BridgeRequest request)
+        /// <summary>HTTP worker只读取immutable request与已冻结registry；未知或依赖场景现状的分类显式按Mutation关闭。</summary>
+        internal static UnityCliBridgeQueuePolicy.WorkClass QueueRequestWorkClass(BridgeRequest request)
         {
-            try
-            {
-                if (request != null && string.Equals(request.Command, "internal.editor.compile.start", StringComparison.Ordinal))
-                    return request.Execution == null || request.Execution.DryRun != true;
-                var contract = ResolveRequestCompletionContract(request);
-                return RequestRequiresMutation(request, contract);
-            }
-            catch
+            if (request == null) return UnityCliBridgeQueuePolicy.WorkClass.Mutation;
+            var toolName = RequestToolName(request);
+            if (!string.IsNullOrEmpty(toolName) && toolName.StartsWith("scene.", StringComparison.Ordinal))
+                return UnityCliBridgeQueuePolicy.WorkClass.Mutation;
+            UnityCliBridgeQueuePolicy.WorkClass registered;
+            if (CommandRegistry.TryGetQueueClass(request.Command, out registered)) return registered;
+            var contract = ResolveQueueCompletionContract(request);
+            if (contract == null)
+                return IsReadOnlyBridgeCommand(request.Command)
+                    ? UnityCliBridgeQueuePolicy.WorkClass.OrdinaryRead
+                    : UnityCliBridgeQueuePolicy.WorkClass.Mutation;
+            if (request.Execution != null && request.Execution.DryRun == true) return UnityCliBridgeQueuePolicy.WorkClass.OrdinaryRead;
+            if (!contract.Mutation) return UnityCliBridgeQueuePolicy.WorkClass.OrdinaryRead;
+            bool requiresSceneState;
+            var inputMutation = RequestMutationFromImmutableInput(contract.ToolName, RequestBusinessInput(request), out requiresSceneState);
+            return requiresSceneState || inputMutation
+                ? UnityCliBridgeQueuePolicy.WorkClass.Mutation
+                : UnityCliBridgeQueuePolicy.WorkClass.OrdinaryRead;
+        }
+
+        /// <summary>worker只读取内置冻结contract；项目自定义Tool未知时由调用方保守归Mutation。</summary>
+        private static UnityCliToolCompletionContract ResolveQueueCompletionContract(BridgeRequest request)
+        {
+            var toolName = RequestToolName(request);
+            if (IsInstanceCleanupCommand(toolName)) return InstanceCleanupCompletionContract();
+            UnityCliToolCompletionContract contract;
+            if (UnityCliToolCompletionRegistry.TryGet(toolName, out contract)) return contract;
+            return string.Equals(toolName, "code.exec", StringComparison.Ordinal) ? UnityCliToolCompletionRegistry.CodeExec : null;
+        }
+
+        private sealed class DurableMutationBarrierProof
+        {
+            internal UnityCliBridgeQueuePolicy.DurableMutationBarrier State;
+            internal string RequestId;
+            internal string RequestDigest;
+        }
+
+        /// <summary>durable lease三态同时冻结当前owner identity，供锁外control root proof精确绑定。</summary>
+        private static DurableMutationBarrierProof CurrentDurableMutationBarrier(BridgeQueueState state)
+        {
+            string requestId;
+            string requestDigest;
+            if (state == null || !state.TryGetCurrentLeaseOwner(out requestId, out requestDigest))
+                return new DurableMutationBarrierProof { State = UnityCliBridgeQueuePolicy.DurableMutationBarrier.Unreadable };
+            if (string.IsNullOrEmpty(requestId) && string.IsNullOrEmpty(requestDigest))
+                return new DurableMutationBarrierProof { State = UnityCliBridgeQueuePolicy.DurableMutationBarrier.Clear };
+            if (!IsSafeId(requestId) || !IsSha256(requestDigest))
+                return new DurableMutationBarrierProof { State = UnityCliBridgeQueuePolicy.DurableMutationBarrier.Unreadable };
+            return new DurableMutationBarrierProof
             {
-                return true;
-            }
+                State = UnityCliBridgeQueuePolicy.DurableMutationBarrier.Held,
+                RequestId = requestId,
+                RequestDigest = requestDigest
+            };
         }
 
-        /// <summary>descriptor 表示潜在风险；本次 input 没有 setter/action 时按 read 执行。</summary>
+        /// <summary>主线程在pure input裁决后，仅对真正依赖场景现状的幂等分支读取Unity对象。</summary>
         private static bool RequestRequiresMutation(BridgeRequest request, UnityCliToolCompletionContract contract)
         {
             if (request == null || contract == null || !contract.Mutation || (request.Execution != null && request.Execution.DryRun == true)) return false;
-            var name = contract.ToolName;
             var input = RequestBusinessInput(request);
-            if (name == "graphics.reflection-probe") return HasAnyMeaningfulInput(input, "mode", "resolution", "bounces", "hdr", "boxSize", "boxOffset") || CreateProbeNeedsMutation(input, true);
-            if (name == "graphics.light-probe-group") return HasAnyMeaningfulInput(input, "positions") || CreateProbeNeedsMutation(input, false);
+            bool requiresSceneState;
+            var inputMutation = RequestMutationFromImmutableInput(contract.ToolName, input, out requiresSceneState);
+            if (!requiresSceneState) return inputMutation;
+            if (contract.ToolName == "physics.rigidbody") return RigidbodyNeedsMutation(input);
+            if (contract.ToolName == "graphics.reflection-probe") return CreateProbeNeedsMutation(input, true);
+            if (contract.ToolName == "graphics.light-probe-group") return CreateProbeNeedsMutation(input, false);
+            return true;
+        }
+
+        /// <summary>只按immutable JSON字段判断；需要场景现状的幂等分支通过requiresSceneState显式上报。</summary>
+        private static bool RequestMutationFromImmutableInput(string name, IDictionary<string, object> input, out bool requiresSceneState)
+        {
+            requiresSceneState = false;
+            if (name == "graphics.reflection-probe")
+            {
+                if (HasAnyMeaningfulInput(input, "mode", "resolution", "bounces", "hdr", "boxSize", "boxOffset")) return true;
+                requiresSceneState = InputBoolean(input, "create");
+                return false;
+            }
+            if (name == "graphics.light-probe-group")
+            {
+                if (HasAnyMeaningfulInput(input, "positions")) return true;
+                requiresSceneState = InputBoolean(input, "create");
+                return false;
+            }
             if (name == "graphics.skybox-set-properties") return HasAllMeaningfulInput(input, "property", "value");
             if (name == "build.settings.set") return HasAnyInput(input, "apiCompatibilityLevel", "applicationIdentifier", "bundleVersion", "companyId", "productName", "scriptingBackend");
             if (name == "graphics.bake-settings") return HasAnyInput(input, "bakedGI", "bounces", "directSamples", "environmentSamples", "filtering", "indirectSamples", "lightingMode", "realtimeGI");
-            if (name == "graphics.probe-positions") return HasAnyInput(input, "positions");
             if (name == "graphics.quality") return HasAnyInput(input, "anisotropicFiltering", "antiAliasing", "lodBias", "masterTextureLimit", "maximumLODLevel", "qualityLevel", "realtimeReflectionProbes", "shadowDistance", "shadowResolution", "shadows", "softParticles", "vSyncCount");
-            if (name == "graphics.settings") return HasAnyInput(input, "antiAliasing", "lodBias", "masterTextureLimit", "maximumLODLevel", "property", "renderPipeline", "shadowDistance", "vSyncCount", "value");
             if (name == "graphics.pipeline-settings") return HasAnyInput(input, "renderPipeline");
-            if (name == "graphics.pipeline-quality") return HasAnyInput(input, "qualityLevel");
             if (name == "graphics.skybox-set-ambient") return HasAnyMeaningfulInput(input, "ambientEquatorColor", "ambientGroundColor", "ambientSkyColor", "color", "intensity", "mode");
             if (name == "graphics.skybox-set-fog") return HasAnyMeaningfulInput(input, "color", "density", "enabled", "endDistance", "mode", "startDistance");
             if (name == "graphics.skybox-set-reflection") return HasAnyMeaningfulInput(input, "bounces", "intensity", "mode", "resolution");
             if (name == "graphics.scene-debug") return HasAnyInput(input, "drawMode", "shadingMode");
             if (name == "physics.collision-matrix") return HasAllInput(input, "layerA", "layerB", "ignore");
             if (name == "physics.settings") return HasAnyInput(input, "autoSimulation", "bounceThreshold", "defaultContactOffset", "defaultSolverIterations", "defaultSolverVelocityIterations", "gravity", "gravity2d", "property", "queriesHitBackfaces", "queriesHitTriggers", "queriesStartInColliders", "value");
-            if (name == "physics.rigidbody") return !InputBoolean(input, "validate") && (HasAnyMeaningfulInput(input, "angularDrag", "drag", "isKinematic", "mass", "useGravity") || RigidbodyNeedsMutation(input));
+            if (name == "physics.rigidbody")
+            {
+                if (InputBoolean(input, "validate")) return false;
+                if (HasAnyMeaningfulInput(input, "angularDrag", "drag", "isKinematic", "mass", "useGravity")) return true;
+                requiresSceneState = true;
+                return false;
+            }
             if (name == "physics.simulation") return InputBoolean(input, "simulate");
             if (name == "texture.import-settings") return HasAnyInput(input, "alphaIsTransparency", "compression", "filterMode", "maxTextureSize", "mipmap", "readable", "sRGB", "textureType", "type", "wrapMode");
             if (name == "profiler.deep") return HasAnyInput(input, "enabled");
@@ -740,8 +1035,11 @@ namespace UnityCli
         /// <summary>Context/catalog/health 类请求没有 business mutation，不得创建 request journal。</summary>
         private static bool IsReadOnlyBridgeCommand(string command)
         {
-            if (IsEditorStateSnapshotCommand(command)) return true;
-            return string.Equals(command, "project-tool.list", StringComparison.Ordinal)
+            if (IsEditorStateSnapshotCommand(command) || IsDoctorDiagnosticCommand(command)) return true;
+            return IsProjectToolCatalogReadCommand(command)
+                || string.Equals(command, "runtime-tool.groups", StringComparison.Ordinal)
+                || string.Equals(command, "runtime-tool.summary", StringComparison.Ordinal)
+                || string.Equals(command, "runtime-tool.describe", StringComparison.Ordinal)
                 || string.Equals(command, "runtime-tool.list", StringComparison.Ordinal);
         }