@remit/web-client 0.0.117 → 0.0.119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.117",
+  "version": "0.0.119",
   "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/mail/SelectionWizardHost.tsx

@@ -719,7 +719,10 @@ function SelectionWizardSession({
 				state,
 				matched: progress.matchedCount,
 				applied: progress.appliedCount,
-				failed: state === "backApplyFailed" ? progress.failedCount : 0,
+				failed:
+					state === "backApplyFailed" || state === "backApplyRestartFailed"
+						? progress.failedCount
+						: 0,
 				failures: [],
 			};
 		},

package/src/components/mail/organize-run-state.test.ts

@@ -59,6 +59,24 @@ describe("organizeRunState", () => {
 		);
 	});
 
+	it("keeps a finished pass's ending when the retry over it could not be started", () => {
+		// #552: the retry is a second create, and a create that failed over a pass
+		// that already moved mail is not a pass that never ran.
+		for (const ruleSaved of [true, false]) {
+			assert.equal(
+				organizeRunState(
+					reading({
+						ruleSaved,
+						isDone: true,
+						failedCount: 84,
+						failure: { kind: "restartFailed", error: new Error("offline") },
+					}),
+				),
+				"backApplyRestartFailed",
+			);
+		}
+	});
+
 	it("says nothing happened only when the create itself failed", () => {
 		assert.equal(
 			organizeRunState(

package/src/components/mail/organize-run-state.ts

@@ -20,6 +20,10 @@ export interface OrganizeJobReading {
  * not a job that never started (#526), so what the job is doing is read before
  * what failed: a dropped poll leaves a running pass running and a finished one
  * finished, and only a create that never returned an id says nothing happened.
+ *
+ * A create that failed over a pass that already ran is that same distinction on
+ * the create path (#552): the counts of the pass that ran stand, and what failed
+ * is the retry.
  */
 export const organizeRunState = ({
 	failure,
@@ -29,6 +33,7 @@ export const organizeRunState = ({
 	failedCount,
 	ruleSaved,
 }: OrganizeJobReading): RunState => {
+	if (failure?.kind === "restartFailed") return "backApplyRestartFailed";
 	if (failure?.kind === "startFailed") {
 		return ruleSaved ? "backApplyStartFailed" : "commitFailed";
 	}

package/src/components/self-update/SelfUpdateOverlay.tsx

@@ -4,8 +4,8 @@
  * Once consent is given the server is genuinely going away, so a quiet spinner
  * over a mailbox that cannot load would let a broken system look healthy. This
  * mounts at the app root and owns the window for the whole apply, and for the
- * "server never came back" verdict — from any route, so a reload mid-apply or a
- * second tab resumes straight into it.
+ * "server never came back" verdict — from any route, and in any tab the server
+ * tells about the run.
  */
 import {
 	SelfUpdateProgressOverlay,

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

@@ -1,9 +1,9 @@
 /**
  * The self-update hook, wired end to end against the generated client through a
  * mocked fetch. The pure state machine is covered in `lib/self-update-state.test.ts`;
- * these exercise the parts only the live hook has: resuming a persisted run
- * across a request that fails, the poll that survives a dead server, and the
- * POST that persists a run id the reload will pick up.
+ * these exercise the parts only the live hook has: what a page claims before the
+ * server has answered, the run this page starts and holds, and the poll that
+ * survives a dead server.
  */
 import assert from "node:assert/strict";
 import { afterEach, beforeEach, describe, test } from "node:test";
@@ -17,9 +17,8 @@ import { SelfUpdateOverlay } from "../components/self-update/SelfUpdateOverlay";
 import { AdvancedNavIcon } from "../components/settings/AdvancedNavIcon";
 import { SelfUpdatePanel } from "../components/settings/SelfUpdatePanel";
 import {
-	loadHeldRun,
-	SELF_UPDATE_RUN_KEY,
-	saveHeldRun,
+	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";
@@ -32,19 +31,12 @@ import {
 let harness: DomHarness | undefined;
 let http: HttpMock | undefined;
 
-function installMemoryStorage(): void {
-	const store = new Map<string, string>();
-	globalThis.localStorage = {
-		getItem: (k: string) => store.get(k) ?? null,
-		setItem: (k: string, v: string) => void store.set(k, v),
-		removeItem: (k: string) => void store.delete(k),
-		clear: () => store.clear(),
-		key: () => null,
-		length: 0,
-	} as Storage;
-}
-
-beforeEach(installMemoryStorage);
+// The browser global, as the app would find it. Present so that "a reload
+// resumes nothing" is a claim about the app rather than about the harness.
+beforeEach(() => {
+	globalThis.localStorage = globalThis.window.localStorage;
+	localStorage.clear();
+});
 
 afterEach(() => {
 	http?.restore();
@@ -84,6 +76,8 @@ const available: RemitImapSystemUpdateResponse = {
 };
 
 const updateKey = systemOperationsGetSystemUpdateQueryKey();
+const BUDGET_MS =
+	(APPLY_BUDGET_SECONDS + NEVER_CAME_BACK_MARGIN_SECONDS) * 1000;
 
 async function settle(dom: DomHarness): Promise<void> {
 	for (let attempt = 0; attempt < 40; attempt += 1) {
@@ -105,6 +99,55 @@ async function settle(dom: DomHarness): Promise<void> {
 	}
 }
 
+/**
+ * Mount the provider with a probe on the hook, so a test can drive `install`
+ * and read the surface back. The POST answers with a run in flight, which is
+ * what the real seam returns the moment it accepts the request.
+ */
+function mountApi(
+	getResponse: () => unknown,
+	children: ReactNode = null,
+): { dom: DomHarness; api: () => SelfUpdateApi } {
+	http = mockFetch((call) => {
+		if (call.path.endsWith("/system/update") && call.method === "GET") {
+			return getResponse();
+		}
+		return {
+			currentVersion: "0.9.3",
+			check: { status: "ok", updateAvailable: true, latestVersion: "0.9.4" },
+			run: run({ outcome: null }),
+		};
+	});
+	let captured: SelfUpdateApi | undefined;
+	const Probe = () => {
+		captured = useSelfUpdate();
+		return null;
+	};
+	harness = createDomHarness();
+	harness.renderApp(
+		createElement(SelfUpdateProvider, null, createElement(Probe), children),
+	);
+	return {
+		dom: harness,
+		api: () => {
+			if (!captured) throw new Error("hook not mounted");
+			return captured;
+		},
+	};
+}
+
+async function startUpdate(
+	dom: DomHarness,
+	api: () => SelfUpdateApi,
+): Promise<void> {
+	await act(async () => {
+		api().install("0.9.4");
+		await dom.flush();
+		await dom.wait(1);
+		await dom.flush();
+	});
+}
+
 async function renderSurface(
 	getResponse: () => unknown,
 	children: ReactNode,
@@ -209,41 +252,122 @@ describe("SelfUpdateOverlay — the blocking screen", () => {
 		assert.match(dom.html(), /Installing Remit 0\.9\.4/);
 	});
 
-	test("a held run resumes into applying when the request fails", async () => {
-		saveHeldRun({
-			runId: "upd_1",
-			attemptedVersion: "0.9.4",
-			previousVersion: "0.9.3",
-			startedAt: Date.now() - 20_000,
-		});
-		const dom = await renderSurface(() => {
-			throw new Error("connection refused");
+	test("a page that has heard nothing yet says nothing at all", async () => {
+		http = mockFetch(() => new Promise(() => {}));
+		harness = createDomHarness();
+		harness.renderApp(
+			createElement(
+				SelfUpdateProvider,
+				null,
+				createElement(SelfUpdateOverlay),
+				createElement(SelfUpdatePanel),
+			),
+		);
+		await harness.flush();
+		await harness.wait(1);
+		await harness.flush();
+
+		assert.equal(harness.html(), "");
+	});
+
+	test("the page that asked for the update rides out a failed request", async () => {
+		let failing = false;
+		const { dom, api } = mountApi(() => {
+			if (failing) throw new Error("connection refused");
+			return available;
 		}, createElement(SelfUpdateOverlay));
+		await settle(dom);
+		await startUpdate(dom, api);
+
+		failing = true;
+		await act(async () => {
+			api().onRetryConnection();
+			await dom.flush();
+			await dom.wait(1);
+			await dom.flush();
+		});
+
+		const surface = api().surface;
+		assert.equal(
+			surface.status === "ready" &&
+				surface.section.status === "applying" &&
+				surface.section.phase,
+			"reconnecting",
+		);
 		assert.match(dom.html(), /Installing Remit 0\.9\.4/);
 		assert.doesNotMatch(dom.html(), /has not answered since the restart/);
 	});
 
-	test("the budget elapsing flips a held run to never-came-back", async () => {
-		saveHeldRun({
-			runId: "upd_1",
-			attemptedVersion: "0.9.4",
-			previousVersion: "0.9.3",
-			startedAt: Date.now() - 60 * 60_000,
-		});
-		const dom = await renderSurface(() => {
-			throw new Error("connection refused");
+	test("a silence past the apply budget stops claiming an install is running", async () => {
+		let failing = false;
+		const { dom, api } = mountApi(() => {
+			if (failing) throw new Error("connection refused");
+			return available;
 		}, createElement(SelfUpdateOverlay));
-		assert.match(dom.html(), /has not answered since the restart/);
-		assert.match(dom.html(), /remit logs/);
+		await settle(dom);
+		await startUpdate(dom, api);
+
+		failing = true;
+		const realNow = Date.now;
+		Date.now = () => realNow() + BUDGET_MS + 60_000;
+		try {
+			await act(async () => {
+				api().onRetryConnection();
+				await dom.flush();
+				await dom.wait(1);
+				await dom.flush();
+			});
+			assert.doesNotMatch(dom.html(), /Installing Remit 0\.9\.4/);
+			assert.match(dom.html(), /has not answered since the restart/);
+			assert.match(dom.html(), /remit logs/);
+		} finally {
+			Date.now = realNow;
+		}
 	});
 
-	test("a poll that never answers gives up at the budget too", async () => {
-		saveHeldRun({
-			runId: "upd_1",
-			attemptedVersion: "0.9.4",
-			previousVersion: "0.9.3",
-			startedAt: Date.now() - 60 * 60_000,
+	test("a run the server reports finished ends the wait", async () => {
+		let finished = false;
+		const { dom, api } = mountApi(
+			() =>
+				finished
+					? {
+							currentVersion: "0.9.4",
+							check: { status: "ok", updateAvailable: false },
+							run: run({ outcome: "succeeded" }),
+						}
+					: available,
+			createElement(SelfUpdateOverlay),
+		);
+		await settle(dom);
+		await startUpdate(dom, api);
+
+		finished = true;
+		await act(async () => {
+			api().onRetryConnection();
+			await dom.flush();
+			await dom.wait(1);
+			await dom.flush();
 		});
+
+		const surface = api().surface;
+		assert.equal(
+			surface.status === "ready" && surface.section.status,
+			"succeeded",
+		);
+		assert.equal(dom.html(), "");
+	});
+
+	test("a reload during the silence resumes nothing", async () => {
+		const { dom, api } = mountApi(
+			() => available,
+			createElement(SelfUpdateOverlay),
+		);
+		await settle(dom);
+		await startUpdate(dom, api);
+		assert.match(dom.html(), /Installing Remit 0\.9\.4/);
+
+		http?.restore();
+		harness?.close();
 		http = mockFetch(() => new Promise(() => {}));
 		harness = createDomHarness();
 		harness.renderApp(
@@ -253,65 +377,28 @@ describe("SelfUpdateOverlay — the blocking screen", () => {
 		await harness.wait(1);
 		await harness.flush();
 
-		assert.doesNotMatch(harness.html(), /Installing Remit 0\.9\.4/);
-		assert.match(harness.html(), /has not answered since the restart/);
-		assert.match(harness.html(), /remit logs/);
-		assert.equal(loadHeldRun(), null);
+		assert.equal(harness.html(), "");
 	});
 });
 
 describe("useSystemUpdate — actions", () => {
-	function mountApi(getResponse: () => unknown): {
-		dom: DomHarness;
-		api: () => SelfUpdateApi;
-	} {
-		http = mockFetch((call) => {
-			if (call.path.endsWith("/system/update") && call.method === "GET") {
-				return getResponse();
-			}
-			return {
-				currentVersion: "0.9.3",
-				check: { status: "ok", updateAvailable: true, latestVersion: "0.9.4" },
-				run: run({ outcome: null }),
-			};
-		});
-		let captured: SelfUpdateApi | undefined;
-		const Probe = () => {
-			captured = useSelfUpdate();
-			return null;
-		};
-		harness = createDomHarness();
-		harness.renderApp(
-			createElement(SelfUpdateProvider, null, createElement(Probe)),
-		);
-		return {
-			dom: harness,
-			api: () => {
-				if (!captured) throw new Error("hook not mounted");
-				return captured;
-			},
-		};
-	}
-
-	test("install persists the run id the surface returns", async () => {
+	test("install takes the run from the surface and writes nothing down", async () => {
 		const { dom, api } = mountApi(() => available);
 		await settle(dom);
+		await startUpdate(dom, api);
 
-		await act(async () => {
-			api().install("0.9.4");
-			await dom.flush();
-			await dom.wait(1);
-			await dom.flush();
-		});
-
-		const held = loadHeldRun();
-		assert.equal(held?.runId, "upd_1");
-		assert.equal(localStorage.getItem(SELF_UPDATE_RUN_KEY) !== null, true);
 		const surface = api().surface;
 		assert.equal(
 			surface.status === "ready" && surface.overlay.kind,
 			"applying",
 		);
+		assert.equal(
+			surface.status === "ready" &&
+				surface.section.status === "applying" &&
+				surface.section.runId,
+			"upd_1",
+		);
+		assert.equal(localStorage.length, 0);
 	});
 
 	test("dismissing a finished result clears the pane", async () => {

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

@@ -1,14 +1,18 @@
 /**
  * The self-update surface, wired to the generated client.
  *
- * A single instance owns the query, the mutation, and the run id the client
- * persists across a restart, and hands the folded `SelfUpdateState` plus the
- * blocking-overlay state to every consumer through context — so the Advanced
- * pane, the root overlay, and the nav dot all read one source of truth. The
- * state machine itself lives in `lib/self-update-state.ts`.
+ * A single instance owns the query, the mutation, and the run this page asked
+ * for, and hands the folded `SelfUpdateState` plus the blocking-overlay state to
+ * every consumer through context — so the Advanced pane, the root overlay, and
+ * the nav dot all read one source of truth. The state machine itself lives in
+ * `lib/self-update-state.ts`.
+ *
+ * The held run lives here and nowhere else. A restart does not reload the page,
+ * so this state spans the whole window; a page that loads afterwards holds
+ * 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 a persisted run is being resumed.
+ * run is in flight or this page is waiting on one it started.
  */
 import {
 	systemOperationsApplySystemUpdateMutation,
@@ -33,13 +37,11 @@ import {
 } from "react";
 import {
 	appliesSchemaMigration,
-	clearStoredRun,
 	deriveUpdateSurface,
 	type HeldRun,
 	isSurfaceAbsent,
-	loadHeldRun,
+	mapUpdatePhase,
 	releaseFromCheck,
-	saveHeldRun,
 	type UpdateSurface,
 } from "@/lib/self-update-state";
 
@@ -76,7 +78,7 @@ function pollInterval(
 
 export function useSystemUpdate(): SelfUpdateApi {
 	const queryClient = useQueryClient();
-	const [held, setHeld] = useState<HeldRun | null>(() => loadHeldRun());
+	const [held, setHeld] = useState<HeldRun | null>(null);
 	const [dismissedRunId, setDismissedRunId] = useState<string | null>(null);
 	const [checkRequested, setCheckRequested] = useState(false);
 
@@ -112,11 +114,7 @@ export function useSystemUpdate(): SelfUpdateApi {
 			? derived.surface.section.runId
 			: null;
 
-	const { clearStoredRun: shouldClearStored, releaseHeld } = derived;
-
-	useEffect(() => {
-		if (shouldClearStored) clearStoredRun();
-	}, [shouldClearStored]);
+	const { releaseHeld } = derived;
 
 	useEffect(() => {
 		if (releaseHeld) setHeld((current) => (current === null ? current : null));
@@ -143,14 +141,13 @@ export function useSystemUpdate(): SelfUpdateApi {
 		onSuccess: (response: RemitImapSystemUpdateResponse) => {
 			const run = response.run;
 			if (run !== null) {
-				const record: HeldRun = {
+				setHeld({
 					runId: run.runId,
 					attemptedVersion: run.targetVersion,
 					previousVersion: run.fromVersion,
+					phase: mapUpdatePhase(run.phase),
 					startedAt: Date.now(),
-				};
-				saveHeldRun(record);
-				setHeld(record);
+				});
 				setDismissedRunId(null);
 			}
 			queryClient.setQueryData(
@@ -174,7 +171,6 @@ export function useSystemUpdate(): SelfUpdateApi {
 	const onDismissResult = useCallback(() => {
 		if (shownRunIdRef.current !== null)
 			setDismissedRunId(shownRunIdRef.current);
-		clearStoredRun();
 		setHeld(null);
 	}, []);
 

package/src/hooks/useOrganizeJob.render.test.ts

@@ -1,8 +1,9 @@
 /**
- * useOrganizeJob — the back-apply job seam. It reports two failures that are not
- * the same fact (#526): a create that never returned a job id, and a status poll
- * that could not be read over a job the server is already running. Looking at
- * that job again is a separate move from starting one.
+ * useOrganizeJob — the back-apply job seam. It reports three failures that are
+ * not the same fact (#526, #552): a create that never returned a job id, that
+ * same create over a pass that already ran, and a status poll that could not be
+ * read over a job the server is already running. Looking at that job again is a
+ * separate move from starting one.
  */
 
 import assert from "node:assert/strict";
@@ -75,6 +76,36 @@ const startJob = async (status: () => unknown): Promise<void> => {
 	await settle();
 };
 
+const COMPLETED_PASS = {
+	organizeJobId: JOB,
+	state: "Complete",
+	matchedCount: 1284,
+	appliedCount: 1200,
+	failedCount: 84,
+};
+
+/** Run one pass to a finish, then answer the next create with `restart`. */
+const restartAfterPass = async (restart: () => unknown): Promise<void> => {
+	let created = false;
+	http = mockFetch((call) => {
+		if (call.method !== "POST") return COMPLETED_PASS;
+		if (created) return restart();
+		created = true;
+		return { organizeJobId: JOB, state: "Pending" };
+	});
+	harness = createDomHarness();
+	harness.renderApp(createElement(Probe));
+	await act(async () => {
+		current().start(DRAFT);
+	});
+	await settle();
+	assert.equal(current().isDone, true, "the first pass never finished");
+	await act(async () => {
+		current().start(DRAFT);
+	});
+	await settle();
+};
+
 const posts = (): number =>
 	(http?.calls ?? []).filter((call) => call.method === "POST").length;
 
@@ -128,6 +159,23 @@ describe("useOrganizeJob status reporting", () => {
 		assert.equal(current().progress.matchedCount, 1284);
 	});
 
+	it("reads a create that failed over a finished pass as a restart, with that pass's counts", async () => {
+		await restartAfterPass(dropped);
+		assert.equal(current().failure?.kind, "restartFailed");
+		assert.equal(current().progress.matchedCount, 1284);
+		assert.equal(current().progress.appliedCount, 1200);
+		assert.equal(current().progress.failedCount, 84);
+		assert.equal(current().isDone, true);
+	});
+
+	it("reports a restart that is under way as its own pass, not the one before it", async () => {
+		await restartAfterPass(() => new Promise<never>(() => {}));
+		assert.equal(current().isStarting, true);
+		assert.equal(current().isDone, false);
+		assert.equal(current().failure, undefined);
+		assert.equal(current().progress.matchedCount, 0);
+	});
+
 	it("stops reporting a job as running once it reaches a terminal state", async () => {
 		await startJob(() => ({
 			organizeJobId: JOB,

package/src/hooks/useOrganizeJob.ts

@@ -23,20 +23,28 @@ export interface OrganizeJobProgress {
 }
 
 /**
- * Why the job is not reporting, which is two separate facts (#526). A create
- * that never returned an id means nothing was started; a status read that
- * failed means a job is out there and this client cannot see how far it got.
+ * Why the job is not reporting, which is three separate facts (#526, #552). A
+ * create that never returned an id means nothing was started; the same create
+ * over a pass that already ran means that pass stands and only the retry never
+ * left; a status read that failed means a job is out there and this client
+ * cannot see how far it got.
  */
 export interface OrganizeJobFailure {
-	kind: "startFailed" | "statusUnreadable";
+	kind: "startFailed" | "restartFailed" | "statusUnreadable";
 	error: unknown;
 }
 
 const organizeJobFailure = (
 	createError: unknown,
 	statusError: unknown,
+	passAlreadyRun: boolean,
 ): OrganizeJobFailure | undefined => {
-	if (createError) return { kind: "startFailed", error: createError };
+	if (createError) {
+		return {
+			kind: passAlreadyRun ? "restartFailed" : "startFailed",
+			error: createError,
+		};
+	}
 	if (statusError) return { kind: "statusUnreadable", error: statusError };
 	return undefined;
 };
@@ -76,7 +84,6 @@ export const useOrganizeJob = (accountId: string | undefined) => {
 	const start = useCallback(
 		(draft: OrganizeDraft) => {
 			if (!accountId) return;
-			setOrganizeJobId(undefined);
 			createJob({
 				path: { accountId },
 				body: buildOrganizeInput(draft),
@@ -92,7 +99,11 @@ export const useOrganizeJob = (accountId: string | undefined) => {
 		void refetch();
 	}, [refetch]);
 
-	const job = jobQuery.data;
+	// The last pass this client read. A restart replaces it only once the server
+	// hands back a job id: while the create is in flight those counts are not this
+	// pass's, and a create that fails leaves them standing (#552).
+	const lastPass = jobQuery.data;
+	const job = createMutation.isPending ? undefined : lastPass;
 	const state = job?.state ?? createMutation.data?.state;
 	const isDone = isTerminalJobState(job?.state);
 
@@ -111,6 +122,10 @@ export const useOrganizeJob = (accountId: string | undefined) => {
 		isStarting: createMutation.isPending,
 		isRunning: !!organizeJobId && !isDone,
 		isDone,
-		failure: organizeJobFailure(createMutation.error, jobQuery.error),
+		failure: organizeJobFailure(
+			createMutation.error,
+			jobQuery.error,
+			!!lastPass,
+		),
 	};
 };

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

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { beforeEach, describe, test } from "node:test";
+import { describe, test } from "node:test";
 import type {
 	RemitImapSystemUpdateResponse,
 	RemitImapSystemUpdateRun,
@@ -8,17 +8,13 @@ import { ApiError } from "./api";
 import {
 	APPLY_BUDGET_SECONDS,
 	appliesSchemaMigration,
-	clearStoredRun,
 	type DeriveInput,
 	deriveUpdateSurface,
 	type HeldRun,
 	isSurfaceAbsent,
-	loadHeldRun,
 	mapUpdatePhase,
 	NEVER_CAME_BACK_MARGIN_SECONDS,
 	releaseFromCheck,
-	SELF_UPDATE_RUN_KEY,
-	saveHeldRun,
 } from "./self-update-state";
 
 const NOW = Date.parse("2026-07-20T12:00:00.000Z");
@@ -60,6 +56,7 @@ function held(overrides: Partial<HeldRun> = {}): HeldRun {
 		runId: "upd_1",
 		attemptedVersion: "0.9.4",
 		previousVersion: "0.9.3",
+		phase: "preparing",
 		startedAt: NOW - 10_000,
 		...overrides,
 	};
@@ -279,7 +276,7 @@ describe("deriveUpdateSurface — check and run stay independent", () => {
 });
 
 describe("deriveUpdateSurface — terminal outcomes", () => {
-	test("a rolledBack run renders message and command verbatim and clears the id", () => {
+	test("a rolledBack run renders message and command verbatim", () => {
 		const result = deriveUpdateSurface(
 			input({
 				data: response({
@@ -291,7 +288,6 @@ describe("deriveUpdateSurface — terminal outcomes", () => {
 				}),
 			}),
 		);
-		assert.equal(result.clearStoredRun, true);
 		assert.equal(result.surface.status, "ready");
 		if (result.surface.status !== "ready") return;
 		const section = result.surface.section;
@@ -374,7 +370,11 @@ describe("deriveUpdateSurface — a held run across a restart", () => {
 		if (result.surface.status !== "ready") return;
 		assert.equal(result.surface.section.status, "applying");
 		assert.equal(result.surface.overlay.kind, "applying");
-		assert.equal(result.clearStoredRun, false);
+		assert.equal(
+			result.surface.overlay.kind === "applying" &&
+				result.surface.overlay.phase,
+			"reconnecting",
+		);
 	});
 
 	test("a failed request without a held run is a check-level failure", () => {
@@ -402,7 +402,6 @@ describe("deriveUpdateSurface — a held run across a restart", () => {
 		assert.equal(result.surface.status, "ready");
 		if (result.surface.status !== "ready") return;
 		assert.equal(result.surface.overlay.kind, "neverCameBack");
-		assert.equal(result.clearStoredRun, true);
 	});
 
 	test("never-came-back never claims the rollback ran", () => {
@@ -449,7 +448,6 @@ describe("deriveUpdateSurface — a held run across a restart", () => {
 			}),
 		);
 		assert.equal(result.releaseHeld, true);
-		assert.equal(result.clearStoredRun, true);
 		assert.equal(
 			result.surface.status === "ready" && result.surface.section.status,
 			"succeeded",
@@ -470,72 +468,33 @@ describe("deriveUpdateSurface — a held run across a restart", () => {
 		assert.equal(result.releaseHeld, true);
 	});
 
-	test("a first poll still in flight keeps applying inside the budget", () => {
+	test("a poll with no answer yet claims no phase at all", () => {
 		const result = deriveUpdateSurface(
 			input({ held: held({ startedAt: NOW - 20_000 }) }),
 		);
-		if (
-			result.surface.status !== "ready" ||
-			result.surface.overlay.kind !== "applying"
-		) {
-			assert.fail("expected the applying overlay");
-		}
-		assert.equal(result.surface.overlay.phase, "preparing");
-		assert.equal(result.clearStoredRun, false);
+		assert.equal(result.surface.status, "loading");
 	});
 
-	test("a poll that never answers gives up at the budget", () => {
+	test("a poll that never answers still claims no phase past the budget", () => {
 		const result = deriveUpdateSurface(
 			input({ held: held({ startedAt: NOW - BUDGET_MS - 60_000 }) }),
 		);
-		assert.equal(result.surface.status, "ready");
-		if (result.surface.status !== "ready") return;
-		assert.equal(result.surface.overlay.kind, "neverCameBack");
-		assert.equal(result.clearStoredRun, true);
+		assert.equal(result.surface.status, "loading");
 	});
 
-	test("an early server answer with no run yet keeps applying", () => {
+	test("the server's own account of the run it accepted carries the phase", () => {
 		const result = deriveUpdateSurface(
-			input({ data: response({ run: null }), held: held() }),
-		);
-		assert.equal(
-			result.surface.status === "ready" && result.surface.overlay.kind,
-			"applying",
-		);
-	});
-});
-
-function installMemoryStorage(): void {
-	const store = new Map<string, string>();
-	globalThis.localStorage = {
-		getItem: (k: string) => store.get(k) ?? null,
-		setItem: (k: string, v: string) => void store.set(k, v),
-		removeItem: (k: string) => void store.delete(k),
-		clear: () => store.clear(),
-		key: () => null,
-		length: 0,
-	} as Storage;
-}
-
-describe("held-run persistence", () => {
-	beforeEach(installMemoryStorage);
-
-	test("saves, loads and clears under the documented key", () => {
-		const record = held();
-		saveHeldRun(record);
-		assert.equal(
-			localStorage.getItem(SELF_UPDATE_RUN_KEY),
-			JSON.stringify(record),
+			input({
+				data: response({ run: null }),
+				held: held({ phase: "restarting" }),
+			}),
 		);
-		assert.deepEqual(loadHeldRun(), record);
-		clearStoredRun();
-		assert.equal(loadHeldRun(), null);
-	});
-
-	test("ignores a malformed stored value", () => {
-		localStorage.setItem(SELF_UPDATE_RUN_KEY, "{not json");
-		assert.equal(loadHeldRun(), null);
-		localStorage.setItem(SELF_UPDATE_RUN_KEY, JSON.stringify({ runId: 1 }));
-		assert.equal(loadHeldRun(), null);
+		if (
+			result.surface.status !== "ready" ||
+			result.surface.overlay.kind !== "applying"
+		) {
+			assert.fail("expected the applying overlay");
+		}
+		assert.equal(result.surface.overlay.phase, "restarting");
 	});
 });

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

@@ -3,16 +3,19 @@
  *
  * `GET /system/update` returns three independent things: the running version,
  * the outcome of the last manifest check, and the state of the current or last
- * run. This module folds that response — plus a run id the client persisted
- * before the server restarted, plus the clock — into the single `SelfUpdateState`
- * the `@remit/ui` components render, and into the full-window blocking overlay.
+ * run. This module folds that response — plus the run this client started and
+ * holds in memory, plus the clock — into the single `SelfUpdateState` the
+ * `@remit/ui` components render, and into the full-window blocking overlay.
  *
  * The design constraints (RFC 037 Interface, issue #135) live here:
- *  - A held run id turns a failed request into `applying`, never `unreachable`.
+ *  - The server decides whether an update is running and how far along it is.
+ *    Every phase shown is one the server reported for this run; an answer the
+ *    client is still waiting for renders no phase at all.
+ *  - A held run turns a failed request into `applying`, never `unreachable`.
  *  - Once the apply budget plus a margin has passed with no answer — a failed
- *    request or one still in flight — that silence becomes "the server never
- *    came back", a state that never claims the rollback ran, because from a
- *    dead connection the client cannot know.
+ *    request, or a server answering without accounting for the run — that
+ *    silence becomes "the server never came back", a state that never claims
+ *    the rollback ran, because from a dead connection the client cannot know.
  *  - The check block and the run block are independent: a check that cannot
  *    reach the update source is a failed check, never a failed update.
  */
@@ -25,9 +28,6 @@ import type {
 import type { ReleaseInfo, SelfUpdateState, UpdatePhase } from "@remit/ui";
 import { getErrorStatus } from "./error-classifier";
 
-/** localStorage key holding the run the client is resuming across a restart. */
-export const SELF_UPDATE_RUN_KEY = "remit.self-update.run";
-
 /**
  * The longest an apply can plausibly take — pull, snapshot, stop, start, gate —
  * before a silent server is treated as gone rather than still working. A five
@@ -42,15 +42,17 @@ export const FALLBACK_LOGS_COMMAND = "remit logs";
 const RELEASE_TAG_BASE = "https://github.com/remit-mail/reader/releases/tag/";
 
 /**
- * The record the client persists the moment it asks for an update, so a reload
- * or a second tab can resume watching a run that outlives the page that started
- * it. Everything needed to render the blocking screens without a reachable
- * server is here.
+ * The run this client asked for, kept in memory for as long as the page that
+ * asked lives. Nothing is written to storage: a run lasts about a minute and
+ * only the server knows how it ends, so a page that was not there for the
+ * request starts from the server's answer instead of from a record of its own.
  */
 export interface HeldRun {
 	runId: string;
 	attemptedVersion: string;
 	previousVersion: string;
+	/** The phase the server reported when it accepted the run. */
+	phase: UpdatePhase;
 	/** Epoch millis when the client began holding this run. */
 	startedAt: number;
 }
@@ -89,9 +91,7 @@ export interface DeriveInput {
 
 export interface DeriveResult {
 	surface: UpdateSurface;
-	/** The persisted resume token should be removed from localStorage. */
-	clearStoredRun: boolean;
-	/** The in-memory held run should be dropped — the run is fully resolved. */
+	/** The held run should be dropped — the server has accounted for it. */
 	releaseHeld: boolean;
 }
 
@@ -159,46 +159,6 @@ export function appliesSchemaMigration(
 	return target > current;
 }
 
-export function loadHeldRun(): HeldRun | null {
-	try {
-		const raw = localStorage.getItem(SELF_UPDATE_RUN_KEY);
-		if (!raw) return null;
-		const parsed: unknown = JSON.parse(raw);
-		if (!isHeldRun(parsed)) return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-}
-
-export function saveHeldRun(run: HeldRun): void {
-	try {
-		localStorage.setItem(SELF_UPDATE_RUN_KEY, JSON.stringify(run));
-	} catch {
-		// Best effort: private mode or quota. A lost token degrades resume, not
-		// correctness — the server remains the authority on the run.
-	}
-}
-
-export function clearStoredRun(): void {
-	try {
-		localStorage.removeItem(SELF_UPDATE_RUN_KEY);
-	} catch {
-		// Best effort, as above.
-	}
-}
-
-function isHeldRun(value: unknown): value is HeldRun {
-	if (!value || typeof value !== "object") return false;
-	const candidate = value as Record<string, unknown>;
-	return (
-		typeof candidate.runId === "string" &&
-		typeof candidate.attemptedVersion === "string" &&
-		typeof candidate.previousVersion === "string" &&
-		typeof candidate.startedAt === "number"
-	);
-}
-
 function budgetLimitSeconds(): number {
 	return APPLY_BUDGET_SECONDS + NEVER_CAME_BACK_MARGIN_SECONDS;
 }
@@ -316,20 +276,14 @@ function checkSection(
 function ready(
 	section: SelfUpdateState,
 	overlay: UpdateOverlay,
-	clearStoredRun: boolean,
 	releaseHeld: boolean,
 ): DeriveResult {
-	return {
-		surface: { status: "ready", section, overlay },
-		clearStoredRun,
-		releaseHeld,
-	};
+	return { surface: { status: "ready", section, overlay }, releaseHeld };
 }
 
 /**
- * The client gave up waiting. The stored token goes so a reload cannot resume
- * the same dead wait, while the in-memory hold stays: the screen has to sit
- * still, and its retry has to keep polling, until the server answers for itself.
+ * 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 {
@@ -350,15 +304,15 @@ function neverCameBack(held: HeldRun, elapsedSeconds: number): DeriveResult {
 				logsCommand: FALLBACK_LOGS_COMMAND,
 			},
 		},
-		clearStoredRun: true,
 		releaseHeld: false,
 	};
 }
 
 /**
  * A held run resolves to one of: still applying, gave up ("never came back"),
- * recovered but unaccountable, or — returning `null` — resolved terminally on
- * the server, in which case the caller renders the outcome from the response.
+ * unaccounted for, still waiting on a first answer, or — returning `null` —
+ * resolved terminally on the server, in which case the caller renders the
+ * outcome from the response.
  */
 function deriveHeld(
 	held: HeldRun,
@@ -385,7 +339,6 @@ function deriveHeld(
 			),
 			{ kind: "applying", target: run.targetVersion, phase, elapsedSeconds },
 			false,
-			false,
 		);
 	}
 
@@ -408,35 +361,13 @@ function deriveHeld(
 				elapsedSeconds,
 			},
 			false,
-			false,
 		);
 	}
 
-	// No answer yet — the resume request is still in flight. A request that is
-	// pending looks exactly like one that will never settle, so the budget bounds
-	// this wait too: within it the client stays applying, past it it stops
-	// claiming an install is running and says what it cannot account for.
+	// Nothing has come back yet. Silence is not a phase, so the surface waits
+	// rather than describing an install it has heard nothing about.
 	if (data === undefined) {
-		if (elapsedSeconds > budgetLimitSeconds()) {
-			return neverCameBack(held, elapsedSeconds);
-		}
-		return ready(
-			applyingSection(
-				held.runId,
-				currentVersion,
-				held.attemptedVersion,
-				"preparing",
-				elapsedSeconds,
-			),
-			{
-				kind: "applying",
-				target: held.attemptedVersion,
-				phase: "preparing",
-				elapsedSeconds,
-			},
-			false,
-			false,
-		);
+		return { surface: { status: "loading" }, releaseHeld: false };
 	}
 
 	// The server answered, but not with our run. If we have been gone longer than
@@ -455,55 +386,48 @@ function deriveHeld(
 				},
 				overlay: { kind: "none" },
 			},
-			clearStoredRun: true,
 			releaseHeld: true,
 		};
 	}
 
-	// Early: the server is up but has not written our run yet. Still applying.
-	const phase =
-		run !== null && run.outcome === null
-			? mapUpdatePhase(run.phase)
-			: "preparing";
+	// The updater picks the request up off a control file, so the seam keeps
+	// reporting the previous run for a moment. The phase stays the one the server
+	// gave when it accepted this run, until the server reports a newer one.
 	return ready(
 		applyingSection(
 			held.runId,
 			currentVersion,
 			held.attemptedVersion,
-			phase,
+			held.phase,
 			elapsedSeconds,
 		),
-		{ kind: "applying", target: held.attemptedVersion, phase, elapsedSeconds },
-		false,
+		{
+			kind: "applying",
+			target: held.attemptedVersion,
+			phase: held.phase,
+			elapsedSeconds,
+		},
 		false,
 	);
 }
 
-function displayFromData(input: DeriveInput): {
-	surface: UpdateSurface;
-	clearStoredRun: boolean;
-} {
+function displayFromData(input: DeriveInput): UpdateSurface {
 	const { data, isError, isFetching, dismissedRunId, checkRequested, now } =
 		input;
 
 	if (isError) {
 		return {
-			surface: {
-				status: "ready",
-				section: {
-					status: "checkFailed",
-					version: data?.currentVersion ?? "the current version",
-					reason: "Remit could not reach the update service.",
-				},
-				overlay: { kind: "none" },
+			status: "ready",
+			section: {
+				status: "checkFailed",
+				version: data?.currentVersion ?? "the current version",
+				reason: "Remit could not reach the update service.",
 			},
-			clearStoredRun: true,
+			overlay: { kind: "none" },
 		};
 	}
 
-	if (!data) {
-		return { surface: { status: "loading" }, clearStoredRun: false };
-	}
+	if (!data) return { status: "loading" };
 
 	const run = data.run;
 	const dismissed =
@@ -511,12 +435,9 @@ function displayFromData(input: DeriveInput): {
 
 	if (run !== null && !dismissed && run.outcome !== null) {
 		return {
-			surface: {
-				status: "ready",
-				section: terminalSection(data, run, run.outcome),
-				overlay: { kind: "none" },
-			},
-			clearStoredRun: true,
+			status: "ready",
+			section: terminalSection(data, run, run.outcome),
+			overlay: { kind: "none" },
 		};
 	}
 
@@ -524,33 +445,27 @@ function displayFromData(input: DeriveInput): {
 		const elapsedSeconds = elapsedSince(parseIso(run.startedAt) ?? now, now);
 		const phase = mapUpdatePhase(run.phase);
 		return {
-			surface: {
-				status: "ready",
-				section: applyingSection(
-					run.runId,
-					run.fromVersion,
-					run.targetVersion,
-					phase,
-					elapsedSeconds,
-				),
-				overlay: {
-					kind: "applying",
-					target: run.targetVersion,
-					phase,
-					elapsedSeconds,
-				},
+			status: "ready",
+			section: applyingSection(
+				run.runId,
+				run.fromVersion,
+				run.targetVersion,
+				phase,
+				elapsedSeconds,
+			),
+			overlay: {
+				kind: "applying",
+				target: run.targetVersion,
+				phase,
+				elapsedSeconds,
 			},
-			clearStoredRun: false,
 		};
 	}
 
 	return {
-		surface: {
-			status: "ready",
-			section: checkSection(data, checkRequested && isFetching, now),
-			overlay: { kind: "none" },
-		},
-		clearStoredRun: false,
+		status: "ready",
+		section: checkSection(data, checkRequested && isFetching, now),
+		overlay: { kind: "none" },
 	};
 }
 
@@ -559,29 +474,15 @@ export function deriveUpdateSurface(input: DeriveInput): DeriveResult {
 	const run = data?.run ?? null;
 
 	if (isSurfaceAbsent(error) && !held) {
-		return {
-			surface: { status: "absent" },
-			clearStoredRun: true,
-			releaseHeld: true,
-		};
+		return { surface: { status: "absent" }, releaseHeld: true };
 	}
 
 	if (held) {
 		const heldResult = deriveHeld(held, data, run, isError, now);
 		if (heldResult) return heldResult;
 		// Our run resolved terminally — render it from the response and let go.
-		const resolved = displayFromData(input);
-		return {
-			surface: resolved.surface,
-			clearStoredRun: true,
-			releaseHeld: true,
-		};
+		return { surface: displayFromData(input), releaseHeld: true };
 	}
 
-	const display = displayFromData(input);
-	return {
-		surface: display.surface,
-		clearStoredRun: display.clearStoredRun,
-		releaseHeld: false,
-	};
+	return { surface: displayFromData(input), releaseHeld: false };
 }