@alpsckr/unitycli 0.4.2 → 0.4.4

package/unitypkg/Editor/Infrastructure/UnityCliDoctorDiagnostics.cs

@@ -0,0 +1,220 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Reflection;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        private const string DoctorBusinessCommand = "internal.doctor.business";
+        private const string DoctorCatalogCommand = "internal.doctor.catalog";
+        private const string DoctorCompileCommand = "internal.doctor.compile";
+        private const string DoctorCatalogIdentity = "unity-cli-immutable-domain-catalog";
+
+        private static void RegisterDoctorDiagnosticCommands(BridgeCommandRegistry registry)
+        {
+            registry.Register<UnityCli.Protocol.BridgeRequest>("internal.doctor.business", "internal", false, 30000,
+                (request, cancellationToken) => new ValueTask<object>(DoctorBusinessDiagnostic(cancellationToken)));
+            registry.Register<UnityCli.Protocol.BridgeRequest>("internal.doctor.catalog", "internal", false, 30000,
+                (request, cancellationToken) => new ValueTask<object>(DoctorCatalogDiagnostic(cancellationToken)));
+            registry.Register<UnityCli.Protocol.BridgeRequest>("internal.doctor.compile", "internal", false, 30000,
+                (request, cancellationToken) => new ValueTask<object>(DoctorCompileDiagnostic(cancellationToken)));
+        }
+
+        /// <summary>业务诊断必须通过正常 admission 和主线程队列，不能替代 transport 或 pulse 结论。</summary>
+        private static object DoctorBusinessDiagnostic(CancellationToken cancellationToken)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var scene = SceneManager.GetActiveScene();
+            return new Dictionary<string, object>
+            {
+                { "projectPath", ProjectRoot() },
+                { "sceneLoaded", scene.IsValid() && scene.isLoaded },
+                { "activeScenePath", scene.path ?? string.Empty },
+                { "playMode", EditorApplication.isPlaying },
+                { "accepted", true }
+            };
+        }
+
+        /// <summary>只投影唯一 published snapshot 的 aggregate；读取失败保持 E_TOOL_REGISTRY_UNHEALTHY。</summary>
+        private static object DoctorCatalogDiagnostic(CancellationToken cancellationToken)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var catalog = ProjectToolCatalogSnapshotReader.Read();
+            return new Dictionary<string, object>
+            {
+                { "identity", DoctorCatalogIdentity },
+                { "toolCount", (long)catalog.ToolCount },
+                { "providerCounts", new Dictionary<string, object>
+                    {
+                        { "builtIn", (long)catalog.BuiltInToolCount },
+                        { "extension", (long)catalog.ExtensionToolCount },
+                        { "projectInterface", (long)catalog.ProjectInterfaceToolCount },
+                        { "officialAttribute", (long)catalog.OfficialAttributeToolCount }
+                    }
+                },
+                { "publicationDiagnostics", new Dictionary<string, object>
+                    {
+                        { "assemblyCount", (long)catalog.AssemblyCount },
+                        { "providerAssemblyCount", (long)catalog.ProviderAssemblyCount },
+                        { "elapsedMilliseconds", catalog.ElapsedMilliseconds },
+                        { "discoveryPassCount", (long)catalog.DiscoveryPassCount },
+                        { "providerMetadataReadCount", (long)catalog.ProviderMetadataReadCount },
+                        { "aggregateSuccessLogCount", (long)catalog.AggregateSuccessLogCount }
+                    }
+                }
+            };
+        }
+
+        /// <summary>编译诊断独立于 catalog 和业务 admission，并保持条目、时间与字节上限。</summary>
+        private static object DoctorCompileDiagnostic(CancellationToken cancellationToken)
+        {
+            const int maxScannedEntries = 5000;
+            const int maxScanMilliseconds = 50;
+            const int maxCompileErrorBytes = 64 * 1024;
+            const int maxCompileErrorLineBytes = 4096;
+            var scanTimer = System.Diagnostics.Stopwatch.StartNew();
+            var compiling = EditorApplication.isCompiling;
+            var scanComplete = true;
+            var compileErrorCount = 0L;
+            var compileErrorsTruncated = false;
+            var compileErrorBytes = 0;
+            var errors = new List<string>();
+
+            try
+            {
+                var logEntriesType = FindType("UnityEditor.LogEntries") ?? FindType("UnityEditorInternal.LogEntries");
+                if (logEntriesType == null) scanComplete = false;
+                else
+                {
+                    var flags = BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic;
+                    var start = logEntriesType.GetMethod("StartGettingEntries", flags);
+                    var end = logEntriesType.GetMethod("EndGettingEntries", flags);
+                    var count = logEntriesType.GetMethod("GetCount", flags);
+                    var getEntry = logEntriesType.GetMethod("GetEntryInternal", flags);
+                    var getLines = logEntriesType.GetMethod("GetLinesAndModeFromEntryInternal", flags)
+                        ?? logEntriesType.GetMethod("GetLinesAndModeInternal", flags);
+                    if ((start == null && count == null) || (getEntry == null && getLines == null)) scanComplete = false;
+                    var total = start != null
+                        ? Convert.ToInt32(start.Invoke(null, Type.EmptyTypes), CultureInfo.InvariantCulture)
+                        : count == null ? 0 : Convert.ToInt32(count.Invoke(null, Type.EmptyTypes), CultureInfo.InvariantCulture);
+                    try
+                    {
+                        var scannedEntries = 0;
+                        for (var index = total - 1; index >= 0; index--)
+                        {
+                            cancellationToken.ThrowIfCancellationRequested();
+                            if (scannedEntries >= maxScannedEntries || scanTimer.ElapsedMilliseconds >= maxScanMilliseconds)
+                            {
+                                scanComplete = false;
+                                compileErrorsTruncated = true;
+                                break;
+                            }
+                            scannedEntries++;
+                            string line = null;
+                            var mode = 0;
+                            try
+                            {
+                                if (getLines != null && getLines.GetParameters().Length == 4)
+                                {
+                                    var args = new object[] { index, 1, 0, null };
+                                    getLines.Invoke(null, args);
+                                    mode = Convert.ToInt32(args[2], CultureInfo.InvariantCulture);
+                                    line = args[3] as string;
+                                }
+                                else if (getEntry != null && getEntry.GetParameters().Length == 4)
+                                {
+                                    var args = new object[] { index, null, null, null };
+                                    getEntry.Invoke(null, args);
+                                    line = args[1] as string;
+                                    mode = args[2] == null ? 0 : Convert.ToInt32(args[2], CultureInfo.InvariantCulture);
+                                }
+                                else if (getLines != null && getLines.GetParameters().Length == 2)
+                                {
+                                    var args = new object[] { index, null };
+                                    getLines.Invoke(null, args);
+                                    line = args[1] as string;
+                                }
+                            }
+                            catch { scanComplete = false; }
+                            if (string.IsNullOrEmpty(line)) { scanComplete = false; continue; }
+                            var compilerText = line.IndexOf("CS", StringComparison.OrdinalIgnoreCase) >= 0
+                                && line.IndexOf("error", StringComparison.OrdinalIgnoreCase) >= 0;
+                            if (!compilerText && ((mode & 1) == 0 || line.IndexOf("Compile", StringComparison.OrdinalIgnoreCase) < 0)) continue;
+
+                            compileErrorCount++;
+                            var boundedLine = DoctorBoundedUtf8(line, maxCompileErrorLineBytes);
+                            var boundedBytes = Encoding.UTF8.GetByteCount(boundedLine);
+                            if (errors.Count < 20 && compileErrorBytes + boundedBytes <= maxCompileErrorBytes)
+                            {
+                                errors.Add(boundedLine);
+                                compileErrorBytes += boundedBytes;
+                                if (boundedLine.Length != line.Length) compileErrorsTruncated = true;
+                            }
+                            else compileErrorsTruncated = true;
+                        }
+                    }
+                    finally
+                    {
+                        if (start != null && end != null) end.Invoke(null, Type.EmptyTypes);
+                    }
+                }
+            }
+            catch (OperationCanceledException) { throw; }
+            catch (Exception exception)
+            {
+                scanComplete = false;
+                var readFailure = "Failed to read compile errors: " + exception.GetType().Name;
+                if (errors.Count < 20 && compileErrorBytes + Encoding.UTF8.GetByteCount(readFailure) <= maxCompileErrorBytes) errors.Insert(0, readFailure);
+                else compileErrorsTruncated = true;
+            }
+
+            if (!scanComplete) compileErrorsTruncated = true;
+            var nextActions = new List<string>();
+            if (!scanComplete) nextActions.Add("Inspect the Unity Console because compile diagnostics could not be scanned completely.");
+            if (compileErrorCount > 0) nextActions.Add("Fix the listed compiler errors, then let Unity finish recompiling.");
+            if (compiling) nextActions.Add("Wait for Unity to finish compiling, then run doctor again.");
+            return new Dictionary<string, object>
+            {
+                { "compiling", compiling },
+                { "scanComplete", scanComplete },
+                { "hasCompileErrors", compileErrorCount > 0 },
+                { "compileErrorCount", compileErrorCount },
+                { "compileErrorsTruncated", compileErrorsTruncated },
+                { "compileErrors", errors },
+                { "nextActions", nextActions }
+            };
+        }
+
+        private static string DoctorBoundedUtf8(string value, int maxBytes)
+        {
+            if (string.IsNullOrEmpty(value) || Encoding.UTF8.GetByteCount(value) <= maxBytes) return value ?? string.Empty;
+            var length = Math.Min(value.Length, maxBytes);
+            while (length > 0 && Encoding.UTF8.GetByteCount(value.Substring(0, length)) > maxBytes) length--;
+            if (length > 0 && char.IsHighSurrogate(value[length - 1])) length--;
+            return value.Substring(0, length);
+        }
+
+        private static bool IsDoctorDiagnosticCommand(string command)
+        {
+            return string.Equals(command, DoctorBusinessCommand, StringComparison.Ordinal)
+                || string.Equals(command, DoctorCatalogCommand, StringComparison.Ordinal)
+                || string.Equals(command, DoctorCompileCommand, StringComparison.Ordinal);
+        }
+
+        private static bool IsDoctorAdmissionBypassCommand(string command)
+        {
+            return string.Equals(command, DoctorCatalogCommand, StringComparison.Ordinal)
+                || string.Equals(command, DoctorCompileCommand, StringComparison.Ordinal);
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliDurableStatusCoordinator.cs

@@ -0,0 +1,118 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityCli.Protocol;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>域专用公开status Tool共用的只读Bridge协调器；公开输入不包含内部digest或scope。</summary>
+        internal static class UnityCliDurableStatusCoordinator
+        {
+            internal const string AssetRefreshCommand = "internal.asset.refresh.public-status";
+            internal const string BuildPlayerCommand = "internal.build.player.public-status";
+            internal const string EditorPlayModeCommand = "internal.editor.play-mode.public-status";
+            internal const string PackageInstallCommand = "internal.package.install.public-status";
+            internal const string PackageRemoveCommand = "internal.package.remove.public-status";
+            internal const string TestRunCommand = "internal.test.run.public-status";
+
+            internal static bool IsCommand(string command)
+            {
+                return command == AssetRefreshCommand || command == BuildPlayerCommand || command == EditorPlayModeCommand
+                    || command == PackageInstallCommand || command == PackageRemoveCommand || command == TestRunCommand;
+            }
+
+            internal static void Register(BridgeCommandRegistry registry)
+            {
+                registry.Register<BridgeRequest>("internal.asset.refresh.public-status", "internal", false, 30000, CoordinatorOwned, UnityCliBridgeQueuePolicy.WorkClass.SafeStatus);
+                registry.Register<BridgeRequest>("internal.build.player.public-status", "internal", false, 30000, CoordinatorOwned, UnityCliBridgeQueuePolicy.WorkClass.SafeStatus);
+                registry.Register<BridgeRequest>("internal.editor.play-mode.public-status", "internal", false, 30000, CoordinatorOwned, UnityCliBridgeQueuePolicy.WorkClass.SafeStatus);
+                registry.Register<BridgeRequest>("internal.package.install.public-status", "internal", false, 30000, CoordinatorOwned, UnityCliBridgeQueuePolicy.WorkClass.SafeStatus);
+                registry.Register<BridgeRequest>("internal.package.remove.public-status", "internal", false, 30000, CoordinatorOwned, UnityCliBridgeQueuePolicy.WorkClass.SafeStatus);
+                registry.Register<BridgeRequest>("internal.test.run.public-status", "internal", false, 30000, CoordinatorOwned, UnityCliBridgeQueuePolicy.WorkClass.SafeStatus);
+            }
+
+            private static ValueTask<object> CoordinatorOwned(BridgeRequest request, CancellationToken cancellationToken)
+            {
+                throw new InvalidOperationException("Durable status is coordinator-owned.");
+            }
+
+            internal static Task<string> Execute(BridgeRequest request, CancellationToken cancellationToken)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                try
+                {
+                    var args = request.DeserializeArgs<Args>();
+                    if (args == null || !IsSafeRequestId(args.RequestId))
+                        throw new BridgeCommandException("E_SCHEMA_INVALID", "requestId is required and must be a safe root request identity.");
+                    object data;
+                    switch (request.Command)
+                    {
+                        case AssetRefreshCommand: data = ReadScope("asset-refresh", args.RequestId); break;
+                        case BuildPlayerCommand: data = ReadScope("build", args.RequestId); break;
+                        case EditorPlayModeCommand: data = ReadEditorPlayModeStatus(args.RequestId); break;
+                        case PackageInstallCommand: data = UnityCliPackageResolveCoordinator.ReadPublicStatus(args.RequestId, "install"); break;
+                        case PackageRemoveCommand: data = UnityCliPackageResolveCoordinator.ReadPublicStatus(args.RequestId, "remove"); break;
+                        case TestRunCommand: data = ReadScope("test-run", args.RequestId); break;
+                        default: throw new BridgeCommandException("E_TOOL_NOT_FOUND", "Durable status command is not registered.");
+                    }
+                    return Task.FromResult(UnityCliSerializer.Serialize(ProtocolEnvelopeFactory.Success(request.RequestId, data)));
+                }
+                catch (BridgeCommandException exception)
+                {
+                    return Task.FromResult(SerializeBridgeExceptionEnvelope(request.RequestId, exception));
+                }
+            }
+
+            /// <summary>先读有界terminal cache，再读单scope active journal；读取不获取lease且不推进operation。</summary>
+            internal static object ReadScope(string scope, string requestId)
+            {
+                string requestDigest;
+                string statusDomain;
+                object terminal;
+                if (UnityCliActiveOperation.TryGetTerminalByRequestId(scope, requestId, out requestDigest, out statusDomain, out terminal))
+                    return Terminal(requestId, terminal);
+                var root = UnityCliActiveOperation.Load(scope);
+                if (root == null || !string.Equals(Text(root, "requestId"), requestId, StringComparison.Ordinal))
+                    throw new BridgeCommandException("E_REQUEST_NOT_FOUND", "The requested durable operation was not found in this Editor session.");
+                return Running(requestId, Text(root, "phase"));
+            }
+
+            internal static object Running(string requestId, string phase)
+            {
+                return new Dictionary<string, object>
+                {
+                    { "requestId", requestId }, { "state", "running" }, { "phase", string.IsNullOrWhiteSpace(phase) ? "accepted" : phase }
+                };
+            }
+
+            internal static object Terminal(string requestId, object envelope)
+            {
+                return new Dictionary<string, object>
+                {
+                    { "requestId", requestId }, { "state", "completed" }, { "terminalEnvelope", envelope }
+                };
+            }
+
+            private static string Text(Dictionary<string, object> value, string key)
+            {
+                object item;
+                return value != null && value.TryGetValue(key, out item) ? item as string : null;
+            }
+
+            private static bool IsSafeRequestId(string requestId)
+            {
+                if (string.IsNullOrWhiteSpace(requestId) || requestId.Length > 200) return false;
+                foreach (var character in requestId)
+                    if (!(char.IsLetterOrDigit(character) || character == '-' || character == '_' || character == '.' || character == ':')) return false;
+                return true;
+            }
+
+            private sealed class Args { public string RequestId { get; set; } }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliEditorStateSnapshot.cs

@@ -52,7 +52,8 @@ namespace UnityCli
                         { "progress", SnapshotProgress() },
                         { "blockers", new List<object>() }
                     });
-                });
+                },
+                UnityCliBridgeQueuePolicy.WorkClass.SafeStatus);
         }
 
         private static bool IsEditorStateSnapshotCommand(string command)

package/unitypkg/Editor/Infrastructure/UnityCliHierarchyPager.cs

@@ -0,0 +1,203 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>基于 next GameObject instance id 的前序游标；续页只做 O(depth) 定位，不重扫旧页面。</summary>
+    internal static class UnityCliHierarchyPager
+    {
+        /// <summary>单场景遍历只获取一次 root snapshot；子节点始终通过 child-at 向前推进。</summary>
+        internal sealed class Traversal
+        {
+            private readonly Scene scene;
+            private readonly GameObject boundaryParent;
+            private readonly Transform boundary;
+            private readonly int maxDepth;
+            private GameObject[] roots;
+
+            internal Traversal(Scene scene, GameObject boundaryParent, int maxDepth, UnityCliRequestBudget budget)
+            {
+                this.scene = scene;
+                this.boundaryParent = boundaryParent;
+                if (boundaryParent != null && !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                boundary = boundaryParent == null ? null : boundaryParent.transform;
+                this.maxDepth = maxDepth;
+            }
+
+            internal Scene Scene { get { return scene; } }
+
+            internal GameObject First(UnityCliRequestBudget budget)
+            {
+                if (boundaryParent != null)
+                {
+                    if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    var childCount = boundary.childCount;
+                    if (childCount == 0) return null;
+                    if (!budget.TryConsumeGetters(2)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    return boundary.GetChild(0).gameObject;
+                }
+                roots = roots ?? UnityCliBridge.ObjectRefResolver.BoundedSceneRoots(scene, budget);
+                return roots.Length == 0 ? null : roots[0];
+            }
+
+            internal GameObject Next(GameObject current, UnityCliRequestBudget budget)
+            {
+                if (current == null) return null;
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var currentTransform = current.transform;
+                var relativeDepth = Depth(currentTransform, boundary, budget);
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                if (relativeDepth < maxDepth && currentTransform.childCount > 0)
+                {
+                    if (!budget.TryConsumeGetters(2)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    return currentTransform.GetChild(0).gameObject;
+                }
+                var cursor = currentTransform;
+                while (cursor != null && cursor != boundary)
+                {
+                    if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    var parent = cursor.parent;
+                    if (parent != null)
+                    {
+                        if (!budget.TryConsumeGetter() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                        var sibling = cursor.GetSiblingIndex() + 1;
+                        if (sibling < parent.childCount)
+                        {
+                            if (!budget.TryConsumeGetters(2)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                            return parent.GetChild(sibling).gameObject;
+                        }
+                        cursor = parent;
+                        continue;
+                    }
+                    if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    var rootSibling = cursor.GetSiblingIndex() + 1;
+                    roots = roots ?? UnityCliBridge.ObjectRefResolver.BoundedSceneRoots(scene, budget);
+                    return rootSibling < roots.Length ? roots[rootSibling] : null;
+                }
+                return null;
+            }
+        }
+
+        /// <summary>加载场景集合在请求开始时冻结，每个场景 root array 最多 materialize 一次。</summary>
+        internal sealed class LoadedSceneTraversal
+        {
+            private readonly List<Scene> scenes = new List<Scene>();
+            private readonly List<Traversal> traversals = new List<Traversal>();
+            private readonly Dictionary<int, int> sceneIndices = new Dictionary<int, int>();
+
+            internal LoadedSceneTraversal(UnityCliRequestBudget budget, int excludedSceneHandle = 0)
+            {
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var sceneCount = SceneManager.sceneCount;
+                for (var sceneIndex = 0; sceneIndex < sceneCount; sceneIndex++)
+                {
+                    if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    var scene = SceneManager.GetSceneAt(sceneIndex);
+                    if (!budget.TryConsumeGetters(2)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    if (!scene.isLoaded || scene.handle == excludedSceneHandle) continue;
+                    var handle = scene.handle;
+                    sceneIndices[handle] = scenes.Count;
+                    scenes.Add(scene);
+                    traversals.Add(null);
+                }
+            }
+
+            internal GameObject First(UnityCliRequestBudget budget)
+            {
+                for (var index = 0; index < traversals.Count; index++)
+                {
+                    var first = GetTraversal(index, budget).First(budget);
+                    if (first != null) return first;
+                }
+                return null;
+            }
+
+            internal GameObject Next(GameObject current, UnityCliRequestBudget budget)
+            {
+                if (current == null) return null;
+                int index;
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                if (!sceneIndices.TryGetValue(current.scene.handle, out index)) return null;
+                var next = GetTraversal(index, budget).Next(current, budget);
+                if (next != null) return next;
+                for (index += 1; index < traversals.Count; index += 1)
+                {
+                    next = GetTraversal(index, budget).First(budget);
+                    if (next != null) return next;
+                }
+                return null;
+            }
+
+            private Traversal GetTraversal(int index, UnityCliRequestBudget budget)
+            {
+                var traversal = traversals[index];
+                if (traversal != null) return traversal;
+                traversal = new Traversal(scenes[index], null, int.MaxValue, budget);
+                traversals[index] = traversal;
+                return traversal;
+            }
+        }
+
+        internal static int Depth(Transform value, Transform boundary, UnityCliRequestBudget budget)
+        {
+            var depth = 0;
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var current = value.parent;
+            while (current != null && current != boundary)
+            {
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                depth++;
+                current = current.parent;
+            }
+            return depth;
+        }
+
+        internal static string Cursor(string scope, string generation, string phase, GameObject next, UnityCliRequestBudget budget)
+        {
+            if (next == null) return null;
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            return UnityCliContinuationToken.Create(scope, generation, (phase ?? "scene") + ":" + next.GetInstanceID().ToString(CultureInfo.InvariantCulture));
+        }
+
+        internal static GameObject ResolveCursor(string token, string scope, string generation, UnityCliRequestBudget budget, out string phase)
+        {
+            phase = null;
+            string position;
+            if (!UnityCliContinuationToken.TryParse(token, scope, generation, out position)) throw Stale();
+            var separator = position.IndexOf(':');
+            int instanceId;
+            if (separator <= 0 || !int.TryParse(position.Substring(separator + 1), NumberStyles.Integer, CultureInfo.InvariantCulture, out instanceId)) throw Stale();
+            phase = position.Substring(0, separator);
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var value = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
+            if (value == null) throw Stale();
+            return value;
+        }
+
+        internal static string Path(GameObject gameObject, UnityCliRequestBudget budget)
+        {
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var value = gameObject.name;
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var current = gameObject.transform.parent;
+            while (current != null)
+            {
+                if (!budget.TryConsumeNode() || !budget.TryConsumeGetter() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                value = current.name + "/" + value;
+                current = current.parent;
+            }
+            return value;
+        }
+
+        internal static UnityCliBridge.BridgeCommandException Stale()
+        {
+            return new UnityCliBridge.BridgeCommandException("E_CONTINUATION_STALE", "The hierarchy continuation no longer identifies the same Unity generation or selector.", "Start a new hierarchy read without cursor.");
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliInstanceCleanup.cs

@@ -263,7 +263,8 @@ namespace UnityCli
                     };
                     RecordDirectCompletionEvidence(request.RequestId, "internal.instances.prune", InstanceCleanupCompletion, result);
                     return new System.Threading.Tasks.ValueTask<object>(result);
-                });
+                },
+                UnityCliBridgeQueuePolicy.WorkClass.Mutation);
         }
 
         private static bool IsInstanceCleanupCommand(string command)