From a4b626aedef2a0cf690a955bf4abd31c5284047a Mon Sep 17 00:00:00 2001
From: Tam Nhu Tran <kaitran.ntt@gmail.com>
Date: Sat, 7 Mar 2026 10:52:46 +0700
Subject: [PATCH] fix: clarify CLIProxy dashboard install lifecycle

---
 .../cliproxy-dashboard-install-service.ts     |  2 ++
 ...cliproxy-dashboard-install-service.test.ts | 20 +++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/src/web-server/services/cliproxy-dashboard-install-service.ts b/src/web-server/services/cliproxy-dashboard-install-service.ts
index cb96487d..60f99a60 100644
--- a/src/web-server/services/cliproxy-dashboard-install-service.ts
+++ b/src/web-server/services/cliproxy-dashboard-install-service.ts
@@ -51,6 +51,8 @@ export async function installDashboardCliproxyVersion(
   const backendLabel = backend === 'plus' ? 'CLIProxy Plus' : 'CLIProxy';
   const shouldRestoreService = await wasProxyRunning(deps);
 
+  // The installer owns the stop-and-replace lifecycle: it stops a running proxy
+  // and waits for the port to free before swapping the binary.
   await deps.installCliproxyVersion(version, true, backend);
 
   if (!shouldRestoreService) {
diff --git a/tests/unit/web-server/cliproxy-dashboard-install-service.test.ts b/tests/unit/web-server/cliproxy-dashboard-install-service.test.ts
index 9af88014..6522dd58 100644
--- a/tests/unit/web-server/cliproxy-dashboard-install-service.test.ts
+++ b/tests/unit/web-server/cliproxy-dashboard-install-service.test.ts
@@ -102,4 +102,24 @@ describe('installDashboardCliproxyVersion', () => {
     expect(calls.installCliproxyVersion).toBe(1);
     expect(calls.ensureCliproxyService).toBe(1);
   });
+
+  it('uses a fallback restart error when the start result omits one', async () => {
+    const { deps } = createDeps({
+      remoteRunning: true,
+      startResult: {
+        started: false,
+        alreadyRunning: false,
+        port: 8317,
+      },
+    });
+
+    const result = await installDashboardCliproxyVersion('6.7.1', 'plus', deps);
+
+    expect(result).toEqual<DashboardCliproxyInstallResult>({
+      success: false,
+      restarted: false,
+      error: 'Installed CLIProxy Plus v6.7.1, but restart failed',
+      message: 'Installed CLIProxy Plus v6.7.1, but failed to restart it',
+    });
+  });
 });