v1.29.0

changelog.md

@@ -3,6 +3,15 @@
 ## Pending
 
 
+## 2026-05-24 - 1.29.0
+
+### Features
+
+- add Onebox runtime update prompts and admin-triggered self-upgrades
+  - expose Onebox update status through system status
+  - reuse the CLI upgrade logic for web-triggered detached upgrades
+  - show an update banner and guided DeesUpdater flow in the dashboard
+
 ## 2026-05-24 - 1.28.0
 
 ### Features

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/onebox",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "exports": "./mod.ts",
   "tasks": {
     "test": "deno test --allow-all test/",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/onebox",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers",
   "main": "mod.ts",
   "type": "module",
@@ -52,7 +52,7 @@
     "x64",
     "arm64"
   ],
-  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34",
+  "packageManager": "pnpm@11.1.2",
   "dependencies": {
     "@api.global/typedrequest-interfaces": "^3.0.19",
     "@api.global/typedsocket": "^4.1.3",
@@ -65,8 +65,5 @@
     "@git.zone/tsdeno": "^1.3.2",
     "@git.zone/tswatch": "^3.3.5"
   },
-  "private": true,
-  "pnpm": {
-    "overrides": {}
-  }
+  "private": true
 }

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/onebox',
-  version: '1.28.0',
+  version: '1.29.0',
   description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }

ts/classes/onebox.ts

@@ -5,6 +5,7 @@
  */
 
 import { logger } from '../logging.ts';
+import { projectInfo } from '../info.ts';
 import { getErrorMessage } from '../utils/error.ts';
 import { hashPassword } from '../utils/auth.ts';
 import { OneboxDatabase } from './database.ts';
@@ -26,6 +27,7 @@ import { BackupManager } from './backup-manager.ts';
 import { BackupScheduler } from './backup-scheduler.ts';
 import { ExternalGatewayManager } from './external-gateway.ts';
 import { ManagedDcRouterManager } from './managed-dcrouter.ts';
+import { OneboxUpdateManager } from './update-manager.ts';
 import { OpsServer } from '../opsserver/index.ts';
 
 export class Onebox {
@@ -48,6 +50,7 @@ export class Onebox {
   public backupScheduler: BackupScheduler;
   public managedDcRouter: ManagedDcRouterManager;
   public externalGateway: ExternalGatewayManager;
+  public updateManager: OneboxUpdateManager;
   public opsServer: OpsServer;
 
   private initialized = false;
@@ -93,6 +96,7 @@ export class Onebox {
     // Initialize optional dcrouter gateway integration
     this.managedDcRouter = new ManagedDcRouterManager(this);
     this.externalGateway = new ExternalGatewayManager(this);
+    this.updateManager = new OneboxUpdateManager();
 
     // Initialize OpsServer (TypedRequest-based server)
     this.opsServer = new OpsServer(this);
@@ -305,6 +309,7 @@ export class Onebox {
       const proxyStatus = this.reverseProxy.getStatus();
       const dnsConfigured = this.dns.isConfigured();
       const sslConfigured = this.ssl.isConfigured();
+      const oneboxUpdate = await this.updateManager.getUpdateStatus();
 
       const services = this.services.listServices();
       const runningServices = services.filter((s) => s.status === 'running').length;
@@ -407,6 +412,10 @@ export class Onebox {
       }
 
       return {
+        onebox: {
+          version: projectInfo.version,
+          update: oneboxUpdate,
+        },
         docker: {
           running: dockerRunning,
           version: dockerRunning ? await this.docker.getDockerVersion() : null,

ts/classes/update-manager.ts

@@ -0,0 +1,214 @@
+import { logger } from '../logging.ts';
+import { projectInfo } from '../info.ts';
+import { getErrorMessage } from '../utils/error.ts';
+import * as interfaces from '../../ts_interfaces/index.ts';
+
+const ONEBOX_REPOSITORY_URL = 'https://code.foss.global/serve.zone/onebox';
+const ONEBOX_LATEST_RELEASE_API_URL =
+  'https://code.foss.global/api/v1/repos/serve.zone/onebox/releases/latest';
+const ONEBOX_INSTALL_SCRIPT_URL = `${ONEBOX_REPOSITORY_URL}/raw/branch/main/install.sh`;
+const ONEBOX_CHANGELOG_URL = `${ONEBOX_REPOSITORY_URL}/src/branch/main/changelog.md`;
+const UPGRADE_LOG_PATH = '/var/log/onebox-upgrade.log';
+
+interface IGiteaReleaseResponse {
+  tag_name?: unknown;
+  html_url?: unknown;
+}
+
+interface IParsedRelease {
+  tagName: string;
+  releaseUrl: string;
+}
+
+export class OneboxUpdateManager {
+  private cachedStatus: interfaces.data.IOneboxUpdateStatus | null = null;
+  private cachedStatusExpiresAt = 0;
+  private upgradeStartedAt = 0;
+  private readonly statusCacheTtlMs = 5 * 60 * 1000;
+
+  public async getUpdateStatus(
+    optionsArg: { force?: boolean } = {},
+  ): Promise<interfaces.data.IOneboxUpdateStatus> {
+    const now = Date.now();
+    if (!optionsArg.force && this.cachedStatus && this.cachedStatusExpiresAt > now) {
+      return this.cachedStatus;
+    }
+
+    const status = await this.fetchUpdateStatus();
+    this.cachedStatus = status;
+    this.cachedStatusExpiresAt = now + this.statusCacheTtlMs;
+    return status;
+  }
+
+  public async startDetachedUpgrade(): Promise<interfaces.data.IOneboxUpgradeStartResult> {
+    this.assertRoot();
+
+    const status = await this.getUpdateStatus({ force: true });
+    this.assertUpdateCheckSucceeded(status);
+
+    const targetVersion = status.latestVersion || status.currentVersion;
+    if (!status.updateAvailable) {
+      return {
+        accepted: false,
+        currentVersion: status.currentVersion,
+        targetVersion,
+        message: 'Onebox is already up to date.',
+      };
+    }
+
+    if (this.upgradeStartedAt && Date.now() - this.upgradeStartedAt < 10 * 60 * 1000) {
+      return {
+        accepted: false,
+        currentVersion: status.currentVersion,
+        targetVersion,
+        message: 'A Onebox upgrade has already been started.',
+        logPath: UPGRADE_LOG_PATH,
+      };
+    }
+
+    const command = new Deno.Command('bash', {
+      args: ['-c', this.createDetachedUpgradeScript()],
+      stdin: 'null',
+      stdout: 'null',
+      stderr: 'null',
+      detached: true,
+    });
+    const child = command.spawn();
+    child.unref();
+    this.upgradeStartedAt = Date.now();
+
+    logger.info(`Started detached Onebox upgrade process ${child.pid}`);
+    return {
+      accepted: true,
+      currentVersion: status.currentVersion,
+      targetVersion,
+      message: 'Onebox upgrade started. The service will restart automatically.',
+      pid: child.pid,
+      logPath: UPGRADE_LOG_PATH,
+    };
+  }
+
+  public async runUpgradeForeground(
+    statusArg?: interfaces.data.IOneboxUpdateStatus,
+  ): Promise<interfaces.data.IOneboxUpgradeStartResult> {
+    this.assertRoot();
+
+    const status = statusArg || (await this.getUpdateStatus({ force: true }));
+    this.assertUpdateCheckSucceeded(status);
+
+    const targetVersion = status.latestVersion || status.currentVersion;
+    if (!status.updateAvailable) {
+      return {
+        accepted: false,
+        currentVersion: status.currentVersion,
+        targetVersion,
+        message: 'Onebox is already up to date.',
+      };
+    }
+
+    const installCommand = new Deno.Command('bash', {
+      args: ['-c', `curl -sSL ${ONEBOX_INSTALL_SCRIPT_URL} | bash`],
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit',
+    });
+    const installResult = await installCommand.output();
+    if (!installResult.success) {
+      throw new Error('Upgrade failed');
+    }
+
+    return {
+      accepted: true,
+      currentVersion: status.currentVersion,
+      targetVersion,
+      message: `Upgraded to ${targetVersion}`,
+    };
+  }
+
+  private async fetchUpdateStatus(): Promise<interfaces.data.IOneboxUpdateStatus> {
+    const currentVersion = this.normalizeVersion(projectInfo.version);
+    const checkedAt = Date.now();
+
+    try {
+      const release = await this.fetchLatestRelease();
+      const latestVersion = this.normalizeVersion(release.tagName);
+      return {
+        currentVersion,
+        latestVersion,
+        updateAvailable: currentVersion !== latestVersion,
+        checkedAt,
+        releaseUrl: release.releaseUrl,
+        changelogUrl: ONEBOX_CHANGELOG_URL,
+      };
+    } catch (error) {
+      return {
+        currentVersion,
+        latestVersion: null,
+        updateAvailable: false,
+        checkedAt,
+        releaseUrl: `${ONEBOX_REPOSITORY_URL}/releases`,
+        changelogUrl: ONEBOX_CHANGELOG_URL,
+        error: getErrorMessage(error),
+      };
+    }
+  }
+
+  private async fetchLatestRelease(): Promise<IParsedRelease> {
+    const abortController = new AbortController();
+    const timeoutId = setTimeout(() => abortController.abort(), 5000);
+
+    try {
+      const response = await fetch(ONEBOX_LATEST_RELEASE_API_URL, {
+        headers: { accept: 'application/json' },
+        signal: abortController.signal,
+      });
+      if (!response.ok) {
+        throw new Error(`Failed to fetch latest release: HTTP ${response.status}`);
+      }
+
+      const release = await response.json() as IGiteaReleaseResponse;
+      if (typeof release.tag_name !== 'string' || !release.tag_name) {
+        throw new Error('Latest release response does not include a tag name');
+      }
+
+      const tagName = release.tag_name;
+      const releaseUrl = typeof release.html_url === 'string' && release.html_url
+        ? release.html_url
+        : `${ONEBOX_REPOSITORY_URL}/releases/tag/${this.normalizeVersion(tagName)}`;
+
+      return { tagName, releaseUrl };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  private assertRoot(): void {
+    if (Deno.uid() !== 0) {
+      throw new Error('Onebox upgrades must be started as root. Try: sudo onebox upgrade');
+    }
+  }
+
+  private assertUpdateCheckSucceeded(statusArg: interfaces.data.IOneboxUpdateStatus): void {
+    if (statusArg.error) {
+      throw new Error(`Cannot determine latest Onebox release: ${statusArg.error}`);
+    }
+  }
+
+  private normalizeVersion(versionArg: string): string {
+    const trimmedVersion = versionArg.trim();
+    return trimmedVersion.startsWith('v') ? trimmedVersion : `v${trimmedVersion}`;
+  }
+
+  private createDetachedUpgradeScript(): string {
+    return `
+set -e
+mkdir -p /var/log
+{
+  echo "==== Onebox upgrade started $(date -Is) ===="
+  sleep 2
+  curl -sSL ${ONEBOX_INSTALL_SCRIPT_URL} | bash
+  echo "==== Onebox upgrade finished $(date -Is) ===="
+} >> ${UPGRADE_LOG_PATH} 2>&1
+`;
+  }
+}

ts/cli.ts

@@ -8,6 +8,7 @@ import { getErrorMessage } from './utils/error.ts';
 import { Onebox } from './classes/onebox.ts';
 import { OneboxDaemon } from './classes/daemon.ts';
 import { OneboxSystemd } from './classes/systemd.ts';
+import { OneboxUpdateManager } from './classes/update-manager.ts';
 import type { IAppVersionConfig } from './classes/appstore-types.ts';
 
 export async function runCli(): Promise<void> {
@@ -500,60 +501,29 @@ async function handleUpgradeCommand(): Promise<void> {
   logger.info('Checking for updates...');
 
   try {
-    // Get current version
-    const currentVersion = projectInfo.version;
+    const updateManager = new OneboxUpdateManager();
+    const status = await updateManager.getUpdateStatus({ force: true });
+    if (status.error) {
+      throw new Error(status.error);
+    }
 
-    // Fetch latest version from Gitea API
-    const apiUrl = 'https://code.foss.global/api/v1/repos/serve.zone/onebox/releases/latest';
-    const curlCmd = new Deno.Command('curl', {
-      args: ['-sSL', apiUrl],
-      stdout: 'piped',
-      stderr: 'piped',
-    });
-    const curlResult = await curlCmd.output();
-    const response = new TextDecoder().decode(curlResult.stdout);
-    const release = JSON.parse(response);
-    const latestVersion = release.tag_name as string; // e.g., "v1.11.0"
-
-    // Normalize versions for comparison (ensure both have "v" prefix)
-    const normalizedCurrent = currentVersion.startsWith('v')
-      ? currentVersion
-      : `v${currentVersion}`;
-    const normalizedLatest = latestVersion.startsWith('v')
-      ? latestVersion
-      : `v${latestVersion}`;
-
-    console.log(`  Current version: ${normalizedCurrent}`);
-    console.log(`  Latest version:  ${normalizedLatest}`);
+    console.log(`  Current version: ${status.currentVersion}`);
+    console.log(`  Latest version:  ${status.latestVersion}`);
     console.log('');
 
-    // Compare normalized versions
-    if (normalizedCurrent === normalizedLatest) {
+    if (!status.updateAvailable) {
       logger.success('Already up to date!');
       return;
     }
 
-    logger.info(`New version available: ${latestVersion}`);
+    logger.info(`New version available: ${status.latestVersion}`);
     logger.info('Downloading and installing...');
     console.log('');
 
-    // Download and run the install script
-    const installUrl = 'https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh';
-    const installCmd = new Deno.Command('bash', {
-      args: ['-c', `curl -sSL ${installUrl} | bash`],
-      stdin: 'inherit',
-      stdout: 'inherit',
-      stderr: 'inherit',
-    });
-    const installResult = await installCmd.output();
-
-    if (!installResult.success) {
-      logger.error('Upgrade failed');
-      Deno.exit(1);
-    }
+    const upgrade = await updateManager.runUpgradeForeground(status);
 
     console.log('');
-    logger.success(`Upgraded to ${latestVersion}`);
+    logger.success(upgrade.message);
   } catch (error) {
     logger.error(`Upgrade failed: ${getErrorMessage(error)}`);
     Deno.exit(1);

ts/opsserver/handlers/status.handler.ts

@@ -2,6 +2,7 @@ import * as plugins from '../../plugins.ts';
 import type { OpsServer } from '../classes.opsserver.ts';
 import * as interfaces from '../../../ts_interfaces/index.ts';
 import { requireAdminIdentity } from '../helpers/guards.ts';
+import { getErrorMessage } from '../../utils/error.ts';
 
 export class StatusHandler {
   public typedrouter = new plugins.typedrequest.TypedRouter();
@@ -22,5 +23,20 @@ export class StatusHandler {
         },
       ),
     );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_StartOneboxUpgrade>(
+        'startOneboxUpgrade',
+        async (dataArg) => {
+          await requireAdminIdentity(this.opsServerRef.adminHandler, dataArg);
+          try {
+            const upgrade = await this.opsServerRef.oneboxRef.updateManager.startDetachedUpgrade();
+            return { upgrade };
+          } catch (error) {
+            throw new plugins.typedrequest.TypedResponseError(getErrorMessage(error));
+          }
+        },
+      ),
+    );
   }
 }

ts_interfaces/data/system.ts

@@ -4,7 +4,30 @@
 
 import type { TPlatformServiceType, TPlatformServiceStatus } from './platform.ts';
 
+export interface IOneboxUpdateStatus {
+  currentVersion: string;
+  latestVersion: string | null;
+  updateAvailable: boolean;
+  checkedAt: number;
+  releaseUrl: string;
+  changelogUrl: string;
+  error?: string;
+}
+
+export interface IOneboxUpgradeStartResult {
+  accepted: boolean;
+  currentVersion: string;
+  targetVersion: string;
+  message: string;
+  pid?: number;
+  logPath?: string;
+}
+
 export interface ISystemStatus {
+  onebox: {
+    version: string;
+    update: IOneboxUpdateStatus;
+  };
   docker: {
     running: boolean;
     version: unknown;

ts_interfaces/requests/status.ts

@@ -13,3 +13,16 @@ export interface IReq_GetSystemStatus extends plugins.typedrequestInterfaces.imp
     status: data.ISystemStatus;
   };
 }
+
+export interface IReq_StartOneboxUpgrade extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_StartOneboxUpgrade
+> {
+  method: 'startOneboxUpgrade';
+  request: {
+    identity: data.IIdentity;
+  };
+  response: {
+    upgrade: data.IOneboxUpgradeStartResult;
+  };
+}

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/onebox',
-  version: '1.28.0',
+  version: '1.29.0',
   description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }

ts_web/elements/ob-app-shell.ts

@@ -41,6 +41,14 @@ export class ObAppShell extends DeesElement {
     refreshInterval: 30000,
   };
 
+  @state()
+  accessor systemState: appstate.ISystemState = {
+    status: null,
+  };
+
+  @state()
+  accessor globalMessages: plugins.deesCatalog.IGlobalMessage[] = [];
+
   @state()
   accessor loginLoading: boolean = false;
 
@@ -126,6 +134,8 @@ export class ObAppShell extends DeesElement {
   ];
 
   private resolvedViewTabs: IResolvedView[] = [];
+  private suppressedUpdateVersion = '';
+  private upgradeFlowRunning = false;
 
   constructor() {
     super();
@@ -135,12 +145,21 @@ export class ObAppShell extends DeesElement {
       .select((stateArg: appstate.ILoginState) => stateArg)
       .subscribe((loginState: appstate.ILoginState) => {
         this.loginState = loginState;
+        this.updateGlobalMessages();
         if (loginState.isLoggedIn) {
           appstate.systemStatePart.dispatchAction(appstate.fetchSystemStatusAction, null);
         }
       });
     this.rxSubscriptions.push(loginSubscription);
 
+    const systemSubscription = appstate.systemStatePart
+      .select((stateArg: appstate.ISystemState) => stateArg)
+      .subscribe((systemState: appstate.ISystemState) => {
+        this.systemState = systemState;
+        this.updateGlobalMessages();
+      });
+    this.rxSubscriptions.push(systemSubscription);
+
     const uiSubscription = appstate.uiStatePart
       .select((stateArg: appstate.IUiState) => stateArg)
       .subscribe((uiState: appstate.IUiState) => {
@@ -214,6 +233,7 @@ export class ObAppShell extends DeesElement {
             name="Onebox"
             .viewTabs=${this.resolvedViewTabs}
             .selectedView=${this.currentViewTab}
+            .globalMessages=${this.globalMessages}
           >
           </dees-simple-appdash>
         </dees-simple-login>
@@ -324,6 +344,177 @@ export class ObAppShell extends DeesElement {
     }
   }
 
+  private updateGlobalMessages(): void {
+    const updateStatus = this.systemState.status?.onebox.update;
+    if (
+      !this.loginState.isLoggedIn ||
+      !updateStatus?.updateAvailable ||
+      !updateStatus.latestVersion ||
+      updateStatus.latestVersion === this.suppressedUpdateVersion
+    ) {
+      this.globalMessages = [];
+      return;
+    }
+
+    this.globalMessages = [
+      {
+        id: `onebox-update-${updateStatus.latestVersion}`,
+        type: 'info',
+        icon: 'lucide:download',
+        message: `Onebox ${updateStatus.latestVersion} is available. Current version: ${updateStatus.currentVersion}.`,
+        dismissible: false,
+        actions: [
+          {
+            name: 'Update Now',
+            iconName: 'lucide:download',
+            action: () => this.startOneboxUpgradeFlow(),
+          },
+          {
+            name: 'Release Notes',
+            iconName: 'lucide:fileText',
+            action: () => this.openUpdateUrl(updateStatus.changelogUrl || updateStatus.releaseUrl),
+          },
+          {
+            name: 'Later',
+            iconName: 'lucide:clock',
+            action: () => {
+              this.suppressedUpdateVersion = updateStatus.latestVersion || '';
+              this.updateGlobalMessages();
+            },
+          },
+        ],
+      },
+    ];
+  }
+
+  private async startOneboxUpgradeFlow(): Promise<void> {
+    if (this.upgradeFlowRunning) {
+      return;
+    }
+
+    const identity = appstate.loginStatePart.getState().identity;
+    const updateStatus = this.systemState.status?.onebox.update;
+    if (!identity || !updateStatus?.latestVersion) {
+      return;
+    }
+
+    this.upgradeFlowRunning = true;
+    const updater = await plugins.deesCatalog.DeesUpdater.createAndShow({
+      currentVersion: updateStatus.currentVersion,
+      updatedVersion: updateStatus.latestVersion,
+      moreInfoUrl: updateStatus.releaseUrl,
+      changelogUrl: updateStatus.changelogUrl,
+      successAction: 'reload',
+      successDelayMs: 30000,
+      successActionLabel: 'Reloading Onebox UI',
+    });
+
+    try {
+      updater.updateProgress({
+        percentage: 10,
+        indeterminate: true,
+        statusText: 'Requesting upgrade...',
+        terminalLines: ['Requesting Onebox upgrade'],
+      });
+
+      const typedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+        interfaces.requests.IReq_StartOneboxUpgrade
+      >('/typedrequest', 'startOneboxUpgrade');
+      const response = await typedRequest.fire({ identity });
+
+      if (!response.upgrade.accepted) {
+        updater.markUpdateError(response.upgrade.message);
+        await this.delay(5000);
+        await updater.destroy();
+        return;
+      }
+
+      updater.appendProgressLine(response.upgrade.message);
+      if (response.upgrade.pid) {
+        updater.appendProgressLine(`Upgrade process PID: ${response.upgrade.pid}`);
+      }
+      if (response.upgrade.logPath) {
+        updater.appendProgressLine(`Upgrade log: ${response.upgrade.logPath}`);
+      }
+      updater.updateProgress({
+        percentage: 45,
+        indeterminate: true,
+        statusText: 'Installer started...',
+      });
+
+      await this.waitForOneboxUpgrade(updater, response.upgrade.targetVersion, identity);
+      await updater.markUpdateReady();
+    } catch (error) {
+      updater.markUpdateError(this.getErrorMessage(error));
+      await this.delay(5000);
+      await updater.destroy();
+    } finally {
+      this.upgradeFlowRunning = false;
+    }
+  }
+
+  private async waitForOneboxUpgrade(
+    updaterArg: plugins.deesCatalog.DeesUpdater,
+    targetVersionArg: string,
+    identityArg: interfaces.data.IIdentity,
+  ): Promise<void> {
+    const normalizedTargetVersion = this.normalizeVersion(targetVersionArg);
+    const timeoutAt = Date.now() + 90000;
+    let attempt = 0;
+
+    updaterArg.appendProgressLine('Waiting for Onebox to restart with the new version');
+    while (Date.now() < timeoutAt) {
+      await this.delay(5000);
+      attempt++;
+
+      try {
+        const typedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+          interfaces.requests.IReq_GetSystemStatus
+        >('/typedrequest', 'getSystemStatus');
+        const response = await typedRequest.fire({ identity: identityArg });
+        const onlineVersion = this.normalizeVersion(response.status.onebox.version);
+        updaterArg.appendProgressLine(`Onebox API answered with ${onlineVersion}`);
+
+        if (onlineVersion === normalizedTargetVersion) {
+          updaterArg.updateProgress({
+            percentage: 100,
+            indeterminate: false,
+            statusText: `Onebox ${normalizedTargetVersion} is online.`,
+          });
+          return;
+        }
+      } catch {
+        updaterArg.appendProgressLine('Onebox API is restarting...');
+      }
+
+      updaterArg.updateProgress({
+        percentage: Math.min(95, 45 + attempt * 5),
+        indeterminate: true,
+        statusText: `Waiting for Onebox ${normalizedTargetVersion}...`,
+      });
+    }
+
+    updaterArg.appendProgressLine('Timed out waiting for the version check; reloading the UI anyway');
+  }
+
+  private openUpdateUrl(urlArg: string): void {
+    window.open(urlArg, '_blank', 'noopener,noreferrer');
+  }
+
+  private async delay(millisecondsArg: number): Promise<void> {
+    const domtools = await this.domtoolsPromise;
+    await domtools.convenience.smartdelay.delayFor(millisecondsArg);
+  }
+
+  private getErrorMessage(errorArg: unknown): string {
+    return errorArg instanceof Error ? errorArg.message : String(errorArg);
+  }
+
+  private normalizeVersion(versionArg: string): string {
+    const trimmedVersion = versionArg.trim();
+    return trimmedVersion.startsWith('v') ? trimmedVersion : `v${trimmedVersion}`;
+  }
+
   private syncAppdashView(viewName: string, subviewName: string | null): void {
     const appDash = this.shadowRoot?.querySelector('dees-simple-appdash') as any;
     if (!appDash || this.resolvedViewTabs.length === 0) return;