Stamp release versions and harden launcher

Add automatic release version stamping and multiple launcher reliability improvements. The Release workflow now runs scripts/Set-ReleaseVersion.ps1 in build jobs to inject tag-derived Version/AssemblyVersion into project metadata; several .csproj/Directory.Build.props and app.manifest files were changed to use a dev placeholder. Introduced AppVersionProvider (and related runtime metadata) to centralize version resolution and updated DeploymentLocator to use it and to prefer package-root/version.json. Launcher startup flow was hardened: added startup success tracking, public-activation recovery path, improved success/fallback semantics, and related IPC handling. UI/UX fixes include OOBE entrance/exit animation improvements (scaling-aware, concurrent fade+translate) and minor window lifecycle reorder in DesktopShellHost. CommandContext now recognizes restart and key=value args. New DesktopTrayService and .trae spec files (spec, checklist, tasks) document shell/tray hardening work. Miscellaneous logging, comments and housekeeping edits across launcher and shared contracts to support the above.

LanMountainDesktop.Launcher/Services/DeploymentLocator.cs

@@ -1,4 +1,4 @@
-using System.Globalization;
+using System.Globalization;
 using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 using LanMountainDesktop.Shared.Contracts.Launcher;
@@ -57,8 +57,8 @@ internal sealed class DeploymentLocator
                     Version = ParseVersionFromDirectory(path),
                     HasCurrentMarker = File.Exists(Path.Combine(path, ".current"))
                 })
-                .OrderBy(x => x.HasCurrentMarker ? 0 : 1)  // .current 标记的排å‰<EFBFBD>é<EFBFBD>¢
-                .ThenByDescending(x => x.Version)  // 然å<EFBFBD>ŽæŒ‰ç‰ˆæœ¬å<EFBFBD>·é™<EFBFBD>åº<EFBFBD>
+                .OrderBy(x => x.HasCurrentMarker ? 0 : 1)  // .current 鏍囪鐨勬帓鍓嶉潰
+                .ThenByDescending(x => x.Version)  // 鐒跺悗鎸夌増鏈彿闄嶅簭
                 .ToList();
 
             if (validInstallations.Count == 0)
@@ -275,7 +275,7 @@ internal sealed class DeploymentLocator
     {
         var executable = OperatingSystem.IsWindows() ? "LanMountainDesktop.exe" : "LanMountainDesktop";
         
-        // 1. 首先查找 app-{version} 目录（生产环境）
+        // 1. 棣栧厛鏌ユ壘 app-{version} 鐩綍锛堢敓浜х幆澧冿級
         var currentDeployment = FindCurrentDeploymentDirectory();
         if (!string.IsNullOrWhiteSpace(currentDeployment))
         {
@@ -299,7 +299,7 @@ internal sealed class DeploymentLocator
             return inParent;
         }
 
-        // 4. å¼€å<EFBFBD>‘模å¼<EFBFBD>：如果å<EFBFBD>¯ç”¨äº†å¼€å<EFBFBD>‘模å¼<EFBFBD>，优先使用ä¿<EFBFBD>存的自定义路径
+        // 4. 寮€鍙戞ā寮忥細濡傛灉鍚敤浜嗗紑鍙戞ā寮忥紝浼樺厛浣跨敤淇濆瓨鐨勮嚜瀹氫箟璺緞
         if (Views.ErrorWindow.CheckDevModeEnabled())
         {
             var savedCustomPath = Views.ErrorWindow.GetSavedCustomHostPath();
@@ -315,7 +315,7 @@ internal sealed class DeploymentLocator
             }
         }
 
-        // 5. å¼€å<EFBFBD>‘模å¼<EFBFBD>：查找主程åº<EFBFBD>项目的输出目录
+        // 5. 寮€鍙戞ā寮忥細鏌ユ壘涓荤▼搴忛」鐩殑杈撳嚭鐩綍
         var devPaths = GetDevelopmentPaths(executable);
         foreach (var devPath in devPaths)
         {
@@ -329,21 +329,21 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 扫æ<EFBFBD><EFBFBD>å¼€å<EFBFBD>‘路径（开å<EFBFBD>‘模å¼<EFBFBD>）
+    /// 鎵弿寮€鍙戣矾寰勶紙寮€鍙戞ā寮忥級
     /// </summary>
     private static string? ScanDevelopmentPaths(string executable)
     {
         var possiblePaths = new[]
         {
-            // ä»?Launcher 项目è¿<EFBFBD>è¡Œ
+            // 浠?Launcher 椤圭洰杩愯
             Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(AppContext.BaseDirectory, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
-            // 从解决方案根目录è¿<EFBFBD>è¡Œ
+            // 浠庤В鍐虫柟妗堟牴鐩綍杩愯
             Path.Combine(AppContext.BaseDirectory, "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(AppContext.BaseDirectory, "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
-            // dev-test 目录
+            // dev-test 鐩綍
             Path.Combine(AppContext.BaseDirectory, "..", "dev-test", "app-1.0.0-dev", executable),
         };
 
@@ -359,22 +359,22 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 获å<EFBFBD>–å¼€å<EFBFBD>‘环境å<EFBFBD>¯èƒ½çš„主程åº<EFBFBD>è·¯å¾?    /// </summary>
+    /// 鑾峰彇寮€鍙戠幆澧冨彲鑳界殑涓荤▼搴忚矾寰?    /// </summary>
     private static IEnumerable<string> GetDevelopmentPaths(string executable)
     {
         var launcherDir = AppContext.BaseDirectory;
         
         var possiblePaths = new[]
         {
-            // ä»?Launcher 项目è¿<EFBFBD>è¡Œï¼?.\LanMountainDesktop\bin\Debug\net10.0\LanMountainDesktop.exe
+            // 浠?Launcher 椤圭洰杩愯锛?.\LanMountainDesktop\bin\Debug\net10.0\LanMountainDesktop.exe
             Path.Combine(launcherDir, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(launcherDir, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
-            // 从解决方案根目录è¿<EFBFBD>行：LanMountainDesktop\bin\Debug\net10.0\LanMountainDesktop.exe
+            // 浠庤В鍐虫柟妗堟牴鐩綍杩愯锛歀anMountainDesktop\bin\Debug\net10.0\LanMountainDesktop.exe
             Path.Combine(launcherDir, "..", "LanMountainDesktop", "bin", "Debug", "net10.0", executable),
             Path.Combine(launcherDir, "..", "LanMountainDesktop", "bin", "Release", "net10.0", executable),
             
-            // ä»?dev-test 目录è¿<EFBFBD>è¡Œ
+            // 浠?dev-test 鐩綍杩愯
             Path.Combine(launcherDir, "..", "dev-test", "app-1.0.0-dev", executable),
         };
 
@@ -409,8 +409,8 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 清ç<EFBFBD>†æ—§ç‰ˆæœ¬éƒ¨ç½²ï¼Œä¿<EFBFBD>留最近的N个版æœ?    /// </summary>
-    /// <param name="minVersionsToKeep">最少ä¿<EFBFBD>留版本数，默è®?ä¸?/param>
+    /// 娓呯悊鏃х増鏈儴缃诧紝淇濈暀鏈€杩戠殑N涓増鏈?    /// </summary>
+    /// <param name="minVersionsToKeep">鏈€灏戜繚鐣欑増鏈暟锛岄粯璁?涓?/param>
     public void CleanupOldDeployments(int minVersionsToKeep = 3)
     {
         try
@@ -438,10 +438,10 @@ internal sealed class DeploymentLocator
 
             Console.WriteLine($"[DeploymentLocator] Found {validDeployments.Count} valid deployments");
 
-            // 确定è¦<EFBFBD>ä¿<EFBFBD>留的版本
+            // 纭畾瑕佷繚鐣欑殑鐗堟湰
             var versionsToKeep = new HashSet<string>();
 
-            // 1. 总是ä¿<EFBFBD>留当å‰<EFBFBD>版本
+            // 1. 鎬绘槸淇濈暀褰撳墠鐗堟湰
             var currentVersion = validDeployments.FirstOrDefault(d => d.IsCurrent);
             if (currentVersion != null)
             {
@@ -449,7 +449,7 @@ internal sealed class DeploymentLocator
                 Console.WriteLine($"[DeploymentLocator] Keep current version: {currentVersion.Path}");
             }
 
-            // 2. ä¿<EFBFBD>留最近的N个有效版本（ä¸<EFBFBD>包括已标记destroy的）
+            // 2. 淇濈暀鏈€杩戠殑N涓湁鏁堢増鏈紙涓嶅寘鎷凡鏍囪destroy鐨勶級
             var activeVersions = validDeployments
                 .Where(d => !d.IsDestroyed)
                 .Take(minVersionsToKeep)
@@ -461,7 +461,7 @@ internal sealed class DeploymentLocator
                 Console.WriteLine($"[DeploymentLocator] Keep recent version: {ver.Path}");
             }
 
-            // 3. ä¿<EFBFBD>留有快照的版本（用于回滚）
+            // 3. 淇濈暀鏈夊揩鐓х殑鐗堟湰锛堢敤浜庡洖婊氾級
             var snapshotDir = Path.Combine(_appRoot, ".launcher", "snapshots");
             if (Directory.Exists(snapshotDir))
             {
@@ -485,17 +485,17 @@ internal sealed class DeploymentLocator
                         }
                         catch
                         {
-                            // 忽略快照解æž<EFBFBD>错误
+                            // 蹇界暐蹇収瑙ｆ瀽閿欒
                         }
                     }
                 }
                 catch
                 {
-                    // 忽略快照目录访问错误
+                    // 蹇界暐蹇収鐩綍璁块棶閿欒
                 }
             }
 
-            // 清ç<EFBFBD>†ä¸<EFBFBD>需è¦<EFBFBD>的版本
+            // 娓呯悊涓嶉渶瑕佺殑鐗堟湰
             foreach (var deployment in validDeployments)
             {
                 if (versionsToKeep.Contains(deployment.Path))
@@ -509,7 +509,7 @@ internal sealed class DeploymentLocator
                         }
                         catch
                         {
-                            // 忽略å<EFBFBD>–消标记失败
+                            // 蹇界暐鍙栨秷鏍囪澶辫触
                         }
                     }
                     continue;
@@ -524,11 +524,11 @@ internal sealed class DeploymentLocator
                     }
                     catch
                     {
-                        // 忽略标记失败
+                        // 蹇界暐鏍囪澶辫触
                     }
                 }
 
-                // å°<EFBFBD>试删除
+                // 灏濊瘯鍒犻櫎
                 try
                 {
                     Directory.Delete(deployment.Path, recursive: true);
@@ -536,7 +536,7 @@ internal sealed class DeploymentLocator
                 }
                 catch
                 {
-                    // 忽略删除失败(å<>¯èƒ½æ–‡ä»¶è¢«å<C2AB> ç”?,下次å<C2A1>¯åŠ¨å†<C3A5>试
+                    // 蹇界暐鍒犻櫎澶辫触(鍙兘鏂囦欢琚崰鐢?,涓嬫鍚姩鍐嶈瘯
                     Console.WriteLine($"[DeploymentLocator] Failed to delete (will retry later): {deployment.Path}");
                 }
             }
@@ -544,12 +544,12 @@ internal sealed class DeploymentLocator
         catch (Exception ex)
         {
             Console.Error.WriteLine($"[DeploymentLocator] Cleanup failed: {ex.Message}");
-            // 忽略清ç<EFBFBD>†å¤±è´¥
+            // 蹇界暐娓呯悊澶辫触
         }
     }
 
     /// <summary>
-    /// 仅清ç<EFBFBD>†å·²æ ‡è®°ä¸?destroy的部署（兼容旧方法）
+    /// 浠呮竻鐞嗗凡鏍囪涓?destroy鐨勯儴缃诧紙鍏煎鏃ф柟娉曪級
     /// </summary>
     [Obsolete("Use CleanupOldDeployments instead")]
     public void CleanupDestroyedDeployments()
@@ -581,36 +581,17 @@ internal sealed class DeploymentLocator
     }
 
     /// <summary>
-    /// 从部署目录读å<EFBFBD>–版本信æ<EFBFBD>?    /// </summary>
+    /// 浠庨儴缃茬洰褰曡鍙栫増鏈俊鎭?    /// </summary>
     public AppVersionInfo GetVersionInfo()
     {
-        var deploymentDir = FindCurrentDeploymentDirectory();
-        if (!string.IsNullOrWhiteSpace(deploymentDir))
-        {
-            var versionFile = Path.Combine(deploymentDir, "version.json");
-            if (File.Exists(versionFile))
+        var executableName = OperatingSystem.IsWindows() ? "LanMountainDesktop.exe" : "LanMountainDesktop";
+        var resolved = AppVersionProvider.ResolveFromPackageRoot(_appRoot, executableName);
+        return string.IsNullOrWhiteSpace(resolved.Version)
+            ? new AppVersionInfo
             {
-                try
-                {
-                    var json = File.ReadAllText(versionFile);
-                    var info = JsonSerializer.Deserialize(json, AppJsonContext.Default.AppVersionInfo);
-                    if (info is not null)
-                    {
-                        return info;
-                    }
-                }
-                catch
-                {
-                }
+                Version = GetCurrentVersion(),
+                Codename = "Administrate"
             }
-        }
-
-        return new AppVersionInfo
-        {
-            Version = GetCurrentVersion(),
-            Codename = "Administrate"
-        };
-}
-
-
+            : resolved;
+    }
 }

LanMountainDesktop.Launcher/Services/LauncherFlowCoordinator.cs

@@ -4,6 +4,7 @@ using LanMountainDesktop.Launcher.Models;
 using LanMountainDesktop.Launcher.Views;
 using LanMountainDesktop.Shared.Contracts.Launcher;
 using LanMountainDesktop.Shared.IPC;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
 
 namespace LanMountainDesktop.Launcher.Services;
 
@@ -12,7 +13,7 @@ internal sealed class LauncherFlowCoordinator
     private static readonly string[] LauncherOnlyOptions =
     [
         "debug", "show-loading-details", "plugins-dir", "source", "result",
-        "app-root", "launch-source",
+        "app-root",
         LauncherIpcConstants.LauncherPidEnvVar,
         LauncherIpcConstants.PackageRootEnvVar,
         LauncherIpcConstants.VersionEnvVar,
@@ -65,6 +66,8 @@ internal sealed class LauncherFlowCoordinator
                 window.Show();
                 return window;
             });
+            var versionInfo = _deploymentLocator.GetVersionInfo();
+            splashWindow.SetVersionInfo(versionInfo.Version, versionInfo.Codename);
             var reporter = (ISplashStageReporter)splashWindow;
 
             LoadingDetailsWindow? loadingDetailsWindow = null;
@@ -77,10 +80,11 @@ internal sealed class LauncherFlowCoordinator
                 });
             }
 
-            var visibilityTcs = new TaskCompletionSource<StartupStage>(TaskCreationOptions.RunContinuationsAsynchronously);
+            var successTcs = new TaskCompletionSource<StartupSuccessState>(TaskCreationOptions.RunContinuationsAsynchronously);
             var activationFailedTcs = new TaskCompletionSource<string>(TaskCreationOptions.RunContinuationsAsynchronously);
             var lastStage = StartupStage.Initializing;
             var lastStageMessage = "launcher-started";
+            var startupSuccessTracker = new StartupSuccessTracker(_context);
 
             var loadingState = new LoadingStateMessage();
             using var ipcClient = new LanMountainDesktopIpcClient();
@@ -105,15 +109,14 @@ internal sealed class LauncherFlowCoordinator
                         reporter.Report(MapStartupStageToSplashStage(message.Stage), message.Message ?? message.Stage.ToString());
                         loadingDetailsWindow?.UpdateLoadingState(loadingState);
 
-                        switch (message.Stage)
+                        if (startupSuccessTracker.TryResolve(message.Stage, out var successState))
                         {
-                            case StartupStage.DesktopVisible:
-                            case StartupStage.ActivationRedirected:
-                                visibilityTcs.TrySetResult(message.Stage);
-                                break;
-                            case StartupStage.ActivationFailed:
-                                activationFailedTcs.TrySetResult(message.Message ?? "activation_failed");
-                                break;
+                            successTcs.TrySetResult(successState);
+                        }
+
+                        if (message.Stage == StartupStage.ActivationFailed)
+                        {
+                            activationFailedTcs.TrySetResult(message.Message ?? "activation_failed");
                         }
                     }
                     catch (Exception ex)
@@ -197,22 +200,20 @@ internal sealed class LauncherFlowCoordinator
 
                 var processExitTask = launchOutcome.Process.WaitForExitAsync();
                 var completedTask = await Task.WhenAny(
-                    visibilityTcs.Task,
+                    successTcs.Task,
                     activationFailedTcs.Task,
                     processExitTask,
                     Task.Delay(TimeSpan.FromSeconds(30))).ConfigureAwait(false);
 
-                if (completedTask == visibilityTcs.Task)
+                if (completedTask == successTcs.Task)
                 {
-                    var stage = await visibilityTcs.Task.ConfigureAwait(false);
+                    var successState = await successTcs.Task.ConfigureAwait(false);
                     await CloseWindowsAsync(splashWindow, loadingDetailsWindow).ConfigureAwait(false);
                     return BuildResult(
                         success: true,
                         stage: "launch",
-                        code: stage == StartupStage.ActivationRedirected ? "activation_redirected" : "ok",
-                        message: stage == StartupStage.ActivationRedirected
-                            ? "Launcher activation was redirected to the existing desktop instance."
-                            : "Desktop is visible and ready.",
+                        code: successState.Code,
+                        message: successState.Message,
                         details: MergeDetails(launcherContextDetails, launchOutcome.Details));
                 }
 
@@ -230,7 +231,7 @@ internal sealed class LauncherFlowCoordinator
                 if (completedTask == processExitTask)
                 {
                     var exitCode = launchOutcome.Process.ExitCode;
-                    Logger.Warn($"Host exited before desktop became visible. ExitCode={exitCode}.");
+                    Logger.Warn($"Host exited before startup success criteria were met. ExitCode={exitCode}.");
 
                     if (exitCode is HostExitCodes.SecondaryActivationFailed or HostExitCodes.RestartLockNotAcquired)
                     {
@@ -249,19 +250,41 @@ internal sealed class LauncherFlowCoordinator
                         code: exitCode == HostExitCodes.SecondaryActivationSucceeded ? "activation_redirected" : "host_exited_early",
                         message: exitCode == HostExitCodes.SecondaryActivationSucceeded
                             ? "Host redirected activation to the existing desktop instance."
-                            : $"Host exited before the desktop became visible. ExitCode={exitCode}.",
+                            : $"Host exited before the required startup state was reported. ExitCode={exitCode}.",
                         details: MergeDetails(launcherContextDetails, MergeDetails(launchOutcome.Details, new Dictionary<string, string>
                         {
                             ["exitCode"] = exitCode.ToString()
                         })));
                 }
 
+                if (connected && !launchOutcome.Process.HasExited)
+                {
+                    var recoveryOutcome = await TryRecoverWithPublicActivationAsync(
+                        ipcClient,
+                        launchOutcome.Process,
+                        successTcs.Task,
+                        startupSuccessTracker).ConfigureAwait(false);
+                    if (recoveryOutcome is not null)
+                    {
+                        await CloseWindowsAsync(splashWindow, loadingDetailsWindow).ConfigureAwait(false);
+                        return BuildResult(
+                            success: true,
+                            stage: "launch",
+                            code: recoveryOutcome.Code,
+                            message: recoveryOutcome.Message,
+                            details: MergeDetails(launcherContextDetails, MergeDetails(launchOutcome.Details, new Dictionary<string, string>
+                            {
+                                ["recoveryActivationAttempted"] = bool.TrueString
+                            })));
+                    }
+                }
+
                 await CloseWindowsAsync(splashWindow, loadingDetailsWindow).ConfigureAwait(false);
                 return BuildResult(
                     success: false,
                     stage: "launch",
                     code: "desktop_not_visible",
-                    message: "Host process started, but the desktop never became visible within 30 seconds.",
+                    message: "Host process started, but it never reached the required startup state within 30 seconds.",
                     details: MergeDetails(launcherContextDetails, MergeDetails(launchOutcome.Details, new Dictionary<string, string>
                     {
                         ["ipcStage"] = lastStage.ToString(),
@@ -452,6 +475,11 @@ internal sealed class LauncherFlowCoordinator
                 firstDetails);
         }
 
+        if (firstAttempt.ExitCode == HostExitCodes.SecondaryActivationSucceeded)
+        {
+            return BuildOutcomeFromAttempt(resolution, firstAttempt, null);
+        }
+
         if (fallbackMode is null)
         {
             return BuildOutcomeFromAttempt(resolution, firstAttempt, null);
@@ -749,8 +777,10 @@ internal sealed class LauncherFlowCoordinator
         StartupStage.Initializing => "initializing",
         StartupStage.LoadingSettings => "settings",
         StartupStage.LoadingPlugins => "plugins",
+        StartupStage.TrayReady => "shell",
         StartupStage.InitializingUI => "ui",
         StartupStage.ShellInitialized => "shell",
+        StartupStage.BackgroundReady => "ready",
         StartupStage.DesktopVisible => "ready",
         StartupStage.ActivationRedirected => "activation",
         StartupStage.ActivationFailed => "error",
@@ -936,6 +966,40 @@ internal sealed class LauncherFlowCoordinator
         return true;
     }
 
+    private static async Task<StartupSuccessState?> TryRecoverWithPublicActivationAsync(
+        LanMountainDesktopIpcClient ipcClient,
+        Process hostProcess,
+        Task<StartupSuccessState> successTask,
+        StartupSuccessTracker startupSuccessTracker)
+    {
+        try
+        {
+            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
+            var activationAccepted = await shellProxy.ActivateMainWindowAsync().ConfigureAwait(false);
+            if (!activationAccepted)
+            {
+                return null;
+            }
+
+            var completedTask = await Task.WhenAny(successTask, Task.Delay(TimeSpan.FromSeconds(5))).ConfigureAwait(false);
+            if (completedTask == successTask)
+            {
+                return await successTask.ConfigureAwait(false);
+            }
+
+            if (!hostProcess.HasExited)
+            {
+                return startupSuccessTracker.BuildRecoverySuccessState();
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Public activation recovery failed: {ex.Message}");
+        }
+
+        return null;
+    }
+
     private enum HostStartMode
     {
         ShellExecute,
@@ -977,4 +1041,108 @@ internal sealed class LauncherFlowCoordinator
         public static HostLaunchOutcome FromProcess(Process process, LauncherResult result, Dictionary<string, string> details) =>
             new(result, process, null, details);
     }
+
+    private sealed class StartupSuccessTracker
+    {
+        private readonly LaunchSuccessPolicy _policy;
+        private bool _trayReady;
+        private bool _backgroundReady;
+
+        public StartupSuccessTracker(CommandContext context)
+        {
+            var restartPresentation = LauncherRuntimeMetadata.GetRestartPresentationMode(context.RawArgs);
+            var isRestartLaunch = string.Equals(context.LaunchSource, "restart", StringComparison.OrdinalIgnoreCase);
+
+            _policy = !isRestartLaunch
+                ? LaunchSuccessPolicy.Foreground
+                : restartPresentation switch
+                {
+                    RestartPresentationMode.Tray => LaunchSuccessPolicy.RestartTray,
+                    RestartPresentationMode.Minimized => LaunchSuccessPolicy.RestartBackground,
+                    _ => LaunchSuccessPolicy.Foreground
+                };
+        }
+
+        public bool TryResolve(StartupStage stage, out StartupSuccessState successState)
+        {
+            switch (stage)
+            {
+                case StartupStage.ActivationRedirected:
+                    successState = new StartupSuccessState(
+                        stage,
+                        "activation_redirected",
+                        "Launcher activation was redirected to the existing desktop instance.");
+                    return true;
+
+                case StartupStage.DesktopVisible:
+                    successState = new StartupSuccessState(
+                        stage,
+                        _policy == LaunchSuccessPolicy.Foreground ? "ok" : "desktop_visible_fallback",
+                        _policy == LaunchSuccessPolicy.Foreground
+                            ? "Desktop is visible and ready."
+                            : "Desktop recovered in a visible state.");
+                    return true;
+
+                case StartupStage.TrayReady:
+                    _trayReady = true;
+                    break;
+
+                case StartupStage.BackgroundReady:
+                    _backgroundReady = true;
+                    break;
+            }
+
+            if (_policy == LaunchSuccessPolicy.RestartBackground && _backgroundReady)
+            {
+                successState = new StartupSuccessState(
+                    StartupStage.BackgroundReady,
+                    "background_ready",
+                    "Desktop restart completed in the background.");
+                return true;
+            }
+
+            if (_policy == LaunchSuccessPolicy.RestartTray && _trayReady && _backgroundReady)
+            {
+                successState = new StartupSuccessState(
+                    StartupStage.BackgroundReady,
+                    "background_ready",
+                    "Desktop restart completed with tray recovery ready.");
+                return true;
+            }
+
+            successState = default!;
+            return false;
+        }
+
+        public StartupSuccessState BuildRecoverySuccessState()
+        {
+            return _policy switch
+            {
+                LaunchSuccessPolicy.RestartTray => new StartupSuccessState(
+                    StartupStage.DesktopVisible,
+                    "recovery_activation_requested",
+                    "Launcher requested a visible recovery because the background restart never confirmed tray readiness."),
+                LaunchSuccessPolicy.RestartBackground => new StartupSuccessState(
+                    StartupStage.DesktopVisible,
+                    "recovery_activation_requested",
+                    "Launcher requested a visible recovery because the background restart never confirmed readiness."),
+                _ => new StartupSuccessState(
+                    StartupStage.DesktopVisible,
+                    "recovery_activation_requested",
+                    "Launcher requested a visible recovery from the running desktop instance.")
+            };
+        }
+    }
+
+    private sealed record StartupSuccessState(
+        StartupStage Stage,
+        string Code,
+        string Message);
+
+    private enum LaunchSuccessPolicy
+    {
+        Foreground,
+        RestartBackground,
+        RestartTray
+    }
 }