@remit/web-client 0.0.270 → 0.0.271

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.270",
+  "version": "0.0.271",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/hooks/update-restart-escalation.render.test.ts

@@ -0,0 +1,340 @@
+/**
+ * The update poll against the app's own fail-fast sink (#468).
+ *
+ * An update stops and starts the backend on purpose, so the proxy in front of
+ * it answers 502 for the seconds it is gone. Every other test in this package
+ * mounts on the harness's plain `QueryClient`, which has no global sink, so none
+ * of them can see that the 502 took the whole screen before the update surface
+ * ever read it. Mounted here on the client `shell/index.tsx` builds.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, test } from "node:test";
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
+import { act, createElement } from "react";
+import { SelfUpdateOverlay } from "@/components/self-update/SelfUpdateOverlay";
+import { __resetFatalError, getCurrentFatalError } from "@/lib/fatal-error";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "@/lib/query-error-handler";
+import {
+	APPLY_BUDGET_SECONDS,
+	NEVER_CAME_BACK_MARGIN_SECONDS,
+} from "@/lib/self-update-state";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, httpError, mockFetch } from "../test-support/http";
+import {
+	type SelfUpdateApi,
+	SelfUpdateProvider,
+	useSelfUpdate,
+} from "./use-system-update";
+import "@/lib/client";
+
+const BUDGET_MS =
+	(APPLY_BUDGET_SECONDS + NEVER_CAME_BACK_MARGIN_SECONDS) * 1000;
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+let api: SelfUpdateApi | undefined;
+
+beforeEach(() => {
+	__resetFatalError();
+});
+
+afterEach(() => {
+	__resetFatalError();
+	http?.restore();
+	http = undefined;
+	harness?.close();
+	harness = undefined;
+	api = undefined;
+});
+
+const available = {
+	currentVersion: "0.9.3",
+	check: {
+		status: "ok",
+		updateAvailable: true,
+		latestVersion: "0.9.4",
+		publishedAt: "2026-07-14T09:00:00.000Z",
+		summary: "Faster first sync.",
+		releaseNotesUrl: "https://example.test/notes",
+	},
+	run: null,
+};
+
+const accepted = {
+	currentVersion: "0.9.3",
+	check: { status: "ok", updateAvailable: true, latestVersion: "0.9.4" },
+	run: {
+		runId: "upd_1",
+		fromVersion: "0.9.3",
+		targetVersion: "0.9.4",
+		phase: "stopping",
+		outcome: null,
+		startedAt: "2026-07-20T11:59:30.000Z",
+		updatedAt: "2026-07-20T11:59:45.000Z",
+		message: "Restarting Remit on 0.9.4.",
+		logCommand: "remit logs --since 10m",
+	},
+};
+
+/**
+ * The run as a tab that never pressed install finds it: reported by the server,
+ * started just now, so the wait is measured from a start the page did not see.
+ */
+const reportedRunning = () => ({
+	...accepted,
+	run: { ...accepted.run, startedAt: new Date().toISOString() },
+});
+
+/** The client `shell/index.tsx` builds: the real global escalation sink. */
+const appQueryClient = (): QueryClient =>
+	new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: {
+			queries: { retry: false },
+			mutations: { retry: false },
+		},
+	});
+
+const hook = (): SelfUpdateApi => {
+	if (!api) throw new Error("hook not mounted");
+	return api;
+};
+
+const dom = (): DomHarness => {
+	if (!harness) throw new Error("nothing mounted");
+	return harness;
+};
+
+/** Mount the surface, with `poll` deciding what each `GET /system/update` answers. */
+async function mount(poll: () => unknown): Promise<void> {
+	http = mockFetch((call) => {
+		if (call.path.endsWith("/system/update") && call.method === "GET") {
+			return poll();
+		}
+		return accepted;
+	});
+	const Probe = () => {
+		api = useSelfUpdate();
+		return null;
+	};
+	harness = createDomHarness({ queryClient: appQueryClient() });
+	harness.renderApp(
+		createElement(
+			SelfUpdateProvider,
+			null,
+			createElement(Probe),
+			createElement(SelfUpdateOverlay),
+		),
+	);
+	await settle();
+}
+
+async function settle(): Promise<void> {
+	for (let round = 0; round < 40; round += 1) {
+		await dom().flush();
+		await dom().wait(0);
+	}
+}
+
+/** Press install and wait for the run this page now holds to reach the surface. */
+async function install(): Promise<void> {
+	await act(async () => {
+		hook().install("0.9.4");
+		await dom().flush();
+	});
+	await dom().waitFor(() => {
+		const surface = hook().surface;
+		return surface.status === "ready" && surface.overlay.kind === "applying";
+	}, "the install to be accepted");
+}
+
+async function repoll(): Promise<void> {
+	await act(async () => {
+		hook().onRetryConnection();
+		await dom().flush();
+	});
+	await settle();
+}
+
+describe("the update poll across the restart it asked for (#468)", () => {
+	test("a 502 while a run is held keeps the update surface, not the fatal page", async () => {
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : available));
+		await install();
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError(), null);
+		const surface = hook().surface;
+		assert.equal(
+			surface.status === "ready" &&
+				surface.section.status === "applying" &&
+				surface.section.phase,
+			"reconnecting",
+		);
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+	});
+
+	test("the same 502 with no run held escalates", async () => {
+		await mount(() => httpError(502));
+
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
+
+	test("a 502 with no run known from either source escalates", async () => {
+		// The server has answered, and what it said was that nothing is running.
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : available));
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
+
+	test("a connection refused inside the window stays soft, as any transport failure does", async () => {
+		let restarting = false;
+		await mount(() => {
+			if (restarting) throw new Error("connection refused");
+			return available;
+		});
+		await install();
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError(), null);
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+	});
+
+	test("a 500 while a run is held escalates — the server answered", async () => {
+		let broken = false;
+		await mount(() => (broken ? httpError(500) : available));
+		await install();
+
+		broken = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
+
+	test("a 502 past the apply budget gives up loudly, still not fatally", async () => {
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : available));
+		await install();
+
+		restarting = true;
+		const realNow = Date.now;
+		Date.now = () => realNow() + BUDGET_MS + 60_000;
+		try {
+			await repoll();
+
+			assert.equal(getCurrentFatalError(), null);
+			assert.match(dom().html(), /has not answered since the restart/);
+			assert.match(dom().html(), /remit logs/);
+			assert.doesNotMatch(dom().html(), /Installing Remit 0\.9\.4/);
+		} finally {
+			Date.now = realNow;
+		}
+	});
+});
+
+/**
+ * The overlay speaks for a run in any tab the server tells about it, so the
+ * restart has to be ridden there too — a second tab, or the initiating one after
+ * a reload, holds nothing of its own.
+ */
+describe("a tab that never pressed install (#468)", () => {
+	test("holds the applying overlay across a 502", async () => {
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : reportedRunning()));
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError(), null);
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+	});
+
+	test("gives up loudly past the same apply budget, and names the run's own log command", async () => {
+		let restarting = false;
+		await mount(() => (restarting ? httpError(502) : reportedRunning()));
+
+		restarting = true;
+		const realNow = Date.now;
+		Date.now = () => realNow() + BUDGET_MS + 60_000;
+		try {
+			await repoll();
+
+			assert.equal(getCurrentFatalError(), null);
+			assert.match(dom().html(), /has not answered since the restart/);
+			assert.match(dom().html(), /remit logs --since 10m/);
+			assert.doesNotMatch(dom().html(), /Installing Remit 0\.9\.4/);
+		} finally {
+			Date.now = realNow;
+		}
+	});
+
+	test("a box clock behind the browser's does not spend the budget before the first 502", async () => {
+		// `startedAt` is written on the box. Twenty minutes of skew is more than
+		// the whole budget, so measuring the wait from it would open the screen on
+		// the give-up and never show the install at all.
+		const skewed = () => ({
+			...accepted.run,
+			startedAt: new Date(Date.now() - BUDGET_MS - 60_000).toISOString(),
+		});
+		let restarting = false;
+		await mount(() =>
+			restarting ? httpError(502) : { ...accepted, run: skewed() },
+		);
+
+		restarting = true;
+		await repoll();
+
+		assert.equal(getCurrentFatalError(), null);
+		assert.match(dom().html(), /Installing Remit 0\.9\.4/);
+		assert.doesNotMatch(dom().html(), /has not answered since the restart/);
+
+		// The wait is this tab's, so it still runs out — on this tab's clock.
+		const realNow = Date.now;
+		Date.now = () => realNow() + BUDGET_MS + 60_000;
+		try {
+			await repoll();
+
+			assert.equal(getCurrentFatalError(), null);
+			assert.match(dom().html(), /has not answered since the restart/);
+		} finally {
+			Date.now = realNow;
+		}
+	});
+
+	test("says the service is unreachable once the run it knew about is finished", async () => {
+		let restarting = false;
+		await mount(() =>
+			restarting
+				? httpError(502)
+				: {
+						currentVersion: "0.9.4",
+						check: { status: "ok", updateAvailable: false },
+						run: { ...accepted.run, outcome: "succeeded" },
+					},
+		);
+
+		restarting = true;
+		await repoll();
+
+		const surface = hook().surface;
+		assert.equal(
+			surface.status === "ready" && surface.section.status,
+			"checkFailed",
+		);
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
+});

package/src/hooks/use-system-update.ts

@@ -37,7 +37,11 @@ import {
 	useRef,
 	useState,
 } from "react";
-import { shouldEscalate, softErrorMeta } from "@/lib/error-classifier";
+import {
+	restartExpectedMeta,
+	shouldEscalate,
+	softErrorMeta,
+} from "@/lib/error-classifier";
 import { reportFatalError } from "@/lib/fatal-error";
 import {
 	appliesSchemaMigration,
@@ -48,13 +52,30 @@ import {
 	type HeldRun,
 	isSurfaceAbsent,
 	mapUpdatePhase,
+	type RunSighting,
 	releaseFromCheck,
+	runInFlight,
 	type UpdateSurface,
 } from "@/lib/self-update-state";
 
 const IDLE_POLL_MS = 30_000;
 const RUN_POLL_MS = 5_000;
 
+/**
+ * The poll's own error UX, and — while a run is known to be in flight — the
+ * restart that run performs. Stopping and starting the backend is what the run
+ * is, so the gateway statuses answered while it is down belong to the surface
+ * below, which shows the phase and gives up loudly if the server never comes
+ * back (#468). Outside that window the poll carries no such claim.
+ *
+ * "Known" is either source: the run this page started and holds, or the run the
+ * server last reported as going. The overlay speaks for a run in any tab, so the
+ * window it rides has to open in any tab too — a second tab, or this one after a
+ * reload, holds nothing and would otherwise meet the restart with no claim on it.
+ */
+const POLL_META = softErrorMeta;
+const POLL_ACROSS_RESTART_META = { ...softErrorMeta, ...restartExpectedMeta };
+
 /**
  * How long a pressed check waits for the updater before the pane calls it a
  * failure. The backend only records the request; the updater picks it up on a
@@ -105,16 +126,25 @@ export function useSystemUpdate(): SelfUpdateApi {
 	const [dismissedRunId, setDismissedRunId] = useState<string | null>(null);
 	const [checkPress, setCheckPress] = useState<CheckPress | null>(null);
 	const [checkFailure, setCheckFailure] = useState<string | null>(null);
+	const [sighting, setSighting] = useState<RunSighting | null>(null);
 
 	const heldRef = useRef(held);
 	heldRef.current = held;
 	const pressRef = useRef(checkPress);
 	pressRef.current = checkPress;
 
+	// The last answer, which outlives the failed requests after it: a tab that
+	// never pressed install learns from here that it is inside a restart.
+	const lastKnown = queryClient.getQueryData<RemitImapSystemUpdateResponse>(
+		systemOperationsGetSystemUpdateQueryKey(),
+	);
+	const insideRestart =
+		held !== null || runInFlight(lastKnown, dismissedRunId) !== null;
+
 	const query = useQuery({
 		...systemOperationsGetSystemUpdateOptions(),
 		retry: false,
-		meta: { softError: true },
+		meta: insideRestart ? POLL_ACROSS_RESTART_META : POLL_META,
 		refetchInterval: (query) =>
 			pollInterval(
 				query.state.error,
@@ -135,9 +165,26 @@ export function useSystemUpdate(): SelfUpdateApi {
 		dismissedRunId,
 		checkPress,
 		checkFailure,
+		sighting,
 		now: Date.now(),
 	});
 
+	// Stamp the run the server reports, once, off this tab's clock. The stamp is
+	// what the give-up is measured against, so it must not move while the server
+	// is unreachable — and it must not carry over to the next run.
+	const reported = runInFlight(query.data, dismissedRunId);
+	useEffect(() => {
+		if (reported === null) {
+			setSighting((current) => (current === null ? current : null));
+			return;
+		}
+		setSighting((current) =>
+			current !== null && current.runId === reported.runId
+				? current
+				: { runId: reported.runId, observedAt: Date.now() },
+		);
+	}, [reported]);
+
 	const shownRunIdRef = useRef<string | null>(null);
 	shownRunIdRef.current =
 		derived.surface.status === "ready" && "runId" in derived.surface.section

package/src/lib/error-classifier.test.ts

@@ -9,6 +9,7 @@ import {
 	isNetworkError,
 	isNotFound,
 	isServerError,
+	restartExpectedMeta,
 	shouldEscalate,
 	softErrorStatuses,
 } from "./error-classifier";
@@ -366,6 +367,13 @@ describe("meta.softErrorStatuses (one outcome owned, the rest not)", () => {
 		);
 	});
 
+	it("does not open the restart gap for a call site that never claimed one", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("bad gateway", 502), ownsNotFound, "nobody"),
+			true,
+		);
+	});
+
 	it("names the record's absence, whichever client raised it", () => {
 		assert.equal(isNotFound(new ApiError("gone", 404)), true);
 		assert.equal(isNotFound({ status: 404 }), true);
@@ -373,3 +381,54 @@ describe("meta.softErrorStatuses (one outcome owned, the rest not)", () => {
 		assert.equal(isNotFound(new TypeError("x is undefined")), false);
 	});
 });
+
+/**
+ * A self-update stops and starts the backend, so for those seconds the proxy in
+ * front of it has nothing to dial. That gap belongs to the surface that asked
+ * for the restart; every other 5xx, on that call site and on any other, is still
+ * the API reporting itself broken (#468).
+ */
+describe("meta.restartExpected (the gap in a restart this call site asked for)", () => {
+	it("does NOT escalate the gateway statuses answered while the backend is down", () => {
+		for (const status of [502, 503, 504]) {
+			assert.equal(
+				shouldEscalate(
+					new ApiError("gateway", status),
+					restartExpectedMeta,
+					"nobody",
+				),
+				false,
+				`a ${status} inside the restart window belongs to the update surface`,
+			);
+		}
+	});
+
+	it("escalates a 500 — a server that answered is up, and up and broken is not designed", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("boom", 500), restartExpectedMeta, "nobody"),
+			true,
+		);
+	});
+
+	it("escalates the same 502 without the claim, however soft the call site is", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("gateway", 502), undefined, "nobody"),
+			true,
+		);
+		assert.equal(
+			shouldEscalate(new ApiError("gateway", 502), { softError: true }, "user"),
+			true,
+		);
+	});
+
+	it("escalates a client bug raised inside the window", () => {
+		assert.equal(
+			shouldEscalate(
+				new TypeError("x is undefined"),
+				restartExpectedMeta,
+				"nobody",
+			),
+			true,
+		);
+	});
+});

package/src/lib/error-classifier.ts

@@ -143,6 +143,33 @@ const isSoftErrorMeta = (
 	return status !== undefined && owned.includes(status);
 };
 
+/**
+ * The statuses answered for the seconds a service is not there. Every `/api/*`
+ * request is proxied to apisix, which stays up while the backend behind it
+ * restarts and refuses in milliseconds — the 29ms 502 in #468, not a dial Caddy
+ * waited out. 503 and 504 are the same gap through a hop that answers
+ * differently.
+ */
+const RESTART_GAP_STATUSES = [502, 503, 504];
+
+/**
+ * The gap in a restart this call site asked for. A self-update stops and starts
+ * the backend on purpose, so the poll watching that run meets a proxy with
+ * nothing behind it — the designed shape of the operation the user pressed, not
+ * our API answering "I'm broken".
+ *
+ * A 500 is not in it: a server that answered is a server that is up, and up and
+ * broken is never designed.
+ */
+const isDesignedRestartGap = (
+	error: unknown,
+	meta: Record<string, unknown> | undefined,
+): boolean => {
+	if (meta?.restartExpected !== true) return false;
+	const status = getErrorStatus(error);
+	return status !== undefined && RESTART_GAP_STATUSES.includes(status);
+};
+
 /**
  * The single fail-fast decision: should this error escalate to the full-screen
  * fatal overlay? Default is YES — a non-2xx must never silently vanish.
@@ -151,7 +178,10 @@ const isSoftErrorMeta = (
  *  1. DEFAULT = escalate.
  *  2. A 5xx (500–599) ALWAYS escalates — no opt-out, even on a background
  *     refetch, even when the call site marked `meta.softError`. Our API
- *     answered "I'm broken"; that is never benign.
+ *     answered "I'm broken"; that is never benign. The single exception is a
+ *     502/503/504 on a call site that declared it is polling across a restart it
+ *     asked for (`meta.restartExpected`, #468): there the backend being gone is
+ *     the operation working, and that call site renders the wait itself.
  *  3. A client-side exception ALWAYS escalates, on the same terms. It is our
  *     bug; there is nothing for the user to retry and nothing to dismiss.
  *  4. A 401 on a request the user is waiting on ALWAYS escalates, on the same
@@ -173,7 +203,7 @@ export const shouldEscalate = (
 	meta?: Record<string, unknown>,
 	awaiting: Awaiting = "nobody",
 ): boolean => {
-	if (isServerError(error)) return true;
+	if (isServerError(error)) return !isDesignedRestartGap(error, meta);
 	if (isAbortError(error)) return false;
 	if (isNetworkError(error)) return false;
 	if (awaiting === "user" && isUnauthenticated(error)) return true;
@@ -209,6 +239,22 @@ export const softErrorStatuses = (
 	...statuses: number[]
 ): { softErrorStatuses: number[] } => ({ softErrorStatuses: statuses });
 
+/**
+ * The one opt-out from rule 2, for a request watching a restart the run it is
+ * following performs. Set it only while a run is known to be in flight — the
+ * update poll carries it while it holds a run it started or the server's last
+ * answer reported one going — because a 502 outside that window is the API being
+ * broken, which is exactly what rule 2 is for.
+ *
+ * A call site that sets this owns the whole wait, so the window outlives the
+ * budget: the give-up screen keeps polling a server it has stopped expecting,
+ * and a fatal page thrown over that verdict would replace the one screen that
+ * names the run and the log to read. A 500 from that same poll still escalates.
+ */
+export const restartExpectedMeta: { restartExpected: true } = {
+	restartExpected: true,
+};
+
 /** The record is not there. */
 export const isNotFound = (error: unknown): boolean =>
 	getErrorStatus(error) === 404;

package/src/lib/self-update-state.test.ts

@@ -72,6 +72,7 @@ function input(overrides: Partial<DeriveInput> = {}): DeriveInput {
 		dismissedRunId: null,
 		checkPress: null,
 		checkFailure: null,
+		sighting: null,
 		now: NOW,
 		...overrides,
 	};

package/src/lib/self-update-state.ts

@@ -72,6 +72,21 @@ export interface CheckPress {
 	since: string | undefined;
 }
 
+/**
+ * When this tab first saw the run the server reported as going, by its own
+ * clock. A run's `startedAt` is written on the box, and a box whose clock is
+ * twenty minutes behind the browser's would put that start far enough in the
+ * past to spend the whole apply budget before the first failed request — the
+ * screen would open on "the server never came back". `CheckPress` keeps its wait
+ * the client's own for the same reason. The runId travels with it so a second
+ * run never inherits the first one's wait.
+ */
+export interface RunSighting {
+	runId: string;
+	/** Epoch millis, this tab's clock, of the first answer that reported it going. */
+	observedAt: number;
+}
+
 export function checkAnswered(
 	press: CheckPress,
 	data: RemitImapSystemUpdateResponse | undefined,
@@ -126,6 +141,8 @@ export interface DeriveInput {
 	checkPress: CheckPress | null;
 	/** Why the request that press fired failed, or null when it did not. */
 	checkFailure: string | null;
+	/** When this tab first saw the server's run going, for a wait it can trust. */
+	sighting: RunSighting | null;
 	now: number;
 }
 
@@ -163,6 +180,22 @@ export function isSurfaceAbsent(error: unknown): boolean {
 	return status === 404 || status === 403 || status === 401;
 }
 
+/**
+ * The run the server last reported as still going, or null when it reported
+ * none. The last answer outlives the failed requests that follow it, which is
+ * what lets any tab — not only the one that pressed install — know it is inside
+ * a restart rather than looking at an unreachable service (#468). A run the user
+ * has dismissed is not one either surface still speaks for.
+ */
+export function runInFlight(
+	data: RemitImapSystemUpdateResponse | undefined,
+	dismissedRunId: string | null,
+): RemitImapSystemUpdateRun | null {
+	const run = data?.run ?? null;
+	if (run === null || run.outcome !== null) return null;
+	return run.runId === dismissedRunId ? null : run;
+}
+
 /**
  * The available release from the check block, or undefined when the check
  * reports none. Independent of what the pane is currently showing, so a retry
@@ -343,29 +376,75 @@ function ready(
 	return { surface: { status: "ready", section, overlay }, releaseHeld };
 }
 
+/**
+ * The wait every tab is in while the server it is polling is not answering: the
+ * run is known to be in flight, and the phase is the only one the client can
+ * claim from a dead connection.
+ */
+function reconnectingSurface(
+	runId: string,
+	previousVersion: string,
+	attemptedVersion: string,
+	elapsedSeconds: number,
+): UpdateSurface {
+	return {
+		status: "ready",
+		section: applyingSection(
+			runId,
+			previousVersion,
+			attemptedVersion,
+			"reconnecting",
+			elapsedSeconds,
+		),
+		overlay: {
+			kind: "applying",
+			target: attemptedVersion,
+			phase: "reconnecting",
+			elapsedSeconds,
+		},
+	};
+}
+
+/** The client gave up waiting, and says so without claiming the rollback ran. */
+function neverCameBackSurface(
+	runId: string,
+	previousVersion: string,
+	attemptedVersion: string,
+	elapsedSeconds: number,
+	logsCommand: string,
+): UpdateSurface {
+	return {
+		status: "ready",
+		section: applyingSection(
+			runId,
+			previousVersion,
+			attemptedVersion,
+			"reconnecting",
+			elapsedSeconds,
+		),
+		overlay: {
+			kind: "neverCameBack",
+			attemptedVersion,
+			previousVersion,
+			elapsedSeconds,
+			logsCommand,
+		},
+	};
+}
+
 /**
  * The client gave up waiting. The hold stays: the screen has to sit still, and
  * its retry has to keep polling, until the server answers for itself.
  */
 function neverCameBack(held: HeldRun, elapsedSeconds: number): DeriveResult {
 	return {
-		surface: {
-			status: "ready",
-			section: applyingSection(
-				held.runId,
-				held.previousVersion,
-				held.attemptedVersion,
-				"reconnecting",
-				elapsedSeconds,
-			),
-			overlay: {
-				kind: "neverCameBack",
-				attemptedVersion: held.attemptedVersion,
-				previousVersion: held.previousVersion,
-				elapsedSeconds,
-				logsCommand: FALLBACK_LOGS_COMMAND,
-			},
-		},
+		surface: neverCameBackSurface(
+			held.runId,
+			held.previousVersion,
+			held.attemptedVersion,
+			elapsedSeconds,
+			FALLBACK_LOGS_COMMAND,
+		),
 		releaseHeld: false,
 	};
 }
@@ -408,22 +487,15 @@ function deriveHeld(
 		if (elapsedSeconds > budgetLimitSeconds()) {
 			return neverCameBack(held, elapsedSeconds);
 		}
-		return ready(
-			applyingSection(
+		return {
+			surface: reconnectingSurface(
 				held.runId,
 				held.previousVersion,
 				held.attemptedVersion,
-				"reconnecting",
 				elapsedSeconds,
 			),
-			{
-				kind: "applying",
-				target: held.attemptedVersion,
-				phase: "reconnecting",
-				elapsedSeconds,
-			},
-			false,
-		);
+			releaseHeld: false,
+		};
 	}
 
 	// Nothing has come back yet. Silence is not a phase, so the surface waits
@@ -474,10 +546,46 @@ function deriveHeld(
 }
 
 function displayFromData(input: DeriveInput): UpdateSurface {
-	const { data, isError, dismissedRunId, checkPress, checkFailure, now } =
-		input;
+	const {
+		data,
+		isError,
+		dismissedRunId,
+		checkPress,
+		checkFailure,
+		sighting,
+		now,
+	} = input;
 
 	if (isError) {
+		const stopped = runInFlight(data, dismissedRunId);
+		// A tab that never pressed install is in the same restart as the one that
+		// did: the run the server last reported is still going, and the server
+		// stopping is how it goes. The wait runs from when this tab saw the run,
+		// never from the `startedAt` the box wrote — same budget, on a clock the
+		// tab owns. A run in flight this tab has no sighting of has only just
+		// arrived, so the wait starts here.
+		if (stopped !== null) {
+			const observedAt =
+				sighting !== null && sighting.runId === stopped.runId
+					? sighting.observedAt
+					: now;
+			const elapsedSeconds = elapsedSince(observedAt, now);
+			if (elapsedSeconds > budgetLimitSeconds()) {
+				return neverCameBackSurface(
+					stopped.runId,
+					stopped.fromVersion,
+					stopped.targetVersion,
+					elapsedSeconds,
+					stopped.logCommand,
+				);
+			}
+			return reconnectingSurface(
+				stopped.runId,
+				stopped.fromVersion,
+				stopped.targetVersion,
+				elapsedSeconds,
+			);
+		}
 		return {
 			status: "ready",
 			section: {