@remit/web-client 0.0.209 → 0.0.211

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.209",
+  "version": "0.0.211",
   "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/components/layout/Drawer.focus.test.ts

@@ -0,0 +1,212 @@
+/**
+ * The drawer's focus trap (#747).
+ *
+ * The drawer is `aria-modal`, so a screen reader offers nothing outside it and
+ * the scrim puts everything outside it out of a pointer's reach. Tab has to
+ * agree with both: it cycles inside the drawer, and the ring is the controls a
+ * reader can actually see and press — not every element that happens to match
+ * a focusable selector.
+ */
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import {
+	act,
+	createElement,
+	Fragment,
+	type ReactElement,
+	type ReactNode,
+} from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { Drawer } from "./Drawer";
+
+let container: HTMLElement;
+let root: Root;
+let outside: HTMLButtonElement;
+
+const press = (key: string, shiftKey = false): void => {
+	act(() => {
+		document.dispatchEvent(
+			new KeyboardEvent("keydown", { key, shiftKey, bubbles: true }),
+		);
+	});
+};
+
+const named = (label: string): HTMLElement => {
+	const found = container.querySelector<HTMLElement>(`[data-name="${label}"]`);
+	if (!found) throw new Error(`expected an element named ${label}`);
+	return found;
+};
+
+const closeButton = (): HTMLElement => {
+	const buttons = container.querySelectorAll<HTMLElement>(
+		'.safe-area-frame [aria-label="Close menu"]',
+	);
+	const found = buttons[0];
+	if (!found) throw new Error("expected the drawer's close button");
+	return found;
+};
+
+const render = (isOpen: boolean, children: ReactNode): void => {
+	act(() => {
+		root.render(
+			createElement(Drawer, {
+				isOpen,
+				onClose: () => undefined,
+				ariaLabel: "Message details",
+				side: "right",
+				children,
+			}),
+		);
+	});
+};
+
+const open = (children: ReactNode): void => render(true, children);
+const close = (): void => render(false, null);
+
+const button = (
+	name: string,
+	props: Record<string, unknown> = {},
+): ReactElement =>
+	createElement(
+		"button",
+		{ key: name, type: "button", "data-name": name, ...props },
+		name,
+	);
+
+beforeEach(() => {
+	container = document.getElementById("root") as unknown as HTMLElement;
+	container.innerHTML = "";
+	outside = document.createElement("button");
+	outside.type = "button";
+	outside.textContent = "Toolbar toggle";
+	document.body.appendChild(outside);
+	root = createRoot(container);
+});
+
+afterEach(() => {
+	act(() => root.unmount());
+	outside.remove();
+});
+
+describe("Drawer keeps Tab inside itself", () => {
+	it("wraps backwards from the first element to the last", () => {
+		open(createElement(Fragment, null, button("alpha"), button("omega")));
+		closeButton().focus();
+
+		press("Tab", true);
+
+		assert.equal(document.activeElement, named("omega"));
+	});
+
+	it("wraps forwards from the last element to the first", () => {
+		open(createElement(Fragment, null, button("alpha"), button("omega")));
+		named("omega").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, closeButton());
+	});
+
+	it("pulls focus back in when it is somewhere else entirely", () => {
+		open(createElement(Fragment, null, button("alpha")));
+		outside.focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, closeButton());
+	});
+
+	it("leaves an interior Tab to the browser", () => {
+		open(createElement(Fragment, null, button("alpha"), button("omega")));
+		named("alpha").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, named("alpha"));
+	});
+});
+
+describe("Drawer's ring is what a reader can reach", () => {
+	it("skips a scrim that took itself out of the tab order", () => {
+		open(
+			createElement(
+				Fragment,
+				null,
+				button("backdrop", { tabIndex: -1 }),
+				button("omega"),
+			),
+		);
+		named("omega").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, closeButton());
+	});
+
+	it("skips disabled, aria-disabled and hidden controls", () => {
+		open(
+			createElement(
+				Fragment,
+				null,
+				button("omega"),
+				button("off", { disabled: true }),
+				button("stated-off", { "aria-disabled": "true" }),
+				button("gone", { style: { display: "none" } }),
+				button("inerted", { inert: true }),
+			),
+		);
+		named("omega").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, closeButton());
+	});
+
+	/**
+	 * The intelligence pane's reclassify dialog renders inside the drawer, over
+	 * its panel. A ring scoped to the panel puts that dialog's Cancel last and
+	 * keeps every control behind its backdrop in the cycle, so Tab walks onto
+	 * buttons no pointer can reach — the very thing the trap exists to prevent.
+	 */
+	it("hands the ring to a modal opened inside it", () => {
+		open(
+			createElement(
+				Fragment,
+				null,
+				button("under-the-backdrop"),
+				createElement(
+					"div",
+					{
+						key: "nested",
+						role: "dialog",
+						"aria-modal": "true",
+						"aria-label": "Reclassify sender",
+					},
+					button("automated"),
+					button("Cancel"),
+				),
+			),
+		);
+		named("Cancel").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, named("automated"));
+
+		press("Tab", true);
+
+		assert.equal(document.activeElement, named("Cancel"));
+	});
+});
+
+describe("Drawer gives focus back on the way out", () => {
+	it("returns it to whatever held it when the drawer went up", () => {
+		outside.focus();
+		open(createElement(Fragment, null, button("alpha")));
+		assert.equal(document.activeElement, closeButton());
+
+		close();
+
+		assert.equal(document.activeElement, outside);
+	});
+});

package/src/components/layout/Drawer.tsx

@@ -2,6 +2,37 @@ import { cn } from "@remit/ui";
 import { X } from "lucide-react";
 import { type ReactNode, useEffect, useRef } from "react";
 
+const FOCUSABLE_SELECTOR =
+	"a[href], button, input, select, textarea, [tabindex]";
+
+const isTabbable = (element: HTMLElement): boolean => {
+	if (element.tabIndex < 0) return false;
+	if (element.hasAttribute("disabled")) return false;
+	if (element.getAttribute("aria-disabled") === "true") return false;
+	if (element.closest("[inert], [hidden], [aria-hidden='true']")) return false;
+	const style = getComputedStyle(element);
+	return style.display !== "none" && style.visibility !== "hidden";
+};
+
+/**
+ * The elements Tab may reach, in the order it reaches them.
+ *
+ * A modal opened from inside the drawer takes the ring with it: the
+ * intelligence pane's reclassify dialog renders under the drawer's own panel,
+ * so a ring scoped to the panel puts its Cancel last and leaves every control
+ * behind that dialog's backdrop in the cycle — Tab walks onto buttons no
+ * pointer can reach, which is the bug the trap exists to prevent.
+ */
+const tabRing = (panel: HTMLElement): HTMLElement[] => {
+	const nested = panel.querySelectorAll<HTMLElement>(
+		'[role="dialog"][aria-modal="true"]',
+	);
+	const root = nested[nested.length - 1] ?? panel;
+	return [...root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter(
+		isTabbable,
+	);
+};
+
 interface DrawerProps {
 	isOpen: boolean;
 	onClose: () => void;
@@ -40,16 +71,35 @@ export const Drawer = ({
 			if (event.key === "Escape") {
 				event.preventDefault();
 				onClose();
+				return;
+			}
+			// Trap Tab inside the drawer: it is `aria-modal`, so a screen reader
+			// offers nothing outside it — and letting Tab walk out would land on
+			// controls a pointer cannot reach under the scrim (#747).
+			if (event.key !== "Tab" || !drawerRef.current) return;
+			const ring = tabRing(drawerRef.current);
+			if (ring.length === 0) return;
+			const first = ring[0];
+			const last = ring[ring.length - 1];
+			const active = document.activeElement;
+			const inside = active instanceof HTMLElement && ring.includes(active);
+			if (event.shiftKey) {
+				if (!inside || active === first) {
+					event.preventDefault();
+					last.focus();
+				}
+				return;
+			}
+			if (!inside || active === last) {
+				event.preventDefault();
+				first.focus();
 			}
 		};
 
 		document.addEventListener("keydown", handleKey);
 
 		// Move focus into the drawer
-		const focusable = drawerRef.current?.querySelector<HTMLElement>(
-			"button, [href], input, select, textarea, [tabindex]:not([tabindex='-1'])",
-		);
-		focusable?.focus();
+		if (drawerRef.current) tabRing(drawerRef.current)[0]?.focus();
 
 		// Lock body scroll
 		const previousOverflow = document.body.style.overflow;

package/src/components/mail/intelligence-drawer.stories.tsx

@@ -1,9 +1,16 @@
-import { type IntelligenceData, IntelligencePanel } from "@remit/ui";
+import {
+	Avatar,
+	type IntelligenceData,
+	IntelligencePanel,
+	RefreshButton,
+	ShellTopBar,
+} from "@remit/ui";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { ChevronLeft, Info } from "lucide-react";
 import { useState } from "react";
 import { expect, userEvent, within } from "storybook/test";
 import { Drawer } from "@/components/layout/Drawer";
+import { MessageToolbar } from "@/components/mail/MessageToolbar";
 import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
 
 /**
@@ -29,6 +36,8 @@ type Story = StoryObj;
 
 const PHONE_WIDTH = 390;
 const PHONE_HEIGHT = 720;
+const MID_WIDTH = 1100;
+const MID_HEIGHT = 640;
 
 const intelligence: IntelligenceData = {
 	sender: {
@@ -213,6 +222,119 @@ export const DismissedAndNotCarried: Story = {
 	},
 };
 
+/**
+ * The two-pane desktop band between 1024 and 1280px, where the rail has no room
+ * and the drawer is the surface. The drawer is right-anchored and 320px wide,
+ * so it lands squarely on the reading toolbar's own intelligence toggle — the
+ * control that put it there. The shell's top bar is here because the geometry
+ * is the point: it is what stands the toolbar clear of the drawer's own header,
+ * as it does in the app.
+ */
+const MidWidthReader = () => {
+	const drawer = useIntelligenceDrawer(messages[0]?.id ?? null);
+	const [search, setSearch] = useState("");
+
+	return (
+		<div
+			className="flex flex-col overflow-hidden rounded-lg border border-line bg-canvas"
+			// As on the phone frame: the transform makes this a containing block,
+			// so the drawer's `position: fixed` resolves against it.
+			style={{
+				width: MID_WIDTH,
+				height: MID_HEIGHT,
+				transform: "translateZ(0)",
+			}}
+		>
+			<ShellTopBar
+				search={{
+					value: search,
+					scope: "global",
+					onChange: setSearch,
+					onClear: () => setSearch(""),
+					onClearQuery: () => setSearch(""),
+					onRemoveChip: () => undefined,
+				}}
+				onCompose={() => undefined}
+				onReportBug={() => undefined}
+				onOpenSettings={() => undefined}
+				refreshControl={
+					<RefreshButton
+						state="idle"
+						label="Refresh all accounts"
+						onRefresh={() => undefined}
+					/>
+				}
+				account={
+					<Avatar
+						name="Matthijs van Henten"
+						email="mvh@example.com"
+						size="sm"
+					/>
+				}
+			/>
+			<MessageToolbar
+				hasThread
+				intelligenceOpen={drawer.isOpen}
+				canToggleIntelligence
+				onToggleIntelligence={drawer.toggle}
+			/>
+			<div className="min-h-0 flex-1 overflow-y-auto px-5 py-4 text-sm text-fg">
+				<h1 className="text-lg font-semibold leading-snug">
+					{messages[0]?.subject}
+				</h1>
+				<p className="mt-1 text-2xs text-fg-subtle">{messages[0]?.from}</p>
+				<p className="mt-4 max-w-2xl">{messages[0]?.body}</p>
+			</div>
+			<Drawer
+				isOpen={drawer.isOpen}
+				onClose={drawer.close}
+				ariaLabel="Message details"
+				side="right"
+			>
+				<IntelligencePanel data={intelligence} hideCloseButton />
+			</Drawer>
+		</div>
+	);
+};
+
+/**
+ * The toggle the drawer covers. It is the only way into this surface for a
+ * message with no warning on it, so the drawer lands on it — and stays there:
+ * the toggle is the way in and nothing else. Getting back out is the drawer's
+ * own job, and its X sits clear of the toggle to do it (#747).
+ */
+export const CoveredToggle: Story = {
+	render: () => <MidWidthReader />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+
+		await userEvent.click(
+			canvas.getByRole("button", { name: "Show intelligence sidebar" }),
+		);
+		const drawer = canvas.getByRole("dialog", { name: "Message details" });
+		await expect(drawer).toBeVisible();
+
+		// The toggle stays in the toolbar the drawer covers. Nothing lifts it over
+		// the surface it opened, so a press aimed at it reaches the drawer.
+		await expect(drawer).not.toContainElement(
+			canvas.getByRole("button", { name: "Hide intelligence sidebar" }),
+		);
+
+		// The header's X, not the scrim that shares its name: the second of the
+		// two, and the one a reader can see.
+		const close = within(drawer).getAllByLabelText("Close menu")[1];
+		await expect(close).toBeVisible();
+		await userEvent.click(close);
+
+		await expect(
+			canvas.queryByRole("dialog", { name: "Message details" }),
+		).toBeNull();
+		await expect(
+			canvas.getByRole("button", { name: "Show intelligence sidebar" }),
+		).toHaveAttribute("aria-pressed", "false");
+	},
+};
+
 /** The drawer over the dark theme. */
 export const OpenOverThreadDark: Story = {
 	name: "Open Over Thread (dark)",

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

@@ -16,13 +16,20 @@ import { act, createElement, type ReactNode } from "react";
 import { SelfUpdateOverlay } from "../components/self-update/SelfUpdateOverlay";
 import { AdvancedNavIcon } from "../components/settings/AdvancedNavIcon";
 import { SelfUpdatePanel } from "../components/settings/SelfUpdatePanel";
+import { __resetFatalError, getCurrentFatalError } from "../lib/fatal-error";
 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 HttpCall,
+	type HttpMock,
+	httpError,
+	mockFetch,
+} from "../test-support/http";
+import {
+	CHECK_ANSWER_BUDGET_MS,
 	type SelfUpdateApi,
 	SelfUpdateProvider,
 	useSelfUpdate,
@@ -36,9 +43,11 @@ let http: HttpMock | undefined;
 beforeEach(() => {
 	globalThis.localStorage = globalThis.window.localStorage;
 	localStorage.clear();
+	__resetFatalError();
 });
 
 afterEach(() => {
+	__resetFatalError();
 	http?.restore();
 	http = undefined;
 	harness?.close();
@@ -105,12 +114,12 @@ async function settle(dom: DomHarness): Promise<void> {
  * what the real seam returns the moment it accepts the request.
  */
 function mountApi(
-	getResponse: () => unknown,
+	getResponse: (call: HttpCall) => unknown,
 	children: ReactNode = null,
 ): { dom: DomHarness; api: () => SelfUpdateApi } {
 	http = mockFetch((call) => {
 		if (call.path.endsWith("/system/update") && call.method === "GET") {
-			return getResponse();
+			return getResponse(call);
 		}
 		return {
 			currentVersion: "0.9.3",
@@ -148,6 +157,15 @@ async function startUpdate(
 	});
 }
 
+async function press(dom: DomHarness, api: () => SelfUpdateApi): Promise<void> {
+	await act(async () => {
+		api().onCheck();
+		await dom.flush();
+		await dom.wait(1);
+		await dom.flush();
+	});
+}
+
 async function renderSurface(
 	getResponse: () => unknown,
 	children: ReactNode,
@@ -428,7 +446,23 @@ describe("useSystemUpdate — actions", () => {
 		assert.equal(after.status === "ready" && after.section.status, "upToDate");
 	});
 
-	test("checking and retrying re-poll the surface", async () => {
+	test("the press asks the updater for a check, not another read of the same file (#599)", async () => {
+		// The whole of #599: a plain re-read answers with the verdict it already
+		// had. Only refresh=true records a request the updater will act on.
+		const { dom, api } = mountApi(() => available);
+		await settle(dom);
+		const before = http?.calls.length ?? 0;
+
+		await press(dom, api);
+
+		const refreshes = (http?.calls ?? [])
+			.slice(before)
+			.filter((call) => call.url.includes("refresh=true"));
+		assert.equal(refreshes.length, 1);
+		assert.equal(refreshes[0].method, "GET");
+	});
+
+	test("retrying the connection re-polls the surface", async () => {
 		let calls = 0;
 		const { dom, api } = mountApi(() => {
 			calls += 1;
@@ -437,10 +471,6 @@ describe("useSystemUpdate — actions", () => {
 		await settle(dom);
 		const afterMount = calls;
 
-		await act(async () => {
-			api().onCheck();
-			await dom.flush();
-		});
 		await act(async () => {
 			api().onRetryConnection();
 			await dom.flush();
@@ -448,4 +478,57 @@ describe("useSystemUpdate — actions", () => {
 
 		assert.equal(calls > afterMount, true);
 	});
+
+	test("a press the updater never answers ends loudly, not in a spinner (#599)", async () => {
+		// The poll keeps answering with the same bytes, so nothing the hook reads
+		// changes and no render would notice the wait running out on its own.
+		const { dom, api } = mountApi(
+			() => available,
+			createElement(SelfUpdatePanel),
+		);
+		await settle(dom);
+
+		const realNow = Date.now;
+		try {
+			await act(async () => {
+				api().onCheck();
+				// The press is stamped off the real clock; the wait it then arms is
+				// measured against one already past the budget, so the deadline the
+				// hook sets for itself lands on the next tick, not in half a minute.
+				Date.now = () => realNow() + CHECK_ANSWER_BUDGET_MS + 1_000;
+				await dom.flush();
+			});
+			// The effects have run and the deadline is armed — let it fire.
+			await dom.wait(5);
+			await dom.flush();
+
+			assert.match(dom.html(), /The updater did not answer/);
+			assert.match(dom.html(), /remit logs updater/);
+			assert.doesNotMatch(dom.html(), /Looking for a newer version/);
+		} finally {
+			Date.now = realNow;
+		}
+	});
+
+	test("a refused refresh is shown, never swallowed back into the old verdict (#599)", async () => {
+		let refused = false;
+		const { dom, api } = mountApi(
+			(call) =>
+				refused && call.url.includes("refresh=true")
+					? httpError(500)
+					: available,
+			createElement(SelfUpdatePanel),
+		);
+		await settle(dom);
+
+		refused = true;
+		await press(dom, api);
+
+		assert.match(dom.html(), /could not be requested/);
+		assert.match(dom.html(), /answered 500/);
+		assert.doesNotMatch(dom.html(), /Install 0\.9\.4/);
+		// The press is a raw SDK call, outside the cache the global sink watches:
+		// a 5xx escalates from here or from nowhere at all.
+		assert.equal(getCurrentFatalError()?.error !== undefined, true);
+	});
 });

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

@@ -12,13 +12,15 @@
  * nothing and takes the server's answer as it finds it.
  *
  * Polling follows the run: every 30 seconds while idle, every 5 seconds while a
- * run is in flight or this page is waiting on one it started.
+ * run is in flight, this page is waiting on one it started, or it is waiting on
+ * a check it pressed for.
  */
 import {
 	systemOperationsApplySystemUpdateMutation,
 	systemOperationsGetSystemUpdateOptions,
 	systemOperationsGetSystemUpdateQueryKey,
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { systemOperationsGetSystemUpdate } from "@remit/api-http-client/sdk.gen.ts";
 import type {
 	RemitImapSystemUpdateResponse,
 	RemitImapSystemUpdateRun,
@@ -35,8 +37,13 @@ import {
 	useRef,
 	useState,
 } from "react";
+import { shouldEscalate, softErrorMeta } from "@/lib/error-classifier";
+import { reportFatalError } from "@/lib/fatal-error";
 import {
 	appliesSchemaMigration,
+	type CheckPress,
+	checkAnswered,
+	checkRequestFailureReason,
 	deriveUpdateSurface,
 	type HeldRun,
 	isSurfaceAbsent,
@@ -48,6 +55,19 @@ import {
 const IDLE_POLL_MS = 30_000;
 const RUN_POLL_MS = 5_000;
 
+/**
+ * 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
+ * five-second watch tick, so half a minute is several ticks — patient enough for
+ * a busy box, short enough that a press against a dead updater is answered
+ * rather than left spinning for good.
+ */
+export const CHECK_ANSWER_BUDGET_MS = 30_000;
+
+/** The press was recorded and nothing came back. Names the process and the log. */
+export const UPDATER_SILENT_REASON =
+	"The updater did not answer. Run `remit logs updater` to see why.";
+
 export interface SelfUpdateApi {
 	surface: UpdateSurface;
 	/** Whether the pending release runs a schema migration during the window. */
@@ -55,7 +75,7 @@ export interface SelfUpdateApi {
 	currentVersion: string | undefined;
 	/** The available release, for the consent dialog. */
 	release: ReleaseInfo | undefined;
-	/** Refetch the surface, showing a `checking` pane until it settles. */
+	/** Ask the updater for a fresh check, showing a `checking` pane until it answers. */
 	onCheck: () => void;
 	/** Request a specific release — consent has been given. */
 	install: (targetVersion: string) => void;
@@ -69,10 +89,13 @@ function pollInterval(
 	error: unknown,
 	run: RemitImapSystemUpdateRun | null,
 	hasHeldRun: boolean,
+	hasPress: boolean,
 ): number | false {
 	if (isSurfaceAbsent(error) && !hasHeldRun) return false;
 	const inFlight = run !== null && run.outcome === null;
-	if (hasHeldRun || inFlight) return RUN_POLL_MS;
+	// A press is waiting on the updater's next watch tick (#599), so it polls at
+	// the run cadence — and only until the wait ends, which drops the press.
+	if (hasHeldRun || inFlight || hasPress) return RUN_POLL_MS;
 	return IDLE_POLL_MS;
 }
 
@@ -80,10 +103,13 @@ export function useSystemUpdate(): SelfUpdateApi {
 	const queryClient = useQueryClient();
 	const [held, setHeld] = useState<HeldRun | null>(null);
 	const [dismissedRunId, setDismissedRunId] = useState<string | null>(null);
-	const [checkRequested, setCheckRequested] = useState(false);
+	const [checkPress, setCheckPress] = useState<CheckPress | null>(null);
+	const [checkFailure, setCheckFailure] = useState<string | null>(null);
 
 	const heldRef = useRef(held);
 	heldRef.current = held;
+	const pressRef = useRef(checkPress);
+	pressRef.current = checkPress;
 
 	const query = useQuery({
 		...systemOperationsGetSystemUpdateOptions(),
@@ -94,17 +120,21 @@ export function useSystemUpdate(): SelfUpdateApi {
 				query.state.error,
 				query.state.data?.run ?? null,
 				heldRef.current !== null,
+				pressRef.current !== null,
 			),
 	});
 
+	const dataRef = useRef(query.data);
+	dataRef.current = query.data;
+
 	const derived = deriveUpdateSurface({
 		data: query.data,
 		isError: query.isError,
 		error: query.error,
-		isFetching: query.isFetching,
 		held,
 		dismissedRunId,
-		checkRequested,
+		checkPress,
+		checkFailure,
 		now: Date.now(),
 	});
 
@@ -120,15 +150,62 @@ export function useSystemUpdate(): SelfUpdateApi {
 		if (releaseHeld) setHeld((current) => (current === null ? current : null));
 	}, [releaseHeld]);
 
+	// The updater answered the press: let go of it, so the next poll renders the
+	// verdict rather than the spinner.
 	useEffect(() => {
-		if (checkRequested && !query.isFetching) setCheckRequested(false);
-	}, [checkRequested, query.isFetching]);
+		if (checkPress !== null && checkAnswered(checkPress, query.data))
+			setCheckPress(null);
+	}, [checkPress, query.data]);
+
+	// The wait has to end itself. A poll that answers with the same bytes changes
+	// nothing this hook reads, so nothing would re-render to notice the budget had
+	// run out, and the spinner would sit there for good (#599).
+	useEffect(() => {
+		if (checkPress === null) return;
+		const remaining =
+			checkPress.pressedAt + CHECK_ANSWER_BUDGET_MS - Date.now();
+		const timer = setTimeout(
+			() => {
+				setCheckPress(null);
+				setCheckFailure(UPDATER_SILENT_REASON);
+			},
+			Math.max(0, remaining),
+		);
+		return () => clearTimeout(timer);
+	}, [checkPress]);
 
 	const { refetch } = query;
 
 	const onCheck = useCallback(() => {
-		setCheckRequested(true);
-		void refetch();
+		// A plain refetch only re-reads state.json, so the answer would be exactly
+		// as old as it was before the press. refresh=true has the backend record a
+		// check request for the updater; the wait is this page's to keep, against
+		// the `lastCheckedAt` the server had when the control was pressed (#599).
+		setCheckFailure(null);
+		setCheckPress({
+			pressedAt: Date.now(),
+			since: dataRef.current?.check.lastCheckedAt,
+		});
+
+		void systemOperationsGetSystemUpdate({
+			query: { refresh: true },
+			throwOnError: true,
+		})
+			.then(() => {
+				void refetch();
+			})
+			.catch((error: unknown) => {
+				// The request never reached the seam, so nothing is coming. Say so
+				// where the press was made instead of reverting to the old verdict.
+				// This is a raw SDK call, outside the query cache that feeds the
+				// global sink, so the 5xx the seam answers when the control volume
+				// is unwritable escalates from here or from nowhere.
+				if (shouldEscalate(error, softErrorMeta, "user")) {
+					reportFatalError(error);
+				}
+				setCheckPress(null);
+				setCheckFailure(checkRequestFailureReason(error));
+			});
 	}, [refetch]);
 
 	const onRetryConnection = useCallback(() => {

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

@@ -8,6 +8,7 @@ import { ApiError } from "./api";
 import {
 	APPLY_BUDGET_SECONDS,
 	appliesSchemaMigration,
+	checkRequestFailureReason,
 	type DeriveInput,
 	deriveUpdateSurface,
 	type HeldRun,
@@ -67,10 +68,10 @@ function input(overrides: Partial<DeriveInput> = {}): DeriveInput {
 		data: undefined,
 		isError: false,
 		error: undefined,
-		isFetching: false,
 		held: null,
 		dismissedRunId: null,
-		checkRequested: false,
+		checkPress: null,
+		checkFailure: null,
 		now: NOW,
 		...overrides,
 	};
@@ -229,12 +230,16 @@ describe("deriveUpdateSurface — the surface without a run", () => {
 		);
 	});
 
-	test("a pressed check shows checking while the refetch is in flight", () => {
+	test("a press keeps checking while the server still reports the answer it had (#599)", () => {
+		const stale = {
+			status: "ok" as const,
+			updateAvailable: false,
+			lastCheckedAt: "2026-07-20T11:00:00.000Z",
+		};
 		const result = deriveUpdateSurface(
 			input({
-				data: response(),
-				checkRequested: true,
-				isFetching: true,
+				data: response({ check: stale }),
+				checkPress: { pressedAt: NOW - 5_000, since: stale.lastCheckedAt },
 			}),
 		);
 		assert.equal(
@@ -242,6 +247,52 @@ describe("deriveUpdateSurface — the surface without a run", () => {
 			"checking",
 		);
 	});
+
+	test("a press settles the moment the server reports a newer lastCheckedAt (#599)", () => {
+		const result = deriveUpdateSurface(
+			input({
+				data: response({
+					check: {
+						status: "ok",
+						updateAvailable: false,
+						lastCheckedAt: "2026-07-20T11:59:50.000Z",
+					},
+				}),
+				checkPress: {
+					pressedAt: NOW - 5_000,
+					since: "2026-07-20T11:00:00.000Z",
+				},
+			}),
+		);
+		assert.equal(
+			result.surface.status === "ready" && result.surface.section.status,
+			"upToDate",
+		);
+	});
+
+	test("a failed press is reported verbatim, never swallowed into the old verdict (#599)", () => {
+		const result = deriveUpdateSurface(
+			input({
+				data: response({
+					check: {
+						status: "ok",
+						updateAvailable: true,
+						latestVersion: "0.9.4",
+						lastCheckedAt: "2026-07-20T11:00:00.000Z",
+					},
+				}),
+				checkFailure: checkRequestFailureReason(new ApiError("boom", 500)),
+			}),
+		);
+		assert.equal(result.surface.status, "ready");
+		if (result.surface.status !== "ready") return;
+		const section = result.surface.section;
+		assert.equal(section.status, "checkFailed");
+		if (section.status !== "checkFailed") return;
+		assert.match(section.reason, /answered 500/);
+		// The age of the answer it is still showing survives the failure.
+		assert.equal(section.lastCheckedAt, Date.parse("2026-07-20T11:00:00.000Z"));
+	});
 });
 
 describe("deriveUpdateSurface — check and run stay independent", () => {

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

@@ -57,6 +57,44 @@ export interface HeldRun {
 	startedAt: number;
 }
 
+/**
+ * The check this page asked for, held for as long as the page that asked lives.
+ * The server records the request and answers with the state it already had, so
+ * the wait is the client's to keep: `since` is `check.lastCheckedAt` as the
+ * server reported it at the moment of the press, and the answer has landed once
+ * the server reports a different one. Comparing against that stored value rather
+ * than against the press's own clock keeps the rule honest on a box whose clock
+ * differs from the browser's.
+ */
+export interface CheckPress {
+	/** Epoch millis when the control was pressed, for the bounded wait. */
+	pressedAt: number;
+	since: string | undefined;
+}
+
+export function checkAnswered(
+	press: CheckPress,
+	data: RemitImapSystemUpdateResponse | undefined,
+): boolean {
+	const lastCheckedAt = data?.check.lastCheckedAt;
+	return lastCheckedAt !== undefined && lastCheckedAt !== press.since;
+}
+
+/**
+ * Why the request the press fired never reached the seam. The status is named
+ * because a 500 here is a real fault on the box — the control volume unwritable
+ * is the one seen in the wild — and a press that quietly re-served the old
+ * verdict is exactly how #599 stayed invisible for an hour.
+ */
+export function checkRequestFailureReason(error: unknown): string {
+	const status = getErrorStatus(error);
+	const cause =
+		status === undefined
+			? "the server did not answer"
+			: `the server answered ${status}`;
+	return `The check could not be requested — ${cause}. Run \`remit logs backend\` to see why.`;
+}
+
 export type UpdateOverlay =
 	| { kind: "none" }
 	| {
@@ -82,10 +120,12 @@ export interface DeriveInput {
 	data: RemitImapSystemUpdateResponse | undefined;
 	isError: boolean;
 	error: unknown;
-	isFetching: boolean;
 	held: HeldRun | null;
 	dismissedRunId: string | null;
-	checkRequested: boolean;
+	/** The check this page pressed for, or null when it is not waiting on one. */
+	checkPress: CheckPress | null;
+	/** Why the request that press fired failed, or null when it did not. */
+	checkFailure: string | null;
 	now: number;
 }
 
@@ -238,27 +278,49 @@ function terminalSection(
 
 function checkSection(
 	data: RemitImapSystemUpdateResponse,
-	isChecking: boolean,
+	press: CheckPress | null,
+	failure: string | null,
 	now: number,
 ): SelfUpdateState {
 	const check = data.check;
-	if (isChecking) return { status: "checking", version: data.currentVersion };
+	const lastCheckedAt = parseIso(check.lastCheckedAt);
+
+	if (failure !== null) {
+		return {
+			status: "checkFailed",
+			version: data.currentVersion,
+			reason: failure,
+			lastCheckedAt,
+		};
+	}
+
+	// The press is recorded and the updater has not answered it: the pane waits on
+	// a genuinely newer `lastCheckedAt` rather than re-serving the verdict it
+	// already had (#599). The caller drops the press when the wait runs out, which
+	// arrives here as a failure.
+	if (press !== null && !checkAnswered(press, data)) {
+		return { status: "checking", version: data.currentVersion };
+	}
 
 	if (check.status === "failed") {
 		return {
 			status: "checkFailed",
 			version: data.currentVersion,
 			reason: check.error ?? "Remit could not reach the update service.",
-			lastCheckedAt: parseIso(check.lastCheckedAt),
+			lastCheckedAt,
 		};
 	}
 
 	// A configured surface that has not run its first check yet is never-checked,
 	// not checking: the updater runs the check on a cadence and has not written a
 	// result. A spinner here would run forever, since nothing on this poll is in
-	// flight. Only a genuine refetch (handled above) shows the spinner.
+	// flight. Only a press this page is still waiting on shows the spinner.
 	if (check.status === "disabled") {
-		return { status: "neverChecked", version: data.currentVersion };
+		return {
+			status: "neverChecked",
+			version: data.currentVersion,
+			lastCheckedAt,
+		};
 	}
 
 	const release = releaseFromCheck(data, now);
@@ -412,7 +474,7 @@ function deriveHeld(
 }
 
 function displayFromData(input: DeriveInput): UpdateSurface {
-	const { data, isError, isFetching, dismissedRunId, checkRequested, now } =
+	const { data, isError, dismissedRunId, checkPress, checkFailure, now } =
 		input;
 
 	if (isError) {
@@ -464,7 +526,7 @@ function displayFromData(input: DeriveInput): UpdateSurface {
 
 	return {
 		status: "ready",
-		section: checkSection(data, checkRequested && isFetching, now),
+		section: checkSection(data, checkPress, checkFailure, now),
 		overlay: { kind: "none" },
 	};
 }