@remit/web-client 0.0.106 → 0.0.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.106",
+  "version": "0.0.108",
   "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/DailyBrief.tsx

@@ -42,8 +42,10 @@ import {
 	type FilterSheetProps,
 	type FilterSheetSource,
 	KeyboardHintBar,
+	partitionSpamResults,
 	type SearchResult,
 	SelectionTopBar,
+	SpamResultsOffer,
 	type ThreadRowData,
 	type ThreadSection,
 } from "@remit/ui";
@@ -81,6 +83,7 @@ import type { ListHeaderChrome } from "@/lib/list-header-chrome";
 import { useMailContext } from "@/lib/mail-context";
 import { relatedSearchResults, rowToSearchResult } from "@/lib/search-result";
 import { parseSearchTokens } from "@/lib/search-tokens";
+import { spamOfferForResults } from "@/lib/spam-offer";
 import {
 	type SelectionWizardControl,
 	useSelectionWizard,
@@ -463,6 +466,7 @@ export function DailyBrief({
 	const tokenContext = useSearchTokenContext();
 	const isDesktop = useIsDesktop();
 	const wizard = useSelectionWizard();
+	const navigate = useNavigate();
 
 	const nonMuted = useMemo(
 		() => sortAccountsByCreatedAt(accounts.filter((a) => !a.muted?.value)),
@@ -592,9 +596,33 @@ export function DailyBrief({
 		);
 	}, [threadsData, searchData, selectedAccountId, sq, queryTokens]);
 
+	// The unscoped search reaches every folder, Spam included (see `filteredRows`
+	// above), and the brief is the one global-scope view whose own rows now stand
+	// in for the read-only results panel once the query commits. The panel held
+	// Spam out and offered a way to it instead (`MailListHeader`'s `spamOffer`);
+	// the brief's own body has to do the same, or a committed search surfaces
+	// junk mail inline and drops the way back to it. A bare token query (e.g.
+	// `is:unread`) never reaches the widened endpoint, so there is nothing to
+	// hold out.
+	const { bodyRows, briefSpamOffer } = useMemo(() => {
+		if (!sq) return { bodyRows: filteredRows, briefSpamOffer: undefined };
+		const asResults = filteredRows.map((row) =>
+			rowToSearchResult(row, resultFolderIndex),
+		);
+		const { spam } = partitionSpamResults(asResults);
+		if (spam.length === 0) {
+			return { bodyRows: filteredRows, briefSpamOffer: undefined };
+		}
+		const spamIds = new Set(spam.map((result) => result.id));
+		return {
+			bodyRows: filteredRows.filter((row) => !spamIds.has(row.id)),
+			briefSpamOffer: spamOfferForResults(asResults),
+		};
+	}, [filteredRows, sq, resultFolderIndex]);
+
 	const sections = useMemo<ThreadSection[]>(
-		() => groupBriefSections(filteredRows),
-		[filteredRows],
+		() => groupBriefSections(bodyRows),
+		[bodyRows],
 	);
 
 	const accountSources = useMemo<FilterSheetSource[]>(() => {
@@ -693,10 +721,14 @@ export function DailyBrief({
 	]);
 
 	// The brief is genuinely empty (caught up) only when nothing is narrowing the
-	// view: no account source and no search. When a source/search yields nothing,
-	// the list says so instead, so the narrowing is still visible as the reason.
+	// view: no account source and no search — free text or token. When a
+	// source/search yields nothing, the list says so instead, so the narrowing
+	// is still visible as the reason.
 	const caughtUp =
-		sections.length === 0 && selectedAccountId === "all" && sq.length === 0;
+		sections.length === 0 &&
+		selectedAccountId === "all" &&
+		sq.length === 0 &&
+		queryTokens.length === 0;
 
 	// "Caught up" is a claim about the user's mail, so it may only be made once
 	// the server has confirmed no sync is running (#452). The config snapshot
@@ -752,12 +784,32 @@ export function DailyBrief({
 			briefSkeleton
 		)
 	) : (
-		<BriefListBody
-			sections={sections}
-			briefCategory={selectedCategory}
-			selectedThreadId={selectedMessageId}
-			onSelectThread={onSelectMessage}
-		/>
+		<div className="flex h-full min-h-0 flex-col">
+			{briefSpamOffer && (
+				<SpamResultsOffer
+					count={briefSpamOffer.count}
+					onScopeToSpam={() =>
+						navigate({
+							to: "/mail/$mailboxId",
+							params: { mailboxId: briefSpamOffer.mailboxId },
+							search: {
+								q: searchQuery || undefined,
+								selectedMessageId: undefined,
+								selectedThreadId: undefined,
+							},
+						})
+					}
+				/>
+			)}
+			<div className="min-h-0 flex-1">
+				<BriefListBody
+					sections={sections}
+					briefCategory={selectedCategory}
+					selectedThreadId={selectedMessageId}
+					onSelectThread={onSelectMessage}
+				/>
+			</div>
+		</div>
 	);
 
 	// The cursor and selection wrap the whole pane, not just the list body: the
@@ -785,6 +837,12 @@ export function DailyBrief({
 					relatedResults,
 					relatedLoading,
 					onSelectSearchResult,
+					// The body already narrows to the committed query
+					// (`matchesBriefSearch` + `matchesSearchTokens` + the server `query`,
+					// above), so a committed search is a selectable list here exactly as
+					// it is on the mailbox route (#212) — the two-engine panel stays for
+					// the typing/uncommitted state only.
+					searchResultsInBody: true,
 				}}
 				rows={filteredRows}
 			>

package/src/components/mail/FlaggedList.tsx

@@ -237,6 +237,11 @@ export function FlaggedList({
 			searchResults={searchResults}
 			searchLoading={isLoading}
 			onSelectSearchResult={(result) => onSelectMessage?.(result.id)}
+			// A committed search renders in this view's own rows (`rows` already
+			// narrows to the query above), so the multi-select toolbar stays
+			// reachable exactly as it does on the mailbox route (#212). The
+			// two-engine panel stays for the typing/uncommitted state only.
+			searchResultsInBody
 		>
 			<ThreadListInteraction
 				selectedMessageId={selectedMessageId}

package/src/components/mail/MailListHeader.tsx

@@ -129,13 +129,13 @@ export interface MailListHeaderProps {
 	relatedResultsLabel?: string;
 	/**
 	 * The body renders the committed search itself as a selectable list — the
-	 * mailbox route's `MessageList` filters to the search results and hosts the
-	 * multi-select toolbar and the "Select all N matching" escalation (#212).
-	 * When set, a committed query keeps the body on tablet/desktop instead of
-	 * swapping in the read-only two-engine `SearchResults` panel; the panel still
-	 * shows while the query is being typed (uncommitted). Views whose body is not
-	 * a search-result list (the brief, flagged, global search) leave this unset
-	 * and keep the panel for every query.
+	 * mailbox route's `MessageList` and the brief and Starred's own rows filter
+	 * to the search and host the multi-select toolbar and (on the mailbox route)
+	 * the "Select all N matching" escalation (#212). When set, a committed query
+	 * keeps the body on tablet/desktop instead of swapping in the read-only
+	 * two-engine `SearchResults` panel; the panel still shows while the query is
+	 * being typed (uncommitted). A view whose body is not a search-result list
+	 * leaves this unset and keeps the panel for every query.
 	 */
 	searchResultsInBody?: boolean;
 }
@@ -336,12 +336,12 @@ export function MailListHeader({
 	// It belongs to the search, not to any one way of showing it. The affordance
 	// therefore sits in the pane, above whichever body is up — the read-only
 	// results panel, or a list whose own rows narrow to the committed query — and
-	// is mounted on the same condition as the query itself. Rendering it inside the
-	// results panel made it a mailbox's flash: the panel shows while the query is
-	// being typed and hands back to `MessageList` the moment the query commits to
-	// the URL, taking the affordance down with it a few hundred milliseconds after
-	// it appeared, and leaving the brief (which keeps the panel for any query) as
-	// the only place it survived.
+	// is mounted on the same condition as the query itself. Rendering it inside
+	// the results panel made it a mailbox's flash: the panel shows while the query
+	// is being typed and hands back to `MessageList` the moment the query commits
+	// to the URL, taking the affordance down with it a few hundred milliseconds
+	// after it appeared. Mounting it here instead keeps it up through that
+	// hand-back on every view.
 	const searchHadSemanticReach = related.length > 0;
 	const conversion = useMemo(
 		() => convertSearchToRule(parsed, { searchHadSemanticReach }),
@@ -372,10 +372,11 @@ export function MailListHeader({
 	// Tablet + desktop keep the inline toolbar search; while a query is being
 	// typed the list-pane body swaps to the same sectioned results the phone
 	// takeover shows, under the same FilterSheet. A view whose own body renders
-	// the committed search as a selectable list (`searchResultsInBody`, the
-	// mailbox route) keeps the panel only until the query commits to the URL,
-	// then hands back to its `MessageList` so the multi-select toolbar and the
-	// escalation are reachable (#212). Clearing the query restores the normal list.
+	// the committed search as a selectable list (`searchResultsInBody` — the
+	// mailbox route, the brief, Starred) keeps the panel only until the query
+	// commits to the URL, then hands back to its own rows so multi-select (and,
+	// on the mailbox route, the "Select all N matching" escalation) is reachable
+	// (#212). Clearing the query restores the normal list.
 	const showInlineResults = showInlineSearchResults({
 		tier,
 		hasLiveInput: hasQuery,

package/src/components/mail/MailViewChrome.tsx

@@ -54,7 +54,8 @@ interface MailViewChromeProps {
 	/**
 	 * The body renders the committed search as a selectable list itself; see
 	 * `MailListHeader`. The mailbox route sets this so a committed search yields
-	 * its multi-select `MessageList` (#212); flagged leaves it unset.
+	 * its multi-select `MessageList` (#212); Starred sets it for the same reason,
+	 * over its own already query-narrowed rows.
 	 */
 	searchResultsInBody?: boolean;
 }

package/src/components/mail/SelectionWizardHost.job-status.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+
+/**
+ * A back-apply whose status could not be read is still running on the server
+ * (#526), so the run screen's affordance looks at that job again rather than
+ * queuing a second pass over the same mail.
+ *
+ * The host wires routing, history and several data hooks together, so — as with
+ * this package's other component-level rules (see `SelectionWizardHost.run-exit.test.ts`)
+ * — the wiring is read off the source. What it decides is proven where it can be
+ * run: `./organize-run-state.test.ts` for the ending the screen shows, and
+ * `../../hooks/useOrganizeJob.render.test.ts` for the poll it re-issues.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = readFileSync(resolve(here, "SelectionWizardHost.tsx"), "utf8");
+
+const retryBody = (): string => {
+	const body = source.match(
+		/const retry = \(\): void => \{([\s\S]*?)\n\t\};/,
+	)?.[1];
+	assert.ok(body, "the run screen has no retry");
+	return body;
+};
+
+describe("retrying from an unknown status", () => {
+	it("looks at the job it already has", () => {
+		const body = retryBody();
+		const unknown = body.indexOf('run.state === "statusUnknown"');
+		assert.ok(unknown >= 0, "retry does not recognise an unknown status");
+		assert.match(body.slice(unknown), /organizeJob\.refreshStatus\(\)/);
+	});
+
+	it("decides that before it can reach anything that queues a second job", () => {
+		const body = retryBody();
+		assert.ok(
+			body.indexOf('run.state === "statusUnknown"') < body.indexOf("startJob("),
+			"a second back-apply can be queued over a job that is still running",
+		);
+	});
+
+	it("reads what the job is doing rather than that something failed", () => {
+		assert.doesNotMatch(source, /organizeJob\.isError/);
+		assert.match(source, /organizeRunState\(\{/);
+	});
+});

package/src/components/mail/SelectionWizardHost.tsx

@@ -65,6 +65,7 @@ import {
 import { searchRuleAccountId } from "@/lib/organize/search-to-rule";
 import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
 import { useWizardEntryValue, useWizardStep } from "@/lib/wizard-history";
+import { organizeRunState } from "./organize-run-state";
 
 const EMPTY_DRAFT: WizardDraft = { clauses: [], matchOperator: "any" };
 
@@ -696,29 +697,34 @@ function SelectionWizardSession({
 		sendCommit();
 	}, [blockedReason, current, goToStep, sendCommit]);
 
-	const jobSnapshot = useCallback((): RunSnapshot => {
-		const progress = organizeJob.progress;
-		const shared = {
-			matched: progress.matchedCount,
-			applied: progress.appliedCount,
-			failures: [],
-		};
-		if (organizeJob.isError) {
-			return { ...NOT_STARTED, state: "commitFailed" };
-		}
-		if (organizeJob.isDone) {
+	const jobSnapshot = useCallback(
+		(ruleSaved: boolean): RunSnapshot => {
+			const progress = organizeJob.progress;
+			const state = organizeRunState({
+				failure: organizeJob.failure,
+				isStarting: organizeJob.isStarting,
+				isRunning: organizeJob.isRunning,
+				isDone: organizeJob.isDone,
+				failedCount: progress.failedCount,
+				ruleSaved,
+			});
+			if (
+				state === "saving" ||
+				state === "commitFailed" ||
+				state === "backApplyStartFailed"
+			) {
+				return { ...NOT_STARTED, state };
+			}
 			return {
-				...shared,
-				state:
-					progress.failedCount > 0 ? "backApplyFailed" : "backApplyComplete",
-				failed: progress.failedCount,
+				state,
+				matched: progress.matchedCount,
+				applied: progress.appliedCount,
+				failed: state === "backApplyFailed" ? progress.failedCount : 0,
+				failures: [],
 			};
-		}
-		if (organizeJob.isStarting || organizeJob.isRunning) {
-			return { ...shared, state: "backApplyRunning", failed: 0 };
-		}
-		return NOT_STARTED;
-	}, [organizeJob]);
+		},
+		[organizeJob],
+	);
 
 	// Every row the wizard has seen a description of, so a run that names what it
 	// did not reach can name it rather than listing an id.
@@ -794,21 +800,27 @@ function SelectionWizardSession({
 				return { ...NOT_STARTED, state: "commitFailed" };
 			if (!createFilter.isSuccess) return NOT_STARTED;
 			if (!backApplyDraft) return { ...NOT_STARTED, state: "filterSaved" };
-			if (organizeJob.isError) {
-				return { ...NOT_STARTED, state: "backApplyStartFailed" };
-			}
-			return jobSnapshot();
+			return jobSnapshot(true);
 		}
 		if (committedScope === "all-like-these" && widenedRunsAsJob(verb)) {
-			return jobSnapshot();
+			return jobSnapshot(false);
 		}
 		return bulkSnapshot();
 	};
 
+	const run = runSnapshot();
+
 	// Retry stays on the run screen: it re-sends the same commit rather than
 	// walking back to Review, which would push an entry the wizard does not own
 	// and leave Cancel rewinding to a step instead of out.
 	const retry = (): void => {
+		// A status that could not be read is a job still running on the server, so
+		// the screen looks at that job again rather than queuing a second pass over
+		// the same mail (#526).
+		if (run.state === "statusUnknown") {
+			organizeJob.refreshStatus();
+			return;
+		}
 		// The predicate is re-resolved, not resumed: every verb it carries is
 		// idempotent, so the messages the first pass already reached are a no-op.
 		if (escalated) {
@@ -881,7 +893,6 @@ function SelectionWizardSession({
 		disabled: current !== "run",
 	});
 
-	const run = runSnapshot();
 	const sampleMessages = escalated
 		? escalatedSample.messages
 		: previewed

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

@@ -0,0 +1,97 @@
+/**
+ * A back-apply job reports two things that used to arrive as one error flag: it
+ * never started, or its status could not be read (#526). The run screen is only
+ * allowed to say nothing happened for the first.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	type OrganizeJobReading,
+	organizeRunState,
+} from "./organize-run-state";
+
+const reading = (
+	over: Partial<OrganizeJobReading> = {},
+): OrganizeJobReading => ({
+	failure: undefined,
+	isStarting: false,
+	isRunning: false,
+	isDone: false,
+	failedCount: 0,
+	ruleSaved: false,
+	...over,
+});
+
+describe("organizeRunState", () => {
+	it("keeps a running job running when a status poll could not be read", () => {
+		const state = organizeRunState(
+			reading({
+				isRunning: true,
+				failure: { kind: "statusUnreadable", error: new Error("offline") },
+			}),
+		);
+		assert.equal(state, "statusUnknown");
+		assert.notEqual(state, "commitFailed");
+	});
+
+	it("keeps a finished job finished when a later poll fails", () => {
+		// Polling stops on a terminal state, so the failing read is a window-focus
+		// refetch over a job that already reported its counts.
+		assert.equal(
+			organizeRunState(
+				reading({
+					isDone: true,
+					failure: { kind: "statusUnreadable", error: new Error("offline") },
+				}),
+			),
+			"backApplyComplete",
+		);
+		assert.equal(
+			organizeRunState(
+				reading({
+					isDone: true,
+					failedCount: 3,
+					failure: { kind: "statusUnreadable", error: new Error("offline") },
+				}),
+			),
+			"backApplyFailed",
+		);
+	});
+
+	it("says nothing happened only when the create itself failed", () => {
+		assert.equal(
+			organizeRunState(
+				reading({ failure: { kind: "startFailed", error: new Error("nope") } }),
+			),
+			"commitFailed",
+		);
+	});
+
+	it("leaves a saved rule standing when its pass never started", () => {
+		assert.equal(
+			organizeRunState(
+				reading({
+					ruleSaved: true,
+					failure: { kind: "startFailed", error: new Error("nope") },
+				}),
+			),
+			"backApplyStartFailed",
+		);
+	});
+
+	it("reports a job that is starting or polling cleanly as running", () => {
+		assert.equal(
+			organizeRunState(reading({ isStarting: true })),
+			"backApplyRunning",
+		);
+		assert.equal(
+			organizeRunState(reading({ isRunning: true })),
+			"backApplyRunning",
+		);
+	});
+
+	it("has nothing to report before a commit", () => {
+		assert.equal(organizeRunState(reading()), "saving");
+	});
+});

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

@@ -0,0 +1,39 @@
+import type { RunState } from "@remit/ui";
+import type { OrganizeJobFailure } from "@/hooks/useOrganizeJob";
+
+/** What the run screen knows about a back-apply job it is reporting on. */
+export interface OrganizeJobReading {
+	failure: OrganizeJobFailure | undefined;
+	isStarting: boolean;
+	isRunning: boolean;
+	isDone: boolean;
+	failedCount: number;
+	/**
+	 * The pass belongs to a rule that already saved, so a pass that never started
+	 * leaves the rule standing rather than leaving nothing behind.
+	 */
+	ruleSaved: boolean;
+}
+
+/**
+ * What the run screen says the job is doing. A status that could not be read is
+ * 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.
+ */
+export const organizeRunState = ({
+	failure,
+	isStarting,
+	isRunning,
+	isDone,
+	failedCount,
+	ruleSaved,
+}: OrganizeJobReading): RunState => {
+	if (failure?.kind === "startFailed") {
+		return ruleSaved ? "backApplyStartFailed" : "commitFailed";
+	}
+	if (isDone) return failedCount > 0 ? "backApplyFailed" : "backApplyComplete";
+	if (failure?.kind === "statusUnreadable") return "statusUnknown";
+	if (isStarting || isRunning) return "backApplyRunning";
+	return "saving";
+};

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

@@ -0,0 +1,142 @@
+/**
+ * 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.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { act, createElement } from "react";
+import type { OrganizeDraft } from "../lib/organize/organize-model";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { useOrganizeJob } from "./useOrganizeJob";
+
+/**
+ * A poll that could not be read reaches this screen only as a transport failure:
+ * `shouldEscalate` puts every answered non-2xx on the full-screen fatal page, so
+ * a status that is merely unreadable is a `fetch` that never landed.
+ */
+const dropped = (): never => {
+	throw new TypeError("fetch failed");
+};
+
+const ACCOUNT = "acc-1";
+const JOB = "job-1";
+
+const DRAFT: OrganizeDraft = {
+	matchOperator: "Or",
+	literalClauses: [{ field: "From", value: "noreply@example.com" }],
+	moveMailboxId: "mbx-1",
+};
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+let job: ReturnType<typeof useOrganizeJob> | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	job = undefined;
+});
+
+function Probe() {
+	job = useOrganizeJob(ACCOUNT);
+	return null;
+}
+
+const current = (): ReturnType<typeof useOrganizeJob> => {
+	if (!job) throw new Error("useOrganizeJob is not mounted");
+	return job;
+};
+
+// A request round-trip needs a macrotask, not just a drained microtask queue.
+const settle = async (): Promise<void> => {
+	await harness?.wait(1);
+	await harness?.flush();
+};
+
+/** Start a job the server accepts, then answer every status poll with `status`. */
+const startJob = async (status: () => unknown): Promise<void> => {
+	http = mockFetch((call) => {
+		if (call.method === "POST") {
+			return { organizeJobId: JOB, state: "Pending" };
+		}
+		return status();
+	});
+	harness = createDomHarness();
+	harness.renderApp(createElement(Probe));
+	await act(async () => {
+		current().start(DRAFT);
+	});
+	await settle();
+};
+
+const posts = (): number =>
+	(http?.calls ?? []).filter((call) => call.method === "POST").length;
+
+const statusPolls = (): number => (http?.to(`/organize/${JOB}`) ?? []).length;
+
+describe("useOrganizeJob status reporting", () => {
+	it("reports a status poll it could not read as unreadable, over a job still running", async () => {
+		await startJob(dropped);
+		assert.equal(current().failure?.kind, "statusUnreadable");
+		assert.equal(current().isRunning, true);
+		assert.equal(current().isDone, false);
+	});
+
+	it("reports a create that never returned a job id as a start failure", async () => {
+		http = mockFetch(dropped);
+		harness = createDomHarness();
+		harness.renderApp(createElement(Probe));
+		await act(async () => {
+			current().start(DRAFT);
+		});
+		await settle();
+		assert.equal(current().failure?.kind, "startFailed");
+		assert.equal(current().isRunning, false);
+	});
+
+	it("re-polls the job it already has instead of starting a second one", async () => {
+		let readable = false;
+		await startJob(() =>
+			readable
+				? {
+						organizeJobId: JOB,
+						state: "Running",
+						matchedCount: 1284,
+						appliedCount: 40,
+						failedCount: 0,
+					}
+				: dropped(),
+		);
+		assert.equal(current().failure?.kind, "statusUnreadable");
+		const pollsBefore = statusPolls();
+
+		readable = true;
+		await act(async () => {
+			current().refreshStatus();
+		});
+		await settle();
+
+		assert.equal(posts(), 1);
+		assert.ok(statusPolls() > pollsBefore, "the existing job was polled again");
+		assert.equal(current().failure, undefined);
+		assert.equal(current().progress.matchedCount, 1284);
+	});
+
+	it("stops reporting a job as running once it reaches a terminal state", async () => {
+		await startJob(() => ({
+			organizeJobId: JOB,
+			state: "Complete",
+			matchedCount: 1284,
+			appliedCount: 1284,
+			failedCount: 0,
+		}));
+		assert.equal(current().isDone, true);
+		assert.equal(current().failure, undefined);
+	});
+});

package/src/hooks/useOrganizeJob.ts

@@ -22,6 +22,25 @@ export interface OrganizeJobProgress {
 	errorMessage: string;
 }
 
+/**
+ * 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.
+ */
+export interface OrganizeJobFailure {
+	kind: "startFailed" | "statusUnreadable";
+	error: unknown;
+}
+
+const organizeJobFailure = (
+	createError: unknown,
+	statusError: unknown,
+): OrganizeJobFailure | undefined => {
+	if (createError) return { kind: "startFailed", error: createError };
+	if (statusError) return { kind: "statusUnreadable", error: statusError };
+	return undefined;
+};
+
 /**
  * "All like these" — start a one-time retroactive back-apply (POST /organize)
  * and poll its status to completion (GET /organize/{organizeJobId}). Polling
@@ -66,6 +85,13 @@ export const useOrganizeJob = (accountId: string | undefined) => {
 		[accountId, createJob],
 	);
 
+	const { refetch } = jobQuery;
+	// Looks at the job already in flight again. Distinct from `start`, which
+	// queues a second pass over the same mail.
+	const refreshStatus = useCallback(() => {
+		void refetch();
+	}, [refetch]);
+
 	const job = jobQuery.data;
 	const state = job?.state ?? createMutation.data?.state;
 	const isDone = isTerminalJobState(job?.state);
@@ -80,11 +106,11 @@ export const useOrganizeJob = (accountId: string | undefined) => {
 
 	return {
 		start,
+		refreshStatus,
 		progress,
 		isStarting: createMutation.isPending,
 		isRunning: !!organizeJobId && !isDone,
 		isDone,
-		isError: createMutation.isError || jobQuery.isError,
-		error: createMutation.error ?? jobQuery.error,
+		failure: organizeJobFailure(createMutation.error, jobQuery.error),
 	};
 };

package/src/lib/search-surface.ts

@@ -13,12 +13,12 @@ import type { LayoutTier } from "@/hooks/useLayoutTier";
  * Phone never swaps: it shows the body and keeps the panel in its full-screen
  * takeover instead, so this only decides tablet/desktop.
  *
- * A view whose body renders committed results itself (`bodyRendersCommittedResults`,
- * the mailbox route) keeps the panel only while the query is still being typed —
- * uncommitted, not yet mirrored to the URL — and hands back to the body the moment
- * the query commits, so the committed search is a selectable list. Every other view
- * (the brief, flagged, global search) leaves the flag off and keeps the panel for
- * any query, committed or not.
+ * A view whose body renders committed results itself (`bodyRendersCommittedResults`
+ * — the mailbox route, the brief, Starred) keeps the panel only while the query is
+ * still being typed — uncommitted, not yet mirrored to the URL — and hands back to
+ * the body the moment the query commits, so the committed search is a selectable
+ * list. A view that leaves the flag off keeps the panel for any query, committed
+ * or not.
  */
 export const showInlineSearchResults = (input: {
 	tier: LayoutTier;