@taskforcehq/taskforce 0.3.304 → 0.3.306

package/dist/hooks/sync/transfers.test.js

@@ -0,0 +1,396 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createWorkspaceTransferCoordinator } from './transfers';
+const { runWorkspacePullSyncServiceMock, runWorkspacePushSyncServiceMock } = vi.hoisted(() => ({
+    runWorkspacePullSyncServiceMock: vi.fn(),
+    runWorkspacePushSyncServiceMock: vi.fn()
+}));
+vi.mock('../../sync/syncService', async () => {
+    const actual = await vi.importActual('../../sync/syncService');
+    return {
+        ...actual,
+        runWorkspacePullSyncService: runWorkspacePullSyncServiceMock,
+        runWorkspacePushSyncService: runWorkspacePushSyncServiceMock
+    };
+});
+function ref(current) {
+    return { current };
+}
+function createCoordinator(overrides) {
+    const persistWorkspaceSyncPatchSafely = (overrides?.persistWorkspaceSyncPatchSafely ?? vi.fn());
+    const scheduleWorkspaceSyncRetry = (overrides?.scheduleWorkspaceSyncRetry ?? vi.fn());
+    const reportSyncEvent = vi.fn();
+    const workspacePendingPushReplayRef = ref(null);
+    const coordinator = createWorkspaceTransferCoordinator({
+        cloudAuthConfigured: true,
+        runtimeMode: 'local',
+        workspaceCloudSyncEnabled: true,
+        currentWorkspaceId: 'workspace-local-active',
+        workspaceSyncPhase: 'active',
+        isAuthenticated: true,
+        checkAuthSession: vi.fn(async () => true),
+        resolveCloudAuthUrl: (path) => `https://cloud.example.com${path}`,
+        ensureCloudWorkspaceReadyForSync: vi.fn(async () => ({ success: true })),
+        ensureWorkspaceSyncReady: vi.fn(async () => true),
+        handleSyncAuthFailure: vi.fn(async () => { }),
+        clearWorkspaceRetry: vi.fn(),
+        clearWorkspaceIssue: vi.fn(),
+        isWorkspaceRetryPending: vi.fn(() => false),
+        scheduleWorkspaceSyncRetry,
+        persistWorkspaceSyncPatchSafely,
+        persistWorkspaceSyncPatchBestEffort: vi.fn(async () => { }),
+        persistWorkspaceSyncWatermarksSnapshotBestEffort: vi.fn(() => true),
+        reportSyncEvent,
+        acquireWorkspaceSyncLease: vi.fn(async () => true),
+        releaseWorkspaceSyncLease: vi.fn(),
+        reportWorkspaceWindowContention: vi.fn(),
+        refreshWorkspaceSyncMarkdownDocumentsSnapshot: vi.fn(async () => { }),
+        refreshWorkspaceSyncAiProfilesSnapshot: vi.fn(async () => { }),
+        refreshWorkspaceSyncAssetsSnapshot: vi.fn(async () => { }),
+        refreshWorkspaceSyncDocumentReviewSessionsSnapshot: vi.fn(async () => { }),
+        refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot: vi.fn(async () => { }),
+        refreshLocalWorkspaceTaskCollections: vi.fn(async () => { }),
+        buildWorkspaceSyncPayload: (overrides?.buildWorkspaceSyncPayload ?? vi.fn(() => ({
+            changes: [],
+            currentTaskIds: new Set(),
+            deleteTaskIds: new Set(),
+            currentInitiativeIds: new Set(),
+            currentInitiativeWatermarks: new Map(),
+            currentWorkstreamIds: new Set(),
+            currentWorkstreamWatermarks: new Map(),
+            currentAiProfileIds: new Set(),
+            currentAiProfileWatermarks: new Map(),
+            currentDocumentPaths: new Set(),
+            deleteDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            currentAssetPaths: new Set(),
+            deleteAssetPaths: new Set(),
+            currentAssetWatermarks: new Map(),
+            currentDocumentReviewSessionIds: new Set(),
+            deleteDocumentReviewSessionIds: new Set(),
+            currentDocumentReviewSessionWatermarks: new Map(),
+            currentDocumentReviewCommentIds: new Set(),
+            deleteDocumentReviewCommentIds: new Set(),
+            currentDocumentReviewCommentWatermarks: new Map(),
+            currentAnnotatedAttachmentSessionIds: new Set(),
+            deleteAnnotatedAttachmentSessionIds: new Set(),
+            currentAnnotatedAttachmentSessionWatermarks: new Map(),
+            currentTaskEventWatermarks: new Map(),
+            pushedWatermarks: new Map()
+        }))),
+        buildWorkspaceSyncSignature: vi.fn(() => 'sync-signature'),
+        seedWorkspaceSnapshotPushBaseline: vi.fn(),
+        shouldSuppressAttachBootstrapPush: vi.fn(() => false),
+        recordSuppressedEventIds: vi.fn(),
+        workspaceRepairModeRef: ref(false),
+        workspaceForceFullAiProfilePushRef: ref(false),
+        workspacePushInFlightRef: ref(false),
+        workspacePullInFlightRef: ref(false),
+        workspacePendingPushReplayRef,
+        workspaceLastPushedSignatureRef: ref(''),
+        workspacePendingSignatureRef: ref(''),
+        workspaceLastPushedTaskIdsRef: ref(new Set()),
+        workspaceDeletedTaskIdsRef: ref(new Set()),
+        workspaceDeletedTaskWatermarksRef: ref(new Map()),
+        workspacePullCursorRef: ref('stale-cursor'),
+        workspaceLastPushedWatermarksRef: ref(new Map()),
+        workspaceLastPushedTaskChangeKeysRef: ref(new Map()),
+        workspaceLastPushedInitiativeIdsRef: ref(new Set()),
+        workspaceLastPushedInitiativeWatermarksRef: ref(new Map()),
+        workspaceLastPushedWorkstreamIdsRef: ref(new Set()),
+        workspaceLastPushedWorkstreamWatermarksRef: ref(new Map()),
+        workspaceLastPushedAiProfileIdsRef: ref(new Set()),
+        workspaceLastPushedAiProfileWatermarksRef: ref(new Map()),
+        workspaceLastPushedAiProfileChangeKeysRef: ref(new Map()),
+        workspaceLastPushedDocumentPathsRef: ref(new Set()),
+        workspaceLastPushedDocumentWatermarksRef: ref(new Map()),
+        workspaceLastPushedAssetPathsRef: ref(new Set()),
+        workspaceLastPushedAssetWatermarksRef: ref(new Map()),
+        workspaceLastPushedDocumentReviewSessionIdsRef: ref(new Set()),
+        workspaceLastPushedDocumentReviewSessionWatermarksRef: ref(new Map()),
+        workspaceLastPushedDocumentReviewCommentIdsRef: ref(new Set()),
+        workspaceLastPushedDocumentReviewCommentWatermarksRef: ref(new Map()),
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef: ref(new Set()),
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef: ref(new Map()),
+        workspaceLastPushedTaskEventWatermarksRef: ref(new Map()),
+        workspaceBaselineResetReasonRef: ref(null),
+        workspaceCaptureAttachBootstrapBaselineRef: ref(false),
+        workspaceStartupFullReconcileRanRef: ref(false),
+        workspaceFullReconcileInFlightRef: ref(false),
+        bootstrapLastProgressAtRef: ref(null),
+        realtimeSuppressedEventQueueRef: ref([]),
+        setWorkspaceSyncBusy: vi.fn(),
+        setUserGlobalSyncStatus: vi.fn(),
+        setUserGlobalSyncError: vi.fn(),
+        setWorkspaceLastErrorMessage: vi.fn(),
+        setWorkspaceLastErrorAt: vi.fn(),
+        setWorkspaceLastPullAt: vi.fn(),
+        setWorkspaceLastPushAt: vi.fn(),
+        setWorkspaceSyncPendingChanges: vi.fn(),
+        setTasks: vi.fn(),
+        setArchivedTasks: vi.fn()
+    });
+    return { coordinator, persistWorkspaceSyncPatchSafely, scheduleWorkspaceSyncRetry, reportSyncEvent, workspacePendingPushReplayRef };
+}
+describe('createWorkspaceTransferCoordinator', () => {
+    beforeEach(() => {
+        runWorkspacePullSyncServiceMock.mockReset();
+        runWorkspacePushSyncServiceMock.mockReset();
+    });
+    it('persists a cleared cursor before scheduling an invalid-cursor retry', async () => {
+        runWorkspacePullSyncServiceMock.mockResolvedValueOnce({
+            success: false,
+            kind: 'pull_http',
+            status: 400,
+            errorCode: 'INVALID_SYNC_CURSOR',
+            error: 'Invalid sync cursor.',
+            cursor: 'stale-cursor',
+            pages: 0,
+            appliedChanges: 0,
+            pullRequestMs: 1,
+            applyMs: 0,
+            pulledDeleteTaskIds: new Set(),
+            pulledActiveUpserts: false,
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
+        });
+        const { coordinator, persistWorkspaceSyncPatchSafely, scheduleWorkspaceSyncRetry } = createCoordinator();
+        const result = await coordinator.pullWorkspaceChangesFromCloud();
+        expect(result).toBe(false);
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledWith(expect.objectContaining({
+            cursor: 'stale-cursor'
+        }));
+        expect(persistWorkspaceSyncPatchSafely).toHaveBeenCalledWith({ pullCursor: null });
+        expect(scheduleWorkspaceSyncRetry).toHaveBeenCalledWith(150);
+    });
+    it('reports push payload diagnostics when a push fails', async () => {
+        runWorkspacePushSyncServiceMock.mockResolvedValueOnce({
+            success: false,
+            status: 524,
+            error: '524 unknown',
+            transient: true,
+            requestMs: 125000,
+            changeCount: 3,
+            deleteCount: 0,
+            currentTaskIds: new Set(),
+            deleteTaskIds: new Set(),
+            currentInitiativeIds: new Set(),
+            currentInitiativeWatermarks: new Map(),
+            currentWorkstreamIds: new Set(),
+            currentWorkstreamWatermarks: new Map(),
+            currentAiProfileIds: new Set(),
+            currentAiProfileWatermarks: new Map(),
+            currentDocumentPaths: new Set(),
+            deleteDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            currentAssetPaths: new Set(),
+            deleteAssetPaths: new Set(),
+            currentAssetWatermarks: new Map(),
+            currentDocumentReviewSessionIds: new Set(),
+            deleteDocumentReviewSessionIds: new Set(),
+            currentDocumentReviewSessionWatermarks: new Map(),
+            currentDocumentReviewCommentIds: new Set(),
+            deleteDocumentReviewCommentIds: new Set(),
+            currentDocumentReviewCommentWatermarks: new Map(),
+            currentAnnotatedAttachmentSessionIds: new Set(),
+            deleteAnnotatedAttachmentSessionIds: new Set(),
+            currentAnnotatedAttachmentSessionWatermarks: new Map(),
+            currentTaskEventWatermarks: new Map(),
+            pushedWatermarks: new Map(),
+            emittedEventIds: [],
+            appliedTaskUpserts: []
+        });
+        const payloadDiagnostics = {
+            totalChanges: 3,
+            byOp: { 'document-upsert': 2, 'asset-upsert': 1 },
+            baselineResetReason: 'repair-reset',
+            domains: {
+                tasks: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                initiatives: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                workstreams: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                aiProfiles: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                documents: { mode: 'send-all', reason: 'repair-reset', currentCount: 2, baselineCount: 0, changeCount: 2 },
+                assets: { mode: 'send-all', reason: 'repair-reset', currentCount: 1, baselineCount: 0, changeCount: 1 },
+                documentReviewSessions: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                documentReviewComments: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                annotatedAttachmentSessions: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                taskEvents: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                taxonomy: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 }
+            }
+        };
+        const buildWorkspaceSyncPayload = vi.fn(() => ({
+            changes: [],
+            currentTaskIds: new Set(),
+            deleteTaskIds: new Set(),
+            currentInitiativeIds: new Set(),
+            currentInitiativeWatermarks: new Map(),
+            currentWorkstreamIds: new Set(),
+            currentWorkstreamWatermarks: new Map(),
+            currentAiProfileIds: new Set(),
+            currentAiProfileWatermarks: new Map(),
+            currentDocumentPaths: new Set(),
+            deleteDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            currentAssetPaths: new Set(),
+            deleteAssetPaths: new Set(),
+            currentAssetWatermarks: new Map(),
+            currentDocumentReviewSessionIds: new Set(),
+            deleteDocumentReviewSessionIds: new Set(),
+            currentDocumentReviewSessionWatermarks: new Map(),
+            currentDocumentReviewCommentIds: new Set(),
+            deleteDocumentReviewCommentIds: new Set(),
+            currentDocumentReviewCommentWatermarks: new Map(),
+            currentAnnotatedAttachmentSessionIds: new Set(),
+            deleteAnnotatedAttachmentSessionIds: new Set(),
+            currentAnnotatedAttachmentSessionWatermarks: new Map(),
+            currentTaskEventWatermarks: new Map(),
+            pushedWatermarks: new Map(),
+            deltaDiagnostics: payloadDiagnostics
+        }));
+        const { coordinator, reportSyncEvent } = createCoordinator({ buildWorkspaceSyncPayload });
+        await coordinator.pushWorkspaceChangesToCloud('signature-1');
+        expect(buildWorkspaceSyncPayload).toHaveBeenCalled();
+        expect(reportSyncEvent).toHaveBeenCalledWith('workspace-local-active', expect.objectContaining({
+            eventType: 'push',
+            status: 'error',
+            details: expect.objectContaining({
+                payloadDiagnostics
+            })
+        }));
+    });
+    it('replays the same payload after a transient push failure before rebuilding a fresh one', async () => {
+        const firstPayload = {
+            changes: [],
+            currentTaskIds: new Set(),
+            deleteTaskIds: new Set(),
+            currentInitiativeIds: new Set(),
+            currentInitiativeWatermarks: new Map(),
+            currentWorkstreamIds: new Set(),
+            currentWorkstreamWatermarks: new Map(),
+            currentAiProfileIds: new Set(),
+            currentAiProfileWatermarks: new Map(),
+            currentDocumentPaths: new Set(),
+            deleteDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            currentAssetPaths: new Set(),
+            deleteAssetPaths: new Set(),
+            currentAssetWatermarks: new Map(),
+            currentDocumentReviewSessionIds: new Set(),
+            deleteDocumentReviewSessionIds: new Set(),
+            currentDocumentReviewSessionWatermarks: new Map(),
+            currentDocumentReviewCommentIds: new Set(),
+            deleteDocumentReviewCommentIds: new Set(),
+            currentDocumentReviewCommentWatermarks: new Map(),
+            currentAnnotatedAttachmentSessionIds: new Set(),
+            deleteAnnotatedAttachmentSessionIds: new Set(),
+            currentAnnotatedAttachmentSessionWatermarks: new Map(),
+            currentTaskEventWatermarks: new Map(),
+            pushedWatermarks: new Map()
+        };
+        const secondPayload = {
+            ...firstPayload,
+            deltaDiagnostics: {
+                totalChanges: 9,
+                byOp: { 'task-upsert': 9 },
+                baselineResetReason: 'missing-baseline',
+                domains: {
+                    tasks: { mode: 'delta', reason: null, currentCount: 9, baselineCount: 8, changeCount: 1 },
+                    initiatives: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    workstreams: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    aiProfiles: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    documents: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    assets: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    documentReviewSessions: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    documentReviewComments: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    annotatedAttachmentSessions: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    taskEvents: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 },
+                    taxonomy: { mode: 'none', reason: null, currentCount: 0, baselineCount: 0, changeCount: 0 }
+                }
+            }
+        };
+        const buildWorkspaceSyncPayload = vi.fn()
+            .mockReturnValueOnce(firstPayload)
+            .mockReturnValueOnce(secondPayload);
+        runWorkspacePushSyncServiceMock
+            .mockResolvedValueOnce({
+            success: false,
+            status: 524,
+            error: '524 unknown',
+            transient: true,
+            requestMs: 125000,
+            changeCount: 1,
+            deleteCount: 0,
+            currentTaskIds: new Set(),
+            deleteTaskIds: new Set(),
+            currentInitiativeIds: new Set(),
+            currentInitiativeWatermarks: new Map(),
+            currentWorkstreamIds: new Set(),
+            currentWorkstreamWatermarks: new Map(),
+            currentAiProfileIds: new Set(),
+            currentAiProfileWatermarks: new Map(),
+            currentDocumentPaths: new Set(),
+            deleteDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            currentAssetPaths: new Set(),
+            deleteAssetPaths: new Set(),
+            currentAssetWatermarks: new Map(),
+            currentDocumentReviewSessionIds: new Set(),
+            deleteDocumentReviewSessionIds: new Set(),
+            currentDocumentReviewSessionWatermarks: new Map(),
+            currentDocumentReviewCommentIds: new Set(),
+            deleteDocumentReviewCommentIds: new Set(),
+            currentDocumentReviewCommentWatermarks: new Map(),
+            currentAnnotatedAttachmentSessionIds: new Set(),
+            deleteAnnotatedAttachmentSessionIds: new Set(),
+            currentAnnotatedAttachmentSessionWatermarks: new Map(),
+            currentTaskEventWatermarks: new Map(),
+            pushedWatermarks: new Map(),
+            emittedEventIds: [],
+            appliedTaskUpserts: []
+        })
+            .mockResolvedValueOnce({
+            success: true,
+            syncedAt: '2026-04-21T12:00:00.000Z',
+            requestMs: 200,
+            changeCount: 1,
+            deleteCount: 0,
+            currentTaskIds: new Set(['task-1']),
+            deleteTaskIds: new Set(),
+            currentInitiativeIds: new Set(),
+            currentInitiativeWatermarks: new Map(),
+            currentWorkstreamIds: new Set(),
+            currentWorkstreamWatermarks: new Map(),
+            currentAiProfileIds: new Set(),
+            currentAiProfileWatermarks: new Map(),
+            currentDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            currentAssetPaths: new Set(),
+            currentAssetWatermarks: new Map(),
+            currentDocumentReviewSessionIds: new Set(),
+            currentDocumentReviewSessionWatermarks: new Map(),
+            currentDocumentReviewCommentIds: new Set(),
+            currentDocumentReviewCommentWatermarks: new Map(),
+            currentAnnotatedAttachmentSessionIds: new Set(),
+            currentAnnotatedAttachmentSessionWatermarks: new Map(),
+            currentTaskEventWatermarks: new Map(),
+            pushedWatermarks: new Map([['task-1', '2026-04-21T12:00:00.000Z']]),
+            emittedEventIds: [],
+            appliedTaskUpserts: []
+        });
+        const { coordinator, workspacePendingPushReplayRef, reportSyncEvent } = createCoordinator({ buildWorkspaceSyncPayload });
+        const firstResult = await coordinator.pushWorkspaceChangesToCloud('signature-1');
+        const secondResult = await coordinator.pushWorkspaceChangesToCloud('signature-1');
+        expect(firstResult).toBe(false);
+        expect(secondResult).toBe(true);
+        expect(buildWorkspaceSyncPayload).toHaveBeenCalledTimes(1);
+        expect(runWorkspacePushSyncServiceMock.mock.calls[0]?.[0]?.payload).toBe(firstPayload);
+        expect(runWorkspacePushSyncServiceMock.mock.calls[1]?.[0]?.payload).toBe(firstPayload);
+        expect(workspacePendingPushReplayRef.current).toBeNull();
+        expect(reportSyncEvent).toHaveBeenLastCalledWith('workspace-local-active', expect.objectContaining({
+            eventType: 'push',
+            status: 'success',
+            details: expect.objectContaining({
+                replayedPayload: true
+            })
+        }));
+    });
+});

package/dist/hooks/sync/useRecentSyncEvents.d.ts

@@ -0,0 +1,21 @@
+import { type SyncEventRecord } from '../../utils/syncEventPresentation';
+interface UseRecentSyncEventsInput {
+    isOpen: boolean;
+    workspaceId: string;
+    refreshKeys: ReadonlyArray<string | null | undefined>;
+}
+export interface PendingSyncEventsScrollRestore {
+    scrollTop: number;
+    scrollHeight: number;
+}
+interface UseRecentSyncEventsResult {
+    syncRecentEvents: SyncEventRecord[];
+    syncRecentEventsLoading: boolean;
+    syncRecentEventsError: string | null;
+    syncEventsListRef: React.RefObject<HTMLDivElement | null>;
+    loadRecentSyncEvents: () => Promise<SyncEventRecord[]>;
+}
+export declare function useRecentSyncEvents({ isOpen, workspaceId, refreshKeys, }: UseRecentSyncEventsInput): UseRecentSyncEventsResult;
+export declare function capturePendingSyncEventsScrollRestore(listEl: HTMLDivElement | null): PendingSyncEventsScrollRestore | null;
+export declare function restorePendingSyncEventsScrollRestore(listEl: HTMLDivElement | null, pendingRestore: PendingSyncEventsScrollRestore | null): null;
+export {};

package/dist/hooks/sync/useRecentSyncEvents.js

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { areSyncEventListsEqual, mergeRecentSyncEvents, } from '../../utils/syncEventPresentation';
+export function useRecentSyncEvents({ isOpen, workspaceId, refreshKeys, }) {
+    const [syncRecentEvents, setSyncRecentEvents] = useState([]);
+    const [syncRecentEventsLoading, setSyncRecentEventsLoading] = useState(false);
+    const [syncRecentEventsError, setSyncRecentEventsError] = useState(null);
+    const syncEventsListRef = useRef(null);
+    const pendingSyncEventsScrollRestoreRef = useRef(null);
+    useLayoutEffect(() => {
+        pendingSyncEventsScrollRestoreRef.current = restorePendingSyncEventsScrollRestore(syncEventsListRef.current, pendingSyncEventsScrollRestoreRef.current);
+    }, [syncRecentEvents]);
+    const loadRecentSyncEvents = useCallback(async () => {
+        const res = await fetch(`/api/taskforce/sync/events?workspace_id=${encodeURIComponent(workspaceId)}&limit=15`, {
+            method: 'GET',
+            credentials: 'include'
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to load sync events (${res.status})`);
+        }
+        const data = await res.json().catch(() => ({}));
+        return Array.isArray(data?.events)
+            ? data.events.filter((event) => event && typeof event === 'object')
+            : [];
+    }, [workspaceId]);
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        let cancelled = false;
+        const isInitialLoad = syncRecentEvents.length === 0;
+        if (isInitialLoad) {
+            setSyncRecentEventsLoading(true);
+        }
+        void loadRecentSyncEvents()
+            .then((events) => {
+            if (cancelled)
+                return;
+            pendingSyncEventsScrollRestoreRef.current = capturePendingSyncEventsScrollRestore(syncEventsListRef.current);
+            setSyncRecentEvents((current) => {
+                const next = current.length === 0 ? events : mergeRecentSyncEvents(current, events, 15);
+                return areSyncEventListsEqual(current, next) ? current : next;
+            });
+            setSyncRecentEventsError(null);
+        })
+            .catch((error) => {
+            if (cancelled)
+                return;
+            const message = error instanceof Error && error.message.trim().length > 0
+                ? error.message.trim()
+                : 'Unable to load recent sync events.';
+            setSyncRecentEventsError(message);
+            if (isInitialLoad) {
+                setSyncRecentEvents([]);
+            }
+        })
+            .finally(() => {
+            if (cancelled)
+                return;
+            if (isInitialLoad) {
+                setSyncRecentEventsLoading(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        isOpen,
+        loadRecentSyncEvents,
+        ...refreshKeys,
+    ]);
+    return {
+        syncRecentEvents,
+        syncRecentEventsLoading,
+        syncRecentEventsError,
+        syncEventsListRef,
+        loadRecentSyncEvents,
+    };
+}
+export function capturePendingSyncEventsScrollRestore(listEl) {
+    return listEl && listEl.scrollTop > 8
+        ? {
+            scrollTop: listEl.scrollTop,
+            scrollHeight: listEl.scrollHeight
+        }
+        : null;
+}
+export function restorePendingSyncEventsScrollRestore(listEl, pendingRestore) {
+    if (!pendingRestore || !listEl)
+        return null;
+    const delta = listEl.scrollHeight - pendingRestore.scrollHeight;
+    listEl.scrollTop = pendingRestore.scrollTop + Math.max(0, delta);
+    return null;
+}

package/dist/hooks/sync/useRecentSyncEvents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/sync/useRecentSyncEvents.test.js

@@ -0,0 +1,124 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { capturePendingSyncEventsScrollRestore, restorePendingSyncEventsScrollRestore, useRecentSyncEvents, } from './useRecentSyncEvents';
+describe('useRecentSyncEvents', () => {
+    const fetchMock = vi.fn();
+    beforeEach(() => {
+        fetchMock.mockReset();
+        vi.stubGlobal('fetch', fetchMock);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it('does not fetch recent sync events while the modal is closed', () => {
+        renderHook(() => useRecentSyncEvents({
+            isOpen: false,
+            workspaceId: 'workspace-1',
+            refreshKeys: ['a'],
+        }));
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    it('loads recent sync events when the modal opens', async () => {
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: async () => ({
+                events: [{
+                        id: 1,
+                        occurredAt: '2026-04-18T12:00:00.000Z',
+                        eventType: 'pull',
+                        status: 'success',
+                    }],
+            }),
+        });
+        const { result } = renderHook(() => useRecentSyncEvents({
+            isOpen: true,
+            workspaceId: 'workspace-1',
+            refreshKeys: ['2026-04-18T12:00:00.000Z'],
+        }));
+        await waitFor(() => {
+            expect(result.current.syncRecentEventsLoading).toBe(false);
+            expect(result.current.syncRecentEvents).toHaveLength(1);
+        });
+        expect(fetchMock).toHaveBeenCalledWith('/api/taskforce/sync/events?workspace_id=workspace-1&limit=15', expect.objectContaining({
+            method: 'GET',
+            credentials: 'include',
+        }));
+        expect(result.current.syncRecentEventsError).toBeNull();
+    });
+    it('stores a readable error when the fetch fails', async () => {
+        fetchMock.mockResolvedValue({
+            ok: false,
+            status: 503,
+            json: async () => ({}),
+        });
+        const { result } = renderHook(() => useRecentSyncEvents({
+            isOpen: true,
+            workspaceId: 'workspace-1',
+            refreshKeys: ['2026-04-18T12:00:00.000Z'],
+        }));
+        await waitFor(() => {
+            expect(result.current.syncRecentEventsLoading).toBe(false);
+            expect(result.current.syncRecentEventsError).toBe('Failed to load sync events (503)');
+        });
+        expect(result.current.syncRecentEvents).toEqual([]);
+    });
+    it('merges refreshed events into the recent event list', async () => {
+        fetchMock
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                events: [{
+                        id: 1,
+                        occurredAt: '2026-04-18T12:00:00.000Z',
+                        eventType: 'pull',
+                        status: 'success',
+                    }],
+            }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                events: [{
+                        id: 2,
+                        occurredAt: '2026-04-18T12:01:00.000Z',
+                        eventType: 'push',
+                        status: 'success',
+                    }],
+            }),
+        });
+        const { result, rerender } = renderHook(({ refreshKey }) => useRecentSyncEvents({
+            isOpen: true,
+            workspaceId: 'workspace-1',
+            refreshKeys: [refreshKey],
+        }), {
+            initialProps: { refreshKey: 'first' },
+        });
+        await waitFor(() => {
+            expect(result.current.syncRecentEvents).toHaveLength(1);
+        });
+        rerender({ refreshKey: 'second' });
+        await waitFor(() => {
+            expect(result.current.syncRecentEvents).toHaveLength(2);
+        });
+    });
+    it('captures and restores list scroll offset when the event list grows', () => {
+        let scrollHeight = 100;
+        const listEl = document.createElement('div');
+        Object.defineProperty(listEl, 'scrollTop', {
+            value: 24,
+            writable: true,
+        });
+        Object.defineProperty(listEl, 'scrollHeight', {
+            get: () => scrollHeight,
+        });
+        const pendingRestore = capturePendingSyncEventsScrollRestore(listEl);
+        expect(pendingRestore).toEqual({
+            scrollTop: 24,
+            scrollHeight: 100,
+        });
+        scrollHeight = 140;
+        const result = restorePendingSyncEventsScrollRestore(listEl, pendingRestore);
+        expect(result).toBeNull();
+        expect(listEl.scrollTop).toBe(64);
+    });
+});

package/dist/hooks/sync/useSyncStatusActions.d.ts

@@ -0,0 +1,30 @@
+import { type WorkspaceSyncDiagnosticsPresentation } from '../../utils/syncStatusPresentation';
+import type { SyncEventRecord } from '../../utils/syncEventPresentation';
+interface UseSyncStatusActionsInput {
+    currentWorkspaceId: string;
+    syncStatusLabel: string;
+    workspaceSyncSummary: string;
+    workspaceSyncRecommendedAction: string;
+    formattedLastSyncTime: string;
+    formattedLastPullTime: string;
+    formattedLastPushTime: string;
+    workspaceSyncDiagnostics: WorkspaceSyncDiagnosticsPresentation;
+    workspaceSyncPendingChanges: string | number;
+    syncLastError: string;
+    workspaceSyncPhase: string;
+    referenceMismatchCount: number;
+    syncRecentEvents: SyncEventRecord[];
+    loadRecentSyncEvents: () => Promise<SyncEventRecord[]>;
+    pushNotice: (message: string, tone: 'success' | 'error') => void;
+    resetWorkspaceSyncCursorAndPull: () => Promise<void>;
+    workspaceSyncBusy: boolean;
+}
+interface UseSyncStatusActionsResult {
+    workspaceSyncRepairBusy: boolean;
+    workspaceSyncRepairQueued: boolean;
+    workspaceSyncCopied: boolean;
+    handleCopySyncDetails: () => Promise<void>;
+    handleQueueOrRunRepairSync: () => void;
+}
+export declare function useSyncStatusActions({ currentWorkspaceId, syncStatusLabel, workspaceSyncSummary, workspaceSyncRecommendedAction, formattedLastSyncTime, formattedLastPullTime, formattedLastPushTime, workspaceSyncDiagnostics, workspaceSyncPendingChanges, syncLastError, workspaceSyncPhase, referenceMismatchCount, syncRecentEvents, loadRecentSyncEvents, pushNotice, resetWorkspaceSyncCursorAndPull, workspaceSyncBusy, }: UseSyncStatusActionsInput): UseSyncStatusActionsResult;
+export {};