changed.对启动器重构的尝试

Co-authored-by: Cursor <cursoragent@cursor.com>

.cursor/plans/launcher_单项目解耦_302f1ec6.plan.md

@@ -0,0 +1,432 @@
+---
+name: Launcher 单项目解耦
+overview: 在保持单一 LanMountainDesktop.Launcher 项目、单一 exe、零部署风险的前提下，按职责域增量重构：目录分层、RunAsync→Pipeline+Phase、UpdateEngine→策略类、App→纯 Avalonia+LauncherOrchestrator；执行过程中由 Agent 自主 Git 提交，每域可编译可测。
+todos:
+  - id: phase-a-diagnostics
+    content: Phase A：Startup 诊断 + HostStartupMonitor 独立类 + AOT 启动检测竞态修复 + 测试
+    status: completed
+  - id: phase-b-directory
+    content: Phase B1：职责域目录迁移（Deployment/Update/Startup/Oobe/Plugins/Infrastructure），零逻辑变更，提交
+    status: completed
+  - id: phase-b-pipeline
+    content: Phase B2：RunAsync→LaunchPipeline+ILaunchPhase，引入 LauncherOrchestrator，删除 LauncherFlowCoordinator，提交
+    status: completed
+  - id: phase-b-app-slim
+    content: Phase B3：App.axaml.cs 精简为纯 Avalonia 初始化 + 委托 LauncherOrchestrator，提交
+    status: completed
+  - id: phase-c-di
+    content: Phase C：LauncherServiceRegistration + 轻量 MS DI，统一 CLI/GUI 装配，提交
+    status: completed
+  - id: phase-d-update-split
+    content: Phase D：UpdateEngineService→门面+策略类（Verifier/Activator/Rollback 等），提交
+    status: completed
+  - id: phase-e-guardrails
+    content: Phase E：LauncherArchitectureTests + 文档 + AOT 回归，提交
+    status: completed
+isProject: false
+---
+
+# Launcher 单项目内部解耦改造计划（执行版）
+
+## 0. 硬性约束
+
+
+| 约束           | 说明                                                                                                                                                        |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **单项目**      | 仅 `[LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj](LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj)`，不新建 Launcher.* 独立程序集 |
+| **单 exe**    | 仍只发布 `LanMountainDesktop.Launcher.exe`（AOT 单文件）                                                                                                           |
+| **零部署风险**    | 不改变安装包目录结构、不引入新进程、不改变 Public IPC / Coordinator IPC 拓扑与契约                                                                                                  |
+| **增量重构**     | 一个职责域一域推进，每步 `dotnet build` + 相关 `dotnet test` 通过后再进下一步                                                                                                   |
+| **单进程性能**    | 模块间仅 in-process 接口调用，不为解耦新增 IPC                                                                                                                           |
+| **未来可拆**     | 各域暴露 `I`* 接口，将来若需多进程可直接复用契约                                                                                                                               |
+| **Git 自主提交** | Agent 在每个职责域完成且验证通过后 **自动 commit**，无需用户手动提交（见 §8）                                                                                                         |
+
+
+外部共享库 `[LanMountainDesktop.PluginPackaging](LanMountainDesktop.PluginPackaging/)` 保留（Host + Launcher CLI 共用），不属于 Launcher 拆分。
+
+---
+
+## 1. 验收标准（必须全部满足）
+
+### 1.1 零部署风险
+
+- Inno Setup / CI 产物仍只有：`LanMountainDesktop.Launcher.exe` + `app-{version}/` + `.launcher/`
+- Host 调用 Launcher 的 CLI 参数、`launch-source`、`apply-update` 路径不变
+- Public IPC routes（`lanmountain.launcher.startup-progress`、`loading-state`）与 Coordinator pipe 不变
+- VeloPack / 更新 apply 状态机（`.current/.partial/.destroy`）行为不变
+
+### 1.2 增量可验证
+
+- 每个 Phase 结束：编译绿 + 该域新增/既有测试绿
+- 允许「纯移动文件」的 PR 单独提交，行为 diff 为零
+
+### 1.3 测试友好
+
+- `Startup/`、`Update/`、`Deployment/` 内类型 **无 Avalonia 依赖**，可独立单元测试
+- 每个 `ILaunchPhase`、每个 Update 策略类各有对应测试类
+- 保留并扩展现有 `[LauncherStartupTimeoutPolicyTests](LanMountainDesktop.Tests/LauncherStartupTimeoutPolicyTests.cs)`、`[LauncherMultiInstancePolicyTests](LanMountainDesktop.Tests/LauncherMultiInstancePolicyTests.cs)`
+
+### 1.4 启动性能
+
+- Pipeline 阶段为同步/异步方法调用链，不引入额外进程或网络
+- DI 容器仅在进程入口构建一次；Stage/Phase 实例可复用 Singleton
+
+### 1.5 代码结构目标
+
+
+| 对象                                  | 当前（实测）                                       | 目标                                                  |
+| ----------------------------------- | -------------------------------------------- | --------------------------------------------------- |
+| `LauncherFlowCoordinator` 全 partial | ~1880 行（859+568+279+…）                       | **删除**；逻辑迁入 Pipeline + Phases                       |
+| `RunAsync()` 等价逻辑                   | 跨 partial ~800+ 行 while/阶段混杂                 | **≤80 行** 编排入口，细节在各 Phase                           |
+| `UpdateEngineService`               | ~1622 行                                      | 门面 **≤200 行** + 6 个策略类各 **≤300 行**                  |
+| `App.axaml.cs`                      | ~258 行（已部分瘦身）                                | **≤120 行**：纯 Avalonia + 一行委托 `LauncherOrchestrator` |
+| `LauncherOrchestrator`              | 不存在（逻辑在 Coordinator + CompositionRoot 546 行） | **≤250 行**：GUI 入口编排                                 |
+| `LauncherCompositionRoot`           | ~546 行                                       | **≤150 行**：仅 DI 构建 + 入口分发                           |
+
+
+---
+
+## 2. 目标架构
+
+### 2.1 核心类型关系
+
+```mermaid
+flowchart TB
+    Program --> EntryRouter
+    App --> LauncherOrchestrator
+    EntryRouter --> LauncherOrchestrator
+    LauncherOrchestrator --> LaunchPipeline
+    LaunchPipeline --> Phase1[CleanupPhase]
+    LaunchPipeline --> Phase2[OobeGatePhase]
+    LaunchPipeline --> Phase3[ApplyUpdatePhase]
+    LaunchPipeline --> Phase4[LaunchHostPhase]
+    LaunchPipeline --> Phase5[MonitorStartupPhase]
+    Phase3 --> IUpdateEngine
+    Phase4 --> IDeploymentLocator
+    Phase5 --> IHostStartupMonitor
+    LauncherCompositionRoot --> ServiceProvider
+    ServiceProvider --> LaunchPipeline
+```
+
+
+
+**命名约定：**
+
+- `**LauncherOrchestrator`**：GUI 生命周期内的唯一编排入口（取代 `LauncherFlowCoordinator` 对外角色）
+- `**LaunchPipeline**`：按序执行 `ILaunchPhase` 列表
+- `**ILaunchPhase**`：原 `ILaunchPipelineStage`；每个 Phase 对应原 `RunAsync` 中一个职责段
+
+### 2.2 职责域目录（单项目内）
+
+```
+LanMountainDesktop.Launcher/
+├── Program.cs                         # CLI / GUI 路由
+├── App.axaml.cs                       # 纯 Avalonia（≤120 行）
+├── Shell/
+│   ├── LauncherOrchestrator.cs        # GUI 编排入口
+│   ├── LauncherCompositionRoot.cs     # DI + Entry 分发
+│   ├── LaunchPipeline.cs
+│   ├── Phases/                        # ILaunchPhase 实现
+│   │   ├── CleanupDeploymentsPhase.cs
+│   │   ├── OobeGatePhase.cs
+│   │   ├── ApplyPendingUpdatePhase.cs
+│   │   ├── LaunchHostPhase.cs
+│   │   └── MonitorStartupPhase.cs
+│   └── EntryHandlers/                 # apply-update / air-app-broker / attach
+├── Deployment/
+├── Update/
+│   ├── IUpdateEngine.cs
+│   ├── UpdateEngineFacade.cs          # 原 UpdateEngineService 门面
+│   └── Strategies/
+│       ├── PendingUpdateDetector.cs
+│       ├── UpdatePackageVerifier.cs
+│       ├── DeploymentActivator.cs
+│       ├── UpdateSnapshotStore.cs
+│       ├── RollbackStrategy.cs
+│       └── IncomingArtifactsCleaner.cs
+├── Startup/
+├── Oobe/
+├── Ipc/
+├── AirApp/
+├── Plugins/
+├── Infrastructure/
+├── Models/
+└── Views/
+```
+
+### 2.3 模块依赖规则
+
+- `Deployment/`、`Update/`、`Startup/`：**禁止** `using Avalonia`
+- `Views/`：**禁止** 引用具体 `UpdateEngineFacade` / `DeploymentLocator`（仅接口或 Orchestrator）
+- 跨域：**仅通过 `I`* 接口**；Orchestrator/Pipeline 负责装配
+
+### 2.4 与 Host 边界（不变）
+
+
+| 能力                         | Owner                          |
+| -------------------------- | ------------------------------ |
+| OOBE / Splash / 多实例 / 启动检测 | Launcher `Startup/` + `Shell/` |
+| 更新 apply / rollback        | Launcher `Update/`             |
+| 插件市场 / pending             | Host + PluginPackaging         |
+| 更新 download                | Host → spawn Launcher apply    |
+
+
+---
+
+## 3. 三大核心拆分（用户指定）
+
+### 3.1 拆分 `LauncherFlowCoordinator`：`RunAsync` → Pipeline + Phase
+
+**现状：** 逻辑分散在 4 个 partial，等效一个 1800+ 行 God Class；`RunAsync` 内含清理、OOBE、更新、启动、IPC 监听、超时 while-loop、多实例分支。
+
+**目标 API（单项目 `Shell/` 内）：**
+
+```csharp
+internal interface ILaunchPhase
+{
+    string PhaseId { get; }
+    /// <returns>null = 继续下一阶段；非 null = 管道终止并返回结果</returns>
+    Task<LauncherResult?> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken);
+}
+
+internal sealed class LaunchPipeline
+{
+    public LaunchPipeline(IEnumerable<ILaunchPhase> phases) { ... }
+    public Task<LauncherResult> RunAsync(LaunchContext context, CancellationToken ct);
+}
+```
+
+**Phase 映射（与原 RunAsync 步骤一一对应）：**
+
+
+| Phase                     | 原 RunAsync 段                            | 产出                            |
+| ------------------------- | --------------------------------------- | ----------------------------- |
+| `CleanupDeploymentsPhase` | `CleanupOldDeployments`                 | 无 UI                          |
+| `ExistingHostProbePhase`  | 多实例 / Public IPC 探测                     | 可短路成功                         |
+| `ApplyPendingUpdatePhase` | `_updateEngine.ApplyPendingUpdateAsync` | 失败仍继续                         |
+| `OobeGatePhase`           | migration + OOBE steps                  | UI via `ILauncherUiPresenter` |
+| `LaunchHostPhase`         | `LaunchHostWithIpcAsync`                | Process + plan                |
+| `MonitorStartupPhase`     | while-loop + IPC + timeout              | 调用 `IHostStartupMonitor`      |
+
+
+`**LauncherOrchestrator` 职责：**
+
+- 接收 `SplashWindow`、构建 `LaunchContext`（含 reporter、attempt registry、coordinator server）
+- 调用 `LaunchPipeline.RunAsync`
+- 管理 Splash/Error 窗口生命周期（委托 `ILauncherUiPresenter`）
+- **不含** 更新/部署/IPC 细节
+
+**删除清单：** `LauncherFlowCoordinator.cs` 及全部 partial 文件。
+
+---
+
+### 3.2 拆分 `UpdateEngineService` → 门面 + 策略类
+
+**现状：** ~1622 行单文件，混合检测、验签、解压、激活、快照、回滚、清理。
+
+**目标结构：**
+
+```
+Update/
+├── IUpdateEngine.cs                    # 对外契约（未来多进程可原样抽出）
+├── UpdateEngineFacade.cs               # 门面，编排策略，≤200 行
+└── Strategies/
+    ├── IUpdateStrategy.cs              # 可选：各策略统一接口
+    ├── PendingUpdateDetector.cs        # CheckPendingUpdate
+    ├── UpdatePackageVerifier.cs        # manifest + RSA 签名
+    ├── UpdatePackageExtractor.cs       # 解压 / 增量复用
+    ├── DeploymentActivator.cs          # .current / .partial / .destroy
+    ├── UpdateSnapshotStore.cs          # snapshots 读写
+    ├── RollbackStrategy.cs             # rollback CLI/GUI
+    └── IncomingArtifactsCleaner.cs     # CleanupIncomingArtifacts
+```
+
+**门面方法映射：**
+
+
+| 原 `UpdateEngineService` 公开方法 | 委托策略                                                   |
+| ---------------------------- | ------------------------------------------------------ |
+| `CheckPendingUpdate()`       | `PendingUpdateDetector`                                |
+| `ApplyPendingUpdateAsync()`  | Detector → Verifier → Extractor → Activator → Snapshot |
+| `RollbackLatest()`           | `RollbackStrategy`                                     |
+| `CleanupIncomingArtifacts()` | `IncomingArtifactsCleaner`                             |
+| `DownloadAsync()`（若有）        | 保持或拆 `UpdateDownloader`                                |
+
+
+**测试：** 每个 Strategy 独立 mock `IDeploymentLocator` / 文件系统，不启 Avalonia。
+
+---
+
+### 3.3 精简 `App.axaml.cs` → 纯 Avalonia + `LauncherOrchestrator`
+
+**现状：** ~258 行，仍含 apply-update、air-app-broker、preview、coordinator attach 等分支。
+
+**目标结构：**
+
+```csharp
+// App.axaml.cs 目标形态（概念）
+public override void OnFrameworkInitializationCompleted()
+{
+    if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
+    {
+        var context = LauncherRuntimeContext.Current;
+        var mode = LauncherEntryModeResolver.Resolve(context);
+        _ = LauncherOrchestrator.RunAsync(desktop, context, mode);
+    }
+    base.OnFrameworkInitializationCompleted();
+}
+```
+
+**从 App 迁出的逻辑 → `Shell/EntryHandlers/`：**
+
+
+| 现 App 分支          | 新 Handler                              |
+| ----------------- | -------------------------------------- |
+| `launch` + splash | `GuiLaunchEntryHandler` → Orchestrator |
+| `apply-update`    | `ApplyUpdateEntryHandler`              |
+| `air-app-broker`  | `AirAppBrokerEntryHandler`             |
+| debug preview     | `PreviewEntryHandler`                  |
+
+
+**验收：** `App.axaml.cs` ≤120 行；不含 `new UpdateEngineService` / `new DeploymentLocator` / while-loop。
+
+---
+
+## 4. 分阶段执行顺序与 Git 提交点
+
+```mermaid
+flowchart LR
+    A[Phase A Startup] --> B1[Phase B1 目录迁移]
+    B1 --> B2[Phase B2 Pipeline+Orchestrator]
+    B2 --> B3[Phase B3 App 精简]
+    B3 --> C[Phase C DI]
+    B1 --> D[Phase D Update 策略拆分]
+    C --> E[Phase E 守卫+文档+AOT回归]
+    D --> E
+```
+
+
+
+### Phase A：Startup 子系统 + AOT 生产 bug（优先）
+
+- 抽出 `Startup/HostStartupMonitor.cs`（从 partial 独立）
+- 修复 IPC 连接退避、成功判定统一走 `StartupSuccessTracker`
+- Host 侧 `DesktopVisible` 上报对齐（仅日志/时序，不改 IPC 契约）
+- 测试 + `**git commit**`: `fix(launcher): extract HostStartupMonitor and harden startup detection`
+
+### Phase B1：目录迁移（零逻辑变更）
+
+- 物理移动文件到 `Deployment/`、`Update/`、`Startup/` 等，更新 namespace
+- `dotnet build` + test
+- `**git commit**`: `refactor(launcher): reorganize into responsibility folders`
+
+### Phase B2：Pipeline + Phase + LauncherOrchestrator
+
+- 实现 `ILaunchPhase`、`LaunchPipeline`、`LauncherOrchestrator`
+- 逐 Phase 从 Coordinator 迁移逻辑（可先并行运行对照测试）
+- 删除 `LauncherFlowCoordinator*`
+- `**git commit**`: `refactor(launcher): replace LauncherFlowCoordinator with LaunchPipeline`
+
+### Phase B3：App.axaml.cs 精简
+
+- EntryHandlers 提取；App 仅 Avalonia + Orchestrator 委托
+- `**git commit**`: `refactor(launcher): slim App.axaml.cs to Avalonia shell only`
+
+### Phase C：轻量 DI
+
+- `LauncherServiceRegistration.cs` + `Microsoft.Extensions.DependencyInjection`
+- Program / CliHost / CompositionRoot 统一 `ServiceProvider`
+- `**git commit**`: `refactor(launcher): add composition-root DI wiring`
+
+### Phase D：UpdateEngine 策略拆分（可与 B2 并行，依赖 B1）
+
+- 策略类提取 + `UpdateEngineFacade`
+- 删除原巨型 `UpdateEngineService.cs`
+- 每策略测试
+- `**git commit**`: `refactor(launcher): split UpdateEngine into strategy classes`
+
+### Phase E：守卫 + 文档 + AOT 回归
+
+- `LauncherArchitectureTests`（命名空间依赖规则）
+- 更新 `[docs/LAUNCHER.md](docs/LAUNCHER.md)`、`[.trae/specs/launcher-shell-hardening/spec.md](.trae/specs/launcher-shell-hardening/spec.md)`
+- AOT publish 本地 smoke：launch / apply-update / 多实例 / 启动检测
+- `**git commit**`: `docs(launcher): document module boundaries and add architecture tests`
+
+---
+
+## 5. Phase / Service 测试矩阵
+
+
+| 组件                      | 测试文件                         | 覆盖点                               |
+| ----------------------- | ---------------------------- | --------------------------------- |
+| `StartupSuccessTracker` | `StartupSuccessTrackerTests` | Foreground/Tray/Background policy |
+| `HostStartupMonitor`    | `HostStartupMonitorTests`    | 超时、IPC 延迟、ShellStatus 轮询          |
+| `LaunchPipeline`        | `LaunchPipelineTests`        | Phase 短路、失败传播                     |
+| 各 `ILaunchPhase`        | `*PhaseTests`                | 单阶段 mock                          |
+| `PendingUpdateDetector` | `PendingUpdateDetectorTests` | 无 pending / corrupt               |
+| `DeploymentActivator`   | `DeploymentActivatorTests`   | 标记文件状态机                           |
+| `RollbackStrategy`      | `RollbackStrategyTests`      | 快照回退                              |
+| 命名空间规则                  | `LauncherArchitectureTests`  | 无 Avalonia 泄漏                     |
+
+
+---
+
+## 6. 明确不做
+
+- 不新建 csproj（Launcher.Deployment 等）
+- 不新建 exe / Windows Service
+- 不改变 Public IPC / Coordinator IPC 协议
+- 不把插件市场安装迁回 Launcher
+- 不为模块间通信引入新 IPC（仅保留现有 Host↔Launcher 契约）
+
+---
+
+## 7. 风险与缓解
+
+
+| 风险              | 缓解                                                                 |
+| --------------- | ------------------------------------------------------------------ |
+| 大规模移动 merge 冲突  | B1 独立 commit，零逻辑变更                                                 |
+| Pipeline 迁移行为回归 | 先写 Phase 级测试再迁代码；保留 `LMD_LAUNCHER_LEGACY_COORDINATOR=1` 开关一个版本（可选） |
+| AOT + DI        | 显式注册，禁止反射扫描；`PublishAot` CI 步骤验证                                   |
+| Update 拆分遗漏路径   | CLI `update *` 与 GUI apply-update 同一 `IUpdateEngine` 门面            |
+
+
+---
+
+## 8. Git 工作流（Agent 自主提交）
+
+**原则：** 每个 Phase 验证通过后立即提交；不累积巨型 uncommitted diff。
+
+**Commit 前检查（每个 commit 必做）：**
+
+```bash
+dotnet build LanMountainDesktop.slnx -c Debug
+dotnet test LanMountainDesktop.slnx -c Debug --filter "FullyQualifiedName~Launcher"
+```
+
+**Commit message 风格（与仓库一致）：**
+
+```
+refactor(launcher): replace LauncherFlowCoordinator with LaunchPipeline
+
+Pipeline + Phase pattern; LauncherOrchestrator becomes GUI entry.
+No deployment or IPC contract changes.
+```
+
+**禁止：** `git push --force`、修改 git config、跳过 hooks（除非 hook 失败需修复后新 commit）。
+
+**建议分支：** `refactor/launcher-internal-modularization`（单 long-lived 分支，按 Phase 连续 commit；或每 Phase 一个 PR 由用户决定 merge 时机）。
+
+---
+
+## 9. 整体完成定义（Definition of Done）
+
+- 无 `LauncherFlowCoordinator` 源文件
+- `App.axaml.cs` ≤120 行，仅 Avalonia + Orchestrator 委托
+- `UpdateEngineService` 巨型文件已替换为 Facade + Strategies
+- 职责域目录就位，架构测试通过
+- 全量 Launcher 相关测试 + AOT publish smoke 通过
+- 安装包结构与 IPC 拓扑与重构前一致
+- 每个 Phase 有对应 Git commit，工作区 clean
+

.github/workflows/release.yml

@@ -98,10 +98,8 @@ jobs:
       matrix:
         include:
           - arch: x64
-            self_contained: true
             suffix: ''
           - arch: x86
-            self_contained: true
             suffix: ''
     name: Build_Windows_${{ matrix.arch }}${{ matrix.suffix }}
 
@@ -167,91 +165,55 @@ jobs:
 
       - name: Publish Main App
         run: |
-          $selfContained = "${{ matrix.self_contained }}" -eq "true"
-          $publishDir = if ($selfContained) { "publish/windows-${{ matrix.arch }}" } else { "publish/windows-${{ matrix.arch }}-lite" }
+          $publishDir = "publish/windows-${{ matrix.arch }}"
 
-          if ($selfContained) {
-            dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
-              -c Release `
-              -o ./$publishDir `
-              --self-contained `
-              -r win-${{ matrix.arch }} `
-              -p:PublishSingleFile=false `
-              -p:DebugType=none `
-              -p:DebugSymbols=false `
-              -p:SkipAirAppHostBuild=true `
-              -p:PublishTrimmed=false `
-              -p:PublishReadyToRun=false `
-              -p:Version=${{ needs.prepare.outputs.version }} `
-              -p:AssemblyVersion=${{ needs.prepare.outputs.assembly_version }} `
-              -p:FileVersion=${{ needs.prepare.outputs.assembly_version }} `
-              -p:InformationalVersion=${{ needs.prepare.outputs.informational_version }}
-          } else {
-            dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
-              -c Release `
-              -o ./$publishDir `
-              --self-contained:false `
-              -p:PublishSingleFile=false `
-              -p:DebugType=none `
-              -p:DebugSymbols=false `
-              -p:SkipAirAppHostBuild=true `
-              -p:PublishTrimmed=false `
-              -p:PublishReadyToRun=false `
-              -p:Version=${{ needs.prepare.outputs.version }} `
-              -p:AssemblyVersion=${{ needs.prepare.outputs.assembly_version }} `
-              -p:FileVersion=${{ needs.prepare.outputs.assembly_version }} `
-              -p:InformationalVersion=${{ needs.prepare.outputs.informational_version }}
-          }
+          dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
+            -c Release `
+            -o ./$publishDir `
+            --self-contained:false `
+            -r win-${{ matrix.arch }} `
+            -p:SelfContained=false `
+            -p:PublishSingleFile=false `
+            -p:DebugType=none `
+            -p:DebugSymbols=false `
+            -p:SkipAirAppHostBuild=true `
+            -p:PublishTrimmed=false `
+            -p:PublishReadyToRun=false `
+            -p:Version=${{ needs.prepare.outputs.version }} `
+            -p:AssemblyVersion=${{ needs.prepare.outputs.assembly_version }} `
+            -p:FileVersion=${{ needs.prepare.outputs.assembly_version }} `
+            -p:InformationalVersion=${{ needs.prepare.outputs.informational_version }}
         shell: pwsh
 
       - name: Publish AirAppHost
         run: |
           $arch = "${{ matrix.arch }}"
-          $selfContained = "${{ matrix.self_contained }}" -eq "true"
-          $publishDir = if ($selfContained) { "publish/windows-$arch" } else { "publish/windows-$arch-lite" }
+          $publishDir = "publish/windows-$arch"
 
-          if ($selfContained) {
-            dotnet publish LanMountainDesktop.AirAppHost/LanMountainDesktop.AirAppHost.csproj `
-              -c Release `
-              -o ./$publishDir `
-              --self-contained:false `
-              -r win-$arch `
-              -p:PublishSingleFile=false `
-              -p:DebugType=none `
-              -p:DebugSymbols=false `
-              -p:PublishTrimmed=false `
-              -p:PublishReadyToRun=false `
-              -p:BuildingAirAppHost=true `
-              -p:SkipAirAppHostBuild=true `
-              -p:Version=${{ needs.prepare.outputs.version }} `
-              -p:AssemblyVersion=${{ needs.prepare.outputs.assembly_version }} `
-              -p:FileVersion=${{ needs.prepare.outputs.assembly_version }} `
-              -p:InformationalVersion=${{ needs.prepare.outputs.informational_version }}
-          } else {
-            dotnet publish LanMountainDesktop.AirAppHost/LanMountainDesktop.AirAppHost.csproj `
-              -c Release `
-              -o ./$publishDir `
-              --self-contained:false `
-              -p:PublishSingleFile=false `
-              -p:DebugType=none `
-              -p:DebugSymbols=false `
-              -p:PublishTrimmed=false `
-              -p:PublishReadyToRun=false `
-              -p:BuildingAirAppHost=true `
-              -p:SkipAirAppHostBuild=true `
-              -p:Version=${{ needs.prepare.outputs.version }} `
-              -p:AssemblyVersion=${{ needs.prepare.outputs.assembly_version }} `
-              -p:FileVersion=${{ needs.prepare.outputs.assembly_version }} `
-              -p:InformationalVersion=${{ needs.prepare.outputs.informational_version }}
-          }
+          dotnet publish LanMountainDesktop.AirAppHost/LanMountainDesktop.AirAppHost.csproj `
+            -c Release `
+            -o ./$publishDir `
+            --self-contained:false `
+            -r win-$arch `
+            -p:SelfContained=false `
+            -p:PublishSingleFile=false `
+            -p:DebugType=none `
+            -p:DebugSymbols=false `
+            -p:PublishTrimmed=false `
+            -p:PublishReadyToRun=false `
+            -p:BuildingAirAppHost=true `
+            -p:SkipAirAppHostBuild=true `
+            -p:Version=${{ needs.prepare.outputs.version }} `
+            -p:AssemblyVersion=${{ needs.prepare.outputs.assembly_version }} `
+            -p:FileVersion=${{ needs.prepare.outputs.assembly_version }} `
+            -p:InformationalVersion=${{ needs.prepare.outputs.informational_version }}
         shell: pwsh
 
       - name: Restructure for Launcher
         run: |
           $version = "${{ needs.prepare.outputs.version }}"
           $arch = "${{ matrix.arch }}"
-          $selfContained = "${{ matrix.self_contained }}" -eq "true"
-          $publishDir = if ($selfContained) { "publish/windows-$arch" } else { "publish/windows-$arch-lite" }
+          $publishDir = "publish/windows-$arch"
           $launcherPublishDir = "publish/launcher-win-$arch"
           $appDir = "app-$version"
           $newStructure = "publish-launcher/windows-$arch"
@@ -274,8 +236,7 @@ jobs:
       - name: Optimize and Guard Windows Payload
         run: |
           $arch = "${{ matrix.arch }}"
-          $selfContained = "${{ matrix.self_contained }}" -eq "true"
-          $publishDir = if ($selfContained) { "publish/windows-$arch" } else { "publish/windows-$arch-lite" }
+          $publishDir = "publish/windows-$arch"
 
           ./LanMountainDesktop/scripts/Optimize-PublishPayload.ps1 `
             -PublishDir $publishDir `
@@ -283,6 +244,27 @@ jobs:
             -AssertClean
         shell: pwsh
 
+      - name: Verify Windows app host payload
+        run: |
+          $version = "${{ needs.prepare.outputs.version }}"
+          $arch = "${{ matrix.arch }}"
+          $publishDir = "publish/windows-$arch"
+          $appDir = Join-Path $publishDir "app-$version"
+
+          $requiredFiles = @(
+            (Join-Path $publishDir "LanMountainDesktop.Launcher.exe"),
+            (Join-Path $appDir "LanMountainDesktop.exe"),
+            (Join-Path $appDir "LanMountainDesktop.AirAppHost.exe")
+          )
+
+          foreach ($path in $requiredFiles) {
+            if (-not (Test-Path -LiteralPath $path -PathType Leaf)) {
+              Write-Error "Required release payload file is missing: $path"
+              exit 1
+            }
+          }
+        shell: pwsh
+
       - name: Install Inno Setup and 7z
         run: |
           choco install innosetup -y --no-progress
@@ -294,8 +276,7 @@ jobs:
           $version = "${{ needs.prepare.outputs.version }}"
           $arch = "${{ matrix.arch }}"
           $suffix = "${{ matrix.suffix }}"
-          $selfContained = "${{ matrix.self_contained }}" -eq "true"
-          $publishDir = if ($selfContained) { "publish/windows-$arch" } else { "publish/windows-$arch-lite" }
+          $publishDir = "publish/windows-$arch"
           $outputDir = "build-installer"
           $installerScript = "LanMountainDesktop/installer/LanMountainDesktop.iss"
 
@@ -329,7 +310,6 @@ jobs:
             "/DMyOutputDir=$outputDir",
             "/DMyAppArch=$arch",
             "/DMyAppSuffix=$suffix",
-            "/DIsSelfContained=$selfContained",
             $installerScript
           )
 

.trae/specs/runtime-packaging-fix/checklist.md

@@ -0,0 +1,5 @@
+# Runtime Packaging Fix Checklist
+
+- [x] `dotnet build LanMountainDesktop.slnx -c Debug -v minimal` succeeds.
+- [x] Runtime probe, AirAppHost startup, and packaging policy tests pass.
+- [ ] Full `win-x64` package dry run completes without timeout.

.trae/specs/runtime-packaging-fix/spec.md

@@ -0,0 +1,12 @@
+# Runtime Packaging Fix
+
+Windows releases use the launcher as the only self-contained bootstrapper. The
+desktop host and AirAppHost are framework-dependent and rely on an
+architecture-matched .NET 10 Desktop Runtime installed by the Inno setup flow.
+
+Acceptance:
+
+- Windows installer payload does not bundle .NET shared runtime files.
+- Inno Setup downloads and silently installs the matching .NET 10 Desktop Runtime.
+- Launcher blocks framework-dependent host startup with `dotnet_runtime_missing` when the runtime is unavailable.
+- AirAppHost startup uses packaged executables or an explicit architecture-matched dotnet host for DLL fallback.

.trae/specs/runtime-packaging-fix/tasks.md

@@ -0,0 +1,7 @@
+# Runtime Packaging Fix Tasks
+
+- [x] Add launcher-side .NET runtime probe and host startup guard.
+- [x] Update AirAppHost process start behavior for packaged exe and DLL fallback.
+- [x] Update Windows packaging scripts and CI release workflow.
+- [x] Update Inno Setup prerequisite download/install flow.
+- [x] Add regression tests and runtime packaging documentation.

Directory.Packages.props

@@ -3,21 +3,21 @@
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
   </PropertyGroup>
   <ItemGroup>
-    <PackageVersion Include="Avalonia" Version="12.0.2" />
-    <PackageVersion Include="Avalonia.Controls.WebView" Version="12.0.0" />
-    <PackageVersion Include="Avalonia.Desktop" Version="12.0.2" />
-    <PackageVersion Include="Avalonia.Fonts.Inter" Version="12.0.2" />
-    <PackageVersion Include="Avalonia.Themes.Fluent" Version="12.0.2" />
+    <PackageVersion Include="Avalonia" Version="12.0.3" />
+    <PackageVersion Include="Avalonia.Controls.WebView" Version="12.0.1" />
+    <PackageVersion Include="Avalonia.Desktop" Version="12.0.3" />
+    <PackageVersion Include="Avalonia.Fonts.Inter" Version="12.0.3" />
+    <PackageVersion Include="Avalonia.Themes.Fluent" Version="12.0.3" />
     <PackageVersion Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.1" />
     <PackageVersion Include="ClassIsland.Markdown.Avalonia" Version="12.0.0" />
     <PackageVersion Include="CommunityToolkit.Mvvm" Version="8.4.2" />
     <PackageVersion Include="dotnetCampus.Ipc" Version="2.0.0-alpha436" />
     <PackageVersion Include="DotNetCampus.AvaloniaInkCanvas" Version="1.0.1" />
     <PackageVersion Include="Downloader" Version="5.4.0" />
-    <PackageVersion Include="FluentAvaloniaUI" Version="3.0.0-preview2" />
+    <PackageVersion Include="FluentAvaloniaUI" Version="3.0.0-preview4" />
     <PackageVersion Include="FluentIcons.Avalonia" Version="2.1.325" />
     <PackageVersion Include="Lib.Harmony.Thin" Version="2.4.2" />
-    <PackageVersion Include="Material.Avalonia" Version="3.16.1" />
+    <PackageVersion Include="Material.Avalonia" Version="3.17.0" />
     <PackageVersion Include="MaterialColorUtilities" Version="0.3.0" />
     <PackageVersion Include="Material.Icons.Avalonia" Version="3.0.3-nightly.0.2" />
     <PackageVersion Include="Microsoft.Data.Sqlite" Version="11.0.0-preview.3.26207.106" />
@@ -30,8 +30,8 @@
     <PackageVersion Include="MudTools.OfficeInterop.PowerPoint" Version="2.0.9" />
     <PackageVersion Include="MudTools.OfficeInterop.Word" Version="2.0.9" />
     <PackageVersion Include="PortAudioSharp2" Version="1.0.6" />
-    <PackageVersion Include="PostHog" Version="2.6.0" />
-    <PackageVersion Include="Sentry" Version="6.4.1" />
+    <PackageVersion Include="PostHog" Version="2.7.1" />
+    <PackageVersion Include="Sentry" Version="6.5.0" />
     <PackageVersion Include="System.Drawing.Common" Version="11.0.0-preview.3.26207.106" />
     <PackageVersion Include="System.Runtime.WindowsRuntime" Version="5.0.0-preview.5.20278.1" />
     <PackageVersion Include="Tmds.DBus.Protocol" Version="0.92.0" />

LanMountainDesktop.Appearance/AppearanceCornerRadiusTokenFactory.cs

@@ -38,6 +38,15 @@ public static class AppearanceCornerRadiusTokenFactory
                 Xl: new CornerRadius(40),
                 Island: new CornerRadius(44),
                 Component: new CornerRadius(32)),
+            GlobalAppearanceSettings.CornerRadiusStyleFluent => new AppearanceCornerRadiusTokens(
+                Micro: new CornerRadius(2),
+                Xs: new CornerRadius(4),
+                Sm: new CornerRadius(4),
+                Md: new CornerRadius(8),
+                Lg: new CornerRadius(8),
+                Xl: new CornerRadius(12),
+                Island: new CornerRadius(16),
+                Component: new CornerRadius(8)),
             // Balanced (default)
             _ => new AppearanceCornerRadiusTokens(
                 Micro: new CornerRadius(6),

LanMountainDesktop.Launcher/AirApp/AirAppHostLocator.cs

@@ -1,4 +1,4 @@
-namespace LanMountainDesktop.Launcher.Services.AirApp;
+namespace LanMountainDesktop.Launcher.AirApp;
 
 internal sealed class AirAppHostLocator
 {

LanMountainDesktop.Launcher/AirApp/AirAppInstanceKey.cs

@@ -1,4 +1,4 @@
-namespace LanMountainDesktop.Launcher.Services.AirApp;
+namespace LanMountainDesktop.Launcher.AirApp;
 
 internal static class AirAppInstanceKey
 {

LanMountainDesktop.Launcher/AirApp/IAirAppProcessStarter.cs

@@ -1,6 +1,5 @@
 using System.Diagnostics;
-
-namespace LanMountainDesktop.Launcher.Services.AirApp;
+namespace LanMountainDesktop.Launcher.AirApp;
 
 internal interface IAirAppProcessStarter
 {
@@ -13,17 +12,20 @@ internal sealed class AirAppProcessStarter : IAirAppProcessStarter
     private readonly Func<string?> _packageRootProvider;
     private readonly Func<string?> _hostPathProvider;
     private readonly Func<string?> _dataRootProvider;
+    private readonly DotNetRuntimeProbeOptions? _runtimeProbeOptions;
 
     public AirAppProcessStarter(
         AirAppHostLocator locator,
         Func<string?> packageRootProvider,
         Func<string?> hostPathProvider,
-        Func<string?> dataRootProvider)
+        Func<string?> dataRootProvider,
+        DotNetRuntimeProbeOptions? runtimeProbeOptions = null)
     {
         _locator = locator;
         _packageRootProvider = packageRootProvider;
         _hostPathProvider = hostPathProvider;
         _dataRootProvider = dataRootProvider;
+        _runtimeProbeOptions = runtimeProbeOptions;
     }
 
     public Process? Start(
@@ -34,22 +36,7 @@ internal sealed class AirAppProcessStarter : IAirAppProcessStarter
         string? sourcePlacementId)
     {
         var hostPath = _locator.Resolve(_packageRootProvider(), _hostPathProvider());
-        var startInfo = new ProcessStartInfo
-        {
-            UseShellExecute = false,
-            WorkingDirectory = Path.GetDirectoryName(hostPath) ?? AppContext.BaseDirectory
-        };
-
-        if (OperatingSystem.IsWindows() &&
-            string.Equals(Path.GetExtension(hostPath), ".exe", StringComparison.OrdinalIgnoreCase))
-        {
-            startInfo.FileName = hostPath;
-        }
-        else
-        {
-            startInfo.FileName = "dotnet";
-            startInfo.ArgumentList.Add(hostPath);
-        }
+        var startInfo = CreateStartInfo(hostPath, _runtimeProbeOptions);
 
         AddArgument(startInfo, "--app-id", appId);
         AddArgument(startInfo, "--session-id", sessionId);
@@ -71,7 +58,7 @@ internal sealed class AirAppProcessStarter : IAirAppProcessStarter
             AddArgument(startInfo, "--source-placement-id", sourcePlacementId.Trim());
         }
 
-        LanMountainDesktop.Launcher.Services.Logger.Info(
+        Logger.Info(
             $"Starting AirAppHost. AppId='{appId}'; InstanceKey='{instanceKey}'; HostPath='{hostPath}'; DataRoot='{dataRoot ?? string.Empty}'.");
         var process = Process.Start(startInfo);
         if (process is not null)
@@ -81,12 +68,12 @@ internal sealed class AirAppProcessStarter : IAirAppProcessStarter
             {
                 try
                 {
-                    LanMountainDesktop.Launcher.Services.Logger.Info(
+                    Logger.Info(
                         $"AirAppHost exited. AppId='{appId}'; InstanceKey='{instanceKey}'; ProcessId={process.Id}; ExitCode={process.ExitCode}.");
                 }
                 catch (Exception ex)
                 {
-                    LanMountainDesktop.Launcher.Services.Logger.Warn($"Failed to log AirAppHost exit: {ex.Message}");
+                    Logger.Warn($"Failed to log AirAppHost exit: {ex.Message}");
                 }
             };
         }
@@ -94,6 +81,54 @@ internal sealed class AirAppProcessStarter : IAirAppProcessStarter
         return process;
     }
 
+    internal static ProcessStartInfo CreateStartInfo(
+        string hostPath,
+        DotNetRuntimeProbeOptions? runtimeProbeOptions = null)
+    {
+        var startInfo = new ProcessStartInfo
+        {
+            UseShellExecute = false,
+            WorkingDirectory = Path.GetDirectoryName(hostPath) ?? AppContext.BaseDirectory
+        };
+
+        if (OperatingSystem.IsWindows())
+        {
+            if (string.Equals(Path.GetExtension(hostPath), ".exe", StringComparison.OrdinalIgnoreCase))
+            {
+                if (DotNetRuntimeProbe.IsFrameworkDependentWindowsApp(hostPath))
+                {
+                    var executableRuntime = DotNetRuntimeProbe.Probe(runtimeProbeOptions);
+                    if (!executableRuntime.IsAvailable)
+                    {
+                        throw new InvalidOperationException(
+                            "Unable to start AirAppHost because the architecture-matched .NET 10 runtime was not found. " +
+                            executableRuntime.Message);
+                    }
+                }
+
+                startInfo.FileName = hostPath;
+                return startInfo;
+            }
+
+            var runtime = DotNetRuntimeProbe.Probe(runtimeProbeOptions);
+            if (!runtime.IsAvailable || string.IsNullOrWhiteSpace(runtime.DotNetHostPath))
+            {
+                throw new InvalidOperationException(
+                    "Unable to start AirAppHost because the architecture-matched .NET 10 runtime was not found. " +
+                    runtime.Message);
+            }
+
+            startInfo.FileName = runtime.DotNetHostPath;
+            startInfo.ArgumentList.Add(hostPath);
+            return startInfo;
+        }
+
+        startInfo.FileName = "dotnet";
+        startInfo.ArgumentList.Add(hostPath);
+        return startInfo;
+    }
+
+
     private static void AddArgument(ProcessStartInfo startInfo, string name, string value)
     {
         startInfo.ArgumentList.Add(name);

LanMountainDesktop.Launcher/AirApp/LauncherAirAppLifecycleIpcHost.cs

@@ -1,7 +1,7 @@
 using LanMountainDesktop.Shared.IPC;
 using LanMountainDesktop.Shared.IPC.Abstractions.Services;
 
-namespace LanMountainDesktop.Launcher.Services.AirApp;
+namespace LanMountainDesktop.Launcher.AirApp;
 
 internal sealed class LauncherAirAppLifecycleIpcHost : IDisposable
 {

LanMountainDesktop.Launcher/AirApp/LauncherAirAppLifecycleService.cs

@@ -2,7 +2,7 @@ using System.Diagnostics;
 using System.Runtime.InteropServices;
 using LanMountainDesktop.Shared.IPC.Abstractions.Services;
 
-namespace LanMountainDesktop.Launcher.Services.AirApp;
+namespace LanMountainDesktop.Launcher.AirApp;
 
 internal sealed class LauncherAirAppLifecycleService : IAirAppLifecycleService
 {

LanMountainDesktop.Launcher/App.axaml.cs

@@ -1,18 +1,11 @@
-using System.Diagnostics;
 using Avalonia;
 using Avalonia.Controls;
 using Avalonia.Controls.ApplicationLifetimes;
 using Avalonia.Markup.Xaml;
-using Avalonia.Threading;
 using LanMountainDesktop.Launcher.Models;
-using LanMountainDesktop.Launcher.Resources;
-using LanMountainDesktop.Launcher.Services;
-using LanMountainDesktop.Launcher.Services.AirApp;
-using LanMountainDesktop.Launcher.Services.Ipc;
+using LanMountainDesktop.Launcher.Shell;
+using LanMountainDesktop.Launcher.Shell.EntryHandlers;
 using LanMountainDesktop.Launcher.Views;
-using LanMountainDesktop.Shared.Contracts.Launcher;
-using LanMountainDesktop.Shared.IPC;
-using LanMountainDesktop.Shared.IPC.Abstractions.Services;
 
 namespace LanMountainDesktop.Launcher;
 
@@ -46,804 +39,56 @@ public partial class App : Application
             return;
         }
 
-        if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
+        if (ApplicationLifetime is not IClassicDesktopStyleApplicationLifetime desktop)
         {
-            desktop.ShutdownMode = ShutdownMode.OnExplicitShutdown;
+            base.OnFrameworkInitializationCompleted();
+            return;
+        }
 
-            var context = LauncherRuntimeContext.Current;
-            var execution = LauncherExecutionContext.Capture();
-            Logger.Info(
-                $"Framework initialization completed. Command='{context.Command}'; IsPreview={context.IsPreviewCommand}; " +
-                $"IsDebugMode={context.IsDebugMode}; LaunchSource='{context.LaunchSource}'; " +
-                $"IsElevated={execution.IsElevated}; UserSid='{execution.UserSid ?? string.Empty}'.");
+        desktop.ShutdownMode = ShutdownMode.OnExplicitShutdown;
 
-            if (HandlePreviewCommand(context, desktop))
-            {
-                base.OnFrameworkInitializationCompleted();
-                return;
-            }
+        var context = LauncherRuntimeContext.Current;
+        var execution = LauncherExecutionContext.Capture();
+        Logger.Info(
+            $"Framework initialization completed. Command='{context.Command}'; IsPreview={context.IsPreviewCommand}; " +
+            $"IsDebugMode={context.IsDebugMode}; LaunchSource='{context.LaunchSource}'; " +
+            $"IsElevated={execution.IsElevated}; UserSid='{execution.UserSid ?? string.Empty}'.");
 
-            if (context.IsAirAppBrokerCommand)
-            {
-                _ = RunAirAppBrokerAsync(desktop, context);
-                base.OnFrameworkInitializationCompleted();
-                return;
-            }
+        if (PreviewEntryHandler.TryHandle(context, desktop))
+        {
+            base.OnFrameworkInitializationCompleted();
+            return;
+        }
 
-            // 调试模式：只显示 DevDebugWindow，不走正常启动流程
-            // 避免启动主程序后 Launcher 自动退出，导致开发者无法预览 UI
-            if (context.IsDebugMode && !context.IsPreviewCommand &&
-                !string.Equals(context.Command, "apply-update", StringComparison.OrdinalIgnoreCase))
-            {
-                Logger.Info("Debug mode active — showing DevDebugWindow instead of normal launch flow.");
-                var devDebugWindow = new DevDebugWindow();
-                devDebugWindow.Show();
-                base.OnFrameworkInitializationCompleted();
-                return;
-            }
+        if (context.IsAirAppBrokerCommand)
+        {
+            _ = AirAppBrokerEntryHandler.RunAsync(desktop, context);
+            base.OnFrameworkInitializationCompleted();
+            return;
+        }
 
-            if (string.Equals(context.Command, "apply-update", StringComparison.OrdinalIgnoreCase))
-            {
-                var updateWindow = new UpdateWindow();
-                updateWindow.Show();
-                _ = RunApplyUpdateWithWindowAsync(desktop, context, updateWindow);
-            }
-            else
-            {
-                var splashWindow = CreateSplashWindow();
-                splashWindow.Show();
-                _ = RunCoordinatorWithSplashAsync(desktop, context, splashWindow);
-            }
+        if (context.IsDebugMode && !context.IsPreviewCommand &&
+            !string.Equals(context.Command, "apply-update", StringComparison.OrdinalIgnoreCase))
+        {
+            Logger.Info("Debug mode active; showing DevDebugWindow instead of normal launch flow.");
+            new DevDebugWindow().Show();
+            base.OnFrameworkInitializationCompleted();
+            return;
+        }
+
+        if (string.Equals(context.Command, "apply-update", StringComparison.OrdinalIgnoreCase))
+        {
+            var updateWindow = new UpdateWindow();
+            updateWindow.Show();
+            _ = ApplyUpdateEntryHandler.RunAsync(desktop, context, updateWindow);
+        }
+        else
+        {
+            var splashWindow = LaunchEntryHandler.CreateSplashWindow();
+            splashWindow.Show();
+            _ = LauncherCompositionRoot.RunOrchestratorWithSplashAsync(desktop, context, splashWindow);
         }
 
         base.OnFrameworkInitializationCompleted();
     }
-
-    private static async Task RunAirAppBrokerAsync(
-        IClassicDesktopStyleApplicationLifetime desktop,
-        CommandContext context)
-    {
-        var appRoot = Commands.ResolveAppRoot(context);
-        var requesterPid = context.GetIntOption("requester-pid", 0);
-        var dataLocationResolver = new DataLocationResolver(appRoot);
-        Logger.Info($"Air APP broker starting. AppRoot='{appRoot}'; RequesterPid={requesterPid}.");
-
-        using var airAppIpcHost = new LauncherAirAppLifecycleIpcHost(
-            new LauncherAirAppLifecycleService(
-                new AirAppProcessStarter(
-                    new AirAppHostLocator(),
-                    () => appRoot,
-                    () => null,
-                    () => dataLocationResolver.ResolveDataRoot())));
-        airAppIpcHost.Start();
-
-        await WaitForAirAppBrokerExitAsync(requesterPid, airAppIpcHost.LifecycleService).ConfigureAwait(false);
-
-        Logger.Info("Air APP broker exiting.");
-        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0), DispatcherPriority.Background);
-    }
-
-    internal static async Task WaitForAirAppBrokerExitAsync(
-        int requesterPid,
-        LauncherAirAppLifecycleService airAppLifecycleService)
-    {
-        while (ShouldKeepAirAppBrokerAlive(requesterPid, airAppLifecycleService))
-        {
-            await Task.Delay(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
-        }
-    }
-
-    internal static bool ShouldKeepAirAppBrokerAlive(
-        int requesterPid,
-        LauncherAirAppLifecycleService airAppLifecycleService)
-    {
-        return TryGetLiveProcess(requesterPid) || airAppLifecycleService.HasLiveAirApps();
-    }
-
-    private bool HandlePreviewCommand(CommandContext context, IClassicDesktopStyleApplicationLifetime desktop)
-    {
-        switch (context.Command.ToLowerInvariant())
-        {
-            case "preview-splash":
-            {
-                Logger.Info("Preview command: splash.");
-                var splashWindow = CreateSplashWindow();
-                splashWindow.SetDebugMode(true);
-                splashWindow.Show();
-                _ = SimulateSplashPreviewAsync(desktop, splashWindow);
-                return true;
-            }
-            case "preview-error":
-            {
-                Logger.Info("Preview command: error.");
-                var errorWindow = new ErrorWindow();
-                errorWindow.SetErrorMessage(Strings.Preview_ErrorMessage);
-                errorWindow.Show();
-                _ = WaitForWindowCloseAsync(desktop, errorWindow);
-                return true;
-            }
-            case "preview-multi-instance":
-            {
-                Logger.Info("Preview command: multi-instance prompt.");
-                var promptWindow = new MultiInstancePromptWindow();
-                promptWindow.SetDetails(Environment.ProcessId, "ForegroundDesktop");
-                promptWindow.Show();
-                _ = WaitForWindowCloseAsync(desktop, promptWindow);
-                return true;
-            }
-            case "preview-update":
-            {
-                Logger.Info("Preview command: update.");
-                var updateWindow = new UpdateWindow();
-                updateWindow.SetDebugMode(true);
-                updateWindow.Show();
-                _ = SimulateUpdatePreviewAsync(desktop, updateWindow);
-                return true;
-            }
-            case "preview-oobe":
-            {
-                Logger.Info("Preview command: oobe.");
-                var oobeWindow = new OobeWindow();
-                oobeWindow.Show();
-                _ = SimulateOobePreviewAsync(desktop, oobeWindow);
-                return true;
-            }
-            case "preview-debug":
-            {
-                Logger.Info("Preview command: debug window.");
-                var devDebugWindow = new DevDebugWindow();
-                devDebugWindow.Show();
-                return true;
-            }
-            default:
-                return false;
-        }
-    }
-
-    private static SplashWindow CreateSplashWindow()
-    {
-        var window = new SplashWindow();
-        TrySetSplashVersionInfo(window, LauncherRuntimeContext.Current);
-        return window;
-    }
-
-    private static void TrySetSplashVersionInfo(SplashWindow window, CommandContext context)
-    {
-        try
-        {
-            var appRoot = Commands.ResolveAppRoot(context);
-            var versionInfo = new DeploymentLocator(appRoot).GetVersionInfo();
-            window.SetVersionInfo(versionInfo.Version, versionInfo.Codename);
-        }
-        catch (Exception ex)
-        {
-            Logger.Warn($"Failed to set splash version info before coordinator start: {ex.Message}");
-        }
-    }
-
-    private async Task SimulateSplashPreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, SplashWindow window)
-    {
-        var stages = new[] { "initializing", "update", "plugins", "launch", "ready" };
-        var messages = new[] { Strings.Preview_SplashInitializing, Strings.Preview_SplashCheckingUpdates, Strings.Preview_SplashCheckingPlugins, Strings.Preview_SplashLaunchingHost, Strings.Preview_SplashReady };
-        var reporter = (ISplashStageReporter)window;
-
-        for (var i = 0; i < stages.Length; i++)
-        {
-            reporter.Report(stages[i], messages[i]);
-            await Task.Delay(800).ConfigureAwait(false);
-        }
-
-        await Task.Delay(5000).ConfigureAwait(false);
-        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
-    }
-
-    private async Task SimulateUpdatePreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, UpdateWindow window)
-    {
-        var stages = new[] { "verify", "extract", "apply", "plugins", "cleanup" };
-
-        for (var i = 0; i < stages.Length; i++)
-        {
-            window.Report(stages[i], string.Format(Strings.Preview_UpdateProcessing, stages[i]), (i + 1) * 20);
-            await Task.Delay(600).ConfigureAwait(false);
-        }
-
-        window.ReportComplete(true, null);
-        await Task.Delay(3000).ConfigureAwait(false);
-        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
-    }
-
-    private async Task SimulateOobePreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, OobeWindow window)
-    {
-        try
-        {
-            await window.WaitForEnterAsync().ConfigureAwait(false);
-            Logger.Info("OOBE preview completed by user.");
-        }
-        catch (Exception ex)
-        {
-            Logger.Error("OOBE preview failed.", ex);
-        }
-
-        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
-    }
-
-    private async Task WaitForWindowCloseAsync(IClassicDesktopStyleApplicationLifetime desktop, Window window)
-    {
-        var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
-        window.Closed += (_, _) => tcs.TrySetResult();
-        await tcs.Task.ConfigureAwait(false);
-        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
-    }
-
-    private static async Task RunCoordinatorWithSplashAsync(
-        IClassicDesktopStyleApplicationLifetime desktop,
-        CommandContext context,
-        SplashWindow splashWindow)
-    {
-        LauncherResult result;
-        SplashWindow? currentSplashWindow = splashWindow;
-        var appRoot = Commands.ResolveAppRoot(context);
-        var dataLocationResolver = new DataLocationResolver(appRoot);
-        var startupAttemptRegistry = new StartupAttemptRegistry();
-        var coordinatorPipeName = LauncherCoordinatorIpcServer.CreatePipeName();
-        var successPolicy = LauncherFlowCoordinator.ResolveSuccessPolicyKey(context);
-        if (!startupAttemptRegistry.TryReserveCoordinator(
-                context.LaunchSource,
-                successPolicy,
-                coordinatorPipeName,
-                out var reservedAttempt,
-                out var activeCoordinatorAttempt))
-        {
-            result = await AttachToExistingCoordinatorAsync(
-                context,
-                currentSplashWindow,
-                activeCoordinatorAttempt).ConfigureAwait(false);
-
-            Logger.Info($"Secondary launcher completed. Success={result.Success}; Code='{result.Code}'.");
-            await WriteLauncherResultAsync(context, result).ConfigureAwait(false);
-
-            Environment.ExitCode = result.Success ? 0 : 1;
-            await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
-            return;
-        }
-
-        using var airAppIpcHost = new LauncherAirAppLifecycleIpcHost(
-            new LauncherAirAppLifecycleService(
-                new AirAppProcessStarter(
-                    new AirAppHostLocator(),
-                    () => appRoot,
-                    () => null,
-                    () => dataLocationResolver.ResolveDataRoot())));
-        airAppIpcHost.Start();
-
-        using var coordinatorServer = new LauncherCoordinatorIpcServer(
-            coordinatorPipeName,
-            BuildCoordinatorStatusFromAttempt(reservedAttempt),
-            HandleCoordinatorRequestAsync,
-            startupAttemptRegistry.UpdateOwnedCoordinatorHeartbeat);
-        coordinatorServer.Start();
-
-        while (true)
-        {
-            try
-            {
-                Logger.Info(
-                    $"Coordinator start. Command='{context.Command}'; AppRoot='{appRoot}'; " +
-                    $"IsDebugMode={context.IsDebugMode}; LaunchSource='{context.LaunchSource}'; " +
-                    $"ResultPath='{context.GetOption("result") ?? "<none>"}'.");
-
-                var deploymentLocator = new DeploymentLocator(appRoot);
-                var coordinator = new LauncherFlowCoordinator(
-                    context,
-                    deploymentLocator,
-                    new OobeStateService(appRoot),
-                    new UpdateEngineService(deploymentLocator),
-                    new PluginInstallerService(),
-                    startupAttemptRegistry,
-                    coordinatorServer);
-
-                result = await coordinator.RunAsync(currentSplashWindow).ConfigureAwait(false);
-            }
-            catch (Exception ex)
-            {
-                Logger.Error("Coordinator threw an unhandled exception.", ex);
-                result = new LauncherResult
-                {
-                    Success = false,
-                    Stage = "launch",
-                    Code = "exception",
-                    Message = $"Launcher failed: {ex.Message}",
-                    ErrorMessage = ex.ToString()
-                };
-            }
-
-            if (result.Success ||
-                result.Code == "host_not_found" ||
-                (!string.Equals(result.Stage, "launch", StringComparison.OrdinalIgnoreCase) &&
-                 !string.Equals(result.Stage, "launchHost", StringComparison.OrdinalIgnoreCase)))
-            {
-                break;
-            }
-
-            var failureAction = await ShowFailureWindowAsync(result).ConfigureAwait(false);
-            if (failureAction == ErrorWindowResult.Exit)
-            {
-                break;
-            }
-
-            if (failureAction == ErrorWindowResult.ActivateExisting &&
-                await TryActivateExistingInstanceAsync().ConfigureAwait(false))
-            {
-                result = new LauncherResult
-                {
-                    Success = true,
-                    Stage = "launch",
-                    Code = "activation_requested",
-                    Message = "Launcher activated the existing desktop instance.",
-                    Details = result.Details
-                };
-                break;
-            }
-
-            currentSplashWindow = CreateSplashWindow();
-            currentSplashWindow.Show();
-        }
-
-        Logger.Info($"Coordinator completed. Success={result.Success}; Stage='{result.Stage}'; Code='{result.Code}'.");
-        await WriteLauncherResultAsync(context, result).ConfigureAwait(false);
-
-        Environment.ExitCode = result.Success ? 0 : 1;
-        if (result.Success)
-        {
-            var hostPid = ResolveManagedHostPid(result, startupAttemptRegistry.GetOwnedAttempt()?.HostPid ?? 0);
-            await WaitForManagedProcessesToExitAsync(hostPid, airAppIpcHost.LifecycleService).ConfigureAwait(false);
-        }
-
-        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
-    }
-
-    private static int ResolveManagedHostPid(LauncherResult result, int fallbackHostPid)
-    {
-        if (result.Details.TryGetValue("hostPid", out var hostPidText) &&
-            int.TryParse(hostPidText, out var hostPid))
-        {
-            return hostPid;
-        }
-
-        if (result.Details.TryGetValue("existingHostPid", out var existingHostPidText) &&
-            int.TryParse(existingHostPidText, out var existingHostPid))
-        {
-            return existingHostPid;
-        }
-
-        return fallbackHostPid;
-    }
-
-    private static async Task WaitForManagedProcessesToExitAsync(
-        int hostPid,
-        LauncherAirAppLifecycleService airAppLifecycleService)
-    {
-        Logger.Info($"Launcher entering managed background lifetime. HostPid={hostPid}.");
-        while (TryGetLiveProcess(hostPid) || airAppLifecycleService.HasLiveAirApps())
-        {
-            await Task.Delay(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
-        }
-
-        Logger.Info("Launcher managed background lifetime completed; no host or Air APP process remains.");
-    }
-
-    private static async Task<LauncherResult> AttachToExistingCoordinatorAsync(
-        CommandContext context,
-        SplashWindow? splashWindow,
-        StartupAttemptRecord? activeCoordinatorAttempt)
-    {
-        var reporter = splashWindow as ISplashStageReporter;
-        reporter?.Report("activation", Strings.Preview_ActivationConnecting);
-
-        if (activeCoordinatorAttempt is not null &&
-            !string.IsNullOrWhiteSpace(activeCoordinatorAttempt.CoordinatorPipeName))
-        {
-            var command = string.Equals(context.LaunchSource, "restart", StringComparison.OrdinalIgnoreCase)
-                ? LauncherCoordinatorCommands.Attach
-                : LauncherCoordinatorCommands.ActivateDesktop;
-            var request = new LauncherCoordinatorRequest
-            {
-                Command = command,
-                LaunchSource = context.LaunchSource,
-                SuccessPolicy = LauncherFlowCoordinator.ResolveSuccessPolicyKey(context)
-            };
-
-            var response = await new LauncherCoordinatorIpcClient()
-                .SendAsync(activeCoordinatorAttempt.CoordinatorPipeName, request, TimeSpan.FromSeconds(2))
-                .ConfigureAwait(false);
-
-            if (response is not null)
-            {
-                reporter?.Report("activation", response.Message);
-                await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
-                var success = response.Accepted ||
-                              IsRecoverableActivationFailure(response.ActivationResult, response.Status);
-                return new LauncherResult
-                {
-                    Success = success,
-                    Stage = "launch",
-                    Code = success && !response.Accepted ? "attached_to_launcher_coordinator" : response.Code,
-                    Message = success && !response.Accepted
-                        ? "Attached to the active Launcher coordinator; desktop startup is still in progress."
-                        : response.Message,
-                    Details = BuildCoordinatorResultDetails(response.Status, response.ActivationResult)
-                };
-            }
-        }
-
-        var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
-        if (activation is not null)
-        {
-            reporter?.Report("activation", activation.Message);
-            await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
-            var success = activation.Accepted || IsRecoverableActivationFailure(activation, null);
-            return new LauncherResult
-            {
-                Success = success,
-                Stage = "launch",
-                Code = activation.Accepted
-                    ? "existing_host_activated"
-                    : success
-                        ? "existing_host_startup_pending"
-                        : "existing_host_activation_failed",
-                Message = success && !activation.Accepted
-                    ? "Existing desktop process is still starting; Launcher attached without starting another process."
-                    : activation.Message,
-                Details = BuildCoordinatorResultDetails(null, activation)
-            };
-        }
-
-        await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
-        return new LauncherResult
-        {
-            Success = false,
-            Stage = "launch",
-            Code = "launcher_coordinator_unavailable",
-            Message = "Another Launcher is coordinating startup, but it did not respond in time.",
-            Details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
-            {
-                ["activeCoordinatorPid"] = activeCoordinatorAttempt?.CoordinatorPid.ToString() ?? string.Empty,
-                ["activeCoordinatorPipeName"] = activeCoordinatorAttempt?.CoordinatorPipeName ?? string.Empty,
-                ["activeAttemptId"] = activeCoordinatorAttempt?.AttemptId ?? string.Empty,
-                ["activeHostPid"] = activeCoordinatorAttempt?.HostPid.ToString() ?? string.Empty
-            }
-        };
-    }
-
-    private static async Task<LauncherCoordinatorResponse> HandleCoordinatorRequestAsync(
-        LauncherCoordinatorRequest request,
-        LauncherCoordinatorStatus status)
-    {
-        if (string.Equals(request.Command, LauncherCoordinatorCommands.ActivateDesktop, StringComparison.OrdinalIgnoreCase))
-        {
-            var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
-            if (activation is not null)
-            {
-                if (!activation.Accepted && IsRecoverableActivationFailure(activation, status))
-                {
-                    return new LauncherCoordinatorResponse
-                    {
-                        Accepted = true,
-                        Code = "attached_to_launcher_coordinator",
-                        Message = "Attached to the active Launcher coordinator; desktop startup is still in progress.",
-                        Status = status,
-                        ActivationResult = activation
-                    };
-                }
-
-                return new LauncherCoordinatorResponse
-                {
-                    Accepted = activation.Accepted,
-                    Code = activation.Accepted ? "existing_host_activated" : "existing_host_activation_failed",
-                    Message = activation.Message,
-                    Status = status,
-                    ActivationResult = activation
-                };
-            }
-
-            return new LauncherCoordinatorResponse
-            {
-                Accepted = true,
-                Code = "attached_to_launcher_coordinator",
-                Message = "Attached to the active Launcher coordinator; desktop startup is still in progress.",
-                Status = status
-            };
-        }
-
-        return new LauncherCoordinatorResponse
-        {
-            Accepted = true,
-            Code = "attached_to_launcher_coordinator",
-            Message = "Attached to the active Launcher coordinator.",
-            Status = status
-        };
-    }
-
-    private static LauncherCoordinatorStatus BuildCoordinatorStatusFromAttempt(StartupAttemptRecord attempt)
-    {
-        return new LauncherCoordinatorStatus
-        {
-            AttemptId = attempt.AttemptId,
-            CoordinatorPid = Environment.ProcessId,
-            HostPid = attempt.HostPid,
-            HostProcessAlive = TryGetLiveProcess(attempt.HostPid),
-            LaunchSource = attempt.LaunchSource,
-            SuccessPolicy = attempt.SuccessPolicy,
-            LastObservedStage = attempt.LastObservedStage,
-            LastObservedMessage = attempt.LastObservedMessage,
-            PublicIpcConnected = attempt.PublicIpcConnected || attempt.IpcConnected,
-            State = attempt.State.ToString(),
-            SoftTimeoutShown = attempt.State is StartupAttemptState.SoftTimeout or StartupAttemptState.DetachedWaiting,
-            Completed = attempt.State is StartupAttemptState.Succeeded or StartupAttemptState.Failed,
-            Succeeded = attempt.State == StartupAttemptState.Succeeded,
-            UpdatedAtUtc = attempt.UpdatedAtUtc
-        };
-    }
-
-    private static bool IsRecoverableActivationFailure(
-        PublicShellActivationResult? activation,
-        LauncherCoordinatorStatus? status)
-    {
-        if (activation is { Accepted: true })
-        {
-            return false;
-        }
-
-        if (status is { Completed: false, HostProcessAlive: true })
-        {
-            return true;
-        }
-
-        var shellStatus = activation?.Status;
-        if (shellStatus is null || !shellStatus.PublicIpcReady)
-        {
-            return false;
-        }
-
-        return !shellStatus.MainWindowOpened ||
-               !shellStatus.DesktopVisible ||
-               string.Equals(activation?.Code, "shell_not_ready", StringComparison.OrdinalIgnoreCase) ||
-               string.Equals(activation?.Code, "startup_pending", StringComparison.OrdinalIgnoreCase);
-    }
-
-    private static Dictionary<string, string> BuildCoordinatorResultDetails(
-        LauncherCoordinatorStatus? status,
-        PublicShellActivationResult? activation)
-    {
-        var details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
-        {
-            ["coordinatorPid"] = status?.CoordinatorPid.ToString() ?? string.Empty,
-            ["coordinatorAttemptId"] = status?.AttemptId ?? string.Empty,
-            ["hostPid"] = status?.HostPid.ToString() ?? activation?.Status.ProcessId.ToString() ?? string.Empty,
-            ["hostProcessAlive"] = status?.HostProcessAlive.ToString() ?? string.Empty,
-            ["publicIpcConnected"] = (status?.PublicIpcConnected ?? activation is not null).ToString(),
-            ["startupStage"] = status?.LastObservedStage.ToString() ?? string.Empty,
-            ["startupState"] = status?.State ?? string.Empty,
-            ["activationAccepted"] = activation?.Accepted.ToString() ?? string.Empty,
-            ["shellState"] = activation?.Status.ShellState ?? status?.ShellStatus?.ShellState ?? string.Empty,
-            ["trayState"] = activation?.Status.Tray.State ?? status?.ShellStatus?.Tray.State ?? string.Empty,
-            ["taskbarUsable"] = activation?.Status.Taskbar.IsUsable.ToString() ?? status?.ShellStatus?.Taskbar.IsUsable.ToString() ?? string.Empty
-        };
-
-        return details;
-    }
-
-    private static async Task DismissSplashIfNeededAsync(SplashWindow? splashWindow)
-    {
-        if (splashWindow is null)
-        {
-            return;
-        }
-
-        try
-        {
-            await splashWindow.DismissAsync().ConfigureAwait(false);
-        }
-        catch (Exception ex)
-        {
-            Logger.Warn($"Failed to dismiss splash after coordinator attach: {ex.Message}");
-        }
-    }
-
-    private static async Task WriteLauncherResultAsync(CommandContext context, LauncherResult result)
-    {
-        var resultPath = context.GetOption("result");
-        if (string.IsNullOrWhiteSpace(resultPath))
-        {
-            return;
-        }
-
-        try
-        {
-            await Commands.WriteResultIfNeededAsync(resultPath, result).ConfigureAwait(false);
-            Logger.Info($"Launcher result written to '{Path.GetFullPath(resultPath)}'.");
-        }
-        catch (Exception ex)
-        {
-            Logger.Error($"Failed to write launcher result to '{resultPath}'.", ex);
-        }
-    }
-
-    private static async Task<ErrorWindowResult> ShowFailureWindowAsync(LauncherResult result)
-    {
-        ErrorWindow? errorWindow = null;
-        var hostProcessAlive = result.Details.TryGetValue("hostProcessAlive", out var hostProcessAliveText) &&
-                               bool.TryParse(hostProcessAliveText, out var hostProcessAliveValue) &&
-                               hostProcessAliveValue;
-        var hostPid = result.Details.TryGetValue("hostPid", out var hostPidText) &&
-                      int.TryParse(hostPidText, out var parsedPid)
-            ? parsedPid
-            : (int?)null;
-
-        await Dispatcher.UIThread.InvokeAsync(() =>
-        {
-            try
-            {
-                errorWindow = new ErrorWindow();
-                if (hostProcessAlive)
-                {
-                    errorWindow.ConfigureForRunningHostFailure(hostPid);
-                }
-                else
-                {
-                    errorWindow.ConfigureForGenericFailure(allowRetry: true);
-                }
-
-                errorWindow.SetErrorMessage(
-                    $"Failed to start LanMountainDesktop.\n\nStage: {result.Stage}\nCode: {result.Code}\n\n{result.Message}");
-                errorWindow.Show();
-            }
-            catch (Exception ex)
-            {
-                Logger.Error("Failed to show launcher failure window.", ex);
-            }
-        });
-
-        if (errorWindow is null)
-        {
-            return ErrorWindowResult.Exit;
-        }
-
-        try
-        {
-            return await errorWindow.WaitForChoiceAsync().ConfigureAwait(false);
-        }
-        catch (Exception ex)
-        {
-            Logger.Error("Failure window closed unexpectedly.", ex);
-            return ErrorWindowResult.Exit;
-        }
-    }
-
-    private static async Task<bool> TryActivateExistingInstanceAsync()
-    {
-        var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(5)).ConfigureAwait(false);
-        return activation?.Accepted == true;
-    }
-
-    private static async Task<PublicShellActivationResult?> TryActivateExistingInstanceWithStatusAsync(TimeSpan timeout)
-    {
-        try
-        {
-            using var ipcClient = new LanMountainDesktopIpcClient();
-            var connectTask = ipcClient.ConnectAsync();
-            var completedTask = await Task.WhenAny(connectTask, Task.Delay(timeout)).ConfigureAwait(false);
-            if (completedTask != connectTask)
-            {
-                return null;
-            }
-
-            await connectTask.ConfigureAwait(false);
-            if (!ipcClient.IsConnected)
-            {
-                return null;
-            }
-
-            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
-            var activationTask = shellProxy.ActivateMainWindowWithStatusAsync();
-            completedTask = await Task.WhenAny(activationTask, Task.Delay(timeout)).ConfigureAwait(false);
-            if (completedTask != activationTask)
-            {
-                return null;
-            }
-
-            return await activationTask.ConfigureAwait(false);
-        }
-        catch (Exception ex)
-        {
-            Logger.Warn($"Failed to activate the existing desktop instance: {ex.Message}");
-            return null;
-        }
-    }
-
-    private static bool TryGetLiveProcess(int processId)
-    {
-        if (processId <= 0)
-        {
-            return false;
-        }
-
-        try
-        {
-            using var process = Process.GetProcessById(processId);
-            return !process.HasExited;
-        }
-        catch
-        {
-            return false;
-        }
-    }
-
-    private static async Task RunApplyUpdateWithWindowAsync(
-        IClassicDesktopStyleApplicationLifetime desktop,
-        CommandContext context,
-        UpdateWindow window)
-    {
-        var appRoot = Commands.ResolveAppRoot(context);
-        var deploymentLocator = new DeploymentLocator(appRoot);
-        var updateEngine = new UpdateEngineService(deploymentLocator);
-        var pluginInstaller = new PluginInstallerService();
-        var pluginUpgrades = new PluginUpgradeQueueService(pluginInstaller);
-
-        var success = true;
-        string? errorMessage = null;
-
-        try
-        {
-            await Dispatcher.UIThread.InvokeAsync(() => window.Report("verify", Strings.Update_Verifying, 10));
-            var updateResult = await updateEngine.ApplyPendingUpdateAsync().ConfigureAwait(false);
-            if (!updateResult.Success)
-            {
-                success = false;
-                errorMessage = updateResult.Message;
-            }
-
-            if (success)
-            {
-                await Dispatcher.UIThread.InvokeAsync(() => window.Report("plugins", Strings.Update_ApplyingPlugins, 60));
-                var pluginsDir = context.GetOption("plugins-dir") ?? Path.Combine(appRoot, "plugins");
-                var queueResult = pluginUpgrades.ApplyPendingUpgrades(pluginsDir);
-                if (!queueResult.Success && queueResult.Code != "noop")
-                {
-                    Logger.Error($"Plugin upgrade failed during apply-update: {queueResult.Message}");
-                }
-            }
-
-            if (success)
-            {
-                await Dispatcher.UIThread.InvokeAsync(() => window.Report("cleanup", Strings.Update_CleaningUp, 90));
-                deploymentLocator.CleanupOldDeployments(minVersionsToKeep: 3);
-            }
-        }
-        catch (Exception ex)
-        {
-            success = false;
-            errorMessage = ex.Message;
-            Logger.Error("Apply-update flow failed.", ex);
-        }
-
-        await Dispatcher.UIThread.InvokeAsync(() => window.ReportComplete(success, errorMessage));
-        await Task.Delay(success ? 1500 : 5000).ConfigureAwait(false);
-
-        await Commands.WriteResultIfNeededAsync(context.GetOption("result"), new LauncherResult
-        {
-            Success = success,
-            Stage = "apply-update",
-            Code = success ? "ok" : "failed",
-            Message = success ? "Update applied successfully." : (errorMessage ?? "Unknown error"),
-            Details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
-            {
-                ["command"] = context.Command,
-                ["launchSource"] = context.LaunchSource
-            }
-        }).ConfigureAwait(false);
-
-        Environment.ExitCode = success ? 0 : 1;
-        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
-    }
 }

LanMountainDesktop.Launcher/AppJsonContext.cs

@@ -1,7 +1,7 @@
 using System.Text.Json;
 using System.Text.Json.Serialization;
 using LanMountainDesktop.Launcher.Models;
-using LanMountainDesktop.Launcher.Services;
+using LanMountainDesktop.Launcher.Plugins;
 using LanMountainDesktop.Shared.Contracts.Launcher;
 using LanMountainDesktop.Shared.IPC.Abstractions.Services;
 
@@ -30,15 +30,10 @@ namespace LanMountainDesktop.Launcher;
 [JsonSerializable(typeof(PublicTaskbarStatus))]
 [JsonSerializable(typeof(PublicShellActivationResult))]
 [JsonSerializable(typeof(LauncherResult))]
-[JsonSerializable(typeof(HostDiscoveryConfig))]
 [JsonSerializable(typeof(PluginManifest))]
-[JsonSerializable(typeof(PendingUpgrade))]
 [JsonSerializable(typeof(List<PendingUpgrade>))]
 [JsonSerializable(typeof(OobeStateFile))]
 [JsonSerializable(typeof(DataLocationConfig))]
-[JsonSerializable(typeof(GitHubRelease))]
-[JsonSerializable(typeof(GitHubAsset))]
-[JsonSerializable(typeof(List<GitHubRelease>))]
 [JsonSerializable(typeof(StartupAttemptRecord))]
 [JsonSerializable(typeof(PrivacyConfig))]
 [JsonSerializable(typeof(PrivacyAgreementState))]

LanMountainDesktop.Launcher/Deployment/DeploymentLocator.cs

@@ -3,7 +3,7 @@ using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 using LanMountainDesktop.Shared.Contracts.Launcher;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Deployment;
 
 internal sealed class DeploymentLocator
 {

LanMountainDesktop.Launcher/Deployment/HostDiscoveryOptions.cs

@@ -1,4 +1,4 @@
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Deployment;
 
 /// <summary>
 /// 主程序发现选项

LanMountainDesktop.Launcher/Deployment/HostLaunchPlan.cs

@@ -1,6 +1,6 @@
 using LanMountainDesktop.Shared.Contracts.Launcher;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Deployment;
 
 internal sealed record HostLaunchPlan(
     string HostPath,

LanMountainDesktop.Launcher/Deployment/HostResolutionResult.cs

@@ -1,4 +1,4 @@
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Deployment;
 
 internal sealed class HostResolutionResult
 {

LanMountainDesktop.Launcher/Deployment/LegacyVersionDetector.cs

@@ -1,7 +1,7 @@
 using System.Diagnostics;
 using Microsoft.Win32;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Deployment;
 
 /// <summary>
 /// 老版本检测器 - 检测 0.8.x 及更早的单应用模式安装

LanMountainDesktop.Launcher/GlobalUsings.cs

@@ -0,0 +1,8 @@
+global using LanMountainDesktop.Launcher.AirApp;
+global using LanMountainDesktop.Launcher.Deployment;
+global using LanMountainDesktop.Launcher.Infrastructure;
+global using LanMountainDesktop.Launcher.Ipc;
+global using LanMountainDesktop.Launcher.Oobe;
+global using LanMountainDesktop.Launcher.Plugins;
+global using LanMountainDesktop.Launcher.Startup;
+global using LanMountainDesktop.Launcher.Update;

LanMountainDesktop.Launcher/Infrastructure/Commands.cs

@@ -2,7 +2,7 @@ using System.Text;
 using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Infrastructure;
 
 internal static class Commands
 {
@@ -36,7 +36,7 @@ internal static class Commands
     {
         var appRoot = ResolveAppRoot(context);
         var deploymentLocator = new DeploymentLocator(appRoot);
-        var updateEngine = new UpdateEngineService(deploymentLocator);
+        var updateEngine = UpdateEngineFactory.Create(deploymentLocator);
         var pluginInstaller = new PluginInstallerService();
         var pluginUpgrades = new PluginUpgradeQueueService(pluginInstaller);
 
@@ -63,7 +63,7 @@ internal static class Commands
 
     private static async Task<LauncherResult> ExecuteCoreAsync(
         CommandContext context,
-        UpdateEngineService updateEngine,
+        IUpdateEngine updateEngine,
         PluginInstallerService pluginInstaller,
         PluginUpgradeQueueService pluginUpgrades)
     {
@@ -84,7 +84,7 @@ internal static class Commands
         }
     }
 
-    private static async Task<LauncherResult> ExecuteUpdateAsync(CommandContext context, UpdateEngineService updateEngine)
+    private static async Task<LauncherResult> ExecuteUpdateAsync(CommandContext context, IUpdateEngine updateEngine)
     {
         return context.SubCommand.ToLowerInvariant() switch
         {
@@ -102,7 +102,7 @@ internal static class Commands
         };
     }
 
-    private static async Task<LauncherResult> DownloadUpdatePayloadAsync(CommandContext context, UpdateEngineService updateEngine)
+    private static async Task<LauncherResult> DownloadUpdatePayloadAsync(CommandContext context, IUpdateEngine updateEngine)
     {
         return await updateEngine.DownloadAsync(
             context.GetOption("manifest-url") ?? throw new InvalidOperationException("Missing --manifest-url."),
@@ -171,16 +171,12 @@ internal static class Commands
             ? launcherDir
             : AppContext.BaseDirectory);
         
-        // 发布版结构：Launcher 和 app-* 目录在同一目录
-        // 检查当前目录是否有 app-* 子目录（发布版）
         var appDirs = Directory.GetDirectories(baseDir, "app-*", SearchOption.TopDirectoryOnly);
         if (appDirs.Length > 0)
         {
-            // 找到 app-* 目录，说明是发布版结构
             return baseDir;
         }
         
-        // 开发环境：检查父目录是否有主程序
         var parent = Path.GetFullPath(Path.Combine(baseDir, ".."));
         var parentHost = OperatingSystem.IsWindows()
             ? Path.Combine(parent, "LanMountainDesktop.exe")
@@ -190,7 +186,6 @@ internal static class Commands
             return parent;
         }
         
-        // 默认返回 baseDir
         return baseDir;
     }
 }

LanMountainDesktop.Launcher/Infrastructure/DataLocationResolver.cs

@@ -1,7 +1,7 @@
 using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Infrastructure;
 
 /// <summary>
 /// 解析应用数据目录位置。

LanMountainDesktop.Launcher/Infrastructure/DotNetRuntimeProbe.cs

@@ -0,0 +1,401 @@
+using System.Diagnostics;
+using System.Runtime.InteropServices;
+using Microsoft.Win32;
+
+namespace LanMountainDesktop.Launcher.Infrastructure;
+
+internal enum DotNetRuntimeArchitecture
+{
+    X64,
+    X86
+}
+
+internal sealed record DotNetRuntimeInfo(
+    string Name,
+    string Version,
+    string Source,
+    string? Location);
+
+internal sealed record DotNetRuntimeProbeOptions
+{
+    public int RequiredMajorVersion { get; init; } = 10;
+
+    public DotNetRuntimeArchitecture Architecture { get; init; } = DotNetRuntimeProbe.GetCurrentArchitecture();
+
+    public string? ProgramFilesPath { get; init; }
+
+    public string? ProgramFilesX86Path { get; init; }
+
+    public string? LocalAppDataPath { get; init; }
+
+    public IReadOnlyList<string>? DotNetHostCandidates { get; init; }
+
+    public bool IncludeRegistry { get; init; } = true;
+
+    public bool IncludeDotNetCli { get; init; } = true;
+}
+
+internal sealed record DotNetRuntimeProbeResult(
+    bool IsAvailable,
+    int RequiredMajorVersion,
+    DotNetRuntimeArchitecture Architecture,
+    string? DotNetHostPath,
+    IReadOnlyList<string> SearchedPaths,
+    IReadOnlyList<DotNetRuntimeInfo> DetectedRuntimes,
+    string Message)
+{
+    public Dictionary<string, string> ToDetails(string prefix = "dotnetRuntime")
+    {
+        return new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            [$"{prefix}Available"] = IsAvailable.ToString(),
+            [$"{prefix}RequiredMajorVersion"] = RequiredMajorVersion.ToString(),
+            [$"{prefix}Architecture"] = Architecture.ToString(),
+            [$"{prefix}DotNetHostPath"] = DotNetHostPath ?? string.Empty,
+            [$"{prefix}SearchedPaths"] = string.Join(" | ", SearchedPaths),
+            [$"{prefix}DetectedRuntimes"] = string.Join(
+                " | ",
+                DetectedRuntimes.Select(runtime =>
+                    $"{runtime.Name} {runtime.Version} [{runtime.Source}{(string.IsNullOrWhiteSpace(runtime.Location) ? string.Empty : $": {runtime.Location}")}]")),
+            [$"{prefix}Message"] = Message
+        };
+    }
+}
+
+internal static class DotNetRuntimeProbe
+{
+    public const string RequiredSharedFrameworkName = "Microsoft.NETCore.App";
+    public const string WindowsDesktopSharedFrameworkName = "Microsoft.WindowsDesktop.App";
+
+    private static readonly string[] RequiredSharedFrameworkNames =
+    [
+        RequiredSharedFrameworkName,
+        WindowsDesktopSharedFrameworkName
+    ];
+
+    public static DotNetRuntimeProbeResult Probe(DotNetRuntimeProbeOptions? options = null)
+    {
+        options ??= new DotNetRuntimeProbeOptions();
+
+        var searchedPaths = new List<string>();
+        var detected = new List<DotNetRuntimeInfo>();
+        var requiredMajor = options.RequiredMajorVersion;
+
+        var localAppDataRoot = GetLocalAppDataPath(options);
+        var perUserDotnetRoot = !string.IsNullOrWhiteSpace(localAppDataRoot)
+            ? Path.Combine(localAppDataRoot, "dotnet")
+            : null;
+
+        foreach (var frameworkName in RequiredSharedFrameworkNames)
+        {
+            foreach (var basePath in EnumerateDotNetInstallRoots(options))
+            {
+                var sharedFrameworkDirectory = Path.Combine(basePath, "shared", frameworkName);
+                searchedPaths.Add(sharedFrameworkDirectory);
+                var isPerUser = perUserDotnetRoot is not null &&
+                    string.Equals(basePath, perUserDotnetRoot, StringComparison.OrdinalIgnoreCase);
+                AddDirectoryRuntimes(sharedFrameworkDirectory, frameworkName,
+                    isPerUser ? "shared-framework-directory-per-user" : "shared-framework-directory",
+                    detected);
+            }
+        }
+
+        string? dotNetHostPath = null;
+        foreach (var candidate in EnumerateDotNetHostCandidates(options))
+        {
+            searchedPaths.Add(candidate);
+            if (dotNetHostPath is null && File.Exists(candidate))
+            {
+                dotNetHostPath = candidate;
+            }
+        }
+
+        if (OperatingSystem.IsWindows() && options.IncludeRegistry)
+        {
+            foreach (var frameworkName in RequiredSharedFrameworkNames)
+            {
+                AddRegistryRuntimes(options.Architecture, frameworkName, detected);
+            }
+        }
+
+        if (options.IncludeDotNetCli)
+        {
+            AddDotNetCliRuntimes(dotNetHostPath, detected);
+        }
+
+        var isAvailable = detected.Any(runtime =>
+            string.Equals(runtime.Name, RequiredSharedFrameworkName, StringComparison.OrdinalIgnoreCase) &&
+            IsRequiredMajor(runtime.Version, requiredMajor));
+
+        var message = isAvailable
+            ? $".NET {requiredMajor} runtime found for {options.Architecture}."
+            : $".NET {requiredMajor} runtime was not found for {options.Architecture}.";
+
+        return new DotNetRuntimeProbeResult(
+            isAvailable,
+            requiredMajor,
+            options.Architecture,
+            dotNetHostPath,
+            searchedPaths
+                .Where(path => !string.IsNullOrWhiteSpace(path))
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .ToList(),
+            detected
+                .DistinctBy(runtime => $"{runtime.Name}|{runtime.Version}|{runtime.Source}|{runtime.Location}", StringComparer.OrdinalIgnoreCase)
+                .OrderBy(runtime => runtime.Name, StringComparer.OrdinalIgnoreCase)
+                .ThenBy(runtime => runtime.Version, StringComparer.OrdinalIgnoreCase)
+                .ToList(),
+            message);
+    }
+
+    public static DotNetRuntimeArchitecture GetCurrentArchitecture()
+    {
+        return RuntimeInformation.ProcessArchitecture switch
+        {
+            Architecture.X86 => DotNetRuntimeArchitecture.X86,
+            _ => DotNetRuntimeArchitecture.X64
+        };
+    }
+
+    public static string? FindDotNetHostPath(DotNetRuntimeProbeOptions? options = null)
+    {
+        options ??= new DotNetRuntimeProbeOptions();
+        return EnumerateDotNetHostCandidates(options).FirstOrDefault(File.Exists);
+    }
+
+    public static bool IsFrameworkDependentWindowsApp(string executablePath)
+    {
+        if (!OperatingSystem.IsWindows() || string.IsNullOrWhiteSpace(executablePath))
+        {
+            return false;
+        }
+
+        var directory = Path.GetDirectoryName(Path.GetFullPath(executablePath));
+        if (string.IsNullOrWhiteSpace(directory))
+        {
+            return false;
+        }
+
+        var appName = Path.GetFileNameWithoutExtension(executablePath);
+        var runtimeConfigPath = Path.Combine(directory, $"{appName}.runtimeconfig.json");
+        if (!File.Exists(runtimeConfigPath))
+        {
+            return false;
+        }
+
+        return !File.Exists(Path.Combine(directory, "coreclr.dll")) &&
+               !File.Exists(Path.Combine(directory, "hostfxr.dll")) &&
+               !File.Exists(Path.Combine(directory, "hostpolicy.dll")) &&
+               !File.Exists(Path.Combine(directory, "System.Private.CoreLib.dll"));
+    }
+
+    private static IEnumerable<string> EnumerateDotNetInstallRoots(DotNetRuntimeProbeOptions options)
+    {
+        var programFilesRoot = options.Architecture == DotNetRuntimeArchitecture.X86
+            ? GetProgramFilesX86Path(options)
+            : GetProgramFilesPath(options);
+
+        yield return Path.Combine(programFilesRoot, "dotnet");
+
+        var localAppData = GetLocalAppDataPath(options);
+        if (!string.IsNullOrWhiteSpace(localAppData))
+        {
+            var perUserDotnet = Path.Combine(localAppData, "dotnet");
+            if (!string.Equals(perUserDotnet, Path.Combine(programFilesRoot, "dotnet"), StringComparison.OrdinalIgnoreCase))
+            {
+                yield return perUserDotnet;
+            }
+        }
+    }
+
+    private static IEnumerable<string> EnumerateDotNetHostCandidates(DotNetRuntimeProbeOptions options)
+    {
+        if (options.DotNetHostCandidates is not null)
+        {
+            foreach (var candidate in options.DotNetHostCandidates)
+            {
+                if (!string.IsNullOrWhiteSpace(candidate))
+                {
+                    yield return Path.GetFullPath(candidate);
+                }
+            }
+
+            yield break;
+        }
+
+        var programFilesRoot = options.Architecture == DotNetRuntimeArchitecture.X86
+            ? GetProgramFilesX86Path(options)
+            : GetProgramFilesPath(options);
+
+        yield return Path.Combine(programFilesRoot, "dotnet", OperatingSystem.IsWindows() ? "dotnet.exe" : "dotnet");
+
+        var localAppData = GetLocalAppDataPath(options);
+        if (!string.IsNullOrWhiteSpace(localAppData))
+        {
+            var perUserHost = Path.Combine(localAppData, "dotnet", OperatingSystem.IsWindows() ? "dotnet.exe" : "dotnet");
+            if (!string.Equals(perUserHost, Path.Combine(programFilesRoot, "dotnet", OperatingSystem.IsWindows() ? "dotnet.exe" : "dotnet"), StringComparison.OrdinalIgnoreCase))
+            {
+                yield return perUserHost;
+            }
+        }
+    }
+
+    private static string GetProgramFilesPath(DotNetRuntimeProbeOptions options)
+    {
+        if (!string.IsNullOrWhiteSpace(options.ProgramFilesPath))
+        {
+            return Path.GetFullPath(options.ProgramFilesPath);
+        }
+
+        return Environment.GetEnvironmentVariable("ProgramW6432") ??
+               Environment.GetFolderPath(Environment.SpecialFolder.ProgramFiles);
+    }
+
+    private static string GetProgramFilesX86Path(DotNetRuntimeProbeOptions options)
+    {
+        if (!string.IsNullOrWhiteSpace(options.ProgramFilesX86Path))
+        {
+            return Path.GetFullPath(options.ProgramFilesX86Path);
+        }
+
+        return Environment.GetEnvironmentVariable("ProgramFiles(x86)") ??
+               Environment.GetFolderPath(Environment.SpecialFolder.ProgramFilesX86);
+    }
+
+    private static string GetLocalAppDataPath(DotNetRuntimeProbeOptions options)
+    {
+        if (!string.IsNullOrWhiteSpace(options.LocalAppDataPath))
+        {
+            return Path.GetFullPath(options.LocalAppDataPath);
+        }
+
+        return Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+    }
+
+    private static void AddDirectoryRuntimes(
+        string sharedFrameworkDirectory,
+        string sharedFrameworkName,
+        string source,
+        List<DotNetRuntimeInfo> detected)
+    {
+        if (!Directory.Exists(sharedFrameworkDirectory))
+        {
+            return;
+        }
+
+        foreach (var directory in Directory.GetDirectories(sharedFrameworkDirectory))
+        {
+            var version = Path.GetFileName(directory);
+            if (!string.IsNullOrWhiteSpace(version))
+            {
+                detected.Add(new DotNetRuntimeInfo(sharedFrameworkName, version, source, directory));
+            }
+        }
+    }
+
+    private static void AddRegistryRuntimes(
+        DotNetRuntimeArchitecture architecture,
+        string sharedFrameworkName,
+        List<DotNetRuntimeInfo> detected)
+    {
+        try
+        {
+            var registryView = architecture == DotNetRuntimeArchitecture.X86
+                ? RegistryView.Registry32
+                : RegistryView.Registry64;
+            using var baseKey = RegistryKey.OpenBaseKey(RegistryHive.LocalMachine, registryView);
+            using var key = baseKey.OpenSubKey(
+                $@"SOFTWARE\dotnet\Setup\InstalledVersions\{(architecture == DotNetRuntimeArchitecture.X86 ? "x86" : "x64")}\sharedfx\{sharedFrameworkName}");
+
+            if (key is null)
+            {
+                return;
+            }
+
+            foreach (var valueName in key.GetValueNames())
+            {
+                if (key.GetValue(valueName) is not null)
+                {
+                    detected.Add(new DotNetRuntimeInfo(sharedFrameworkName, valueName, "registry", key.Name));
+                }
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to inspect .NET runtime registry keys: {ex.Message}");
+        }
+    }
+
+    private static void AddDotNetCliRuntimes(
+        string? dotNetHostPath,
+        List<DotNetRuntimeInfo> detected)
+    {
+        if (string.IsNullOrWhiteSpace(dotNetHostPath) || !File.Exists(dotNetHostPath))
+        {
+            return;
+        }
+
+        try
+        {
+            using var process = new Process();
+            process.StartInfo = new ProcessStartInfo
+            {
+                FileName = dotNetHostPath,
+                Arguments = "--list-runtimes",
+                UseShellExecute = false,
+                RedirectStandardOutput = true,
+                RedirectStandardError = true,
+                CreateNoWindow = true
+            };
+
+            process.Start();
+            var output = process.StandardOutput.ReadToEnd();
+            process.WaitForExit(3000);
+
+            foreach (var line in output.Split(Environment.NewLine, StringSplitOptions.RemoveEmptyEntries))
+            {
+                var parsed = ParseListRuntimeLine(line);
+                if (parsed is not null &&
+                    RequiredSharedFrameworkNames.Contains(parsed.Value.Name, StringComparer.OrdinalIgnoreCase))
+                {
+                    detected.Add(new DotNetRuntimeInfo(
+                        parsed.Value.Name,
+                        parsed.Value.Version,
+                        "dotnet-cli",
+                        parsed.Value.Location));
+                }
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to inspect .NET runtimes via dotnet CLI: {ex.Message}");
+        }
+    }
+
+    private static (string Name, string Version, string? Location)? ParseListRuntimeLine(string line)
+    {
+        var firstSpace = line.IndexOf(' ');
+        if (firstSpace <= 0 || firstSpace + 1 >= line.Length)
+        {
+            return null;
+        }
+
+        var secondSpace = line.IndexOf(' ', firstSpace + 1);
+        if (secondSpace <= firstSpace)
+        {
+            return null;
+        }
+
+        var name = line[..firstSpace].Trim();
+        var version = line[(firstSpace + 1)..secondSpace].Trim();
+        var location = line[(secondSpace + 1)..].Trim().Trim('[', ']');
+        return (name, version, string.IsNullOrWhiteSpace(location) ? null : location);
+    }
+
+    private static bool IsRequiredMajor(string version, int requiredMajor)
+    {
+        var dotIndex = version.IndexOf('.');
+        var majorText = dotIndex < 0 ? version : version[..dotIndex];
+        return int.TryParse(majorText, out var major) && major == requiredMajor;
+    }
+}

LanMountainDesktop.Launcher/Infrastructure/ISplashStageReporter.cs

@@ -1,4 +1,4 @@
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Infrastructure;
 
 internal interface ISplashStageReporter
 {

LanMountainDesktop.Launcher/Infrastructure/LanguagePreferenceService.cs

@@ -1,7 +1,7 @@
 using System.Globalization;
 using System.Text.Json.Nodes;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Infrastructure;
 
 internal static class LanguagePreferenceService
 {

LanMountainDesktop.Launcher/Infrastructure/LauncherDebugSettingsStore.cs

@@ -1,4 +1,4 @@
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Infrastructure;
 
 internal sealed record LauncherDebugSettings(bool DevModeEnabled, string? CustomHostPath);
 

LanMountainDesktop.Launcher/Infrastructure/LauncherExecutionContext.cs

@@ -1,7 +1,7 @@
 using System.Security.Principal;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Infrastructure;
 
 internal static class LauncherExecutionContext
 {

LanMountainDesktop.Launcher/Infrastructure/Logger.cs

@@ -1,6 +1,6 @@
 using System.Text;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Infrastructure;
 
 /// <summary>
 /// 简单的日志记录器 - 同时输出到控制台和文件

LanMountainDesktop.Launcher/Ipc/LauncherCoordinatorIpcClient.cs

@@ -3,7 +3,7 @@ using System.Text;
 using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services.Ipc;
+namespace LanMountainDesktop.Launcher.Ipc;
 
 internal sealed class LauncherCoordinatorIpcClient
 {

LanMountainDesktop.Launcher/Ipc/LauncherCoordinatorIpcServer.cs

@@ -4,7 +4,7 @@ using System.Text.Json;
 using System.IO.Pipes;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services.Ipc;
+namespace LanMountainDesktop.Launcher.Ipc;
 
 internal sealed class LauncherCoordinatorIpcServer : IDisposable
 {

LanMountainDesktop.Launcher/Ipc/LauncherUpdateProgressIpcServer.cs

@@ -2,10 +2,9 @@ using System.Buffers;
 using System.IO.Pipes;
 using System.Text;
 using System.Text.Json;
-using LanMountainDesktop.Launcher.Services;
 using LanMountainDesktop.Shared.Contracts.Update;
 
-namespace LanMountainDesktop.Launcher.Services.Ipc;
+namespace LanMountainDesktop.Launcher.Ipc;
 
 internal sealed class LauncherUpdateProgressIpcServer : IUpdateProgressReporter, IDisposable
 {

LanMountainDesktop.Launcher/LanMountainDesktop.Launcher.csproj

@@ -18,6 +18,7 @@
   <ItemGroup>
     <!-- 只引用 Shared.Contracts（IPC 协议） -->
     <ProjectReference Include="..\LanMountainDesktop.Shared.Contracts\LanMountainDesktop.Shared.Contracts.csproj" />
+    <ProjectReference Include="..\LanMountainDesktop.PluginPackaging\LanMountainDesktop.PluginPackaging.csproj" />
     <ProjectReference Include="..\LanMountainDesktop.Shared.IPC\LanMountainDesktop.Shared.IPC.csproj" />
   </ItemGroup>
 
@@ -29,6 +30,7 @@
     <PackageReference Include="Avalonia.Fonts.Inter" />
     <PackageReference Include="ClassIsland.Markdown.Avalonia" />
     <PackageReference Include="CommunityToolkit.Mvvm" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
     <PackageReference Include="Tmds.DBus.Protocol" />
   </ItemGroup>
 

LanMountainDesktop.Launcher/Oobe/DataLocationOobeStep.cs

@@ -2,7 +2,7 @@ using Avalonia.Threading;
 using LanMountainDesktop.Launcher.Models;
 using LanMountainDesktop.Launcher.Views;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Oobe;
 
 internal sealed class DataLocationOobeStep : IOobeStep
 {

LanMountainDesktop.Launcher/Oobe/HostAppSettingsOobeMerger.cs

@@ -2,7 +2,7 @@ using System.Text.Json;
 using System.Text.Json.Nodes;
 using LanMountainDesktop.Shared.Contracts.Launcher;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Oobe;
 
 /// <summary>
 /// 在 OOBE 中向 Host 的 settings.json 写入启动与展示相关字段，属性名与 Host

LanMountainDesktop.Launcher/Oobe/IOobeStep.cs

@@ -1,4 +1,4 @@
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Oobe;
 
 internal interface IOobeStep
 {

LanMountainDesktop.Launcher/Oobe/LauncherWindowsStartupService.cs

@@ -1,7 +1,7 @@
 using System;
 using Microsoft.Win32;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Oobe;
 
 /// <summary>
 /// 将当前 Windows 用户登录时自启动项指向<strong>本 Launcher 进程</strong>（与正式入口一致）。

LanMountainDesktop.Launcher/Oobe/OobeStateService.cs

@@ -1,7 +1,7 @@
 using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Oobe;
 
 internal sealed class OobeStateService
 {

LanMountainDesktop.Launcher/Oobe/PrivacyAgreementService.cs

@@ -3,7 +3,7 @@ using System.Text;
 using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Oobe;
 
 /// <summary>
 /// 隐私协议同意状态管理服务（带防篡改保护）

LanMountainDesktop.Launcher/Oobe/WelcomeOobeStep.cs

@@ -1,7 +1,7 @@
 using Avalonia.Threading;
 using LanMountainDesktop.Launcher.Views;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Oobe;
 
 internal sealed class WelcomeOobeStep : IOobeStep
 {

LanMountainDesktop.Launcher/Plugins/PluginInstallerService.cs

@@ -2,7 +2,7 @@ using System.IO.Compression;
 using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Plugins;
 
 /// <summary>
 /// 插件安装服务 - 简化版，不依赖 PluginSdk
@@ -290,7 +290,7 @@ internal sealed class PluginInstallerService
 /// <summary>
 /// 简化的插件清单模型
 /// </summary>
-public class PluginManifest
+internal class PluginManifest
 {
     public string Id { get; set; } = "";
     public string Name { get; set; } = "";

LanMountainDesktop.Launcher/Plugins/PluginUpgradeQueueService.cs

@@ -1,7 +1,7 @@
 using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Plugins;
 
 internal sealed class PluginUpgradeQueueService
 {
@@ -29,7 +29,7 @@ internal sealed class PluginUpgradeQueueService
         }
 
         var text = File.ReadAllText(pendingPath);
-        var pending = JsonSerializer.Deserialize(text, AppJsonContext.Default.ListPendingUpgrade) ?? [];
+        var pending = JsonSerializer.Deserialize<List<PendingUpgrade>>(text, AppJsonContext.Default.Options) ?? [];
         var failures = new List<string>();
         var succeeded = new List<PendingUpgrade>();
 
@@ -63,7 +63,7 @@ internal sealed class PluginUpgradeQueueService
         }
         else
         {
-            File.WriteAllText(pendingPath, JsonSerializer.Serialize(remaining, AppJsonContext.Default.ListPendingUpgrade));
+            File.WriteAllText(pendingPath, JsonSerializer.Serialize(remaining, AppJsonContext.Default.Options));
         }
 
         return new LauncherResult

LanMountainDesktop.Launcher/Program.cs

@@ -1,7 +1,6 @@
 using Avalonia;
 using LanMountainDesktop.Launcher.Models;
-using LanMountainDesktop.Launcher.Services;
-
+using LanMountainDesktop.Launcher.Shell;
 namespace LanMountainDesktop.Launcher;
 
 public static class Program
@@ -34,6 +33,7 @@ public static class Program
             }
 
             LauncherRuntimeContext.Current = commandContext;
+            LauncherServiceRegistration.Initialize(commandContext);
 
             var appRoot = Commands.ResolveAppRoot(commandContext);
             var languageCode = LanguagePreferenceService.ResolveLanguageCode(appRoot);

LanMountainDesktop.Launcher/Services/FlexibleHostLocator.cs

@@ -1,634 +0,0 @@
-using System.Diagnostics;
-using System.Text.Json;
-
-namespace LanMountainDesktop.Launcher.Services;
-
-/// <summary>
-    /// 灵活的主程序定位器
-    /// </summary>
-    internal sealed class FlexibleHostLocator
-    {
-        private readonly HostDiscoveryOptions _options;
-        private readonly string _appRoot;
-        private readonly DeploymentLocator _deploymentLocator;
-
-        public FlexibleHostLocator(string appRoot, HostDiscoveryOptions? options = null)
-        {
-            _appRoot = appRoot;
-            _options = options ?? new HostDiscoveryOptions();
-            _deploymentLocator = new DeploymentLocator(appRoot);
-        }
-
-        /// <summary>
-        /// 解析主程序可执行文件路径
-        /// </summary>
-        public string? ResolveHostExecutablePath()
-        {
-            var executable = GetExecutableName();
-            var searchContext = new SearchContext
-            {
-                ExecutableName = executable,
-                AppRoot = _appRoot,
-                Options = _options
-            };
-
-            // ========== 第一阶段：标准路径查找（快速路径）==========
-            
-            // 1. 检查环境变量指定的路径（最高优先级 - 用于调试和特殊场景）
-            var envPath = GetPathFromEnvironment();
-            if (!string.IsNullOrWhiteSpace(envPath))
-            {
-                var validated = ValidateAndReturn(envPath, "environment variable");
-                if (validated != null) return validated;
-            }
-
-            // 2. 使用 DeploymentLocator（ClassIsland 风格的简洁查询 - 优先）
-            Console.WriteLine("[FlexibleHostLocator] Trying quick path: DeploymentLocator.FindCurrentDeploymentDirectory()");
-            var deploymentDir = _deploymentLocator.FindCurrentDeploymentDirectory();
-            if (!string.IsNullOrWhiteSpace(deploymentDir))
-            {
-                var deploymentExePath = Path.Combine(deploymentDir, executable);
-                if (File.Exists(deploymentExePath))
-                {
-                    Console.WriteLine($"[FlexibleHostLocator] Quick path found: {deploymentExePath}");
-                    return deploymentExePath;
-                }
-                Console.WriteLine($"[FlexibleHostLocator] Quick path found dir but no exe: {deploymentExePath}");
-            }
-
-            // 3. 快速路径失败，尝试旧的 SearchDeploymentDirectories 作为 fallback
-            Console.WriteLine("[FlexibleHostLocator] Quick path failed, falling back to SearchDeploymentDirectories");
-            var deploymentPath = SearchDeploymentDirectories(searchContext);
-            if (!string.IsNullOrWhiteSpace(deploymentPath))
-            {
-                return deploymentPath;
-            }
-
-        // 4. 检查 Launcher 同级目录（便携模式）
-        var portablePath = SearchPortableLocation(searchContext);
-        if (!string.IsNullOrWhiteSpace(portablePath))
-        {
-            return portablePath;
-        }
-
-        // ========== 第二阶段：灵活查找（标准路径找不到时）==========
-        
-        // 5. 检查配置文件中的路径 - 用户自定义配置
-        var configPath = GetPathFromConfigFile();
-        if (!string.IsNullOrWhiteSpace(configPath))
-        {
-            var validated = ValidateAndReturn(configPath, "config file");
-            if (validated != null) return validated;
-        }
-
-        // 5. 搜索附近目录（向上、向下各一层）
-        var nearbyPath = SearchNearbyDirectories(searchContext);
-        if (!string.IsNullOrWhiteSpace(nearbyPath))
-        {
-            return nearbyPath;
-        }
-
-        // 7. 开发模式：检查保存的自定义路径
-        if (_options.PreferDevModeConfig && Views.ErrorWindow.CheckDevModeEnabled())
-        {
-            var savedPath = Views.ErrorWindow.GetSavedCustomHostPath();
-            if (!string.IsNullOrWhiteSpace(savedPath))
-            {
-                var validated = ValidateAndReturn(savedPath, "saved dev mode path");
-                if (validated != null) return validated;
-            }
-        }
-
-        // 8. 搜索标准开发路径
-        var devPath = SearchDevelopmentPaths(searchContext);
-        if (!string.IsNullOrWhiteSpace(devPath))
-        {
-            return devPath;
-        }
-
-        // 9. 搜索额外的配置路径
-        var additionalPath = SearchAdditionalPaths(searchContext);
-        if (!string.IsNullOrWhiteSpace(additionalPath))
-        {
-            return additionalPath;
-        }
-
-        // 10. 递归搜索（如果启用）
-        if (_options.RecursiveSearch)
-        {
-            var recursivePath = SearchRecursively(searchContext);
-            if (!string.IsNullOrWhiteSpace(recursivePath))
-            {
-                return recursivePath;
-            }
-        }
-
-        return null;
-    }
-
-    /// <summary>
-    /// 从环境变量获取路径
-    /// </summary>
-    private string? GetPathFromEnvironment()
-    {
-        if (string.IsNullOrWhiteSpace(_options.CustomPathEnvVar))
-        {
-            return null;
-        }
-
-        var path = Environment.GetEnvironmentVariable(_options.CustomPathEnvVar);
-        return path;
-    }
-
-    /// <summary>
-    /// 从配置文件获取路径
-    /// </summary>
-    private string? GetPathFromConfigFile()
-    {
-        if (string.IsNullOrWhiteSpace(_options.ConfigFileName))
-        {
-            return null;
-        }
-
-        var configPath = Path.Combine(_appRoot, _options.ConfigFileName);
-        if (!File.Exists(configPath))
-        {
-            return null;
-        }
-
-        try
-        {
-            var json = File.ReadAllText(configPath);
-            var config = JsonSerializer.Deserialize(json, AppJsonContext.Default.HostDiscoveryConfig);
-            if (config?.HostPath != null && File.Exists(config.HostPath))
-            {
-                return config.HostPath;
-            }
-        }
-        catch
-        {
-            // 忽略配置文件读取错误
-        }
-
-        return null;
-    }
-
-    /// <summary>
-    /// 搜索部署目录
-    /// </summary>
-    private string? SearchDeploymentDirectories(SearchContext context)
-    {
-        if (!Directory.Exists(_appRoot))
-        {
-            return null;
-        }
-
-        try
-        {
-            // 查找 app-* 目录
-            var appDirs = Directory.GetDirectories(_appRoot, "app-*", SearchOption.TopDirectoryOnly)
-                .Where(dir => !File.Exists(Path.Combine(dir, ".destroy")))
-                .Where(dir => !File.Exists(Path.Combine(dir, ".partial")))
-                .ToList();
-
-            // 优先选择带 .current 标记的
-            var currentMarked = appDirs
-                .Where(dir => File.Exists(Path.Combine(dir, ".current")))
-                .Select(dir => Path.Combine(dir, context.ExecutableName))
-                .FirstOrDefault(File.Exists);
-
-            if (currentMarked != null)
-            {
-                return currentMarked;
-            }
-
-            // 选择版本号最高的
-            var latest = appDirs
-                .Select(dir => new
-                {
-                    Dir = dir,
-                    Version = ParseVersionFromDirectoryName(dir)
-                })
-                .OrderByDescending(x => x.Version)
-                .Select(x => Path.Combine(x.Dir, context.ExecutableName))
-                .FirstOrDefault(File.Exists);
-
-            return latest;
-        }
-        catch
-        {
-            return null;
-        }
-    }
-
-    /// <summary>
-    /// 搜索便携模式位置（Launcher 同级目录）
-    /// </summary>
-    private string? SearchPortableLocation(SearchContext context)
-    {
-        try
-        {
-            var launcherDir = AppContext.BaseDirectory;
-            var portablePath = Path.Combine(launcherDir, context.ExecutableName);
-            
-            if (File.Exists(portablePath))
-            {
-                return portablePath;
-            }
-        }
-        catch
-        {
-            // 忽略错误
-        }
-        return null;
-    }
-
-    /// <summary>
-    /// 搜索附近目录（灵活查找，适用于各种部署场景）
-    /// </summary>
-    private string? SearchNearbyDirectories(SearchContext context)
-    {
-        try
-        {
-            var searchDirs = new List<string>();
-            
-            // Launcher 所在目录
-            var launcherDir = AppContext.BaseDirectory;
-            searchDirs.Add(launcherDir);
-            
-            // 上级目录
-            var parentDir = Path.GetFullPath(Path.Combine(launcherDir, ".."));
-            if (Directory.Exists(parentDir))
-            {
-                searchDirs.Add(parentDir);
-            }
-            
-            // 上上级目录
-            var grandparentDir = Path.GetFullPath(Path.Combine(launcherDir, "..", ".."));
-            if (Directory.Exists(grandparentDir))
-            {
-                searchDirs.Add(grandparentDir);
-            }
-            
-            // AppRoot 及其上级
-            if (!string.IsNullOrWhiteSpace(_appRoot) && Directory.Exists(_appRoot))
-            {
-                searchDirs.Add(_appRoot);
-                var appParent = Path.GetFullPath(Path.Combine(_appRoot, ".."));
-                if (Directory.Exists(appParent))
-                {
-                    searchDirs.Add(appParent);
-                }
-            }
-            
-            // 去重后搜索
-            foreach (var dir in searchDirs.Distinct(StringComparer.OrdinalIgnoreCase))
-            {
-                // 直接搜索
-                var directPath = Path.Combine(dir, context.ExecutableName);
-                if (File.Exists(directPath))
-                {
-                    return directPath;
-                }
-                
-                // 搜索子目录（一层）
-                if (Directory.Exists(dir))
-                {
-                    foreach (var subDir in Directory.GetDirectories(dir))
-                    {
-                        var subPath = Path.Combine(subDir, context.ExecutableName);
-                        if (File.Exists(subPath))
-                        {
-                            return subPath;
-                        }
-                    }
-                }
-            }
-        }
-        catch
-        {
-            // 忽略搜索错误
-        }
-        
-        return null;
-    }
-
-    /// <summary>
-    /// 搜索开发路径
-    /// </summary>
-    private string? SearchDevelopmentPaths(SearchContext context)
-    {
-        // 获取 Launcher 所在目录
-        var launcherDir = AppContext.BaseDirectory;
-
-        // 动态构建可能的开发路径（支持不同的项目结构）
-        var possiblePaths = new List<string>();
-
-        // 从解决方案根目录搜索（支持不同的解决方案结构）
-        var solutionRoot = FindSolutionRoot(launcherDir);
-        if (!string.IsNullOrWhiteSpace(solutionRoot))
-        {
-            // 搜索所有可能的 bin 目录
-            possiblePaths.AddRange(SearchBinDirectories(solutionRoot, context.ExecutableName));
-        }
-
-        // 添加硬编码的备用路径
-        possiblePaths.AddRange(new[]
-        {
-            Path.Combine(launcherDir, "..", "..", "LanMountainDesktop", "bin", "Debug", "net10.0", context.ExecutableName),
-            Path.Combine(launcherDir, "..", "..", "LanMountainDesktop", "bin", "Release", "net10.0", context.ExecutableName),
-            Path.Combine(launcherDir, "..", "LanMountainDesktop", "bin", "Debug", "net10.0", context.ExecutableName),
-            Path.Combine(launcherDir, "..", "LanMountainDesktop", "bin", "Release", "net10.0", context.ExecutableName),
-        });
-
-        foreach (var path in possiblePaths.Select(Path.GetFullPath).Distinct())
-        {
-            if (File.Exists(path))
-            {
-                return path;
-            }
-        }
-
-        return null;
-    }
-
-    /// <summary>
-    /// 搜索额外的配置路径
-    /// </summary>
-    private string? SearchAdditionalPaths(SearchContext context)
-    {
-        if (_options.AdditionalSearchPaths == null || !_options.AdditionalSearchPaths.Any())
-        {
-            return null;
-        }
-
-        foreach (var pattern in _options.AdditionalSearchPaths)
-        {
-            try
-            {
-                // 替换变量
-                var expandedPattern = ExpandVariables(pattern);
-
-                // 支持通配符
-                if (expandedPattern.Contains('*') || expandedPattern.Contains('?'))
-                {
-                    var dir = Path.GetDirectoryName(expandedPattern) ?? _appRoot;
-                    var filePattern = Path.GetFileName(expandedPattern);
-
-                    if (Directory.Exists(dir))
-                    {
-                        var matches = Directory.GetFiles(dir, filePattern, SearchOption.TopDirectoryOnly);
-                        var validMatch = matches.FirstOrDefault(File.Exists);
-                        if (validMatch != null)
-                        {
-                            return validMatch;
-                        }
-                    }
-                }
-                else if (File.Exists(expandedPattern))
-                {
-                    return expandedPattern;
-                }
-            }
-            catch
-            {
-                // 忽略搜索错误
-            }
-        }
-
-        return null;
-    }
-
-    /// <summary>
-    /// 递归搜索
-    /// </summary>
-    private string? SearchRecursively(SearchContext context)
-    {
-        try
-        {
-            var searchDirs = new[] { _appRoot, Path.GetFullPath(Path.Combine(_appRoot, "..")) };
-
-            foreach (var searchDir in searchDirs.Where(Directory.Exists))
-            {
-                var result = SearchDirectoryRecursively(searchDir, context.ExecutableName, 0);
-                if (result != null)
-                {
-                    return result;
-                }
-            }
-        }
-        catch
-        {
-            // 忽略递归搜索错误
-        }
-
-        return null;
-    }
-
-    /// <summary>
-    /// 递归搜索目录
-    /// </summary>
-    private string? SearchDirectoryRecursively(string dir, string executableName, int depth)
-    {
-        if (depth > _options.MaxRecursionDepth)
-        {
-            return null;
-        }
-
-        try
-        {
-            // 检查当前目录
-            var directPath = Path.Combine(dir, executableName);
-            if (File.Exists(directPath))
-            {
-                return directPath;
-            }
-
-            // 检查子目录
-            foreach (var subDir in Directory.GetDirectories(dir))
-            {
-                // 跳过某些目录
-                var dirName = Path.GetFileName(subDir).ToLowerInvariant();
-                if (dirName is ".git" or "node_modules" or ".vs" or "obj" or ".launcher")
-                {
-                    continue;
-                }
-
-                var result = SearchDirectoryRecursively(subDir, executableName, depth + 1);
-                if (result != null)
-                {
-                    return result;
-                }
-            }
-        }
-        catch
-        {
-            // 忽略访问错误
-        }
-
-        return null;
-    }
-
-    /// <summary>
-    /// 查找解决方案根目录
-    /// </summary>
-    private string? FindSolutionRoot(string startDir)
-    {
-        var current = new DirectoryInfo(startDir);
-        while (current != null)
-        {
-            // 查找 .sln 文件
-            if (current.GetFiles("*.sln").Any())
-            {
-                return current.FullName;
-            }
-
-            // 查找 .git 目录作为备选
-            if (current.GetDirectories(".git").Any())
-            {
-                return current.FullName;
-            }
-
-            current = current.Parent;
-        }
-
-        return null;
-    }
-
-    /// <summary>
-    /// 搜索 bin 目录
-    /// </summary>
-    private IEnumerable<string> SearchBinDirectories(string root, string executableName)
-    {
-        var results = new List<string>();
-
-        try
-        {
-            // 查找所有 bin 目录
-            var binDirs = Directory.GetDirectories(root, "bin", SearchOption.AllDirectories);
-
-            foreach (var binDir in binDirs)
-            {
-                // 检查 Debug 和 Release 子目录
-                var configDirs = new[] { "Debug", "Release" };
-                foreach (var config in configDirs)
-                {
-                    var configPath = Path.Combine(binDir, config);
-                    if (Directory.Exists(configPath))
-                    {
-                        // 检查所有 net* 子目录
-                        var frameworkDirs = Directory.GetDirectories(configPath, "net*");
-                        foreach (var fwDir in frameworkDirs)
-                        {
-                            var exePath = Path.Combine(fwDir, executableName);
-                            if (File.Exists(exePath))
-                            {
-                                results.Add(exePath);
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        catch
-        {
-            // 忽略搜索错误
-        }
-
-        return results;
-    }
-
-    /// <summary>
-    /// 验证路径并返回
-    /// </summary>
-    private string? ValidateAndReturn(string path, string source)
-    {
-        if (File.Exists(path))
-        {
-            Debug.WriteLine($"Found host executable from {source}: {path}");
-            return path;
-        }
-
-        // 尝试添加 .exe（Windows）
-        if (OperatingSystem.IsWindows() && !path.EndsWith(".exe", StringComparison.OrdinalIgnoreCase))
-        {
-            var withExe = path + ".exe";
-            if (File.Exists(withExe))
-            {
-                Debug.WriteLine($"Found host executable from {source}: {withExe}");
-                return withExe;
-            }
-        }
-
-        if (string.Equals(source, "saved dev mode path", StringComparison.OrdinalIgnoreCase))
-        {
-            Logger.Warn($"Saved launcher debug host path is invalid; continuing host discovery. Path='{path}'.");
-        }
-
-        return null;
-    }
-
-    /// <summary>
-    /// 获取可执行文件名
-    /// </summary>
-    private string GetExecutableName()
-    {
-        var name = _options.ExecutableName;
-        if (OperatingSystem.IsWindows() && !name.EndsWith(".exe", StringComparison.OrdinalIgnoreCase))
-        {
-            name += ".exe";
-        }
-        return name;
-    }
-
-    /// <summary>
-    /// 展开路径变量
-    /// </summary>
-    private string ExpandVariables(string path)
-    {
-        return path
-            .Replace("${AppRoot}", _appRoot)
-            .Replace("${BaseDirectory}", AppContext.BaseDirectory)
-            .Replace("${UserProfile}", Environment.GetFolderPath(Environment.SpecialFolder.UserProfile))
-            .Replace("${LocalAppData}", Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData));
-    }
-
-    /// <summary>
-    /// 从目录名解析版本
-    /// </summary>
-    private static Version ParseVersionFromDirectoryName(string path)
-    {
-        var fileName = Path.GetFileName(path);
-        if (string.IsNullOrWhiteSpace(fileName))
-        {
-            return new Version(0, 0, 0);
-        }
-
-        var segments = fileName.Split('-');
-        if (segments.Length < 2)
-        {
-            return new Version(0, 0, 0);
-        }
-
-        return Version.TryParse(segments[1], out var version) ? version : new Version(0, 0, 0);
-    }
-
-    /// <summary>
-    /// 搜索上下文
-    /// </summary>
-    private class SearchContext
-    {
-        public required string ExecutableName { get; set; }
-        public required string AppRoot { get; set; }
-        public required HostDiscoveryOptions Options { get; set; }
-    }
-}
-
-/// <summary>
-/// 发现配置文件
-/// </summary>
-internal class HostDiscoveryConfig
-{
-    public string? HostPath { get; set; }
-    public List<string>? AdditionalPaths { get; set; }
-}

LanMountainDesktop.Launcher/Services/UpdateCheckService.cs

@@ -1,161 +0,0 @@
-using System.Net.Http;
-using System.Net.Http.Json;
-using System.Text.Json;
-using System.Text.Json.Serialization;
-using LanMountainDesktop.Launcher.Models;
-
-namespace LanMountainDesktop.Launcher.Services;
-
-/// <summary>
-/// 更新检查服务 - 基于 GitHub Release API
-/// </summary>
-internal sealed class UpdateCheckService
-{
-    private const string GitHubApiBase = "https://api.github.com";
-    private readonly string _repoOwner;
-    private readonly string _repoName;
-    private readonly HttpClient _httpClient;
-
-    public UpdateCheckService(string repoOwner, string repoName)
-    {
-        _repoOwner = repoOwner;
-        _repoName = repoName;
-        _httpClient = new HttpClient();
-        _httpClient.DefaultRequestHeaders.Add("User-Agent", "LanMountainDesktop-Launcher");
-        _httpClient.DefaultRequestHeaders.Add("Accept", "application/vnd.github+json");
-    }
-
-    /// <summary>
-    /// 检查更新
-    /// </summary>
-    public async Task<UpdateCheckResult> CheckForUpdateAsync(
-        string currentVersion,
-        UpdateChannel channel,
-        CancellationToken cancellationToken = default)
-    {
-        try
-        {
-            var releases = await FetchReleasesAsync(cancellationToken);
-            
-            // 根据频道过滤版本
-            var filteredReleases = channel == UpdateChannel.Stable
-                ? releases.Where(r => !r.Prerelease).ToList()
-                : releases;
-
-            // 找到最新版本
-            var latestRelease = filteredReleases
-                .OrderByDescending(r => ParseVersion(r.TagName))
-                .FirstOrDefault();
-
-            if (latestRelease == null)
-            {
-                return new UpdateCheckResult
-                {
-                    HasUpdate = false,
-                    CurrentVersion = currentVersion,
-                    ErrorMessage = "No releases found"
-                };
-            }
-
-            var latestVersion = ParseVersionString(latestRelease.TagName);
-            var current = ParseVersion(currentVersion);
-            var latest = ParseVersion(latestVersion);
-
-            return new UpdateCheckResult
-            {
-                HasUpdate = latest > current,
-                LatestVersion = latestVersion,
-                CurrentVersion = currentVersion,
-                Release = latestRelease
-            };
-        }
-        catch (Exception ex)
-        {
-            return new UpdateCheckResult
-            {
-                HasUpdate = false,
-                CurrentVersion = currentVersion,
-                ErrorMessage = ex.Message
-            };
-        }
-    }
-
-    /// <summary>
-    /// 获取所有 Release
-    /// </summary>
-    private async Task<List<ReleaseInfo>> FetchReleasesAsync(CancellationToken cancellationToken)
-    {
-        var url = $"{GitHubApiBase}/repos/{_repoOwner}/{_repoName}/releases";
-        var response = await _httpClient.GetAsync(url, cancellationToken);
-        response.EnsureSuccessStatusCode();
-
-        var json = await response.Content.ReadAsStringAsync(cancellationToken);
-        var releases = JsonSerializer.Deserialize(json, AppJsonContext.Default.ListGitHubRelease);
-
-        return releases?.Select(r => new ReleaseInfo
-        {
-            TagName = r.TagName ?? "",
-            Name = r.Name ?? "",
-            Prerelease = r.Prerelease,
-            PublishedAt = r.PublishedAt,
-            Body = r.Body,
-            Assets = r.Assets?.Select(a => new ReleaseAsset
-            {
-                Name = a.Name ?? "",
-                BrowserDownloadUrl = a.BrowserDownloadUrl ?? "",
-                Size = a.Size
-            }).ToList() ?? []
-        }).ToList() ?? [];
-    }
-
-    /// <summary>
-    /// 从 tag 解析版本号 (例如: v1.0.0 -> 1.0.0)
-    /// </summary>
-    private static string ParseVersionString(string tag)
-    {
-        return tag.TrimStart('v', 'V');
-    }
-
-    /// <summary>
-    /// 解析版本号
-    /// </summary>
-    private static Version ParseVersion(string versionString)
-    {
-        var cleaned = ParseVersionString(versionString);
-        return Version.TryParse(cleaned, out var version) ? version : new Version(0, 0, 0);
-    }
-}
-
-// GitHub API 响应模型
-internal sealed class GitHubRelease
-{
-    [JsonPropertyName("tag_name")]
-    public string? TagName { get; set; }
-
-    [JsonPropertyName("name")]
-    public string? Name { get; set; }
-
-    [JsonPropertyName("prerelease")]
-    public bool Prerelease { get; set; }
-
-    [JsonPropertyName("published_at")]
-    public DateTime PublishedAt { get; set; }
-
-    [JsonPropertyName("body")]
-    public string? Body { get; set; }
-
-    [JsonPropertyName("assets")]
-    public List<GitHubAsset>? Assets { get; set; }
-}
-
-internal sealed class GitHubAsset
-{
-    [JsonPropertyName("name")]
-    public string? Name { get; set; }
-
-    [JsonPropertyName("browser_download_url")]
-    public string? BrowserDownloadUrl { get; set; }
-
-    [JsonPropertyName("size")]
-    public long Size { get; set; }
-}

LanMountainDesktop.Launcher/Shell/ApplyUpdateGuiFlow.cs

@@ -0,0 +1,78 @@
+using Avalonia.Controls.ApplicationLifetimes;
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Resources;
+using LanMountainDesktop.Launcher.Views;
+
+namespace LanMountainDesktop.Launcher.Shell;
+
+internal static class ApplyUpdateGuiFlow
+{
+    public static async Task RunAsync(
+        IClassicDesktopStyleApplicationLifetime desktop,
+        CommandContext context,
+        UpdateWindow window)
+    {
+        var appRoot = Commands.ResolveAppRoot(context);
+        var deploymentLocator = new DeploymentLocator(appRoot);
+        var updateEngine = UpdateEngineFactory.Create(deploymentLocator);
+        var pluginInstaller = new PluginInstallerService();
+        var pluginUpgrades = new PluginUpgradeQueueService(pluginInstaller);
+
+        var success = true;
+        string? errorMessage = null;
+
+        try
+        {
+            await Dispatcher.UIThread.InvokeAsync(() => window.Report("verify", Strings.Update_Verifying, 10));
+            var updateResult = await updateEngine.ApplyPendingUpdateAsync().ConfigureAwait(false);
+            if (!updateResult.Success)
+            {
+                success = false;
+                errorMessage = updateResult.Message;
+            }
+
+            if (success)
+            {
+                await Dispatcher.UIThread.InvokeAsync(() => window.Report("plugins", Strings.Update_ApplyingPlugins, 60));
+                var pluginsDir = context.GetOption("plugins-dir") ?? Path.Combine(appRoot, "plugins");
+                var queueResult = pluginUpgrades.ApplyPendingUpgrades(pluginsDir);
+                if (!queueResult.Success && queueResult.Code != "noop")
+                {
+                    Logger.Error($"Plugin upgrade failed during apply-update: {queueResult.Message}");
+                }
+            }
+
+            if (success)
+            {
+                await Dispatcher.UIThread.InvokeAsync(() => window.Report("cleanup", Strings.Update_CleaningUp, 90));
+                deploymentLocator.CleanupOldDeployments(minVersionsToKeep: 3);
+            }
+        }
+        catch (Exception ex)
+        {
+            success = false;
+            errorMessage = ex.Message;
+            Logger.Error("Apply-update flow failed.", ex);
+        }
+
+        await Dispatcher.UIThread.InvokeAsync(() => window.ReportComplete(success, errorMessage));
+        await Task.Delay(success ? 1500 : 5000).ConfigureAwait(false);
+
+        await Commands.WriteResultIfNeededAsync(context.GetOption("result"), new LauncherResult
+        {
+            Success = success,
+            Stage = "apply-update",
+            Code = success ? "ok" : "failed",
+            Message = success ? "Update applied successfully." : (errorMessage ?? "Unknown error"),
+            Details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+            {
+                ["command"] = context.Command,
+                ["launchSource"] = context.LaunchSource
+            }
+        }).ConfigureAwait(false);
+
+        Environment.ExitCode = success ? 0 : 1;
+        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
+    }
+}

LanMountainDesktop.Launcher/Shell/DeferredSplashStageReporter.cs

@@ -1,7 +1,7 @@
 using Avalonia.Threading;
 using LanMountainDesktop.Launcher.Views;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Shell;
 
 internal sealed class DeferredSplashStageReporter : ISplashStageReporter
 {

LanMountainDesktop.Launcher/Shell/EntryHandlers/LaunchEntryHandlers.cs

@@ -0,0 +1,90 @@
+using Avalonia.Controls.ApplicationLifetimes;
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Views;
+
+namespace LanMountainDesktop.Launcher.Shell.EntryHandlers;
+
+internal static class LaunchEntryHandler
+{
+    public static SplashWindow CreateSplashWindow()
+    {
+        var window = new SplashWindow();
+        try
+        {
+            var appRoot = Commands.ResolveAppRoot(LauncherRuntimeContext.Current);
+            var versionInfo = new DeploymentLocator(appRoot).GetVersionInfo();
+            window.SetVersionInfo(versionInfo.Version, versionInfo.Codename);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to set splash version info: {ex.Message}");
+        }
+
+        return window;
+    }
+
+    public static Task RunAsync(
+        IClassicDesktopStyleApplicationLifetime desktop,
+        CommandContext context,
+        SplashWindow splashWindow) =>
+        LauncherCompositionRoot.RunOrchestratorWithSplashAsync(desktop, context, splashWindow);
+}
+
+internal static class ApplyUpdateEntryHandler
+{
+    public static Task RunAsync(
+        IClassicDesktopStyleApplicationLifetime desktop,
+        CommandContext context,
+        UpdateWindow window) =>
+        ApplyUpdateGuiFlow.RunAsync(desktop, context, window);
+}
+
+internal static class AirAppBrokerEntryHandler
+{
+    public static async Task RunAsync(IClassicDesktopStyleApplicationLifetime desktop, CommandContext context)
+    {
+        var appRoot = Commands.ResolveAppRoot(context);
+        var requesterPid = context.GetIntOption("requester-pid", 0);
+        var dataLocationResolver = new DataLocationResolver(appRoot);
+        Logger.Info($"Air APP broker starting. AppRoot='{appRoot}'; RequesterPid={requesterPid}.");
+
+        using var airAppIpcHost = new LauncherAirAppLifecycleIpcHost(
+            new LauncherAirAppLifecycleService(
+                new AirAppProcessStarter(
+                    new AirAppHostLocator(),
+                    () => appRoot,
+                    () => null,
+                    () => dataLocationResolver.ResolveDataRoot())));
+        airAppIpcHost.Start();
+
+        while (ShouldKeepAlive(requesterPid, airAppIpcHost.LifecycleService))
+        {
+            await Task.Delay(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
+        }
+
+        Logger.Info("Air APP broker exiting.");
+        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0), DispatcherPriority.Background);
+    }
+
+    internal static bool ShouldKeepAirAppBrokerAlive(int requesterPid, LauncherAirAppLifecycleService lifecycleService)
+    {
+        if (requesterPid <= 0)
+        {
+            return lifecycleService.HasLiveAirApps();
+        }
+
+        try
+        {
+            using var process = System.Diagnostics.Process.GetProcessById(requesterPid);
+            return !process.HasExited || lifecycleService.HasLiveAirApps();
+        }
+        catch
+        {
+            return lifecycleService.HasLiveAirApps();
+        }
+    }
+
+    private static bool ShouldKeepAlive(int requesterPid, LauncherAirAppLifecycleService lifecycleService) =>
+        ShouldKeepAirAppBrokerAlive(requesterPid, lifecycleService);
+}

LanMountainDesktop.Launcher/Shell/EntryHandlers/PreviewEntryHandler.cs

@@ -0,0 +1,136 @@
+using Avalonia.Controls;
+using Avalonia.Controls.ApplicationLifetimes;
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Resources;
+using LanMountainDesktop.Launcher.Views;
+
+namespace LanMountainDesktop.Launcher.Shell.EntryHandlers;
+
+internal static class PreviewEntryHandler
+{
+    public static bool TryHandle(CommandContext context, IClassicDesktopStyleApplicationLifetime desktop)
+    {
+        switch (context.Command.ToLowerInvariant())
+        {
+            case "preview-splash":
+                RunSplashPreview(desktop);
+                return true;
+            case "preview-error":
+                RunErrorPreview(desktop);
+                return true;
+            case "preview-multi-instance":
+                RunMultiInstancePreview(desktop);
+                return true;
+            case "preview-update":
+                RunUpdatePreview(desktop);
+                return true;
+            case "preview-oobe":
+                RunOobePreview(desktop);
+                return true;
+            case "preview-debug":
+                new DevDebugWindow().Show();
+                return true;
+            default:
+                return false;
+        }
+    }
+
+    private static void RunSplashPreview(IClassicDesktopStyleApplicationLifetime desktop)
+    {
+        var splashWindow = LaunchEntryHandler.CreateSplashWindow();
+        splashWindow.SetDebugMode(true);
+        splashWindow.Show();
+        _ = SimulateSplashPreviewAsync(desktop, splashWindow);
+    }
+
+    private static void RunErrorPreview(IClassicDesktopStyleApplicationLifetime desktop)
+    {
+        var errorWindow = new ErrorWindow();
+        errorWindow.SetErrorMessage(Strings.Preview_ErrorMessage);
+        errorWindow.Show();
+        _ = WaitForWindowCloseAsync(desktop, errorWindow);
+    }
+
+    private static void RunMultiInstancePreview(IClassicDesktopStyleApplicationLifetime desktop)
+    {
+        var promptWindow = new MultiInstancePromptWindow();
+        promptWindow.SetDetails(Environment.ProcessId, "ForegroundDesktop");
+        promptWindow.Show();
+        _ = WaitForWindowCloseAsync(desktop, promptWindow);
+    }
+
+    private static void RunUpdatePreview(IClassicDesktopStyleApplicationLifetime desktop)
+    {
+        var updateWindow = new UpdateWindow();
+        updateWindow.SetDebugMode(true);
+        updateWindow.Show();
+        _ = SimulateUpdatePreviewAsync(desktop, updateWindow);
+    }
+
+    private static void RunOobePreview(IClassicDesktopStyleApplicationLifetime desktop)
+    {
+        var oobeWindow = new OobeWindow();
+        oobeWindow.Show();
+        _ = SimulateOobePreviewAsync(desktop, oobeWindow);
+    }
+
+    private static async Task SimulateSplashPreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, SplashWindow window)
+    {
+        var stages = new[] { "initializing", "update", "plugins", "launch", "ready" };
+        var messages = new[]
+        {
+            Strings.Preview_SplashInitializing,
+            Strings.Preview_SplashCheckingUpdates,
+            Strings.Preview_SplashCheckingPlugins,
+            Strings.Preview_SplashLaunchingHost,
+            Strings.Preview_SplashReady
+        };
+        var reporter = (ISplashStageReporter)window;
+
+        for (var i = 0; i < stages.Length; i++)
+        {
+            reporter.Report(stages[i], messages[i]);
+            await Task.Delay(800).ConfigureAwait(false);
+        }
+
+        await Task.Delay(5000).ConfigureAwait(false);
+        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
+    }
+
+    private static async Task SimulateUpdatePreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, UpdateWindow window)
+    {
+        var stages = new[] { "verify", "extract", "apply", "plugins", "cleanup" };
+        for (var i = 0; i < stages.Length; i++)
+        {
+            window.Report(stages[i], string.Format(Strings.Preview_UpdateProcessing, stages[i]), (i + 1) * 20);
+            await Task.Delay(600).ConfigureAwait(false);
+        }
+
+        window.ReportComplete(true, null);
+        await Task.Delay(3000).ConfigureAwait(false);
+        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
+    }
+
+    private static async Task SimulateOobePreviewAsync(IClassicDesktopStyleApplicationLifetime desktop, OobeWindow window)
+    {
+        try
+        {
+            await window.WaitForEnterAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("OOBE preview failed.", ex);
+        }
+
+        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
+    }
+
+    private static async Task WaitForWindowCloseAsync(IClassicDesktopStyleApplicationLifetime desktop, Window window)
+    {
+        var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+        window.Closed += (_, _) => tcs.TrySetResult();
+        await tcs.Task.ConfigureAwait(false);
+        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(0));
+    }
+}

LanMountainDesktop.Launcher/Shell/LaunchUiPresenter.cs

@@ -0,0 +1,184 @@
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Views;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Shell;
+
+internal static class LaunchUiPresenter
+{
+    public static async Task HideSplashAsync(SplashWindow splashWindow)
+    {
+        await Dispatcher.UIThread.InvokeAsync(splashWindow.Hide);
+    }
+
+    public static async Task ShowSplashAsync(SplashWindow splashWindow)
+    {
+        await Dispatcher.UIThread.InvokeAsync(splashWindow.Show);
+    }
+
+    public static async Task CloseWindowsAsync(SplashWindow splashWindow, LoadingDetailsWindow? loadingDetailsWindow)
+    {
+        try
+        {
+            await Dispatcher.UIThread.InvokeAsync(() => splashWindow.DismissAsync());
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("Failed to dismiss splash window.", ex);
+        }
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            try
+            {
+                if (loadingDetailsWindow is not null && loadingDetailsWindow.IsVisible)
+                {
+                    loadingDetailsWindow.Close();
+                }
+            }
+            catch (Exception ex)
+            {
+                Logger.Error("Failed to close loading details window.", ex);
+            }
+        });
+    }
+
+    public static async Task<(ErrorWindowResult Result, string? CustomPath)> ShowHostNotFoundErrorAsync()
+    {
+        ErrorWindow? errorWindow = null;
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            try
+            {
+                errorWindow = new ErrorWindow();
+                errorWindow.ConfigureForHostNotFound();
+                errorWindow.SetErrorMessage("LanMountainDesktop host executable was not found.");
+                errorWindow.Show();
+                Logger.Warn("Host not found. Showing error window.");
+            }
+            catch (Exception ex)
+            {
+                Logger.Error("Failed to show host-not-found error window.", ex);
+            }
+        });
+
+        if (errorWindow is null)
+        {
+            return (ErrorWindowResult.Exit, null);
+        }
+
+        ErrorWindowResult result;
+        string? customPath;
+        try
+        {
+            result = await errorWindow.WaitForChoiceAsync().ConfigureAwait(false);
+            customPath = errorWindow.GetCustomHostPath();
+            Logger.Info($"Host-not-found window result='{result}'; HasCustomPath={!string.IsNullOrWhiteSpace(customPath)}.");
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("Failed while waiting for host-not-found window result.", ex);
+            result = ErrorWindowResult.Exit;
+            customPath = null;
+        }
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            try
+            {
+                if (errorWindow.IsVisible && errorWindow.IsLoaded)
+                {
+                    errorWindow.Close();
+                }
+            }
+            catch (Exception ex)
+            {
+                Logger.Error("Failed to close host-not-found error window.", ex);
+            }
+        });
+
+        return (result, customPath);
+    }
+
+    public static async Task<MigrationResult> ShowMigrationPromptAsync(LegacyVersionInfo legacyInfo)
+    {
+        MigrationPromptWindow? migrationWindow = null;
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            try
+            {
+                migrationWindow = new MigrationPromptWindow();
+                migrationWindow.SetLegacyInfo(legacyInfo);
+                migrationWindow.Show();
+            }
+            catch (Exception ex)
+            {
+                Logger.Error("Failed to show migration prompt window.", ex);
+            }
+        });
+
+        if (migrationWindow is null)
+        {
+            return MigrationResult.Skipped;
+        }
+
+        MigrationResult result;
+        try
+        {
+            result = await migrationWindow.WaitForChoiceAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("Failed while waiting for migration prompt result.", ex);
+            result = MigrationResult.Skipped;
+        }
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            try
+            {
+                if (migrationWindow.IsVisible && migrationWindow.IsLoaded)
+                {
+                    migrationWindow.Close();
+                }
+            }
+            catch (Exception ex)
+            {
+                Logger.Error("Failed to close migration prompt window.", ex);
+            }
+        });
+
+        return result;
+    }
+
+    public static string MapStartupStageToSplashStage(StartupStage stage) => stage switch
+    {
+        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",
+        StartupStage.Ready => "ready",
+        _ => "launch"
+    };
+
+    public static async Task<MultiInstancePromptResult> ShowMultiInstancePromptAsync(PublicShellStatus status)
+    {
+        return await Dispatcher.UIThread.InvokeAsync(async () =>
+        {
+            var prompt = new MultiInstancePromptWindow();
+            prompt.SetDetails(status.ProcessId, status.ShellState);
+            prompt.Show();
+            return await prompt.WaitForChoiceAsync().ConfigureAwait(true);
+        });
+    }
+}

LanMountainDesktop.Launcher/Shell/LauncherBackgroundService.cs

@@ -1,6 +1,6 @@
 using Avalonia.Media.Imaging;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Shell;
 
 /// <summary>
 /// 启动器背景图片服务

LanMountainDesktop.Launcher/Shell/LauncherCompositionRoot.cs

@@ -0,0 +1,26 @@
+using Avalonia.Controls.ApplicationLifetimes;
+using LanMountainDesktop.Launcher.Views;
+
+namespace LanMountainDesktop.Launcher.Shell;
+
+/// <summary>
+/// Launcher GUI composition root. It only wires services and dispatches to entry coordinators.
+/// </summary>
+internal static class LauncherCompositionRoot
+{
+    public static LauncherOrchestrator CreateOrchestrator(
+        CommandContext context,
+        string appRoot,
+        StartupAttemptRegistry startupAttemptRegistry,
+        LauncherCoordinatorIpcServer coordinatorServer)
+    {
+        _ = appRoot;
+        return LauncherServiceRegistration.CreateOrchestrator(context, startupAttemptRegistry, coordinatorServer);
+    }
+
+    public static Task RunOrchestratorWithSplashAsync(
+        IClassicDesktopStyleApplicationLifetime desktop,
+        CommandContext context,
+        SplashWindow splashWindow) =>
+        LauncherGuiCoordinator.RunAsync(desktop, context, splashWindow);
+}

LanMountainDesktop.Launcher/Shell/LauncherGuiCoordinator.cs

@@ -0,0 +1,533 @@
+using System.Diagnostics;
+using Avalonia.Controls.ApplicationLifetimes;
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Resources;
+using LanMountainDesktop.Launcher.Views;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Shell;
+
+internal static class LauncherGuiCoordinator
+{
+    public static async Task RunAsync(
+        IClassicDesktopStyleApplicationLifetime desktop,
+        CommandContext context,
+        SplashWindow splashWindow)
+    {
+        LauncherResult result;
+        SplashWindow? currentSplashWindow = splashWindow;
+        var appRoot = Commands.ResolveAppRoot(context);
+        var dataLocationResolver = new DataLocationResolver(appRoot);
+        var startupAttemptRegistry = new StartupAttemptRegistry();
+        var coordinatorPipeName = LauncherCoordinatorIpcServer.CreatePipeName();
+        var successPolicy = LauncherOrchestrator.ResolveSuccessPolicyKey(context);
+        if (!startupAttemptRegistry.TryReserveCoordinator(
+                context.LaunchSource,
+                successPolicy,
+                coordinatorPipeName,
+                out var reservedAttempt,
+                out var activeCoordinatorAttempt))
+        {
+            result = await AttachToExistingCoordinatorAsync(
+                context,
+                currentSplashWindow,
+                activeCoordinatorAttempt).ConfigureAwait(false);
+
+            Logger.Info($"Secondary launcher completed. Success={result.Success}; Code='{result.Code}'.");
+            await WriteLauncherResultAsync(context, result).ConfigureAwait(false);
+
+            Environment.ExitCode = result.Success ? 0 : 1;
+            await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
+            return;
+        }
+
+        using var airAppIpcHost = new LauncherAirAppLifecycleIpcHost(
+            new LauncherAirAppLifecycleService(
+                new AirAppProcessStarter(
+                    new AirAppHostLocator(),
+                    () => appRoot,
+                    () => null,
+                    () => dataLocationResolver.ResolveDataRoot())));
+        airAppIpcHost.Start();
+
+        using var coordinatorServer = new LauncherCoordinatorIpcServer(
+            coordinatorPipeName,
+            BuildCoordinatorStatusFromAttempt(reservedAttempt),
+            HandleCoordinatorRequestAsync,
+            startupAttemptRegistry.UpdateOwnedCoordinatorHeartbeat);
+        coordinatorServer.Start();
+
+        while (true)
+        {
+            try
+            {
+                Logger.Info(
+                    $"Coordinator start. Command='{context.Command}'; AppRoot='{appRoot}'; " +
+                    $"IsDebugMode={context.IsDebugMode}; LaunchSource='{context.LaunchSource}'; " +
+                    $"ResultPath='{context.GetOption("result") ?? "<none>"}'.");
+
+                var orchestrator = LauncherCompositionRoot.CreateOrchestrator(
+                    context,
+                    appRoot,
+                    startupAttemptRegistry,
+                    coordinatorServer);
+
+                result = await orchestrator.RunAsync(currentSplashWindow).ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                Logger.Error("Coordinator threw an unhandled exception.", ex);
+                result = new LauncherResult
+                {
+                    Success = false,
+                    Stage = "launch",
+                    Code = "exception",
+                    Message = $"Launcher failed: {ex.Message}",
+                    ErrorMessage = ex.ToString()
+                };
+            }
+
+            if (result.Success ||
+                result.Code == "host_not_found" ||
+                (!string.Equals(result.Stage, "launch", StringComparison.OrdinalIgnoreCase) &&
+                 !string.Equals(result.Stage, "launchHost", StringComparison.OrdinalIgnoreCase)))
+            {
+                break;
+            }
+
+            var failureAction = await ShowFailureWindowAsync(result).ConfigureAwait(false);
+            if (failureAction == ErrorWindowResult.Exit)
+            {
+                break;
+            }
+
+            if (failureAction == ErrorWindowResult.ActivateExisting &&
+                await TryActivateExistingInstanceAsync().ConfigureAwait(false))
+            {
+                result = new LauncherResult
+                {
+                    Success = true,
+                    Stage = "launch",
+                    Code = "activation_requested",
+                    Message = "Launcher activated the existing desktop instance.",
+                    Details = result.Details
+                };
+                break;
+            }
+
+            currentSplashWindow = CreateSplashWindow();
+            currentSplashWindow.Show();
+        }
+
+        Logger.Info($"Coordinator completed. Success={result.Success}; Stage='{result.Stage}'; Code='{result.Code}'.");
+        await WriteLauncherResultAsync(context, result).ConfigureAwait(false);
+
+        Environment.ExitCode = result.Success ? 0 : 1;
+        if (result.Success)
+        {
+            var hostPid = ResolveManagedHostPid(result, startupAttemptRegistry.GetOwnedAttempt()?.HostPid ?? 0);
+            await WaitForManagedProcessesToExitAsync(hostPid, airAppIpcHost.LifecycleService).ConfigureAwait(false);
+        }
+
+        await Dispatcher.UIThread.InvokeAsync(() => desktop.Shutdown(Environment.ExitCode), DispatcherPriority.Background);
+    }
+
+    private static SplashWindow CreateSplashWindow()
+    {
+        var window = new SplashWindow();
+        TrySetSplashVersionInfo(window, LauncherRuntimeContext.Current);
+        return window;
+    }
+
+    private static void TrySetSplashVersionInfo(SplashWindow window, CommandContext context)
+    {
+        try
+        {
+            var appRoot = Commands.ResolveAppRoot(context);
+            var versionInfo = new DeploymentLocator(appRoot).GetVersionInfo();
+            window.SetVersionInfo(versionInfo.Version, versionInfo.Codename);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to set splash version info before coordinator start: {ex.Message}");
+        }
+    }
+
+    private static int ResolveManagedHostPid(LauncherResult result, int fallbackHostPid)
+    {
+        if (result.Details.TryGetValue("hostPid", out var hostPidText) &&
+            int.TryParse(hostPidText, out var hostPid))
+        {
+            return hostPid;
+        }
+
+        if (result.Details.TryGetValue("existingHostPid", out var existingHostPidText) &&
+            int.TryParse(existingHostPidText, out var existingHostPid))
+        {
+            return existingHostPid;
+        }
+
+        return fallbackHostPid;
+    }
+
+    private static async Task WaitForManagedProcessesToExitAsync(
+        int hostPid,
+        LauncherAirAppLifecycleService airAppLifecycleService)
+    {
+        Logger.Info($"Launcher entering managed background lifetime. HostPid={hostPid}.");
+        while (TryGetLiveProcess(hostPid) || airAppLifecycleService.HasLiveAirApps())
+        {
+            await Task.Delay(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
+        }
+
+        Logger.Info("Launcher managed background lifetime completed; no host or Air APP process remains.");
+    }
+
+    private static async Task<LauncherResult> AttachToExistingCoordinatorAsync(
+        CommandContext context,
+        SplashWindow? splashWindow,
+        StartupAttemptRecord? activeCoordinatorAttempt)
+    {
+        var reporter = splashWindow as ISplashStageReporter;
+        reporter?.Report("activation", Strings.Preview_ActivationConnecting);
+
+        if (activeCoordinatorAttempt is not null &&
+            !string.IsNullOrWhiteSpace(activeCoordinatorAttempt.CoordinatorPipeName))
+        {
+            var command = string.Equals(context.LaunchSource, "restart", StringComparison.OrdinalIgnoreCase)
+                ? LauncherCoordinatorCommands.Attach
+                : LauncherCoordinatorCommands.ActivateDesktop;
+            var request = new LauncherCoordinatorRequest
+            {
+                Command = command,
+                LaunchSource = context.LaunchSource,
+                SuccessPolicy = LauncherOrchestrator.ResolveSuccessPolicyKey(context)
+            };
+
+            var response = await new LauncherCoordinatorIpcClient()
+                .SendAsync(activeCoordinatorAttempt.CoordinatorPipeName, request, TimeSpan.FromSeconds(2))
+                .ConfigureAwait(false);
+
+            if (response is not null)
+            {
+                reporter?.Report("activation", response.Message);
+                await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
+                var success = response.Accepted ||
+                              IsRecoverableActivationFailure(response.ActivationResult, response.Status);
+                return new LauncherResult
+                {
+                    Success = success,
+                    Stage = "launch",
+                    Code = success && !response.Accepted ? "attached_to_launcher_coordinator" : response.Code,
+                    Message = success && !response.Accepted
+                        ? "Attached to the active Launcher coordinator; desktop startup is still in progress."
+                        : response.Message,
+                    Details = BuildCoordinatorResultDetails(response.Status, response.ActivationResult)
+                };
+            }
+        }
+
+        var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
+        if (activation is not null)
+        {
+            reporter?.Report("activation", activation.Message);
+            await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
+            var success = activation.Accepted || IsRecoverableActivationFailure(activation, null);
+            return new LauncherResult
+            {
+                Success = success,
+                Stage = "launch",
+                Code = activation.Accepted
+                    ? "existing_host_activated"
+                    : success
+                        ? "existing_host_startup_pending"
+                        : "existing_host_activation_failed",
+                Message = success && !activation.Accepted
+                    ? "Existing desktop process is still starting; Launcher attached without starting another process."
+                    : activation.Message,
+                Details = BuildCoordinatorResultDetails(null, activation)
+            };
+        }
+
+        await DismissSplashIfNeededAsync(splashWindow).ConfigureAwait(false);
+        return new LauncherResult
+        {
+            Success = false,
+            Stage = "launch",
+            Code = "launcher_coordinator_unavailable",
+            Message = "Another Launcher is coordinating startup, but it did not respond in time.",
+            Details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+            {
+                ["activeCoordinatorPid"] = activeCoordinatorAttempt?.CoordinatorPid.ToString() ?? string.Empty,
+                ["activeCoordinatorPipeName"] = activeCoordinatorAttempt?.CoordinatorPipeName ?? string.Empty,
+                ["activeAttemptId"] = activeCoordinatorAttempt?.AttemptId ?? string.Empty,
+                ["activeHostPid"] = activeCoordinatorAttempt?.HostPid.ToString() ?? string.Empty
+            }
+        };
+    }
+
+    private static async Task<LauncherCoordinatorResponse> HandleCoordinatorRequestAsync(
+        LauncherCoordinatorRequest request,
+        LauncherCoordinatorStatus status)
+    {
+        if (string.Equals(request.Command, LauncherCoordinatorCommands.ActivateDesktop, StringComparison.OrdinalIgnoreCase))
+        {
+            var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(2)).ConfigureAwait(false);
+            if (activation is not null)
+            {
+                if (!activation.Accepted && IsRecoverableActivationFailure(activation, status))
+                {
+                    return new LauncherCoordinatorResponse
+                    {
+                        Accepted = true,
+                        Code = "attached_to_launcher_coordinator",
+                        Message = "Attached to the active Launcher coordinator; desktop startup is still in progress.",
+                        Status = status,
+                        ActivationResult = activation
+                    };
+                }
+
+                return new LauncherCoordinatorResponse
+                {
+                    Accepted = activation.Accepted,
+                    Code = activation.Accepted ? "existing_host_activated" : "existing_host_activation_failed",
+                    Message = activation.Message,
+                    Status = status,
+                    ActivationResult = activation
+                };
+            }
+
+            return new LauncherCoordinatorResponse
+            {
+                Accepted = true,
+                Code = "attached_to_launcher_coordinator",
+                Message = "Attached to the active Launcher coordinator; desktop startup is still in progress.",
+                Status = status
+            };
+        }
+
+        return new LauncherCoordinatorResponse
+        {
+            Accepted = true,
+            Code = "attached_to_launcher_coordinator",
+            Message = "Attached to the active Launcher coordinator.",
+            Status = status
+        };
+    }
+
+    private static LauncherCoordinatorStatus BuildCoordinatorStatusFromAttempt(StartupAttemptRecord attempt)
+    {
+        return new LauncherCoordinatorStatus
+        {
+            AttemptId = attempt.AttemptId,
+            CoordinatorPid = Environment.ProcessId,
+            HostPid = attempt.HostPid,
+            HostProcessAlive = TryGetLiveProcess(attempt.HostPid),
+            LaunchSource = attempt.LaunchSource,
+            SuccessPolicy = attempt.SuccessPolicy,
+            LastObservedStage = attempt.LastObservedStage,
+            LastObservedMessage = attempt.LastObservedMessage,
+            PublicIpcConnected = attempt.PublicIpcConnected || attempt.IpcConnected,
+            State = attempt.State.ToString(),
+            SoftTimeoutShown = attempt.State is StartupAttemptState.SoftTimeout or StartupAttemptState.DetachedWaiting,
+            Completed = attempt.State is StartupAttemptState.Succeeded or StartupAttemptState.Failed,
+            Succeeded = attempt.State == StartupAttemptState.Succeeded,
+            UpdatedAtUtc = attempt.UpdatedAtUtc
+        };
+    }
+
+    private static bool IsRecoverableActivationFailure(
+        PublicShellActivationResult? activation,
+        LauncherCoordinatorStatus? status)
+    {
+        if (activation is { Accepted: true })
+        {
+            return false;
+        }
+
+        if (status is { Completed: false, HostProcessAlive: true })
+        {
+            return true;
+        }
+
+        var shellStatus = activation?.Status;
+        if (shellStatus is null || !shellStatus.PublicIpcReady)
+        {
+            return false;
+        }
+
+        return !shellStatus.MainWindowOpened ||
+               !shellStatus.DesktopVisible ||
+               string.Equals(activation?.Code, "shell_not_ready", StringComparison.OrdinalIgnoreCase) ||
+               string.Equals(activation?.Code, "startup_pending", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static Dictionary<string, string> BuildCoordinatorResultDetails(
+        LauncherCoordinatorStatus? status,
+        PublicShellActivationResult? activation)
+    {
+        return new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["coordinatorPid"] = status?.CoordinatorPid.ToString() ?? string.Empty,
+            ["coordinatorAttemptId"] = status?.AttemptId ?? string.Empty,
+            ["hostPid"] = status?.HostPid.ToString() ?? activation?.Status.ProcessId.ToString() ?? string.Empty,
+            ["hostProcessAlive"] = status?.HostProcessAlive.ToString() ?? string.Empty,
+            ["publicIpcConnected"] = (status?.PublicIpcConnected ?? activation is not null).ToString(),
+            ["startupStage"] = status?.LastObservedStage.ToString() ?? string.Empty,
+            ["startupState"] = status?.State ?? string.Empty,
+            ["activationAccepted"] = activation?.Accepted.ToString() ?? string.Empty,
+            ["shellState"] = activation?.Status.ShellState ?? status?.ShellStatus?.ShellState ?? string.Empty,
+            ["trayState"] = activation?.Status.Tray.State ?? status?.ShellStatus?.Tray.State ?? string.Empty,
+            ["taskbarUsable"] = activation?.Status.Taskbar.IsUsable.ToString() ?? status?.ShellStatus?.Taskbar.IsUsable.ToString() ?? string.Empty
+        };
+    }
+
+    private static async Task DismissSplashIfNeededAsync(SplashWindow? splashWindow)
+    {
+        if (splashWindow is null)
+        {
+            return;
+        }
+
+        try
+        {
+            await splashWindow.DismissAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to dismiss splash after coordinator attach: {ex.Message}");
+        }
+    }
+
+    private static async Task WriteLauncherResultAsync(CommandContext context, LauncherResult result)
+    {
+        var resultPath = context.GetOption("result");
+        if (string.IsNullOrWhiteSpace(resultPath))
+        {
+            return;
+        }
+
+        try
+        {
+            await Commands.WriteResultIfNeededAsync(resultPath, result).ConfigureAwait(false);
+            Logger.Info($"Launcher result written to '{Path.GetFullPath(resultPath)}'.");
+        }
+        catch (Exception ex)
+        {
+            Logger.Error($"Failed to write launcher result to '{resultPath}'.", ex);
+        }
+    }
+
+    private static async Task<ErrorWindowResult> ShowFailureWindowAsync(LauncherResult result)
+    {
+        ErrorWindow? errorWindow = null;
+        var hostProcessAlive = result.Details.TryGetValue("hostProcessAlive", out var hostProcessAliveText) &&
+                               bool.TryParse(hostProcessAliveText, out var hostProcessAliveValue) &&
+                               hostProcessAliveValue;
+        var hostPid = result.Details.TryGetValue("hostPid", out var hostPidText) &&
+                      int.TryParse(hostPidText, out var parsedPid)
+            ? parsedPid
+            : (int?)null;
+
+        await Dispatcher.UIThread.InvokeAsync(() =>
+        {
+            try
+            {
+                errorWindow = new ErrorWindow();
+                if (hostProcessAlive)
+                {
+                    errorWindow.ConfigureForRunningHostFailure(hostPid);
+                }
+                else
+                {
+                    errorWindow.ConfigureForGenericFailure(allowRetry: true);
+                }
+
+                errorWindow.SetErrorMessage(
+                    $"Failed to start LanMountainDesktop.\n\nStage: {result.Stage}\nCode: {result.Code}\n\n{result.Message}");
+                errorWindow.Show();
+            }
+            catch (Exception ex)
+            {
+                Logger.Error("Failed to show launcher failure window.", ex);
+            }
+        });
+
+        if (errorWindow is null)
+        {
+            return ErrorWindowResult.Exit;
+        }
+
+        try
+        {
+            return await errorWindow.WaitForChoiceAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("Failure window closed unexpectedly.", ex);
+            return ErrorWindowResult.Exit;
+        }
+    }
+
+    private static async Task<bool> TryActivateExistingInstanceAsync()
+    {
+        var activation = await TryActivateExistingInstanceWithStatusAsync(TimeSpan.FromSeconds(5)).ConfigureAwait(false);
+        return activation?.Accepted == true;
+    }
+
+    private static async Task<PublicShellActivationResult?> TryActivateExistingInstanceWithStatusAsync(TimeSpan timeout)
+    {
+        try
+        {
+            using var ipcClient = new LanMountainDesktopIpcClient();
+            var connectTask = ipcClient.ConnectAsync();
+            var completedTask = await Task.WhenAny(connectTask, Task.Delay(timeout)).ConfigureAwait(false);
+            if (completedTask != connectTask)
+            {
+                return null;
+            }
+
+            await connectTask.ConfigureAwait(false);
+            if (!ipcClient.IsConnected)
+            {
+                return null;
+            }
+
+            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
+            var activationTask = shellProxy.ActivateMainWindowWithStatusAsync();
+            completedTask = await Task.WhenAny(activationTask, Task.Delay(timeout)).ConfigureAwait(false);
+            if (completedTask != activationTask)
+            {
+                return null;
+            }
+
+            return await activationTask.ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to activate the existing desktop instance: {ex.Message}");
+            return null;
+        }
+    }
+
+    private static bool TryGetLiveProcess(int processId)
+    {
+        if (processId <= 0)
+        {
+            return false;
+        }
+
+        try
+        {
+            using var process = Process.GetProcessById(processId);
+            return !process.HasExited;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+}

LanMountainDesktop.Launcher/Shell/LauncherOrchestrator.cs

@@ -0,0 +1,283 @@
+using Avalonia.Threading;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Startup;
+using LanMountainDesktop.Launcher.Views;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Shell;
+
+internal sealed class LauncherOrchestrator
+{
+    private readonly CommandContext _context;
+    private readonly DeploymentLocator _deploymentLocator;
+    private readonly OobeStateService _oobeStateService;
+    private readonly IUpdateEngine _updateEngine;
+    private readonly StartupAttemptRegistry _startupAttemptRegistry;
+    private readonly LauncherCoordinatorIpcServer? _coordinatorIpcServer;
+    private readonly DataLocationResolver _dataLocationResolver;
+    private readonly IReadOnlyList<IOobeStep> _oobeSteps;
+    private readonly LaunchPipeline _pipeline;
+
+    public LauncherOrchestrator(
+        CommandContext context,
+        DeploymentLocator deploymentLocator,
+        OobeStateService oobeStateService,
+        IUpdateEngine updateEngine,
+        StartupAttemptRegistry startupAttemptRegistry,
+        LauncherCoordinatorIpcServer? coordinatorIpcServer = null,
+        LaunchPipeline? pipeline = null)
+    {
+        _context = context;
+        _deploymentLocator = deploymentLocator;
+        _oobeStateService = oobeStateService;
+        _updateEngine = updateEngine;
+        _startupAttemptRegistry = startupAttemptRegistry;
+        _coordinatorIpcServer = coordinatorIpcServer;
+        _dataLocationResolver = new DataLocationResolver(deploymentLocator.GetAppRoot());
+        _oobeSteps =
+        [
+            new WelcomeOobeStep(_oobeStateService, _context),
+            new DataLocationOobeStep(_dataLocationResolver)
+        ];
+        _pipeline = pipeline ?? new LaunchPipeline(
+        [
+            new CleanupDeploymentsPhase(),
+            new ExistingHostProbePhase(),
+            new ApplyPendingUpdatePhase(),
+            new OobeGatePhase(),
+            new LaunchHostPhase(),
+            new MonitorStartupPhase()
+        ]);
+    }
+
+    public static string ResolveSuccessPolicyKey(CommandContext context) =>
+        new StartupSuccessTracker(context).PolicyKey;
+
+    public async Task<LauncherResult> RunAsync(SplashWindow? existingSplashWindow = null)
+    {
+        try
+        {
+            var oobeDecision = _oobeStateService.Evaluate(_context);
+            if (oobeDecision.ShouldShowOobe)
+            {
+                var legacyInfo = LegacyVersionDetector.DetectLegacyInstallation();
+                if (legacyInfo is not null)
+                {
+                    var migrationResult = await LaunchUiPresenter.ShowMigrationPromptAsync(legacyInfo).ConfigureAwait(false);
+                    Logger.Info($"Migration prompt completed. Result='{migrationResult}'.");
+                }
+            }
+
+            var splashWindow = existingSplashWindow ?? await Dispatcher.UIThread.InvokeAsync(() =>
+            {
+                var window = new SplashWindow();
+                window.Show();
+                return window;
+            });
+            var versionInfo = _deploymentLocator.GetVersionInfo();
+            splashWindow.SetVersionInfo(versionInfo.Version, versionInfo.Codename);
+            var reporter = (ISplashStageReporter)splashWindow;
+
+            LoadingDetailsWindow? loadingDetailsWindow = null;
+            if (_context.IsDebugMode || _context.GetOption("show-loading-details") == "true")
+            {
+                await Dispatcher.UIThread.InvokeAsync(() =>
+                {
+                    loadingDetailsWindow = new LoadingDetailsWindow();
+                    loadingDetailsWindow.Show();
+                });
+            }
+
+            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 activationFailureReason = string.Empty;
+            var ipcConnected = false;
+            var softTimeoutShown = false;
+            var attachedToExistingAttempt = false;
+            var windowsClosingByOrchestrator = false;
+            StartupAttemptRecord? trackedAttempt = null;
+            PublicShellStatus? shellStatus = null;
+            var loadingState = new LoadingStateMessage();
+
+            void PublishCoordinatorStatus(bool? hostProcessAliveOverride = null, bool completed = false, bool succeeded = false)
+            {
+                if (_coordinatorIpcServer is null)
+                {
+                    return;
+                }
+
+                trackedAttempt = _startupAttemptRegistry.GetOwnedAttempt() ?? trackedAttempt;
+                var hostPid = trackedAttempt?.HostPid ?? 0;
+                var hostProcessAlive = hostProcessAliveOverride ??
+                                       (hostPid > 0 && LaunchResultBuilder.TryGetLiveProcess(hostPid, out _));
+                var status = new LauncherCoordinatorStatus
+                {
+                    AttemptId = trackedAttempt?.AttemptId ?? string.Empty,
+                    CoordinatorPid = Environment.ProcessId,
+                    HostPid = hostPid,
+                    HostProcessAlive = hostProcessAlive,
+                    LaunchSource = trackedAttempt?.LaunchSource ?? _context.LaunchSource,
+                    SuccessPolicy = trackedAttempt?.SuccessPolicy ?? startupSuccessTracker.PolicyKey,
+                    LastObservedStage = lastStage,
+                    LastObservedMessage = lastStageMessage,
+                    PublicIpcConnected = ipcConnected,
+                    State = trackedAttempt?.State.ToString() ?? StartupAttemptState.Pending.ToString(),
+                    SoftTimeoutShown = softTimeoutShown,
+                    Completed = completed,
+                    Succeeded = succeeded,
+                    ShellStatus = shellStatus,
+                    UpdatedAtUtc = DateTimeOffset.UtcNow
+                };
+
+                _coordinatorIpcServer.UpdateStatus(status);
+                _startupAttemptRegistry.UpdateOwnedCoordinatorHeartbeat(status);
+            }
+
+            trackedAttempt = _startupAttemptRegistry.GetOwnedAttempt();
+            PublishCoordinatorStatus();
+
+            EventHandler? splashClosedHandler = null;
+            splashClosedHandler = (_, _) =>
+            {
+                if (windowsClosingByOrchestrator)
+                {
+                    return;
+                }
+
+                _startupAttemptRegistry.MarkOwnedDetachedWaiting();
+                Logger.Warn("Splash window was closed manually. Launcher will continue monitoring the current startup attempt.");
+            };
+            splashWindow.Closed += splashClosedHandler;
+
+            using var ipcClient = new LanMountainDesktopIpcClient();
+            ipcClient.RegisterNotifyHandler<StartupProgressMessage>(IpcRoutedNotifyIds.LauncherStartupProgress, message =>
+            {
+                Dispatcher.UIThread.Post(() =>
+                {
+                    try
+                    {
+                        ipcConnected = true;
+                        lastStage = message.Stage;
+                        lastStageMessage = message.Message ?? message.Stage.ToString();
+                        Logger.Info($"IPC stage received. Stage='{message.Stage}'; Message='{message.Message ?? string.Empty}'.");
+
+                        loadingState = loadingState with
+                        {
+                            Stage = message.Stage,
+                            OverallProgressPercent = message.ProgressPercent,
+                            Message = message.Message,
+                            Timestamp = DateTimeOffset.UtcNow
+                        };
+
+                        reporter.Report(LaunchUiPresenter.MapStartupStageToSplashStage(message.Stage), message.Message ?? message.Stage.ToString());
+                        loadingDetailsWindow?.UpdateLoadingState(loadingState);
+                        _startupAttemptRegistry.UpdateOwnedStage(message.Stage, message.Message, ipcConnected: true);
+                        PublishCoordinatorStatus();
+
+                        if (startupSuccessTracker.TryResolve(message.Stage, out var successState))
+                        {
+                            successTcs.TrySetResult(successState);
+                        }
+
+                        if (message.Stage == StartupStage.ActivationFailed)
+                        {
+                            activationFailureReason = message.Message ?? "activation_failed";
+                            activationFailedTcs.TrySetResult(message.Message ?? "activation_failed");
+                        }
+                    }
+                    catch (Exception ex)
+                    {
+                        Logger.Error("IPC progress callback failed.", ex);
+                    }
+                });
+            });
+            ipcClient.RegisterNotifyHandler<LoadingStateMessage>(IpcRoutedNotifyIds.LauncherLoadingState, message =>
+            {
+                Dispatcher.UIThread.Post(() =>
+                {
+                    try
+                    {
+                        loadingState = message;
+                        loadingDetailsWindow?.UpdateLoadingState(loadingState);
+                    }
+                    catch (Exception ex)
+                    {
+                        Logger.Error("IPC loading-state callback failed.", ex);
+                    }
+                });
+            });
+
+            var launchContext = new LaunchContext
+            {
+                CommandContext = _context,
+                DeploymentLocator = _deploymentLocator,
+                OobeStateService = _oobeStateService,
+                UpdateEngine = _updateEngine,
+                StartupAttemptRegistry = _startupAttemptRegistry,
+                CoordinatorIpcServer = _coordinatorIpcServer,
+                DataLocationResolver = _dataLocationResolver,
+                OobeSteps = _oobeSteps,
+                SplashWindow = splashWindow,
+                LoadingDetailsWindow = loadingDetailsWindow,
+                Reporter = reporter,
+                IpcClient = ipcClient,
+                SuccessTracker = startupSuccessTracker,
+                SuccessTcs = successTcs,
+                ActivationFailedTcs = activationFailedTcs,
+                LoadingState = loadingState,
+                PublishCoordinatorStatus = PublishCoordinatorStatus,
+                SplashClosedHandler = splashClosedHandler
+            };
+
+            try
+            {
+                var result = await _pipeline.ExecuteAsync(launchContext).ConfigureAwait(false);
+                windowsClosingByOrchestrator = launchContext.WindowsClosingByOrchestrator;
+                return result;
+            }
+            finally
+            {
+                if (splashClosedHandler is not null)
+                {
+                    splashWindow.Closed -= splashClosedHandler;
+                }
+
+                if (!windowsClosingByOrchestrator && !launchContext.WindowsClosingByOrchestrator)
+                {
+                    await Dispatcher.UIThread.InvokeAsync(() =>
+                    {
+                        try
+                        {
+                            if (splashWindow.IsVisible && splashWindow.IsLoaded)
+                            {
+                                splashWindow.Close();
+                                Logger.Info("Splash window closed in orchestrator cleanup.");
+                            }
+                        }
+                        catch (Exception ex)
+                        {
+                            Logger.Error("Failed to close splash window during orchestrator cleanup.", ex);
+                        }
+                    });
+                }
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("Launcher orchestrator failed.", ex);
+            var oobeDecision = _oobeStateService.Evaluate(_context);
+            return LaunchResultBuilder.Build(
+                false,
+                "launch",
+                "exception",
+                ex.Message,
+                LaunchResultBuilder.BuildLauncherContextDetails(_context, oobeDecision, _deploymentLocator.GetAppRoot()),
+                ex.ToString());
+        }
+    }
+}

LanMountainDesktop.Launcher/Shell/LauncherServiceRegistration.cs

@@ -0,0 +1,55 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace LanMountainDesktop.Launcher.Shell;
+
+internal static class LauncherServiceRegistration
+{
+    private static ServiceProvider? _provider;
+
+    public static IServiceProvider Provider =>
+        _provider ?? throw new InvalidOperationException("Launcher services are not initialized.");
+
+    public static void Initialize(CommandContext context)
+    {
+        if (_provider is not null)
+        {
+            return;
+        }
+
+        var appRoot = Commands.ResolveAppRoot(context);
+        var services = new ServiceCollection();
+        services.AddSingleton(context);
+        services.AddSingleton(new DeploymentLocator(appRoot));
+        services.AddSingleton(sp => new OobeStateService(appRoot));
+        services.AddSingleton(sp => new DataLocationResolver(appRoot));
+        services.AddSingleton(sp => UpdateEngineFactory.Create(sp.GetRequiredService<DeploymentLocator>()));
+        services.AddSingleton<HostLaunchService>();
+        services.AddSingleton<StartupAttemptRegistry>();
+        services.AddSingleton<ILaunchPhase, CleanupDeploymentsPhase>();
+        services.AddSingleton<ILaunchPhase, ExistingHostProbePhase>();
+        services.AddSingleton<ILaunchPhase, ApplyPendingUpdatePhase>();
+        services.AddSingleton<ILaunchPhase, OobeGatePhase>();
+        services.AddSingleton<ILaunchPhase, LaunchHostPhase>();
+        services.AddSingleton<ILaunchPhase, MonitorStartupPhase>();
+        services.AddSingleton(sp => new LaunchPipeline(sp.GetServices<ILaunchPhase>()));
+
+        _provider = services.BuildServiceProvider();
+    }
+
+    public static LauncherOrchestrator CreateOrchestrator(
+        CommandContext context,
+        StartupAttemptRegistry startupAttemptRegistry,
+        LauncherCoordinatorIpcServer coordinatorServer)
+    {
+        Initialize(context);
+        var services = Provider;
+        return new LauncherOrchestrator(
+            context,
+            services.GetRequiredService<DeploymentLocator>(),
+            services.GetRequiredService<OobeStateService>(),
+            services.GetRequiredService<IUpdateEngine>(),
+            startupAttemptRegistry,
+            coordinatorServer,
+            services.GetRequiredService<LaunchPipeline>());
+    }
+}

LanMountainDesktop.Launcher/Shell/ThemeService.cs

@@ -2,7 +2,7 @@ using Avalonia;
 using Avalonia.Styling;
 using FluentAvalonia.Styling;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Shell;
 
 /// <summary>
 /// 主题服务，管理启动器的主题设置

LanMountainDesktop.Launcher/Startup/ExistingHostProbe.cs

@@ -0,0 +1,163 @@
+using LanMountainDesktop.Launcher.Shell;
+using LanMountainDesktop.Launcher.Views;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal static class ExistingHostProbe
+{
+    public static MultiInstanceLaunchBehavior LoadMultiInstanceLaunchBehavior(DataLocationResolver dataLocationResolver)
+    {
+        try
+        {
+            var settingsPath = HostAppSettingsOobeMerger.GetSettingsFilePath(dataLocationResolver.ResolveDataRoot());
+            return HostAppSettingsOobeMerger.LoadMultiInstanceLaunchBehavior(settingsPath);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to load multi-instance launch behavior. Falling back to default. {ex.Message}");
+            return MultiInstanceLaunchBehavior.NotifyAndOpenDesktop;
+        }
+    }
+
+    public static async Task<PublicShellStatus?> TryGetExistingHostStatusAsync(
+        LanMountainDesktopIpcClient ipcClient,
+        TimeSpan timeout)
+    {
+        try
+        {
+            var connected = ipcClient.IsConnected ||
+                            await PublicIpcConnection.TryConnectAsync(ipcClient, timeout).ConfigureAwait(false);
+            if (!connected)
+            {
+                return null;
+            }
+
+            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
+            return await shellProxy.GetShellStatusAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Info($"Existing host status probe did not complete: {ex.Message}");
+            return null;
+        }
+    }
+
+    public static async Task<ExistingHostBehaviorResult> ApplyExistingHostBehaviorAsync(
+        LanMountainDesktopIpcClient ipcClient,
+        MultiInstanceLaunchBehavior behavior,
+        PublicShellStatus status)
+    {
+        try
+        {
+            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
+            return behavior switch
+            {
+                MultiInstanceLaunchBehavior.OpenDesktopSilently => await ActivateExistingHostForBehaviorAsync(
+                    shellProxy,
+                    showLauncherNotice: false,
+                    successCode: "existing_host_activated",
+                    successMessage: "Launcher activated the existing desktop instance.",
+                    failureCode: "existing_host_activation_failed").ConfigureAwait(false),
+
+                MultiInstanceLaunchBehavior.NotifyAndOpenDesktop => await ActivateExistingHostForBehaviorAsync(
+                    shellProxy,
+                    showLauncherNotice: true,
+                    successCode: "existing_host_activated_with_notice",
+                    successMessage: "Launcher activated the existing desktop instance and showed the repeated-launch notice.",
+                    failureCode: "existing_host_activation_failed").ConfigureAwait(false),
+
+                MultiInstanceLaunchBehavior.PromptOnly => await ShowPromptOnlyExistingHostAsync(
+                    shellProxy,
+                    status).ConfigureAwait(false),
+
+                MultiInstanceLaunchBehavior.RestartApp => await RestartExistingHostAsync(shellProxy).ConfigureAwait(false),
+
+                _ => await ActivateExistingHostForBehaviorAsync(
+                    shellProxy,
+                    showLauncherNotice: true,
+                    successCode: "existing_host_activated_with_notice",
+                    successMessage: "Launcher activated the existing desktop instance and showed the repeated-launch notice.",
+                    failureCode: "existing_host_activation_failed").ConfigureAwait(false)
+            };
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to apply multi-instance behavior '{behavior}': {ex.Message}");
+            return new ExistingHostBehaviorResult(
+                false,
+                "multi_instance_behavior_failed",
+                $"Failed to apply multi-instance behavior '{behavior}': {ex.Message}",
+                null);
+        }
+    }
+
+    private static async Task<ExistingHostBehaviorResult> ActivateExistingHostForBehaviorAsync(
+        IPublicShellControlService shellProxy,
+        bool showLauncherNotice,
+        string successCode,
+        string successMessage,
+        string failureCode)
+    {
+        var activation = await shellProxy.ActivateMainWindowWithStatusAsync().ConfigureAwait(false);
+        var success = activation.Accepted || HostActivationPolicy.IsRecoverableActivationFailure(activation);
+        if (showLauncherNotice && success)
+        {
+            var promptResult = await LaunchUiPresenter.ShowMultiInstancePromptAsync(activation.Status).ConfigureAwait(false);
+            if (promptResult == MultiInstancePromptResult.OpenDesktop)
+            {
+                activation = await shellProxy.ActivateMainWindowWithStatusAsync().ConfigureAwait(false);
+            }
+        }
+
+        return new ExistingHostBehaviorResult(
+            success,
+            activation.Accepted ? successCode : success ? "existing_host_startup_pending" : failureCode,
+            activation.Accepted ? successMessage : activation.Message,
+            activation);
+    }
+
+    private static async Task<ExistingHostBehaviorResult> RestartExistingHostAsync(
+        IPublicShellControlService shellProxy)
+    {
+        var accepted = await shellProxy.RestartAsync().ConfigureAwait(false);
+        return new ExistingHostBehaviorResult(
+            accepted,
+            accepted ? "existing_host_restart_requested" : "existing_host_restart_failed",
+            accepted
+                ? "Launcher requested the existing desktop instance to restart."
+                : "Launcher could not request restart from the existing desktop instance.",
+            null);
+    }
+
+    private static async Task<ExistingHostBehaviorResult> ShowPromptOnlyExistingHostAsync(
+        IPublicShellControlService shellProxy,
+        PublicShellStatus status)
+    {
+        var promptResult = await LaunchUiPresenter.ShowMultiInstancePromptAsync(status).ConfigureAwait(false);
+
+        if (promptResult == MultiInstancePromptResult.OpenDesktop)
+        {
+            return await ActivateExistingHostForBehaviorAsync(
+                shellProxy,
+                showLauncherNotice: false,
+                successCode: "existing_host_activated_from_prompt",
+                successMessage: "Launcher activated the existing desktop instance from the prompt.",
+                failureCode: "existing_host_activation_failed").ConfigureAwait(false);
+        }
+
+        return new ExistingHostBehaviorResult(
+            true,
+            "existing_host_prompt_only",
+            "Launcher showed the repeated-launch prompt and did not open the desktop automatically.",
+            null);
+    }
+}
+
+internal sealed record ExistingHostBehaviorResult(
+    bool Success,
+    string Code,
+    string Message,
+    PublicShellActivationResult? ActivationResult);

LanMountainDesktop.Launcher/Startup/HostActivationPolicy.cs

@@ -0,0 +1,50 @@
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal static class HostActivationPolicy
+{
+    internal static bool ShouldProbeExistingHostBeforeLaunch(CommandContext context)
+    {
+        if (!string.Equals(context.Command, "launch", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (context.IsPreviewCommand || context.IsMaintenanceCommand)
+        {
+            return false;
+        }
+
+        return !string.Equals(context.LaunchSource, "restart", StringComparison.OrdinalIgnoreCase);
+    }
+
+    internal static bool IsExistingHostReadyForLauncherDecision(PublicShellStatus? status) =>
+        status is { PublicIpcReady: true, ProcessId: > 0 };
+
+    internal static bool IsRecoverableActivationFailure(PublicShellActivationResult activation)
+    {
+        if (activation.Accepted)
+        {
+            return false;
+        }
+
+        if (string.Equals(activation.Code, "shutdown_in_progress", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        return activation.Status.PublicIpcReady &&
+               (!activation.Status.MainWindowOpened ||
+                !activation.Status.DesktopVisible ||
+                string.Equals(activation.Code, "shell_not_ready", StringComparison.OrdinalIgnoreCase) ||
+                string.Equals(activation.Code, "startup_pending", StringComparison.OrdinalIgnoreCase));
+    }
+
+    internal static bool IsSuccessfulActivationExitCode(int exitCode) =>
+        exitCode == HostExitCodes.SecondaryActivationSucceeded;
+
+    internal static bool IsFailedActivationExitCode(int exitCode) =>
+        exitCode is HostExitCodes.SecondaryActivationFailed or HostExitCodes.RestartLockNotAcquired;
+}

LanMountainDesktop.Launcher/Startup/HostLaunchModels.cs

@@ -0,0 +1,77 @@
+using System.Diagnostics;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal enum HostStartMode
+{
+    ShellExecute,
+    Direct
+}
+
+internal sealed record HostStartAttempt(
+    HostStartMode StartMode,
+    bool ProcessCreated,
+    Process? Process,
+    bool ExitedEarly,
+    int? ExitCode,
+    string? FailureReason,
+    string? PackageRoot,
+    string? WorkingDirectory,
+    string? Arguments)
+{
+    public int? ProcessId => Process?.Id;
+
+    public static HostStartAttempt Started(HostStartMode startMode, Process process, HostLaunchPlan plan) =>
+        new(
+            startMode,
+            true,
+            process,
+            false,
+            null,
+            null,
+            plan.PackageRoot,
+            plan.WorkingDirectory,
+            HostLaunchPlanBuilder.FormatArgumentsForLog(plan.Arguments));
+
+    public static HostStartAttempt EarlyExit(HostStartMode startMode, Process process, int exitCode, HostLaunchPlan plan) =>
+        new(
+            startMode,
+            true,
+            process,
+            true,
+            exitCode,
+            null,
+            plan.PackageRoot,
+            plan.WorkingDirectory,
+            HostLaunchPlanBuilder.FormatArgumentsForLog(plan.Arguments));
+
+    public static HostStartAttempt StartFailed(HostStartMode startMode, string failureReason, HostLaunchPlan? plan = null) =>
+        new(
+            startMode,
+            false,
+            null,
+            false,
+            null,
+            failureReason,
+            plan?.PackageRoot,
+            plan?.WorkingDirectory,
+            plan is null ? null : HostLaunchPlanBuilder.FormatArgumentsForLog(plan.Arguments));
+}
+
+internal sealed record HostLaunchOutcome(
+    LauncherResult Result,
+    Process? Process,
+    LauncherResult? ImmediateResult,
+    Dictionary<string, string> Details)
+{
+    public static HostLaunchOutcome FromResult(LauncherResult result) =>
+        new(result, null, result.Success ? result : null, result.Details);
+
+    public static HostLaunchOutcome FromImmediateResult(LauncherResult result) =>
+        new(result, null, result, result.Details);
+
+    public static HostLaunchOutcome FromProcess(Process process, LauncherResult result, Dictionary<string, string> details) =>
+        new(result, process, null, details);
+}

LanMountainDesktop.Launcher/Startup/HostLaunchService.cs

@@ -0,0 +1,320 @@
+using System.Diagnostics;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Shell;
+using LanMountainDesktop.Launcher.Views;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal sealed class HostLaunchService
+{
+    public async Task<HostLaunchOutcome> LaunchAsync(LaunchContext context, bool forceDirectMode = false, string? retryTag = null)
+    {
+        var commandContext = context.CommandContext;
+        var deploymentLocator = context.DeploymentLocator;
+        var resolution = deploymentLocator.ResolveHostExecutable(commandContext);
+        if (!resolution.Success || string.IsNullOrWhiteSpace(resolution.ResolvedHostPath))
+        {
+            var (errorResult, selectedPath) = await LaunchUiPresenter.ShowHostNotFoundErrorAsync().ConfigureAwait(false);
+            if (errorResult == ErrorWindowResult.Retry)
+            {
+                if (!string.IsNullOrWhiteSpace(selectedPath) && File.Exists(selectedPath))
+                {
+                    return await LaunchWithExplicitPathAsync(context, selectedPath, forceDirectMode, retryTag).ConfigureAwait(false);
+                }
+
+                return await LaunchAsync(context, forceDirectMode, retryTag).ConfigureAwait(false);
+            }
+
+            return HostLaunchOutcome.FromResult(LaunchResultBuilder.Build(
+                success: false,
+                stage: "launchHost",
+                code: "host_not_found",
+                message: "LanMountainDesktop host executable was not found.",
+                details: BuildResolutionDetails(resolution, null, null, "resolve")));
+        }
+
+        return await LaunchWithResolvedPathAsync(context, resolution, forceDirectMode, retryTag).ConfigureAwait(false);
+    }
+
+    public static LauncherResult? ValidateDotNetRuntimePrerequisite(
+        HostLaunchPlan plan,
+        HostResolutionResult resolution,
+        DotNetRuntimeProbeOptions? probeOptions = null)
+    {
+        ArgumentNullException.ThrowIfNull(plan);
+        ArgumentNullException.ThrowIfNull(resolution);
+
+        if (!DotNetRuntimeProbe.IsFrameworkDependentWindowsApp(plan.HostPath))
+        {
+            return null;
+        }
+
+        var runtime = DotNetRuntimeProbe.Probe(probeOptions);
+        Logger.Info(
+            $"Runtime prerequisite check completed. Available={runtime.IsAvailable}; " +
+            $"Architecture={runtime.Architecture}; Message='{runtime.Message}'.");
+
+        if (runtime.IsAvailable)
+        {
+            return null;
+        }
+
+        var details = BuildResolutionDetails(resolution, null, null, "runtime");
+        foreach (var pair in runtime.ToDetails())
+        {
+            details[pair.Key] = pair.Value;
+        }
+
+        return LaunchResultBuilder.Build(
+            success: false,
+            stage: "launchHost",
+            code: "dotnet_runtime_missing",
+            message: ".NET 10 Desktop Runtime is required before LanMountainDesktop can start.",
+            details: details,
+            errorMessage: runtime.Message);
+    }
+
+    private static Task<HostLaunchOutcome> LaunchWithExplicitPathAsync(
+        LaunchContext context,
+        string hostPath,
+        bool forceDirectMode,
+        string? retryTag)
+    {
+        var resolution = new HostResolutionResult
+        {
+            Success = true,
+            ResolvedHostPath = Path.GetFullPath(hostPath),
+            ResolutionSource = "user_selected_path",
+            AppRoot = context.DeploymentLocator.GetAppRoot(),
+            ExplicitAppRoot = Path.GetDirectoryName(hostPath),
+            SearchedPaths = [Path.GetFullPath(hostPath)]
+        };
+
+        return LaunchWithResolvedPathAsync(context, resolution, forceDirectMode, retryTag);
+    }
+
+    private static async Task<HostLaunchOutcome> LaunchWithResolvedPathAsync(
+        LaunchContext context,
+        HostResolutionResult resolution,
+        bool forceDirectMode,
+        string? retryTag)
+    {
+        var dataRoot = context.DataLocationResolver.ResolveDataRoot();
+        var plan = HostLaunchPlanBuilder.Build(context.CommandContext, context.DeploymentLocator, resolution, dataRoot);
+        var prerequisiteFailure = ValidateDotNetRuntimePrerequisite(plan, resolution);
+        if (prerequisiteFailure is not null)
+        {
+            return HostLaunchOutcome.FromResult(prerequisiteFailure);
+        }
+
+        var hostPath = plan.HostPath;
+        if (OperatingSystem.IsLinux() || OperatingSystem.IsMacOS())
+        {
+            EnsureExecutable(hostPath);
+        }
+
+        var primaryMode = HostStartMode.Direct;
+        var fallbackMode = !forceDirectMode && OperatingSystem.IsWindows()
+            ? HostStartMode.ShellExecute
+            : (HostStartMode?)null;
+
+        var firstAttempt = await StartHostProcessAsync(plan, primaryMode, retryTag).ConfigureAwait(false);
+        if (firstAttempt.ProcessCreated && firstAttempt.Process is not null)
+        {
+            var firstDetails = BuildResolutionDetails(resolution, firstAttempt, null, null);
+            return HostLaunchOutcome.FromProcess(
+                firstAttempt.Process,
+                LaunchResultBuilder.Build(true, "launchHost", "ok", "Host launched.", firstDetails),
+                firstDetails);
+        }
+
+        if (fallbackMode is null)
+        {
+            return BuildOutcomeFromAttempt(resolution, firstAttempt, null);
+        }
+
+        Logger.Warn(
+            $"Primary host start attempt failed. Retrying with fallback mode '{fallbackMode}'. " +
+            $"FailureReason='{firstAttempt.FailureReason ?? "unknown"}'; ExitCode='{firstAttempt.ExitCode?.ToString() ?? "<none>"}'.");
+
+        var secondAttempt = await StartHostProcessAsync(plan, fallbackMode.Value, retryTag).ConfigureAwait(false);
+        if (secondAttempt.ProcessCreated && secondAttempt.Process is not null)
+        {
+            var details = BuildResolutionDetails(resolution, firstAttempt, secondAttempt, null);
+            return HostLaunchOutcome.FromProcess(
+                secondAttempt.Process,
+                LaunchResultBuilder.Build(true, "launchHost", "ok", "Host launched.", details),
+                details);
+        }
+
+        return BuildOutcomeFromAttempt(resolution, secondAttempt, firstAttempt);
+    }
+
+    private static HostLaunchOutcome BuildOutcomeFromAttempt(
+        HostResolutionResult resolution,
+        HostStartAttempt finalAttempt,
+        HostStartAttempt? previousAttempt)
+    {
+        var details = BuildResolutionDetails(
+            resolution,
+            previousAttempt ?? finalAttempt,
+            previousAttempt is null ? null : finalAttempt,
+            !finalAttempt.ProcessCreated
+                ? "start"
+                : finalAttempt.ExitCode is int finalExitCode && HostActivationPolicy.IsFailedActivationExitCode(finalExitCode)
+                    ? "activation"
+                    : "early-exit");
+
+        if (!finalAttempt.ProcessCreated)
+        {
+            return HostLaunchOutcome.FromResult(LaunchResultBuilder.Build(
+                false,
+                "launchHost",
+                "host_start_failed",
+                $"Failed to start host using start mode '{finalAttempt.StartMode}'.",
+                details));
+        }
+
+        if (finalAttempt.ExitCode is not null && HostActivationPolicy.IsSuccessfulActivationExitCode(finalAttempt.ExitCode.Value))
+        {
+            return HostLaunchOutcome.FromImmediateResult(LaunchResultBuilder.Build(
+                true,
+                "launch",
+                "activation_redirected",
+                "Launcher activation was redirected to the existing desktop instance.",
+                details));
+        }
+
+        if (finalAttempt.ExitCode is not null && HostActivationPolicy.IsFailedActivationExitCode(finalAttempt.ExitCode.Value))
+        {
+            return HostLaunchOutcome.FromResult(LaunchResultBuilder.Build(
+                false,
+                "launch",
+                "activation_failed",
+                $"Host activation handshake failed using start mode '{finalAttempt.StartMode}'.",
+                details));
+        }
+
+        return HostLaunchOutcome.FromResult(LaunchResultBuilder.Build(
+            false,
+            "launchHost",
+            "host_exited_early",
+            $"Host exited early using start mode '{finalAttempt.StartMode}'.",
+            details));
+    }
+
+    private static async Task<HostStartAttempt> StartHostProcessAsync(
+        HostLaunchPlan plan,
+        HostStartMode startMode,
+        string? retryTag)
+    {
+        var startInfo = new ProcessStartInfo
+        {
+            FileName = plan.HostPath,
+            WorkingDirectory = plan.WorkingDirectory,
+            UseShellExecute = startMode == HostStartMode.ShellExecute
+        };
+
+        if (startMode == HostStartMode.Direct)
+        {
+            foreach (var argument in plan.Arguments)
+            {
+                startInfo.ArgumentList.Add(argument);
+            }
+
+            foreach (var pair in plan.EnvironmentVariables)
+            {
+                startInfo.EnvironmentVariables[pair.Key] = pair.Value;
+            }
+        }
+        else
+        {
+            startInfo.Arguments = HostLaunchPlanBuilder.FormatArgumentsForLog(plan.Arguments);
+        }
+
+        try
+        {
+            var process = Process.Start(startInfo);
+            Logger.Info(
+                $"Host launch requested. Mode='{startMode}'; RetryTag='{retryTag ?? "<none>"}'; Path='{plan.HostPath}'; " +
+                $"PackageRoot='{plan.PackageRoot}'; WorkingDir='{plan.WorkingDirectory}'; Pid={(process is null ? -1 : process.Id)}; " +
+                $"Args='{HostLaunchPlanBuilder.FormatArgumentsForLog(plan.Arguments)}'.");
+
+            if (process is null)
+            {
+                return HostStartAttempt.StartFailed(startMode, "process_start_returned_null", plan);
+            }
+
+            await Task.Yield();
+            return HostStartAttempt.Started(startMode, process, plan);
+        }
+        catch (Exception ex)
+        {
+            Logger.Error($"Host start failed. Mode='{startMode}'.", ex);
+            return HostStartAttempt.StartFailed(startMode, ex.GetType().Name, plan);
+        }
+    }
+
+    internal static Dictionary<string, string> BuildResolutionDetails(
+        HostResolutionResult resolution,
+        HostStartAttempt? firstAttempt,
+        HostStartAttempt? secondAttempt,
+        string? failureStage)
+    {
+        var details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["resolvedAppRoot"] = resolution.AppRoot,
+            ["explicitAppRoot"] = resolution.ExplicitAppRoot ?? string.Empty,
+            ["resolvedHostPath"] = resolution.ResolvedHostPath ?? string.Empty,
+            ["resolutionSource"] = resolution.ResolutionSource ?? string.Empty,
+            ["devModeConfigIgnored"] = resolution.DevModeConfigIgnored.ToString(),
+            ["searchedPaths"] = string.Join(" | ", resolution.SearchedPaths),
+            ["failureStage"] = failureStage ?? string.Empty
+        };
+
+        if (firstAttempt is not null)
+        {
+            details["startMode"] = firstAttempt.StartMode.ToString();
+            details["processCreated"] = firstAttempt.ProcessCreated.ToString();
+            details["hostPid"] = firstAttempt.ProcessId?.ToString() ?? string.Empty;
+            details["packageRoot"] = firstAttempt.PackageRoot ?? string.Empty;
+            details["workingDirectory"] = firstAttempt.WorkingDirectory ?? string.Empty;
+            details["arguments"] = firstAttempt.Arguments ?? string.Empty;
+            details["firstAttemptFailureReason"] = firstAttempt.FailureReason ?? string.Empty;
+            details["firstAttemptExitCode"] = firstAttempt.ExitCode?.ToString() ?? string.Empty;
+        }
+
+        if (secondAttempt is not null)
+        {
+            details["fallbackStartMode"] = secondAttempt.StartMode.ToString();
+            details["fallbackProcessCreated"] = secondAttempt.ProcessCreated.ToString();
+            details["fallbackHostPid"] = secondAttempt.ProcessId?.ToString() ?? string.Empty;
+            details["fallbackPackageRoot"] = secondAttempt.PackageRoot ?? string.Empty;
+            details["fallbackWorkingDirectory"] = secondAttempt.WorkingDirectory ?? string.Empty;
+            details["fallbackArguments"] = secondAttempt.Arguments ?? string.Empty;
+            details["fallbackFailureReason"] = secondAttempt.FailureReason ?? string.Empty;
+            details["fallbackExitCode"] = secondAttempt.ExitCode?.ToString() ?? string.Empty;
+        }
+
+        return details;
+    }
+
+    private static void EnsureExecutable(string path)
+    {
+        if (OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        try
+        {
+            var mode = File.GetUnixFileMode(path);
+            mode |= UnixFileMode.UserExecute | UnixFileMode.GroupExecute | UnixFileMode.OtherExecute;
+            File.SetUnixFileMode(path, mode);
+        }
+        catch
+        {
+        }
+    }
+}

LanMountainDesktop.Launcher/Startup/HostStartupMonitor.cs

@@ -0,0 +1,510 @@
+using System.Diagnostics;
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Resources;
+using LanMountainDesktop.Launcher.Views;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal sealed class HostStartupMonitor
+{
+    private static readonly string SoftTimeoutStatusMessage = Strings.Coordinator_SlowDeviceMessage;
+    private static readonly string SoftTimeoutDetailsMessage = Strings.Coordinator_RunningHostMessage;
+
+    internal sealed record Request(
+        Process HostProcess,
+        LanMountainDesktopIpcClient IpcClient,
+        StartupSuccessTracker SuccessTracker,
+        StartupAttemptRegistry AttemptRegistry,
+        StartupAttemptRecord? TrackedAttempt,
+        bool AttachedToExistingAttempt,
+        Dictionary<string, string> LaunchDetails,
+        TaskCompletionSource<StartupSuccessState> SuccessTcs,
+        TaskCompletionSource<string> ActivationFailedTcs,
+        ISplashStageReporter Reporter,
+        LoadingDetailsWindow? LoadingDetailsWindow,
+        LoadingStateMessage LoadingState,
+        StartupStage LastStage,
+        string LastStageMessage,
+        bool IpcConnected,
+        string ActivationFailureReason,
+        bool SoftTimeoutShown,
+        Action<bool?, bool, bool> PublishCoordinatorStatus,
+        Func<bool, bool, Dictionary<string, string>> ComposeLaunchDetails);
+
+    internal sealed record Outcome(
+        bool Success,
+        string Code,
+        string Message,
+        bool RecoveryActivationAttempted,
+        Dictionary<string, string> Details);
+
+    public async Task<Outcome> MonitorUntilCompleteAsync(Request request)
+    {
+        var ipcConnected = request.IpcConnected;
+        var softTimeoutShown = request.SoftTimeoutShown;
+        var lastStage = request.LastStage;
+        var lastStageMessage = request.LastStageMessage;
+        var activationFailureReason = request.ActivationFailureReason;
+        var loadingState = request.LoadingState;
+        PublicShellStatus? shellStatus = null;
+        var trackedAttempt = request.TrackedAttempt;
+
+        async Task<StartupSuccessState?> RefreshShellStatusAsync(string waitingMessage)
+        {
+            if (!request.IpcClient.IsConnected)
+            {
+                return null;
+            }
+
+            ipcConnected = true;
+            request.AttemptRegistry.MarkOwnedIpcConnected();
+            shellStatus = await TryGetPublicShellStatusAsync(request.IpcClient).ConfigureAwait(false);
+            StartupDiagnostics.TraceShellStatus("refresh", shellStatus, lastStage);
+            if (request.SuccessTracker.TryResolve(shellStatus, out var successState))
+            {
+                return successState;
+            }
+
+            if (shellStatus is not null && !shellStatus.MainWindowOpened && !shellStatus.DesktopVisible)
+            {
+                request.AttemptRegistry.MarkOwnedWaitingForShell(waitingMessage);
+            }
+
+            request.PublishCoordinatorStatus(true, false, false);
+            return null;
+        }
+
+        var connected = await PublicIpcConnection.TryConnectWithBackoffAsync(
+            request.IpcClient,
+            [
+                StartupTimeoutPolicy.InitialIpcConnectTimeout,
+                TimeSpan.FromMilliseconds(3000),
+                TimeSpan.FromMilliseconds(5000)
+            ]).ConfigureAwait(false);
+        if (!connected)
+        {
+            Logger.Info("Host public IPC is not ready yet. Launcher will keep monitoring the host process and retry.");
+        }
+        else
+        {
+            var shellSuccess = await RefreshShellStatusAsync("Host public IPC is ready; waiting for desktop shell.")
+                .ConfigureAwait(false);
+            if (shellSuccess is not null)
+            {
+                request.SuccessTcs.TrySetResult(shellSuccess);
+            }
+        }
+
+        var processExitTask = request.HostProcess.WaitForExitAsync();
+        var startedAt = trackedAttempt?.StartedAtUtc ?? DateTimeOffset.UtcNow;
+        var softTimeoutAt = startedAt + StartupTimeoutPolicy.SoftTimeout;
+        var hardTimeoutAt = startedAt + StartupTimeoutPolicy.HardTimeout;
+        var nextReconnectAttemptAt = DateTimeOffset.UtcNow + StartupTimeoutPolicy.IpcReconnectInterval;
+        var nextShellStatusPollAt = DateTimeOffset.UtcNow + StartupTimeoutPolicy.ShellStatusPollInterval;
+        var ipcReconnectAttemptIndex = 0;
+        var activationRetryAttempted = false;
+
+        while (true)
+        {
+            if (request.SuccessTcs.Task.IsCompleted)
+            {
+                var successState = await request.SuccessTcs.Task.ConfigureAwait(false);
+                request.AttemptRegistry.MarkOwnedSucceeded(successState.Stage, successState.Message);
+                request.PublishCoordinatorStatus(!request.HostProcess.HasExited, true, true);
+                return new Outcome(
+                    true,
+                    successState.Code,
+                    successState.Message,
+                    false,
+                    request.ComposeLaunchDetails(!request.HostProcess.HasExited, false));
+            }
+
+            if (request.ActivationFailedTcs.Task.IsCompleted && !activationRetryAttempted)
+            {
+                activationRetryAttempted = true;
+                activationFailureReason = await request.ActivationFailedTcs.Task.ConfigureAwait(false);
+                Logger.Warn($"Activation failure received before startup success. Reason='{activationFailureReason}'.");
+                var activationRecovery = await TryRecoverActivationThroughExistingHostAsync(
+                    request.IpcClient,
+                    request.SuccessTracker,
+                    TimeSpan.FromSeconds(1)).ConfigureAwait(false);
+                if (activationRecovery is not null)
+                {
+                    request.AttemptRegistry.MarkOwnedSucceeded(activationRecovery.Stage, activationRecovery.Message);
+                    request.PublishCoordinatorStatus(!request.HostProcess.HasExited, true, true);
+                    return new Outcome(
+                        true,
+                        activationRecovery.Code,
+                        activationRecovery.Message,
+                        true,
+                        request.ComposeLaunchDetails(!request.HostProcess.HasExited, true));
+                }
+
+                Logger.Info("Activation failure did not recover through public IPC yet. Launcher will keep monitoring the current host attempt.");
+            }
+
+            if (processExitTask.IsCompleted)
+            {
+                var exitCode = request.HostProcess.ExitCode;
+                Logger.Warn($"Host exited before startup success criteria were met. ExitCode={exitCode}.");
+
+                if (HostActivationPolicy.IsSuccessfulActivationExitCode(exitCode))
+                {
+                    request.AttemptRegistry.MarkOwnedSucceeded(StartupStage.ActivationRedirected, "Host redirected activation to the existing desktop instance.");
+                    request.PublishCoordinatorStatus(false, true, true);
+                    return new Outcome(
+                        true,
+                        "activation_redirected",
+                        "Host redirected activation to the existing desktop instance.",
+                        false,
+                        MergeExitCodeDetails(request.ComposeLaunchDetails(false, false), exitCode));
+                }
+
+                if (!activationRetryAttempted && HostActivationPolicy.IsFailedActivationExitCode(exitCode))
+                {
+                    activationRetryAttempted = true;
+                    var activationRecovery = await TryRecoverActivationThroughExistingHostAsync(
+                        request.IpcClient,
+                        request.SuccessTracker,
+                        TimeSpan.FromSeconds(2)).ConfigureAwait(false);
+                    if (activationRecovery is not null)
+                    {
+                        request.AttemptRegistry.MarkOwnedSucceeded(activationRecovery.Stage, activationRecovery.Message);
+                        request.PublishCoordinatorStatus(true, true, true);
+                        return new Outcome(
+                            true,
+                            activationRecovery.Code,
+                            activationRecovery.Message,
+                            true,
+                            MergeExitCodeDetails(request.ComposeLaunchDetails(true, true), exitCode));
+                    }
+
+                    Logger.Info("Activation exit code did not recover through public IPC. Launcher will report the activation failure without launching another host.");
+                }
+
+                request.AttemptRegistry.MarkOwnedFailed(lastStage, activationFailureReason);
+                request.PublishCoordinatorStatus(false, true, false);
+                return new Outcome(
+                    false,
+                    HostActivationPolicy.IsFailedActivationExitCode(exitCode) ? "activation_failed" : "host_exited_early",
+                    HostActivationPolicy.IsFailedActivationExitCode(exitCode)
+                        ? $"Host activation handshake failed before the required startup state was reported. ExitCode={exitCode}."
+                        : $"Host exited before the required startup state was reported. ExitCode={exitCode}.",
+                    false,
+                    MergeExitCodeDetails(request.ComposeLaunchDetails(false, false), exitCode));
+            }
+
+            var now = DateTimeOffset.UtcNow;
+            if (ipcConnected &&
+                !request.HostProcess.HasExited &&
+                now >= nextShellStatusPollAt)
+            {
+                var shellSuccess = await RefreshShellStatusAsync("Host public IPC is ready; waiting for desktop shell.")
+                    .ConfigureAwait(false);
+                if (shellSuccess is not null)
+                {
+                    request.SuccessTcs.TrySetResult(shellSuccess);
+                    continue;
+                }
+
+                nextShellStatusPollAt = DateTimeOffset.UtcNow + StartupTimeoutPolicy.ShellStatusPollInterval;
+            }
+
+            if (!ipcConnected &&
+                !request.HostProcess.HasExited &&
+                now >= nextReconnectAttemptAt)
+            {
+                var reconnectTimeout = StartupTimeoutPolicy.IpcReconnectAttemptTimeouts[
+                    Math.Min(ipcReconnectAttemptIndex, StartupTimeoutPolicy.IpcReconnectAttemptTimeouts.Length - 1)];
+                ipcReconnectAttemptIndex++;
+                connected = await PublicIpcConnection.TryConnectAsync(request.IpcClient, reconnectTimeout).ConfigureAwait(false);
+                if (connected)
+                {
+                    ipcConnected = true;
+                    var shellSuccess = await RefreshShellStatusAsync("Host public IPC reconnected; waiting for desktop shell.")
+                        .ConfigureAwait(false);
+                    if (shellSuccess is not null)
+                    {
+                        request.SuccessTcs.TrySetResult(shellSuccess);
+                        continue;
+                    }
+                }
+
+                nextReconnectAttemptAt = DateTimeOffset.UtcNow + StartupTimeoutPolicy.IpcReconnectInterval;
+            }
+
+            if (!softTimeoutShown &&
+                now >= softTimeoutAt &&
+                (!request.HostProcess.HasExited || ipcConnected))
+            {
+                softTimeoutShown = true;
+                request.AttemptRegistry.MarkOwnedSoftTimeout(SoftTimeoutStatusMessage);
+                request.Reporter.Report("delayed", SoftTimeoutStatusMessage);
+                loadingState = BuildDelayedLoadingState(
+                    loadingState,
+                    SoftTimeoutStatusMessage,
+                    SoftTimeoutDetailsMessage,
+                    trackedAttempt?.StartedAtUtc ?? startedAt);
+                request.LoadingDetailsWindow?.UpdateLoadingState(loadingState);
+                request.PublishCoordinatorStatus(!request.HostProcess.HasExited, false, false);
+            }
+
+            if (now >= hardTimeoutAt)
+            {
+                break;
+            }
+
+            var nextCheckpointAt = hardTimeoutAt;
+            if (!softTimeoutShown && softTimeoutAt < nextCheckpointAt)
+            {
+                nextCheckpointAt = softTimeoutAt;
+            }
+
+            var delay = nextCheckpointAt - now;
+            if (delay > TimeSpan.FromSeconds(1))
+            {
+                delay = TimeSpan.FromSeconds(1);
+            }
+            else if (delay < TimeSpan.FromMilliseconds(100))
+            {
+                delay = TimeSpan.FromMilliseconds(100);
+            }
+
+            await Task.WhenAny(
+                request.SuccessTcs.Task,
+                request.ActivationFailedTcs.Task,
+                processExitTask,
+                Task.Delay(delay)).ConfigureAwait(false);
+        }
+
+        var recoveryActivationAttempted = false;
+        if (!connected && !request.HostProcess.HasExited)
+        {
+            connected = await PublicIpcConnection.TryConnectAsync(request.IpcClient, TimeSpan.FromSeconds(3)).ConfigureAwait(false);
+            if (connected)
+            {
+                var shellSuccess = await RefreshShellStatusAsync("Host public IPC is ready; waiting for desktop shell.")
+                    .ConfigureAwait(false);
+                if (shellSuccess is not null)
+                {
+                    request.AttemptRegistry.MarkOwnedSucceeded(shellSuccess.Stage, shellSuccess.Message);
+                    request.PublishCoordinatorStatus(true, true, true);
+                    return new Outcome(
+                        true,
+                        shellSuccess.Code,
+                        shellSuccess.Message,
+                        false,
+                        request.ComposeLaunchDetails(true, false));
+                }
+            }
+        }
+
+        if (connected && !request.HostProcess.HasExited)
+        {
+            recoveryActivationAttempted = true;
+            var recoveryOutcome = await TryRecoverWithPublicActivationAsync(
+                request.IpcClient,
+                request.HostProcess,
+                request.SuccessTcs.Task,
+                request.SuccessTracker).ConfigureAwait(false);
+            if (recoveryOutcome is not null)
+            {
+                request.AttemptRegistry.MarkOwnedSucceeded(recoveryOutcome.Stage, recoveryOutcome.Message);
+                request.PublishCoordinatorStatus(!request.HostProcess.HasExited, true, true);
+                return new Outcome(
+                    true,
+                    recoveryOutcome.Code,
+                    recoveryOutcome.Message,
+                    true,
+                    request.ComposeLaunchDetails(!request.HostProcess.HasExited, true));
+            }
+        }
+
+        if (connected && !request.HostProcess.HasExited)
+        {
+            request.AttemptRegistry.MarkOwnedWaitingForShell("Host process is still running after the launcher wait window.");
+            shellStatus = await TryGetPublicShellStatusAsync(request.IpcClient).ConfigureAwait(false);
+            if (request.SuccessTracker.TryResolve(shellStatus, out var finalShellSuccess))
+            {
+                request.AttemptRegistry.MarkOwnedSucceeded(finalShellSuccess.Stage, finalShellSuccess.Message);
+                request.PublishCoordinatorStatus(true, true, true);
+                return new Outcome(
+                    true,
+                    finalShellSuccess.Code,
+                    finalShellSuccess.Message,
+                    recoveryActivationAttempted,
+                    request.ComposeLaunchDetails(true, recoveryActivationAttempted));
+            }
+
+            request.PublishCoordinatorStatus(true, true, false);
+            return new Outcome(
+                false,
+                "shell_not_ready",
+                "Host public IPC is connected, but the desktop shell did not create or show the main window in time.",
+                recoveryActivationAttempted,
+                request.ComposeLaunchDetails(true, recoveryActivationAttempted));
+        }
+
+        if (!connected && !request.HostProcess.HasExited)
+        {
+            request.AttemptRegistry.MarkOwnedWaitingForShell("Host process is still running, but public IPC is not ready yet.");
+            request.PublishCoordinatorStatus(true, false, true);
+            return new Outcome(
+                true,
+                "startup_pending",
+                "Host process is still running; Launcher will not start another process while public IPC finishes startup.",
+                recoveryActivationAttempted,
+                request.ComposeLaunchDetails(true, recoveryActivationAttempted));
+        }
+
+        request.AttemptRegistry.MarkOwnedFailed(lastStage, activationFailureReason);
+        request.PublishCoordinatorStatus(!request.HostProcess.HasExited, true, false);
+        return new Outcome(
+            false,
+            "desktop_not_visible",
+            $"Host process started, but it never reached the required startup state within {StartupTimeoutPolicy.HardTimeout.TotalSeconds:0} seconds.",
+            recoveryActivationAttempted,
+            request.ComposeLaunchDetails(!request.HostProcess.HasExited, recoveryActivationAttempted));
+    }
+
+    internal static async Task<StartupSuccessState?> TryRecoverActivationThroughExistingHostAsync(
+        LanMountainDesktopIpcClient ipcClient,
+        StartupSuccessTracker startupSuccessTracker,
+        TimeSpan timeout)
+    {
+        var activation = await TryActivateExistingHostWithStatusAsync(ipcClient, timeout).ConfigureAwait(false);
+        if (activation is null)
+        {
+            return null;
+        }
+
+        if (startupSuccessTracker.TryResolve(activation.Status, out var shellSuccess))
+        {
+            return shellSuccess;
+        }
+
+        if (activation.Accepted)
+        {
+            return startupSuccessTracker.BuildRecoverySuccessState();
+        }
+
+        return HostActivationPolicy.IsRecoverableActivationFailure(activation)
+            ? new StartupSuccessState(
+                StartupStage.Ready,
+                "startup_pending",
+                activation.Message)
+            : null;
+    }
+
+    internal static async Task<PublicShellStatus?> TryGetPublicShellStatusAsync(LanMountainDesktopIpcClient ipcClient)
+    {
+        try
+        {
+            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
+            return await shellProxy.GetShellStatusAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to query public shell status: {ex.Message}");
+            return null;
+        }
+    }
+
+    private static async Task<PublicShellActivationResult?> TryActivateExistingHostWithStatusAsync(
+        LanMountainDesktopIpcClient ipcClient,
+        TimeSpan timeout)
+    {
+        try
+        {
+            var connected = ipcClient.IsConnected ||
+                            await PublicIpcConnection.TryConnectAsync(ipcClient, timeout).ConfigureAwait(false);
+            if (!connected)
+            {
+                return null;
+            }
+
+            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
+            return await shellProxy.ActivateMainWindowWithStatusAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            Logger.Info($"Existing host activation probe did not complete: {ex.Message}");
+            return null;
+        }
+    }
+
+    private static async Task<StartupSuccessState?> TryRecoverWithPublicActivationAsync(
+        LanMountainDesktopIpcClient ipcClient,
+        Process hostProcess,
+        Task<StartupSuccessState> successTask,
+        StartupSuccessTracker startupSuccessTracker)
+    {
+        try
+        {
+            var shellProxy = ipcClient.CreateProxy<IPublicShellControlService>();
+            var activation = await shellProxy.ActivateMainWindowWithStatusAsync().ConfigureAwait(false);
+            StartupDiagnostics.TraceShellStatus("recovery_activation", activation.Status);
+            if (startupSuccessTracker.TryResolve(activation.Status, out var shellSuccess))
+            {
+                return shellSuccess;
+            }
+
+            var completedTask = await Task.WhenAny(successTask, Task.Delay(TimeSpan.FromSeconds(5))).ConfigureAwait(false);
+            if (completedTask == successTask)
+            {
+                return await successTask.ConfigureAwait(false);
+            }
+
+            if (!hostProcess.HasExited && (activation.Accepted || HostActivationPolicy.IsRecoverableActivationFailure(activation)))
+            {
+                return startupSuccessTracker.BuildRecoverySuccessState();
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Public activation recovery failed: {ex.Message}");
+        }
+
+        return null;
+    }
+
+    internal static LoadingStateMessage BuildDelayedLoadingState(
+        LoadingStateMessage loadingState,
+        string summaryMessage,
+        string detailMessage,
+        DateTimeOffset startedAtUtc)
+    {
+        var delayedItems = loadingState.ActiveItems
+            .Where(item => !string.Equals(item.Id, "launcher-soft-timeout", StringComparison.OrdinalIgnoreCase))
+            .ToList();
+
+        delayedItems.Insert(0, new LoadingItem
+        {
+            Id = "launcher-soft-timeout",
+            Type = LoadingItemType.System,
+            Name = "Startup still in progress",
+            Description = detailMessage,
+            State = LoadingState.Delayed,
+            ProgressPercent = Math.Max(loadingState.OverallProgressPercent, 1),
+            Message = detailMessage,
+            StartTime = startedAtUtc
+        });
+
+        return loadingState with
+        {
+            ActiveItems = delayedItems,
+            Message = summaryMessage,
+            Timestamp = DateTimeOffset.UtcNow,
+            TotalCount = Math.Max(loadingState.TotalCount, delayedItems.Count)
+        };
+    }
+
+    private static Dictionary<string, string> MergeExitCodeDetails(Dictionary<string, string> details, int exitCode)
+    {
+        details["exitCode"] = exitCode.ToString();
+        return details;
+    }
+}

LanMountainDesktop.Launcher/Startup/LaunchAttemptDetails.cs

@@ -0,0 +1,49 @@
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal static class LaunchAttemptDetails
+{
+    public static Dictionary<string, string> Build(
+        StartupAttemptRecord? trackedAttempt,
+        bool attachedToExistingAttempt,
+        bool ipcConnected,
+        bool hostProcessAlive,
+        StartupStage lastStage,
+        string lastStageMessage,
+        string? activationFailureReason,
+        bool softTimeoutShown,
+        bool recoveryActivationAttempted)
+    {
+        var details = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["hostProcessAlive"] = hostProcessAlive.ToString(),
+            ["attachedToExistingAttempt"] = attachedToExistingAttempt.ToString(),
+            ["ipcConnected"] = ipcConnected.ToString(),
+            ["ipcStage"] = lastStage.ToString(),
+            ["ipcMessage"] = lastStageMessage,
+            ["activationFailureReason"] = activationFailureReason ?? string.Empty,
+            ["softTimeoutShown"] = softTimeoutShown.ToString(),
+            ["recoveryActivationAttempted"] = recoveryActivationAttempted.ToString()
+        };
+
+        if (trackedAttempt is not null)
+        {
+            details["startupAttemptId"] = trackedAttempt.AttemptId;
+            details["startupAttemptState"] = trackedAttempt.State.ToString();
+            details["startupAttemptStartedAtUtc"] = trackedAttempt.StartedAtUtc.ToString("O");
+            details["startupAttemptUpdatedAtUtc"] = trackedAttempt.UpdatedAtUtc.ToString("O");
+            details["startupAttemptHeartbeatAtUtc"] = trackedAttempt.HeartbeatAtUtc.ToString("O");
+            details["successPolicy"] = trackedAttempt.SuccessPolicy;
+            details["hostPid"] = trackedAttempt.HostPid.ToString();
+            details["coordinatorPid"] = trackedAttempt.CoordinatorPid.ToString();
+            details["coordinatorPipeName"] = trackedAttempt.CoordinatorPipeName;
+            details["reservedBeforeHostStart"] = trackedAttempt.ReservedBeforeHostStart.ToString();
+            details["publicIpcConnected"] = trackedAttempt.PublicIpcConnected.ToString();
+            details["shellStatus"] = trackedAttempt.ShellStatus;
+        }
+
+        return details;
+    }
+}

LanMountainDesktop.Launcher/Startup/LaunchPipeline.cs

@@ -0,0 +1,191 @@
+using System.Diagnostics;
+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.Startup;
+
+internal enum LaunchPhaseStatus
+{
+    Continue,
+    Completed
+}
+
+internal sealed record LaunchPhaseResult(LaunchPhaseStatus Status, LauncherResult? Result = null);
+
+internal interface ILaunchPhase
+{
+    string Name { get; }
+
+    Task<LaunchPhaseResult> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken = default);
+}
+
+internal sealed class LaunchContext
+{
+    public required CommandContext CommandContext { get; init; }
+    public required DeploymentLocator DeploymentLocator { get; init; }
+    public required OobeStateService OobeStateService { get; init; }
+    public required IUpdateEngine UpdateEngine { get; init; }
+    public required StartupAttemptRegistry StartupAttemptRegistry { get; init; }
+    public LauncherCoordinatorIpcServer? CoordinatorIpcServer { get; init; }
+    public required DataLocationResolver DataLocationResolver { get; init; }
+    public required IReadOnlyList<IOobeStep> OobeSteps { get; init; }
+
+    public SplashWindow SplashWindow { get; set; } = null!;
+    public LoadingDetailsWindow? LoadingDetailsWindow { get; set; }
+    public ISplashStageReporter Reporter { get; set; } = null!;
+    public LanMountainDesktopIpcClient IpcClient { get; set; } = null!;
+    public StartupSuccessTracker SuccessTracker { get; set; } = null!;
+    public TaskCompletionSource<StartupSuccessState> SuccessTcs { get; set; } = null!;
+    public TaskCompletionSource<string> ActivationFailedTcs { get; set; } = null!;
+    public LoadingStateMessage LoadingState { get; set; }
+    public Dictionary<string, string> LauncherContextDetails { get; set; } = [];
+    public OobeLaunchDecision OobeDecision { get; set; } = null!;
+
+    public StartupStage LastStage { get; set; } = StartupStage.Initializing;
+    public string LastStageMessage { get; set; } = "launcher-started";
+    public string ActivationFailureReason { get; set; } = string.Empty;
+    public bool IpcConnected { get; set; }
+    public bool SoftTimeoutShown { get; set; }
+    public bool AttachedToExistingAttempt { get; set; }
+    public bool WindowsClosingByOrchestrator { get; set; }
+    public StartupAttemptRecord? TrackedAttempt { get; set; }
+    public PublicShellStatus? ShellStatus { get; set; }
+    public HostLaunchOutcome? LaunchOutcome { get; set; }
+
+    public Action<bool?, bool, bool> PublishCoordinatorStatus { get; set; } = static (_, _, _) => { };
+    public EventHandler? SplashClosedHandler { get; set; }
+}
+
+internal sealed class LaunchPipeline
+{
+    private readonly IReadOnlyList<ILaunchPhase> _phases;
+
+    public LaunchPipeline(IEnumerable<ILaunchPhase> phases)
+    {
+        _phases = phases.ToList();
+    }
+
+    public async Task<LauncherResult> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken = default)
+    {
+        foreach (var phase in _phases)
+        {
+            Logger.Info($"Launch pipeline entering phase '{phase.Name}'.");
+            var phaseResult = await phase.ExecuteAsync(context, cancellationToken).ConfigureAwait(false);
+            if (phaseResult.Status == LaunchPhaseStatus.Completed)
+            {
+                return phaseResult.Result ?? LaunchResultBuilder.BuildFailure(
+                    "launch",
+                    "phase_completed_without_result",
+                    $"Launch phase '{phase.Name}' completed without a result.");
+            }
+        }
+
+        return LaunchResultBuilder.BuildFailure(
+            "launch",
+            "pipeline_incomplete",
+            "Launch pipeline finished without producing a result.");
+    }
+}
+
+internal static class LaunchResultBuilder
+{
+    public static LauncherResult Build(
+        bool success,
+        string stage,
+        string code,
+        string message,
+        Dictionary<string, string>? details = null,
+        string? errorMessage = null)
+    {
+        Logger.Info($"Launcher result prepared. Success={success}; Stage='{stage}'; Code='{code}'.");
+        return new LauncherResult
+        {
+            Success = success,
+            Stage = stage,
+            Code = code,
+            Message = message,
+            ErrorMessage = errorMessage,
+            Details = details ?? []
+        };
+    }
+
+    public static LauncherResult BuildFailure(string stage, string code, string message) =>
+        Build(false, stage, code, message);
+
+    public static LauncherResult WithAdditionalDetails(LauncherResult result, Dictionary<string, string> details) =>
+        new()
+        {
+            Success = result.Success,
+            Stage = result.Stage,
+            Code = result.Code,
+            Message = result.Message,
+            CurrentVersion = result.CurrentVersion,
+            TargetVersion = result.TargetVersion,
+            RolledBackTo = result.RolledBackTo,
+            Details = MergeDetails(details, result.Details),
+            InstalledPackagePath = result.InstalledPackagePath,
+            ManifestId = result.ManifestId,
+            ManifestName = result.ManifestName,
+            ErrorMessage = result.ErrorMessage
+        };
+
+    public static Dictionary<string, string> BuildLauncherContextDetails(
+        CommandContext context,
+        OobeLaunchDecision oobeDecision,
+        string appRoot) =>
+        new(StringComparer.OrdinalIgnoreCase)
+        {
+            ["command"] = context.Command,
+            ["launchSource"] = context.LaunchSource,
+            ["isGuiMode"] = context.IsGuiCommand.ToString(),
+            ["isDebugMode"] = context.IsDebugMode.ToString(),
+            ["isElevated"] = oobeDecision.IsElevated.ToString(),
+            ["resolvedAppRoot"] = appRoot,
+            ["oobeStatePath"] = oobeDecision.StatePath,
+            ["oobeStateStatus"] = oobeDecision.Status.ToString(),
+            ["oobeDecision"] = oobeDecision.ShouldShowOobe ? "show" : "skip",
+            ["oobeSuppressionReason"] = oobeDecision.SuppressionReason,
+            ["oobeResultCode"] = oobeDecision.ResultCode,
+            ["userSid"] = oobeDecision.UserSid ?? string.Empty,
+            ["usedLegacyOobeMarker"] = oobeDecision.UsedLegacyMarker.ToString(),
+            ["migratedLegacyOobeMarker"] = oobeDecision.MigratedLegacyMarker.ToString(),
+            ["oobeStateError"] = oobeDecision.ErrorMessage
+        };
+
+    public static Dictionary<string, string> MergeDetails(
+        Dictionary<string, string> left,
+        Dictionary<string, string> right)
+    {
+        var merged = new Dictionary<string, string>(left, StringComparer.OrdinalIgnoreCase);
+        foreach (var pair in right)
+        {
+            merged[pair.Key] = pair.Value;
+        }
+
+        return merged;
+    }
+
+    public static bool TryGetLiveProcess(int processId, out Process? process)
+    {
+        process = null;
+        if (processId <= 0)
+        {
+            return false;
+        }
+
+        try
+        {
+            process = Process.GetProcessById(processId);
+            return !process.HasExited;
+        }
+        catch
+        {
+            process?.Dispose();
+            process = null;
+            return false;
+        }
+    }
+}

LanMountainDesktop.Launcher/Startup/Phases/ApplyPendingUpdatePhase.cs

@@ -0,0 +1,27 @@
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal sealed class ApplyPendingUpdatePhase : ILaunchPhase
+{
+    public string Name => nameof(ApplyPendingUpdatePhase);
+
+    public async Task<LaunchPhaseResult> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken = default)
+    {
+        context.Reporter.Report("update", "Checking updates...");
+        var updateResult = await context.UpdateEngine.ApplyPendingUpdateAsync().ConfigureAwait(false);
+        if (!updateResult.Success)
+        {
+            Logger.Warn($"Update apply failed, will try to launch existing version. Error='{updateResult.Message}'.");
+            context.Reporter.Report("update", "Update failed, launching existing version...");
+            try
+            {
+                context.UpdateEngine.CleanupIncomingArtifacts();
+            }
+            catch (Exception ex)
+            {
+                Logger.Warn($"Failed to cleanup update artifacts after failed update: {ex.Message}");
+            }
+        }
+
+        return new LaunchPhaseResult(LaunchPhaseStatus.Continue);
+    }
+}

LanMountainDesktop.Launcher/Startup/Phases/CleanupDeploymentsPhase.cs

@@ -0,0 +1,17 @@
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal sealed class CleanupDeploymentsPhase : ILaunchPhase
+{
+    public string Name => nameof(CleanupDeploymentsPhase);
+
+    public Task<LaunchPhaseResult> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken = default)
+    {
+        context.DeploymentLocator.CleanupOldDeployments(minVersionsToKeep: 3);
+        context.OobeDecision = context.OobeStateService.Evaluate(context.CommandContext);
+        context.LauncherContextDetails = LaunchResultBuilder.BuildLauncherContextDetails(
+            context.CommandContext,
+            context.OobeDecision,
+            context.DeploymentLocator.GetAppRoot());
+        return Task.FromResult(new LaunchPhaseResult(LaunchPhaseStatus.Continue));
+    }
+}

LanMountainDesktop.Launcher/Startup/Phases/ExistingHostProbePhase.cs

@@ -0,0 +1,72 @@
+using LanMountainDesktop.Launcher.Shell;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal sealed class ExistingHostProbePhase : ILaunchPhase
+{
+    public string Name => nameof(ExistingHostProbePhase);
+
+    public async Task<LaunchPhaseResult> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken = default)
+    {
+        if (!HostActivationPolicy.ShouldProbeExistingHostBeforeLaunch(context.CommandContext))
+        {
+            return new LaunchPhaseResult(LaunchPhaseStatus.Continue);
+        }
+
+        var multiInstanceBehavior = ExistingHostProbe.LoadMultiInstanceLaunchBehavior(context.DataLocationResolver);
+        var existingShellStatus = await ExistingHostProbe.TryGetExistingHostStatusAsync(
+            context.IpcClient,
+            StartupTimeoutPolicy.ExistingHostProbeTimeout).ConfigureAwait(false);
+
+        if (!HostActivationPolicy.IsExistingHostReadyForLauncherDecision(existingShellStatus))
+        {
+            return new LaunchPhaseResult(LaunchPhaseStatus.Continue);
+        }
+
+        context.IpcConnected = true;
+        context.ShellStatus = existingShellStatus;
+        var decisionResult = await ExistingHostProbe.ApplyExistingHostBehaviorAsync(
+            context.IpcClient,
+            multiInstanceBehavior,
+            existingShellStatus!).ConfigureAwait(false);
+        context.ShellStatus = decisionResult.ActivationResult?.Status ?? existingShellStatus;
+        var recoverableActivationFailure = decisionResult.ActivationResult is not null &&
+                                           HostActivationPolicy.IsRecoverableActivationFailure(decisionResult.ActivationResult);
+        context.LastStage = decisionResult.Success || recoverableActivationFailure
+            ? StartupStage.ActivationRedirected
+            : StartupStage.ActivationFailed;
+        context.LastStageMessage = decisionResult.Message;
+        if (decisionResult.Success || recoverableActivationFailure)
+        {
+            context.StartupAttemptRegistry.MarkOwnedSucceeded(context.LastStage, context.LastStageMessage);
+        }
+        else
+        {
+            context.StartupAttemptRegistry.MarkOwnedFailed(context.LastStage, context.LastStageMessage);
+        }
+
+        context.PublishCoordinatorStatus(true, true, decisionResult.Success);
+        context.WindowsClosingByOrchestrator = true;
+        await LaunchUiPresenter.CloseWindowsAsync(context.SplashWindow, context.LoadingDetailsWindow).ConfigureAwait(false);
+        return new LaunchPhaseResult(
+            LaunchPhaseStatus.Completed,
+            LaunchResultBuilder.Build(
+                decisionResult.Success,
+                "launch",
+                decisionResult.Code,
+                decisionResult.Message,
+                LaunchResultBuilder.MergeDetails(
+                    context.LauncherContextDetails,
+                    new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+                    {
+                        ["publicIpcConnected"] = "true",
+                        ["multiInstanceBehavior"] = multiInstanceBehavior.ToString(),
+                        ["existingHostPid"] = context.ShellStatus?.ProcessId.ToString() ?? string.Empty,
+                        ["existingShellState"] = context.ShellStatus?.ShellState ?? string.Empty,
+                        ["existingTrayState"] = context.ShellStatus?.Tray.State ?? string.Empty,
+                        ["existingTaskbarUsable"] = context.ShellStatus?.Taskbar.IsUsable.ToString() ?? string.Empty,
+                        ["activationAccepted"] = decisionResult.ActivationResult?.Accepted.ToString() ?? string.Empty
+                    })));
+    }
+}

LanMountainDesktop.Launcher/Startup/Phases/LaunchHostPhase.cs

@@ -0,0 +1,174 @@
+using LanMountainDesktop.Launcher.Models;
+using LanMountainDesktop.Launcher.Shell;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal sealed class LaunchHostPhase : ILaunchPhase
+{
+    private static readonly string SoftTimeoutStatusMessage = Resources.Strings.Coordinator_SlowDeviceMessage;
+    private static readonly string SoftTimeoutDetailsMessage = Resources.Strings.Coordinator_RunningHostMessage;
+
+    private readonly HostLaunchService _hostLaunchService = new();
+
+    public string Name => nameof(LaunchHostPhase);
+
+    public async Task<LaunchPhaseResult> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken = default)
+    {
+        context.Reporter.Report("launch", "Launching desktop...");
+        var startupSuccessTracker = context.SuccessTracker;
+        var attachableAttempt = context.StartupAttemptRegistry.TryGetAttachableAttempt(
+            context.CommandContext.LaunchSource,
+            startupSuccessTracker.PolicyKey);
+
+        HostLaunchOutcome launchOutcome;
+        if (attachableAttempt is not null &&
+            context.StartupAttemptRegistry.AdoptAttempt(attachableAttempt.AttemptId) &&
+            LaunchResultBuilder.TryGetLiveProcess(attachableAttempt.HostPid, out var attachedProcess))
+        {
+            context.TrackedAttempt = attachableAttempt;
+            context.AttachedToExistingAttempt = true;
+            context.IpcConnected = attachableAttempt.IpcConnected;
+            context.LastStage = attachableAttempt.LastObservedStage;
+            context.LastStageMessage = string.IsNullOrWhiteSpace(attachableAttempt.LastObservedMessage)
+                ? "Attached to the existing startup attempt."
+                : attachableAttempt.LastObservedMessage;
+            context.Reporter.Report(
+                LaunchUiPresenter.MapStartupStageToSplashStage(context.LastStage),
+                context.LastStageMessage);
+            context.PublishCoordinatorStatus(true, false, false);
+
+            if (startupSuccessTracker.TryResolve(context.LastStage, out var attachedSuccessState))
+            {
+                context.WindowsClosingByOrchestrator = true;
+                context.StartupAttemptRegistry.MarkOwnedSucceeded(attachedSuccessState.Stage, attachedSuccessState.Message);
+                await LaunchUiPresenter.CloseWindowsAsync(context.SplashWindow, context.LoadingDetailsWindow).ConfigureAwait(false);
+                return new LaunchPhaseResult(
+                    LaunchPhaseStatus.Completed,
+                    LaunchResultBuilder.Build(
+                        true,
+                        "launch",
+                        attachedSuccessState.Code,
+                        attachedSuccessState.Message,
+                        LaunchResultBuilder.MergeDetails(
+                            context.LauncherContextDetails,
+                            LaunchAttemptDetails.Build(
+                                context.TrackedAttempt,
+                                context.AttachedToExistingAttempt,
+                                context.IpcConnected,
+                                hostProcessAlive: true,
+                                context.LastStage,
+                                context.LastStageMessage,
+                                context.ActivationFailureReason,
+                                softTimeoutShown: false,
+                                recoveryActivationAttempted: false))));
+            }
+
+            if (attachableAttempt.State is StartupAttemptState.SoftTimeout or StartupAttemptState.DetachedWaiting)
+            {
+                context.SoftTimeoutShown = true;
+                context.Reporter.Report("delayed", SoftTimeoutStatusMessage);
+                context.LoadingState = HostStartupMonitor.BuildDelayedLoadingState(
+                    context.LoadingState,
+                    SoftTimeoutStatusMessage,
+                    SoftTimeoutDetailsMessage,
+                    context.TrackedAttempt!.StartedAtUtc);
+                context.LoadingDetailsWindow?.UpdateLoadingState(context.LoadingState);
+            }
+
+            launchOutcome = HostLaunchOutcome.FromProcess(
+                attachedProcess!,
+                LaunchResultBuilder.Build(
+                    true,
+                    "launchHost",
+                    "attached_attempt",
+                    "Attached to an existing startup attempt.",
+                    LaunchAttemptDetails.Build(
+                        context.TrackedAttempt,
+                        context.AttachedToExistingAttempt,
+                        context.IpcConnected,
+                        hostProcessAlive: true,
+                        context.LastStage,
+                        context.LastStageMessage,
+                        context.ActivationFailureReason,
+                        context.SoftTimeoutShown,
+                        recoveryActivationAttempted: false)),
+                LaunchAttemptDetails.Build(
+                    context.TrackedAttempt,
+                    context.AttachedToExistingAttempt,
+                    context.IpcConnected,
+                    hostProcessAlive: true,
+                    context.LastStage,
+                    context.LastStageMessage,
+                    context.ActivationFailureReason,
+                    context.SoftTimeoutShown,
+                    recoveryActivationAttempted: false));
+        }
+        else
+        {
+            launchOutcome = await _hostLaunchService.LaunchAsync(context).ConfigureAwait(false);
+        }
+
+        context.LaunchOutcome = launchOutcome;
+
+        if (!launchOutcome.Result.Success)
+        {
+            return new LaunchPhaseResult(
+                LaunchPhaseStatus.Completed,
+                LaunchResultBuilder.WithAdditionalDetails(launchOutcome.Result, context.LauncherContextDetails));
+        }
+
+        if (launchOutcome.ImmediateResult is not null)
+        {
+            context.WindowsClosingByOrchestrator = true;
+            await LaunchUiPresenter.CloseWindowsAsync(context.SplashWindow, context.LoadingDetailsWindow).ConfigureAwait(false);
+            return new LaunchPhaseResult(
+                LaunchPhaseStatus.Completed,
+                LaunchResultBuilder.WithAdditionalDetails(launchOutcome.ImmediateResult, context.LauncherContextDetails));
+        }
+
+        if (launchOutcome.Process is null)
+        {
+            return new LaunchPhaseResult(
+                LaunchPhaseStatus.Completed,
+                LaunchResultBuilder.Build(
+                    success: false,
+                    stage: "launch",
+                    code: "host_start_failed",
+                    message: "Host launch did not create a process.",
+                    details: LaunchResultBuilder.MergeDetails(
+                        context.LauncherContextDetails,
+                        LaunchResultBuilder.MergeDetails(
+                            launchOutcome.Details,
+                            LaunchAttemptDetails.Build(
+                                context.TrackedAttempt,
+                                context.AttachedToExistingAttempt,
+                                context.IpcConnected,
+                                hostProcessAlive: false,
+                                context.LastStage,
+                                context.LastStageMessage,
+                                context.ActivationFailureReason,
+                                context.SoftTimeoutShown,
+                                recoveryActivationAttempted: false)))));
+        }
+
+        if (!context.AttachedToExistingAttempt)
+        {
+            var reservedAttempt = context.StartupAttemptRegistry.GetOwnedAttempt();
+            context.TrackedAttempt = reservedAttempt is { ReservedBeforeHostStart: true }
+                ? context.StartupAttemptRegistry.AssignOwnedHostProcess(
+                    launchOutcome.Process.Id,
+                    context.LastStage,
+                    context.LastStageMessage)
+                : context.StartupAttemptRegistry.StartOwnedAttempt(
+                    launchOutcome.Process.Id,
+                    context.CommandContext.LaunchSource,
+                    startupSuccessTracker.PolicyKey,
+                    context.LastStage,
+                    context.LastStageMessage);
+            context.PublishCoordinatorStatus(true, false, false);
+        }
+
+        return new LaunchPhaseResult(LaunchPhaseStatus.Continue);
+    }
+}

LanMountainDesktop.Launcher/Startup/Phases/MonitorStartupPhase.cs

@@ -0,0 +1,70 @@
+using LanMountainDesktop.Launcher.Shell;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal sealed class MonitorStartupPhase : ILaunchPhase
+{
+    public string Name => nameof(MonitorStartupPhase);
+
+    public async Task<LaunchPhaseResult> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken = default)
+    {
+        var launchOutcome = context.LaunchOutcome
+            ?? throw new InvalidOperationException("LaunchHostPhase must run before MonitorStartupPhase.");
+
+        if (launchOutcome.Process is null)
+        {
+            return new LaunchPhaseResult(
+                LaunchPhaseStatus.Completed,
+                LaunchResultBuilder.BuildFailure("launch", "host_start_failed", "Host process is missing."));
+        }
+
+        Dictionary<string, string> ComposeLaunchDetails(bool hostProcessAlive, bool recoveryActivationAttempted = false) =>
+            LaunchResultBuilder.MergeDetails(
+                context.LauncherContextDetails,
+                LaunchResultBuilder.MergeDetails(
+                    launchOutcome.Details,
+                    LaunchAttemptDetails.Build(
+                        context.TrackedAttempt,
+                        context.AttachedToExistingAttempt,
+                        context.IpcConnected,
+                        hostProcessAlive,
+                        context.LastStage,
+                        context.LastStageMessage,
+                        context.ActivationFailureReason,
+                        context.SoftTimeoutShown,
+                        recoveryActivationAttempted)));
+
+        var monitor = new HostStartupMonitor();
+        var monitorOutcome = await monitor.MonitorUntilCompleteAsync(new HostStartupMonitor.Request(
+            launchOutcome.Process,
+            context.IpcClient,
+            context.SuccessTracker,
+            context.StartupAttemptRegistry,
+            context.TrackedAttempt,
+            context.AttachedToExistingAttempt,
+            context.LauncherContextDetails,
+            context.SuccessTcs,
+            context.ActivationFailedTcs,
+            context.Reporter,
+            context.LoadingDetailsWindow,
+            context.LoadingState,
+            context.LastStage,
+            context.LastStageMessage,
+            context.IpcConnected,
+            context.ActivationFailureReason,
+            context.SoftTimeoutShown,
+            context.PublishCoordinatorStatus,
+            ComposeLaunchDetails)).ConfigureAwait(false);
+
+        context.WindowsClosingByOrchestrator = true;
+        await LaunchUiPresenter.CloseWindowsAsync(context.SplashWindow, context.LoadingDetailsWindow).ConfigureAwait(false);
+        return new LaunchPhaseResult(
+            LaunchPhaseStatus.Completed,
+            LaunchResultBuilder.Build(
+                monitorOutcome.Success,
+                "launch",
+                monitorOutcome.Code,
+                monitorOutcome.Message,
+                monitorOutcome.Details));
+    }
+}

LanMountainDesktop.Launcher/Startup/Phases/OobeGatePhase.cs

@@ -0,0 +1,24 @@
+using LanMountainDesktop.Launcher.Shell;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal sealed class OobeGatePhase : ILaunchPhase
+{
+    public string Name => nameof(OobeGatePhase);
+
+    public async Task<LaunchPhaseResult> ExecuteAsync(LaunchContext context, CancellationToken cancellationToken = default)
+    {
+        if (context.OobeDecision.ShouldShowOobe)
+        {
+            await LaunchUiPresenter.HideSplashAsync(context.SplashWindow).ConfigureAwait(false);
+            foreach (var step in context.OobeSteps)
+            {
+                await step.RunAsync(cancellationToken).ConfigureAwait(false);
+            }
+
+            await LaunchUiPresenter.ShowSplashAsync(context.SplashWindow).ConfigureAwait(false);
+        }
+
+        return new LaunchPhaseResult(LaunchPhaseStatus.Continue);
+    }
+}

LanMountainDesktop.Launcher/Startup/PublicIpcConnection.cs

@@ -0,0 +1,56 @@
+using LanMountainDesktop.Shared.IPC;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal static class PublicIpcConnection
+{
+    public static async Task<bool> TryConnectAsync(
+        LanMountainDesktopIpcClient ipcClient,
+        TimeSpan timeout,
+        CancellationToken cancellationToken = default)
+    {
+        if (ipcClient.IsConnected)
+        {
+            return true;
+        }
+
+        try
+        {
+            var connectTask = ipcClient.ConnectAsync();
+            var completedTask = await Task.WhenAny(connectTask, Task.Delay(timeout, cancellationToken)).ConfigureAwait(false);
+            if (completedTask != connectTask)
+            {
+                return false;
+            }
+
+            await connectTask.ConfigureAwait(false);
+            return ipcClient.IsConnected;
+        }
+        catch (Exception ex) when (ex is not OperationCanceledException)
+        {
+            Logger.Info($"Public IPC is not ready yet: {ex.Message}");
+            return false;
+        }
+    }
+
+    public static async Task<bool> TryConnectWithBackoffAsync(
+        LanMountainDesktopIpcClient ipcClient,
+        IReadOnlyList<TimeSpan> attemptTimeouts,
+        CancellationToken cancellationToken = default)
+    {
+        if (ipcClient.IsConnected)
+        {
+            return true;
+        }
+
+        foreach (var timeout in attemptTimeouts)
+        {
+            if (await TryConnectAsync(ipcClient, timeout, cancellationToken).ConfigureAwait(false))
+            {
+                return true;
+            }
+        }
+
+        return ipcClient.IsConnected;
+    }
+}

LanMountainDesktop.Launcher/Startup/StartupAttemptRegistry.cs

@@ -5,7 +5,7 @@ using System.Text.Json;
 using LanMountainDesktop.Launcher.Models;
 using LanMountainDesktop.Shared.Contracts.Launcher;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Startup;
 
 internal sealed class StartupAttemptRegistry
 {

LanMountainDesktop.Launcher/Startup/StartupDiagnostics.cs

@@ -0,0 +1,71 @@
+using System.Text.Json;
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal static class StartupDiagnostics
+{
+    private static readonly bool Enabled =
+        string.Equals(
+            Environment.GetEnvironmentVariable("LMD_LAUNCHER_STARTUP_DIAG"),
+            "1",
+            StringComparison.OrdinalIgnoreCase);
+
+    public static bool IsEnabled => Enabled;
+
+    public static void Trace(string eventName, IReadOnlyDictionary<string, string?> fields)
+    {
+        if (!Enabled)
+        {
+            return;
+        }
+
+        var payload = new Dictionary<string, string?>(fields, StringComparer.OrdinalIgnoreCase)
+        {
+            ["event"] = eventName,
+            ["timestampUtc"] = DateTimeOffset.UtcNow.ToString("O")
+        };
+
+        Logger.Info($"[startup-diag] {eventName}: {string.Join("; ", payload.Select(static kv => $"{kv.Key}={kv.Value}"))}");
+
+        try
+        {
+            var directory = Path.Combine(
+                Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+                "LanMountainDesktop",
+                ".launcher",
+                "diag");
+            Directory.CreateDirectory(directory);
+            var filePath = Path.Combine(directory, $"startup-{DateTime.UtcNow:yyyyMMdd}.jsonl");
+            var line = JsonSerializer.Serialize(payload);
+            File.AppendAllText(filePath, line + Environment.NewLine);
+        }
+        catch (Exception ex)
+        {
+            Logger.Warn($"Failed to write startup diagnostic bundle: {ex.Message}");
+        }
+    }
+
+    public static void TraceShellStatus(string source, PublicShellStatus? status, StartupStage? stage = null)
+    {
+        if (!Enabled)
+        {
+            return;
+        }
+
+        Trace(
+            "shell_status",
+            new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase)
+            {
+                ["source"] = source,
+                ["stage"] = stage?.ToString(),
+                ["processId"] = status?.ProcessId.ToString(),
+                ["publicIpcReady"] = status?.PublicIpcReady.ToString(),
+                ["desktopVisible"] = status?.DesktopVisible.ToString(),
+                ["mainWindowVisible"] = status?.MainWindowVisible.ToString(),
+                ["mainWindowOpened"] = status?.MainWindowOpened.ToString(),
+                ["shellState"] = status?.ShellState
+            });
+    }
+}

LanMountainDesktop.Launcher/Startup/StartupSuccessTracker.cs

@@ -0,0 +1,137 @@
+using LanMountainDesktop.Shared.Contracts.Launcher;
+using LanMountainDesktop.Shared.IPC.Abstractions.Services;
+
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal enum LaunchSuccessPolicy
+{
+    Foreground,
+    RestartBackground,
+    RestartTray
+}
+
+internal sealed record StartupSuccessState(
+    StartupStage Stage,
+    string Code,
+    string Message);
+
+internal sealed class StartupSuccessTracker
+{
+    private readonly LaunchSuccessPolicy _policy;
+    private bool _trayReady;
+    private bool _backgroundReady;
+
+    public string PolicyKey => _policy.ToString();
+
+    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.Ready:
+                successState = new StartupSuccessState(
+                    stage,
+                    _policy == LaunchSuccessPolicy.Foreground ? "ready" : "background_ready",
+                    "Desktop reported that startup is ready.");
+                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 bool TryResolve(PublicShellStatus? status, out StartupSuccessState successState)
+    {
+        if (status is not null &&
+            (status.DesktopVisible || status.MainWindowVisible || status.MainWindowOpened))
+        {
+            successState = new StartupSuccessState(
+                status.DesktopVisible || status.MainWindowVisible
+                    ? StartupStage.DesktopVisible
+                    : StartupStage.Ready,
+                _policy == LaunchSuccessPolicy.Foreground ? "ok" : "background_ready",
+                status.DesktopVisible || status.MainWindowVisible
+                    ? "Desktop shell is visible and ready."
+                    : "Desktop shell window has opened.");
+            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.")
+        };
+    }
+}

LanMountainDesktop.Launcher/Startup/StartupTimeoutPolicy.cs

@@ -0,0 +1,23 @@
+namespace LanMountainDesktop.Launcher.Startup;
+
+internal static class StartupTimeoutPolicy
+{
+    public static readonly TimeSpan SoftTimeout = TimeSpan.FromSeconds(30);
+    public static readonly TimeSpan HardTimeout = TimeSpan.FromSeconds(120);
+
+    /// <summary>Initial Public IPC connect attempt (AOT cold start may be slower).</summary>
+    public static readonly TimeSpan InitialIpcConnectTimeout = TimeSpan.FromMilliseconds(1200);
+
+    /// <summary>Subsequent reconnect attempts use increasing per-try timeouts.</summary>
+    public static readonly TimeSpan[] IpcReconnectAttemptTimeouts =
+    [
+        TimeSpan.FromMilliseconds(800),
+        TimeSpan.FromMilliseconds(1500),
+        TimeSpan.FromMilliseconds(3000),
+        TimeSpan.FromMilliseconds(5000)
+    ];
+
+    public static readonly TimeSpan ExistingHostProbeTimeout = TimeSpan.FromMilliseconds(900);
+    public static readonly TimeSpan ShellStatusPollInterval = TimeSpan.FromSeconds(1);
+    public static readonly TimeSpan IpcReconnectInterval = TimeSpan.FromSeconds(2);
+}

LanMountainDesktop.Launcher/Update/DeploymentActivator.cs

@@ -0,0 +1,73 @@
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class DeploymentActivator(DeploymentLocator deploymentLocator)
+{
+    public void Activate(string fromDeployment, string toDeployment)
+    {
+        var toCurrent = Path.Combine(toDeployment, ".current");
+        var fromCurrent = Path.Combine(fromDeployment, ".current");
+        var fromDestroy = Path.Combine(fromDeployment, ".destroy");
+        var toDestroy = Path.Combine(toDeployment, ".destroy");
+        var toPartial = Path.Combine(toDeployment, ".partial");
+
+        File.WriteAllText(toCurrent, string.Empty);
+        if (File.Exists(toDestroy))
+        {
+            File.Delete(toDestroy);
+        }
+
+        if (File.Exists(fromCurrent))
+        {
+            File.Delete(fromCurrent);
+        }
+
+        File.WriteAllText(fromDestroy, string.Empty);
+        if (File.Exists(toPartial))
+        {
+            File.Delete(toPartial);
+        }
+    }
+
+    public RollbackAttemptResult TryRollbackOnFailure(SnapshotMetadata snapshot)
+    {
+        try
+        {
+            if (!string.IsNullOrWhiteSpace(snapshot.TargetDirectory) && Directory.Exists(snapshot.TargetDirectory))
+            {
+                Directory.Delete(snapshot.TargetDirectory, true);
+            }
+
+            if (string.IsNullOrWhiteSpace(snapshot.SourceDirectory) || !Directory.Exists(snapshot.SourceDirectory))
+            {
+                return new RollbackAttemptResult(false, "Source deployment is missing.");
+            }
+
+            var destroyMarker = Path.Combine(snapshot.SourceDirectory, ".destroy");
+            if (File.Exists(destroyMarker))
+            {
+                File.Delete(destroyMarker);
+            }
+
+            var currentMarker = Path.Combine(snapshot.SourceDirectory, ".current");
+            if (!File.Exists(currentMarker))
+            {
+                File.WriteAllText(currentMarker, string.Empty);
+            }
+
+            return new RollbackAttemptResult(true, null);
+        }
+        catch (Exception ex)
+        {
+            return new RollbackAttemptResult(false, ex.Message);
+        }
+    }
+
+    public void RetainDeploymentsForRollback()
+    {
+        deploymentLocator.CleanupOldDeployments(minVersionsToKeep: 3);
+    }
+}
+
+internal sealed record RollbackAttemptResult(bool Success, string? ErrorMessage);

LanMountainDesktop.Launcher/Update/IUpdateEngine.cs

@@ -0,0 +1,18 @@
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal interface IUpdateEngine
+{
+    LauncherResult CheckPendingUpdate();
+
+    Task<LauncherResult> DownloadAsync(string manifestUrl, string signatureUrl, string archiveUrl, CancellationToken cancellationToken);
+
+    Task<LauncherResult> ApplyPendingUpdateAsync();
+
+    LauncherResult RollbackLatest();
+
+    void CleanupDestroyedDeployments();
+
+    void CleanupIncomingArtifacts();
+}

LanMountainDesktop.Launcher/Update/IUpdateProgressReporter.cs

@@ -1,6 +1,6 @@
 using LanMountainDesktop.Shared.Contracts.Update;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Update;
 
 public interface IUpdateProgressReporter
 {

LanMountainDesktop.Launcher/Update/IncomingArtifactsCleaner.cs

@@ -0,0 +1,51 @@
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class IncomingArtifactsCleaner(UpdateEnginePaths paths)
+{
+    public void Cleanup()
+    {
+        foreach (var path in new[]
+                 {
+                     paths.FileMapPath,
+                     paths.SignaturePath,
+                     paths.ArchivePath,
+                     paths.PlondsFileMapPath,
+                     paths.PlondsSignaturePath,
+                     paths.PlondsUpdateMetadataPath,
+                     paths.InstallCheckpointPath
+                 })
+        {
+            TryDeleteFile(path);
+        }
+
+        TryDeleteDirectory(paths.PlondsObjectsRoot);
+    }
+
+    private static void TryDeleteFile(string path)
+    {
+        try
+        {
+            if (File.Exists(path))
+            {
+                File.Delete(path);
+            }
+        }
+        catch
+        {
+        }
+    }
+
+    private static void TryDeleteDirectory(string path)
+    {
+        try
+        {
+            if (Directory.Exists(path))
+            {
+                Directory.Delete(path, true);
+            }
+        }
+        catch
+        {
+        }
+    }
+}

LanMountainDesktop.Launcher/Update/InstallCheckpointStore.cs

@@ -0,0 +1,49 @@
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class InstallCheckpointStore(UpdateEnginePaths paths)
+{
+    public InstallCheckpoint? Load()
+    {
+        if (!File.Exists(paths.InstallCheckpointPath))
+        {
+            return null;
+        }
+
+        try
+        {
+            var text = File.ReadAllText(paths.InstallCheckpointPath);
+            if (string.IsNullOrWhiteSpace(text))
+            {
+                return null;
+            }
+
+            return JsonSerializer.Deserialize(text, AppJsonContext.Default.InstallCheckpoint);
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    public void Save(InstallCheckpoint checkpoint)
+    {
+        File.WriteAllText(paths.InstallCheckpointPath, JsonSerializer.Serialize(checkpoint, AppJsonContext.Default.InstallCheckpoint));
+    }
+
+    public void Delete()
+    {
+        try
+        {
+            if (File.Exists(paths.InstallCheckpointPath))
+            {
+                File.Delete(paths.InstallCheckpointPath);
+            }
+        }
+        catch
+        {
+        }
+    }
+}

LanMountainDesktop.Launcher/Update/LegacyUpdateApplier.cs

@@ -0,0 +1,287 @@
+using System.IO.Compression;
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+using ContractsUpdate = LanMountainDesktop.Shared.Contracts.Update;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class LegacyUpdateApplier(
+    DeploymentLocator deploymentLocator,
+    UpdateEnginePaths paths,
+    UpdateSignatureVerifier signatureVerifier,
+    IUpdateProgressReporter progressReporter,
+    UpdateSnapshotStore snapshotStore,
+    InstallCheckpointStore checkpointStore,
+    DeploymentActivator deploymentActivator,
+    IncomingArtifactsCleaner incomingCleaner)
+{
+    public async Task<LauncherResult> ApplyAsync()
+    {
+        if (!File.Exists(paths.FileMapPath) || !File.Exists(paths.ArchivePath))
+        {
+            return new LauncherResult
+            {
+                Success = true,
+                Stage = "update.apply",
+                Code = "noop",
+                Message = "No update payload found."
+            };
+        }
+
+        progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.VerifySignature, "Verifying signature...", 0, null, 0, 0));
+        var verifyResult = signatureVerifier.Verify(paths.FileMapPath, paths.SignaturePath, UpdateEnginePaths.SignatureFileName);
+        if (!verifyResult.Success)
+        {
+            progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(false, null, null, verifyResult.Message, false));
+            return UpdateEngineResults.Failed("update.apply", "signature_failed", verifyResult.Message);
+        }
+
+        var fileMapText = await File.ReadAllTextAsync(paths.FileMapPath).ConfigureAwait(false);
+        var fileMap = JsonSerializer.Deserialize(fileMapText, AppJsonContext.Default.SignedFileMap);
+        if (fileMap is null || fileMap.Files.Count == 0)
+        {
+            progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(false, null, null, "No update file entries were found.", false));
+            return UpdateEngineResults.Failed("update.apply", "invalid_manifest", "No update file entries were found.");
+        }
+
+        var currentDeployment = deploymentLocator.FindCurrentDeploymentDirectory();
+        var currentVersion = deploymentLocator.GetCurrentVersion();
+        if (!string.IsNullOrWhiteSpace(fileMap.FromVersion) &&
+            !string.Equals(fileMap.FromVersion, currentVersion, StringComparison.OrdinalIgnoreCase))
+        {
+            return UpdateEngineResults.Failed(
+                "update.apply",
+                "version_mismatch",
+                $"Update requires source version {fileMap.FromVersion} but current is {currentVersion}.");
+        }
+
+        var targetVersion = string.IsNullOrWhiteSpace(fileMap.ToVersion) ? currentVersion : fileMap.ToVersion!;
+        var existingCheckpoint = checkpointStore.Load();
+        var canResume = existingCheckpoint is not null
+                        && string.Equals(existingCheckpoint.SourceVersion, currentVersion, StringComparison.OrdinalIgnoreCase)
+                        && string.Equals(existingCheckpoint.TargetVersion, targetVersion, StringComparison.OrdinalIgnoreCase)
+                        && string.Equals(existingCheckpoint.SourceDirectory ?? string.Empty, currentDeployment ?? string.Empty, StringComparison.OrdinalIgnoreCase)
+                        && Directory.Exists(existingCheckpoint.TargetDirectory)
+                        && File.Exists(Path.Combine(existingCheckpoint.TargetDirectory, ".partial"));
+
+        if (existingCheckpoint is not null && !canResume)
+        {
+            return UpdateEngineResults.Failed("update.apply", "resume_state_invalid", "Install checkpoint is stale or invalid. Please cancel and redownload update payload.");
+        }
+
+        var targetDeployment = canResume
+            ? existingCheckpoint!.TargetDirectory
+            : deploymentLocator.BuildNextDeploymentDirectory(targetVersion);
+        var snapshot = BuildSnapshot(canResume, existingCheckpoint, currentVersion, targetVersion, currentDeployment, targetDeployment);
+        var snapshotPath = snapshotStore.CreateSnapshotPath(snapshot.SnapshotId);
+        var checkpoint = canResume
+            ? existingCheckpoint!
+            : BuildCheckpoint(snapshot, currentVersion, targetVersion, currentDeployment, targetDeployment);
+
+        try
+        {
+            snapshotStore.Save(snapshotPath, snapshot);
+            PrepareExtractRoot();
+            ZipFile.ExtractToDirectory(paths.ArchivePath, paths.ExtractRoot, overwriteFiles: true);
+
+            if (!canResume)
+            {
+                progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.CreateTarget, "Creating target deployment...", 20, null, 0, fileMap.Files.Count));
+                Directory.CreateDirectory(targetDeployment);
+                File.WriteAllText(Path.Combine(targetDeployment, ".partial"), string.Empty);
+            }
+
+            checkpointStore.Save(checkpoint);
+            ApplyFiles(fileMap, currentDeployment!, targetDeployment, checkpoint);
+            VerifyFiles(fileMap, targetDeployment, checkpoint);
+
+            progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.ActivateDeployment, "Activating deployment...", 85, null, fileMap.Files.Count, fileMap.Files.Count));
+            deploymentActivator.Activate(currentDeployment!, targetDeployment);
+
+            snapshot.Status = "applied";
+            snapshotStore.Save(snapshotPath, snapshot);
+            incomingCleaner.Cleanup();
+            deploymentActivator.RetainDeploymentsForRollback();
+
+            progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.Completed, $"Updated to {targetVersion}.", 100, null, fileMap.Files.Count, fileMap.Files.Count));
+            progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(true, currentVersion, targetVersion, null, false));
+
+            return new LauncherResult
+            {
+                Success = true,
+                Stage = "update.apply",
+                Code = "ok",
+                Message = $"Updated to {targetVersion}.",
+                CurrentVersion = currentVersion,
+                TargetVersion = targetVersion
+            };
+        }
+        catch (Exception ex)
+        {
+            progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.RollingBack, "Rolling back...", 0, null, 0, 0));
+            var rollbackResult = deploymentActivator.TryRollbackOnFailure(snapshot);
+            snapshot.Status = rollbackResult.Success ? "rolled_back" : "rollback_failed";
+            snapshotStore.Save(snapshotPath, snapshot);
+            var errorMessage = rollbackResult.Success
+                ? ex.Message
+                : $"{ex.Message}; rollback failed: {rollbackResult.ErrorMessage}";
+            progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(false, currentVersion, targetVersion, errorMessage, rollbackResult.Success));
+            return new LauncherResult
+            {
+                Success = false,
+                Stage = "update.apply",
+                Code = rollbackResult.Success ? "apply_failed" : "rollback_failed",
+                Message = rollbackResult.Success
+                    ? "Failed to apply update. Rolled back to previous version."
+                    : "Failed to apply update and rollback failed.",
+                ErrorMessage = errorMessage,
+                CurrentVersion = currentVersion,
+                RolledBackTo = rollbackResult.Success ? currentVersion : null
+            };
+        }
+        finally
+        {
+            checkpointStore.Delete();
+            TryDeleteExtractRoot();
+        }
+    }
+
+    private void ApplyFiles(SignedFileMap fileMap, string currentDeployment, string targetDeployment, InstallCheckpoint checkpoint)
+    {
+        progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.ApplyFiles, "Applying files...", 30, null, checkpoint.AppliedCount, fileMap.Files.Count));
+        for (var fileIndex = checkpoint.AppliedCount; fileIndex < fileMap.Files.Count; fileIndex++)
+        {
+            var file = fileMap.Files[fileIndex];
+            ApplyFileEntry(file, currentDeployment, targetDeployment);
+            checkpoint.AppliedCount = fileIndex + 1;
+            checkpointStore.Save(checkpoint);
+            progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.ApplyFiles, "Applying files...", 30 + (checkpoint.AppliedCount * 30 / fileMap.Files.Count), file.Path, checkpoint.AppliedCount, fileMap.Files.Count));
+        }
+    }
+
+    private void VerifyFiles(SignedFileMap fileMap, string targetDeployment, InstallCheckpoint checkpoint)
+    {
+        progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.VerifyHashes, "Verifying hashes...", 65, null, checkpoint.VerifiedCount, fileMap.Files.Count));
+        for (var verifyIndex = checkpoint.VerifiedCount; verifyIndex < fileMap.Files.Count; verifyIndex++)
+        {
+            var file = fileMap.Files[verifyIndex];
+            if (NeedsVerification(file))
+            {
+                var fullPath = Path.Combine(targetDeployment, file.Path);
+                var actualHash = UpdateHash.ComputeSha256Hex(fullPath);
+                if (!string.Equals(actualHash, file.Sha256, StringComparison.OrdinalIgnoreCase))
+                {
+                    throw new InvalidOperationException($"File hash mismatch for '{file.Path}'.");
+                }
+            }
+
+            checkpoint.VerifiedCount = verifyIndex + 1;
+            checkpointStore.Save(checkpoint);
+            progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.VerifyHashes, "Verifying hashes...", 65 + (checkpoint.VerifiedCount * 15 / fileMap.Files.Count), file.Path, checkpoint.VerifiedCount, fileMap.Files.Count));
+        }
+    }
+
+    private void ApplyFileEntry(UpdateFileEntry file, string currentDeployment, string targetDeployment)
+    {
+        var normalizedPath = UpdatePathGuard.NormalizeRelativePath(file.Path);
+        if (string.Equals(file.Action, "delete", StringComparison.OrdinalIgnoreCase))
+        {
+            return;
+        }
+
+        var targetPath = Path.Combine(targetDeployment, normalizedPath);
+        UpdatePathGuard.EnsurePathWithinRoot(targetPath, targetDeployment);
+        var targetDir = Path.GetDirectoryName(targetPath);
+        if (!string.IsNullOrWhiteSpace(targetDir))
+        {
+            Directory.CreateDirectory(targetDir);
+        }
+
+        if (string.Equals(file.Action, "reuse", StringComparison.OrdinalIgnoreCase))
+        {
+            var sourcePath = Path.Combine(currentDeployment, normalizedPath);
+            UpdatePathGuard.EnsurePathWithinRoot(sourcePath, currentDeployment);
+            if (!File.Exists(sourcePath))
+            {
+                throw new FileNotFoundException($"Cannot reuse file '{file.Path}' because it was not found in current deployment.");
+            }
+
+            File.Copy(sourcePath, targetPath, overwrite: true);
+            return;
+        }
+
+        var archiveRelative = string.IsNullOrWhiteSpace(file.ArchivePath) ? normalizedPath : UpdatePathGuard.NormalizeRelativePath(file.ArchivePath);
+        var extractedPath = Path.Combine(paths.ExtractRoot, archiveRelative);
+        UpdatePathGuard.EnsurePathWithinRoot(extractedPath, paths.ExtractRoot);
+        if (!File.Exists(extractedPath))
+        {
+            throw new FileNotFoundException($"Archive file '{archiveRelative}' not found for '{file.Path}'.");
+        }
+
+        File.Copy(extractedPath, targetPath, overwrite: true);
+    }
+
+    private void PrepareExtractRoot()
+    {
+        if (Directory.Exists(paths.ExtractRoot))
+        {
+            Directory.Delete(paths.ExtractRoot, true);
+        }
+
+        Directory.CreateDirectory(paths.ExtractRoot);
+    }
+
+    private void TryDeleteExtractRoot()
+    {
+        try
+        {
+            if (Directory.Exists(paths.ExtractRoot))
+            {
+                Directory.Delete(paths.ExtractRoot, true);
+            }
+        }
+        catch
+        {
+        }
+    }
+
+    private static SnapshotMetadata BuildSnapshot(
+        bool canResume,
+        InstallCheckpoint? existingCheckpoint,
+        string currentVersion,
+        string targetVersion,
+        string? currentDeployment,
+        string targetDeployment) =>
+        new()
+        {
+            SnapshotId = canResume ? existingCheckpoint!.SnapshotId : Guid.NewGuid().ToString("N"),
+            SourceVersion = currentVersion,
+            TargetVersion = targetVersion,
+            CreatedAt = DateTimeOffset.UtcNow,
+            SourceDirectory = currentDeployment ?? string.Empty,
+            TargetDirectory = targetDeployment,
+            Status = "pending"
+        };
+
+    private static InstallCheckpoint BuildCheckpoint(
+        SnapshotMetadata snapshot,
+        string currentVersion,
+        string targetVersion,
+        string? currentDeployment,
+        string targetDeployment) =>
+        new()
+        {
+            SnapshotId = snapshot.SnapshotId,
+            SourceVersion = currentVersion,
+            TargetVersion = targetVersion,
+            SourceDirectory = currentDeployment,
+            TargetDirectory = targetDeployment,
+            IsInitialDeployment = false
+        };
+
+    private static bool NeedsVerification(UpdateFileEntry file)
+    {
+        return !string.Equals(file.Action, "delete", StringComparison.OrdinalIgnoreCase) &&
+               !string.IsNullOrWhiteSpace(file.Sha256);
+    }
+}

LanMountainDesktop.Launcher/Update/NullUpdateProgressReporter.cs

@@ -1,6 +1,6 @@
 using LanMountainDesktop.Shared.Contracts.Update;
 
-namespace LanMountainDesktop.Launcher.Services;
+namespace LanMountainDesktop.Launcher.Update;
 
 internal sealed class NullUpdateProgressReporter : IUpdateProgressReporter
 {

LanMountainDesktop.Launcher/Update/PendingUpdateDetector.cs

@@ -0,0 +1,116 @@
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class PendingUpdateDetector(
+    DeploymentLocator deploymentLocator,
+    UpdateEnginePaths paths,
+    UpdateSignatureVerifier signatureVerifier)
+{
+    public LauncherResult CheckPendingUpdate()
+    {
+        if (File.Exists(paths.PlondsFileMapPath) && File.Exists(paths.PlondsSignaturePath))
+        {
+            var pdcFileMapText = File.ReadAllText(paths.PlondsFileMapPath);
+            var pdcFileMap = JsonSerializer.Deserialize(pdcFileMapText, AppJsonContext.Default.PlondsFileMap);
+            if (pdcFileMap is null)
+            {
+                return UpdateEngineResults.Failed("update.check", "invalid_manifest", "plonds-filemap.json is invalid.");
+            }
+
+            var pdcVerified = signatureVerifier.Verify(
+                paths.PlondsFileMapPath,
+                paths.PlondsSignaturePath,
+                UpdateEnginePaths.PlondsSignatureFileName);
+            if (!pdcVerified.Success)
+            {
+                return UpdateEngineResults.Failed("update.check", "signature_failed", pdcVerified.Message);
+            }
+
+            var pdcMetadata = PlondsManifestParser.LoadMetadata(paths.PlondsUpdateMetadataPath);
+            return new LauncherResult
+            {
+                Success = true,
+                Stage = "update.check",
+                Code = "available",
+                Message = "Pending PLONDS update is available.",
+                CurrentVersion = deploymentLocator.GetCurrentVersion(),
+                TargetVersion = PlondsManifestParser.ResolveTargetVersion(pdcFileMap, pdcMetadata)
+            };
+        }
+
+        if (!File.Exists(paths.FileMapPath) || !File.Exists(paths.ArchivePath))
+        {
+            return new LauncherResult
+            {
+                Success = true,
+                Stage = "update.check",
+                Code = "noop",
+                Message = "No pending update."
+            };
+        }
+
+        var fileMapText = File.ReadAllText(paths.FileMapPath);
+        var fileMap = JsonSerializer.Deserialize(fileMapText, AppJsonContext.Default.SignedFileMap);
+        if (fileMap is null)
+        {
+            return UpdateEngineResults.Failed("update.check", "invalid_manifest", "files.json is invalid.");
+        }
+
+        var verified = signatureVerifier.Verify(paths.FileMapPath, paths.SignaturePath, UpdateEnginePaths.SignatureFileName);
+        if (!verified.Success)
+        {
+            return UpdateEngineResults.Failed("update.check", "signature_failed", verified.Message);
+        }
+
+        return new LauncherResult
+        {
+            Success = true,
+            Stage = "update.check",
+            Code = "available",
+            Message = "Pending update is available.",
+            CurrentVersion = deploymentLocator.GetCurrentVersion(),
+            TargetVersion = fileMap.ToVersion
+        };
+    }
+
+    public LauncherResult ValidateIncomingState()
+    {
+        if (File.Exists(paths.ApplyLockPath))
+        {
+            return UpdateEngineResults.Failed("update.apply", "lock_conflict", "Another update apply operation is already in progress.");
+        }
+
+        if (!File.Exists(paths.DeploymentLockPath))
+        {
+            return UpdateEngineResults.Failed("update.apply", "staging_incomplete", "Deployment lock is missing. Please redownload the update.");
+        }
+
+        var hasPlondsMap = File.Exists(paths.PlondsFileMapPath);
+        var hasLegacyMap = File.Exists(paths.FileMapPath);
+        if (hasPlondsMap && !File.Exists(paths.DownloadMarkerPath))
+        {
+            return UpdateEngineResults.Failed("update.apply", "staging_incomplete", "Download marker is missing for pending PLONDS update.");
+        }
+
+        if (!hasPlondsMap && !hasLegacyMap)
+        {
+            return new LauncherResult
+            {
+                Success = true,
+                Stage = "update.apply",
+                Code = "noop",
+                Message = "No update payload found."
+            };
+        }
+
+        return new LauncherResult
+        {
+            Success = true,
+            Stage = "update.apply",
+            Code = "ok",
+            Message = "Incoming update state validated."
+        };
+    }
+}

LanMountainDesktop.Launcher/Update/PlondsManifestParser.cs

@@ -0,0 +1,416 @@
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal static class PlondsManifestParser
+{
+    public static List<PlondsFileEntry> CollectFileEntries(PlondsFileMap fileMap)
+    {
+        var files = new List<PlondsFileEntry>();
+        if (fileMap.Files is { Count: > 0 })
+        {
+            files.AddRange(fileMap.Files);
+        }
+
+        if (fileMap.Components is null)
+        {
+            return files;
+        }
+
+        foreach (var component in fileMap.Components)
+        {
+            if (component.Files is { Count: > 0 })
+            {
+                files.AddRange(component.Files);
+            }
+        }
+
+        return files;
+    }
+
+    public static void PopulateFromRawJson(string fileMapJson, PlondsFileMap fileMap, ICollection<PlondsFileEntry> files)
+    {
+        if (string.IsNullOrWhiteSpace(fileMapJson))
+        {
+            return;
+        }
+
+        using var document = JsonDocument.Parse(fileMapJson);
+        var root = document.RootElement;
+        if (root.ValueKind != JsonValueKind.Object)
+        {
+            return;
+        }
+
+        fileMap.FromVersion ??= ReadStringIgnoreCase(root, "fromversion");
+        fileMap.ToVersion ??= ReadStringIgnoreCase(root, "toversion");
+        fileMap.Version ??= ReadStringIgnoreCase(root, "version");
+        fileMap.Platform ??= ReadStringIgnoreCase(root, "platform");
+        fileMap.Arch ??= ReadStringIgnoreCase(root, "arch");
+        fileMap.DistributionId ??= ReadStringIgnoreCase(root, "distributionid");
+        PopulateMetadata(root, fileMap.Metadata);
+
+        if (TryGetPropertyIgnoreCase(root, "files", out var rootFilesNode))
+        {
+            ParseFilesNode(rootFilesNode, null, files);
+        }
+
+        if (TryGetPropertyIgnoreCase(root, "components", out var componentsNode))
+        {
+            ParseComponentsNode(componentsNode, files);
+        }
+    }
+
+    public static PlondsUpdateMetadata? LoadMetadata(string path)
+    {
+        if (!File.Exists(path))
+        {
+            return null;
+        }
+
+        try
+        {
+            var text = File.ReadAllText(path);
+            return string.IsNullOrWhiteSpace(text)
+                ? null
+                : JsonSerializer.Deserialize(text, AppJsonContext.Default.PlondsUpdateMetadata);
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    public static string? ResolveSourceVersion(PlondsFileMap fileMap, PlondsUpdateMetadata? metadata)
+    {
+        return FirstNonEmpty(
+            metadata?.FromVersion,
+            fileMap.FromVersion,
+            TryGetMetadataValue(fileMap.Metadata, "fromVersion"),
+            TryGetMetadataValue(fileMap.Metadata, "sourceVersion"));
+    }
+
+    public static string? ResolveTargetVersion(PlondsFileMap fileMap, PlondsUpdateMetadata? metadata)
+    {
+        return FirstNonEmpty(
+            metadata?.ToVersion,
+            fileMap.ToVersion,
+            fileMap.Version,
+            TryGetMetadataValue(fileMap.Metadata, "toVersion"),
+            TryGetMetadataValue(fileMap.Metadata, "targetVersion"));
+    }
+
+    public static bool TryGetExpectedSha512(PlondsFileEntry file, out byte[] expected)
+    {
+        expected = [];
+        if (file.Sha512Bytes is { Length: > 0 })
+        {
+            expected = file.Sha512Bytes;
+            return true;
+        }
+
+        if (file.Hash is not null)
+        {
+            if (file.Hash.Bytes is { Length: > 0 })
+            {
+                expected = file.Hash.Bytes;
+                return true;
+            }
+
+            if ((string.IsNullOrWhiteSpace(file.Hash.Algorithm) ||
+                 file.Hash.Algorithm.Contains("sha512", StringComparison.OrdinalIgnoreCase)) &&
+                UpdateHash.TryParseHashBytes(file.Hash.Value, out expected))
+            {
+                return true;
+            }
+        }
+
+        if (UpdateHash.TryParseHashBytes(file.Sha512, out expected))
+        {
+            return true;
+        }
+
+        return UpdateHash.TryParseHashBytes(file.Sha512Base64, out expected);
+    }
+
+    public static bool TryGetExpectedObjectSha512(PlondsFileEntry file, out byte[] expected)
+    {
+        expected = [];
+        if (file.Hash is null)
+        {
+            return false;
+        }
+
+        if (file.Hash.Bytes is { Length: > 0 })
+        {
+            expected = file.Hash.Bytes;
+            return true;
+        }
+
+        if (!string.IsNullOrWhiteSpace(file.Hash.Algorithm) &&
+            !file.Hash.Algorithm.Contains("sha512", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        return UpdateHash.TryParseHashBytes(file.Hash.Value, out expected);
+    }
+
+    private static void ParseComponentsNode(JsonElement componentsNode, ICollection<PlondsFileEntry> files)
+    {
+        if (componentsNode.ValueKind == JsonValueKind.Object)
+        {
+            foreach (var component in componentsNode.EnumerateObject())
+            {
+                if (component.Value.ValueKind == JsonValueKind.Object &&
+                    TryGetPropertyIgnoreCase(component.Value, "files", out var componentFilesNode))
+                {
+                    ParseFilesNode(componentFilesNode, component.Name, files);
+                }
+            }
+
+            return;
+        }
+
+        if (componentsNode.ValueKind != JsonValueKind.Array)
+        {
+            return;
+        }
+
+        foreach (var component in componentsNode.EnumerateArray())
+        {
+            if (component.ValueKind != JsonValueKind.Object)
+            {
+                continue;
+            }
+
+            var componentName = ReadStringIgnoreCase(component, "name");
+            if (TryGetPropertyIgnoreCase(component, "files", out var componentFilesNode))
+            {
+                ParseFilesNode(componentFilesNode, componentName, files);
+            }
+        }
+    }
+
+    private static void ParseFilesNode(JsonElement filesNode, string? componentName, ICollection<PlondsFileEntry> files)
+    {
+        if (filesNode.ValueKind == JsonValueKind.Object)
+        {
+            foreach (var fileEntry in filesNode.EnumerateObject())
+            {
+                if (fileEntry.Value.ValueKind == JsonValueKind.Object &&
+                    TryCreateFileEntry(fileEntry.Name, componentName, fileEntry.Value, out var parsed))
+                {
+                    files.Add(parsed);
+                }
+            }
+
+            return;
+        }
+
+        if (filesNode.ValueKind != JsonValueKind.Array)
+        {
+            return;
+        }
+
+        foreach (var fileEntry in filesNode.EnumerateArray())
+        {
+            if (fileEntry.ValueKind == JsonValueKind.Object &&
+                TryCreateFileEntry(ReadStringIgnoreCase(fileEntry, "path"), componentName, fileEntry, out var parsed))
+            {
+                files.Add(parsed);
+            }
+        }
+    }
+
+    private static bool TryCreateFileEntry(string? fallbackPath, string? componentName, JsonElement node, out PlondsFileEntry entry)
+    {
+        entry = new PlondsFileEntry();
+        var path = ReadStringIgnoreCase(node, "path");
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            path = fallbackPath;
+        }
+
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            return false;
+        }
+
+        var archiveSha512 = ReadByteArrayIgnoreCase(node, "archivesha512");
+        var archiveSha512Text = ReadStringIgnoreCase(node, "archivesha512");
+        entry = new PlondsFileEntry
+        {
+            Path = path,
+            Action = FirstNonEmpty(ReadStringIgnoreCase(node, "action"), "replace"),
+            Url = ReadStringIgnoreCase(node, "archivedownloadurl") ?? ReadStringIgnoreCase(node, "downloadurl") ?? ReadStringIgnoreCase(node, "url"),
+            ObjectUrl = ReadStringIgnoreCase(node, "objecturl"),
+            ObjectPath = ReadStringIgnoreCase(node, "objectpath") ?? ReadStringIgnoreCase(node, "archivepath"),
+            ObjectKey = ReadStringIgnoreCase(node, "objectkey"),
+            ArchivePath = ReadStringIgnoreCase(node, "archivepath"),
+            Sha256 = ReadStringIgnoreCase(node, "sha256") ?? ReadStringIgnoreCase(node, "filesha256"),
+            Sha512 = ReadStringIgnoreCase(node, "filesha512") ?? ReadStringIgnoreCase(node, "sha512"),
+            Sha512Bytes = ReadByteArrayIgnoreCase(node, "filesha512") ?? ReadByteArrayIgnoreCase(node, "sha512"),
+            Metadata = BuildMetadata(node, componentName)
+        };
+
+        if (archiveSha512 is { Length: > 0 } || !string.IsNullOrWhiteSpace(archiveSha512Text))
+        {
+            entry.Hash = new PlondsHashDescriptor
+            {
+                Algorithm = "sha512",
+                Bytes = archiveSha512,
+                Value = archiveSha512Text ?? (archiveSha512 is { Length: > 0 }
+                    ? Convert.ToHexString(archiveSha512).ToLowerInvariant()
+                    : null)
+            };
+        }
+        else if (TryGetPropertyIgnoreCase(node, "hash", out var hashNode) && hashNode.ValueKind == JsonValueKind.Object)
+        {
+            entry.Hash = new PlondsHashDescriptor
+            {
+                Algorithm = ReadStringIgnoreCase(hashNode, "algorithm"),
+                Value = ReadStringIgnoreCase(hashNode, "value"),
+                Bytes = ReadByteArrayIgnoreCase(hashNode, "bytes")
+            };
+        }
+
+        return true;
+    }
+
+    private static Dictionary<string, string> BuildMetadata(JsonElement node, string? componentName)
+    {
+        var metadata = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        if (!string.IsNullOrWhiteSpace(componentName))
+        {
+            metadata["component"] = componentName;
+        }
+
+        PopulateMetadata(node, metadata);
+        return metadata;
+    }
+
+    private static void PopulateMetadata(JsonElement node, Dictionary<string, string> metadata)
+    {
+        if (!TryGetPropertyIgnoreCase(node, "metadata", out var metadataNode) ||
+            metadataNode.ValueKind != JsonValueKind.Object)
+        {
+            return;
+        }
+
+        foreach (var property in metadataNode.EnumerateObject())
+        {
+            if (property.Value.ValueKind is JsonValueKind.Null or JsonValueKind.Undefined)
+            {
+                continue;
+            }
+
+            var value = property.Value.ValueKind == JsonValueKind.String
+                ? property.Value.GetString()
+                : property.Value.ToString();
+            if (!string.IsNullOrWhiteSpace(value))
+            {
+                metadata[property.Name] = value;
+            }
+        }
+    }
+
+    private static bool TryGetPropertyIgnoreCase(JsonElement node, string propertyName, out JsonElement value)
+    {
+        if (node.ValueKind == JsonValueKind.Object)
+        {
+            foreach (var property in node.EnumerateObject())
+            {
+                if (string.Equals(property.Name, propertyName, StringComparison.OrdinalIgnoreCase))
+                {
+                    value = property.Value;
+                    return true;
+                }
+            }
+        }
+
+        value = default;
+        return false;
+    }
+
+    private static string? ReadStringIgnoreCase(JsonElement node, string propertyName)
+    {
+        if (!TryGetPropertyIgnoreCase(node, propertyName, out var value))
+        {
+            return null;
+        }
+
+        return value.ValueKind == JsonValueKind.String
+            ? value.GetString()
+            : value.ValueKind is JsonValueKind.Undefined or JsonValueKind.Null
+                ? null
+                : value.ToString();
+    }
+
+    private static byte[]? ReadByteArrayIgnoreCase(JsonElement node, string propertyName)
+    {
+        return TryGetPropertyIgnoreCase(node, propertyName, out var value)
+            ? ParseByteArrayValue(value)
+            : null;
+    }
+
+    private static byte[]? ParseByteArrayValue(JsonElement value)
+    {
+        if (value.ValueKind == JsonValueKind.String)
+        {
+            return UpdateHash.TryParseHashBytes(value.GetString(), out var parsed) ? parsed : null;
+        }
+
+        if (value.ValueKind != JsonValueKind.Array)
+        {
+            return null;
+        }
+
+        var bytes = new byte[value.GetArrayLength()];
+        var index = 0;
+        foreach (var element in value.EnumerateArray())
+        {
+            if (!element.TryGetInt32(out var number) || number < byte.MinValue || number > byte.MaxValue)
+            {
+                return null;
+            }
+
+            bytes[index++] = (byte)number;
+        }
+
+        return bytes;
+    }
+
+    private static string? TryGetMetadataValue(Dictionary<string, string>? metadata, string key)
+    {
+        if (metadata is null || metadata.Count == 0)
+        {
+            return null;
+        }
+
+        foreach (var pair in metadata)
+        {
+            if (string.Equals(pair.Key, key, StringComparison.OrdinalIgnoreCase) &&
+                !string.IsNullOrWhiteSpace(pair.Value))
+            {
+                return pair.Value;
+            }
+        }
+
+        return null;
+    }
+
+    private static string? FirstNonEmpty(params string?[] values)
+    {
+        foreach (var value in values)
+        {
+            if (!string.IsNullOrWhiteSpace(value))
+            {
+                return value;
+            }
+        }
+
+        return null;
+    }
+}

LanMountainDesktop.Launcher/Update/PlondsPayloadResolver.cs

@@ -0,0 +1,97 @@
+using System.IO.Compression;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class PlondsPayloadResolver(UpdateEnginePaths paths)
+{
+    public string ResolveObjectPath(PlondsFileEntry file)
+    {
+        var candidates = new List<string>();
+        AddPathCandidates(candidates, file.ObjectPath);
+        AddPathCandidates(candidates, file.ObjectKey);
+        AddPathCandidates(candidates, file.ArchivePath);
+        AddPathCandidates(candidates, file.ObjectUrl);
+        AddPathCandidates(candidates, file.Url);
+
+        if (PlondsManifestParser.TryGetExpectedObjectSha512(file, out var expectedSha512) ||
+            PlondsManifestParser.TryGetExpectedSha512(file, out expectedSha512))
+        {
+            var hashHex = Convert.ToHexString(expectedSha512).ToLowerInvariant();
+            AddPathCandidates(candidates, Path.Combine(UpdateEnginePaths.PlondsObjectsDirectoryName, hashHex));
+            if (hashHex.Length > 2)
+            {
+                AddPathCandidates(candidates, Path.Combine(UpdateEnginePaths.PlondsObjectsDirectoryName, hashHex[..2], hashHex));
+                AddPathCandidates(candidates, Path.Combine(UpdateEnginePaths.PlondsObjectsDirectoryName, hashHex[..2], hashHex[2..]));
+            }
+
+            AddPathCandidates(candidates, Path.Combine(UpdateEnginePaths.PlondsObjectsDirectoryName, $"{hashHex}.gz"));
+        }
+
+        foreach (var relativePath in candidates.Distinct(StringComparer.OrdinalIgnoreCase))
+        {
+            var fullPath = Path.GetFullPath(Path.Combine(paths.IncomingRoot, relativePath));
+            if (!fullPath.StartsWith(Path.GetFullPath(paths.IncomingRoot), StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            if (File.Exists(fullPath))
+            {
+                return fullPath;
+            }
+        }
+
+        throw new FileNotFoundException($"Unable to resolve object payload for '{file.Path}'.");
+    }
+
+    public static byte[]? TryInflateGzip(byte[] payload)
+    {
+        try
+        {
+            using var input = new MemoryStream(payload, writable: false);
+            using var gzip = new GZipStream(input, CompressionMode.Decompress);
+            using var output = new MemoryStream();
+            gzip.CopyTo(output);
+            return output.ToArray();
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    private static void AddPathCandidates(ICollection<string> candidates, string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return;
+        }
+
+        var normalized = value.Trim();
+        if (Uri.TryCreate(normalized, UriKind.Absolute, out var absoluteUri))
+        {
+            normalized = Uri.UnescapeDataString(absoluteUri.AbsolutePath);
+        }
+
+        normalized = normalized.TrimStart('/', '\\');
+        if (string.IsNullOrWhiteSpace(normalized))
+        {
+            return;
+        }
+
+        normalized = normalized.Replace('/', Path.DirectorySeparatorChar).Replace('\\', Path.DirectorySeparatorChar);
+        candidates.Add(normalized);
+
+        if (!normalized.StartsWith($"{UpdateEnginePaths.PlondsObjectsDirectoryName}{Path.DirectorySeparatorChar}", StringComparison.OrdinalIgnoreCase))
+        {
+            candidates.Add(Path.Combine(UpdateEnginePaths.PlondsObjectsDirectoryName, normalized));
+        }
+
+        var fileName = Path.GetFileName(normalized);
+        if (!string.IsNullOrWhiteSpace(fileName))
+        {
+            candidates.Add(Path.Combine(UpdateEnginePaths.PlondsObjectsDirectoryName, fileName));
+        }
+    }
+}

LanMountainDesktop.Launcher/Update/PlondsUpdateApplier.cs

@@ -0,0 +1,374 @@
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+using ContractsUpdate = LanMountainDesktop.Shared.Contracts.Update;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class PlondsUpdateApplier(
+    DeploymentLocator deploymentLocator,
+    UpdateEnginePaths paths,
+    UpdateSignatureVerifier signatureVerifier,
+    IUpdateProgressReporter progressReporter,
+    UpdateSnapshotStore snapshotStore,
+    InstallCheckpointStore checkpointStore,
+    DeploymentActivator deploymentActivator,
+    IncomingArtifactsCleaner incomingCleaner,
+    PlondsPayloadResolver payloadResolver)
+{
+    public async Task<LauncherResult> ApplyAsync()
+    {
+        progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.VerifySignature, "Verifying PLONDS signature...", 0, null, 0, 0));
+        var verifyResult = signatureVerifier.Verify(paths.PlondsFileMapPath, paths.PlondsSignaturePath, UpdateEnginePaths.PlondsSignatureFileName);
+        if (!verifyResult.Success)
+        {
+            progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(false, null, null, verifyResult.Message, false));
+            return UpdateEngineResults.Failed("update.apply", "signature_failed", verifyResult.Message);
+        }
+
+        var fileMapText = await File.ReadAllTextAsync(paths.PlondsFileMapPath).ConfigureAwait(false);
+        var fileMap = JsonSerializer.Deserialize(fileMapText, AppJsonContext.Default.PlondsFileMap) ?? new PlondsFileMap();
+        var fileEntries = PlondsManifestParser.CollectFileEntries(fileMap);
+        if (fileEntries.Count == 0)
+        {
+            PlondsManifestParser.PopulateFromRawJson(fileMapText, fileMap, fileEntries);
+        }
+
+        if (fileEntries.Count == 0)
+        {
+            progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(false, null, null, "No PLONDS file entries were found.", false));
+            return UpdateEngineResults.Failed("update.apply", "invalid_manifest", "No PLONDS file entries were found.");
+        }
+
+        var pdcMetadata = PlondsManifestParser.LoadMetadata(paths.PlondsUpdateMetadataPath);
+        var currentDeployment = deploymentLocator.FindCurrentDeploymentDirectory();
+        var currentVersion = deploymentLocator.GetCurrentVersion();
+        var sourceVersion = string.IsNullOrWhiteSpace(currentVersion) ? "0.0.0" : currentVersion;
+        var expectedSourceVersion = PlondsManifestParser.ResolveSourceVersion(fileMap, pdcMetadata);
+        if (!string.IsNullOrWhiteSpace(expectedSourceVersion) &&
+            !string.Equals(expectedSourceVersion, sourceVersion, StringComparison.OrdinalIgnoreCase))
+        {
+            return UpdateEngineResults.Failed(
+                "update.apply",
+                "version_mismatch",
+                $"PLONDS update requires source version {expectedSourceVersion} but current is {sourceVersion}.");
+        }
+
+        var targetVersion = PlondsManifestParser.ResolveTargetVersion(fileMap, pdcMetadata);
+        if (string.IsNullOrWhiteSpace(targetVersion))
+        {
+            targetVersion = sourceVersion;
+        }
+
+        var isInitialDeployment = string.IsNullOrWhiteSpace(currentDeployment);
+        var existingCheckpoint = checkpointStore.Load();
+        var canResume = existingCheckpoint is not null
+                        && string.Equals(existingCheckpoint.SourceVersion, sourceVersion, StringComparison.OrdinalIgnoreCase)
+                        && string.Equals(existingCheckpoint.TargetVersion, targetVersion, StringComparison.OrdinalIgnoreCase)
+                        && string.Equals(existingCheckpoint.SourceDirectory ?? string.Empty, currentDeployment ?? string.Empty, StringComparison.OrdinalIgnoreCase)
+                        && Directory.Exists(existingCheckpoint.TargetDirectory)
+                        && File.Exists(Path.Combine(existingCheckpoint.TargetDirectory, ".partial"));
+
+        if (existingCheckpoint is not null && !canResume)
+        {
+            return UpdateEngineResults.Failed("update.apply", "resume_state_invalid", "Install checkpoint is stale or invalid. Please cancel and redownload update payload.");
+        }
+
+        var targetDeployment = canResume
+            ? existingCheckpoint!.TargetDirectory
+            : deploymentLocator.BuildNextDeploymentDirectory(targetVersion!);
+        var snapshot = BuildSnapshot(canResume, existingCheckpoint, sourceVersion, targetVersion, currentDeployment, targetDeployment);
+        var snapshotPath = snapshotStore.CreateSnapshotPath(snapshot.SnapshotId);
+        var checkpoint = canResume
+            ? existingCheckpoint!
+            : BuildCheckpoint(snapshot, sourceVersion, targetVersion, currentDeployment, targetDeployment, isInitialDeployment);
+
+        try
+        {
+            snapshotStore.Save(snapshotPath, snapshot);
+            if (!canResume)
+            {
+                if (Directory.Exists(targetDeployment))
+                {
+                    Directory.Delete(targetDeployment, true);
+                }
+
+                progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.CreateTarget, "Creating target deployment...", 20, null, 0, fileEntries.Count));
+                Directory.CreateDirectory(targetDeployment);
+                File.WriteAllText(Path.Combine(targetDeployment, ".partial"), string.Empty);
+            }
+
+            checkpointStore.Save(checkpoint);
+            ApplyFiles(fileEntries, currentDeployment, targetDeployment, checkpoint);
+            VerifyFiles(fileEntries, targetDeployment, checkpoint);
+
+            if (isInitialDeployment)
+            {
+                File.WriteAllText(Path.Combine(targetDeployment, ".current"), string.Empty);
+                var partialMarker = Path.Combine(targetDeployment, ".partial");
+                if (File.Exists(partialMarker))
+                {
+                    File.Delete(partialMarker);
+                }
+            }
+            else
+            {
+                progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.ActivateDeployment, "Activating deployment...", 85, null, fileEntries.Count, fileEntries.Count));
+                deploymentActivator.Activate(currentDeployment!, targetDeployment);
+            }
+
+            snapshot.Status = "applied";
+            snapshotStore.Save(snapshotPath, snapshot);
+            incomingCleaner.Cleanup();
+            deploymentActivator.RetainDeploymentsForRollback();
+
+            progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.Completed, $"Updated to {targetVersion}.", 100, null, fileEntries.Count, fileEntries.Count));
+            progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(true, sourceVersion, targetVersion, null, false));
+
+            return new LauncherResult
+            {
+                Success = true,
+                Stage = "update.apply",
+                Code = "ok",
+                Message = $"Updated to {targetVersion}.",
+                CurrentVersion = sourceVersion,
+                TargetVersion = targetVersion
+            };
+        }
+        catch (Exception ex)
+        {
+            return HandleFailure(ex, isInitialDeployment, targetDeployment, snapshot, snapshotPath, sourceVersion, targetVersion);
+        }
+        finally
+        {
+            checkpointStore.Delete();
+        }
+    }
+
+    private void ApplyFiles(IReadOnlyList<PlondsFileEntry> fileEntries, string? currentDeployment, string targetDeployment, InstallCheckpoint checkpoint)
+    {
+        progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.ApplyFiles, "Applying PLONDS files...", 30, null, checkpoint.AppliedCount, fileEntries.Count));
+        for (var fileIndex = checkpoint.AppliedCount; fileIndex < fileEntries.Count; fileIndex++)
+        {
+            var entry = fileEntries[fileIndex];
+            ApplyFileEntry(entry, currentDeployment, targetDeployment);
+            checkpoint.AppliedCount = fileIndex + 1;
+            checkpointStore.Save(checkpoint);
+            progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.ApplyFiles, "Applying PLONDS files...", 30 + (checkpoint.AppliedCount * 30 / fileEntries.Count), entry.Path, checkpoint.AppliedCount, fileEntries.Count));
+        }
+    }
+
+    private void VerifyFiles(IReadOnlyList<PlondsFileEntry> fileEntries, string targetDeployment, InstallCheckpoint checkpoint)
+    {
+        progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.VerifyHashes, "Verifying PLONDS hashes...", 65, null, checkpoint.VerifiedCount, fileEntries.Count));
+        for (var verifyIndex = checkpoint.VerifiedCount; verifyIndex < fileEntries.Count; verifyIndex++)
+        {
+            var entry = fileEntries[verifyIndex];
+            VerifyFileEntry(entry, targetDeployment);
+            checkpoint.VerifiedCount = verifyIndex + 1;
+            checkpointStore.Save(checkpoint);
+            progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.VerifyHashes, "Verifying PLONDS hashes...", 65 + (checkpoint.VerifiedCount * 15 / fileEntries.Count), entry.Path, checkpoint.VerifiedCount, fileEntries.Count));
+        }
+    }
+
+    private void ApplyFileEntry(PlondsFileEntry file, string? currentDeployment, string targetDeployment)
+    {
+        var normalizedPath = UpdatePathGuard.NormalizeRelativePath(file.Path);
+        var action = string.IsNullOrWhiteSpace(file.Action) ? "replace" : file.Action!;
+        if (string.Equals(action, "delete", StringComparison.OrdinalIgnoreCase))
+        {
+            return;
+        }
+
+        var targetPath = Path.Combine(targetDeployment, normalizedPath);
+        UpdatePathGuard.EnsurePathWithinRoot(targetPath, targetDeployment);
+        var targetDir = Path.GetDirectoryName(targetPath);
+        if (!string.IsNullOrWhiteSpace(targetDir))
+        {
+            Directory.CreateDirectory(targetDir);
+        }
+
+        if (string.Equals(action, "reuse", StringComparison.OrdinalIgnoreCase))
+        {
+            CopyReusedFile(file, currentDeployment, normalizedPath, targetPath);
+            return;
+        }
+
+        var objectPath = payloadResolver.ResolveObjectPath(file);
+        var objectBytes = File.ReadAllBytes(objectPath);
+        var restoredBytes = PlondsPayloadResolver.TryInflateGzip(objectBytes) ?? objectBytes;
+        File.WriteAllBytes(targetPath, restoredBytes);
+        ApplyUnixFileModeIfPresent(targetPath, file);
+    }
+
+    private static void CopyReusedFile(PlondsFileEntry file, string? currentDeployment, string normalizedPath, string targetPath)
+    {
+        if (string.IsNullOrWhiteSpace(currentDeployment))
+        {
+            throw new FileNotFoundException($"Cannot reuse file '{file.Path}' because no source deployment is available.");
+        }
+
+        var sourcePath = Path.Combine(currentDeployment, normalizedPath);
+        UpdatePathGuard.EnsurePathWithinRoot(sourcePath, currentDeployment);
+        if (!File.Exists(sourcePath))
+        {
+            throw new FileNotFoundException($"Cannot reuse file '{file.Path}' because it was not found in current deployment.");
+        }
+
+        File.Copy(sourcePath, targetPath, overwrite: true);
+        ApplyUnixFileModeIfPresent(targetPath, file);
+    }
+
+    private static void VerifyFileEntry(PlondsFileEntry file, string targetDeployment)
+    {
+        var action = string.IsNullOrWhiteSpace(file.Action) ? "replace" : file.Action!;
+        if (string.Equals(action, "delete", StringComparison.OrdinalIgnoreCase))
+        {
+            return;
+        }
+
+        var targetPath = Path.Combine(targetDeployment, UpdatePathGuard.NormalizeRelativePath(file.Path));
+        UpdatePathGuard.EnsurePathWithinRoot(targetPath, targetDeployment);
+        if (!File.Exists(targetPath))
+        {
+            throw new FileNotFoundException($"Expected target file was not created: {file.Path}");
+        }
+
+        if (PlondsManifestParser.TryGetExpectedSha512(file, out var expectedSha512))
+        {
+            var actualSha512 = UpdateHash.ComputeSha512(targetPath);
+            if (!actualSha512.AsSpan().SequenceEqual(expectedSha512))
+            {
+                throw new InvalidOperationException($"SHA-512 mismatch for '{file.Path}'.");
+            }
+
+            return;
+        }
+
+        if (!string.IsNullOrWhiteSpace(file.Sha256))
+        {
+            var expectedSha256 = UpdateHash.NormalizeHashText(file.Sha256);
+            var actualSha256 = UpdateHash.ComputeSha256Hex(targetPath);
+            if (!string.Equals(actualSha256, expectedSha256, StringComparison.OrdinalIgnoreCase))
+            {
+                throw new InvalidOperationException($"SHA-256 mismatch for '{file.Path}'.");
+            }
+        }
+    }
+
+    private LauncherResult HandleFailure(
+        Exception ex,
+        bool isInitialDeployment,
+        string targetDeployment,
+        SnapshotMetadata snapshot,
+        string snapshotPath,
+        string sourceVersion,
+        string targetVersion)
+    {
+        if (isInitialDeployment)
+        {
+            TryDeleteDirectory(targetDeployment);
+            snapshot.Status = "failed";
+            snapshotStore.Save(snapshotPath, snapshot);
+            progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(false, "0.0.0", targetVersion, ex.Message, false));
+            return new LauncherResult
+            {
+                Success = false,
+                Stage = "update.apply",
+                Code = "initial_deploy_failed",
+                Message = "Failed to apply initial PLONDS deployment.",
+                ErrorMessage = ex.Message,
+                CurrentVersion = "0.0.0",
+                TargetVersion = targetVersion
+            };
+        }
+
+        progressReporter.ReportProgress(new ContractsUpdate.InstallProgressReport(ContractsUpdate.InstallStage.RollingBack, "Rolling back...", 0, null, 0, 0));
+        var rollbackResult = deploymentActivator.TryRollbackOnFailure(snapshot);
+        snapshot.Status = rollbackResult.Success ? "rolled_back" : "rollback_failed";
+        snapshotStore.Save(snapshotPath, snapshot);
+        var errorMessage = rollbackResult.Success
+            ? ex.Message
+            : $"{ex.Message}; rollback failed: {rollbackResult.ErrorMessage}";
+        progressReporter.ReportComplete(new ContractsUpdate.InstallCompleteReport(false, sourceVersion, targetVersion, errorMessage, rollbackResult.Success));
+        return new LauncherResult
+        {
+            Success = false,
+            Stage = "update.apply",
+            Code = rollbackResult.Success ? "apply_failed" : "rollback_failed",
+            Message = rollbackResult.Success
+                ? "Failed to apply PLONDS update. Rolled back to previous version."
+                : "Failed to apply PLONDS update and rollback failed.",
+            ErrorMessage = errorMessage,
+            CurrentVersion = sourceVersion,
+            RolledBackTo = rollbackResult.Success ? sourceVersion : null
+        };
+    }
+
+    private static SnapshotMetadata BuildSnapshot(
+        bool canResume,
+        InstallCheckpoint? existingCheckpoint,
+        string sourceVersion,
+        string targetVersion,
+        string? currentDeployment,
+        string targetDeployment) =>
+        new()
+        {
+            SnapshotId = canResume ? existingCheckpoint!.SnapshotId : Guid.NewGuid().ToString("N"),
+            SourceVersion = sourceVersion,
+            TargetVersion = targetVersion,
+            CreatedAt = DateTimeOffset.UtcNow,
+            SourceDirectory = currentDeployment ?? string.Empty,
+            TargetDirectory = targetDeployment,
+            Status = "pending"
+        };
+
+    private static InstallCheckpoint BuildCheckpoint(
+        SnapshotMetadata snapshot,
+        string sourceVersion,
+        string targetVersion,
+        string? currentDeployment,
+        string targetDeployment,
+        bool isInitialDeployment) =>
+        new()
+        {
+            SnapshotId = snapshot.SnapshotId,
+            SourceVersion = sourceVersion,
+            TargetVersion = targetVersion,
+            SourceDirectory = currentDeployment,
+            TargetDirectory = targetDeployment,
+            IsInitialDeployment = isInitialDeployment
+        };
+
+    private static void ApplyUnixFileModeIfPresent(string targetPath, PlondsFileEntry file)
+    {
+        if (OperatingSystem.IsWindows() ||
+            !file.Metadata.TryGetValue("unixFileMode", out var rawMode) ||
+            string.IsNullOrWhiteSpace(rawMode))
+        {
+            return;
+        }
+
+        try
+        {
+            var modeValue = Convert.ToInt32(rawMode.Trim(), 8);
+            File.SetUnixFileMode(targetPath, (UnixFileMode)modeValue);
+        }
+        catch
+        {
+        }
+    }
+
+    private static void TryDeleteDirectory(string path)
+    {
+        try
+        {
+            if (Directory.Exists(path))
+            {
+                Directory.Delete(path, true);
+            }
+        }
+        catch
+        {
+        }
+    }
+}

LanMountainDesktop.Launcher/Update/RollbackStrategy.cs

@@ -0,0 +1,48 @@
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class RollbackStrategy(
+    DeploymentLocator deploymentLocator,
+    UpdateSnapshotStore snapshotStore,
+    DeploymentActivator deploymentActivator)
+{
+    public LauncherResult RollbackLatest()
+    {
+        var latest = snapshotStore.LoadLatest();
+        if (latest is null)
+        {
+            return UpdateEngineResults.Failed("update.rollback", "no_snapshot", "No snapshot found.");
+        }
+
+        var (snapshotPath, snapshot) = latest.Value;
+        if (string.IsNullOrWhiteSpace(snapshot.SourceDirectory))
+        {
+            return UpdateEngineResults.Failed("update.rollback", "invalid_snapshot", "Invalid snapshot metadata.");
+        }
+
+        if (!Directory.Exists(snapshot.SourceDirectory))
+        {
+            return UpdateEngineResults.Failed("update.rollback", "source_missing", $"Rollback source deployment is missing: {snapshot.SourceDirectory}");
+        }
+
+        var currentDeployment = deploymentLocator.FindCurrentDeploymentDirectory();
+        if (string.IsNullOrWhiteSpace(currentDeployment))
+        {
+            return UpdateEngineResults.Failed("update.rollback", "no_current_deployment", "Current deployment not found.");
+        }
+
+        deploymentActivator.Activate(currentDeployment, snapshot.SourceDirectory);
+        snapshot.Status = "manual_rollback";
+        snapshotStore.Save(snapshotPath, snapshot);
+
+        return new LauncherResult
+        {
+            Success = true,
+            Stage = "update.rollback",
+            Code = "ok",
+            Message = $"Rolled back to {snapshot.SourceVersion}.",
+            RolledBackTo = snapshot.SourceVersion
+        };
+    }
+}

LanMountainDesktop.Launcher/Update/UpdateEngineFacade.cs

@@ -0,0 +1,119 @@
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class UpdateEngineFacade : IUpdateEngine
+{
+    private readonly UpdateEnginePaths _paths;
+    private readonly PendingUpdateDetector _pendingUpdateDetector;
+    private readonly LegacyUpdateApplier _legacyUpdateApplier;
+    private readonly PlondsUpdateApplier _plondsUpdateApplier;
+    private readonly RollbackStrategy _rollbackStrategy;
+    private readonly DeploymentActivator _deploymentActivator;
+    private readonly IncomingArtifactsCleaner _incomingArtifactsCleaner;
+
+    public UpdateEngineFacade(DeploymentLocator deploymentLocator, IUpdateProgressReporter? progressReporter = null)
+    {
+        var reporter = progressReporter ?? new NullUpdateProgressReporter();
+        _paths = new UpdateEnginePaths(deploymentLocator.GetAppRoot());
+        var signatureVerifier = new UpdateSignatureVerifier(_paths);
+        var snapshotStore = new UpdateSnapshotStore(_paths);
+        var checkpointStore = new InstallCheckpointStore(_paths);
+        _deploymentActivator = new DeploymentActivator(deploymentLocator);
+        _incomingArtifactsCleaner = new IncomingArtifactsCleaner(_paths);
+        _pendingUpdateDetector = new PendingUpdateDetector(deploymentLocator, _paths, signatureVerifier);
+        _legacyUpdateApplier = new LegacyUpdateApplier(
+            deploymentLocator,
+            _paths,
+            signatureVerifier,
+            reporter,
+            snapshotStore,
+            checkpointStore,
+            _deploymentActivator,
+            _incomingArtifactsCleaner);
+        _plondsUpdateApplier = new PlondsUpdateApplier(
+            deploymentLocator,
+            _paths,
+            signatureVerifier,
+            reporter,
+            snapshotStore,
+            checkpointStore,
+            _deploymentActivator,
+            _incomingArtifactsCleaner,
+            new PlondsPayloadResolver(_paths));
+        _rollbackStrategy = new RollbackStrategy(deploymentLocator, snapshotStore, _deploymentActivator);
+    }
+
+    public LauncherResult CheckPendingUpdate() => _pendingUpdateDetector.CheckPendingUpdate();
+
+    public Task<LauncherResult> DownloadAsync(string manifestUrl, string signatureUrl, string archiveUrl, CancellationToken cancellationToken)
+    {
+        _ = manifestUrl;
+        _ = signatureUrl;
+        _ = archiveUrl;
+        _ = cancellationToken;
+
+        return Task.FromResult(new LauncherResult
+        {
+            Success = false,
+            Stage = "update.download",
+            Code = "host_managed_only",
+            Message = "Launcher no longer performs network downloads. Host must download update payload into incoming directory first."
+        });
+    }
+
+    public async Task<LauncherResult> ApplyPendingUpdateAsync()
+    {
+        Directory.CreateDirectory(_paths.IncomingRoot);
+        Directory.CreateDirectory(_paths.SnapshotsRoot);
+
+        var stateValidation = _pendingUpdateDetector.ValidateIncomingState();
+        if (!stateValidation.Success || stateValidation.Code == "noop")
+        {
+            return stateValidation;
+        }
+
+        try
+        {
+            File.WriteAllText(_paths.ApplyLockPath, DateTimeOffset.UtcNow.ToString("O"));
+        }
+        catch (Exception ex)
+        {
+            return UpdateEngineResults.Failed("update.apply", "lock_conflict", $"Failed to acquire apply lock: {ex.Message}");
+        }
+
+        try
+        {
+            if (_paths.HasPlondsPayload)
+            {
+                return await _plondsUpdateApplier.ApplyAsync().ConfigureAwait(false);
+            }
+
+            return await _legacyUpdateApplier.ApplyAsync().ConfigureAwait(false);
+        }
+        finally
+        {
+            TryDeleteApplyLock();
+        }
+    }
+
+    public LauncherResult RollbackLatest() => _rollbackStrategy.RollbackLatest();
+
+    public void CleanupDestroyedDeployments() => _deploymentActivator.RetainDeploymentsForRollback();
+
+    public void CleanupIncomingArtifacts() => _incomingArtifactsCleaner.Cleanup();
+
+    private void TryDeleteApplyLock()
+    {
+        try
+        {
+            if (File.Exists(_paths.ApplyLockPath))
+            {
+                File.Delete(_paths.ApplyLockPath);
+            }
+        }
+        catch
+        {
+        }
+    }
+}

LanMountainDesktop.Launcher/Update/UpdateEngineFactory.cs

@@ -0,0 +1,7 @@
+namespace LanMountainDesktop.Launcher.Update;
+
+internal static class UpdateEngineFactory
+{
+    public static IUpdateEngine Create(DeploymentLocator deploymentLocator, IUpdateProgressReporter? progressReporter = null) =>
+        new UpdateEngineFacade(deploymentLocator, progressReporter);
+}

LanMountainDesktop.Launcher/Update/UpdateEnginePaths.cs

@@ -0,0 +1,68 @@
+using ContractsUpdate = LanMountainDesktop.Shared.Contracts.Update;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class UpdateEnginePaths
+{
+    public const string UpdateDirectoryName = "update";
+    public const string IncomingDirectoryName = "incoming";
+    public const string SnapshotsDirectoryName = "snapshots";
+    public const string SignedFileMapName = "files.json";
+    public const string SignatureFileName = "files.json.sig";
+    public const string ArchiveFileName = "update.zip";
+    public const string PlondsFileMapName = "plonds-filemap.json";
+    public const string PlondsSignatureFileName = "plonds-filemap.sig";
+    public const string PlondsUpdateMetadataName = "plonds-update.json";
+    public const string PlondsObjectsDirectoryName = "objects";
+    public const string PublicKeyFileName = "public-key.pem";
+
+    public UpdateEnginePaths(string appRoot)
+    {
+        AppRoot = appRoot;
+        var resolver = new DataLocationResolver(appRoot);
+        LauncherRoot = resolver.ResolveLauncherDataPath();
+        IncomingRoot = Path.Combine(LauncherRoot, UpdateDirectoryName, IncomingDirectoryName);
+        SnapshotsRoot = Path.Combine(LauncherRoot, SnapshotsDirectoryName);
+        InstallCheckpointPath = ContractsUpdate.UpdatePaths.GetInstallCheckpointPath(appRoot);
+    }
+
+    public string AppRoot { get; }
+
+    public string LauncherRoot { get; }
+
+    public string IncomingRoot { get; }
+
+    public string SnapshotsRoot { get; }
+
+    public string InstallCheckpointPath { get; }
+
+    public string ApplyLockPath => ContractsUpdate.UpdatePaths.GetApplyInProgressLockPath(AppRoot);
+
+    public string DeploymentLockPath => ContractsUpdate.UpdatePaths.GetDeploymentLockPath(AppRoot);
+
+    public string DownloadMarkerPath => ContractsUpdate.UpdatePaths.GetDownloadMarkerPath(AppRoot);
+
+    public string FileMapPath => Path.Combine(IncomingRoot, SignedFileMapName);
+
+    public string SignaturePath => Path.Combine(IncomingRoot, SignatureFileName);
+
+    public string ArchivePath => Path.Combine(IncomingRoot, ArchiveFileName);
+
+    public string PlondsFileMapPath => Path.Combine(IncomingRoot, PlondsFileMapName);
+
+    public string PlondsSignaturePath => Path.Combine(IncomingRoot, PlondsSignatureFileName);
+
+    public string PlondsUpdateMetadataPath => Path.Combine(IncomingRoot, PlondsUpdateMetadataName);
+
+    public string PlondsObjectsRoot => Path.Combine(IncomingRoot, PlondsObjectsDirectoryName);
+
+    public string PublicKeyPath => Path.Combine(LauncherRoot, UpdateDirectoryName, PublicKeyFileName);
+
+    public string ExtractRoot => Path.Combine(IncomingRoot, "extracted");
+
+    public bool HasPlondsPayload => File.Exists(PlondsFileMapPath) && File.Exists(PlondsSignaturePath);
+
+    public bool HasLegacyPayload => File.Exists(FileMapPath) && File.Exists(ArchivePath);
+
+    public string GetSnapshotPath(string snapshotId) => Path.Combine(SnapshotsRoot, $"{snapshotId}.json");
+}

LanMountainDesktop.Launcher/Update/UpdateEngineResults.cs

@@ -0,0 +1,18 @@
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal static class UpdateEngineResults
+{
+    public static LauncherResult Failed(string stage, string code, string message)
+    {
+        return new LauncherResult
+        {
+            Success = false,
+            Stage = stage,
+            Code = code,
+            Message = message,
+            ErrorMessage = message
+        };
+    }
+}

LanMountainDesktop.Launcher/Update/UpdateHash.cs

@@ -0,0 +1,84 @@
+using System.Security.Cryptography;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal static class UpdateHash
+{
+    public static string ComputeSha256Hex(string filePath)
+    {
+        using var stream = File.OpenRead(filePath);
+        var hash = SHA256.HashData(stream);
+        return Convert.ToHexString(hash).ToLowerInvariant();
+    }
+
+    public static byte[] ComputeSha512(string filePath)
+    {
+        using var stream = File.OpenRead(filePath);
+        return SHA512.HashData(stream);
+    }
+
+    public static bool TryParseHashBytes(string? rawHash, out byte[] bytes)
+    {
+        bytes = [];
+        if (string.IsNullOrWhiteSpace(rawHash))
+        {
+            return false;
+        }
+
+        var normalized = rawHash.Trim();
+        var separator = normalized.IndexOf(':');
+        if (separator >= 0 && separator < normalized.Length - 1)
+        {
+            normalized = normalized[(separator + 1)..].Trim();
+        }
+
+        var compact = normalized.Replace("-", string.Empty);
+        if (compact.Length > 0 && compact.Length % 2 == 0 && IsHexString(compact))
+        {
+            try
+            {
+                bytes = Convert.FromHexString(compact);
+                return true;
+            }
+            catch
+            {
+                return false;
+            }
+        }
+
+        try
+        {
+            bytes = Convert.FromBase64String(normalized);
+            return bytes.Length > 0;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    public static string NormalizeHashText(string hash)
+    {
+        var normalized = hash.Trim();
+        var separator = normalized.IndexOf(':');
+        if (separator >= 0 && separator < normalized.Length - 1)
+        {
+            normalized = normalized[(separator + 1)..];
+        }
+
+        return normalized.Replace("-", string.Empty).Trim().ToLowerInvariant();
+    }
+
+    private static bool IsHexString(string value)
+    {
+        foreach (var ch in value)
+        {
+            if (!Uri.IsHexDigit(ch))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

LanMountainDesktop.Launcher/Update/UpdatePathGuard.cs

@@ -0,0 +1,20 @@
+namespace LanMountainDesktop.Launcher.Update;
+
+internal static class UpdatePathGuard
+{
+    public static string NormalizeRelativePath(string path)
+    {
+        var normalized = path.Replace('\\', Path.DirectorySeparatorChar).Replace('/', Path.DirectorySeparatorChar);
+        return normalized.TrimStart(Path.DirectorySeparatorChar);
+    }
+
+    public static void EnsurePathWithinRoot(string targetPath, string rootPath)
+    {
+        var fullTarget = Path.GetFullPath(targetPath);
+        var fullRoot = Path.GetFullPath(rootPath);
+        if (!fullTarget.StartsWith(fullRoot, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new InvalidOperationException($"Path traversal detected: {targetPath}");
+        }
+    }
+}

LanMountainDesktop.Launcher/Update/UpdateSignatureVerifier.cs

@@ -0,0 +1,41 @@
+using System.Security.Cryptography;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class UpdateSignatureVerifier(UpdateEnginePaths paths)
+{
+    public (bool Success, string Message) Verify(string payloadPath, string signaturePath, string signatureName)
+    {
+        if (!File.Exists(signaturePath))
+        {
+            return (false, $"Missing {signatureName}.");
+        }
+
+        if (!File.Exists(paths.PublicKeyPath))
+        {
+            return (false, $"Missing public key: {paths.PublicKeyPath}");
+        }
+
+        var payloadBytes = File.ReadAllBytes(payloadPath);
+        var signatureBase64 = File.ReadAllText(signaturePath).Trim();
+        if (string.IsNullOrWhiteSpace(signatureBase64))
+        {
+            return (false, "Signature is empty.");
+        }
+
+        byte[] signature;
+        try
+        {
+            signature = Convert.FromBase64String(signatureBase64);
+        }
+        catch (FormatException)
+        {
+            return (false, "Signature is not valid base64.");
+        }
+
+        using var rsa = RSA.Create();
+        rsa.ImportFromPem(File.ReadAllText(paths.PublicKeyPath));
+        var isValid = rsa.VerifyData(payloadBytes, signature, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
+        return isValid ? (true, "ok") : (false, "Signature verification failed.");
+    }
+}

LanMountainDesktop.Launcher/Update/UpdateSnapshotStore.cs

@@ -0,0 +1,34 @@
+using System.Text.Json;
+using LanMountainDesktop.Launcher.Models;
+
+namespace LanMountainDesktop.Launcher.Update;
+
+internal sealed class UpdateSnapshotStore(UpdateEnginePaths paths)
+{
+    public string CreateSnapshotPath(string snapshotId) => paths.GetSnapshotPath(snapshotId);
+
+    public void Save(string path, SnapshotMetadata snapshot)
+    {
+        File.WriteAllText(path, JsonSerializer.Serialize(snapshot, AppJsonContext.Default.SnapshotMetadata));
+    }
+
+    public (string Path, SnapshotMetadata Snapshot)? LoadLatest()
+    {
+        if (!Directory.Exists(paths.SnapshotsRoot))
+        {
+            return null;
+        }
+
+        var snapshotPath = Directory
+            .EnumerateFiles(paths.SnapshotsRoot, "*.json", SearchOption.TopDirectoryOnly)
+            .OrderByDescending(File.GetCreationTimeUtc)
+            .FirstOrDefault();
+        if (string.IsNullOrWhiteSpace(snapshotPath))
+        {
+            return null;
+        }
+
+        var snapshot = JsonSerializer.Deserialize(File.ReadAllText(snapshotPath), AppJsonContext.Default.SnapshotMetadata);
+        return snapshot is null ? null : (snapshotPath, snapshot);
+    }
+}

LanMountainDesktop.Launcher/Views/DataLocationPromptWindow.axaml.cs

@@ -8,7 +8,7 @@ using Avalonia.Media;
 using Avalonia.Styling;
 using LanMountainDesktop.Launcher.Models;
 using LanMountainDesktop.Launcher.Resources;
-using LanMountainDesktop.Launcher.Services;
+using LanMountainDesktop.Launcher.Infrastructure;
 
 namespace LanMountainDesktop.Launcher.Views;
 

LanMountainDesktop.Launcher/Views/DevDebugWindow.axaml.cs

@@ -1,7 +1,7 @@
 using Avalonia.Controls;
 using Avalonia.Markup.Xaml;
 using LanMountainDesktop.Launcher.Resources;
-using LanMountainDesktop.Launcher.Services;
+using LanMountainDesktop.Launcher.Infrastructure;
 using LanMountainDesktop.Launcher.ViewModels;
 using LanMountainDesktop.Launcher.Views;
 

LanMountainDesktop.Launcher/Views/ErrorWindow.axaml.cs

@@ -6,7 +6,7 @@ using Avalonia.Interactivity;
 using Avalonia.Markup.Xaml;
 using FluentAvalonia.UI.Controls;
 using LanMountainDesktop.Launcher.Resources;
-using LanMountainDesktop.Launcher.Services;
+using LanMountainDesktop.Launcher.Infrastructure;
 
 namespace LanMountainDesktop.Launcher.Views;
 

LanMountainDesktop.Launcher/Views/LoadingDetailsWindow.axaml.cs

@@ -4,7 +4,7 @@ using Avalonia.Markup.Xaml;
 using Avalonia.Media;
 using Avalonia.Threading;
 using LanMountainDesktop.Launcher.Resources;
-using LanMountainDesktop.Launcher.Services;
+using LanMountainDesktop.Launcher.Infrastructure;
 using LanMountainDesktop.Shared.Contracts.Launcher;
 using System.Collections.ObjectModel;
 using System.ComponentModel;