From c464816b48ca553cf2f16dd8b67233ee109f5022 Mon Sep 17 00:00:00 2001
From: "@daniel-lxs" <57051444+daniel-lxs@users.noreply.github.com>
Date: Fri, 16 Oct 2026 05:34:35 +0000
Subject: [PATCH 1/2] fix: recover Users settings reads without discarding
 cached content

---
 .../settings/UsersSettings.client.test.tsx    | 92 +++++++++++++++++--
 .../src/components/settings/UsersSettings.tsx | 30 ++++--
 2 files changed, 109 insertions(+), 13 deletions(-)

diff --git a/apps/web/src/components/settings/UsersSettings.client.test.tsx b/apps/web/src/components/settings/UsersSettings.client.test.tsx
index 2972d11214..cff3bb1970 100644
--- a/apps/web/src/components/settings/UsersSettings.client.test.tsx
+++ b/apps/web/src/components/settings/UsersSettings.client.test.tsx
@@ -71,6 +71,7 @@ function createDeferred<T>() {
 const {
   mockAuthorizedUser,
   mockSettingsState,
+  mockGetSettings,
   mockCreateInvite,
   mockRevokeInvite,
   mockUpdateUserRole,
@@ -104,6 +105,7 @@ const {
       } as LicenseSummary,
     },
   },
+  mockGetSettings: vi.fn(),
   mockCreateInvite: vi.fn(
     async (input: { label?: string; maxUses?: number }) => {
       mockSettingsState.current = {
@@ -195,7 +197,7 @@ vi.mock('@/trpc/client', () => ({
         queryKey: () => ['access-policy'],
         queryOptions: () => ({
           queryKey: ['access-policy'],
-          queryFn: async () => mockSettingsState.current,
+          queryFn: () => mockGetSettings(),
         }),
       },
       accountLinkHelp: {
@@ -266,16 +268,21 @@ function renderUsersSettings() {
     defaultOptions: { queries: { retry: false } },
   });
 
-  return render(
-    <QueryClientProvider client={queryClient}>
-      <UsersSettings />
-    </QueryClientProvider>,
-  );
+  return {
+    queryClient,
+    ...render(
+      <QueryClientProvider client={queryClient}>
+        <UsersSettings />
+      </QueryClientProvider>,
+    ),
+  };
 }
 
 describe('UsersSettings', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mockGetSettings.mockReset();
+    mockGetSettings.mockImplementation(async () => mockSettingsState.current);
     mockClipboardWriteText.mockResolvedValue(undefined);
     mockAuthorizedUser.current = { userId: 'user-1', cloudEnabled: false };
     mockAccountLinkHelpState.current = { helpText: null };
@@ -289,6 +296,79 @@ describe('UsersSettings', () => {
     };
   });
 
+  it('recovers an initial read failure through Retry and prevents duplicate retries', async () => {
+    const retry = createDeferred<typeof mockSettingsState.current>();
+    mockGetSettings.mockRejectedValueOnce(new Error('Read unavailable'));
+    mockGetSettings.mockImplementationOnce(() => retry.promise);
+    renderUsersSettings();
+
+    const button = await screen.findByRole('button', { name: 'Retry' });
+    expect(screen.getByText('Failed to load user settings.')).toBeVisible();
+    fireEvent.click(button);
+    await waitFor(() =>
+      expect(
+        screen.queryByRole('button', { name: 'Retry' }),
+      ).not.toBeInTheDocument(),
+    );
+    fireEvent.click(button);
+    expect(mockGetSettings).toHaveBeenCalledTimes(2);
+
+    await act(async () => retry.resolve(mockSettingsState.current));
+    expect(
+      await screen.findByRole('button', { name: 'Create invite' }),
+    ).toBeEnabled();
+    expect(
+      screen.queryByText('Failed to load user settings.'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('keeps the invite draft and cached settings usable after a background read failure', async () => {
+    const { queryClient } = renderUsersSettings();
+    const label = await screen.findByLabelText(/Label/);
+    fireEvent.change(label, { target: { value: 'Unsaved invite' } });
+    mockGetSettings.mockRejectedValueOnce(new Error('Read unavailable'));
+    await act(async () => {
+      await queryClient.refetchQueries({ queryKey: ['access-policy'] });
+    });
+
+    expect(label).toBeVisible();
+    expect(label).toHaveValue('Unsaved invite');
+    expect(screen.getByRole('button', { name: 'Create invite' })).toBeEnabled();
+    expect(
+      screen.queryByText('Failed to load user settings.'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('recovers the one-time invite link through Retry after post-create refresh fails', async () => {
+    const { queryClient } = renderUsersSettings();
+    await screen.findByRole('button', { name: 'Create invite' });
+    mockGetSettings.mockRejectedValueOnce(new Error('Read unavailable'));
+    fireEvent.click(screen.getByRole('button', { name: 'Create invite' }));
+    await waitFor(() => expect(mockGetSettings).toHaveBeenCalledTimes(2));
+    await waitFor(() => expect(toast.success).toHaveBeenCalled());
+
+    expect(
+      screen.queryByText('Failed to load user settings.'),
+    ).not.toBeInTheDocument();
+    expect(screen.getByText('Failed to refresh user settings.')).toBeVisible();
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
+    expect(
+      await screen.findByText('https://roomote.example.com/invite/new-token'),
+    ).toBeVisible();
+    expect(
+      screen.queryByText('Failed to refresh user settings.'),
+    ).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Create invite' })).toBeEnabled();
+
+    mockGetSettings.mockRejectedValueOnce(new Error('Read unavailable'));
+    await act(async () => {
+      await queryClient.refetchQueries({ queryKey: ['access-policy'] });
+    });
+    expect(
+      screen.getByText('https://roomote.example.com/invite/new-token'),
+    ).toBeVisible();
+  });
+
   it('saves deployment-specific account linking help', async () => {
     renderUsersSettings();
 
diff --git a/apps/web/src/components/settings/UsersSettings.tsx b/apps/web/src/components/settings/UsersSettings.tsx
index 4a0d234027..572bf45bad 100644
--- a/apps/web/src/components/settings/UsersSettings.tsx
+++ b/apps/web/src/components/settings/UsersSettings.tsx
@@ -234,13 +234,28 @@ export function UsersSettings() {
     return <Skeleton className="h-64 w-full" />;
   }
 
-  if (settingsQuery.isError || !settingsQuery.data) {
-    return (
-      <div className="flex items-start gap-2 rounded-lg border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive">
-        <AlertCircle className="mt-0.5 size-4 shrink-0" />
-        <p>Failed to load user settings.</p>
-      </div>
-    );
+  const loadError = (
+    <div className="flex items-center gap-2 rounded-lg border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive">
+      <AlertCircle className="size-4 shrink-0" />
+      <p className="flex-1">
+        {settingsQuery.data
+          ? 'Failed to refresh user settings.'
+          : 'Failed to load user settings.'}
+      </p>
+      <Button
+        type="button"
+        variant="outline"
+        size="sm"
+        disabled={settingsQuery.isFetching}
+        onClick={() => void settingsQuery.refetch()}
+      >
+        Retry
+      </Button>
+    </div>
+  );
+
+  if (!settingsQuery.data) {
+    return loadError;
   }
 
   const {
@@ -327,6 +342,7 @@ export function UsersSettings() {
 
   return (
     <div className="space-y-6">
+      {settingsQuery.isError ? loadError : null}
       {cloudEnabled ? null : (
         <Section icon={ScrollText} title="License">
           <div className="space-y-4">

From 50b773603824ed5919b6305264cda02ca7c9a202 Mon Sep 17 00:00:00 2001
From: "@daniel-lxs" <57051444+daniel-lxs@users.noreply.github.com>
Date: Fri, 16 Oct 2026 06:50:44 +0000
Subject: [PATCH 2/2] fix: recover the independent account linking help read

---
 .../settings/AccountLinkHelpSection.tsx       | 66 ++++++++++++-------
 .../settings/UsersSettings.client.test.tsx    | 66 ++++++++++++++++++-
 2 files changed, 108 insertions(+), 24 deletions(-)

diff --git a/apps/web/src/components/settings/AccountLinkHelpSection.tsx b/apps/web/src/components/settings/AccountLinkHelpSection.tsx
index 4844c82aa9..bf6e904dae 100644
--- a/apps/web/src/components/settings/AccountLinkHelpSection.tsx
+++ b/apps/web/src/components/settings/AccountLinkHelpSection.tsx
@@ -75,6 +75,26 @@ export function AccountLinkHelpSection() {
       </>
     );
 
+  const loadError = (
+    <div className="flex items-center gap-2 rounded-lg border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive">
+      <AlertCircle className="size-4 shrink-0" />
+      <p className="flex-1">
+        {settingsQuery.data
+          ? 'Failed to refresh account linking help.'
+          : 'Failed to load account linking help.'}
+      </p>
+      <Button
+        type="button"
+        variant="outline"
+        size="sm"
+        disabled={settingsQuery.isFetching}
+        onClick={() => void settingsQuery.refetch()}
+      >
+        Retry
+      </Button>
+    </div>
+  );
+
   return (
     <Section icon={LucideLink} title="Account linking help" footer={footer}>
       <p className="text-sm text-muted-foreground">
@@ -84,30 +104,30 @@ export function AccountLinkHelpSection() {
       </p>
       {settingsQuery.isPending ? (
         <Skeleton className="h-24 w-full max-w-2xl" />
-      ) : settingsQuery.isError ? (
-        <div className="flex items-start gap-2 rounded-lg border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive">
-          <AlertCircle className="mt-0.5 size-4 shrink-0" />
-          <p>Failed to load account linking help.</p>
-        </div>
       ) : (
-        <div className="max-w-2xl space-y-2">
-          <Label htmlFor="account-link-help-text" className="sr-only">
-            Account linking help text
-          </Label>
-          <Textarea
-            id="account-link-help-text"
-            value={value}
-            onChange={(event) => setValue(event.target.value)}
-            maxLength={1000}
-            rows={3}
-            placeholder="If you need an invite, ask an admin in Discord: https://discord.gg/..."
-            disabled={updateMutation.isPending}
-          />
-          <p className="text-xs text-muted-foreground">
-            Markdown links are supported. Plain text with a full URL works on
-            every supported surface.
-          </p>
-        </div>
+        <>
+          {settingsQuery.isError ? loadError : null}
+          {settingsQuery.data ? (
+            <div className="max-w-2xl space-y-2">
+              <Label htmlFor="account-link-help-text" className="sr-only">
+                Account linking help text
+              </Label>
+              <Textarea
+                id="account-link-help-text"
+                value={value}
+                onChange={(event) => setValue(event.target.value)}
+                maxLength={1000}
+                rows={3}
+                placeholder="If you need an invite, ask an admin in Discord: https://discord.gg/..."
+                disabled={updateMutation.isPending}
+              />
+              <p className="text-xs text-muted-foreground">
+                Markdown links are supported. Plain text with a full URL works
+                on every supported surface.
+              </p>
+            </div>
+          ) : null}
+        </>
       )}
     </Section>
   );
diff --git a/apps/web/src/components/settings/UsersSettings.client.test.tsx b/apps/web/src/components/settings/UsersSettings.client.test.tsx
index cff3bb1970..3bb149c963 100644
--- a/apps/web/src/components/settings/UsersSettings.client.test.tsx
+++ b/apps/web/src/components/settings/UsersSettings.client.test.tsx
@@ -79,6 +79,7 @@ const {
   mockCreatePasswordResetLink,
   mockSetLicenseKey,
   mockAccountLinkHelpState,
+  mockGetAccountLinkHelp,
   mockSetAccountLinkHelp,
   mockClipboardWriteText,
   mockCapture,
@@ -166,6 +167,7 @@ const {
   mockAccountLinkHelpState: {
     current: { helpText: null as string | null },
   },
+  mockGetAccountLinkHelp: vi.fn(),
   mockSetAccountLinkHelp: vi.fn(async (input: { helpText: string | null }) => {
     mockAccountLinkHelpState.current = { helpText: input.helpText };
     return mockAccountLinkHelpState.current;
@@ -204,7 +206,7 @@ vi.mock('@/trpc/client', () => ({
         queryKey: () => ['account-link-help'],
         queryOptions: () => ({
           queryKey: ['account-link-help'],
-          queryFn: async () => mockAccountLinkHelpState.current,
+          queryFn: () => mockGetAccountLinkHelp(),
         }),
       },
       setAccountLinkHelp: {
@@ -283,6 +285,10 @@ describe('UsersSettings', () => {
     vi.clearAllMocks();
     mockGetSettings.mockReset();
     mockGetSettings.mockImplementation(async () => mockSettingsState.current);
+    mockGetAccountLinkHelp.mockReset();
+    mockGetAccountLinkHelp.mockImplementation(
+      async () => mockAccountLinkHelpState.current,
+    );
     mockClipboardWriteText.mockResolvedValue(undefined);
     mockAuthorizedUser.current = { userId: 'user-1', cloudEnabled: false };
     mockAccountLinkHelpState.current = { helpText: null };
@@ -386,6 +392,64 @@ describe('UsersSettings', () => {
     });
   });
 
+  it('recovers the independent initial account-linking-help read through Retry', async () => {
+    const retry = createDeferred<typeof mockAccountLinkHelpState.current>();
+    mockGetAccountLinkHelp.mockRejectedValueOnce(new Error('Help unavailable'));
+    mockGetAccountLinkHelp.mockImplementationOnce(() => retry.promise);
+    renderUsersSettings();
+
+    const button = await screen.findByRole('button', { name: 'Retry' });
+    expect(
+      screen.getByText('Failed to load account linking help.'),
+    ).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Create invite' })).toBeEnabled();
+    fireEvent.click(button);
+    await waitFor(() =>
+      expect(mockGetAccountLinkHelp).toHaveBeenCalledTimes(2),
+    );
+    expect(
+      screen.queryByLabelText('Account linking help text'),
+    ).not.toBeInTheDocument();
+
+    await act(async () => retry.resolve({ helpText: 'Existing saved help.' }));
+    expect(
+      await screen.findByLabelText('Account linking help text'),
+    ).toHaveValue('Existing saved help.');
+    expect(
+      screen.queryByText('Failed to load account linking help.'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('keeps an account-linking-help draft usable through a failed background read and Retry', async () => {
+    const { queryClient } = renderUsersSettings();
+    const editor = await screen.findByLabelText('Account linking help text');
+    fireEvent.change(editor, { target: { value: 'Draft help to preserve.' } });
+    mockGetAccountLinkHelp.mockRejectedValueOnce(new Error('Help unavailable'));
+    await act(async () => {
+      await queryClient.refetchQueries({ queryKey: ['account-link-help'] });
+    });
+
+    expect(
+      await screen.findByText('Failed to refresh account linking help.'),
+    ).toBeVisible();
+    expect(editor).toBeVisible();
+    expect(editor).toHaveValue('Draft help to preserve.');
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
+    await waitFor(() =>
+      expect(
+        screen.queryByText('Failed to refresh account linking help.'),
+      ).not.toBeInTheDocument(),
+    );
+    expect(editor).toHaveValue('Draft help to preserve.');
+
+    fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+    await waitFor(() =>
+      expect(mockSetAccountLinkHelp.mock.calls[0]?.[0]).toEqual({
+        helpText: 'Draft help to preserve.',
+      }),
+    );
+  });
+
   it('shows org membership rows only for configured org providers', async () => {
     mockSettingsState.current = {
       ...mockSettingsState.current,