@taskforcehq/taskforce 0.3.170 → 0.3.300

package/dist/hooks/useSyncOrchestrator.retry-closure.test.js

@@ -1,6 +1,23 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { act, renderHook, waitFor } from '@testing-library/react';
 import { useSyncOrchestrator } from './useSyncOrchestrator';
+class MockWebSocket {
+    static instances = [];
+    url;
+    constructor(url) {
+        this.url = url;
+        MockWebSocket.instances.push(this);
+    }
+    close() {
+        // noop for orchestration gating tests
+    }
+    addEventListener() {
+        // noop for orchestration gating tests
+    }
+    send() {
+        // noop for orchestration gating tests
+    }
+}
 const { ensureCloudWorkspaceReadyForSyncServiceMock, runWorkspacePullSyncServiceMock, runWorkspacePushSyncServiceMock, syncUserGlobalSettingsServiceMock } = vi.hoisted(() => ({
     ensureCloudWorkspaceReadyForSyncServiceMock: vi.fn(),
     runWorkspacePullSyncServiceMock: vi.fn(),
@@ -23,6 +40,7 @@ function buildInput(overrides) {
         currentWorkspaceId: 'workspace-local-active',
         cloudAuthConfigured: true,
         runtimeMode: 'local',
+        authSessionResolved: true,
         isAuthenticated: true,
         authUserId: 'user-1',
         projectName: 'Test Project',
@@ -31,6 +49,8 @@ function buildInput(overrides) {
         realtimeSyncEnabled: false,
         tasks: [],
         archivedTasks: [],
+        initiatives: [],
+        workstreams: [],
         taxonomies: [],
         setupState: null,
         globalTheme: 'dark',
@@ -47,36 +67,14 @@ function buildInput(overrides) {
         setSetupState: vi.fn(),
         setLocale: vi.fn(),
         setGlobalWeekStartsOn: vi.fn(),
+        fetchPlanningEntities: vi.fn(async () => { }),
         ...overrides
     };
 }
-describe('useSyncOrchestrator retry closure', () => {
+describe('useSyncOrchestrator', () => {
     beforeEach(() => {
         localStorage.clear();
         ensureCloudWorkspaceReadyForSyncServiceMock.mockResolvedValue({ success: true });
-        runWorkspacePullSyncServiceMock.mockResolvedValue({
-            success: false,
-            kind: 'pull_http',
-            status: 503,
-            cursor: null,
-            pages: 0,
-            appliedChanges: 0,
-            pullRequestMs: 1,
-            applyMs: 0,
-            pulledDeleteTaskIds: new Set(),
-            pulledActiveUpserts: false,
-            pulledArchivedUpserts: false
-        });
-        runWorkspacePushSyncServiceMock.mockResolvedValue({
-            success: true,
-            syncedAt: new Date().toISOString(),
-            changeCount: 0,
-            deleteCount: 0,
-            requestMs: 1,
-            currentTaskIds: new Set(),
-            pushedWatermarks: new Map(),
-            deleteTaskIds: new Set()
-        });
         syncUserGlobalSettingsServiceMock.mockResolvedValue({
             success: true,
             mode: 'pulled',
@@ -89,10 +87,13 @@ describe('useSyncOrchestrator retry closure', () => {
                     json: () => Promise.resolve({
                         success: true,
                         state: {
-                            cloudSyncEnabled: true,
-                            sourceOfTruth: 'cloud',
-                            onboardingCompleted: true,
-                            pullCursor: ''
+                            version: 2,
+                            enabled: true,
+                            phase: 'active',
+                            pullCursor: null,
+                            lastPullAt: null,
+                            lastPushAt: null,
+                            lastSyncedAt: null
                         }
                     })
                 });
@@ -103,90 +104,325 @@ describe('useSyncOrchestrator retry closure', () => {
             if (url.includes('/api/taskforce/sync/workspace/documents')) {
                 return Promise.resolve({ ok: true, json: () => Promise.resolve({ documents: [] }) });
             }
+            if (url.includes('/api/taskforce/sync/workspace/annotated-attachments')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ sessions: [] }) });
+            }
             if (url.includes('/api/taskforce/sync/events')) {
                 return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
             }
-            return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+            if (url.includes('/api/taskforce/tasks')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ tasks: [] }) });
+            }
+            if (url.includes('/api/taskforce/archive')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ archived: [] }) });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
         }));
     });
-    afterEach(() => {
+    afterEach(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+        vi.useRealTimers();
         vi.unstubAllGlobals();
         vi.clearAllMocks();
+        MockWebSocket.instances = [];
     });
-    it('uses latest pull callback when delayed retry fires after auth state changes', async () => {
+    it('uses the latest retry callback after auth state changes', async () => {
+        vi.useFakeTimers();
+        runWorkspacePullSyncServiceMock.mockResolvedValue({
+            success: false,
+            kind: 'pull_http',
+            status: 503,
+            transient: true,
+            retryAfterMs: 250,
+            cursor: null,
+            pages: 0,
+            appliedChanges: 0,
+            pullRequestMs: 1,
+            applyMs: 0,
+            pulledDeleteTaskIds: new Set(),
+            pulledActiveUpserts: false,
+            pulledArchivedUpserts: false
+        });
         let input = buildInput();
-        const { result, rerender } = renderHook((props) => useSyncOrchestrator(props), {
+        const { result, rerender, unmount } = renderHook((props) => useSyncOrchestrator(props), {
             initialProps: input
         });
         act(() => {
             result.current.applyWorkspaceSyncStateSnapshot({
-                cloudSyncEnabled: true,
-                sourceOfTruth: 'cloud',
-                onboardingCompleted: true,
-                pullCursor: ''
+                enabled: true,
+                phase: 'active',
+                pullCursor: null
             });
         });
-        await waitFor(() => {
-            expect(result.current.workspaceCloudSyncEnabled).toBe(true);
-        });
         await act(async () => {
             await result.current.pullWorkspaceChangesFromCloud();
         });
-        await waitFor(() => {
-            expect(runWorkspacePullSyncServiceMock.mock.calls.length).toBeGreaterThanOrEqual(1);
-        });
-        await waitFor(() => {
-            expect(result.current.workspaceRetryAt).not.toBeNull();
-        });
+        const pullCallsBeforeRetry = runWorkspacePullSyncServiceMock.mock.calls.length;
+        expect(pullCallsBeforeRetry).toBeGreaterThanOrEqual(1);
+        expect(result.current.workspaceRetryAt).not.toBeNull();
         input = buildInput({
             isAuthenticated: false,
             checkAuthSession: vi.fn(async () => false)
         });
         rerender(input);
         await act(async () => {
-            await new Promise((resolve) => setTimeout(resolve, 250));
+            await vi.runOnlyPendingTimersAsync();
         });
-        expect(runWorkspacePullSyncServiceMock.mock.calls.length).toBeGreaterThanOrEqual(1);
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(pullCallsBeforeRetry);
+        unmount();
     });
-    it('skips pull when another tab holds the workspace lease (non-leader coordination)', async () => {
-        const leaseKey = 'taskforce.sync.pullLease.v1.workspace-local-active';
-        window.localStorage.setItem(leaseKey, JSON.stringify({
-            owner: 'other-tab',
-            acquiredAt: Date.now(),
-            expiresAt: Date.now() + 30_000
+    it('does not enable realtime until auth session is resolved with a non-anonymous user', async () => {
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        const { result, rerender, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput({
+                realtimeSyncEnabled: true,
+                authSessionResolved: false,
+                authUserId: 'anonymous'
+            })
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'active',
+                pullCursor: null
+            });
+        });
+        expect(MockWebSocket.instances).toHaveLength(0);
+        rerender(buildInput({
+            realtimeSyncEnabled: true,
+            authSessionResolved: true,
+            authUserId: 'anonymous'
+        }));
+        expect(MockWebSocket.instances).toHaveLength(0);
+        rerender(buildInput({
+            realtimeSyncEnabled: true,
+            authSessionResolved: true,
+            authUserId: 'user-1'
         }));
-        vi.stubGlobal('navigator', { locks: undefined });
-        const { result } = renderHook((props) => useSyncOrchestrator(props), {
+        await waitFor(() => {
+            expect(MockWebSocket.instances).toHaveLength(1);
+        });
+        expect(MockWebSocket.instances[0]?.url).toBe('wss://api.example.com/taskforce-ws');
+        unmount();
+    });
+    it('retries transient push failures automatically', async () => {
+        runWorkspacePushSyncServiceMock
+            .mockResolvedValueOnce({
+            success: false,
+            status: 503,
+            transient: true,
+            retryAfterMs: 200,
+            requestMs: 1,
+            changeCount: 1,
+            deleteCount: 0,
+            currentTaskIds: new Set(),
+            deleteTaskIds: new Set(),
+            currentDocumentPaths: new Set(),
+            deleteDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            pushedWatermarks: new Map(),
+            emittedEventIds: []
+        })
+            .mockResolvedValueOnce({
+            success: true,
+            syncedAt: '2026-03-15T15:00:00.000Z',
+            requestMs: 1,
+            changeCount: 1,
+            deleteCount: 0,
+            currentTaskIds: new Set(['task-1']),
+            deleteTaskIds: new Set(),
+            currentDocumentPaths: new Set(),
+            deleteDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            pushedWatermarks: new Map([['task-1', '2026-03-14T12:00:00.000Z']]),
+            emittedEventIds: []
+        });
+        const task = {
+            id: 'task-1',
+            status: 'task',
+            title: 'Retry me',
+            createdAt: '2026-03-14T12:00:00.000Z',
+            updatedAt: '2026-03-14T12:00:00.000Z'
+        };
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput({ tasks: [task] })
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'provision-local',
+                pullCursor: null
+            });
+        });
+        expect(result.current.workspaceCloudSyncEnabled).toBe(true);
+        expect(result.current.workspaceSyncPhase).toBe('provision-local');
+        await act(async () => {
+            await result.current.pushWorkspaceChangesToCloud('sig-push-retry');
+        });
+        expect(runWorkspacePushSyncServiceMock).toHaveBeenCalledTimes(1);
+        expect(result.current.isWorkspaceRetryPending()).toBe(true);
+        await act(async () => {
+            await result.current.pushWorkspaceChangesToCloud('sig-push-retry');
+        });
+        await waitFor(() => {
+            expect(runWorkspacePushSyncServiceMock).toHaveBeenCalledTimes(2);
+        });
+        expect(result.current.workspaceSyncPhase).toBe('active');
+        expect(result.current.workspaceLastPushAt).toBe('2026-03-15T15:00:00.000Z');
+        await act(async () => {
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        unmount();
+    });
+    it('keeps the last workspace error visible while a retry attempt is in flight', async () => {
+        let resolveRetryPull = null;
+        runWorkspacePullSyncServiceMock
+            .mockResolvedValueOnce({
+            success: false,
+            kind: 'apply_all_candidates',
+            status: 400,
+            transient: true,
+            hasTransientApplyFailure: true,
+            error: 'Apply failed during bootstrap',
+            failures: ['/api/taskforce/sync/workspace/apply-local:400'],
+            cursor: null,
+            pages: 0,
+            appliedChanges: 0,
+            pullRequestMs: 1,
+            applyMs: 1,
+            pulledDeleteTaskIds: new Set(),
+            pulledActiveUpserts: false,
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
+        })
+            .mockImplementationOnce(() => new Promise((resolve) => {
+            resolveRetryPull = resolve;
+        }));
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
             initialProps: buildInput()
         });
         act(() => {
             result.current.applyWorkspaceSyncStateSnapshot({
-                cloudSyncEnabled: true,
-                sourceOfTruth: 'cloud',
-                onboardingCompleted: true,
-                pullCursor: ''
+                enabled: true,
+                phase: 'attach-cloud',
+                pullCursor: null
             });
         });
+        await waitFor(() => {
+            expect(result.current.workspaceLastErrorMessage).toBe('Apply failed during bootstrap');
+            expect(result.current.isWorkspaceRetryPending()).toBe(true);
+        });
+        act(() => {
+            void result.current.retryWorkspaceCloudSync();
+        });
+        await waitFor(() => {
+            expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(2);
+            expect(result.current.workspaceSyncBusy).toBe(true);
+            expect(result.current.workspaceLastErrorMessage).toBe('Apply failed during bootstrap');
+        });
         await act(async () => {
-            const pulled = await result.current.pullWorkspaceChangesFromCloud();
-            expect(pulled).toBe(false);
+            resolveRetryPull?.({
+                success: true,
+                syncedAt: '2026-03-15T19:30:00.000Z',
+                cursor: null,
+                pages: 1,
+                appliedChanges: 0,
+                pullRequestMs: 1,
+                applyMs: 0,
+                pulledDeleteTaskIds: new Set(),
+                pulledActiveUpserts: false,
+                pulledArchivedUpserts: false,
+                documentDecryptFailures: []
+            });
+        });
+        await waitFor(() => {
+            expect(result.current.workspaceSyncBusy).toBe(false);
+            expect(result.current.workspaceLastPullAt).toBe('2026-03-15T19:30:00.000Z');
         });
-        expect(runWorkspacePullSyncServiceMock).not.toHaveBeenCalled();
+        unmount();
     });
-    it('persists pull cursor/timestamps against the active workspace after workspace switch', async () => {
+    it('finishes provision-local bootstrap by moving to active after the first push', async () => {
+        runWorkspacePushSyncServiceMock.mockResolvedValue({
+            success: true,
+            syncedAt: '2026-03-15T18:00:00.000Z',
+            requestMs: 1,
+            changeCount: 0,
+            deleteCount: 0,
+            currentTaskIds: new Set(),
+            deleteTaskIds: new Set(),
+            currentDocumentPaths: new Set(),
+            deleteDocumentPaths: new Set(),
+            currentDocumentWatermarks: new Map(),
+            pushedWatermarks: new Map(),
+            emittedEventIds: []
+        });
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'provision-local',
+                pullCursor: null
+            });
+        });
+        await waitFor(() => {
+            expect(result.current.workspaceSyncPhase).toBe('provision-local');
+        });
+        await act(async () => {
+            await result.current.pushWorkspaceChangesToCloud('sig-bootstrap');
+        });
+        await waitFor(() => {
+            expect(result.current.workspaceSyncPhase).toBe('active');
+            expect(result.current.workspaceLastPushAt).toBe('2026-03-15T18:00:00.000Z');
+        });
+        await act(async () => {
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        unmount();
+    });
+    it('finishes attach-cloud bootstrap after the first successful pull, including zero-change pulls', async () => {
         runWorkspacePullSyncServiceMock.mockResolvedValue({
             success: true,
-            cursor: 'cursor-next',
+            syncedAt: '2026-03-15T19:00:00.000Z',
+            cursor: null,
             pages: 1,
             appliedChanges: 0,
-            pullRequestMs: 2,
-            applyMs: 1,
-            syncedAt: '2026-02-23T00:00:00.000Z',
+            pullRequestMs: 1,
+            applyMs: 0,
             pulledDeleteTaskIds: new Set(),
             pulledActiveUpserts: false,
-            pulledArchivedUpserts: false
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
+        });
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
         });
-        const uiStatePosts = [];
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'attach-cloud',
+                pullCursor: null
+            });
+        });
+        await waitFor(() => {
+            expect(result.current.workspaceSyncPhase).toBe('active');
+            expect(result.current.workspaceLastPullAt).toBe('2026-03-15T19:00:00.000Z');
+        });
+        unmount();
+    });
+    it('does not auto-push local state immediately after attach-cloud bootstrap completes', async () => {
+        vi.useFakeTimers();
+        const task = {
+            id: 'task-1',
+            status: 'task',
+            title: 'Local stale task',
+            createdAt: '2026-03-14T12:00:00.000Z',
+            updatedAt: '2026-03-14T12:00:00.000Z'
+        };
         vi.stubGlobal('fetch', vi.fn((url, init) => {
             if (url.includes('/api/taskforce/ui-state?key=workspace-sync')) {
                 return Promise.resolve({
@@ -194,75 +430,338 @@ describe('useSyncOrchestrator retry closure', () => {
                     json: () => Promise.resolve({
                         success: true,
                         state: {
-                            cloudSyncEnabled: true,
-                            sourceOfTruth: 'cloud',
-                            onboardingCompleted: true,
-                            pullCursor: ''
+                            version: 2,
+                            enabled: true,
+                            phase: 'attach-cloud',
+                            pullCursor: null,
+                            lastPullAt: null,
+                            lastPushAt: null,
+                            lastSyncedAt: null
                         }
                     })
                 });
             }
             if (url.includes('/api/taskforce/ui-state') && String(init?.method || '').toUpperCase() === 'POST') {
-                const body = JSON.parse(String(init?.body || '{}'));
-                uiStatePosts.push(body);
                 return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
             }
             if (url.includes('/api/taskforce/sync/workspace/documents')) {
                 return Promise.resolve({ ok: true, json: () => Promise.resolve({ documents: [] }) });
             }
+            if (url.includes('/api/taskforce/sync/workspace/annotated-attachments')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ sessions: [] }) });
+            }
             if (url.includes('/api/taskforce/sync/events')) {
                 return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
             }
-            return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+            if (url.includes('/api/taskforce/tasks')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ tasks: [] }) });
+            }
+            if (url.includes('/api/taskforce/archive')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ archived: [] }) });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
         }));
-        let input = buildInput({ currentWorkspaceId: 'workspace-a' });
-        const { result, rerender } = renderHook((props) => useSyncOrchestrator(props), {
-            initialProps: input
+        runWorkspacePullSyncServiceMock.mockResolvedValue({
+            success: true,
+            syncedAt: '2026-03-15T19:00:00.000Z',
+            cursor: null,
+            pages: 1,
+            appliedChanges: 0,
+            pullRequestMs: 1,
+            applyMs: 0,
+            pulledDeleteTaskIds: new Set(),
+            pulledActiveUpserts: false,
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
+        });
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput({ tasks: [task] })
         });
         act(() => {
             result.current.applyWorkspaceSyncStateSnapshot({
-                cloudSyncEnabled: true,
-                sourceOfTruth: 'cloud',
-                onboardingCompleted: true,
-                pullCursor: ''
+                enabled: true,
+                phase: 'attach-cloud',
+                pullCursor: null
             });
         });
         await act(async () => {
-            await result.current.pullWorkspaceChangesFromCloud();
+            await vi.advanceTimersByTimeAsync(2000);
+        });
+        expect(result.current.workspaceSyncPhase).toBe('active');
+        expect(runWorkspacePushSyncServiceMock).not.toHaveBeenCalled();
+        unmount();
+    });
+    it('prevents duplicate local windows from running the same pull concurrently', async () => {
+        let resolveFirstPull = null;
+        runWorkspacePullSyncServiceMock.mockImplementationOnce(() => new Promise((resolve) => {
+            resolveFirstPull = resolve;
+        }));
+        const firstHook = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
+        });
+        const secondHook = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
+        });
+        act(() => {
+            firstHook.result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'active',
+                pullCursor: null
+            });
+        });
+        await waitFor(() => {
+            expect(runWorkspacePullSyncServiceMock.mock.calls.length).toBeGreaterThanOrEqual(1);
+            expect(firstHook.result.current.workspaceSyncBusy).toBe(true);
+        });
+        const callsWhileFirstWindowOwnsLease = runWorkspacePullSyncServiceMock.mock.calls.length;
+        act(() => {
+            secondHook.result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'active',
+                pullCursor: null
+            });
+        });
+        await waitFor(() => {
+            expect(secondHook.result.current.workspaceLastErrorMessage).toMatch(/another local window/i);
+        });
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(callsWhileFirstWindowOwnsLease);
+        await act(async () => {
+            resolveFirstPull?.({
+                success: true,
+                syncedAt: '2026-03-15T20:00:00.000Z',
+                cursor: null,
+                pages: 1,
+                appliedChanges: 0,
+                pullRequestMs: 1,
+                applyMs: 0,
+                pulledDeleteTaskIds: new Set(),
+                pulledActiveUpserts: false,
+                pulledArchivedUpserts: false,
+                documentDecryptFailures: []
+            });
+        });
+        firstHook.unmount();
+        secondHook.unmount();
+    });
+    it('marks stalled bootstrap as error and keeps repair actionable', async () => {
+        vi.useFakeTimers();
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput({
+                isAuthenticated: false,
+                checkAuthSession: vi.fn(async () => false)
+            })
         });
-        input = buildInput({ currentWorkspaceId: 'workspace-b' });
-        rerender(input);
         act(() => {
             result.current.applyWorkspaceSyncStateSnapshot({
-                cloudSyncEnabled: true,
-                sourceOfTruth: 'cloud',
-                onboardingCompleted: true,
-                pullCursor: ''
+                enabled: true,
+                phase: 'attach-cloud',
+                pullCursor: null
             });
         });
         await act(async () => {
-            await result.current.pullWorkspaceChangesFromCloud();
+            await vi.advanceTimersByTimeAsync(130_000);
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(result.current.workspaceSyncPhase).toBe('error');
+        expect(result.current.workspaceLastErrorMessage).toMatch(/stalled/i);
+        expect(result.current.workspaceSyncRecommendedAction).toMatch(/repair/i);
+        unmount();
+    });
+    it('does not mark bootstrap stalled while pull is slow but making progress', async () => {
+        vi.useFakeTimers();
+        runWorkspacePullSyncServiceMock.mockImplementation(async (input) => {
+            input.onPagePulled?.();
+            await new Promise((resolve) => {
+                setTimeout(resolve, 70_000);
+            });
+            input.onChangesApplied?.(200);
+            await new Promise((resolve) => {
+                setTimeout(resolve, 70_000);
+            });
+            return {
+                success: true,
+                syncedAt: '2026-03-15T20:30:00.000Z',
+                cursor: null,
+                pages: 2,
+                appliedChanges: 200,
+                pullRequestMs: 140_000,
+                applyMs: 100,
+                pulledDeleteTaskIds: new Set(),
+                pulledActiveUpserts: true,
+                pulledArchivedUpserts: false,
+                documentDecryptFailures: []
+            };
+        });
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'attach-cloud',
+                pullCursor: null
+            });
+        });
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(130_000);
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(result.current.workspaceSyncPhase).toBe('attach-cloud');
+        expect(result.current.workspaceLastErrorMessage).toBeNull();
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(20_000);
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(result.current.workspaceSyncPhase).toBe('active');
+        expect(result.current.workspaceLastPullAt).toBe('2026-03-15T20:30:00.000Z');
+        unmount();
+    });
+    it('does not mark bootstrap stalled while the first pull page is still in flight without progress callbacks yet', async () => {
+        vi.useFakeTimers();
+        let resolvePull = null;
+        runWorkspacePullSyncServiceMock.mockImplementation(() => new Promise((resolve) => {
+            resolvePull = resolve;
+        }));
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'attach-cloud',
+                pullCursor: null
+            });
+        });
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(130_000);
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(result.current.workspaceSyncPhase).toBe('attach-cloud');
+        expect(result.current.workspaceLastErrorMessage).toBeNull();
+        await act(async () => {
+            resolvePull?.({
+                success: true,
+                syncedAt: '2026-03-15T20:45:00.000Z',
+                cursor: null,
+                pages: 1,
+                appliedChanges: 0,
+                pullRequestMs: 130_000,
+                applyMs: 0,
+                pulledDeleteTaskIds: new Set(),
+                pulledActiveUpserts: false,
+                pulledArchivedUpserts: false,
+                documentDecryptFailures: []
+            });
+            await Promise.resolve();
+            await Promise.resolve();
         });
-        const syncPatchPosts = uiStatePosts.filter((entry) => entry?.stateKey === 'workspace-sync');
-        const workspaceIds = syncPatchPosts.map((entry) => entry?.workspaceId).filter(Boolean);
-        expect(workspaceIds).toContain('workspace-a');
-        expect(workspaceIds).toContain('workspace-b');
+        expect(result.current.workspaceSyncPhase).toBe('active');
+        expect(result.current.workspaceLastPullAt).toBe('2026-03-15T20:45:00.000Z');
+        unmount();
     });
-    it('surfaces document decryption warning and reports structured apply error event', async () => {
+    it('repair resets bootstrap state and retries attach-cloud deterministically', async () => {
         runWorkspacePullSyncServiceMock.mockResolvedValue({
             success: true,
-            cursor: 'cursor-warning',
+            syncedAt: '2026-03-15T21:00:00.000Z',
+            cursor: null,
             pages: 1,
-            appliedChanges: 1,
-            pullRequestMs: 2,
-            applyMs: 1,
-            syncedAt: '2026-02-23T00:00:00.000Z',
+            appliedChanges: 0,
+            pullRequestMs: 1,
+            applyMs: 0,
             pulledDeleteTaskIds: new Set(),
             pulledActiveUpserts: false,
             pulledArchivedUpserts: false,
-            documentDecryptFailures: ['docs/secret.md']
+            documentDecryptFailures: []
         });
-        const syncEventBodies = [];
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'attach-cloud',
+                pullCursor: 'stale-cursor'
+            });
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'error',
+                pullCursor: 'stale-cursor',
+                lastErrorMessage: 'Workspace sync initial cloud pull stalled. Press Repair to restart sync for this workspace.'
+            });
+        });
+        await act(async () => {
+            await result.current.resetWorkspaceSyncCursorAndPull();
+        });
+        expect(runWorkspacePullSyncServiceMock.mock.calls.length).toBeGreaterThanOrEqual(1);
+        expect(runWorkspacePushSyncServiceMock).not.toHaveBeenCalled();
+        expect(result.current.workspacePullCursorRef.current).toBeNull();
+        expect(result.current.workspaceSyncPhase).toBe('active');
+        expect(result.current.workspaceLastPullAt).toBe('2026-03-15T21:00:00.000Z');
+        unmount();
+    });
+    it('blocks same-window push and pull reentry while repair is active', async () => {
+        let resolveRepairPull = null;
+        runWorkspacePullSyncServiceMock.mockImplementationOnce(() => new Promise((resolve) => {
+            resolveRepairPull = resolve;
+        }));
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'attach-cloud',
+                pullCursor: 'stale-cursor'
+            });
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'error',
+                pullCursor: 'stale-cursor',
+                lastErrorMessage: 'Workspace sync initial cloud pull stalled. Press Repair to restart sync for this workspace.'
+            });
+        });
+        let repairPromise = null;
+        await act(async () => {
+            repairPromise = result.current.resetWorkspaceSyncCursorAndPull();
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(1);
+        await act(async () => {
+            const pushed = await result.current.pushWorkspaceChangesToCloud('sig-during-repair');
+            const pulled = await result.current.pullWorkspaceChangesFromCloud();
+            expect(pushed).toBe(false);
+            expect(pulled).toBe(false);
+        });
+        expect(runWorkspacePushSyncServiceMock).not.toHaveBeenCalled();
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(1);
+        await act(async () => {
+            resolveRepairPull?.({
+                success: true,
+                syncedAt: '2026-03-15T21:05:00.000Z',
+                cursor: null,
+                pages: 1,
+                appliedChanges: 0,
+                pullRequestMs: 1,
+                applyMs: 0,
+                pulledDeleteTaskIds: new Set(),
+                pulledActiveUpserts: false,
+                pulledArchivedUpserts: false,
+                documentDecryptFailures: []
+            });
+            await repairPromise;
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(result.current.workspaceSyncPhase).toBe('active');
+        expect(result.current.workspaceLastPullAt).toBe('2026-03-15T21:05:00.000Z');
+        unmount();
+    });
+    it('forces a full ai-profile push during manual retry even when the workspace signature is unchanged', async () => {
         vi.stubGlobal('fetch', vi.fn((url, init) => {
             if (url.includes('/api/taskforce/ui-state?key=workspace-sync')) {
                 return Promise.resolve({
@@ -270,10 +769,13 @@ describe('useSyncOrchestrator retry closure', () => {
                     json: () => Promise.resolve({
                         success: true,
                         state: {
-                            cloudSyncEnabled: true,
-                            sourceOfTruth: 'cloud',
-                            onboardingCompleted: true,
-                            pullCursor: ''
+                            version: 2,
+                            enabled: true,
+                            phase: 'active',
+                            pullCursor: null,
+                            lastPullAt: null,
+                            lastPushAt: null,
+                            lastSyncedAt: null
                         }
                     })
                 });
@@ -281,87 +783,111 @@ describe('useSyncOrchestrator retry closure', () => {
             if (url.includes('/api/taskforce/ui-state') && String(init?.method || '').toUpperCase() === 'POST') {
                 return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
             }
+            if (url.includes('/api/taskforce/sync/workspace/ai-profiles')) {
+                return Promise.resolve({
+                    ok: true,
+                    json: () => Promise.resolve({
+                        aiProfiles: [{
+                                id: 'ai-profile-codex',
+                                workspaceId: 'workspace-local-active',
+                                profileToken: 'token-codex',
+                                name: 'Codex',
+                                username: 'codex',
+                                icon: 'Bot',
+                                color: '#0ea5e9',
+                                createdAt: '2026-03-15T18:00:00.000Z',
+                                updatedAt: '2026-03-15T18:00:00.000Z',
+                                lastActiveAt: '2026-03-15T18:00:00.000Z'
+                            }]
+                    })
+                });
+            }
             if (url.includes('/api/taskforce/sync/workspace/documents')) {
                 return Promise.resolve({ ok: true, json: () => Promise.resolve({ documents: [] }) });
             }
+            if (url.includes('/api/taskforce/sync/workspace/annotated-attachments')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ sessions: [] }) });
+            }
+            if (url.includes('/api/taskforce/sync/workspace/assets')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ assets: [] }) });
+            }
             if (url.includes('/api/taskforce/sync/events')) {
-                syncEventBodies.push(JSON.parse(String(init?.body || '{}')));
                 return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
             }
-            return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+            if (url.includes('/api/taskforce/tasks')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ tasks: [] }) });
+            }
+            if (url.includes('/api/taskforce/archive')) {
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ archived: [] }) });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
         }));
-        const { result } = renderHook((props) => useSyncOrchestrator(props), {
-            initialProps: buildInput()
-        });
-        act(() => {
-            result.current.applyWorkspaceSyncStateSnapshot({
-                cloudSyncEnabled: true,
-                sourceOfTruth: 'cloud',
-                onboardingCompleted: true,
-                pullCursor: ''
-            });
-        });
-        await waitFor(() => {
-            expect(result.current.workspaceCloudSyncEnabled).toBe(true);
-        });
-        await act(async () => {
-            await result.current.pullWorkspaceChangesFromCloud();
-        });
-        await waitFor(() => {
-            expect(result.current.workspaceLastWarningMessage).toBe('Some synced documents could not be decrypted (1).');
-        });
-        expect(syncEventBodies.some((entry) => entry.eventType === 'apply' && entry.status === 'error')).toBe(true);
-    });
-    it('forces a pull retry when pending push is blocked on hydration for too long', async () => {
-        vi.useFakeTimers();
         runWorkspacePullSyncServiceMock.mockResolvedValue({
-            success: false,
-            kind: 'pull_http',
-            status: 503,
-            retryAfterMs: 60_000,
+            success: true,
+            syncedAt: '2026-03-15T22:00:00.000Z',
             cursor: null,
-            pages: 0,
+            pages: 1,
             appliedChanges: 0,
             pullRequestMs: 1,
             applyMs: 0,
             pulledDeleteTaskIds: new Set(),
             pulledActiveUpserts: false,
-            pulledArchivedUpserts: false
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
         });
-        try {
-            const { result } = renderHook((props) => useSyncOrchestrator(props), {
-                initialProps: buildInput()
-            });
-            act(() => {
-                result.current.applyWorkspaceSyncStateSnapshot({
-                    cloudSyncEnabled: true,
-                    sourceOfTruth: 'cloud',
-                    onboardingCompleted: true,
-                    pullCursor: ''
-                });
-            });
-            await act(async () => {
-                await result.current.pullWorkspaceChangesFromCloud();
-            });
-            expect(runWorkspacePullSyncServiceMock.mock.calls.length).toBeGreaterThanOrEqual(1);
-            expect(result.current.isWorkspacePullRetryPending()).toBe(true);
-            await act(async () => {
-                await result.current.pushWorkspaceChangesToCloud('sig-1');
-            });
-            expect(result.current.workspaceLastWarningMessage).toBe('Local changes queued — waiting for initial cloud pull before upload.');
-            await act(async () => {
-                await vi.advanceTimersByTimeAsync(46_000);
-            });
-            await act(async () => {
-                await result.current.pushWorkspaceChangesToCloud('sig-2');
-            });
-            await act(async () => {
-                await vi.advanceTimersByTimeAsync(250);
-            });
-            expect(runWorkspacePullSyncServiceMock.mock.calls.length).toBeGreaterThanOrEqual(2);
-        }
-        finally {
-            vi.useRealTimers();
-        }
+        runWorkspacePushSyncServiceMock.mockResolvedValue({
+            success: true,
+            syncedAt: '2026-03-15T22:00:01.000Z',
+            requestMs: 1,
+            changeCount: 1,
+            deleteCount: 0,
+            currentTaskIds: new Set(),
+            deleteTaskIds: new Set(),
+            currentAiProfileIds: new Set(['ai-profile-codex']),
+            currentAiProfileWatermarks: new Map([['ai-profile-codex', '2026-03-15T18:00:00.000Z']]),
+            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(),
+            currentAnnotatedAttachmentSessionIds: new Set(),
+            deleteAnnotatedAttachmentSessionIds: new Set(),
+            currentAnnotatedAttachmentSessionWatermarks: new Map(),
+            pushedWatermarks: new Map(),
+            emittedEventIds: []
+        });
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput()
+        });
+        runWorkspacePushSyncServiceMock.mockClear();
+        await act(async () => {
+            await result.current.retryWorkspaceCloudSync();
+        });
+        await waitFor(() => {
+            expect(runWorkspacePushSyncServiceMock.mock.calls.length).toBeGreaterThanOrEqual(1);
+        });
+        const retryPayloads = runWorkspacePushSyncServiceMock.mock.calls
+            .map((call) => call?.[0]?.payload)
+            .filter(Boolean);
+        expect(retryPayloads).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                changes: expect.arrayContaining([
+                    expect.objectContaining({
+                        op: 'ai-profile-upsert',
+                        profile: expect.objectContaining({
+                            id: 'ai-profile-codex',
+                            workspaceId: 'workspace-local-active',
+                            name: 'Codex'
+                        })
+                    })
+                ])
+            })
+        ]));
+        expect(result.current.workspaceSyncPendingChanges).toBe(0);
+        unmount();
     });
 });