@remit/web-client 0.0.240 → 0.0.241

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.240",
+  "version": "0.0.241",
   "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/auth/auth-interceptor.test.ts

@@ -1,15 +1,19 @@
 import assert from "node:assert";
-import { describe, test } from "node:test";
+import { afterEach, describe, test } from "node:test";
+import { client } from "@remit/api-http-client/client.gen.ts";
+import { trashOperationsEmptyTrash } from "@remit/api-http-client/sdk.gen.ts";
+import { type HttpMock, mockFetch } from "../test-support/http";
 import { AuthTokenError } from "./better-auth-config";
 import { type AuthProvider, noneAuthProvider } from "./provider";
 
-type RequestFn = (req: Request) => Promise<Request>;
-
-declare global {
-	var __REMIT_CLIENT_MOCKS__: { requestFns: RequestFn[] } | undefined;
-}
-
 let cacheBust = 1000;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	http?.restore();
+	http = undefined;
+	client.interceptors.request.clear();
+});
 
 const providerWithToken = (
 	getToken: AuthProvider["getToken"],
@@ -17,15 +21,30 @@ const providerWithToken = (
 
 const loadInterceptor = async () => {
 	cacheBust += 1;
-	globalThis.__REMIT_CLIENT_MOCKS__ = { requestFns: [] };
+	client.interceptors.request.clear();
 	return import(`./auth-interceptor.ts?v=${cacheBust}`);
 };
 
+const send = (headers?: Record<string, string>): Promise<unknown> => {
+	http = mockFetch();
+	return trashOperationsEmptyTrash({
+		path: { accountId: "acc-1" },
+		headers,
+		throwOnError: true,
+	});
+};
+
+const sentHeaders = (): Record<string, string> => {
+	assert.ok(http, "expected a request to have been sent");
+	assert.equal(http.calls.length, 1);
+	return http.calls[0].headers;
+};
+
 describe("installAuthInterceptor", () => {
 	test("registers exactly one request interceptor", async () => {
 		const mod = await loadInterceptor();
 		mod.installAuthInterceptor(providerWithToken(async () => null));
-		assert.equal(globalThis.__REMIT_CLIENT_MOCKS__?.requestFns.length, 1);
+		assert.equal(client.interceptors.request.fns.length, 1);
 	});
 
 	test("is idempotent — subsequent calls do not register additional interceptors", async () => {
@@ -34,17 +53,14 @@ describe("installAuthInterceptor", () => {
 		mod.installAuthInterceptor(provider);
 		mod.installAuthInterceptor(provider);
 		mod.installAuthInterceptor(provider);
-		assert.equal(globalThis.__REMIT_CLIENT_MOCKS__?.requestFns.length, 1);
+		assert.equal(client.interceptors.request.fns.length, 1);
 	});
 
 	test("attaches the provider's Bearer token when one exists", async () => {
 		const mod = await loadInterceptor();
 		mod.installAuthInterceptor(providerWithToken(async () => "ID-TOKEN-123"));
-		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
-		assert.ok(fn, "expected interceptor fn to be registered");
-		const req = new Request("https://api.example.com/thing");
-		const out = await fn(req);
-		assert.equal(out.headers.get("Authorization"), "Bearer ID-TOKEN-123");
+		await send();
+		assert.equal(sentHeaders().authorization, "Bearer ID-TOKEN-123");
 	});
 
 	test("abandons the request when the token cannot be minted — never sends it unauthenticated", async () => {
@@ -54,42 +70,32 @@ describe("installAuthInterceptor", () => {
 				throw new AuthTokenError("Could not mint a session token: 429", 429);
 			}),
 		);
-		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
-		assert.ok(fn);
-		const req = new Request("https://api.example.com/thing");
 		await assert.rejects(
-			() => fn(req),
+			() => send(),
 			(error: unknown) => {
 				assert.ok(error instanceof AuthTokenError);
 				assert.equal(error.status, 429);
 				return true;
 			},
 		);
-		assert.equal(req.headers.get("Authorization"), null);
+		assert.equal(http?.calls.length, 0);
 	});
 
 	test("omits Authorization header when the deployment presents no identity", async () => {
 		const mod = await loadInterceptor();
 		mod.installAuthInterceptor(providerWithToken(async () => null));
-		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
-		assert.ok(fn);
-		const req = new Request("https://api.example.com/thing");
-		const out = await fn(req);
-		assert.equal(out.headers.get("Authorization"), null);
+		await send();
+		assert.equal(sentHeaders().authorization, undefined);
 	});
 
 	test("preserves caller-supplied headers when adding Authorization", async () => {
 		const mod = await loadInterceptor();
 		mod.installAuthInterceptor(providerWithToken(async () => "TOK"));
-		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
-		assert.ok(fn);
-		const req = new Request("https://api.example.com/thing", {
-			headers: { "X-Trace-Id": "abc-123", "Content-Type": "application/json" },
-		});
-		const out = await fn(req);
-		assert.equal(out.headers.get("X-Trace-Id"), "abc-123");
-		assert.equal(out.headers.get("Content-Type"), "application/json");
-		assert.equal(out.headers.get("Authorization"), "Bearer TOK");
+		await send({ "X-Trace-Id": "abc-123", "X-Client": "reader" });
+		const headers = sentHeaders();
+		assert.equal(headers["x-trace-id"], "abc-123");
+		assert.equal(headers["x-client"], "reader");
+		assert.equal(headers.authorization, "Bearer TOK");
 	});
 
 	test("propagates errors when the provider's getToken rejects (let it crash)", async () => {
@@ -99,9 +105,6 @@ describe("installAuthInterceptor", () => {
 				throw new Error("session fetch failed");
 			}),
 		);
-		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
-		assert.ok(fn);
-		const req = new Request("https://api.example.com/thing");
-		await assert.rejects(() => fn(req), /session fetch failed/);
+		await assert.rejects(() => send(), /session fetch failed/);
 	});
 });

package/src/components/compose/ComposeForm.tsx

@@ -14,12 +14,15 @@ import {
 	ComposeBodySkeleton,
 	ComposeFormShell,
 	ComposeHeader,
+	ComposeQuoteMissingBanner,
+	type ComposeQuoteMode,
 	type ComposeSendState,
 	type ComposeShellLayout,
 	ComposeSubjectField,
 	composeHeaderSummary,
 	defaultComposeLanguages,
 	modeOfDraft,
+	NO_QUOTABLE_BODY_FORWARD_MESSAGE,
 	QuotedText,
 	type RichTextValue,
 	SMTP_MISSING_MESSAGE,
@@ -678,6 +681,7 @@ export const ComposeForm = ({
 		data: sourceBody,
 		isLoading: quoteIsLoading,
 		isError: quoteFailed,
+		hasNoRenderablePart: sourceHasNoQuotableBody,
 		refetch: refetchQuote,
 	} = useMessageBodyContent({
 		messageId: sourceMessage?.message.messageId,
@@ -685,6 +689,31 @@ export const ComposeForm = ({
 		enabled: isQuoting && !!sourceMessage,
 	});
 
+	const quoteMode: ComposeQuoteMode = mode === "forward" ? "forward" : "reply";
+
+	/**
+	 * The message being answered has not arrived yet, so the quote's own fetch
+	 * cannot have started — it picks its part out of what has not landed. A send
+	 * pressed in this window went out carrying none of the original and was
+	 * refused by nothing, because "no part picked" reads the same here as "this
+	 * message has no part to pick" (#1030).
+	 */
+	const quoteSourceIsLoading = isQuoting && !sourceMessage;
+
+	/**
+	 * The message being answered arrived carrying attachments and no text. A
+	 * forward of it is refused: the composer sends a text body and an html body
+	 * and no attachments, so the forward would arrive holding nothing of the
+	 * original at all. A reply goes out — it carries the answer and the thread's
+	 * references either way — and says the original is not quoted in it.
+	 *
+	 * Not stated for a resumed draft, whose body already holds whatever quote it
+	 * was saved with; this composer is not the one that assembles it.
+	 */
+	const quoteHasNoBody =
+		isQuoting && !documentHoldsQuote && sourceHasNoQuotableBody;
+	const nothingToForward = quoteHasNoBody && quoteMode === "forward";
+
 	/**
 	 * The original as it will be sent, and as it is shown while the answer is
 	 * written — one value for both, because the two disagreeing is the whole of
@@ -818,7 +847,7 @@ export const ComposeForm = ({
 			if (selectedAccountMissingSmtp) {
 				return { status: "blocked", reason: SMTP_MISSING_MESSAGE };
 			}
-			if (quoteIsLoading) {
+			if (quoteIsLoading || quoteSourceIsLoading) {
 				return { status: "blocked", reason: QUOTE_LOADING_MESSAGE };
 			}
 			if (unparsed) {
@@ -827,9 +856,26 @@ export const ComposeForm = ({
 			if (toCount === 0) {
 				return { status: "blocked", reason: NO_TO_ADDRESS_MESSAGE };
 			}
+			// Last of the refusals: the others name something the writer can go and
+			// fix, and this one names something about the message being forwarded
+			// that they cannot. The banner above states it the whole time either
+			// way, so the press is better spent on the fixable thing.
+			if (nothingToForward) {
+				return {
+					status: "blocked",
+					reason: NO_QUOTABLE_BODY_FORWARD_MESSAGE,
+				};
+			}
 			return { status: "ready", accountId: selectedAccountId };
 		},
-		[isSending, selectedAccountId, selectedAccountMissingSmtp, quoteIsLoading],
+		[
+			isSending,
+			selectedAccountId,
+			selectedAccountMissingSmtp,
+			quoteIsLoading,
+			quoteSourceIsLoading,
+			nothingToForward,
+		],
 	);
 	const sendReadiness = useMemo<SendReadiness>(
 		() =>
@@ -1092,6 +1138,9 @@ export const ComposeForm = ({
 							configureRef={smtpConfigureRef}
 						/>
 					) : null}
+					{quoteHasNoBody ? (
+						<ComposeQuoteMissingBanner mode={quoteMode} />
+					) : null}
 					{quoteFailed ? (
 						<Banner tone="warning" data-testid="compose-quote-failed">
 							<span>{QUOTE_FAILED_MESSAGE}</span>{" "}

package/src/components/compose/attachment-only-source.render.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Issue #1030: a source with no text or html part — a message that is
+ * attachments and nothing else — left the quote hook disabled, so nothing was
+ * loading, nothing had failed, and the composer sent a forward carrying none of
+ * the original at all.
+ *
+ * The composer sends a text body and an html body and no attachments, so that
+ * forward has nothing to arrive with: it is refused, in words. A reply still
+ * carries the answer and the thread's references, so it goes out and says the
+ * original is not quoted in it. And a source that has not arrived yet is a
+ * third thing again — still loading, not a message with nothing in it.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type {
+	RemitImapAccountResponse,
+	RemitImapDescribeMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { NO_QUOTABLE_BODY_FORWARD_MESSAGE } from "@remit/ui";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	RouterContextProvider,
+} from "@tanstack/react-router";
+import { createElement, useState } from "react";
+import { createDomHarness, type DomHarness } from "../../test-support/dom";
+import { type HttpMock, mockFetch } from "../../test-support/http";
+import { ComposeForm } from "./ComposeForm";
+import type { ComposeMode } from "./ComposeProvider";
+import { ComposeProvider } from "./ComposeProvider";
+
+const ACCOUNT_ID = "acc-1";
+
+const account = {
+	accountId: ACCOUNT_ID,
+	email: "me@example.com",
+	smtpEnabled: true,
+} as unknown as RemitImapAccountResponse;
+
+/** Two scans and a cover sheet — no text part anywhere in it. */
+const attachmentOnlySource = {
+	message: { messageId: "msg-1" },
+	envelope: {
+		subject: "Scans",
+		date: Date.UTC(2026, 5, 24, 9, 14),
+		messageIdValue: "<m1@example.com>",
+		from: [{ normalizedEmail: "dana@example.com", displayName: "Dana" }],
+		replyTo: [],
+		to: [{ normalizedEmail: "me@example.com" }],
+		cc: [],
+	},
+	references: [],
+	bodyParts: [
+		{
+			mediaType: "MULTIPART",
+			mediaSubtype: "MIXED",
+			contentUrl: "",
+			isMultipart: true,
+		},
+		{
+			mediaType: "IMAGE",
+			mediaSubtype: "JPEG",
+			disposition: "attachment",
+			contentUrl: "/content/msg-1/2.jpg",
+			isMultipart: false,
+		},
+	],
+} as unknown as RemitImapDescribeMessageResponse;
+
+const outboxEntry = () => ({
+	outboxMessageId: "ob-1030",
+	accountId: ACCOUNT_ID,
+	fromAddress: account.email,
+	toAddresses: ["dana@example.com"],
+	ccAddresses: [],
+	bccAddresses: [],
+	references: [],
+	subject: "Fwd: Scans",
+	status: "draft",
+});
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+});
+
+const Opened = ({
+	mode,
+	sourceMessage,
+}: {
+	mode: ComposeMode;
+	sourceMessage?: RemitImapDescribeMessageResponse;
+}) => {
+	const [draftId, setDraftId] = useState<string | undefined>(undefined);
+
+	return createElement(ComposeForm, {
+		mode,
+		account,
+		sourceMessage,
+		outboxMessageId: draftId,
+		onDraftCreated: setDraftId,
+		onClose: () => {},
+	});
+};
+
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+const rootRoute = createRootRoute();
+const mailboxRoute = createRoute({
+	getParentRoute: () => rootRoute,
+	path: "/mail/$mailboxId",
+	validateSearch: (search: Record<string, unknown>) => search,
+});
+
+const testRouter = (): AnyRouter =>
+	createRouter({
+		routeTree: rootRoute.addChildren([mailboxRoute]),
+		history: createMemoryHistory({ initialEntries: ["/mail/mbx-1"] }),
+	}) as unknown as AnyRouter;
+
+const mount = async (options: {
+	mode: ComposeMode;
+	/** Left out for the deep link that opened before the source landed. */
+	sourceMessage?: RemitImapDescribeMessageResponse;
+}): Promise<void> => {
+	http = mockFetch(async (call) => {
+		if (call.path.endsWith("/config")) return { accounts: [account] };
+		return outboxEntry();
+	});
+
+	harness = createDomHarness();
+	harness.renderApp(
+		createElement(RouterContextProvider, {
+			router: testRouter(),
+			// biome-ignore lint/correctness/noChildrenProp: RouterContextProvider types `children` as a required prop, which createElement's rest-argument form does not satisfy
+			children: createElement(
+				ComposeProvider,
+				null,
+				createElement(Opened, {
+					mode: options.mode,
+					sourceMessage: options.sourceMessage,
+				}),
+			),
+		}),
+	);
+	await harness.flush();
+	await harness.wait(100);
+	await harness.flush();
+};
+
+const sendButton = (): HTMLElement => {
+	const button = harness?.byText("button", "Send");
+	if (!button) throw new Error("the compose send button is not mounted");
+	return button;
+};
+
+const addRecipient = (email: string): void => {
+	const field = harness?.query<HTMLInputElement>("#address-field-To");
+	if (!field) throw new Error("the To field is not mounted");
+	harness?.type(field, email);
+};
+
+const dispatches = (): number =>
+	(http?.calls ?? []).filter((call) => call.path.endsWith("/send")).length;
+
+const press = async (): Promise<void> => {
+	harness?.click(sendButton());
+	await harness?.flush();
+	await harness?.wait(100);
+};
+
+describe("a source with nothing to quote (#1030)", () => {
+	it("refuses a forward of a message that is attachments only", async () => {
+		await mount({ mode: "forward", sourceMessage: attachmentOnlySource });
+
+		addRecipient("bob@example.com");
+		await press();
+
+		assert.equal(
+			dispatches(),
+			0,
+			"a forward left with nothing of the message it forwards",
+		);
+		assert.ok(
+			(harness?.text() ?? "").includes(NO_QUOTABLE_BODY_FORWARD_MESSAGE),
+			"the refusal was not stated",
+		);
+	});
+
+	it("says so on screen before the forward is even written", async () => {
+		await mount({ mode: "forward", sourceMessage: attachmentOnlySource });
+
+		const banner = harness?.query("[data-testid=compose-quote-missing]");
+		assert.ok(banner, "nothing said the message had no body to quote");
+	});
+
+	it("sends a reply to it, saying the original is not quoted", async () => {
+		await mount({ mode: "reply", sourceMessage: attachmentOnlySource });
+
+		assert.ok(
+			harness?.query("[data-testid=compose-quote-missing]"),
+			"nothing said the original would not be quoted",
+		);
+
+		await press();
+
+		assert.equal(dispatches(), 1, "the reply was not sent");
+	});
+
+	it("refuses while the source is still on its way, without claiming it is empty", async () => {
+		await mount({ mode: "forward" });
+
+		addRecipient("bob@example.com");
+		await press();
+
+		assert.equal(dispatches(), 0, "a forward left before its source arrived");
+		assert.match(harness?.text() ?? "", /Loading the message you're quoting/);
+		assert.equal(
+			harness?.query("[data-testid=compose-quote-missing]"),
+			null,
+			"a source still arriving was reported as a message with no body",
+		);
+	});
+});

package/src/components/mail/RoleAppointmentPromptProvider.tsx

@@ -24,6 +24,7 @@ import {
 import { isMailboxNotSettledRefusal } from "@/components/ui/folder-role-refusal";
 import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
+import { softErrorStatuses } from "@/lib/error-classifier";
 import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
 import { buildMoveOptions, folderDelimiter } from "@/lib/move-options";
 
@@ -90,9 +91,12 @@ export const RoleAppointmentPromptProvider = ({
 		enabled: !!accountId,
 	});
 	const { createFolderIn } = useCreateMailbox(accountId);
-	const appointMutation = useMutation(
-		folderRoleOperationsAppointFolderRoleMutation(),
-	);
+	const appointMutation = useMutation({
+		...folderRoleOperationsAppointFolderRoleMutation(),
+		// A mailbox still settling answers 409, and the prompt states that itself
+		// in `appoint-failed`. Escalating would take the screen the prompt is on.
+		meta: softErrorStatuses(409),
+	});
 
 	const account = config?.accounts.find((one) => one.accountId === accountId);
 	const mailboxes = useMemo(() => mailboxData?.items ?? [], [mailboxData]);

package/src/components/ui/folder-role-refusal.test.ts

@@ -1,19 +1,26 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
+import { wrapHttpFailure } from "@/lib/api";
 import {
 	isFolderRoleRefusal,
 	isMailboxNotSettledRefusal,
 } from "./folder-role-refusal.js";
 
-const refusal = {
+const wireBody = {
 	code: "folder_role_unresolved",
 	message: "No folder is appointed as Trash",
 	details: { role: "Trash", reason: "none", accountId: "acct-1" },
 };
 
+// Every call site takes the error interceptor, so what reaches these readers is
+// always the `ApiError` `wrapHttpFailure` builds — never the flat wire body it
+// carries at `.body` (#1004).
+const refused = (body: Record<string, unknown> = wireBody) =>
+	wrapHttpFailure(body, 409);
+
 describe("isFolderRoleRefusal", () => {
 	it("carries the account and the reason the prompt needs", () => {
-		assert.deepEqual(isFolderRoleRefusal(refusal), {
+		assert.deepEqual(isFolderRoleRefusal(refused()), {
 			reason: "none",
 			role: "Trash",
 			accountId: "acct-1",
@@ -23,10 +30,9 @@ describe("isFolderRoleRefusal", () => {
 	it("reads every reason the API declares", () => {
 		for (const reason of ["none", "stale", "unconfirmed"]) {
 			assert.equal(
-				isFolderRoleRefusal({
-					...refusal,
-					details: { ...refusal.details, reason },
-				})?.reason,
+				isFolderRoleRefusal(
+					refused({ ...wireBody, details: { ...wireBody.details, reason } }),
+				)?.reason,
 				reason,
 			);
 		}
@@ -34,14 +40,18 @@ describe("isFolderRoleRefusal", () => {
 
 	it("does not open the prompt for a 409 without the code", () => {
 		assert.equal(
-			isFolderRoleRefusal({
-				message: "No folder is appointed as Trash",
-				details: refusal.details,
-			}),
+			isFolderRoleRefusal(
+				refused({
+					message: "No folder is appointed as Trash",
+					details: wireBody.details,
+				}),
+			),
 			undefined,
 		);
 		assert.equal(
-			isFolderRoleRefusal({ ...refusal, code: "mailbox_not_settled" }),
+			isFolderRoleRefusal(
+				refused({ ...wireBody, code: "mailbox_not_settled" }),
+			),
 			undefined,
 		);
 	});
@@ -51,22 +61,32 @@ describe("isFolderRoleRefusal", () => {
 			isFolderRoleRefusal(new Error("folder_role_unresolved: Trash")),
 			undefined,
 		);
+		assert.equal(
+			isFolderRoleRefusal(
+				wrapHttpFailure({ message: "folder_role_unresolved" }, 409),
+			),
+			undefined,
+		);
 	});
 
 	it("refuses a body missing anything the prompt has to have", () => {
-		assert.equal(isFolderRoleRefusal({ ...refusal, details: {} }), undefined);
 		assert.equal(
-			isFolderRoleRefusal({
-				...refusal,
-				details: { role: "Trash", reason: "sideways", accountId: "acct-1" },
-			}),
+			isFolderRoleRefusal(refused({ ...wireBody, details: {} })),
+			undefined,
+		);
+		assert.equal(
+			isFolderRoleRefusal(
+				refused({
+					...wireBody,
+					details: { role: "Trash", reason: "sideways", accountId: "acct-1" },
+				}),
+			),
 			undefined,
 		);
 		assert.equal(
-			isFolderRoleRefusal({
-				...refusal,
-				details: { role: "Trash", reason: "none" },
-			}),
+			isFolderRoleRefusal(
+				refused({ ...wireBody, details: { role: "Trash", reason: "none" } }),
+			),
 			undefined,
 		);
 	});
@@ -75,20 +95,30 @@ describe("isFolderRoleRefusal", () => {
 		for (const value of [undefined, null, "boom", 409, []]) {
 			assert.equal(isFolderRoleRefusal(value), undefined);
 		}
+		assert.equal(
+			isFolderRoleRefusal(wrapHttpFailure(undefined, 500)),
+			undefined,
+		);
+	});
+
+	it("still reads a bare wire body", () => {
+		assert.equal(isFolderRoleRefusal(wireBody)?.accountId, "acct-1");
 	});
 });
 
 describe("isMailboxNotSettledRefusal", () => {
 	it("matches only the appointment write's own refusal", () => {
 		assert.equal(
-			isMailboxNotSettledRefusal({
-				code: "mailbox_not_settled",
-				message: "Mailbox is still being created",
-				details: { mailboxId: "mbx-1", syncStatus: "pending" },
-			}),
+			isMailboxNotSettledRefusal(
+				refused({
+					code: "mailbox_not_settled",
+					message: "Mailbox is still being created",
+					details: { mailboxId: "mbx-1", syncStatus: "pending" },
+				}),
+			),
 			true,
 		);
-		assert.equal(isMailboxNotSettledRefusal(refusal), false);
+		assert.equal(isMailboxNotSettledRefusal(refused()), false);
 		assert.equal(isMailboxNotSettledRefusal(new Error("pending")), false);
 	});
 });

package/src/components/ui/folder-role-refusal.ts

@@ -5,11 +5,9 @@
  * appointment prompt over an unrelated conflict. A 409 without one of these
  * codes is somebody else's error and keeps today's banner.
  */
-import type {
-	ApiError,
-	RemitImapCanonicalMailboxRole,
-} from "@remit/api-http-client/types.gen.ts";
+import type { RemitImapCanonicalMailboxRole } from "@remit/api-http-client/types.gen.ts";
 import { CanonicalMailboxRole } from "@remit/domain-enums";
+import { type CodedApiErrorBody, codedApiErrorBody } from "@/lib/api";
 
 /** Why the role is unresolved, as the API's `details.reason` spells it. */
 export type FolderRoleRefusalReason = "none" | "stale" | "unconfirmed";
@@ -29,18 +27,8 @@ const REASONS: ReadonlySet<string> = new Set<FolderRoleRefusalReason>([
 
 const ROLES: ReadonlySet<string> = new Set(Object.values(CanonicalMailboxRole));
 
-/**
- * The wire body as `handleError` emits it — flat, so `code` and `details` sit
- * at the top level. Everything is re-checked at runtime: this is a network
- * boundary, and the type only says what the contract promises.
- */
-const bodyOf = (error: unknown): Partial<ApiError> | undefined =>
-	typeof error === "object" && error !== null
-		? (error as Partial<ApiError>)
-		: undefined;
-
 const stringAt = (
-	details: ApiError["details"],
+	details: CodedApiErrorBody["details"],
 	key: string,
 ): string | undefined => {
 	const value = details?.[key];
@@ -55,10 +43,10 @@ const stringAt = (
 export const isFolderRoleRefusal = (
 	error: unknown,
 ): FolderRoleRefusal | undefined => {
-	const body = bodyOf(error);
+	const body = codedApiErrorBody(error);
 	if (body?.code !== "folder_role_unresolved") return undefined;
 	const { details } = body;
-	if (typeof details !== "object" || details === null) return undefined;
+	if (!details) return undefined;
 	const reason = stringAt(details, "reason");
 	const role = stringAt(details, "role");
 	const accountId = stringAt(details, "accountId");
@@ -78,4 +66,4 @@ export const isFolderRoleRefusal = (
  * one, retrying does not.
  */
 export const isMailboxNotSettledRefusal = (error: unknown): boolean =>
-	bodyOf(error)?.code === "mailbox_not_settled";
+	codedApiErrorBody(error)?.code === "mailbox_not_settled";

package/src/components/ui/placement-refusal.test.ts

@@ -1,15 +1,23 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
+import { wrapHttpFailure } from "@/lib/api";
 import {
 	isPlacementRefusal,
 	placementRefusalBanner,
 } from "./placement-refusal.js";
 
-const refusal = (reason: string) => ({
-	message: "Message 4f1 was not acted on: its folder and uid do not name...",
-	code: "message_placement_unsettled",
-	details: { accountId: "acc-1", messageId: "msg-1", reason },
-});
+// The reader is handed what the error interceptor produces, not the flat wire
+// body it carries at `.body` (#1004).
+const refusal = (reason: string) =>
+	wrapHttpFailure(
+		{
+			message:
+				"Message 4f1 was not acted on: its folder and uid do not name...",
+			code: "message_placement_unsettled",
+			details: { accountId: "acc-1", messageId: "msg-1", reason },
+		},
+		409,
+	);
 
 describe("isPlacementRefusal", () => {
 	it("reads the reason and the message off the coded body", () => {
@@ -23,7 +31,7 @@ describe("isPlacementRefusal", () => {
 		assert.equal(isPlacementRefusal(undefined), undefined);
 		assert.equal(isPlacementRefusal(new Error("network")), undefined);
 		assert.equal(
-			isPlacementRefusal({ ...refusal("in_flight"), code: "other" }),
+			isPlacementRefusal(wrapHttpFailure({ code: "other" }, 409)),
 			undefined,
 		);
 		assert.equal(isPlacementRefusal(refusal("something_else")), undefined);

package/src/components/ui/placement-refusal.ts

@@ -4,8 +4,8 @@
  * server's sentence names a uuid and no remedy, and a message-string match
  * would start firing on an unrelated conflict the moment the copy changes.
  */
-import type { ApiError } from "@remit/api-http-client/types.gen.ts";
 import type { PushErrorInput } from "@/components/ui/error-banners";
+import { type CodedApiErrorBody, codedApiErrorBody } from "@/lib/api";
 
 /**
  * `in_flight` clears on its own once the mail server confirms the move;
@@ -25,7 +25,7 @@ const REASONS: ReadonlySet<string> = new Set<PlacementRefusalReason>([
 ]);
 
 const stringAt = (
-	details: ApiError["details"],
+	details: CodedApiErrorBody["details"],
 	key: string,
 ): string | undefined => {
 	const value = details?.[key];
@@ -35,11 +35,10 @@ const stringAt = (
 export const isPlacementRefusal = (
 	error: unknown,
 ): PlacementRefusal | undefined => {
-	if (typeof error !== "object" || error === null) return undefined;
-	const body = error as Partial<ApiError>;
-	if (body.code !== "message_placement_unsettled") return undefined;
+	const body = codedApiErrorBody(error);
+	if (body?.code !== "message_placement_unsettled") return undefined;
 	const { details } = body;
-	if (typeof details !== "object" || details === null) return undefined;
+	if (!details) return undefined;
 	const reason = stringAt(details, "reason");
 	const messageId = stringAt(details, "messageId");
 	if (!reason || !REASONS.has(reason) || !messageId) return undefined;

package/src/hooks/refusal-escalation.render.test.ts

@@ -0,0 +1,187 @@
+/**
+ * A coded 409 must reach the surface that answers it and nothing else (#1004).
+ *
+ * Both delete paths raise through `useMutation`, and the app wires the global
+ * fail-fast sink on the `MutationCache` (`shell/index.tsx`), where a 409 with
+ * no `meta` escalates to the full-screen fatal overlay. The prompt then opens
+ * underneath a red page nobody can see past — the refusal is handled and still
+ * never reaches the user. Every other test mounts on the harness's plain
+ * `QueryClient`, which has no such sink, so none of them can see this.
+ *
+ * Mounted here on the client the app actually builds, with the error
+ * interceptor registered.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	MutationCache,
+	QueryCache,
+	QueryClient,
+	QueryClientProvider,
+} from "@tanstack/react-query";
+import { act, createElement } from "react";
+import { RoleAppointmentPromptProvider } from "@/components/mail/RoleAppointmentPromptProvider";
+import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
+import { __resetFatalError, getCurrentFatalError } from "@/lib/fatal-error";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "@/lib/query-error-handler";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { useDeleteMessages } from "./useDeleteMessages";
+import { type EmptyTrashState, useEmptyTrash } from "./useEmptyTrash";
+import "@/lib/client";
+
+const ACCOUNT = "acc-1";
+const INBOX = "mbx-inbox";
+const TRASH = "mbx-trash";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+let deleteMessages: ((messageIds: string[]) => void) | undefined;
+let trash: EmptyTrashState | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	deleteMessages = undefined;
+	trash = undefined;
+	__resetFatalError();
+});
+
+const CONFIG = {
+	accounts: [
+		{
+			accountId: ACCOUNT,
+			email: "you@example.com",
+			folderAppointments: [
+				{ role: "Trash", mailboxId: TRASH, source: "Proposed" },
+			],
+		},
+	],
+};
+
+/** Fresh every call — a `Response` body can only be read once. */
+const refusal = (): Response =>
+	new Response(
+		JSON.stringify({
+			status: 409,
+			message: "Nobody has confirmed which folder is this account's Trash",
+			code: "folder_role_unresolved",
+			details: { reason: "unconfirmed", role: "Trash", accountId: ACCOUNT },
+		}),
+		{ status: 409, headers: { "content-type": "application/json" } },
+	);
+
+const broken = (): Response =>
+	new Response(JSON.stringify({ message: "boom" }), {
+		status: 500,
+		headers: { "content-type": "application/json" },
+	});
+
+const Probe = () => {
+	deleteMessages = useDeleteMessages({
+		mailboxId: INBOX,
+		accountId: ACCOUNT,
+	}).deleteMessages;
+	trash = useEmptyTrash({ accountId: ACCOUNT, mailboxId: TRASH });
+	return null;
+};
+
+/** 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 settle = async (): Promise<void> => {
+	if (!harness) throw new Error("nothing mounted");
+	for (let round = 0; round < 40; round += 1) {
+		await harness.flush();
+		await harness.wait(0);
+	}
+};
+
+const mount = async (respond: (path: string) => unknown): Promise<void> => {
+	http = mockFetch((call) => respond(call.path));
+	harness = createDomHarness({ queryClient: appQueryClient() });
+	await harness.renderAsync(
+		createElement(
+			QueryClientProvider,
+			{ client: harness.queryClient as never },
+			createElement(
+				ErrorBannerProvider,
+				null,
+				createElement(
+					RoleAppointmentPromptProvider,
+					null,
+					createElement(Probe),
+				),
+			),
+		),
+	);
+	await settle();
+};
+
+const responder =
+	(endpoint: string, answer: () => Response) =>
+	(path: string): unknown => {
+		if (path.endsWith("/config")) return CONFIG;
+		if (path.endsWith(endpoint)) return answer();
+		return {};
+	};
+
+describe("a delete refused for its folder role", () => {
+	it("opens the appointment prompt without taking the screen", async () => {
+		await mount(responder("/messages/delete", refusal));
+
+		await act(async () => {
+			deleteMessages?.(["msg-1"]);
+		});
+		await settle();
+
+		assert.match(harness?.text() ?? "", /Confirm this account's Trash folder/);
+		assert.equal(
+			getCurrentFatalError(),
+			null,
+			"a refusal the prompt answers is not a fatal error",
+		);
+	});
+
+	it("still escalates a 500 on the same delete", async () => {
+		await mount(responder("/messages/delete", broken));
+
+		await act(async () => {
+			deleteMessages?.(["msg-1"]);
+		});
+		await settle();
+
+		assert.ok(
+			getCurrentFatalError(),
+			"the 409 opt-out must not cover anything else",
+		);
+	});
+});
+
+describe("an empty Trash refused for its folder role", () => {
+	it("states the refusal in the pane without taking the screen", async () => {
+		await mount(responder("/trash/empty", refusal));
+
+		await act(async () => {
+			trash?.emptyTrash();
+		});
+		await settle();
+
+		assert.equal(trash?.refusal?.reason, "unconfirmed");
+		assert.equal(getCurrentFatalError(), null);
+	});
+});

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

@@ -558,6 +558,110 @@ describe("useSystemUpdate — actions", () => {
 		}
 	});
 
+	test("checking from the success row reaches the pane, not a dead button (#1015)", async () => {
+		// An undismissed run outcome wins over any check in flight, so a press
+		// made while the success banner holds the pane would leave the screen
+		// exactly as it was. The row's control retires the outcome first.
+		const succeeded = {
+			currentVersion: "0.9.4",
+			check: { status: "ok", updateAvailable: false },
+			run: run({ outcome: "succeeded" }),
+		};
+		const { dom } = mountApi(() => succeeded, createElement(SelfUpdatePanel));
+		await settle(dom);
+		assert.match(dom.html(), /Updated to Remit 0\.9\.4/);
+
+		dom.click(dom.byText("button", "Check for updates"));
+		await waitFor(
+			dom,
+			() => /Looking for a newer version/.test(dom.html()),
+			"the pressed check to reach the pane",
+		);
+		assert.doesNotMatch(dom.html(), /Updated to Remit/);
+	});
+
+	test("a check pressed from the success row fails in the open, not behind the banner (#1015)", async () => {
+		const succeeded = {
+			currentVersion: "0.9.4",
+			check: { status: "ok", updateAvailable: false },
+			run: run({ outcome: "succeeded" }),
+		};
+		const { dom } = mountApi(() => succeeded, createElement(SelfUpdatePanel));
+		await settle(dom);
+
+		const control = dom.byText("button", "Check for updates");
+		const realNow = Date.now;
+		try {
+			await act(async () => {
+				// Dispatched inside this `act` rather than through `dom.click`, so
+				// the press is stamped off the real clock and the wait it arms is
+				// measured against one already past the budget.
+				control.dispatchEvent(
+					new MouseEvent("click", { bubbles: true, cancelable: true }),
+				);
+				Date.now = () => realNow() + CHECK_ANSWER_BUDGET_MS + 1_000;
+				await dom.flush();
+			});
+			await dom.wait(5);
+			await dom.flush();
+
+			assert.match(dom.html(), /The updater did not answer/);
+			assert.doesNotMatch(dom.html(), /Updated to Remit/);
+		} finally {
+			Date.now = realNow;
+		}
+	});
+
+	test("dismissing an outcome does not uncover the check verdict it hid", async () => {
+		// The failure belongs to a press made before the run, on a pane the user
+		// has not been able to see since. Serving it as the current verdict claims
+		// a check failed that may well have succeeded.
+		let response: unknown = available;
+		const { dom, api } = mountApi(
+			() => response,
+			createElement(SelfUpdatePanel),
+		);
+		await settle(dom);
+
+		const realNow = Date.now;
+		try {
+			await act(async () => {
+				api().onCheck();
+				Date.now = () => realNow() + CHECK_ANSWER_BUDGET_MS + 1_000;
+				await dom.flush();
+			});
+			await dom.wait(5);
+			await dom.flush();
+			assert.match(dom.html(), /The updater did not answer/);
+		} finally {
+			Date.now = realNow;
+		}
+
+		response = {
+			currentVersion: "0.9.4",
+			check: { status: "ok", updateAvailable: false },
+			run: run({ outcome: "succeeded" }),
+		};
+		await retryConnection(dom, api);
+		await waitFor(
+			dom,
+			() => /Updated to Remit 0\.9\.4/.test(dom.html()),
+			"the finished run to reach the pane",
+		);
+
+		await act(async () => {
+			api().onDismissResult();
+			await dom.flush();
+		});
+		await waitFor(
+			dom,
+			() => !/Updated to Remit/.test(dom.html()),
+			"the outcome to be retired",
+		);
+		assert.doesNotMatch(dom.html(), /The updater did not answer/);
+		assert.match(dom.html(), /0\.9\.4 is the latest version/);
+	});
+
 	test("a refused refresh is shown, never swallowed back into the old verdict (#599)", async () => {
 		let refused = false;
 		const { dom, api } = mountApi(

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

@@ -249,6 +249,12 @@ export function useSystemUpdate(): SelfUpdateApi {
 		if (shownRunIdRef.current !== null)
 			setDismissedRunId(shownRunIdRef.current);
 		setHeld(null);
+		// Retiring the outcome uncovers the check verdict beneath it. A failure
+		// recorded while the outcome held the pane describes a press the user can
+		// no longer see, and an update run of its own supersedes anything an
+		// earlier check concluded — either way it must not resurface here.
+		setCheckPress(null);
+		setCheckFailure(null);
 	}, []);
 
 	return {

package/src/hooks/useDeleteMessages.ts

@@ -16,6 +16,7 @@ import {
 } from "@/components/ui/placement-refusal";
 import { resolveMailboxesForMessages } from "@/hooks/useMarkAsRead";
 import { runChunkedMutation } from "@/lib/bulk-actions";
+import { softErrorStatuses } from "@/lib/error-classifier";
 import {
 	cancelThreadListQueries,
 	invalidateThreadListQueries,
@@ -92,6 +93,10 @@ export const useDeleteMessages = ({
 
 	const { mutateAsync, isPending } = useMutation({
 		...messageBulkOperationsDeleteMessagesMutation(),
+		// A coded 409 is answered here — the prompt, or a banner — so it must not
+		// also take the whole screen. Only 409: a 401, 403 or 5xx on a delete is
+		// still the fatal page's (#1059).
+		meta: softErrorStatuses(409),
 		onMutate: async (variables): Promise<ThreadMutationContext> => {
 			const messageIds = new Set(variables.body.messageIds ?? []);
 

package/src/hooks/useEmptyTrash.ts

@@ -22,6 +22,7 @@ import {
 	type FolderRoleRefusal,
 	isFolderRoleRefusal,
 } from "@/components/ui/folder-role-refusal";
+import { softErrorStatuses } from "@/lib/error-classifier";
 import {
 	invalidateThreadListQueries,
 	threadListCacheKeys,
@@ -109,6 +110,9 @@ export const useEmptyTrash = ({
 
 	const { mutateAsync, isPending } = useMutation({
 		...trashOperationsEmptyTrashMutation(),
+		// The refusal is rendered in the pane, so it must not also take the whole
+		// screen. Only 409 — every other status is still the fatal page's (#1059).
+		meta: softErrorStatuses(409),
 		onMutate: (): EmptyTrashContext => {
 			inFlight.current = scope;
 			return { scope, listMailboxId: listMailboxIdNow() };

package/src/hooks/useMessageBodyContent.ts

@@ -351,6 +351,12 @@ export const useMessageBodyContent = ({
 
 	const isLoading = query.isLoading && !!picked;
 
+	// `picked` is null for two different reasons, and a caller that treats them
+	// alike is wrong about one of them: the message has not arrived yet, or it
+	// arrived carrying nothing renderable. Only the second is a fact about the
+	// message, and only it may be stated to the reader (#1030).
+	const hasNoRenderablePart = bodyParts !== undefined && picked === null;
+
 	useEffect(() => {
 		if (isLoading) {
 			loadStartRef.current = performance.now();
@@ -374,6 +380,7 @@ export const useMessageBodyContent = ({
 		picked,
 		data,
 		isLoading,
+		hasNoRenderablePart,
 		isError: query.isError,
 		error: query.error,
 		refetch: query.refetch,

package/src/lib/api.ts

@@ -1,3 +1,4 @@
+import type { ApiError as ApiErrorWireBody } from "@remit/api-http-client/types.gen.ts";
 import { taggedFetch } from "./network-error";
 
 export class ApiError extends Error {
@@ -11,6 +12,46 @@ export class ApiError extends Error {
 	}
 }
 
+/**
+ * The wire body's coded half, re-checked at runtime. `ApiErrorWireBody` is the
+ * generated flat shape the API sends; `ApiError` is the class every HTTP
+ * failure arrives in, carrying that body at `.body`. Reading `code` off the
+ * class is the bug #1004 is about, so nothing outside this module reaches for
+ * either shape directly.
+ */
+export interface CodedApiErrorBody {
+	code: ApiErrorWireBody["code"];
+	details: Record<string, unknown> | undefined;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+export const codedApiErrorBody = (
+	error: unknown,
+): CodedApiErrorBody | undefined => {
+	const body = error instanceof ApiError ? error.body : error;
+	if (!isRecord(body)) return undefined;
+	const { code, details } = body;
+	if (typeof code !== "string") return undefined;
+	return { code, details: isRecord(details) ? details : undefined };
+};
+
+const failureMessage = (body: unknown, status: number): string => {
+	if (isRecord(body) && body.message !== undefined && body.message !== null) {
+		const message = String(body.message);
+		if (message) return message;
+	}
+	return `Request failed with status ${status}`;
+};
+
+/**
+ * The one place an HTTP failure becomes an `ApiError`, so a test can hand a
+ * consumer the exact value the error interceptor produces.
+ */
+export const wrapHttpFailure = (body: unknown, status: number): ApiError =>
+	new ApiError(failureMessage(body, status), status, body);
+
 interface RequestOptions extends Omit<RequestInit, "body"> {
 	params?: Record<string, string | number | boolean | undefined>;
 	body?: unknown;
@@ -52,11 +93,7 @@ const request = async <T>(
 
 	if (!response.ok) {
 		const errorBody = await response.json().catch(() => undefined);
-		throw new ApiError(
-			errorBody?.message || `Request failed with status ${response.status}`,
-			response.status,
-			errorBody,
-		);
+		throw wrapHttpFailure(errorBody, response.status);
 	}
 
 	if (response.status === 204) {

package/src/lib/client.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { trashOperationsEmptyTrash } from "@remit/api-http-client/sdk.gen.ts";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { ApiError } from "./api";
+import "./client";
+
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	http?.restore();
+	http = undefined;
+});
+
+const answer = (status: number, body: unknown): void => {
+	http = mockFetch(
+		() =>
+			new Response(JSON.stringify(body), {
+				status,
+				headers: { "content-type": "application/json" },
+			}),
+	);
+};
+
+const empty = (): Promise<unknown> =>
+	trashOperationsEmptyTrash({
+		path: { accountId: "acc-1" },
+		throwOnError: true,
+	});
+
+describe("the error interceptor", () => {
+	it("hands the app an ApiError carrying the status and the wire body", async () => {
+		answer(409, {
+			code: "folder_role_unresolved",
+			message: "Nobody has confirmed which folder is this account's Trash",
+			details: { reason: "unconfirmed", role: "Trash", accountId: "acc-1" },
+		});
+
+		const error = await empty().then(
+			() => undefined,
+			(reason: unknown) => reason,
+		);
+
+		assert.ok(error instanceof ApiError);
+		assert.equal(error.status, 409);
+		assert.equal(
+			error.message,
+			"Nobody has confirmed which folder is this account's Trash",
+		);
+		assert.deepEqual(error.body, {
+			code: "folder_role_unresolved",
+			message: "Nobody has confirmed which folder is this account's Trash",
+			details: { reason: "unconfirmed", role: "Trash", accountId: "acc-1" },
+		});
+	});
+
+	it("falls back to the status when the body states no message", async () => {
+		answer(503, {});
+
+		const error = await empty().then(
+			() => undefined,
+			(reason: unknown) => reason,
+		);
+
+		assert.ok(error instanceof ApiError);
+		assert.equal(error.message, "Request failed with status 503");
+	});
+});

package/src/lib/client.ts

@@ -1,6 +1,6 @@
 import { client } from "@remit/api-http-client/client.gen.ts";
 import { getRuntimeConfig } from "../runtime-config";
-import { ApiError } from "./api";
+import { ApiError, wrapHttpFailure } from "./api";
 import { taggedFetch } from "./network-error";
 
 // In production, the config.js apiUrl points at the deployed API Gateway.
@@ -27,13 +27,7 @@ client.interceptors.error.use((error, response) => {
 	if (error instanceof ApiError) return error;
 	if (!response) return error;
 
-	const body = error;
-	const message =
-		body && typeof body === "object" && "message" in body
-			? String((body as { message: unknown }).message)
-			: `Request failed with status ${response.status}`;
-
-	return new ApiError(message, response.status, body);
+	return wrapHttpFailure(error, response.status);
 });
 
 export { client };

package/src/routes/settings/folders.tsx

@@ -31,6 +31,7 @@ import { isMailboxNotSettledRefusal } from "@/components/ui/folder-role-refusal"
 import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
 import { guardFolderDeletion } from "@/lib/delete-folder";
+import { softErrorStatuses } from "@/lib/error-classifier";
 import {
 	buildMailboxRoleMap,
 	CANONICAL_TO_NAV_ROLE,
@@ -57,6 +58,9 @@ function AccountFolders({ account }: { account: RemitImapAccountResponse }) {
 
 	const appointMutation = useMutation({
 		...folderRoleOperationsAppointFolderRoleMutation(),
+		// The pane states a still-settling mailbox inline; see the same meta on
+		// the prompt's own write.
+		meta: softErrorStatuses(409),
 		onSuccess: () => {
 			queryClient.invalidateQueries({
 				queryKey: configOperationsGetConfigQueryKey(),

package/src/test-support/http.ts

@@ -71,8 +71,9 @@ export const mockFetch = (responder: Responder = () => ({})): HttpMock => {
 
 /**
  * A failed request. The status travels in the body as well as on the response:
- * the generated client throws the parsed body, and the app's error classifier
- * reads the status off it.
+ * the generated client throws the parsed body, which the error interceptor
+ * re-wraps as an `ApiError` carrying the response status. Anything read off the
+ * body — a `code`, its `details` — sits at `.body`, never at the top level.
  */
 export const httpError = (status: number, message = "boom"): Response =>
 	new Response(JSON.stringify({ status, message }), {