From 19864b3f8562eaa95ea75ec093fe301cfe49e81e Mon Sep 17 00:00:00 2001
From: Weilong Liao <37870767+Soulter@users.noreply.github.com>
Date: Wed, 17 Jun 2026 22:48:47 +0800
Subject: [PATCH] fix: recover interrupted dashboard upgrades

---
 astrbot/dashboard/services/update_service.py  |  51 +++-
 dashboard/src/App.vue                         |   2 +
 dashboard/src/api/v1.ts                       | 116 ++++++++--
 .../shared/UpgradeRecoveryDialog.vue          | 217 ++++++++++++++++++
 .../src/i18n/locales/en-US/core/common.json   |  10 +
 .../src/i18n/locales/ru-RU/core/common.json   |  12 +-
 .../src/i18n/locales/zh-CN/core/common.json   |  10 +
 .../full/vertical-header/VerticalHeader.vue   |  21 +-
 tests/test_dashboard.py                       |  66 ++++--
 9 files changed, 457 insertions(+), 48 deletions(-)
 create mode 100644 dashboard/src/components/shared/UpgradeRecoveryDialog.vue

diff --git a/astrbot/dashboard/services/update_service.py b/astrbot/dashboard/services/update_service.py
index 07a7e5c54..388812e70 100644
--- a/astrbot/dashboard/services/update_service.py
+++ b/astrbot/dashboard/services/update_service.py
@@ -92,6 +92,7 @@ class UpdateService:
         self.demo_mode = demo_mode
         self.clear_site_data_headers = clear_site_data_headers
         self.update_progress: dict[str, dict] = {}
+        self._update_tasks: dict[str, asyncio.Task] = {}
 
     def get_update_progress(self, progress_id: str) -> UpdateServiceResult:
         if not progress_id:
@@ -156,7 +157,43 @@ class UpdateService:
         if proxy:
             proxy = proxy.removesuffix("/")
 
+        existing_task = self._update_tasks.get(progress_id)
+        if existing_task and not existing_task.done():
+            return UpdateServiceResult(
+                data={"id": progress_id, "status": "running"},
+                message="更新任务正在进行中。",
+                headers=self.clear_site_data_headers,
+            )
+
         self._init_update_progress(progress_id, version)
+        task = asyncio.create_task(
+            self._run_update_project(progress_id, version, latest, reboot, proxy)
+        )
+        self._update_tasks[progress_id] = task
+        task.add_done_callback(lambda _task: self._update_tasks.pop(progress_id, None))
+        return UpdateServiceResult(
+            data={"id": progress_id, "status": "running"},
+            message="更新任务已开始。",
+            headers=self.clear_site_data_headers,
+        )
+
+    async def _run_update_project(
+        self,
+        progress_id: str,
+        version: str,
+        latest: bool,
+        reboot: bool,
+        proxy: str | None,
+    ) -> None:
+        """Run the long core update outside the request lifecycle.
+
+        Args:
+            progress_id: Progress record id reported to the frontend.
+            version: Target version without the latest sentinel.
+            latest: Whether to install the latest release.
+            reboot: Whether to restart AstrBot after applying files.
+            proxy: Optional GitHub proxy URL.
+        """
         update_temp_dir = Path(get_astrbot_system_tmp_path()) / "updates"
         update_temp_dir.mkdir(parents=True, exist_ok=True)
         update_token = uuid.uuid4().hex
@@ -308,10 +345,16 @@ class UpdateService:
                     "overall_percent": 100,
                 },
             )
-            return UpdateServiceResult(
-                message=message,
-                headers=self.clear_site_data_headers,
+            logger.info(message)
+        except asyncio.CancelledError:
+            self.update_progress[progress_id].update(
+                {
+                    "status": "error",
+                    "message": "更新任务已取消。",
+                },
             )
+            logger.warning(f"Update task was cancelled: {progress_id}")
+            raise
         except Exception as exc:
             self.update_progress[progress_id].update(
                 {
@@ -320,7 +363,7 @@ class UpdateService:
                 },
             )
             logger.error(f"/api/update_project: {traceback.format_exc()}")
-            raise UpdateServiceError(exc.__str__()) from exc
+            logger.debug(f"Update task failed: {exc!s}")
         finally:
             for zip_path in (dashboard_zip_path, core_zip_path):
                 try:
diff --git a/dashboard/src/App.vue b/dashboard/src/App.vue
index af23e75ff..6ce7b460a 100644
--- a/dashboard/src/App.vue
+++ b/dashboard/src/App.vue
@@ -1,6 +1,7 @@
 <template>
   <RouterView></RouterView>
   <WaitingForRestart ref="globalWaitingRef" />
+  <UpgradeRecoveryDialog />
 
   <!-- 全局唯一 snackbar -->
   <v-snackbar v-if="toastStore.current" v-model="snackbarShow" :color="toastStore.current.color"
@@ -18,6 +19,7 @@ import { RouterView } from 'vue-router';
 import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
 import { useToastStore } from '@/stores/toast'
 import WaitingForRestart from '@/components/shared/WaitingForRestart.vue'
+import UpgradeRecoveryDialog from '@/components/shared/UpgradeRecoveryDialog.vue'
 
 const toastStore = useToastStore()
 const globalWaitingRef = ref(null)
diff --git a/dashboard/src/api/v1.ts b/dashboard/src/api/v1.ts
index 664b93d1c..29d244d38 100644
--- a/dashboard/src/api/v1.ts
+++ b/dashboard/src/api/v1.ts
@@ -102,6 +102,10 @@ export interface VersionData {
   [key: string]: unknown;
 }
 
+type StartTimeData = {
+  start_time?: number | string | null;
+};
+
 export interface CommandListData {
   items?: any[];
   wake_prefix?: string[];
@@ -176,6 +180,53 @@ function typed<T>(response: Promise<unknown>): V1Response<T> {
   return response as unknown as V1Response<T>;
 }
 
+function isLegacyFallbackError(error: unknown): boolean {
+  const axiosError = error as {
+    response?: { status?: number; data?: { message?: string } | string };
+    message?: string;
+  };
+  if (axiosError.response?.status === 404) {
+    return true;
+  }
+
+  const data = axiosError.response?.data;
+  const message =
+    typeof data === 'string' ? data : data?.message || axiosError.message || '';
+  return message.toLowerCase().includes('missing api key');
+}
+
+function withLegacyFallback<T>(
+  primary: Promise<unknown>,
+  legacy: () => Promise<AxiosResponse<ApiEnvelope<T>>>,
+): V1Response<T> {
+  return typed<T>(primary).catch((error) => {
+    if (isLegacyFallbackError(error)) {
+      return legacy();
+    }
+    throw error;
+  });
+}
+
+function firstSuccessfulResponse<T>(
+  requests: Array<Promise<AxiosResponse<ApiEnvelope<T>>>>,
+): V1Response<T> {
+  return new Promise<AxiosResponse<ApiEnvelope<T>>>((resolve, reject) => {
+    let pending = requests.length;
+    let firstError: unknown;
+    requests.forEach((request) => {
+      request.then(resolve).catch((error) => {
+        if (firstError === undefined) {
+          firstError = error;
+        }
+        pending -= 1;
+        if (pending === 0) {
+          reject(firstError);
+        }
+      });
+    });
+  });
+}
+
 function generatedOptions(
   options: Record<string, unknown>,
   requestConfig?: AxiosRequestConfig,
@@ -505,27 +556,25 @@ export const providerApi = {
 
 export const authApi = {
   login(payload: LoginRequest) {
-    return typed<any>(openApiV1.login({ body: payload }));
+    return httpClient.post<ApiEnvelope<any>>('/api/auth/login', payload);
   },
   logout() {
-    return typed<OpenConfig>(openApiV1.logout());
+    return httpClient.post<ApiEnvelope<OpenConfig>>('/api/auth/logout');
   },
   setupStatus() {
-    return typed<any>(openApiV1.getAuthSetupStatus());
+    return httpClient.get<ApiEnvelope<any>>('/api/auth/setup-status');
   },
   setup(payload: SetupAuthRequest) {
-    return typed<OpenConfig>(openApiV1.setupAuth({ body: payload }));
+    return httpClient.post<ApiEnvelope<OpenConfig>>('/api/auth/setup', payload);
   },
   setupTotp(payload?: TotpSetupRequest) {
-    return typed<any>(openApiV1.setupTotp({ body: payload }));
+    return httpClient.post<ApiEnvelope<any>>('/api/auth/totp/setup', payload);
   },
   recoverTotp() {
-    return typed<any>(openApiV1.recoverTotp());
+    return httpClient.post<ApiEnvelope<any>>('/api/auth/totp/recovery');
   },
   updateAccount(payload: UpdateAccountRequest) {
-    return typed<OpenConfig>(
-      openApiV1.updateAuthAccount({ body: payload }),
-    );
+    return httpClient.post<ApiEnvelope<OpenConfig>>('/api/auth/account/edit', payload);
   },
 };
 
@@ -561,31 +610,45 @@ export const traceApi = {
 
 export const updatesApi = {
   check() {
-    return typed<any>(openApiV1.checkUpdate());
+    return withLegacyFallback<any>(openApiV1.checkUpdate(), () =>
+      httpClient.get<ApiEnvelope<any>>('/api/update/check'),
+    );
   },
   releases(type?: 'core' | 'dashboard') {
-    return typed<any[]>(
+    return withLegacyFallback<any[]>(
       openApiV1.listReleases({
         query: type ? { type } : undefined,
       }),
+      () =>
+        httpClient.get<ApiEnvelope<any[]>>('/api/update/releases', {
+          params: type ? { type } : undefined,
+        }),
     );
   },
   core(payload?: UpdateRequest) {
-    return typed<OpenConfig>(openApiV1.updateCore({ body: payload }));
+    return withLegacyFallback<OpenConfig>(openApiV1.updateCore({ body: payload }), () =>
+      httpClient.post<ApiEnvelope<OpenConfig>>('/api/update/do', payload),
+    );
   },
   dashboard(payload?: UpdateRequest) {
-    return typed<OpenConfig>(
+    return withLegacyFallback<OpenConfig>(
       openApiV1.updateDashboard({ body: payload }),
+      () => httpClient.post<ApiEnvelope<OpenConfig>>('/api/update/dashboard', payload),
     );
   },
   progress(taskId: string) {
-    return typed<any>(
+    return withLegacyFallback<any>(
       openApiV1.getUpdateProgress({ path: { task_id: taskId } }),
+      () =>
+        httpClient.get<ApiEnvelope<any>>('/api/update/progress', {
+          params: { id: taskId },
+        }),
     );
   },
   installPip(payload: PipInstallRequest) {
-    return typed<OpenConfig>(
+    return withLegacyFallback<OpenConfig>(
       openApiV1.installPipPackage({ body: payload }),
+      () => httpClient.post<ApiEnvelope<OpenConfig>>('/api/update/pip-install', payload),
     );
   },
 };
@@ -1575,7 +1638,9 @@ export const statsApi = {
     );
   },
   version() {
-    return typed<VersionData>(openApiV1.getVersion());
+    return withLegacyFallback<VersionData>(openApiV1.getVersion(), () =>
+      httpClient.get<ApiEnvelope<VersionData>>('/api/stat/version'),
+    );
   },
   firstNotice(locale?: string) {
     return typed<{ content?: string | null }>(
@@ -1585,15 +1650,28 @@ export const statsApi = {
     );
   },
   testGhproxy(payload: GhproxyTestRequest) {
-    return typed<{ latency?: number }>(
+    return withLegacyFallback<{ latency?: number }>(
       openApiV1.testGhproxyConnection({ body: payload }),
+      () =>
+        httpClient.post<ApiEnvelope<{ latency?: number }>>(
+          '/api/stat/test-ghproxy-connection',
+          payload,
+        ),
     );
   },
   startTime() {
-    return typed<{ start_time?: number | string | null }>(openApiV1.getStartTime());
+    const v1Request = typed<StartTimeData>(openApiV1.getStartTime());
+    const legacyRequest = httpClient.get<ApiEnvelope<StartTimeData>>(
+      '/api/stat/start-time',
+    );
+
+    // Restart polling must also work after downgrading to backends without v1 stats routes.
+    return firstSuccessfulResponse<StartTimeData>([v1Request, legacyRequest]);
   },
   restart() {
-    return typed<OpenConfig>(openApiV1.restartCore());
+    return withLegacyFallback<OpenConfig>(openApiV1.restartCore(), () =>
+      httpClient.post<ApiEnvelope<OpenConfig>>('/api/stat/restart-core'),
+    );
   },
   storage() {
     return typed<OpenConfig>(openApiV1.getStorageStatus());
diff --git a/dashboard/src/components/shared/UpgradeRecoveryDialog.vue b/dashboard/src/components/shared/UpgradeRecoveryDialog.vue
new file mode 100644
index 000000000..5a1b65f6b
--- /dev/null
+++ b/dashboard/src/components/shared/UpgradeRecoveryDialog.vue
@@ -0,0 +1,217 @@
+<template>
+  <v-dialog v-model="visible" max-width="520">
+    <v-card>
+      <v-card-title class="upgrade-recovery-title">
+        <span>{{ t('core.common.upgradeRecovery.title') }}</span>
+      </v-card-title>
+
+      <v-card-text>
+        <p class="mb-3">
+          {{
+            t('core.common.upgradeRecovery.description', {
+              coreVersion,
+              dashboardVersion,
+            })
+          }}
+        </p>
+        <v-alert type="warning" variant="tonal" density="comfortable" class="mb-3">
+          {{ t('core.common.upgradeRecovery.hint') }}
+        </v-alert>
+        <v-progress-linear
+          v-if="restarting"
+          indeterminate
+          color="primary"
+          class="mb-2"
+        />
+        <div v-if="statusMessage" class="text-medium-emphasis">
+          {{ statusMessage }}
+        </div>
+      </v-card-text>
+
+      <v-card-actions>
+        <v-spacer />
+        <v-btn variant="text" :disabled="restarting" @click="dismiss">
+          {{ t('core.common.upgradeRecovery.laterButton') }}
+        </v-btn>
+        <v-btn
+          color="primary"
+          variant="flat"
+          prepend-icon="mdi-restart"
+          :loading="restarting"
+          @click="restartCore"
+        >
+          {{ t('core.common.upgradeRecovery.restartButton') }}
+        </v-btn>
+      </v-card-actions>
+    </v-card>
+  </v-dialog>
+</template>
+
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, ref } from 'vue';
+
+import type { ApiEnvelope, VersionData } from '@/api/v1';
+import { httpClient } from '@/api/http';
+import { useI18n } from '@/i18n/composables';
+
+type StartTimeData = {
+  start_time?: number | string | null;
+};
+
+const { t } = useI18n();
+
+const visible = ref(false);
+const restarting = ref(false);
+const statusMessage = ref('');
+const coreVersion = ref('');
+const dashboardVersion = ref('');
+const initialStartTime = ref<number | string | null>(null);
+
+let restartTimer: ReturnType<typeof setInterval> | null = null;
+
+function normalizeVersion(version?: string | null) {
+  return (version || '').trim().replace(/^v/i, '');
+}
+
+function displayVersion(version?: string | null) {
+  const normalized = normalizeVersion(version);
+  return normalized ? `v${normalized}` : 'unknown';
+}
+
+function versionsMismatch(core?: string | null, dashboard?: string | null) {
+  const normalizedCore = normalizeVersion(core);
+  const normalizedDashboard = normalizeVersion(dashboard);
+  return Boolean(
+    normalizedCore &&
+      normalizedDashboard &&
+      normalizedCore !== normalizedDashboard,
+  );
+}
+
+function isMissingApiKeyResponse(response: {
+  data?: { message?: string | null } | string;
+}) {
+  const message =
+    typeof response.data === 'string'
+      ? response.data
+      : response.data?.message || '';
+  return message.toLowerCase().includes('missing api key');
+}
+
+function getDismissKey() {
+  return `astrbot-upgrade-recovery-dismissed:${coreVersion.value}:${dashboardVersion.value}`;
+}
+
+async function fetchLegacyStartTime() {
+  const response = await httpClient.get<ApiEnvelope<StartTimeData>>(
+    '/api/stat/start-time',
+  );
+  return response.data?.data?.start_time ?? null;
+}
+
+function clearRestartTimer() {
+  if (restartTimer !== null) {
+    clearInterval(restartTimer);
+    restartTimer = null;
+  }
+}
+
+function dismiss() {
+  sessionStorage.setItem(getDismissKey(), '1');
+  visible.value = false;
+}
+
+function waitForRestart() {
+  clearRestartTimer();
+  let attempts = 0;
+  restartTimer = setInterval(async () => {
+    attempts += 1;
+    try {
+      const nextStartTime = await fetchLegacyStartTime();
+      if (
+        nextStartTime !== null &&
+        String(nextStartTime) !== String(initialStartTime.value)
+      ) {
+        clearRestartTimer();
+        window.location.reload();
+      }
+    } catch (_error) {
+      // The backend may be temporarily unavailable during restart.
+    }
+
+    if (attempts >= 90) {
+      clearRestartTimer();
+      restarting.value = false;
+      statusMessage.value = t('core.common.upgradeRecovery.failed');
+    }
+  }, 1000);
+}
+
+async function restartCore() {
+  restarting.value = true;
+  statusMessage.value = t('core.common.upgradeRecovery.restarting');
+  try {
+    initialStartTime.value =
+      initialStartTime.value ?? (await fetchLegacyStartTime());
+    await httpClient.post<ApiEnvelope<unknown>>('/api/stat/restart-core');
+    statusMessage.value = t('core.common.upgradeRecovery.waiting');
+    waitForRestart();
+  } catch (_error) {
+    restarting.value = false;
+    statusMessage.value = t('core.common.upgradeRecovery.failed');
+  }
+}
+
+async function detectUpgradeMismatch() {
+  try {
+    const v1Response = await httpClient.get<ApiEnvelope<unknown>>(
+      '/api/v1/auth/setup-status',
+      { validateStatus: () => true },
+    );
+    if (!isMissingApiKeyResponse(v1Response)) {
+      return;
+    }
+
+    const legacyResponse = await httpClient.get<ApiEnvelope<VersionData>>(
+      '/api/stat/version',
+      { validateStatus: () => true },
+    );
+    if (legacyResponse.status === 401 || legacyResponse.status >= 400) {
+      return;
+    }
+
+    const versionData = legacyResponse.data?.data || {};
+    if (!versionsMismatch(versionData.version, versionData.dashboard_version)) {
+      return;
+    }
+
+    coreVersion.value = displayVersion(versionData.version);
+    dashboardVersion.value = displayVersion(versionData.dashboard_version);
+    if (sessionStorage.getItem(getDismissKey())) {
+      return;
+    }
+
+    initialStartTime.value = await fetchLegacyStartTime().catch(() => null);
+    visible.value = true;
+  } catch (_error) {
+    // This recovery dialog is best-effort and should never block the app.
+  }
+}
+
+onMounted(() => {
+  void detectUpgradeMismatch();
+});
+
+onBeforeUnmount(() => {
+  clearRestartTimer();
+});
+</script>
+
+<style scoped>
+.upgrade-recovery-title {
+  align-items: center;
+  display: flex;
+  white-space: normal;
+  word-break: break-word;
+}
+</style>
diff --git a/dashboard/src/i18n/locales/en-US/core/common.json b/dashboard/src/i18n/locales/en-US/core/common.json
index 973feea54..345061969 100644
--- a/dashboard/src/i18n/locales/en-US/core/common.json
+++ b/dashboard/src/i18n/locales/en-US/core/common.json
@@ -48,6 +48,16 @@
     "waiting": "Waiting for AstrBot to restart...",
     "maxRetriesReached": "Maximum retry attempts reached, please check manually."
   },
+  "upgradeRecovery": {
+    "title": "Upgrade Needs Restart",
+    "description": "The WebUI has been updated to {dashboardVersion}, but AstrBot Core is still {coreVersion}. This usually means the restart flow was interrupted by refreshing the page during upgrade.",
+    "hint": "Restart the backend to finish the upgrade. This page will reload automatically after AstrBot is back.",
+    "restartButton": "Restart Backend",
+    "laterButton": "Later",
+    "restarting": "Requesting backend restart...",
+    "waiting": "Restart requested. Waiting for the backend to recover...",
+    "failed": "Restart request failed. Please restart AstrBot manually."
+  },
   "readme": {
     "title": "Extension Documentation",
     "buttons": {
diff --git a/dashboard/src/i18n/locales/ru-RU/core/common.json b/dashboard/src/i18n/locales/ru-RU/core/common.json
index e9f0d4a11..400f4049d 100644
--- a/dashboard/src/i18n/locales/ru-RU/core/common.json
+++ b/dashboard/src/i18n/locales/ru-RU/core/common.json
@@ -48,6 +48,16 @@
         "waiting": "Ожидание перезагрузки AstrBot...",
         "maxRetriesReached": "Превышено количество попыток проверки статуса. Пожалуйста, проверьте вручную."
     },
+    "upgradeRecovery": {
+        "title": "Требуется завершить обновление",
+        "description": "WebUI обновлен до {dashboardVersion}, но AstrBot Core все еще {coreVersion}. Обычно это означает, что процесс перезапуска был прерван обновлением страницы во время обновления.",
+        "hint": "Перезапустите backend, чтобы завершить обновление. Страница автоматически обновится после восстановления AstrBot.",
+        "restartButton": "Перезапустить backend",
+        "laterButton": "Позже",
+        "restarting": "Запрашивается перезапуск backend...",
+        "waiting": "Перезапуск запрошен. Ожидание восстановления backend...",
+        "failed": "Не удалось отправить запрос на перезапуск. Перезапустите AstrBot вручную."
+    },
     "readme": {
         "title": "Документация плагина",
         "buttons": {
@@ -130,4 +140,4 @@
             "subtitle": "Файл FIRST_NOTICE.md не найден или пуст."
         }
     }
-}
\ No newline at end of file
+}
diff --git a/dashboard/src/i18n/locales/zh-CN/core/common.json b/dashboard/src/i18n/locales/zh-CN/core/common.json
index fa1a8bf8b..f0fca5853 100644
--- a/dashboard/src/i18n/locales/zh-CN/core/common.json
+++ b/dashboard/src/i18n/locales/zh-CN/core/common.json
@@ -48,6 +48,16 @@
     "waiting": "正在等待 AstrBot 重启...",
     "maxRetriesReached": "拉取状态达到最大次数，请手动检查。"
   },
+  "upgradeRecovery": {
+    "title": "检测到升级未完成",
+    "description": "当前 WebUI 已更新到 {dashboardVersion}，但 AstrBot Core 仍是 {coreVersion}。这通常是升级过程中刷新页面导致重启流程被打断。",
+    "hint": "请重启后端以完成升级，重启完成后页面会自动刷新。",
+    "restartButton": "立即重启后端",
+    "laterButton": "稍后处理",
+    "restarting": "正在请求后端重启...",
+    "waiting": "已发起重启，正在等待后端恢复...",
+    "failed": "重启请求失败，请手动重启 AstrBot。"
+  },
   "readme": {
     "title": "插件说明文档",
     "buttons": {
diff --git a/dashboard/src/layouts/full/vertical-header/VerticalHeader.vue b/dashboard/src/layouts/full/vertical-header/VerticalHeader.vue
index 15cee8210..1c59bb11a 100644
--- a/dashboard/src/layouts/full/vertical-header/VerticalHeader.vue
+++ b/dashboard/src/layouts/full/vertical-header/VerticalHeader.vue
@@ -738,20 +738,20 @@ async function switchVersion(targetVersion: string) {
     })
     .then((res) => {
       updateStatus.value = res.data.message || "";
-      updateProgress.value = {
-        ...updateProgress.value,
-        status:
-          res.data.status === "ok" ? "success" : updateProgress.value.status,
-        message: res.data.message || "",
-        overall_percent:
-          res.data.status === "ok" ? 100 : updateProgress.value.overall_percent,
-      };
-      if (res.data.status === "ok") {
-        waitForAstrBotRestart(initialStartTime);
+      if (res.data.status === "error") {
+        stopUpdateProgressPolling();
+        updateProgress.value = {
+          ...updateProgress.value,
+          status: "error",
+          message:
+            res.data.message ||
+            t("core.header.updateDialog.progress.failed"),
+        };
       }
     })
     .catch((err) => {
       console.log(err);
+      stopUpdateProgressPolling();
       updateStatus.value = err;
       updateProgress.value = {
         ...updateProgress.value,
@@ -764,7 +764,6 @@ async function switchVersion(targetVersion: string) {
     })
     .finally(() => {
       installLoading.value = false;
-      stopUpdateProgressPolling();
     });
 }
 
diff --git a/tests/test_dashboard.py b/tests/test_dashboard.py
index 637b680f7..53ca81b45 100644
--- a/tests/test_dashboard.py
+++ b/tests/test_dashboard.py
@@ -73,6 +73,33 @@ def _assert_cookie_samesite_strict(cookie_header: str) -> None:
     assert "samesite=strict" in cookie_header.lower()
 
 
+async def _wait_for_update_progress(
+    test_client,
+    authenticated_header: dict,
+    progress_id: str,
+) -> dict:
+    """Wait until a dashboard update task reaches a terminal status.
+
+    Args:
+        test_client: Quart/FastAPI adapter test client.
+        authenticated_header: Headers for authenticated dashboard requests.
+        progress_id: Update progress id to poll.
+
+    Returns:
+        The progress response payload.
+    """
+    for _ in range(100):
+        response = await test_client.get(
+            f"/api/update/progress?id={progress_id}",
+            headers=authenticated_header,
+        )
+        data = await response.get_json()
+        if data["data"].get("status") in {"success", "error"}:
+            return data
+        await asyncio.sleep(0.01)
+    pytest.fail(f"Update task did not finish: {progress_id}")
+
+
 @pytest.fixture
 def registered_plugin_page(core_lifecycle_td: AstrBotCoreLifecycle, monkeypatch):
     plugin_root = (
@@ -2633,6 +2660,13 @@ async def test_do_update(
     assert response.status_code == 200
     data = await response.get_json()
     assert data["status"] == "ok"
+    assert data["data"]["id"] == "test-progress"
+
+    progress_data = await _wait_for_update_progress(
+        test_client,
+        authenticated_header,
+        "test-progress",
+    )
     assert os.path.exists(release_path)
     assert calls[:4] == [
         "download-dashboard",
@@ -2641,11 +2675,6 @@ async def test_do_update(
         "apply-dashboard",
     ]
 
-    progress_response = await test_client.get(
-        "/api/update/progress?id=test-progress",
-        headers=authenticated_header,
-    )
-    progress_data = await progress_response.get_json()
     assert progress_data["status"] == "ok"
     assert progress_data["data"]["status"] == "success"
     assert progress_data["data"]["overall_percent"] == 100
@@ -2707,7 +2736,13 @@ async def test_do_update_does_not_apply_files_when_core_download_fails(
     data = await response.get_json()
 
     assert response.status_code == 200
-    assert data["status"] == "error"
+    assert data["status"] == "ok"
+    progress_data = await _wait_for_update_progress(
+        test_client,
+        authenticated_header,
+        "atomic-fail",
+    )
+    assert progress_data["data"]["status"] == "error"
     assert calls == ["download-dashboard", "download-core"]
 
 
@@ -2769,7 +2804,13 @@ async def test_do_update_does_not_apply_files_when_package_verification_fails(
     data = await response.get_json()
 
     assert response.status_code == 200
-    assert data["status"] == "error"
+    assert data["status"] == "ok"
+    progress_data = await _wait_for_update_progress(
+        test_client,
+        authenticated_header,
+        "invalid-zip",
+    )
+    assert progress_data["data"]["status"] == "error"
     assert calls == ["download-dashboard", "download-core"]
 
 
@@ -2812,15 +2853,14 @@ async def test_do_update_hides_internal_error_message_in_response_and_progress(
     data = await response.get_json()
 
     assert response.status_code == 200
-    assert data["status"] == "error"
-    assert data["message"] == "An internal error has occurred."
+    assert data["status"] == "ok"
     assert "secret stack trace" not in str(data)
 
-    progress_response = await test_client.get(
-        "/api/update/progress?id=failed-progress",
-        headers=authenticated_header,
+    progress_data = await _wait_for_update_progress(
+        test_client,
+        authenticated_header,
+        "failed-progress",
     )
-    progress_data = await progress_response.get_json()
 
     assert progress_data["status"] == "ok"
     assert progress_data["data"]["status"] == "error"