@alpsckr/unitycli 0.4.0 → 0.4.1

package/skills/unitycli/manifest.json

@@ -1,8 +1,8 @@
 {
   "name": "unitycli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "owner": "alps-unity-cli maintainers",
-  "updated_at": "2026-08-13",
+  "updated_at": "2026-08-27",
   "status": "active",
   "maturity_tier": "governed",
   "lifecycle_stage": "governed",

package/skills/unitycli/references/custom-tools.md

@@ -96,16 +96,16 @@ AI 使用当前实例的统一公开目录自发现和执行：
 
 ```powershell
 unitycli tools group --instance <id|projectPath|alias>
-unitycli tools group list <group> --instance <id|projectPath|alias>
+unitycli tools group list <group> --page-size 20 --instance <id|projectPath|alias>
 unitycli tools describe <custom-tool> --instance <id|projectPath|alias>
 unitycli tools run <custom-tool> --input '<json>' --instance <id|projectPath|alias>
 ```
 
-`<group>` 必须来自当前实例 `tools group` 的真实输出；不要假设项目 Tool 位于 `custom` 组。`source` 只作描述/审计，不改变发现或执行路径。
+`<group>` 必须来自当前实例 `tools group` 的真实输出；不要假设项目 Tool 位于 `custom` 组。存在`pageInfo.nextCursor`时必须继续读取所需页面。`source` 只作内部描述/审计，不改变发现或执行路径。
 
 ## 最小验证
 
 1. Unity 编译无错误。
-2. `tools group` 与 `tools group list <group>` 能从同一实例完整目录发现 Tool。
+2. `tools group` 与 `tools group list <group>` 的分页结果能从同一实例完整目录发现 Tool。
 3. `tools describe <tool>` 的 schema、风险、target、Play Mode 语义足以让陌生 AI 一次调用成功。
 4. `tools run <tool> --input '<json>' --instance <id|projectPath|alias>` 覆盖默认正向、代表性可选参数和错误路径。

package/skills/unitycli/references/operation-protocol.md

@@ -6,9 +6,11 @@
 
 `--instance <full-id|canonical-project-path|alias>`是通用显式实例选择器；`command --project-path <path>`是同一canonical identity选择语法。显式空值必须失败；业务`input.instance`不是selector。未传selector时只从当前Unity项目CWD解析；无法确定实例即稳定失败，`--project`和Tool input都不能选实例。
 
-`target alias` 只维护 canonical project identity alias。`source` 只供说明和审计，不影响显示、describe、owner 路由或执行。连接实例的 Tool 目录是权威目录；离线静态 catalog 不能替代它。PowerShell中执行多token搜索时使用`tools search '<k1|k2|...>'`；单引号必须包住完整关键词，避免`|`被解释为shell管道。
+`target alias` 只维护 canonical project identity alias。`source` 只供说明和审计，不影响显示、describe、owner 路由或执行，也不进入搜索结果。连接实例的 Tool 目录是权威目录；离线静态 catalog 不能替代它。PowerShell中执行多token搜索时使用`tools search '<k1|k2|...>'`；单引号必须包住完整关键词，避免`|`被解释为shell管道。
 
-`instances list`逐个验证当前Registry v3正式文件。旧格式、损坏或不可读文件不参与路由，也不阻断其他合法实例；存在时结果包含`invalidRecordCount`，应使用`doctor`读取计数告警。不得读取、兼容解析、转换、移动或删除内部文件。显式选择对应坏instanceId仍严格失败。
+`tools group list`、`tools search`和省略name的`command`列表按名称稳定分页，默认20项、最大100项。存在`pageInfo.nextCursor`时，将其原值传回同一查询的`--cursor`；不要重新解释或递增cursor。stdout默认是单行紧凑JSON，`--pretty`只增加缩进。
+
+`instances list`逐个验证当前正式实例记录。旧格式、损坏或不可读文件不参与路由，也不阻断其他合法实例；存在时结果包含`invalidRecordCount`。当前项目由Unity在ready时自动重建。需要清理历史记录时调用`instances prune --instance <id|projectPath|alias>`并检查`removed`、`remaining`、`deferred`、`scanned`和`truncated`；不得读取、兼容解析、转换、移动或手工删除内部文件。
 
 ## Descriptor
 
@@ -46,7 +48,7 @@ Tool descriptor 常用字段：
 
 每个live Editor或Development Player session拥有独立任务池，默认达到5个active root时关闭准入，降到4仍关闭，降到3才重开。CLI在业务请求前自动等待；AI不手工轮询、不读取active count，也不管理内部token。统一catalog在Editor和Runtime同时在线时，会分别经过两个session的准入后才返回完整结果。
 
-`--timeout-ms T`先提供一份最多`T`的准入预算。准入deadline的`E_UNITY_BUSY`明确证明业务Bridge请求未发送、effect未开始，可以稍后提交新root。获得grant后再创建一份完整`T`的execution预算；token重取、status、rebind、reload和terminal recovery都只能消费该预算，不能刷新第三份预算。
+`--timeout-ms T`先提供一份最多`T`的准入预算。CLI在其中等待首次ready记录、当前编译/导入/重载和任务池；证明Unity未运行时立即返回。准入deadline的`E_UNITY_BUSY`明确证明业务Bridge请求未发送、effect未开始，可以稍后提交新root。获得grant后再创建一份完整`T`的execution预算；token重取、status、rebind、reload和terminal recovery都只能消费该预算，不能刷新第三份预算。
 
 `E_EXECUTION_TIMEOUT`、放行后的transport丢失、进程中断或没有可信terminal envelope时，只能确定本次调用没有返回可信终态，不能据此判断mutation是否发生。先读取对象、场景、Package、build/test状态或artifact manifest；只有形成新的业务决策后才提交新请求，不把outcome unknown自动重放。
 
@@ -80,4 +82,4 @@ unitycli extensions remove <id> --project <path>
 unitycli extensions doctor --project <path>
 ```
 
-Skill/runtime bundle 安装使用 `init`；`init --check` 只读校验。Unity project 文件投影完成后，如任务要求 Editor 效果，仍需在已连接实例中完成 import/compile 和业务 readback。
+安装协议先使用`unitycli init help`学习，再由`init discover`只读发现现场。Bridge只用`init package --project <UnityProject>`安装，并用同命令加`--check`校验；Skill只用`init skill --agent <.agents|claude> --scope <workspace|user>`，workspace scope还必须传`--workspace <path>`，同命令加`--check`校验。不得使用裸`init`或混装Bridge与Skill。Unity project文件投影完成后，如任务要求Editor效果，仍需在已连接实例中完成import/compile和业务readback；安装协议本身不得管理Unity进程。

package/skills/unitycli/reports/output_quality_scorecard.md

@@ -24,7 +24,7 @@ The feedback output contract requires category, concise issue summary, optional
 | Feedback privacy negatives | PASS | Secret/endpoint/path negative matrix | Novel secret formats can still exist |
 | Concurrent JSONL validity | PASS | 16 parallel Windows PowerShell writers | Cross-session Windows desktop contention not measured |
 | Rolling bound | PASS | Main + 3 archives, each <= 64 KiB | Longitudinal retention utility not measured |
-| Installed bundle reachability | PASS | Public init/drifted-update/check/recorder smoke for all three agents | Verified on the selected Dev project only |
+| Installed bundle reachability | PASS | Public workspace/user install, drifted-update, check, and recorder smoke for `.agents` and Claude | Verified with isolated filesystem targets |
 | Clean Agent interpretation | PASS | Black-box runtime discovery transcript and main-agent audit | Human adjudication unavailable |
 
 ## Rollback Boundary

package/skills/unitycli/reports/trust-report.md

@@ -36,7 +36,7 @@ The Skill does not add confirmation, intent review, or a predefined operation ra
 
 - Full repository tests: 876/876 PASS; targeted Skill/installer/docs regression: 61/61 PASS.
 - Recorder concurrency, rotation, privacy negatives, PowerShell 5.1 BOM, and non-ASCII stdout: PASS.
-- Public runtime install, drifted update, check, marker preservation, and installed-recorder smoke across `.pi`, `.claude`, and `.agents`: PASS.
+- Public runtime install, drifted update, check, marker preservation, and installed-recorder smoke across `.claude` and `.agents`: PASS.
 - Resource boundary: 963 estimated initial-load tokens (691 Skill body tokens), limit 1300.
 - Trigger fixture gate: 29/29 classifications.
 - Output assertion gate: 5/5 with-skill cases, 100% pass rate.

package/unitypkg/Editor/Bridge/BridgeCommandRegistry.cs

@@ -86,6 +86,7 @@ namespace UnityCli
             RegisterInstalledExtensionCommands(registry);
             RegisterCodeExecCommand(registry);
             RegisterEditorStateSnapshotCommand(registry);
+            RegisterInstanceCleanupCommand(registry);
             UnityCliCompileCoordinator.Register(registry);
             UnityCliLiveBuildCoordinator.Register(registry);
             UnityCliLiveRefreshCoordinator.Register(registry);

package/unitypkg/Editor/Bridge/BridgeWorkQueue.cs

@@ -60,22 +60,34 @@ namespace UnityCli
             // pulse只证明EditorApplication.update最近推进；具体请求仍由TryStart证明开始。
             Volatile.Write(ref mainThreadPulseTimestamp, System.Diagnostics.Stopwatch.GetTimestamp());
             Interlocked.Increment(ref mainThreadPulseSequence);
-            cachedIsCompiling = EditorApplication.isCompiling;
-            cachedIsUpdating = EditorApplication.isUpdating;
+            var listenerWasStarted = started;
+            var isCompiling = EditorApplication.isCompiling;
+            var isUpdating = EditorApplication.isUpdating;
+            var isBuilding = BuildPipeline.isBuildingPlayer;
+            var isPlayModeChanging = IsPlayModeChanging();
+            var lifecycleChanged = cachedIsCompiling != isCompiling
+                || cachedIsUpdating != isUpdating
+                || cachedIsBuilding != isBuilding
+                || cachedIsPlayModeChanging != isPlayModeChanging;
+            cachedIsCompiling = isCompiling;
+            cachedIsUpdating = isUpdating;
             cachedIsPlayingOrWillChangePlaymode = EditorApplication.isPlayingOrWillChangePlaymode;
             cachedIsPlaying = EditorApplication.isPlaying;
-            cachedIsBuilding = BuildPipeline.isBuildingPlayer;
-            cachedIsPlayModeChanging = IsPlayModeChanging();
+            cachedIsBuilding = isBuilding;
+            cachedIsPlayModeChanging = isPlayModeChanging;
             AdvanceBridgeStartup();
             UnityCliSessionMutationLease.TryFinalizeOwnedPlayModeRoot();
             UnityCliWaitScheduler.Tick();
 
-            // 生命周期变化会即时登记；这里仅低频刷新，修复漏事件并更新诊断快照。
-            if (started && EditorApplication.timeSinceStartup >= nextRegistryRefreshAt)
+            // 新listener先保留至少一个主线程update的transitioning状态；后续生命周期变化即时发布，30秒刷新只修复漏事件。
+            if (listenerWasStarted && started
+                && (readyPublicationPending || lifecycleChanged || EditorApplication.timeSinceStartup >= nextRegistryRefreshAt))
             {
+                readyPublicationPending = false;
                 RegisterInstance("ready");
                 nextRegistryRefreshAt = EditorApplication.timeSinceStartup + RegistryRefreshSeconds;
             }
+            TickInstancePublicationRetry();
             var startedThisTick = 0;
             while (startedThisTick < MaxWorkStartsPerTick)
             {

package/unitypkg/Editor/Infrastructure/CodeExecSupport.cs

@@ -11,8 +11,6 @@ using System.Text;
 using System.Text.RegularExpressions;
 using System.Threading;
 using System.Threading.Tasks;
-using Microsoft.CodeAnalysis;
-using Microsoft.CodeAnalysis.CSharp;
 using UnityEditor;
 using UnityEditor.SceneManagement;
 using UnityEngine;
@@ -34,9 +32,6 @@ namespace UnityCli
         private const int MaxRoslynOutputBytes = 512 * 1024;
         private const int MaxRoslynDiagnostics = 100;
 
-        // code.exec 编译核心开关：默认 in-process Roslyn（官方方案）；置 false 回退到 csc.exe 子进程。
-        private const bool CodeExecUseInProcessRoslyn = true;
-
         // 注册运行时代码执行命令。
         private static void RegisterCodeExecCommand(BridgeCommandRegistry registry)
         {
@@ -90,9 +85,7 @@ namespace UnityCli
             byte[] assemblyBytes;
             try
             {
-                var compilation = CodeExecUseInProcessRoslyn
-                    ? CompileInProcess(source, references, request.StringArg("defines"), request, cancellationToken)
-                    : CompileWithCscFallback(source, references, request.StringArg("defines"), request, cancellationToken);
+                var compilation = CompileWithUnityCompiler(source, references, request.StringArg("defines"), request, cancellationToken);
                 if (compilation.TimedOut)
                     return CodeExecutionResult.Fail("E_EXECUTION_TIMEOUT", "Runtime Code compilation exceeded the immutable deadline.", new Dictionary<string, object>(), "Inspect the Editor state before submitting a new request.");
                 if (!compilation.Success)
@@ -215,8 +208,8 @@ namespace UnityCli
         }
 
         /// <summary>
-        /// 汇总 in-process Roslyn 所需引用；跟随官方 Editor 模式全包含 AppDomain 已加载程序集，
-        /// 不排除 mscorlib/System*/netstandard，避免针对 mscorlib 编译的项目程序集缺核心库引用。
+        /// 汇总 Unity Editor 编译器所需引用；全包含 AppDomain 已加载程序集，
+        /// 不排除 mscorlib/System*/netstandard，避免项目程序集缺少核心库引用。
         /// </summary>
         private static IEnumerable<string> DefaultCodeReferences(string refsCsv, UnityCli.Protocol.BridgeRequest request, CancellationToken cancellationToken)
         {
@@ -245,7 +238,7 @@ namespace UnityCli
             if (!references.Contains(reference)) references.Add(reference);
         }
 
-        // in-process 与 csc.exe 回退共用的编译结果；成功时携带程序集字节，失败时携带错误诊断。
+        // Unity Editor 编译器结果；成功时携带程序集字节，失败时携带结构化诊断。
         private sealed class CodeCompilationResult
         {
             public bool Success;
@@ -255,71 +248,9 @@ namespace UnityCli
         }
 
         /// <summary>
-        /// 用 in-process Roslyn（Microsoft.CodeAnalysis.CSharp）编译源码。
-        /// 引用集全包含 AppDomain 已加载程序集，与官方 Editor 模式一致；
-        /// 编译无法中途终止，只能在编译前后重验 immutable deadline。
-        /// </summary>
-        private static CodeCompilationResult CompileInProcess(string source, IEnumerable<string> references, string definesCsv, UnityCli.Protocol.BridgeRequest request, CancellationToken cancellationToken)
-        {
-            var result = new CodeCompilationResult();
-            try
-            {
-                EnsureCodePreEffectDeadline(request, cancellationToken);
-                var parseOptions = new CSharpParseOptions(preprocessorSymbols: SplitCsv(definesCsv));
-                var tree = CSharpSyntaxTree.ParseText(WrapCodeSource(source), parseOptions);
-                var metadataReferences = new List<MetadataReference>();
-                foreach (var reference in references)
-                {
-                    if (string.IsNullOrEmpty(reference)) continue;
-                    try { metadataReferences.Add(MetadataReference.CreateFromFile(reference)); }
-                    catch { /* 跳过不可读引用，避免个别文件缺失中断整次编译 */ }
-                }
-                var compilation = CSharpCompilation.Create(
-                    "UnityCli.RuntimeCode",
-                    new[] { tree },
-                    metadataReferences,
-                    new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary));
-                using (var ms = new MemoryStream())
-                {
-                    var emitResult = compilation.Emit(ms);
-                    foreach (var diagnostic in emitResult.Diagnostics)
-                    {
-                        if (diagnostic.Severity != DiagnosticSeverity.Error) continue;
-                        if (result.Diagnostics.Count >= MaxRoslynDiagnostics) continue;
-                        var lineSpan = diagnostic.Location.GetLineSpan();
-                        result.Diagnostics.Add(new Dictionary<string, object>
-                        {
-                            { "severity", "error" }, { "id", BoundedText(diagnostic.Id, 64) },
-                            { "message", BoundedText(diagnostic.GetMessage(), 4096) },
-                            { "file", BoundedText(lineSpan.Path ?? string.Empty, 2048) },
-                            { "line", (long)(lineSpan.StartLinePosition.Line + 1) },
-                            { "column", (long)(lineSpan.StartLinePosition.Character + 1) },
-                            { "span", null }
-                        });
-                    }
-                    result.Success = emitResult.Success;
-                    if (emitResult.Success) result.AssemblyBytes = ms.ToArray();
-                }
-                // in-process 无法中途终止；编译完成后重验 deadline，拒绝超时结果。
-                int remainingMs;
-                if (cancellationToken.IsCancellationRequested || request == null || !request.TryDeadlineRemainingMs(out remainingMs))
-                {
-                    result.TimedOut = true;
-                    result.Success = false;
-                    result.AssemblyBytes = null;
-                }
-            }
-            catch (OperationCanceledException)
-            {
-                result.TimedOut = true;
-            }
-            return result;
-        }
-
-        /// <summary>
-        /// csc.exe 子进程编译回退；保留原临时文件与子进程超时终止逻辑，仅在 in-process 编译不可用时切换回来。
+        /// 使用当前 Unity Editor 自带的 csc.exe 编译源码；子进程受请求 deadline 约束并可终止。
         /// </summary>
-        private static CodeCompilationResult CompileWithCscFallback(string source, IEnumerable<string> references, string definesCsv, UnityCli.Protocol.BridgeRequest request, CancellationToken cancellationToken)
+        private static CodeCompilationResult CompileWithUnityCompiler(string source, IEnumerable<string> references, string definesCsv, UnityCli.Protocol.BridgeRequest request, CancellationToken cancellationToken)
         {
             var result = new CodeCompilationResult();
             var editorDataPath = EditorDataPath();
@@ -339,7 +270,7 @@ namespace UnityCli
             {
                 File.WriteAllText(sourceFilePath, WrapCodeSource(source), new UTF8Encoding(true));
                 WriteReferenceResponseFile(responseFilePath, references);
-                var compilation = CompileWithRoslyn(editorDataPath, sourceFilePath, responseFilePath, assemblyFilePath, definesCsv, request, cancellationToken);
+                var compilation = RunUnityCompiler(editorDataPath, sourceFilePath, responseFilePath, assemblyFilePath, definesCsv, request, cancellationToken);
                 if (compilation.TimedOut)
                 {
                     result.TimedOut = true;
@@ -394,7 +325,7 @@ namespace UnityCli
         /// <summary>
         /// 使用 Unity 内置 Roslyn 编译临时源码；进程最多运行 60 秒，输出仅用于诊断，成功程序集由调用方读取到内存。
         /// </summary>
-        private static RoslynCompilation CompileWithRoslyn(string editorDataPath, string sourceFilePath, string responseFilePath, string assemblyFilePath, string definesCsv, UnityCli.Protocol.BridgeRequest request, CancellationToken cancellationToken)
+        private static RoslynCompilation RunUnityCompiler(string editorDataPath, string sourceFilePath, string responseFilePath, string assemblyFilePath, string definesCsv, UnityCli.Protocol.BridgeRequest request, CancellationToken cancellationToken)
         {
             var monoPath = Path.Combine(editorDataPath, "MonoBleedingEdge", "bin", "mono.exe");
             var cscPath = Path.Combine(editorDataPath, "MonoBleedingEdge", "lib", "mono", "4.5", "csc.exe");

package/unitypkg/Editor/Infrastructure/UnityCliInstanceCleanup.cs

@@ -0,0 +1,295 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Text;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        private const int InstanceCleanupMaxScanned = 2000;
+        private const int InstanceCleanupMaxDeleted = 20;
+        private const int InstanceCleanupRetainedOffline = 100;
+        private const int InstanceCleanupRetainedDamaged = 20;
+        private const int InstanceCleanupRetentionDays = 30;
+        private static bool instanceCleanupAttempted;
+        private static readonly UnityCliToolCompletionContract InstanceCleanupCompletion = new UnityCliToolCompletionContract(
+            "internal.instances.prune", "control-plane", "direct-terminal", "atomic", "bounded-cleanup-summary",
+            "writer-owned-registry-reinspection", "caller-responsibility", "E_EXECUTION_TIMEOUT", "caller-responsibility",
+            "atomic-typed-result-v1", "required", true);
+
+        private sealed class InstanceCleanupCandidate
+        {
+            public string Path;
+            public string InstanceId;
+            public DateTimeOffset LastActivity;
+            public bool Damaged;
+        }
+
+        private sealed class InstanceCleanupSummary
+        {
+            public int Scanned;
+            public int Offline;
+            public int Damaged;
+            public int Preserved;
+            public int Deleted;
+            public int Deferred;
+            public int Remaining;
+            public bool Truncated;
+        }
+
+        /// <summary>每个domain只尝试一次自动清理；其他Unity持有全局锁时直接让其负责。</summary>
+        private static void TryRunAutomaticInstanceCleanup()
+        {
+            if (instanceCleanupAttempted) return;
+            instanceCleanupAttempted = true;
+            try
+            {
+                InstanceCleanupSummary summary;
+                var acquired = TryExecuteInstanceCleanup(null, out summary);
+                if (!acquired)
+                {
+                    WriteLog("instance_cleanup_deferred reason=global-lock");
+                    return;
+                }
+                WriteLog("instance_cleanup_completed scanned=" + summary.Scanned.ToString(CultureInfo.InvariantCulture)
+                    + " offline=" + summary.Offline.ToString(CultureInfo.InvariantCulture)
+                    + " damaged=" + summary.Damaged.ToString(CultureInfo.InvariantCulture)
+                    + " preserved=" + summary.Preserved.ToString(CultureInfo.InvariantCulture)
+                    + " deleted=" + summary.Deleted.ToString(CultureInfo.InvariantCulture)
+                    + " deferred=" + summary.Deferred.ToString(CultureInfo.InvariantCulture)
+                    + " truncated=" + (summary.Truncated ? "true" : "false"));
+            }
+            catch (Exception exception)
+            {
+                WriteLog("instance_cleanup_failed kind=" + exception.GetType().Name);
+            }
+        }
+
+        /// <summary>跨Unity只允许一个清理owner；零等待失败由调用方延期或返回busy。</summary>
+        private static bool TryExecuteInstanceCleanup(Action beginEffect, out InstanceCleanupSummary summary)
+        {
+            InstanceCleanupSummary value = null;
+            var acquired = TryWithCurrentUserMutex("Local\\UnityCli.Registry.Cleanup", 0, delegate
+            {
+                if (beginEffect != null) beginEffect();
+                value = RunInstanceCleanup();
+            });
+            summary = value;
+            return acquired;
+        }
+
+        /// <summary>扫描和删除均有硬上限；活跃、不可确认、链接或锁竞争记录只保留。</summary>
+        private static InstanceCleanupSummary RunInstanceCleanup()
+        {
+            var summary = new InstanceCleanupSummary();
+            var directory = InstancesDir();
+            if (!Directory.Exists(directory)) return summary;
+            var root = Path.GetFullPath(directory).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+            var candidates = new List<InstanceCleanupCandidate>();
+            using (var enumerator = Directory.EnumerateFiles(root, "*.json", SearchOption.TopDirectoryOnly).GetEnumerator())
+            {
+                while (summary.Scanned < InstanceCleanupMaxScanned && enumerator.MoveNext())
+                {
+                    var fullPath = Path.GetFullPath(enumerator.Current);
+                    var parent = Path.GetDirectoryName(fullPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+                    var fileName = Path.GetFileName(fullPath);
+                    string candidateInstanceId;
+                    if (!string.Equals(parent, root, StringComparison.OrdinalIgnoreCase)
+                        || !TryInstanceIdFromFileName(fileName, out candidateInstanceId)) continue;
+                    summary.Scanned += 1;
+                    if (string.Equals(candidateInstanceId, InstanceId(), StringComparison.Ordinal))
+                    {
+                        summary.Preserved += 1;
+                        continue;
+                    }
+                    InstanceCleanupCandidate candidate;
+                    if (!TryInspectCleanupCandidate(fullPath, candidateInstanceId, out candidate))
+                    {
+                        summary.Preserved += 1;
+                        continue;
+                    }
+                    if (candidate.Damaged) summary.Damaged += 1;
+                    else summary.Offline += 1;
+                    candidates.Add(candidate);
+                }
+                if (enumerator.MoveNext()) summary.Truncated = true;
+            }
+
+            var cutoff = DateTimeOffset.UtcNow.AddDays(-InstanceCleanupRetentionDays);
+            var offline = candidates.Where(value => !value.Damaged).OrderBy(value => value.LastActivity).ThenBy(value => value.InstanceId, StringComparer.Ordinal).ToList();
+            var damaged = candidates.Where(value => value.Damaged).OrderBy(value => value.LastActivity).ThenBy(value => value.InstanceId, StringComparer.Ordinal).ToList();
+            var planned = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            PlanCleanup(offline, InstanceCleanupRetainedOffline, cutoff, planned);
+            PlanCleanup(damaged, InstanceCleanupRetainedDamaged, cutoff, planned);
+            summary.Deferred += Math.Max(0, planned.Count - InstanceCleanupMaxDeleted);
+
+            foreach (var candidate in candidates.Where(value => planned.Contains(value.Path)).OrderBy(value => value.LastActivity).ThenBy(value => value.InstanceId, StringComparer.Ordinal).Take(InstanceCleanupMaxDeleted))
+            {
+                var deleted = false;
+                var locked = false;
+                try
+                {
+                    locked = TryWithCurrentUserMutex("Local\\UnityCli.Registry." + candidate.InstanceId, 0, delegate
+                    {
+                        InstanceCleanupCandidate current;
+                        if (!TryInspectCleanupCandidate(candidate.Path, candidate.InstanceId, out current)) return;
+                        if (current.Damaged != candidate.Damaged || current.LastActivity > candidate.LastActivity) return;
+                        File.Delete(candidate.Path);
+                        deleted = true;
+                    });
+                }
+                catch
+                {
+                    deleted = false;
+                }
+                if (deleted) summary.Deleted += 1;
+                else if (!locked || File.Exists(candidate.Path)) summary.Deferred += 1;
+            }
+            summary.Remaining = Math.Max(0, summary.Scanned - summary.Deleted);
+            return summary;
+        }
+
+        private static void PlanCleanup(List<InstanceCleanupCandidate> ordered, int retained, DateTimeOffset cutoff, HashSet<string> planned)
+        {
+            var excess = Math.Max(0, ordered.Count - retained);
+            for (var index = 0; index < ordered.Count; index++)
+            {
+                if (index < excess || ordered[index].LastActivity <= cutoff) planned.Add(ordered[index].Path);
+            }
+        }
+
+        /// <summary>返回false表示活跃、不可确认、链接、占用或不安全路径，调用方必须保留。</summary>
+        private static bool TryInspectCleanupCandidate(string path, string expectedInstanceId, out InstanceCleanupCandidate candidate)
+        {
+            candidate = null;
+            try
+            {
+                var info = new FileInfo(path);
+                if (!info.Exists || (info.Attributes & FileAttributes.ReparsePoint) != 0) return false;
+                var fallbackActivity = new DateTimeOffset(info.LastWriteTimeUtc, TimeSpan.Zero);
+                if (info.Length > RegistryMaxBytes)
+                {
+                    candidate = CleanupCandidate(path, expectedInstanceId, fallbackActivity, true);
+                    return true;
+                }
+
+                Dictionary<string, object> record;
+                try
+                {
+                    record = UnityCliSerializer.Parse(File.ReadAllText(path, Encoding.UTF8)) as Dictionary<string, object>;
+                }
+                catch (FormatException)
+                {
+                    candidate = CleanupCandidate(path, expectedInstanceId, fallbackActivity, true);
+                    return true;
+                }
+                if (record == null || ReadLong(record, "version") != 3L || ReadLong(record, "canonicalizationVersion") != 1L)
+                {
+                    candidate = CleanupCandidate(path, expectedInstanceId, fallbackActivity, true);
+                    return true;
+                }
+                var identity = ReadDictionary(record, "identity");
+                var canonicalPath = ReadString(identity, "canonicalProjectPath");
+                var actualInstanceId = ReadString(identity, "instanceId");
+                if (string.IsNullOrEmpty(canonicalPath)
+                    || !string.Equals(actualInstanceId, expectedInstanceId, StringComparison.Ordinal)
+                    || !string.Equals("unity-" + Sha256Utf8(canonicalPath), expectedInstanceId, StringComparison.Ordinal))
+                {
+                    candidate = CleanupCandidate(path, expectedInstanceId, fallbackActivity, true);
+                    return true;
+                }
+                object rawSessions;
+                var sessionValues = record.TryGetValue("sessions", out rawSessions) ? rawSessions as List<object> : null;
+                if (sessionValues == null)
+                {
+                    candidate = CleanupCandidate(path, expectedInstanceId, fallbackActivity, true);
+                    return true;
+                }
+                var sessions = sessionValues.OfType<Dictionary<string, object>>().ToList();
+                if (sessions.Count != sessionValues.Count || sessions.Any(IsProcessClaimAliveOrUnverifiable)) return false;
+                DateTimeOffset publishedAt;
+                if (!DateTimeOffset.TryParse(ReadString(record, "publishedAt"), CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal, out publishedAt))
+                {
+                    candidate = CleanupCandidate(path, expectedInstanceId, fallbackActivity, true);
+                    return true;
+                }
+                candidate = CleanupCandidate(path, expectedInstanceId, publishedAt, false);
+                return true;
+            }
+            catch (IOException) { return false; }
+            catch (UnauthorizedAccessException) { return false; }
+            catch { return false; }
+        }
+
+        private static InstanceCleanupCandidate CleanupCandidate(string path, string instanceId, DateTimeOffset lastActivity, bool damaged)
+        {
+            return new InstanceCleanupCandidate { Path = path, InstanceId = instanceId, LastActivity = lastActivity, Damaged = damaged };
+        }
+
+        /// <summary>私有Bridge命令让公开instances prune只触发Unity writer，不把删除权交给CLI。</summary>
+        private static void RegisterInstanceCleanupCommand(BridgeCommandRegistry registry)
+        {
+            registry.Register<UnityCli.Protocol.BridgeRequest>(
+                "internal.instances.prune",
+                "internal",
+                true,
+                30000,
+                (request, cancellationToken) =>
+                {
+                    cancellationToken.ThrowIfCancellationRequested();
+                    InstanceCleanupSummary summary;
+                    if (!TryExecuteInstanceCleanup(delegate { BeginDirectEffect(request.RequestId); }, out summary))
+                        throw new BridgeCommandException("E_UNITY_BUSY", "Another Unity instance is cleaning historical instance records.", null, new[] { "Retry unitycli instances prune after the current cleanup finishes." }, true, 100);
+                    var result = new Dictionary<string, object>
+                    {
+                        { "removed", (long)summary.Deleted },
+                        { "remaining", (long)summary.Remaining },
+                        { "deferred", (long)summary.Deferred },
+                        { "scanned", (long)summary.Scanned },
+                        { "truncated", summary.Truncated },
+                        { "retention", new Dictionary<string, object>
+                            {
+                                { "offlineMax", (long)InstanceCleanupRetainedOffline },
+                                { "damagedMax", (long)InstanceCleanupRetainedDamaged },
+                                { "maxAgeDays", (long)InstanceCleanupRetentionDays },
+                                { "scanLimit", (long)InstanceCleanupMaxScanned },
+                                { "deleteLimit", (long)InstanceCleanupMaxDeleted }
+                            }
+                        }
+                    };
+                    RecordDirectCompletionEvidence(request.RequestId, "internal.instances.prune", InstanceCleanupCompletion, result);
+                    return new System.Threading.Tasks.ValueTask<object>(result);
+                });
+        }
+
+        private static bool IsInstanceCleanupCommand(string command)
+        {
+            return string.Equals(command, "internal.instances.prune", StringComparison.Ordinal);
+        }
+
+        private static UnityCliToolCompletionContract InstanceCleanupCompletionContract()
+        {
+            return InstanceCleanupCompletion;
+        }
+
+        private static bool TryInstanceIdFromFileName(string fileName, out string instanceId)
+        {
+            instanceId = null;
+            if (string.IsNullOrEmpty(fileName) || !fileName.EndsWith(".json", StringComparison.OrdinalIgnoreCase)) return false;
+            var value = fileName.Substring(0, fileName.Length - 5);
+            if (!value.StartsWith("unity-", StringComparison.Ordinal) || value.Length != 70) return false;
+            for (var index = 6; index < value.Length; index++)
+            {
+                var ch = value[index];
+                if (!((ch >= '0' && ch <= '9') || (ch >= 'a' && ch <= 'f'))) return false;
+            }
+            instanceId = value;
+            return true;
+        }
+    }
+}
+#endif