diff --git a/apps/web/components/github/github-status.test.tsx b/apps/web/components/github/github-status.test.tsx
index ce3bfcac1c..9534ec0401 100644
--- a/apps/web/components/github/github-status.test.tsx
+++ b/apps/web/components/github/github-status.test.tsx
@@ -4,12 +4,24 @@ import { ToastProvider } from "@/components/toast-provider";
import type { GitHubStatus } from "@/lib/types/github";
import { GitHubPersonalSettings } from "./github-status";
-const mocks = vi.hoisted(() => ({ status: null as GitHubStatus | null }));
+const mocks = vi.hoisted(() => ({
+ status: null as GitHubStatus | null,
+ loading: false,
+}));
vi.mock("@/hooks/domains/github/use-github-status", () => ({
- useGitHubStatus: () => ({ status: mocks.status, loaded: true, loading: false, refresh: vi.fn() }),
+ useGitHubStatus: () => ({
+ status: mocks.status,
+ loaded: true,
+ loading: mocks.loading,
+ refresh: vi.fn(),
+ }),
}));
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ mocks.status = null;
+ mocks.loading = false;
+});
function renderPersonal() {
return render(
@@ -61,4 +73,13 @@ describe("GitHubPersonalSettings", () => {
expect(screen.getByRole("button", { name: /Connect identity/ })).toBeTruthy();
expect(screen.getByText(/never given to managed agents/)).toBeTruthy();
});
+
+ it("keeps the current identity visible while refreshing", () => {
+ mocks.status = status("github_app_installation");
+ mocks.loading = true;
+ renderPersonal();
+
+ expect(screen.getByTestId("github-personal-identity")).toBeTruthy();
+ expect(screen.getByText("octocat", { exact: true })).toBeTruthy();
+ });
});
diff --git a/apps/web/components/github/github-status.tsx b/apps/web/components/github/github-status.tsx
index edfc9603db..9d645c9156 100644
--- a/apps/web/components/github/github-status.tsx
+++ b/apps/web/components/github/github-status.tsx
@@ -189,6 +189,7 @@ function AutomationActions({
status,
workspaceId,
busy,
+ refreshing,
onDisconnect,
onRefresh,
taskAccess,
@@ -196,6 +197,7 @@ function AutomationActions({
status: GitHubStatus;
workspaceId: string;
busy: boolean;
+ refreshing: boolean;
onDisconnect: () => void;
onRefresh: () => void;
taskAccess: TaskGitCredentialsState;
@@ -213,10 +215,12 @@ function AutomationActions({
variant="outline"
size="icon"
onClick={onRefresh}
+ disabled={refreshing}
+ aria-busy={refreshing}
className="h-11 w-11 cursor-pointer"
aria-label="Refresh GitHub connection"
>
-
+
{status.automation && (
;
+ if (!loaded || !status) return ;
const activeRegistrationId =
status.app_registration?.id ?? status.automation?.app_registration_id;
const activeApp = appRegistrations.registrations.find((item) => item.id === activeRegistrationId);
@@ -268,6 +272,7 @@ export function GitHubAutomationSettings({ workspaceId }: { workspaceId: string
status={status}
workspaceId={workspaceId}
busy={busy}
+ refreshing={loading}
onDisconnect={disconnect}
onRefresh={refresh}
taskAccess={taskAccess}
@@ -346,10 +351,10 @@ function PersonalIdentityActions({
}
export function GitHubPersonalSettings({ workspaceId }: { workspaceId: string }) {
- const { status, loaded, loading, refresh } = useGitHubStatus(workspaceId);
+ const { status, loaded, refresh } = useGitHubStatus(workspaceId);
const [busy, setBusy] = useState(false);
const { toast } = useToast();
- if (!loaded || loading || !status) return null;
+ if (!loaded || !status) return null;
const view = personalIdentityView(status);
const appAutomation = status.automation?.source === "github_app_installation";
if (!status.automation) return null;
diff --git a/apps/web/e2e/tests/integrations/github-authentication.spec.ts b/apps/web/e2e/tests/integrations/github-authentication.spec.ts
index f899fc992e..14f138a21b 100644
--- a/apps/web/e2e/tests/integrations/github-authentication.spec.ts
+++ b/apps/web/e2e/tests/integrations/github-authentication.spec.ts
@@ -109,6 +109,47 @@ test.describe("GitHub workspace authentication", () => {
});
});
+ test("keeps loaded settings visible during refresh", async ({
+ testPage,
+ apiClient,
+ seedData,
+ }) => {
+ await apiClient.mockGitHubSetWorkspaceConnection(seedData.workspaceId, {
+ source: "pat",
+ status: "active",
+ login: "refresh-user",
+ });
+ let holdStatus = false;
+ let releaseStatus!: () => void;
+ const statusGate = new Promise((resolve) => {
+ releaseStatus = resolve;
+ });
+ await testPage.route("**/api/v1/github/status?*", async (route) => {
+ if (holdStatus) await statusGate;
+ await route.continue();
+ });
+
+ await testPage.goto(settingsPath(seedData.workspaceId));
+ const automation = testPage.getByTestId("github-workspace-automation");
+ await expect(automation.getByText("refresh-user", { exact: true })).toBeVisible({
+ timeout: 15_000,
+ });
+
+ holdStatus = true;
+ const refresh = automation.getByRole("button", { name: "Refresh GitHub connection" });
+ await refresh.click();
+ await expect(automation.getByText("refresh-user", { exact: true })).toBeVisible();
+ await expect(testPage.getByText("Checking GitHub connection...", { exact: true })).toHaveCount(
+ 0,
+ );
+ await expect(refresh).toBeDisabled();
+ await expect(refresh).toHaveAttribute("aria-busy", "true");
+
+ holdStatus = false;
+ releaseStatus();
+ await expect(refresh).toBeEnabled();
+ });
+
test("migrates a legacy connection explicitly and disconnects the replacement", async ({
testPage,
apiClient,
diff --git a/apps/web/e2e/tests/integrations/mobile-github-auth-settings.spec.ts b/apps/web/e2e/tests/integrations/mobile-github-auth-settings.spec.ts
index 297cdd931e..cc6177cd9e 100644
--- a/apps/web/e2e/tests/integrations/mobile-github-auth-settings.spec.ts
+++ b/apps/web/e2e/tests/integrations/mobile-github-auth-settings.spec.ts
@@ -2,6 +2,56 @@ import { test, expect } from "../../fixtures/test-base";
import { GitHubAuthSettingsPage } from "../../pages/github-auth-settings-page";
test.describe("Mobile GitHub authentication settings", () => {
+ test("keeps loaded settings visible during refresh", async ({
+ testPage,
+ apiClient,
+ seedData,
+ }) => {
+ await apiClient.mockGitHubSetWorkspaceConnection(seedData.workspaceId, {
+ source: "pat",
+ status: "active",
+ login: "mobile-refresh-user",
+ });
+ let holdStatus = false;
+ let releaseStatus!: () => void;
+ const statusGate = new Promise((resolve) => {
+ releaseStatus = resolve;
+ });
+ await testPage.route("**/api/v1/github/status?*", async (route) => {
+ if (holdStatus) await statusGate;
+ await route.continue();
+ });
+
+ await testPage.setViewportSize({ width: 390, height: 844 });
+ await testPage.goto(`/settings/workspace/${seedData.workspaceId}/integrations/github`);
+ const automation = testPage.getByTestId("github-workspace-automation");
+ await expect(automation.getByText("mobile-refresh-user", { exact: true })).toBeVisible({
+ timeout: 15_000,
+ });
+
+ holdStatus = true;
+ const refresh = automation.getByRole("button", { name: "Refresh GitHub connection" });
+ await refresh.tap();
+ await expect(automation.getByText("mobile-refresh-user", { exact: true })).toBeVisible();
+ await expect(testPage.getByText("Checking GitHub connection...", { exact: true })).toHaveCount(
+ 0,
+ );
+ await expect(refresh).toBeDisabled();
+ await expect(refresh).toHaveAttribute("aria-busy", "true");
+ const refreshBox = await refresh.boundingBox();
+ expect(refreshBox).not.toBeNull();
+ expect(refreshBox!.height).toBeGreaterThanOrEqual(44);
+
+ const hasHorizontalOverflow = await testPage.evaluate(
+ () => document.documentElement.scrollWidth > document.documentElement.clientWidth,
+ );
+ expect(hasHorizontalOverflow).toBe(false);
+
+ holdStatus = false;
+ releaseStatus();
+ await expect(refresh).toBeEnabled();
+ });
+
test("keeps workspace and personal identity controls usable on a narrow viewport", async ({
testPage,
apiClient,
diff --git a/apps/web/hooks/domains/github/use-github-status.test.tsx b/apps/web/hooks/domains/github/use-github-status.test.tsx
index c19aee7627..68ebc484ec 100644
--- a/apps/web/hooks/domains/github/use-github-status.test.tsx
+++ b/apps/web/hooks/domains/github/use-github-status.test.tsx
@@ -123,6 +123,52 @@ describe("useGitHubStatus workspace scoping", () => {
});
});
+describe("useGitHubStatus refresh behavior", () => {
+ it("keeps the loaded status visible while a manual refresh is pending", async () => {
+ const initial: GitHubStatusResponse = {
+ workspace_id: WORKSPACE_A,
+ authenticated: true,
+ username: "initial",
+ auth_method: "pat",
+ token_configured: true,
+ required_scopes: [],
+ effective_personal_actor: {
+ kind: "human",
+ source: "pat",
+ login: "initial",
+ workspace_id: WORKSPACE_A,
+ },
+ };
+ const refreshed = deferred();
+ fetchGitHubStatusMock.mockResolvedValueOnce(initial).mockReturnValueOnce(refreshed.promise);
+ const wrapper = ({ children }: { children: React.ReactNode }) => (
+ {children}
+ );
+ const { result } = renderHook(() => useGitHubStatus(WORKSPACE_A), { wrapper });
+
+ await waitFor(() => expect(result.current.status?.username).toBe("initial"));
+ await waitFor(() => expect(result.current.loading).toBe(false));
+ act(() => result.current.refresh());
+ await waitFor(() => expect(fetchGitHubStatusMock).toHaveBeenCalledTimes(2));
+
+ expect(result.current.status?.username).toBe("initial");
+ expect(result.current.loading).toBe(true);
+
+ await act(async () => {
+ refreshed.resolve({
+ ...initial,
+ username: "refreshed",
+ effective_personal_actor: {
+ ...initial.effective_personal_actor!,
+ login: "refreshed",
+ },
+ });
+ await refreshed.promise;
+ });
+ await waitFor(() => expect(result.current.status?.username).toBe("refreshed"));
+ });
+});
+
describe("normalizeGitHubStatus for GitHub Apps", () => {
it("uses the personal identity for App-backed workspaces", () => {
const status = normalizeGitHubStatus({
diff --git a/apps/web/hooks/domains/github/use-github-status.ts b/apps/web/hooks/domains/github/use-github-status.ts
index a64a8090f6..1231ecc104 100644
--- a/apps/web/hooks/domains/github/use-github-status.ts
+++ b/apps/web/hooks/domains/github/use-github-status.ts
@@ -82,9 +82,8 @@ export function useGitHubStatus(requestedWorkspaceId?: string | null) {
const refresh = useCallback(() => {
invalidateSystemHealth();
if (!workspaceId) return;
- resetGitHubStatus(workspaceId);
doFetch();
- }, [doFetch, invalidateSystemHealth, resetGitHubStatus, workspaceId]);
+ }, [doFetch, invalidateSystemHealth, workspaceId]);
return {
workspaceId,
diff --git a/docs/plans/github-settings-stable-refresh/plan.md b/docs/plans/github-settings-stable-refresh/plan.md
new file mode 100644
index 0000000000..f966baa44c
--- /dev/null
+++ b/docs/plans/github-settings-stable-refresh/plan.md
@@ -0,0 +1,74 @@
+---
+spec: docs/specs/integrations/github-authentication.md
+created: 2026-07-31
+status: done
+---
+
+# Implementation Plan: Stable GitHub Settings Refresh
+
+## Overview
+
+The GitHub status hook currently clears the workspace cache before every manual refresh, while the
+settings components replace loaded content whenever the shared loading flag is true. Preserve the
+same-workspace snapshot during an in-flight refresh, reserve the full loading placeholder for an
+initial or workspace-changing load, and expose refresh progress on the existing icon control.
+
+## Frontend
+
+### Workspace status state
+
+In `apps/web/hooks/domains/github/use-github-status.ts`, make `refresh` start a versioned fetch
+without resetting the existing workspace entry. Keep the existing initial-load reset path and
+request-version guard so workspace changes cannot render another workspace's status and older
+requests cannot overwrite the newest result.
+
+### GitHub settings status
+
+In `apps/web/components/github/github-status.tsx`, render the initial placeholder only when the
+current workspace has no loaded status. Continue rendering loaded automation and personal identity
+content while `loading` is true. Pass the loading state into the automation actions so the existing
+44px refresh button is disabled, marked busy, and animates its refresh icon until the request
+settles. This is shared presentation behavior across desktop and mobile; no responsive composition,
+scroll ownership, navigation, or touch target changes.
+
+The nearest shipped mobile exemplar is `apps/web/components/branch-refresh-button.tsx`: retain the
+visible 44px icon target and use its disabled/spinning progress treatment. The mobile entry point,
+information hierarchy, primary actions, single page scroll owner, and safe-area behavior remain
+those of the existing GitHub settings page.
+
+## Tests
+
+- **What:** A same-workspace manual refresh retains the loaded status while setting `loading`.
+ **File:** `apps/web/hooks/domains/github/use-github-status.test.tsx`.
+ **How:** Resolve the initial status, gate the refresh promise, and assert the cached actor remains
+ available with `loading: true` before the second response resolves.
+- **What:** Loaded settings remain rendered and the refresh control presents local progress.
+ **File:** `apps/web/components/github/github-status.test.tsx`.
+ **How:** Render the personal identity settings with loaded status plus `loading: true`; assert
+ the current identity remains present instead of returning the initial empty state. The browser
+ regressions cover the automation refresh control's disabled/busy/spinning presentation.
+
+## E2E Tests
+
+- **Scenario:** GIVEN a loaded desktop workspace status, WHEN refresh is held pending, THEN the
+ current identity remains visible and the refresh control is busy without showing the initial
+ placeholder. **File:** `apps/web/e2e/tests/integrations/github-authentication.spec.ts`.
+- **Scenario:** GIVEN the same state on a narrow touch viewport, WHEN refresh is held pending, THEN
+ the same content and 44px refresh target remain in place without horizontal overflow.
+ **File:** `apps/web/e2e/tests/integrations/mobile-github-auth-settings.spec.ts`.
+
+## Implementation Waves And Parallel Candidates
+
+Wave 1 (sequential):
+
+- [x] [task-01-stabilize-refresh](task-01-stabilize-refresh.md) — done
+
+No task is marked parallel-safe; the hook, component, and regression coverage form one small
+vertical slice.
+
+## Risks
+
+- Connection save and disconnect flows also call `refresh`; they must still reconcile to the new
+ server status after the request completes while avoiding an interim blank state.
+- Workspace changes must continue to clear unrelated status rather than carrying stale identity
+ data across workspace boundaries.
diff --git a/docs/plans/github-settings-stable-refresh/task-01-stabilize-refresh.md b/docs/plans/github-settings-stable-refresh/task-01-stabilize-refresh.md
new file mode 100644
index 0000000000..6b3b5fc710
--- /dev/null
+++ b/docs/plans/github-settings-stable-refresh/task-01-stabilize-refresh.md
@@ -0,0 +1,77 @@
+---
+id: "01-stabilize-refresh"
+title: "Stabilize GitHub status refresh"
+status: done
+wave: 1
+depends_on: []
+plan: "plan.md"
+spec: "../../specs/integrations/github-authentication.md"
+---
+
+# Task 01: Stabilize GitHub Status Refresh
+
+## Acceptance
+
+- A manual same-workspace refresh preserves the loaded GitHub status until the newest request
+ resolves; initial loads and workspace switches still show no stale status.
+- The automation and personal identity settings remain mounted during refresh, while the existing
+ refresh button is disabled, busy, and visibly spinning.
+- Desktop and mobile E2E coverage proves the loaded content does not flash away while a refresh
+ response is held pending; the mobile target remains at least 44px and the page has no horizontal
+ overflow.
+
+## Verification
+
+```bash
+cd apps/web && pnpm test -- hooks/domains/github/use-github-status.test.tsx components/github/github-status.test.tsx
+cd apps/web && pnpm e2e:run tests/integrations/github-authentication.spec.ts -- --grep "keeps loaded settings visible during refresh"
+cd apps/web && pnpm e2e:run --no-build tests/integrations/mobile-github-auth-settings.spec.ts -- --project=mobile-chrome --grep "keeps loaded settings visible during refresh"
+```
+
+## Files Likely Touched
+
+- `apps/web/hooks/domains/github/use-github-status.ts`
+- `apps/web/hooks/domains/github/use-github-status.test.tsx`
+- `apps/web/components/github/github-status.tsx`
+- `apps/web/components/github/github-status.test.tsx`
+- `apps/web/e2e/tests/integrations/github-authentication.spec.ts`
+- `apps/web/e2e/tests/integrations/mobile-github-auth-settings.spec.ts`
+
+## Dependencies
+
+None.
+
+## Parallelism
+
+`sequential` — the hook behavior, loading presentation, and E2E assertions share one state contract.
+
+## Inputs
+
+- GitHub authentication spec: `UX And Mobile Contract` and the stable-refresh scenarios.
+- Plan sections: `Workspace status state`, `GitHub settings status`, `Tests`, and `E2E Tests`.
+- Existing same-identity stale-while-refresh pattern in
+ `apps/web/hooks/domains/github/use-pr-feedback.ts`.
+- Existing mobile refresh-control treatment in
+ `apps/web/components/branch-refresh-button.tsx`.
+
+## Risks
+
+- Do not weaken request-version ordering for overlapping refreshes.
+- Do not carry status across workspace IDs.
+- Do not let connection replacement or disconnect keep stale content after the response settles.
+
+## Output Contract
+
+Report the root cause, files changed, RED and GREEN test evidence, exact commands and results,
+remaining blockers or risks, and update this task to `done` plus the linked plan checkbox after all
+targeted checks pass.
+
+## Verification Results
+
+- RED: the new hook and component regressions failed before the production change because refresh
+ cleared the cached status and the personal identity returned `null` while loading.
+- GREEN: `cd apps && pnpm --filter @kandev/web test -- --run hooks/domains/github/use-github-status.test.tsx components/github/github-status.test.tsx` — 2 files, 12 tests passed.
+- Typecheck: `cd apps/web && pnpm run typecheck` — passed.
+- Lint: targeted ESLint over the six changed TypeScript/TSX files — passed with no warnings.
+- E2E desktop: production-build managed runner — 1 Chromium test passed.
+- E2E mobile: production-build managed runner with `mobile-chrome` — 1 test passed.
diff --git a/docs/specs/integrations/github-authentication.md b/docs/specs/integrations/github-authentication.md
index bbdbb272e6..c8f158db99 100644
--- a/docs/specs/integrations/github-authentication.md
+++ b/docs/specs/integrations/github-authentication.md
@@ -457,6 +457,10 @@ registration and never creates a global default.
human identity; the page does not render a redundant identity section or a fake selector.
- The workspace identity and task-access summary lines expose concise help through a tooltip on
hover or keyboard focus and the same explanation in a 44px-target drawer on touch devices.
+- Refreshing an already loaded workspace GitHub status keeps the current identity, task-access
+ summary, and actions visible while the request is in flight. The refresh control alone shows
+ progress and prevents duplicate activation. A workspace whose status has not loaded yet still
+ shows the initial connection-status placeholder and never inherits another workspace's data.
- When rate-limit snapshots are available, the connection status row exposes a **Show GitHub API
limits** icon. Its desktop tooltip and touch drawer show remaining and total API requests,
GraphQL query points, Search requests, and reset timing. Exhausted buckets explain that
@@ -475,6 +479,12 @@ registration and never creates a global default.
## Scenarios
+- **GIVEN** a workspace GitHub status is visible, **WHEN** the user refreshes it and the status
+ request is still pending, **THEN** the existing workspace content remains visible and usable
+ while the refresh control is busy, on both desktop and mobile.
+- **GIVEN** the user navigates to a workspace with no loaded GitHub status, **WHEN** its initial
+ status request is pending, **THEN** the UI shows the connection-status placeholder and no status
+ from the previous workspace.
- **GIVEN** two workspaces, **WHEN** each selects a different App registration and installation,
**THEN** status, tokens, webhooks, repositories, actors, and revocation remain isolated.
- **GIVEN** two workspaces intentionally reuse one registration, **WHEN** each installs it into a