fix: surface permission sync issues requiring user action

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - [EE] Preserved cached repository permissions when OAuth token refresh fails because of a transient code host outage. [#1481](https://github.com/sourcebot-dev/sourcebot/pull/1481)
 - [EE] Classified code host permission sync failures by provider context before clearing cached repository permissions. [#1482](https://github.com/sourcebot-dev/sourcebot/pull/1482)
+- [EE] Added action-required warnings and guided recovery when permission syncing clears cached repository access. [#1484](https://github.com/sourcebot-dev/sourcebot/pull/1484)
 
 ## [5.1.3] - 2026-07-20
 

packages/backend/src/ee/accountPermissionSyncer.test.ts

@@ -1,5 +1,14 @@
-import { describe, expect, test } from 'vitest';
-import { classifyPermissionSyncFailure } from './accountPermissionSyncer.js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    hasEntitlement: vi.fn(),
+}));
+
+vi.mock('../entitlements.js', () => ({
+    hasEntitlement: mocks.hasEntitlement,
+}));
+
+import { AccountPermissionSyncer, classifyPermissionSyncFailure } from './accountPermissionSyncer.js';
 import {
     PermissionSyncUpstreamError,
     type PermissionSyncUpstreamErrorKind,
@@ -22,6 +31,49 @@ const upstreamError = (
     operation: 'list_accessible_repositories',
 });
 
+const createSyncerHarness = (syncError?: Error, permissionCount = 95) => {
+    const account = {
+        id: 'account_1',
+        providerId: 'bitbucket-server',
+        user: { email: 'user@example.com' },
+    };
+    const db = {
+        accountPermissionSyncJob: {
+            update: vi.fn().mockResolvedValue({ account }),
+        },
+        accountToRepoPermission: {
+            deleteMany: vi.fn().mockResolvedValue({ count: permissionCount }),
+        },
+        account: {
+            update: vi.fn().mockResolvedValue(account),
+        },
+        $transaction: vi.fn((queries: Array<Promise<unknown>>) => Promise.all(queries)),
+    };
+    const syncAccountPermissions = syncError
+        ? vi.fn().mockRejectedValue(syncError)
+        : vi.fn().mockResolvedValue(undefined);
+    const syncer = Object.create(AccountPermissionSyncer.prototype) as {
+        db: typeof db;
+        syncAccountPermissions: typeof syncAccountPermissions;
+        runJob(job: { data: { jobId: string } }): Promise<void>;
+        onJobCompleted(job: { data: { jobId: string } }): Promise<void>;
+    };
+    syncer.db = db;
+    syncer.syncAccountPermissions = syncAccountPermissions;
+
+    return {
+        account,
+        db,
+        job: { data: { jobId: 'job_1' } },
+        syncer,
+    };
+};
+
+beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.hasEntitlement.mockResolvedValue(true);
+});
+
 describe('classifyPermissionSyncFailure', () => {
     test('fails closed for invalid_grant', () => {
         expect(classifyPermissionSyncFailure(tokenRefreshError('invalid_grant', 400))).toEqual({
@@ -75,3 +127,79 @@ describe('classifyPermissionSyncFailure', () => {
         });
     });
 });
+
+describe('permission sync issue lifecycle', () => {
+    test('atomically records a reauthentication issue when invalid_grant clears permissions', async () => {
+        const error = tokenRefreshError('invalid_grant', 400);
+        const { db, job, syncer } = createSyncerHarness(error);
+
+        await expect(syncer.runJob(job)).rejects.toBe(error);
+
+        expect(db.accountToRepoPermission.deleteMany).toHaveBeenCalledWith({
+            where: { accountId: 'account_1' },
+        });
+        expect(db.account.update).toHaveBeenCalledWith({
+            where: { id: 'account_1' },
+            data: {
+                permissionSyncIssue: 'REAUTHENTICATION_REQUIRED',
+                permissionSyncIssueAt: expect.any(Date),
+            },
+        });
+        expect(db.$transaction).toHaveBeenCalledOnce();
+    });
+
+    test('records an issue when permissions were already cleared by an earlier attempt', async () => {
+        const error = tokenRefreshError('invalid_grant', 400);
+        const { db, job, syncer } = createSyncerHarness(error, 0);
+
+        await expect(syncer.runJob(job)).rejects.toBe(error);
+
+        expect(db.account.update).toHaveBeenCalledWith(expect.objectContaining({
+            data: expect.objectContaining({
+                permissionSyncIssue: 'REAUTHENTICATION_REQUIRED',
+            }),
+        }));
+        expect(db.$transaction).toHaveBeenCalledOnce();
+    });
+
+    test('records an insufficient-scope issue for scope failures', async () => {
+        const error = upstreamError('insufficient_scope');
+        const { db, job, syncer } = createSyncerHarness(error);
+
+        await expect(syncer.runJob(job)).rejects.toBe(error);
+
+        expect(db.account.update).toHaveBeenCalledWith(expect.objectContaining({
+            data: expect.objectContaining({
+                permissionSyncIssue: 'INSUFFICIENT_SCOPE',
+            }),
+        }));
+    });
+
+    test('does not record an issue or clear permissions for a transient refresh failure', async () => {
+        const error = tokenRefreshError('transient', 500);
+        const { db, job, syncer } = createSyncerHarness(error);
+
+        await expect(syncer.runJob(job)).rejects.toBe(error);
+
+        expect(db.accountToRepoPermission.deleteMany).not.toHaveBeenCalled();
+        expect(db.account.update).not.toHaveBeenCalled();
+        expect(db.$transaction).not.toHaveBeenCalled();
+    });
+
+    test('clears the action-required issue after a successful permission sync', async () => {
+        const { db, job, syncer } = createSyncerHarness();
+
+        await syncer.onJobCompleted(job);
+
+        expect(db.accountPermissionSyncJob.update).toHaveBeenCalledWith(expect.objectContaining({
+            data: expect.objectContaining({
+                account: {
+                    update: expect.objectContaining({
+                        permissionSyncIssue: null,
+                        permissionSyncIssueAt: null,
+                    }),
+                },
+            }),
+        }));
+    });
+});

packages/backend/src/ee/accountPermissionSyncer.ts

@@ -1,5 +1,11 @@
 import * as Sentry from "@sentry/node";
-import { PrismaClient, AccountPermissionSyncJobStatus, Account, PermissionSyncSource} from "@sourcebot/db";
+import {
+    PrismaClient,
+    AccountPermissionSyncIssue,
+    AccountPermissionSyncJobStatus,
+    Account,
+    PermissionSyncSource,
+} from "@sourcebot/db";
 import { env, createLogger, getIdentityProviderConfig, PERMISSION_SYNC_SUPPORTED_IDENTITY_PROVIDERS } from "@sourcebot/shared";
 import { hasEntitlement } from "../entitlements.js";
 import { ensureFreshAccountToken, TokenRefreshError } from "./tokenRefresh.js";
@@ -46,10 +52,22 @@ export type PermissionCleanupDecision =
         action: 'preserve_permissions';
     };
 
-const PERMISSION_CLEANUP_REASON_MESSAGES: Record<PermissionCleanupReason, string> = {
-    oauth_invalid_grant: 'OAuth invalid_grant',
-    upstream_credential_rejected: 'upstream credential rejection',
-    upstream_insufficient_scope: 'insufficient OAuth scope',
+const PERMISSION_CLEANUP_DETAILS: Record<PermissionCleanupReason, {
+    message: string;
+    issue: AccountPermissionSyncIssue;
+}> = {
+    oauth_invalid_grant: {
+        message: 'OAuth invalid_grant',
+        issue: AccountPermissionSyncIssue.REAUTHENTICATION_REQUIRED,
+    },
+    upstream_credential_rejected: {
+        message: 'upstream credential rejection',
+        issue: AccountPermissionSyncIssue.REAUTHENTICATION_REQUIRED,
+    },
+    upstream_insufficient_scope: {
+        message: 'insufficient OAuth scope',
+        issue: AccountPermissionSyncIssue.INSUFFICIENT_SCOPE,
+    },
 };
 
 export const classifyPermissionSyncFailure = (error: unknown): PermissionCleanupDecision => {
@@ -238,12 +256,21 @@ export class AccountPermissionSyncer {
             const cleanupDecision = classifyPermissionSyncFailure(error);
 
             if (cleanupDecision.action === 'clear_permissions') {
-                const { count } = await this.db.accountToRepoPermission.deleteMany({
-                    where: { accountId: account.id },
-                });
+                const details = PERMISSION_CLEANUP_DETAILS[cleanupDecision.reason];
+                const [{ count }] = await this.db.$transaction([
+                    this.db.accountToRepoPermission.deleteMany({
+                        where: { accountId: account.id },
+                    }),
+                    this.db.account.update({
+                        where: { id: account.id },
+                        data: {
+                            permissionSyncIssue: details.issue,
+                            permissionSyncIssueAt: new Date(),
+                        },
+                    }),
+                ]);
                 const message = error instanceof Error ? error.message : String(error);
-                const reason = PERMISSION_CLEANUP_REASON_MESSAGES[cleanupDecision.reason];
-                logger.warn(`Cleared ${count} permission row(s) for account ${account.id} (user ${account.user.email ?? 'unknown'}) — fail-closed cleanup triggered by ${reason}: ${message}`);
+                logger.warn(`Cleared ${count} permission row(s) for account ${account.id} (user ${account.user.email ?? 'unknown'}) — fail-closed cleanup triggered by ${details.message}: ${message}`);
             }
             throw error;
         }
@@ -451,6 +478,8 @@ export class AccountPermissionSyncer {
                 account: {
                     update: {
                         permissionSyncedAt: new Date(),
+                        permissionSyncIssue: null,
+                        permissionSyncIssueAt: null,
                     },
                 },
                 completedAt: new Date(),

packages/db/prisma/migrations/20260722144824_add_account_permission_sync_issue/migration.sql

@@ -0,0 +1,7 @@
+-- CreateEnum
+CREATE TYPE "AccountPermissionSyncIssue" AS ENUM ('REAUTHENTICATION_REQUIRED', 'INSUFFICIENT_SCOPE');
+
+-- AlterTable
+ALTER TABLE "Account"
+ADD COLUMN "permissionSyncIssue" "AccountPermissionSyncIssue",
+ADD COLUMN "permissionSyncIssueAt" TIMESTAMP(3);

packages/db/prisma/schema.prisma

@@ -562,6 +562,11 @@ enum PermissionSyncSource {
   REPO_DRIVEN
 }
 
+enum AccountPermissionSyncIssue {
+  REAUTHENTICATION_REQUIRED
+  INSUFFICIENT_SCOPE
+}
+
 model AccountToRepoPermission {
   createdAt DateTime @default(now())
 
@@ -607,7 +612,12 @@ model Account {
   permissionSyncJobs AccountPermissionSyncJob[]
   permissionSyncedAt DateTime?
 
-  /// Set when an OAuth token refresh fails and the account needs to be re-linked by the user.
+  /// Set when permission syncing fails closed and user action is required.
+  /// Cleared after a subsequent permission sync completes successfully.
+  permissionSyncIssue   AccountPermissionSyncIssue?
+  permissionSyncIssueAt DateTime?
+
+  /// Last OAuth token refresh failure, retained for diagnostics.
   /// Cleared when the user successfully re-authenticates.
   tokenRefreshErrorMessage String?
 

packages/web/src/app/(app)/components/banners/bannerResolver.test.ts

@@ -78,6 +78,7 @@ const makeContext = (overrides: Partial<BannerContext> = {}): BannerContext => (
     offlineLicense: null,
     hasPermissionSyncEntitlement: false,
     hasPendingFirstSync: false,
+    permissionSyncIssues: [],
     dismissals: {},
     today: TODAY,
     now: NOW,
@@ -100,6 +101,22 @@ describe('resolveActiveBanner', () => {
             expect(result?.id).toBe('permissionSync');
         });
 
+        test('shows permission sync banner when an account requires reauthentication', () => {
+            const result = resolveActiveBanner(makeContext({
+                hasPermissionSyncEntitlement: true,
+                permissionSyncIssues: [{
+                    accountId: 'account_1',
+                    providerId: 'bitbucket-server',
+                    providerType: 'bitbucket-server',
+                    reason: 'REAUTHENTICATION_REQUIRED',
+                    occurredAt: NOW.toISOString(),
+                    isSyncing: false,
+                }],
+            }));
+            expect(result?.id).toBe('permissionSync');
+            expect(result?.dismissible).toBe(false);
+        });
+
         test('license expired outranks permission sync', () => {
             const result = resolveActiveBanner(makeContext({
                 license: makeLicense({ status: 'canceled' }),

packages/web/src/app/(app)/components/banners/bannerResolver.tsx

@@ -15,6 +15,7 @@ import { InvoicePastDueBanner } from "./invoicePastDueBanner";
 import { ServicePingFailedBanner } from "./servicePingFailedBanner";
 import { TrialBanner } from "./trialBanner";
 import { UpgradeAvailableBanner } from "./upgradeAvailableBanner";
+import type { PermissionSyncStatusResponse } from "@/app/api/(server)/ee/permissionSyncStatus/api";
 
 // Mirrors the value in `lighthouse: lambda/serviceError.ts` and the gating
 // constant in `packages/shared/src/entitlements.ts`.
@@ -28,6 +29,7 @@ export interface BannerContext {
     offlineLicense: OfflineLicenseMetadata | null;
     hasPermissionSyncEntitlement: boolean;
     hasPendingFirstSync: boolean;
+    permissionSyncIssues: PermissionSyncStatusResponse['issues'];
     dismissals: Partial<Record<BannerId, string>>;
     today: string;
     now: Date;
@@ -155,14 +157,23 @@ function buildCandidates(ctx: BannerContext): BannerDescriptor[] {
         });
     }
 
-    if (ctx.hasPermissionSyncEntitlement && ctx.hasPendingFirstSync) {
+    if (
+        ctx.hasPermissionSyncEntitlement &&
+        (ctx.hasPendingFirstSync || ctx.permissionSyncIssues.length > 0)
+    ) {
         banners.push({
             id: 'permissionSync',
             priority: BannerPriority.PERMISSION_SYNC,
             dismissible: false,
             audience: 'everyone',
             render: (props) => (
-                <PermissionSyncBanner {...props} initialHasPendingFirstSync={true} />
+                <PermissionSyncBanner
+                    {...props}
+                    initialStatus={{
+                        hasPendingFirstSync: ctx.hasPendingFirstSync,
+                        issues: ctx.permissionSyncIssues,
+                    }}
+                />
             ),
         });
     }