From 16059ba6b48b143771882ea8e1b1cc574453f921 Mon Sep 17 00:00:00 2001
From: perry gupta <cg077593@gmail.com>
Date: Sun, 15 Nov 2026 10:12:02 +0530
Subject: [PATCH 1/2] fix(startup): show database migration progress

Refs #35995
---
 apps/desktop/src/app/DesktopState.ts          |   3 +
 .../src/backend/DesktopBackendManager.test.ts |  23 ++-
 .../src/backend/DesktopBackendManager.ts      |  32 +++-
 .../desktop/src/backend/DesktopBackendPool.ts |   4 +-
 apps/desktop/src/ipc/DesktopIpcHandlers.ts    |   2 +
 apps/desktop/src/ipc/channels.ts              |   1 +
 apps/desktop/src/ipc/methods/window.ts        |  13 ++
 apps/desktop/src/preload.ts                   |   2 +
 .../server/src/httpResponseErrorGuard.test.ts |  60 ++++++--
 apps/server/src/httpResponseErrorGuard.ts     |  29 +++-
 .../persistence/DatabaseMigrationProgress.ts  |  15 ++
 .../server/src/persistence/Migrations.test.ts |  57 ++++++-
 apps/server/src/persistence/Migrations.ts     | 143 ++++++++++--------
 apps/server/src/server.ts                     |   5 +
 apps/web/index.html                           |  29 ++++
 packages/contracts/src/ipc.ts                 |   2 +
 packages/contracts/src/server.ts              |  12 ++
 .../shared/src/databaseMigrationLog.test.ts   |  30 ++++
 packages/shared/src/databaseMigrationLog.ts   |  22 +++
 19 files changed, 400 insertions(+), 84 deletions(-)
 create mode 100644 apps/server/src/persistence/DatabaseMigrationProgress.ts
 create mode 100644 packages/shared/src/databaseMigrationLog.test.ts

diff --git a/apps/desktop/src/app/DesktopState.ts b/apps/desktop/src/app/DesktopState.ts
index f869fd335ab07..39d3dabdf7864 100644
--- a/apps/desktop/src/app/DesktopState.ts
+++ b/apps/desktop/src/app/DesktopState.ts
@@ -3,6 +3,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Ref from "effect/Ref";
 import * as SubscriptionRef from "effect/SubscriptionRef";
+import type { DatabaseMigrationProgress } from "@t3tools/contracts";
 
 import type { BackendStartupFailure } from "../backend/DesktopBackendManager.ts";
 
@@ -20,6 +21,7 @@ export class DesktopState extends Context.Service<
     // Set by DesktopUpdates.configure, which runs before the first backend start.
     readonly canInstallUpdates: Ref.Ref<boolean>;
     readonly primaryBackendStartup: SubscriptionRef.SubscriptionRef<PrimaryBackendStartup>;
+    readonly databaseMigrationProgress: Ref.Ref<DatabaseMigrationProgress | null>;
   }
 >()("@t3tools/desktop/app/DesktopState") {}
 
@@ -28,6 +30,7 @@ const make = Effect.all({
   quitting: Ref.make(false),
   canInstallUpdates: Ref.make(false),
   primaryBackendStartup: SubscriptionRef.make<PrimaryBackendStartup>({ _tag: "Starting" }),
+  databaseMigrationProgress: Ref.make<DatabaseMigrationProgress | null>(null),
 });
 
 export const layer = Layer.effect(DesktopState, make);
diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts
index 06a1f768f4bd4..5406b2357d017 100644
--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts
+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts
@@ -129,6 +129,9 @@ interface MakeInstanceInput {
   readonly onReady?: Effect.Effect<void>;
   readonly onShutdown?: Effect.Effect<void>;
   readonly onStateDirOwned?: Effect.Effect<void>;
+  readonly onMigrationProgress?: (
+    progress: { current: number; total: number } | null,
+  ) => Effect.Effect<void>;
   readonly onStartupFailure?: (
     failure: DesktopBackendManager.BackendStartupFailure,
   ) => Effect.Effect<void>;
@@ -192,6 +195,7 @@ function makeTestInstance(input: MakeInstanceInput) {
     ...(input.onStateDirOwned ? { onStateDirOwned: () => input.onStateDirOwned! } : {}),
     ...(input.onPreflightFailed ? { onPreflightFailed: input.onPreflightFailed } : {}),
     ...(input.onStartupFailure ? { onStartupFailure: input.onStartupFailure } : {}),
+    ...(input.onMigrationProgress ? { onMigrationProgress: input.onMigrationProgress } : {}),
   });
 
   return instance.pipe(Effect.provide(layerServices));
@@ -657,7 +661,8 @@ describe("DesktopBackendManager", () => {
     "reports exit $code with the server output after $exits exits",
     ({ code, exits, managedPolicy }) =>
       Effect.gen(function* () {
-        const message = "Error: Cannot find module 'zod/v4' in /Users/René";
+        const message = `${DATABASE_MIGRATION_PROGRESS_MESSAGE} (1 of 3)\n  progress: 1 of 3\nError: Cannot find module 'zod/v4' in /Users/René`;
+        const progress: Array<{ current: number; total: number } | null> = [];
         let exitCount = 0;
         const firstExit = yield* Deferred.make<void>();
         const reports = yield* Queue.unbounded<{
@@ -691,6 +696,10 @@ describe("DesktopBackendManager", () => {
               return Deferred.succeed(firstExit, undefined).pipe(Effect.asVoid);
             },
           },
+          onMigrationProgress: (value) =>
+            Effect.sync(() => {
+              progress.push(value);
+            }),
           onStartupFailure: (failure) =>
             Queue.offer(reports, { exitCount, failure }).pipe(Effect.asVoid),
         });
@@ -703,12 +712,15 @@ describe("DesktopBackendManager", () => {
         assert.equal(failure.managedPolicy, managedPolicy);
         assert.isTrue(failure.output.endsWith(message));
         assert.isTrue(failure.output.isWellFormed());
+        assert.isTrue(progress.some((value) => value?.current === 1 && value.total === 3));
+        assert.isNull(progress.at(-1));
       }).pipe(Effect.provide(TestClock.layer())),
   );
 
   it.effect("waits out a slow startup and reports one that never becomes ready", () =>
     Effect.gen(function* () {
       const reports = yield* Queue.unbounded<DesktopBackendManager.BackendStartupFailure>();
+      const progress: Array<{ current: number; total: number } | null> = [];
       const startInstance = (status: Ref.Ref<number>, onReady?: Effect.Effect<void>, stdout = "") =>
         makeTestInstance({
           spawnerLayer: Layer.succeed(
@@ -725,6 +737,10 @@ describe("DesktopBackendManager", () => {
           httpClientLayer: layerHttpClient((request) =>
             Ref.get(status).pipe(Effect.map((code) => responseForRequest(request, code))),
           ),
+          onMigrationProgress: (value) =>
+            Effect.sync(() => {
+              progress.push(value);
+            }),
           onStartupFailure: (failure) => Queue.offer(reports, failure).pipe(Effect.asVoid),
           ...(onReady ? { onReady } : {}),
         }).pipe(Effect.tap((instance) => instance.start));
@@ -748,14 +764,16 @@ describe("DesktopBackendManager", () => {
           Array.from(
             { length: 80 },
             (_, index) =>
-              `INFO ${DATABASE_MIGRATION_PROGRESS_MESSAGE} migration=${index}_Migration progress="${index + 1} of 80"\n`,
+              `INFO ${DATABASE_MIGRATION_PROGRESS_MESSAGE} (${index + 1} of 80)\n  migration: ${index}_Migration\n  progress: ${index + 1} of 80\n`,
           ).join(""),
       );
       yield* TestClock.adjust(Duration.minutes(10));
+      assert.deepStrictEqual(progress.at(-1), { current: 80, total: 80 });
       assert.isTrue(Option.isNone(yield* Queue.poll(reports)));
       yield* Ref.set(migratingStatus, 200);
       yield* TestClock.adjust(Duration.millis(100));
       yield* Deferred.await(migrated);
+      assert.isNull(progress.at(-1));
 
       yield* startInstance(
         yield* Ref.make(503),
@@ -766,6 +784,7 @@ describe("DesktopBackendManager", () => {
       assert.isTrue(Option.isNone(yield* Queue.poll(reports)));
       yield* TestClock.adjust(Duration.seconds(1));
       const failure = yield* Queue.take(reports);
+      assert.isNull(progress.at(-1));
       assert.equal(failure.reason, "The server started but did not become ready in time.");
     }).pipe(Effect.provide(TestClock.layer())),
   );
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts
index 4acaa8a3c18b8..00662d1293269 100644
--- a/apps/desktop/src/backend/DesktopBackendManager.ts
+++ b/apps/desktop/src/backend/DesktopBackendManager.ts
@@ -25,8 +25,12 @@ import {
   PRIMARY_LOCAL_ENVIRONMENT_ID,
   DesktopTelemetryControlMessage,
   type DesktopTelemetryControlMessage as DesktopTelemetryControlMessageValue,
+  type DatabaseMigrationProgress,
 } from "@t3tools/contracts";
-import { isRunningDatabaseMigrations } from "@t3tools/shared/databaseMigrationLog";
+import {
+  databaseMigrationProgress,
+  isRunningDatabaseMigrations,
+} from "@t3tools/shared/databaseMigrationLog";
 import { waitForHttpReady as waitForHttpReadyShared } from "@t3tools/shared/httpReadiness";
 
 import * as DesktopObservability from "../app/DesktopObservability.ts";
@@ -260,6 +264,9 @@ export interface BackendInstanceSpec {
   readonly onStateDirOwned?: () => Effect.Effect<void>;
   /** Fires on each repeated crash or readiness timeout until the backend becomes ready. */
   readonly onStartupFailure?: (failure: BackendStartupFailure) => Effect.Effect<void>;
+  readonly onMigrationProgress?: (
+    progress: DatabaseMigrationProgress | null,
+  ) => Effect.Effect<void>;
 }
 
 interface ActiveBackendRun {
@@ -893,6 +900,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
                 );
 
               if (isCurrentRun) {
+                yield* spec.onMigrationProgress?.(null) ?? Effect.void;
                 yield* desktopTelemetryPublisher.removeControlSource(spec.id);
                 if (Option.isSome(pid)) {
                   if (exitObserved && !stopRequested) {
@@ -936,6 +944,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
               pid: Option.some(pid),
             }));
             yield* Ref.set(outputTail, "");
+            yield* spec.onMigrationProgress?.(null) ?? Effect.void;
             outputDecoders = makeOutputDecoders();
             yield* backendOutputLog.beginSession({
               details: `pid=${pid} port=${config.value.bootstrap.port} cwd=${config.value.cwd}`,
@@ -966,6 +975,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
               return;
             }
 
+            yield* spec.onMigrationProgress?.(null) ?? Effect.void;
             yield* spec.onReady?.(config.value.httpBaseUrl, pid) ?? Effect.void;
             if (
               config.value.runningDistro !== undefined &&
@@ -995,12 +1005,28 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
             },
           ),
           onOutput: (streamName, chunk) =>
-            Ref.update(outputTail, (tail) =>
+            Ref.updateAndGet(outputTail, (tail) =>
               // A cut through a surrogate pair would make encodeURIComponent throw when rendering.
               (tail + outputDecoders[streamName].decode(chunk, { stream: true }))
                 .slice(-STARTUP_FAILURE_OUTPUT_CHARS)
                 .toWellFormed(),
-            ).pipe(Effect.andThen(backendOutputLog.writeOutputChunk(streamName, chunk))),
+            ).pipe(
+              Effect.flatMap((tail) =>
+                Effect.gen(function* () {
+                  const latest = yield* SubscriptionRef.get(state);
+                  if (
+                    !latest.ready &&
+                    Option.isSome(latest.active) &&
+                    latest.active.value.id === runId
+                  ) {
+                    yield* (
+                      spec.onMigrationProgress?.(databaseMigrationProgress(tail)) ?? Effect.void
+                    );
+                  }
+                }),
+              ),
+              Effect.andThen(backendOutputLog.writeOutputChunk(streamName, chunk)),
+            ),
         }).pipe(
           Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
           Effect.provideService(HttpClient.HttpClient, httpClient),
diff --git a/apps/desktop/src/backend/DesktopBackendPool.ts b/apps/desktop/src/backend/DesktopBackendPool.ts
index d69e1ce1427fe..8e1ba3214e0d7 100644
--- a/apps/desktop/src/backend/DesktopBackendPool.ts
+++ b/apps/desktop/src/backend/DesktopBackendPool.ts
@@ -6,6 +6,7 @@ import * as Context from "effect/Context";
 import * as Deferred from "effect/Deferred";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
 import * as Exit from "effect/Exit";
 import * as FiberHandle from "effect/FiberHandle";
 import * as Layer from "effect/Layer";
@@ -124,7 +125,7 @@ export const layer = Layer.effect(
     const electronDialog = yield* ElectronDialog.ElectronDialog;
     const electronApp = yield* ElectronApp.ElectronApp;
     const appSettings = yield* DesktopAppSettings.DesktopAppSettings;
-    const { primaryBackendStartup } = yield* DesktopState.DesktopState;
+    const { primaryBackendStartup, databaseMigrationProgress } = yield* DesktopState.DesktopState;
     // Parent instance scopes to the pool so shutdown runs stop finalizers before the OS kills backends.
     const layerScope = yield* Scope.Scope;
     const factoryContext = yield* Effect.context<BackendInstanceFactoryRequirements>();
@@ -226,6 +227,7 @@ export const layer = Layer.effect(
         ),
       onStartupFailure: (failure) =>
         SubscriptionRef.set(primaryBackendStartup, { _tag: "Failing", ...failure }),
+      onMigrationProgress: (progress) => Ref.set(databaseMigrationProgress, progress),
       onShutdown: () =>
         FiberHandle.clear(updateMarkerWait).pipe(
           Effect.andThen(desktopWindow.handleBackendNotReady),
diff --git a/apps/desktop/src/ipc/DesktopIpcHandlers.ts b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
index 57d7101cf9ec7..e4c1ed852d87f 100644
--- a/apps/desktop/src/ipc/DesktopIpcHandlers.ts
+++ b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
@@ -35,6 +35,7 @@ import {
 } from "./methods/updates.ts";
 import {
   getAppBranding,
+  getDatabaseMigrationProgress,
   getLocalEnvironmentBootstraps,
   getLocalEnvironmentBearerToken,
   installRelayTelemetryEnabled,
@@ -98,6 +99,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
   yield* ipc.handleSync(takeLegacyLocalStorage);
   yield* ipc.handle(completeLegacyLocalStorage);
   yield* ipc.handleSync(getAppBranding);
+  yield* ipc.handle(getDatabaseMigrationProgress);
   yield* installRelayTelemetryEnabled();
   yield* ipc.handleSync(getSystemLocale);
   yield* ipc.handleSync(getPreferredSystemLanguages);
diff --git a/apps/desktop/src/ipc/channels.ts b/apps/desktop/src/ipc/channels.ts
index b7bb5e579572f..973452a009596 100644
--- a/apps/desktop/src/ipc/channels.ts
+++ b/apps/desktop/src/ipc/channels.ts
@@ -35,6 +35,7 @@ export const CLI_COMMAND_INSTALL_CHANNEL = "desktop:cli-command-install";
 export const CLI_COMMAND_UNINSTALL_CHANNEL = "desktop:cli-command-uninstall";
 export const CLI_COMMAND_ADD_TO_PATH_CHANNEL = "desktop:cli-command-add-to-path";
 export const GET_APP_BRANDING_CHANNEL = "desktop:get-app-branding";
+export const GET_DATABASE_MIGRATION_PROGRESS_CHANNEL = "desktop:get-database-migration-progress";
 export const GET_RELAY_TELEMETRY_ENABLED_CHANNEL = "desktop:get-relay-telemetry-enabled";
 export const GET_SYSTEM_LOCALE_CHANNEL = "desktop:get-system-locale";
 export const GET_PREFERRED_SYSTEM_LANGUAGES_CHANNEL = "desktop:get-preferred-system-languages";
diff --git a/apps/desktop/src/ipc/methods/window.ts b/apps/desktop/src/ipc/methods/window.ts
index cee92e1ead38c..3b858c2844960 100644
--- a/apps/desktop/src/ipc/methods/window.ts
+++ b/apps/desktop/src/ipc/methods/window.ts
@@ -2,6 +2,7 @@ import {
   ContextMenuItemSchema,
   ContextMenuSource,
   DesktopAppBrandingSchema,
+  DatabaseMigrationProgress,
   DesktopEnvironmentBootstrapSchema,
   DesktopMediaReadSchema,
   DesktopThemeSchema,
@@ -24,6 +25,8 @@ import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
+import * as Ref from "effect/Ref";
+import * as DesktopState from "../../app/DesktopState.ts";
 
 import * as DesktopBackendConfiguration from "../../backend/DesktopBackendConfiguration.ts";
 import * as DesktopBackendManager from "../../backend/DesktopBackendManager.ts";
@@ -69,6 +72,16 @@ function toWebSocketBaseUrl(httpBaseUrl: URL): string {
   return url.href;
 }
 
+export const getDatabaseMigrationProgress = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.GET_DATABASE_MIGRATION_PROGRESS_CHANNEL,
+  payload: Schema.Void,
+  result: Schema.NullOr(DatabaseMigrationProgress),
+  handler: Effect.fn("desktop.ipc.window.getDatabaseMigrationProgress")(function* () {
+    const state = yield* DesktopState.DesktopState;
+    return yield* Ref.get(state.databaseMigrationProgress);
+  }),
+});
+
 export const getAppBranding = DesktopIpc.makeSyncIpcMethod({
   channel: IpcChannels.GET_APP_BRANDING_CHANNEL,
   result: Schema.NullOr(DesktopAppBrandingSchema),
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index e0ac5f2161051..9c517169d3637 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -104,6 +104,8 @@ function unwrapEnsureSshEnvironmentResult(result: unknown) {
 }
 
 contextBridge.exposeInMainWorld("desktopBridge", {
+  getDatabaseMigrationProgress: () =>
+    ipcRenderer.invoke(IpcChannels.GET_DATABASE_MIGRATION_PROGRESS_CHANNEL),
   getAppBranding: () => {
     const result = ipcRenderer.sendSync(IpcChannels.GET_APP_BRANDING_CHANNEL);
     if (typeof result !== "object" || result === null) {
diff --git a/apps/server/src/httpResponseErrorGuard.test.ts b/apps/server/src/httpResponseErrorGuard.test.ts
index 7227e03dade0a..6ed044f6dba90 100644
--- a/apps/server/src/httpResponseErrorGuard.test.ts
+++ b/apps/server/src/httpResponseErrorGuard.test.ts
@@ -27,7 +27,12 @@ function fetchResponse(
   port: number,
   path: string,
   upgrade = false,
-): Promise<NodeHttp.IncomingMessage> {
+  accept?: string,
+): Promise<{
+  statusCode: number | undefined;
+  headers: NodeHttp.IncomingHttpHeaders;
+  body: string;
+}> {
   return new Promise((resolve, reject) => {
     const request = NodeHttp.get(
       {
@@ -35,26 +40,35 @@ function fetchResponse(
         port,
         path,
         agent: false,
-        headers: upgrade
-          ? {
-              connection: "Upgrade",
-              upgrade: "websocket",
-              "sec-websocket-key": "dGhlIHNhbXBsZSBub25jZQ==",
-              "sec-websocket-version": "13",
-            }
-          : {},
+        headers: {
+          ...(accept ? { accept } : {}),
+          ...(upgrade
+            ? {
+                connection: "Upgrade",
+                upgrade: "websocket",
+                "sec-websocket-key": "dGhlIHNhbXBsZSBub25jZQ==",
+                "sec-websocket-version": "13",
+              }
+            : {}),
+        },
       },
       (response) => {
         response.on("error", reject);
-        response.on("end", () => resolve(response));
-        response.resume();
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk: string) => {
+          body += chunk;
+        });
+        response.on("end", () =>
+          resolve({ statusCode: response.statusCode, headers: response.headers, body }),
+        );
       },
     );
     requests.push(request);
     request.on("error", reject);
     request.on("upgrade", (response, socket) => {
       socket.destroy();
-      resolve(response);
+      resolve({ statusCode: response.statusCode, headers: response.headers, body: "" });
     });
   });
 }
@@ -205,8 +219,10 @@ describe("keepIdleConnections", () => {
 describe("rejectRequestsUntilServing", () => {
   it("rejects early HTTP and upgrades, then hands each off to its serving handler", async () => {
     const writeErrors: unknown[] = [];
+    let progress: { current: number; total: number } | null = { current: 2, total: 7 };
     const server = HttpResponseErrorGuard.rejectRequestsUntilServing(
       guardHttpResponseWriteErrors(NodeHttp.createServer(), (error) => writeErrors.push(error)),
+      () => progress,
     );
     const port = await listen(server);
 
@@ -214,6 +230,26 @@ describe("rejectRequestsUntilServing", () => {
     expect(earlyHttp.statusCode).toBe(503);
     expect(earlyHttp.headers["retry-after"]).toBe("1");
 
+    const startup = await fetchResponse(
+      port,
+      "/?name=<script>alert(1)</script>",
+      false,
+      "text/html",
+    );
+    const startupHtml = startup.body;
+    expect(startupHtml).toContain("Upgrading database (2 of 7)");
+    expect(startupHtml).not.toContain("<script>");
+    expect(startup.headers["cache-control"]).toBe("no-store");
+    expect(startup.headers["content-security-policy"]).toContain("default-src 'none'");
+    progress = { current: 3, total: 7 };
+    const step = await fetchResponse(port, "/.well-known/t3/environment");
+    expect(JSON.parse(step.body)).toEqual({ status: "starting", migration: progress });
+    progress = null;
+    const finished = await fetchResponse(port, "/.well-known/t3/environment");
+    expect(JSON.parse(finished.body)).toEqual({ status: "starting", migration: null });
+    const finishingPage = await fetchResponse(port, "/", false, "text/html");
+    expect(finishingPage.body).not.toContain("Upgrading database");
+
     const earlyUpgrade = await fetchResponse(port, "/rpc", true);
     expect(earlyUpgrade.statusCode).toBe(503);
     expect(earlyUpgrade.headers["retry-after"]).toBe("1");
diff --git a/apps/server/src/httpResponseErrorGuard.ts b/apps/server/src/httpResponseErrorGuard.ts
index c75ccae660a55..fb7f22b32f527 100644
--- a/apps/server/src/httpResponseErrorGuard.ts
+++ b/apps/server/src/httpResponseErrorGuard.ts
@@ -2,6 +2,7 @@
 // @effect-diagnostics nodeBuiltinImport:off
 import type * as NodeHttp from "node:http";
 import type * as NodeStream from "node:stream";
+import type { DatabaseMigrationProgress, ServerStartupStatus } from "@t3tools/contracts";
 
 export function guardHttpResponseWriteErrors<T extends NodeHttp.Server>(
   server: T,
@@ -51,9 +52,31 @@ export function keepIdleConnections<T extends NodeHttp.Server>(server: T): T {
  * between would hang. Install this after the write-error guards so only the
  * serving handlers trigger the handoff.
  */
-export function rejectRequestsUntilServing<T extends NodeHttp.Server>(server: T): T {
-  const rejectRequest = (_request: NodeHttp.IncomingMessage, response: NodeHttp.ServerResponse) => {
-    response.writeHead(503, { "retry-after": "1", connection: "close" }).end();
+export function rejectRequestsUntilServing<T extends NodeHttp.Server>(
+  server: T,
+  migrationProgress: () => DatabaseMigrationProgress | null = () => null,
+): T {
+  const rejectRequest = (request: NodeHttp.IncomingMessage, response: NodeHttp.ServerResponse) => {
+    const migration = migrationProgress();
+    const html = request.headers.accept?.includes("text/html") === true;
+    const status: ServerStartupStatus = { status: "starting", migration };
+    const message = migration
+      ? `Upgrading database (${migration.current} of ${migration.total})`
+      : "Starting T3 Code…";
+    const body = html
+      ? `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="refresh" content="1"><title>Starting T3 Code</title><style>:root{color-scheme:light dark}body{margin:0;min-height:100vh;display:grid;place-content:center;text-align:center;font:16px system-ui}h1{font-size:20px}p{opacity:.7}</style></head><body><h1>${message}</h1><p>The app will open when startup finishes.</p></body></html>`
+      : JSON.stringify(status);
+    response
+      .writeHead(503, {
+        "retry-after": "1",
+        connection: "close",
+        "cache-control": "no-store",
+        "content-type": html ? "text/html; charset=utf-8" : "application/json; charset=utf-8",
+        "content-security-policy":
+          "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'",
+        "x-content-type-options": "nosniff",
+      })
+      .end(body);
   };
   const rejectUpgrade = (_request: NodeHttp.IncomingMessage, socket: NodeStream.Duplex) => {
     socket.end(
diff --git a/apps/server/src/persistence/DatabaseMigrationProgress.ts b/apps/server/src/persistence/DatabaseMigrationProgress.ts
new file mode 100644
index 0000000000000..2b8d5bf522a86
--- /dev/null
+++ b/apps/server/src/persistence/DatabaseMigrationProgress.ts
@@ -0,0 +1,15 @@
+import type { DatabaseMigrationProgress as Progress } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import * as Effect from "effect/Effect";
+
+export class DatabaseMigrationProgress extends Context.Service<
+  DatabaseMigrationProgress,
+  { readonly current: Ref.Ref<Progress | null> }
+>()("t3/persistence/DatabaseMigrationProgress") {}
+
+export const layer = Layer.effect(
+  DatabaseMigrationProgress,
+  Effect.map(Ref.make<Progress | null>(null), (current) => ({ current })),
+);
diff --git a/apps/server/src/persistence/Migrations.test.ts b/apps/server/src/persistence/Migrations.test.ts
index 64705e4bbb8f5..f1d1f391b2c33 100644
--- a/apps/server/src/persistence/Migrations.test.ts
+++ b/apps/server/src/persistence/Migrations.test.ts
@@ -6,6 +6,16 @@ import * as Exit from "effect/Exit";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import * as SqlClient from "effect/sql/SqlClient";
+import * as Ref from "effect/Ref";
+import * as Logger from "effect/Logger";
+import * as Console from "effect/Console";
+import * as NodeUtil from "node:util";
+import type { DatabaseMigrationProgress as Progress } from "@t3tools/contracts";
+import {
+  databaseMigrationProgress,
+  DATABASE_MIGRATION_PROGRESS_MESSAGE,
+} from "@t3tools/shared/databaseMigrationLog";
+import * as DatabaseMigrationProgress from "./DatabaseMigrationProgress.ts";
 
 import { migrationManifest, runMigrations } from "./Migrations.ts";
 
@@ -72,7 +82,44 @@ describe("runMigrations", () => {
   it.effect("upgrades a database at exactly 54", () =>
     Effect.gen(function* () {
       yield* runMigrations({ toMigrationInclusive: 54 });
-      assert.deepStrictEqual(yield* runMigrations(), v2Migrations);
+      const current = yield* Ref.make<Progress | null>(null);
+      const steps: Array<Progress | null> = [];
+      const loggedSteps: Array<Progress | null> = [];
+      let output = "";
+      const pretty = Logger.consolePretty({ mode: "tty", colors: false });
+      const logger = Logger.make((options) => {
+        pretty.log(options);
+        if (String(options.message).startsWith(DATABASE_MIGRATION_PROGRESS_MESSAGE)) {
+          steps.push(Ref.getUnsafe(current));
+          loggedSteps.push(databaseMigrationProgress(output.slice(-4_000)));
+        }
+      });
+      assert.deepStrictEqual(
+        yield* runMigrations().pipe(
+          Effect.provideService(DatabaseMigrationProgress.DatabaseMigrationProgress, { current }),
+          Effect.provide(Logger.layer([logger], { mergeWithExisting: false })),
+          Effect.provideService(Console.Console, {
+            ...globalThis.console,
+            log: (...args) => {
+              output += `${NodeUtil.format(...args)}\n`;
+            },
+          }),
+        ),
+        v2Migrations,
+      );
+      assert.deepStrictEqual(
+        steps,
+        v2Migrations.map((_, index) => ({ current: index + 1, total: v2Migrations.length })),
+      );
+      assert.deepStrictEqual(loggedSteps, steps);
+      assert.isNull(yield* Ref.get(current));
+      assert.deepStrictEqual(
+        yield* runMigrations().pipe(
+          Effect.provideService(DatabaseMigrationProgress.DatabaseMigrationProgress, { current }),
+        ),
+        [],
+      );
+      assert.isNull(yield* Ref.get(current));
       assert.deepStrictEqual(yield* history, migrationManifest);
       assert.isAbove(yield* v2TableCount, 0);
     }).pipe(Effect.provide(NodeSqliteClient.layer({ filename: ":memory:" }))),
@@ -157,9 +204,15 @@ describe("runMigrations", () => {
       yield* runMigrations({ toMigrationInclusive: 81 });
       yield* sql`CREATE TABLE orchestration_v2_projection_turn_item_counts (thread_id TEXT)`;
 
-      const exit = yield* Effect.exit(runMigrations());
+      const current = yield* Ref.make<Progress | null>(null);
+      const exit = yield* Effect.exit(
+        runMigrations().pipe(
+          Effect.provideService(DatabaseMigrationProgress.DatabaseMigrationProgress, { current }),
+        ),
+      );
 
       assert.isTrue(Exit.isFailure(exit));
+      assert.isNull(yield* Ref.get(current));
       assert.deepStrictEqual(
         yield* history,
         migrationManifest.filter(([id]) => id <= 84),
diff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.ts
index 1279fe9e60364..af9dda4696c74 100644
--- a/apps/server/src/persistence/Migrations.ts
+++ b/apps/server/src/persistence/Migrations.ts
@@ -1,6 +1,9 @@
 import * as Migrator from "effect/sql/Migrator";
 import * as Effect from "effect/Effect";
 import * as SqlClient from "effect/sql/SqlClient";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as DatabaseMigrationProgress from "./DatabaseMigrationProgress.ts";
 import {
   DATABASE_MIGRATION_PROGRESS_MESSAGE,
   DATABASE_MIGRATIONS_FINISHED_MESSAGE,
@@ -278,69 +281,87 @@ export interface RunMigrationsOptions {
   readonly toMigrationInclusive?: number | undefined;
 }
 
-export const runMigrations = Effect.fn("runMigrations")(function* ({
-  toMigrationInclusive,
-}: RunMigrationsOptions = {}) {
-  // The desktop waits past its readiness budget until the finished line follows this one.
-  if (yield* hasPendingMigrations()) yield* Effect.log(DATABASE_MIGRATIONS_STARTED_MESSAGE);
-  const includesV2 =
-    toMigrationInclusive === undefined || toMigrationInclusive >= FIRST_V2_MIGRATION_ID;
-  const previewMigrations = includesV2 ? yield* reconcileV2PreviewMigration() : [];
-  if (includesV2) {
-    yield* assertV2MigrationsCanRun(toMigrationInclusive);
-  }
-  const sql = yield* SqlClient.SqlClient;
-  const ledger = yield* sql`
+export const runMigrations = Effect.fn("runMigrations")(
+  function* ({ toMigrationInclusive }: RunMigrationsOptions = {}) {
+    const progress = yield* Effect.serviceOption(
+      DatabaseMigrationProgress.DatabaseMigrationProgress,
+    );
+    // The desktop waits past its readiness budget until the finished line follows this one.
+    if (yield* hasPendingMigrations()) yield* Effect.log(DATABASE_MIGRATIONS_STARTED_MESSAGE);
+    const includesV2 =
+      toMigrationInclusive === undefined || toMigrationInclusive >= FIRST_V2_MIGRATION_ID;
+    const previewMigrations = includesV2 ? yield* reconcileV2PreviewMigration() : [];
+    if (includesV2) {
+      yield* assertV2MigrationsCanRun(toMigrationInclusive);
+    }
+    const sql = yield* SqlClient.SqlClient;
+    const ledger = yield* sql`
     SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'effect_sql_migrations'
   `;
-  const [latest] =
-    ledger.length === 0
-      ? []
-      : yield* sql<{
-          readonly id: number | null;
-        }>`SELECT MAX(migration_id) AS id FROM effect_sql_migrations`;
-  const latestRecordedId = latest?.id ?? 0;
-  const pending = migrationEntries.filter(
-    ([id]) =>
-      id > latestRecordedId && (toMigrationInclusive === undefined || id <= toMigrationInclusive),
-  );
-  // One transaction per migration: an index build on a large database can take minutes, and a
-  // restart then resumes after the last finished migration instead of rolling all of them back.
-  const executedMigrations: Array<readonly [id: number, name: string]> = [...previewMigrations];
-  for (const [index, [id, name]] of pending.entries()) {
-    if (latestRecordedId > 0) {
-      yield* Effect.log(DATABASE_MIGRATION_PROGRESS_MESSAGE).pipe(
-        Effect.annotateLogs({
-          migration: `${id}_${name}`,
-          progress: `${index + 1} of ${pending.length}`,
-        }),
-      );
+    const [latest] =
+      ledger.length === 0
+        ? []
+        : yield* sql<{
+            readonly id: number | null;
+          }>`SELECT MAX(migration_id) AS id FROM effect_sql_migrations`;
+    const latestRecordedId = latest?.id ?? 0;
+    const pending = migrationEntries.filter(
+      ([id]) =>
+        id > latestRecordedId && (toMigrationInclusive === undefined || id <= toMigrationInclusive),
+    );
+    // One transaction per migration: an index build on a large database can take minutes, and a
+    // restart then resumes after the last finished migration instead of rolling all of them back.
+    const executedMigrations: Array<readonly [id: number, name: string]> = [...previewMigrations];
+    for (const [index, [id, name]] of pending.entries()) {
+      if (Option.isSome(progress)) {
+        yield* Ref.set(progress.value.current, { current: index + 1, total: pending.length });
+      }
+      if (latestRecordedId > 0) {
+        yield* Effect.log(
+          `${DATABASE_MIGRATION_PROGRESS_MESSAGE} (${index + 1} of ${pending.length})`,
+        ).pipe(
+          Effect.annotateLogs({
+            migration: `${id}_${name}`,
+            progress: `${index + 1} of ${pending.length}`,
+          }),
+        );
+      }
+      executedMigrations.push(...(yield* run({ loader: makeMigrationLoader(id) })));
     }
-    executedMigrations.push(...(yield* run({ loader: makeMigrationLoader(id) })));
-  }
-  const migrations = executedMigrations.map(([id, name]) => `${id}_${name}`);
-  yield* migrations.length === 0
-    ? Effect.logDebug("Database schema is current")
-    : Effect.log(DATABASE_MIGRATIONS_FINISHED_MESSAGE).pipe(Effect.annotateLogs({ migrations }));
+    const migrations = executedMigrations.map(([id, name]) => `${id}_${name}`);
+    yield* migrations.length === 0
+      ? Effect.logDebug("Database schema is current")
+      : Effect.log(DATABASE_MIGRATIONS_FINISHED_MESSAGE).pipe(Effect.annotateLogs({ migrations }));
 
-  const recorded = yield* sql<{
-    readonly migration_id: number;
-    readonly name: string;
-  }>`SELECT migration_id, name FROM effect_sql_migrations`;
-  const manifestNames = new Map<number, string>(migrationEntries.map(([id, name]) => [id, name]));
-  const divergent = recorded.flatMap((row) => {
-    const expected = manifestNames.get(row.migration_id);
-    if (expected === undefined) {
-      return [`${row.migration_id}:${row.name} (unknown to this build)`];
+    const recorded = yield* sql<{
+      readonly migration_id: number;
+      readonly name: string;
+    }>`SELECT migration_id, name FROM effect_sql_migrations`;
+    const manifestNames = new Map<number, string>(migrationEntries.map(([id, name]) => [id, name]));
+    const divergent = recorded.flatMap((row) => {
+      const expected = manifestNames.get(row.migration_id);
+      if (expected === undefined) {
+        return [`${row.migration_id}:${row.name} (unknown to this build)`];
+      }
+      return expected === row.name
+        ? []
+        : [`${row.migration_id}:${row.name} (this build: ${expected})`];
+    });
+    if (divergent.length > 0) {
+      yield* Effect.logWarning(
+        "Database migration history diverges from this build; recorded migration ids are skipped, not reconciled by name.",
+      ).pipe(Effect.annotateLogs({ divergent }));
     }
-    return expected === row.name
-      ? []
-      : [`${row.migration_id}:${row.name} (this build: ${expected})`];
-  });
-  if (divergent.length > 0) {
-    yield* Effect.logWarning(
-      "Database migration history diverges from this build; recorded migration ids are skipped, not reconciled by name.",
-    ).pipe(Effect.annotateLogs({ divergent }));
-  }
-  return executedMigrations;
-});
+    return executedMigrations;
+  },
+  (effect, _options: RunMigrationsOptions = {}) =>
+    Effect.ensuring(
+      effect,
+      Effect.gen(function* () {
+        const progress = yield* Effect.serviceOption(
+          DatabaseMigrationProgress.DatabaseMigrationProgress,
+        );
+        if (Option.isSome(progress)) yield* Ref.set(progress.value.current, null);
+      }),
+    ),
+);
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 8b1cce579162f..a5ecfec66cf8d 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -1,4 +1,5 @@
 import * as ProviderEventLoggers from "@t3tools/provider-core/server/ProviderEventLoggers";
+import * as DatabaseMigrationProgress from "./persistence/DatabaseMigrationProgress.ts";
 import type { RelayManagedEndpointRuntimeConfig } from "@t3tools/contracts/relay";
 import * as Random from "effect/Random";
 import * as EnvironmentKeys from "./cloud/environmentKeys.ts";
@@ -22,6 +23,7 @@ import * as Duration from "effect/Duration";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
 import * as Layer from "effect/Layer";
 import * as Stream from "effect/Stream";
 import { FetchHttpClient, HttpRouter, HttpServer } from "effect/http";
@@ -351,6 +353,7 @@ const layerRelayClient = Layer.unwrap(
 const layerHttpServer = Layer.unwrap(
   Effect.gen(function* () {
     const config = yield* ServerConfig.ServerConfig;
+    const migrationProgress = yield* DatabaseMigrationProgress.DatabaseMigrationProgress;
     // Before binding: a host the policy does not allow must never listen, not even briefly.
     const policy = yield* ManagedPolicy.ManagedPolicy;
     const bindHost = yield* ManagedLimits.checkServerReachability(policy, {
@@ -364,6 +367,7 @@ const layerHttpServer = Layer.unwrap(
       () => {
         const server = rejectRequestsUntilServing(
           keepIdleConnections(guardHttpResponseWriteErrors(NodeHttp.createServer())),
+          () => Ref.getUnsafe(migrationProgress.current),
         );
         if (config.privateNetworkOnly) {
           server.on("connection", (socket) => {
@@ -1345,6 +1349,7 @@ const layerMakeServer = Layer.unwrap(
         RelayTracing.layerServerRelayBroker.pipe(Layer.provide(ManagedPolicy.layer)),
       ),
       Layer.provideMerge(layerHttpServer),
+      Layer.provide(DatabaseMigrationProgress.layer),
       Layer.provide(layerApplicationObservability),
       Layer.provideMerge(FetchHttpClient.layer),
       Layer.provide(VcsProcess.layer),
diff --git a/apps/web/index.html b/apps/web/index.html
index 051e3090a5d48..7f8be6fa934c7 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -445,6 +445,15 @@
         object-fit: contain;
       }
 
+      #boot-shell-progress {
+        position: absolute;
+        top: 100%;
+        width: min(360px, 80vw);
+        text-align: center;
+        font: 13px system-ui;
+        opacity: 0.7;
+      }
+
       /* App CSS locks body and #root scrolling once main loads, so the error screen scrolls itself. */
       #boot-shell:has(> #boot-error) {
         height: 100%;
@@ -688,9 +697,29 @@
       <div id="boot-shell">
         <div id="boot-shell-card" aria-label="T3 Code splash screen">
           <img id="boot-shell-logo" src="/apple-touch-icon.png" alt="T3 Code" />
+          <p id="boot-shell-progress" role="status" aria-live="polite"></p>
         </div>
       </div>
     </div>
+    <script>
+      const migrationLabel = document.getElementById("boot-shell-progress");
+      const readMigrationProgress = window.desktopBridge?.getDatabaseMigrationProgress;
+      if (readMigrationProgress && migrationLabel) {
+        const updateMigrationProgress = async () => {
+          if (!migrationLabel.isConnected) return;
+          try {
+            const progress = await readMigrationProgress();
+            migrationLabel.textContent = progress
+              ? `Upgrading database (${progress.current} of ${progress.total})`
+              : "";
+          } catch {
+            migrationLabel.textContent = "";
+          }
+          if (migrationLabel.isConnected) setTimeout(updateMigrationProgress, 1000);
+        };
+        void updateMigrationProgress();
+      }
+    </script>
     <script type="module" src="/src/bootstrap.ts"></script>
   </body>
 </html>
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 8f5258596c5f5..be28cbbb15631 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -1,4 +1,5 @@
 import * as Schema from "effect/Schema";
+import type { DatabaseMigrationProgress } from "./server.ts";
 import type { PreviewCaptureFailureEncoded } from "./previewCapture.ts";
 
 import { SnapShotSource } from "./chatAttachment.ts";
@@ -1052,6 +1053,7 @@ export type SystemSettingsPane = typeof SystemSettingsPaneSchema.Type;
 
 export interface DesktopBridge {
   getAppBranding: () => DesktopAppBranding | null;
+  getDatabaseMigrationProgress?: () => Promise<DatabaseMigrationProgress | null>;
   getRelayTelemetryEnabled: () => boolean;
   getPathForFile: (file: File) => string;
   getClientPlatform: () => string;
diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts
index d859ecb91ffa4..3031e9937550f 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -983,6 +983,18 @@ export class ServerProviderUpdateError extends Schema.TaggedError<ServerProvider
   }
 }
 
+export const DatabaseMigrationProgress = Schema.Struct({
+  current: Schema.Int.check(Schema.isGreaterThan(0)),
+  total: Schema.Int.check(Schema.isGreaterThan(0)),
+});
+export type DatabaseMigrationProgress = typeof DatabaseMigrationProgress.Type;
+
+export const ServerStartupStatus = Schema.Struct({
+  status: Schema.Literal("starting"),
+  migration: Schema.NullOr(DatabaseMigrationProgress),
+});
+export type ServerStartupStatus = typeof ServerStartupStatus.Type;
+
 export const ServerNpmReleaseInput = Schema.Struct({
   spec: Schema.String.check(
     Schema.isMaxLength(64),
diff --git a/packages/shared/src/databaseMigrationLog.test.ts b/packages/shared/src/databaseMigrationLog.test.ts
new file mode 100644
index 0000000000000..783b33cddae39
--- /dev/null
+++ b/packages/shared/src/databaseMigrationLog.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  databaseMigrationProgress,
+  DATABASE_MIGRATION_PROGRESS_MESSAGE as STEP,
+  DATABASE_MIGRATIONS_STARTED_MESSAGE as START,
+  DATABASE_MIGRATIONS_FINISHED_MESSAGE as FINISH,
+} from "./databaseMigrationLog.ts";
+
+describe("databaseMigrationProgress", () => {
+  it.each([
+    ["", null],
+    [START, null],
+    [`${STEP} (2 of 7)\n  progress: 2 of 7\n`, { current: 2, total: 7 }],
+    [`${STEP} (2 of 7`, null],
+    [`${STEP} (8 of 7)\n`, null],
+    [`${STEP} progress="1 of 7"\n${STEP} progress="2 of 7"`, { current: 2, total: 7 }],
+    [`${STEP} migration=<script>alert(1)</script> progress="2 of 7"`, { current: 2, total: 7 }],
+    [`{"message":"${STEP}","progress":"3 of 7"}`, { current: 3, total: 7 }],
+    [`${STEP} progress="2 of 7`, null],
+    [`${STEP} progress="0 of 7"`, null],
+    [`${STEP} progress="8 of 7"`, null],
+    [`${STEP} progress="1 of 99999999999999999999"`, null],
+    [`${STEP} progress="2 of 7"\n${FINISH}`, null],
+    [`${STEP} progress="2 of 7"\n${START}`, null],
+    [`${FINISH}\n${START}\n${STEP} progress="1 of 5"`, { current: 1, total: 5 }],
+  ])("reads the current complete progress from %s", (output, expected) => {
+    expect(databaseMigrationProgress(output)).toEqual(expected);
+  });
+});
diff --git a/packages/shared/src/databaseMigrationLog.ts b/packages/shared/src/databaseMigrationLog.ts
index 7adc4e4a6c84c..12d953b9828b5 100644
--- a/packages/shared/src/databaseMigrationLog.ts
+++ b/packages/shared/src/databaseMigrationLog.ts
@@ -1,5 +1,7 @@
 // The server logs these around pending migrations; the desktop reads them from its output tail,
 // which keeps only the last few thousand characters, so each progress line also marks a running upgrade.
+import type { DatabaseMigrationProgress } from "@t3tools/contracts";
+
 export const DATABASE_MIGRATIONS_STARTED_MESSAGE = "Running database migrations";
 export const DATABASE_MIGRATION_PROGRESS_MESSAGE = "Upgrading database";
 export const DATABASE_MIGRATIONS_FINISHED_MESSAGE = "Migrations ran successfully";
@@ -12,3 +14,23 @@ export function isRunningDatabaseMigrations(output: string): boolean {
     ) > output.lastIndexOf(DATABASE_MIGRATIONS_FINISHED_MESSAGE)
   );
 }
+
+export function databaseMigrationProgress(output: string): DatabaseMigrationProgress | null {
+  if (!isRunningDatabaseMigrations(output)) return null;
+  const start = output.lastIndexOf(DATABASE_MIGRATIONS_STARTED_MESSAGE);
+  const line = output.slice(
+    Math.max(start, output.lastIndexOf(DATABASE_MIGRATION_PROGRESS_MESSAGE)),
+  );
+  const match =
+    /^Upgrading database \((\d+) of (\d+)\)/.exec(line) ??
+    /(?:progress=|"progress"\s*:\s*)"(\d+) of (\d+)"/.exec(line);
+  if (!match) return null;
+  const current = Number(match[1]);
+  const total = Number(match[2]);
+  return Number.isSafeInteger(current) &&
+    Number.isSafeInteger(total) &&
+    current > 0 &&
+    current <= total
+    ? { current, total }
+    : null;
+}

From dff60ec66739f42de5f8add401da1b7ef1af0a77 Mon Sep 17 00:00:00 2001
From: perry gupta <cg077593@gmail.com>
Date: Sun, 15 Nov 2026 18:25:23 +0530
Subject: [PATCH 2/2] fix(desktop): show migration progress in WSL splash

---
 apps/desktop/src/window/DesktopWindow.test.ts | 28 ++++++++++++-
 apps/desktop/src/window/DesktopWindow.ts      | 40 ++++++++++++++++---
 2 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/apps/desktop/src/window/DesktopWindow.test.ts b/apps/desktop/src/window/DesktopWindow.test.ts
index f66586503e24d..892fcb99c6706 100644
--- a/apps/desktop/src/window/DesktopWindow.test.ts
+++ b/apps/desktop/src/window/DesktopWindow.test.ts
@@ -114,7 +114,7 @@ function makeFakeBrowserWindow() {
     isMaximized: vi.fn(() => false),
     isMinimized: vi.fn(() => false),
     isVisible: vi.fn(() => true),
-    loadURL: vi.fn(() => Promise.resolve()),
+    loadURL: vi.fn<(url: string) => Promise<void>>(() => Promise.resolve()),
     maximize: vi.fn(),
     on: vi.fn((eventName: string, listener: (...args: readonly unknown[]) => void) => {
       windowListeners.set(eventName, listener);
@@ -484,6 +484,7 @@ const makeSplashScenario = (createOutcomes: readonly (Electron.BrowserWindow | n
           }),
         ),
       ),
+      Layer.merge(DesktopState.layer),
     );
 
     return { layer, createCalls, mainWindow, revealedWindows } as const;
@@ -1559,9 +1560,21 @@ describe("DesktopWindow", () => {
 
         yield* Effect.gen(function* () {
           const desktopWindow = yield* DesktopWindow.DesktopWindow;
+          const state = yield* DesktopState.DesktopState;
+          const splashHtml = () =>
+            decodeURIComponent(String(splash.loadURL.mock.calls.at(-1)?.[0]).split(",")[1] ?? "");
 
           yield* desktopWindow.showConnectingSplash;
           assert.equal(yield* Ref.get(scenario.createCalls), 1);
+          yield* TestClock.adjust("1 second");
+          assert.include(splashHtml(), "Connecting to WSL…");
+          const initialLoads = splash.loadURL.mock.calls.length;
+          yield* TestClock.adjust("1 second");
+          assert.equal(splash.loadURL.mock.calls.length, initialLoads);
+
+          yield* Ref.set(state.databaseMigrationProgress, { current: 2, total: 7 });
+          yield* TestClock.adjust("1 second");
+          assert.include(splashHtml(), "Upgrading database (2 of 7)");
 
           const readyExit = yield* Effect.exit(
             desktopWindow.handleBackendReady(new URL("http://127.0.0.1:3773")),
@@ -1570,11 +1583,24 @@ describe("DesktopWindow", () => {
           assert.equal(yield* Ref.get(scenario.createCalls), 2);
           assert.isTrue(Option.isNone(yield* Ref.get(scenario.mainWindow)));
 
+          yield* Ref.set(state.databaseMigrationProgress, { current: 3, total: 7 });
+          yield* TestClock.adjust("1 second");
+          assert.include(splashHtml(), "Upgrading database (3 of 7)");
+          yield* Ref.set(state.databaseMigrationProgress, null);
+          yield* TestClock.adjust("1 second");
+          assert.include(splashHtml(), "Connecting to WSL…");
+          assert.notInclude(splashHtml(), "Upgrading database");
+
           yield* desktopWindow.activate;
           assert.equal(yield* Ref.get(scenario.createCalls), 3);
           const registeredMain = yield* Ref.get(scenario.mainWindow);
           assert.isTrue(Option.isSome(registeredMain));
           assert.equal(Option.getOrThrow(registeredMain), main.window);
+          splash.windowListeners.get("closed")?.();
+          const loadsAtClose = splash.loadURL.mock.calls.length;
+          yield* Ref.set(state.databaseMigrationProgress, { current: 4, total: 7 });
+          yield* TestClock.adjust("2 seconds");
+          assert.equal(splash.loadURL.mock.calls.length, loadsAtClose);
         }).pipe(Effect.provide(scenario.layer));
       }),
   );
diff --git a/apps/desktop/src/window/DesktopWindow.ts b/apps/desktop/src/window/DesktopWindow.ts
index 7be14bc720838..bcfc42634202c 100644
--- a/apps/desktop/src/window/DesktopWindow.ts
+++ b/apps/desktop/src/window/DesktopWindow.ts
@@ -6,11 +6,16 @@ import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
 import * as Schema from "effect/Schema";
+import * as Schedule from "effect/Schedule";
 import * as Semaphore from "effect/Semaphore";
 
 import * as Electron from "electron";
 
-import { type DesktopSnapShotEvent, DEFAULT_CLIENT_SETTINGS } from "@t3tools/contracts";
+import {
+  type DatabaseMigrationProgress,
+  type DesktopSnapShotEvent,
+  DEFAULT_CLIENT_SETTINGS,
+} from "@t3tools/contracts";
 
 import * as DesktopAssets from "../app/DesktopAssets.ts";
 import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
@@ -260,12 +265,18 @@ export function resolveInitialMainWindowBounds(
   return DesktopAppSettings.DEFAULT_MAIN_WINDOW_SIZE;
 }
 
-function buildConnectingSplashDataUrl(shouldUseDarkColors: boolean): string {
+function buildConnectingSplashDataUrl(
+  shouldUseDarkColors: boolean,
+  progress: DatabaseMigrationProgress | null,
+): string {
   const background = getInitialWindowBackgroundColor(shouldUseDarkColors);
   const label = shouldUseDarkColors ? "#9ca3af" : "#6b7280";
   const accent = shouldUseDarkColors ? "#f8fafc" : "#1f2937";
   const track = shouldUseDarkColors ? "rgba(248,250,252,0.18)" : "rgba(31,41,55,0.18)";
-  const html = `<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'"><style>html,body{margin:0;height:100%}body{background:${background};color:${label};font-family:system-ui,-apple-system,'Segoe UI',sans-serif;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:18px;-webkit-user-select:none;user-select:none;-webkit-app-region:drag}.spinner{width:26px;height:26px;border:3px solid ${track};border-top-color:${accent};border-radius:50%;animation:spin .8s linear infinite}.label{font-size:13px}@keyframes spin{to{transform:rotate(360deg)}}</style></head><body><div class="spinner"></div><div class="label">Connecting to WSL…</div></body></html>`;
+  const message = progress
+    ? `Upgrading database (${progress.current} of ${progress.total})`
+    : "Connecting to WSL…";
+  const html = `<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'"><style>html,body{margin:0;height:100%}body{background:${background};color:${label};font-family:system-ui,-apple-system,'Segoe UI',sans-serif;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:18px;-webkit-user-select:none;user-select:none;-webkit-app-region:drag}.spinner{width:26px;height:26px;border:3px solid ${track};border-top-color:${accent};border-radius:50%;animation:spin .8s linear infinite}.label{font-size:13px}@keyframes spin{to{transform:rotate(360deg)}}</style></head><body><div class="spinner"></div><div class="label">${message}</div></body></html>`;
   return `data:text/html;charset=utf-8,${encodeURIComponent(html)}`;
 }
 
@@ -1082,15 +1093,34 @@ export const make = Effect.gen(function* () {
     }
     yield* rendererHistory.register(splash.webContents, { surface: "splash" });
     yield* Ref.set(splashWindowRef, Option.some(splash));
+    let renderedUrl: string | undefined;
+    const progressFiber = runFork(
+      Effect.gen(function* () {
+        if (splash.isDestroyed() || (yield* Ref.get(desktopState.quitting))) return;
+        const progress = yield* Ref.get(desktopState.databaseMigrationProgress);
+        const url = buildConnectingSplashDataUrl(shouldUseDarkColors, progress);
+        if (url === renderedUrl) return;
+        const loaded = yield* Effect.promise(() =>
+          splash.loadURL(url).then(
+            () => true,
+            () => false,
+          ),
+        );
+        if (loaded) renderedUrl = url;
+      }).pipe(Effect.repeat(Schedule.spaced("1 second"))),
+    );
     splash.once("closed", () => {
-      void runPromise(Ref.set(splashWindowRef, Option.none()));
+      runFork(
+        Fiber.interrupt(progressFiber).pipe(
+          Effect.andThen(Ref.set(splashWindowRef, Option.none())),
+        ),
+      );
     });
     splash.once("ready-to-show", () => {
       if (!splash.isDestroyed()) {
         splash.show();
       }
     });
-    void splash.loadURL(buildConnectingSplashDataUrl(shouldUseDarkColors));
     yield* logWindowInfo("connecting splash shown");
   }).pipe(
     Effect.catch((error) =>