@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Infrastructure/UnityCliJson.cs

@@ -0,0 +1,155 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Net;
+using System.Text;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        private static List<object> CapabilitiesData()
+        {
+            return new List<object> {
+                CapabilityData("camera", CameraCommands), CapabilityData("scene", SceneCommands), CapabilityData("go", GameObjectCommands), CapabilityData("asset", AssetCommands),
+                CapabilityData("diagnose", DiagnoseCommands), CapabilityData("screenshot", ScreenshotCommands), CapabilityData("prefab", PrefabCommands), CapabilityData("ui", UiCommands),
+                CapabilityData("material", MaterialCommands), CapabilityData("graphics", GraphicsCommands), CapabilityData("physics", PhysicsCommands), CapabilityData("scriptable-object", ScriptableObjectCommands),
+                CapabilityData("profiler", ProfilerCommands), CapabilityData("animation", AnimationCommands), CapabilityData("shader", ShaderCommands), CapabilityData("texture", TextureCommands),
+                CapabilityData("editor", EditorCommands), CapabilityData("code", CodeCommands), CapabilityData("project-tool", ProjectToolCommands), CapabilityData("runtime-tool", RuntimeToolCommands),
+                CapabilityData("extension", ExtensionCommands)
+            };
+        }
+
+        private static bool IsMutatingCommand(string command) => CommandRegistry.IsMutating(command);
+
+        private static Dictionary<string, object> CapabilityData(string domain, string[] commands)
+        {
+            return new Dictionary<string, object> { { "domain", domain }, { "route", "POST /bridge/execute" }, { "commands", (commands ?? Array.Empty<string>()).Cast<object>().ToList() } };
+        }
+
+        private static string HierarchyPath(GameObject gameObject)
+        {
+            var names = new Stack<string>();
+            var current = gameObject.transform;
+            while (current != null) { names.Push(current.name); current = current.parent; }
+            return string.Join("/", names.ToArray());
+        }
+
+        /// <summary>读取 HTTP 收到的 exact bytes；chunked body 同样受 1 MiB hard limit 约束。</summary>
+        private static byte[] ReadBodyBytes(HttpListenerRequest request)
+        {
+            const int maximumBytes = 1024 * 1024;
+            using (var stream = request.InputStream)
+            {
+                if (request.ContentLength64 >= 0)
+                {
+                    var length = request.ContentLength64;
+                    if (length > maximumBytes) throw new InvalidOperationException("Bridge request body is too large.");
+                    var bytes = new byte[(int)length];
+                    var offset = 0;
+                    while (offset < bytes.Length)
+                    {
+                        var read = stream.Read(bytes, offset, bytes.Length - offset);
+                        if (read <= 0) throw new EndOfStreamException("Request body ended before Content-Length bytes were read.");
+                        offset += read;
+                    }
+                    return bytes;
+                }
+                using (var buffer = new MemoryStream())
+                {
+                    var chunk = new byte[8192];
+                    for (;;)
+                    {
+                        var read = stream.Read(chunk, 0, chunk.Length);
+                        if (read <= 0) break;
+                        if (buffer.Length + read > maximumBytes) throw new InvalidOperationException("Bridge request body is too large.");
+                        buffer.Write(chunk, 0, read);
+                    }
+                    return buffer.ToArray();
+                }
+            }
+        }
+
+        /// <summary>协议只接受无 BOM 的 strict UTF-8；digest 仍使用解码前 exact bytes。</summary>
+        private static string DecodeRequestBody(byte[] bytes)
+        {
+            if (bytes == null) throw new ArgumentNullException("bytes");
+            if (bytes.Length >= 3 && bytes[0] == 0xef && bytes[1] == 0xbb && bytes[2] == 0xbf)
+                throw new FormatException("Bridge request body must not contain a UTF-8 BOM.");
+            return new UTF8Encoding(false, true).GetString(bytes);
+        }
+
+        // HTTP 边界接收最终 JSON response body，不在业务 helper 中拼接 JSON。
+        private static void WriteJson(HttpListenerContext context, string json, int statusCode)
+        {
+            try
+            {
+                var bytes = Encoding.UTF8.GetBytes(json);
+                context.Response.StatusCode = statusCode;
+                context.Response.ContentType = "application/json; charset=utf-8";
+                // transport attestation 由 supervisor 消费，禁止写入公开 business envelope。
+                context.Response.Headers["x-unity-cli-instance-id"] = InstanceId();
+                context.Response.Headers["x-unity-cli-session-id"] = EditorSessionId();
+                context.Response.Headers["x-unity-cli-target"] = "editor";
+                context.Response.Headers["x-unity-cli-listener-id"] = ListenerId;
+                context.Response.Headers["x-unity-cli-listener-generation"] = CurrentListenerGeneration().ToString(CultureInfo.InvariantCulture);
+                context.Response.ContentLength64 = bytes.Length;
+                context.Response.OutputStream.Write(bytes, 0, bytes.Length);
+                context.Response.OutputStream.Close();
+            }
+            catch (Exception exception) { WriteLog("write_json_failed " + exception.GetType().Name + ": " + exception.Message); }
+        }
+
+        private static void TryWriteSerializeErrorEnvelope(HttpListenerContext context, string code, string message, string nextAction)
+        {
+            try { WriteJson(context, SerializeErrorEnvelope(code, message, nextAction), 200); }
+            catch (Exception exception) { WriteLog("try_write_error_json_failed " + exception.GetType().Name + ": " + exception.Message); }
+        }
+
+        private static string SerializeSuccessEnvelope(object data)
+        {
+            return UnityCliSerializer.Serialize(UnityCli.Protocol.ProtocolEnvelopeFactory.Success(string.Empty, data));
+        }
+
+        private static string SerializeTransientErrorEnvelope(string requestId, string code, string message, string nextAction, int retryAfterMs)
+        {
+            return UnityCliSerializer.Serialize(UnityCli.Protocol.ProtocolEnvelopeFactory.Error(requestId, code, message, nextActions: new[] { nextAction }, transient: true, retryAfterMs: retryAfterMs));
+        }
+
+        private static string SerializeErrorEnvelope(string code, string message, string nextAction)
+        {
+            return UnityCliSerializer.Serialize(UnityCli.Protocol.ProtocolEnvelopeFactory.Error(string.Empty, code, message, nextActions: string.IsNullOrWhiteSpace(nextAction) ? Array.Empty<string>() : new[] { nextAction }));
+        }
+
+        private static string SerializeBridgeExceptionEnvelope(string requestId, BridgeCommandException exception)
+        {
+            return UnityCliSerializer.Serialize(UnityCli.Protocol.ProtocolEnvelopeFactory.Error(requestId, exception.Code, exception.Message, exception.Details, exception.NextActions, exception.Transient, exception.RetryAfterMs > 0 ? (double?)exception.RetryAfterMs : null));
+        }
+
+        private static string TargetAmbiguousSerializeErrorEnvelope(string label, string target, TargetResolution resolution, string nextAction)
+        {
+            var details = new Dictionary<string, object> { { "label", label }, { "target", target }, { "count", resolution.Matches.Count }, { "matches", TargetMatchesData(resolution.Matches) } };
+            return UnityCliSerializer.Serialize(UnityCli.Protocol.ProtocolEnvelopeFactory.Error(string.Empty, "E_TARGET_AMBIGUOUS", "Multiple targets matched.", details, new[] { nextAction }));
+        }
+
+        private static List<object> TargetMatchesData(List<GameObject> matches)
+        {
+            var items = new List<object>();
+            var limit = Math.Min(matches.Count, 10);
+            for (var index = 0; index < limit; index++)
+            {
+                var gameObject = matches[index];
+                items.Add(new Dictionary<string, object> { { "id", (long)gameObject.GetInstanceID() }, { "name", gameObject.name }, { "path", HierarchyPath(gameObject) }, { "components", ComponentNamesData(gameObject) } });
+            }
+            return items;
+        }
+
+        // 仅供文本日志使用，保持既有小写布尔格式，不承担 JSON 构造职责。
+        private static string Bool(bool value) => value ? "true" : "false";
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliLargeOutput.cs

@@ -0,0 +1,128 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        private const int InlineImageMaxBytes = 512 * 1024;
+
+        /// <summary>解析统一分页大小，避免大列表默认返回过多条目。</summary>
+        private static int LargeOutputPageSize(UnityCli.Protocol.BridgeRequest request, int fallback, int max)
+        {
+            return Math.Max(1, Math.Min(request.IntArg("pageSize", fallback), max));
+        }
+
+        /// <summary>解析统一分页游标，负数游标按 0 处理。</summary>
+        private static int LargeOutputCursor(UnityCli.Protocol.BridgeRequest request)
+        {
+            return Math.Max(0, request.IntArg("cursor", 0));
+        }
+
+        // 分页元数据保持为 typed 数据，最终 response 统一在协议层序列化。
+        private static Dictionary<string, object> PageInfoData(int pageSize, int cursor, int totalCount, int returnedCount)
+        {
+            var next = cursor + returnedCount < totalCount ? (object)(long)(cursor + returnedCount) : null;
+            return new Dictionary<string, object>
+            {
+                { "total", (long)totalCount },
+                { "totalCount", (long)totalCount },
+                { "returnedCount", (long)returnedCount },
+                { "pageSize", (long)pageSize },
+                { "cursor", (long)cursor },
+                { "nextCursor", next },
+                { "hasMore", next != null },
+                { "truncated", next != null }
+            };
+        }
+
+        /// <summary>通用文本筛选；query 为空时视为匹配。</summary>
+        private static bool LargeOutputTextMatches(string query, params string[] values)
+        {
+            if (string.IsNullOrEmpty(query)) return true;
+            foreach (var value in values ?? new string[0])
+            {
+                if (!string.IsNullOrEmpty(value) && value.IndexOf(query, StringComparison.OrdinalIgnoreCase) >= 0) return true;
+            }
+            return false;
+        }
+
+        /// <summary>判断 GameObject 是否拥有指定 Component 类型；空 componentType 表示不过滤。</summary>
+        private static bool LargeOutputComponentMatches(GameObject gameObject, string componentType)
+        {
+            if (gameObject == null || string.IsNullOrEmpty(componentType)) return true;
+            var resolved = ResolveComponentType(componentType);
+            if (resolved != null) return gameObject.GetComponent(resolved) != null;
+            foreach (var component in gameObject.GetComponents<Component>())
+            {
+                if (LargeOutputComponentTypeMatches(component, componentType)) return true;
+            }
+            return false;
+        }
+
+        /// <summary>判断单个 Component 是否匹配类型筛选；空 componentType 表示不过滤。</summary>
+        private static bool LargeOutputComponentTypeMatches(Component component, string componentType)
+        {
+            if (string.IsNullOrEmpty(componentType)) return true;
+            if (component == null) return string.Equals(componentType, "MissingScript", StringComparison.OrdinalIgnoreCase);
+            var type = component.GetType();
+            return string.Equals(type.Name, componentType, StringComparison.OrdinalIgnoreCase)
+                || string.Equals(type.FullName, componentType, StringComparison.OrdinalIgnoreCase)
+                || type.FullName.IndexOf(componentType, StringComparison.OrdinalIgnoreCase) >= 0;
+        }
+
+        /// <summary>返回轻量组件类型摘要，供层级节点默认输出。</summary>
+        private static List<object> ComponentTypesData(GameObject gameObject)
+        {
+            var types = new List<object>();
+            foreach (var component in gameObject.GetComponents<Component>()) types.Add(component == null ? "MissingScript" : component.GetType().Name);
+            return types;
+        }
+
+        // 图片字段与告警直接写入业务数据，避免把局部 JSON 再嵌入 response。
+        private static void AppendInlineScreenshotBytes(Dictionary<string, object> data, UnityCli.Protocol.BridgeRequest request, byte[] bytes, int width, int height, string mimeType = "image/png")
+        {
+            if (!request.BoolArg("inlineBase64", false) || bytes == null || bytes.Length == 0) return;
+            if (bytes.Length > InlineImageMaxBytes)
+            {
+                AddInlineScreenshotTooLargeWarning(data, bytes.Length);
+                return;
+            }
+            data["imageBase64"] = Convert.ToBase64String(bytes);
+            data["imageWidth"] = (long)width;
+            data["imageHeight"] = (long)height;
+            data["imageMimeType"] = mimeType;
+        }
+
+        private static bool ShouldInlineScreenshotBase64(Dictionary<string, object> data, string imageBase64)
+        {
+            if (string.IsNullOrEmpty(imageBase64)) return false;
+            var approximateBytes = (long)Math.Ceiling(imageBase64.Length * 3.0 / 4.0);
+            if (approximateBytes <= InlineImageMaxBytes) return true;
+            AddInlineScreenshotTooLargeWarning(data, approximateBytes);
+            return false;
+        }
+
+        private static void AddInlineScreenshotTooLargeWarning(Dictionary<string, object> data, long sizeBytes)
+        {
+            object rawWarnings;
+            var warnings = data.TryGetValue("warnings", out rawWarnings) ? rawWarnings as List<object> : null;
+            if (warnings == null)
+            {
+                warnings = new List<object>();
+                data["warnings"] = warnings;
+            }
+            warnings.Add(new Dictionary<string, object>
+            {
+                { "code", "INLINE_IMAGE_TOO_LARGE" },
+                { "message", "inlineBase64 was requested, but the image exceeds the internal inline limit; use the artifact path instead." },
+                { "sizeBytes", sizeBytes },
+                { "maxInlineBytes", (long)InlineImageMaxBytes }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliLiveBuildCoordinator.cs

@@ -0,0 +1,230 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor;
+using UnityEditor.Build.Reporting;
+using UnityCli.Protocol;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>BuildPlayer 的进行中状态只保留在 active-build 文件，终态立即删除。</summary>
+        internal static class UnityCliLiveBuildCoordinator
+        {
+            internal const string Command = "internal.build.run.start";
+            private const string Scope = "build";
+            private static bool reloadRecoveryPending;
+            internal static bool IsCommand(string command) { return command == Command; }
+            internal static void Register(BridgeCommandRegistry registry)
+            {
+                registry.Register<BridgeRequest>(Command, "internal", true, 600000, (r, c) => { throw new InvalidOperationException("Build is coordinator-owned."); });
+            }
+
+            /// <summary>reload后先持久化outcome-unknown标记，再释放已终止旧domain的exact lease。</summary>
+            internal static void Initialize() { RecoverTerminalCleanup(); reloadRecoveryPending = true; MarkReloadOutcomeUnknownAndRelease(); }
+            internal static void Tick() { RecoverTerminalCleanup(); if (reloadRecoveryPending) MarkReloadOutcomeUnknownAndRelease(); }
+
+            private static void MarkReloadOutcomeUnknownAndRelease()
+            {
+                Dictionary<string, object> active;
+                try { active = UnityCliActiveOperation.Load(Scope); }
+                catch { return; }
+                if (active == null) { reloadRecoveryPending = false; return; }
+                var requestId = Value(active, "requestId");
+                var requestDigest = Value(active, "requestDigest");
+                var editorSessionId = Value(active, "editorSessionId");
+                if (!IsSafeId(requestId) || !IsSha256(requestDigest)) return;
+                if (!string.Equals(editorSessionId, EditorSessionId(), StringComparison.Ordinal))
+                {
+                    try { UnityCliActiveOperation.Clear(Scope); reloadRecoveryPending = false; } catch { }
+                    return;
+                }
+                object marked;
+                if (!active.TryGetValue("reloadOutcomeUnknown", out marked) || !(marked is bool) || !(bool)marked)
+                {
+                    active["reloadOutcomeUnknown"] = true;
+                    try { UnityCliActiveOperation.Save(Scope, active); }
+                    catch { return; }
+                }
+                UnityCliSessionMutationLease.Release(requestId, requestDigest);
+                bool isOwned;
+                if (UnityCliSessionMutationLease.TryIsOwnedBy(requestId, requestDigest, out isOwned) && !isOwned)
+                    reloadRecoveryPending = false;
+            }
+
+            internal static void BeforeReload() { }
+            internal static void Shutdown() { reloadRecoveryPending = false; }
+
+            internal static async Task<string> Execute(BridgeRequest request, byte[] rawRequestBytes, Func<bool> tryAccept, CancellationToken cancellationToken)
+            {
+                var args = request.DeserializeArgs<Args>();
+                if (request.Execution != null && request.Execution.DryRun == true)
+                {
+                    Validate(args);
+                    return UnityCliSerializer.Serialize(ProtocolEnvelopeFactory.Success(request.RequestId, new Dictionary<string, object> { { "dryRun", true }, { "plannedEffects", args.Targets.Select(x => (object)new Dictionary<string, object> { { "type", "build-player" }, { "target", x.Target }, { "outputPath", x.OutputPath } }).ToList() } }));
+                }
+                var digest = UnityCliRequestDigest.Compute(rawRequestBytes, request.InstanceId);
+                object recoveredTerminal;
+                if (UnityCliActiveOperation.TryGetTerminal(Scope, request.RequestId, digest, out recoveredTerminal))
+                {
+                    try { UnityCliActiveOperation.BeginExactTerminalCleanup(Scope, request.RequestId, digest); } catch { }
+                    return Terminal(request.RequestId, recoveredTerminal);
+                }
+                Dictionary<string, object> active;
+                try { active = UnityCliActiveOperation.Load(Scope); }
+                catch (Exception) { return SerializeBridgeExceptionEnvelope(request.RequestId, new BridgeCommandException("E_EXECUTION_TIMEOUT", "Build active state cannot be read; outcome is unknown.")); }
+                if (active != null)
+                {
+                    if (!string.Equals(Value(active, "requestId"), request.RequestId, StringComparison.Ordinal)) return Busy(request.RequestId);
+                    if (!string.Equals(Value(active, "requestDigest"), digest, StringComparison.Ordinal))
+                        return SerializeBridgeExceptionEnvelope(request.RequestId, new BridgeCommandException("E_REQUEST_ID_REUSED", "Build requestId was reused with different input."));
+                    object reloadUnknown;
+                    if (!active.TryGetValue("reloadOutcomeUnknown", out reloadUnknown) || !(reloadUnknown is bool) || !(bool)reloadUnknown)
+                        return Busy(request.RequestId);
+                    var unknown = ProtocolEnvelopeFactory.Error(request.RequestId, "E_EXECUTION_TIMEOUT", "A previous build did not reach a terminal result before reload or timeout.", null, new[] { "Inspect build output and editor.state before retrying." });
+                    return FinishTerminal(request.RequestId, digest, unknown);
+                }
+                bool newlyAcquiredLease;
+                if (!UnityCliSessionMutationLease.TryAcquire(request.RequestId, digest, out newlyAcquiredLease) || !newlyAcquiredLease) return Busy(request.RequestId);
+                try
+                {
+                    if (tryAccept == null || !tryAccept()) throw new OperationCanceledException();
+                    Validate(args);
+                    var prepared = args.Targets.Select(Prepare).ToList();
+                    active = NewActive(request, digest, args);
+                    UnityCliActiveOperation.Save(Scope, active);
+                    cancellationToken.ThrowIfCancellationRequested();
+                    active["phase"] = "running";
+                    UnityCliActiveOperation.Save(Scope, active);
+                    var reports = new List<object>();
+                    foreach (var item in prepared)
+                    {
+                        bool ownedBefore;
+                        if (!UnityCliSessionMutationLease.TryIsOwnedBy(request.RequestId, digest, out ownedBefore) || !ownedBefore)
+                            return FinishTerminal(request.RequestId, digest, UnknownLeaseTerminal(request.RequestId));
+                        reports.Add(Build(item));
+                        bool ownedAfter;
+                        if (!UnityCliSessionMutationLease.TryIsOwnedBy(request.RequestId, digest, out ownedAfter) || !ownedAfter)
+                            return FinishTerminal(request.RequestId, digest, UnknownLeaseTerminal(request.RequestId));
+                    }
+                    var data = new Dictionary<string, object> { { "targets", reports } };
+                    var failed = reports.Cast<Dictionary<string, object>>().Any(x => !string.Equals(x["result"] as string, "Succeeded", StringComparison.Ordinal));
+                    object envelope = failed ? (object)ProtocolEnvelopeFactory.Error(request.RequestId, "E_BUILD_FAILED", "One or more BuildPlayer reports were not successful.", data, new[] { "Inspect the returned BuildReport summaries and Unity Console." }) : ProtocolEnvelopeFactory.Success(request.RequestId, data);
+                    return FinishTerminal(request.RequestId, digest, envelope);
+                }
+                catch (OperationCanceledException)
+                {
+                    return FinishTerminal(request.RequestId, digest, ProtocolEnvelopeFactory.Error(request.RequestId, "E_EXECUTION_TIMEOUT", "Build did not complete before the request deadline.", null, new[] { "Inspect editor.state and retry." }));
+                }
+                catch (BridgeCommandException ex)
+                {
+                    return SerializeBridgeExceptionEnvelope(request.RequestId, ex);
+                }
+                catch (Exception ex)
+                {
+                    return FinishTerminal(request.RequestId, digest, SerializeException(request.RequestId, ex));
+                }
+                finally
+                {
+                    try
+                    {
+                        UnityCliActiveOperation.RetryExactTerminalCleanup(Scope);
+                        if (!UnityCliActiveOperation.Exists(Scope) && !UnityCliActiveOperation.Exists(Scope + "-terminal-cleanup"))
+                            UnityCliSessionMutationLease.Release(request.RequestId, digest);
+                    }
+                    catch { }
+                    await Task.FromResult(0);
+                }
+            }
+
+            private static Dictionary<string, object> NewActive(BridgeRequest request, string digest, Args args) { return new Dictionary<string, object> { { "requestId", request.RequestId }, { "requestDigest", digest }, { "editorSessionId", EditorSessionId() }, { "phase", "accepted" }, { "startedAt", DateTimeOffset.UtcNow.ToString("O", CultureInfo.InvariantCulture) }, { "targets", args.Targets.Select(x => (object)new Dictionary<string, object> { { "target", x.Target }, { "outputPath", x.OutputPath } }).ToList() } }; }
+            private static string Value(IDictionary<string, object> value, string key) { object item; return value != null && value.TryGetValue(key, out item) ? item as string : null; }
+            private static string Busy(string id) { return UnityCliSerializer.Serialize(ProtocolEnvelopeFactory.Error(id, "E_UNITY_BUSY", "Another mutation owns the selected Unity instance.", null, new[] { "Wait for the current mutation to reach its terminal result, then retry." }, true, 250)); }
+            private static string FinishTerminal(string id, string digest, object envelope)
+            {
+                bool isOwned;
+                if (!UnityCliSessionMutationLease.TryIsOwnedBy(id, digest, out isOwned) || !isOwned) envelope = UnknownLeaseTerminal(id);
+                var active = UnityCliActiveOperation.Load(Scope);
+                if (active != null)
+                {
+                    if (!string.Equals(Value(active, "requestId"), id, StringComparison.Ordinal)
+                        || !string.Equals(Value(active, "requestDigest"), digest, StringComparison.Ordinal))
+                        throw new BridgeCommandException("E_EXECUTION_TIMEOUT", "Build terminal active identity cannot be proven.");
+                    active["phase"] = "terminal_pending";
+                    active["terminalEnvelope"] = envelope;
+                    UnityCliActiveOperation.Save(Scope, active);
+                }
+                var first = UnityCliActiveOperation.StoreTerminalFirst(Scope, id, digest, envelope);
+                UnityCliActiveOperation.BeginExactTerminalCleanup(Scope, id, digest);
+                return Terminal(id, first);
+            }
+            private static void RecoverTerminalCleanup()
+            {
+                try
+                {
+                    if (UnityCliActiveOperation.RetryExactTerminalCleanup(Scope)) return;
+                    var active = UnityCliActiveOperation.Load(Scope);
+                    if (active == null) return;
+                    var requestId = Value(active, "requestId");
+                    var requestDigest = Value(active, "requestDigest");
+                    object terminal = null;
+                    var hasTerminal = IsSafeId(requestId) && IsSha256(requestDigest)
+                        && UnityCliActiveOperation.TryGetTerminal(Scope, requestId, requestDigest, out terminal);
+                    if (!hasTerminal)
+                    {
+                        object pending;
+                        if (!active.TryGetValue("terminalEnvelope", out pending) || pending == null)
+                        {
+                            if (!string.Equals(Value(active, "phase"), "running", StringComparison.Ordinal)) return;
+                            pending = UnknownLeaseTerminal(requestId);
+                            active["phase"] = "terminal_pending";
+                            active["terminalEnvelope"] = pending;
+                            UnityCliActiveOperation.Save(Scope, active);
+                        }
+                        terminal = UnityCliActiveOperation.StoreTerminalFirst(Scope, requestId, requestDigest, pending);
+                    }
+                    if (terminal != null) UnityCliActiveOperation.BeginExactTerminalCleanup(Scope, requestId, requestDigest);
+                }
+                catch { }
+            }
+            private static object UnknownLeaseTerminal(string id) { return ProtocolEnvelopeFactory.Error(id, "E_EXECUTION_TIMEOUT", "Build lost its exact mutation lease after BuildPlayer; outcome is unknown.", null, new[] { "Inspect build artifacts before submitting another mutation." }); }
+            private static string Terminal(string id, object envelope) { return UnityCliSerializer.Serialize(ProtocolEnvelopeFactory.Success(id, new Dictionary<string, object> { { "terminal", true }, { "rootEnvelope", envelope } })); }
+            private static object SerializeException(string id, Exception ex) { return ProtocolEnvelopeFactory.Error(id, "E_BRIDGE_COMMAND_FAILED", ex.Message, null, new[] { "Check Unity Console and UnityCliBridge.log." }); }
+            private static Prepared Prepare(TargetArgs input)
+            {
+                if (input == null || string.IsNullOrWhiteSpace(input.Target) || string.IsNullOrWhiteSpace(input.OutputPath)) throw new BridgeCommandException("E_SCHEMA_INVALID", "Each build target requires target and outputPath.");
+                BuildTarget target; if (!Enum.TryParse(input.Target, false, out target)) throw new BridgeCommandException("E_SCHEMA_INVALID", "Unsupported Unity BuildTarget: " + input.Target);
+                var scenes = EditorBuildSettings.scenes.Where(x => x.enabled && File.Exists(x.path)).Select(x => x.path).ToArray(); if (scenes.Length == 0) throw new BridgeCommandException("E_BUILD_SCENES_EMPTY", "No enabled existing build scenes are available.");
+                var publicPath = input.OutputPath.Replace('\\', '/'); if (Path.IsPathRooted(input.OutputPath) || publicPath.Split('/').Any(x => x == "..")) throw new BridgeCommandException("E_SCHEMA_INVALID", "Build outputPath must be project-relative.");
+                var projectRoot = Path.GetFullPath(ProjectRoot()); var outputPath = Path.GetFullPath(Path.Combine(projectRoot, input.OutputPath)); if (!outputPath.StartsWith(projectRoot + Path.DirectorySeparatorChar, StringComparison.Ordinal) && !string.Equals(outputPath, projectRoot, StringComparison.Ordinal)) throw new BridgeCommandException("E_SCHEMA_INVALID", "Build outputPath escapes the project.");
+                return new Prepared { Target = target, TargetName = input.Target, OutputPath = outputPath, PublicOutputPath = publicPath, Scenes = scenes, Options = ParseOptions(input.Options) };
+            }
+            private static BuildOptions ParseOptions(List<string> values) { var result = BuildOptions.None; foreach (var value in values ?? new List<string>()) { BuildOptions option; if (string.IsNullOrWhiteSpace(value) || !Enum.TryParse(value, false, out option)) throw new BridgeCommandException("E_SCHEMA_INVALID", "Unsupported BuildOptions value: " + value); result |= option; } return result; }
+            private static Dictionary<string, object> Build(Prepared p)
+            {
+                var started = DateTimeOffset.UtcNow; var parent = Path.GetDirectoryName(p.OutputPath); if (!string.IsNullOrEmpty(parent)) Directory.CreateDirectory(parent);
+                var report = BuildPipeline.BuildPlayer(p.Scenes, p.OutputPath, p.Target, p.Options); var finished = DateTimeOffset.UtcNow; var artifact = ReadArtifact(p.OutputPath, p.PublicOutputPath);
+                if (report.summary.result == BuildResult.Succeeded && !SuccessfulArtifactProof(artifact)) throw new BridgeCommandException("E_BUILD_ARTIFACT_MISSING", "BuildReport succeeded but its fresh output artifact has no non-empty SHA-256 proof.");
+                var messages = report.steps.SelectMany(step => step.messages ?? new BuildStepMessage[0]).Where(message => !string.IsNullOrWhiteSpace(message.content)).Select(message => (object)new Dictionary<string, object> { { "type", message.type.ToString() }, { "message", message.content } }).Take(100).ToList();
+                return new Dictionary<string, object> { { "target", p.TargetName }, { "result", report.summary.result.ToString() }, { "outputPath", p.PublicOutputPath }, { "totalSize", report.summary.totalSize }, { "totalErrors", (long)report.summary.totalErrors }, { "totalWarnings", (long)report.summary.totalWarnings }, { "startedAt", started.ToString("O", CultureInfo.InvariantCulture) }, { "finishedAt", finished.ToString("O", CultureInfo.InvariantCulture) }, { "durationMs", (long)(finished - started).TotalMilliseconds }, { "messages", messages }, { "artifact", artifact } };
+            }
+            private static Dictionary<string, object> ReadArtifact(string path, string publicPath) { var roots = new List<string>(); if (File.Exists(path)) roots.Add(path); if (Directory.Exists(path)) roots.Add(path); var sidecar = Path.Combine(Path.GetDirectoryName(path) ?? string.Empty, Path.GetFileNameWithoutExtension(path) + "_Data"); if (Directory.Exists(sidecar)) roots.Add(sidecar); var files = roots.SelectMany(root => File.Exists(root) ? new[] { root } : Directory.GetFiles(root, "*", SearchOption.AllDirectories)).Distinct(StringComparer.Ordinal).OrderBy(x => x, StringComparer.Ordinal).ToArray(); var size = files.Sum(x => new FileInfo(x).Length); var treeRoot = Path.GetDirectoryName(path) ?? path; return new Dictionary<string, object> { { "outputPath", publicPath }, { "exists", files.Length > 0 }, { "hash", File.Exists(path) ? HashFile(path) : null }, { "treeHash", files.Length > 0 ? HashTree(files, treeRoot) : null }, { "fileCount", (long)files.Length }, { "size", size } }; }
+            private static bool SuccessfulArtifactProof(Dictionary<string, object> artifact) { object exists; object count; object size; object hash; object treeHash; artifact.TryGetValue("exists", out exists); artifact.TryGetValue("fileCount", out count); artifact.TryGetValue("size", out size); artifact.TryGetValue("hash", out hash); artifact.TryGetValue("treeHash", out treeHash); return exists is bool && (bool)exists && count is long && (long)count > 0 && size is long && (long)size > 0 && (IsSha256(hash as string) || IsSha256(treeHash as string)); }
+            private static string HashFile(string path) { using (var sha = SHA256.Create()) using (var stream = File.OpenRead(path)) return BitConverter.ToString(sha.ComputeHash(stream)).Replace("-", "").ToLowerInvariant(); }
+            private static string HashTree(IEnumerable<string> files, string root) { using (var sha = SHA256.Create()) return BitConverter.ToString(sha.ComputeHash(Encoding.UTF8.GetBytes(string.Join("\n", files.Select(x => Path.GetRelativePath(root, x).Replace('\\', '/') + "\0" + HashFile(x)))))).Replace("-", "").ToLowerInvariant(); }
+            private static void Validate(Args args) { if (args == null || string.IsNullOrWhiteSpace(args.ExpectedEditorSessionId) || args.Targets == null || args.Targets.Count == 0) throw new BridgeCommandException("E_SCHEMA_INVALID", "Build targets and expectedEditorSessionId are required."); if (args.Targets.Any(x => x == null || string.IsNullOrWhiteSpace(x.Target) || string.IsNullOrWhiteSpace(x.OutputPath))) throw new BridgeCommandException("E_SCHEMA_INVALID", "Each build target requires target and outputPath."); if (args.Targets.Select(x => x.Target).Distinct(StringComparer.Ordinal).Count() != args.Targets.Count) throw new BridgeCommandException("E_SCHEMA_INVALID", "Build targets must not contain duplicates."); if (args.Targets.Select(x => x.OutputPath.Replace('\\', '/')).Distinct(StringComparer.OrdinalIgnoreCase).Count() != args.Targets.Count) throw new BridgeCommandException("E_SCHEMA_INVALID", "Build output paths must not conflict."); if (!string.Equals(args.ExpectedEditorSessionId, EditorSessionId(), StringComparison.Ordinal)) throw new BridgeCommandException("E_EDITOR_SESSION_REPLACED", "The selected Editor session changed before build execution."); if (EditorApplication.isPlaying || IsPlayModeChanging()) throw new BridgeCommandException("E_TOOL_PLAYMODE_UNAVAILABLE", "build.run is editor-only and requires stable Edit Mode.", new Dictionary<string, object> { { "toolName", "build.run" }, { "playModeSupport", "editor-only" } }, new[] { "Exit Play Mode before running build.run." }); if (EditorUtility.scriptCompilationFailed) throw new BridgeCommandException("E_UNITY_COMPILE_FAILED", "Unity has unresolved script compilation errors and cannot start BuildPlayer.", "Run editor.compile and fix all diagnostics before retrying build.run."); }
+            private sealed class Args { public List<TargetArgs> Targets { get; set; } public string ExpectedEditorSessionId { get; set; } }
+            private sealed class TargetArgs { public string Target { get; set; } public string OutputPath { get; set; } public List<string> Options { get; set; } }
+            private sealed class Prepared { public BuildTarget Target; public string TargetName; public string OutputPath; public string PublicOutputPath; public string[] Scenes; public BuildOptions Options; }
+        }
+    }
+}
+#endif