@taskforcehq/taskforce 0.3.311 → 0.3.313

package/dist/sync/syncService.test.js

@@ -1,903 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { runWorkspacePullSyncService, runWorkspacePushSyncService, ensureCloudWorkspaceReadyForSyncService, syncUserGlobalSettingsService } from './syncService';
-vi.mock('./cloudSyncApi', () => ({
-    pullWorkspaceChanges: vi.fn(),
-    pushWorkspaceChanges: vi.fn(),
-    applyLocalWorkspaceChanges: vi.fn(),
-    handshakeWorkspace: vi.fn(),
-    provisionWorkspace: vi.fn(),
-    pullUserSettings: vi.fn(),
-    pushUserSettings: vi.fn()
-}));
-import { pullWorkspaceChanges, pushWorkspaceChanges, applyLocalWorkspaceChanges, handshakeWorkspace, provisionWorkspace, pullUserSettings, pushUserSettings } from './cloudSyncApi';
-const mockResolveCloudAuthUrl = (p) => p;
-function buildPayload(overrides = {}) {
-    return {
-        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(),
-        ...overrides
-    };
-}
-const baseHandshakeInput = {
-    cloudAuthConfigured: true,
-    runtimeMode: 'local',
-    isAuthenticated: true,
-    resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-    workspaceId: 'ws-test',
-    workspaceName: 'Test Workspace'
-};
-describe('syncService', () => {
-    describe('runWorkspacePushSyncService', () => {
-        beforeEach(() => {
-            vi.mocked(pushWorkspaceChanges).mockReset();
-        });
-        it('returns current/delete document path sets from payload', async () => {
-            vi.mocked(pushWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: { success: true, emittedEventIds: ['epoch-1:1', 'epoch-1:1', 'epoch-1:2', ''] }
-            });
-            const result = await runWorkspacePushSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                payload: buildPayload({
-                    changes: [{ op: 'document-delete', path: 'docs/remove.md' }],
-                    currentTaskIds: new Set(['task-1']),
-                    currentDocumentPaths: new Set(['docs/keep.md']),
-                    deleteDocumentPaths: new Set(['docs/remove.md']),
-                    currentDocumentWatermarks: new Map([['docs/keep.md', '2026-02-01T00:00:00.000Z']]),
-                    pushedWatermarks: new Map([['task-1', 'wm-1']])
-                }),
-                ensureCloudWorkspaceReadyForSync: async () => ({ success: true })
-            });
-            expect(result.success).toBe(true);
-            expect(Array.from(result.currentDocumentPaths)).toEqual(['docs/keep.md']);
-            expect(Array.from(result.deleteDocumentPaths)).toEqual(['docs/remove.md']);
-            expect(result.changeCount).toBe(1);
-            expect(result.emittedEventIds).toEqual(['epoch-1:1', 'epoch-1:2']);
-        });
-        it('uses deterministic fallback idempotency key when crypto.subtle is unavailable', async () => {
-            const payload = buildPayload({
-                changes: [{ op: 'document-delete', path: 'docs/remove.md' }],
-                deleteDocumentPaths: new Set(['docs/remove.md']),
-            });
-            vi.mocked(pushWorkspaceChanges)
-                .mockResolvedValue({
-                ok: true,
-                status: 200,
-                data: { success: true }
-            });
-            vi.stubGlobal('crypto', {});
-            try {
-                await runWorkspacePushSyncService({
-                    resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                    workspaceId: 'ws-fallback',
-                    payload,
-                    ensureCloudWorkspaceReadyForSync: async () => ({ success: true })
-                });
-                await runWorkspacePushSyncService({
-                    resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                    workspaceId: 'ws-fallback',
-                    payload,
-                    ensureCloudWorkspaceReadyForSync: async () => ({ success: true })
-                });
-            }
-            finally {
-                vi.unstubAllGlobals();
-            }
-            expect(pushWorkspaceChanges).toHaveBeenCalledTimes(2);
-            const firstKey = vi.mocked(pushWorkspaceChanges).mock.calls[0]?.[1]?.idempotencyKey;
-            const secondKey = vi.mocked(pushWorkspaceChanges).mock.calls[1]?.[1]?.idempotencyKey;
-            expect(firstKey).toEqual(secondKey);
-            expect(String(firstKey || '')).toMatch(/^ws-fallback:fallback:[0-9a-f]{8}$/);
-        });
-        it('reuses the same idempotency key when retrying push after ensure succeeds', async () => {
-            vi.mocked(pushWorkspaceChanges)
-                .mockResolvedValueOnce({
-                ok: false,
-                status: 403,
-                data: { error: 'forbidden' }
-            })
-                .mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: { success: true }
-            });
-            const ensureCloudWorkspaceReadyForSync = vi.fn().mockResolvedValue({ success: true });
-            const result = await runWorkspacePushSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-retry',
-                payload: buildPayload({
-                    changes: [{ op: 'delete', taskId: 'task-1' }],
-                    deleteTaskIds: new Set(['task-1']),
-                }),
-                ensureCloudWorkspaceReadyForSync
-            });
-            expect(result.success).toBe(true);
-            expect(ensureCloudWorkspaceReadyForSync).toHaveBeenCalledTimes(1);
-            expect(pushWorkspaceChanges).toHaveBeenCalledTimes(2);
-            const firstKey = vi.mocked(pushWorkspaceChanges).mock.calls[0]?.[1]?.idempotencyKey;
-            const secondKey = vi.mocked(pushWorkspaceChanges).mock.calls[1]?.[1]?.idempotencyKey;
-            expect(firstKey).toEqual(secondKey);
-        });
-        it('surfaces push error details from non-ok cloud responses', async () => {
-            vi.mocked(pushWorkspaceChanges).mockResolvedValueOnce({
-                ok: false,
-                status: 500,
-                data: {
-                    error: 'Failed to apply workspace deltas',
-                    code: 'SQLITE_BUSY'
-                }
-            });
-            const result = await runWorkspacePushSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-error',
-                payload: buildPayload({
-                    changes: [{ op: 'delete', taskId: 'task-1' }],
-                    deleteTaskIds: new Set(['task-1']),
-                }),
-                ensureCloudWorkspaceReadyForSync: async () => ({ success: false })
-            });
-            expect(result.success).toBe(false);
-            expect(result.status).toBe(500);
-            expect(result.error).toBe('Failed to apply workspace deltas');
-            expect(result.code).toBe('SQLITE_BUSY');
-        });
-    });
-    describe('runWorkspacePullSyncService', () => {
-        beforeEach(() => {
-            vi.mocked(pullWorkspaceChanges).mockReset();
-            vi.mocked(applyLocalWorkspaceChanges).mockReset();
-        });
-        it('halts pagination correctly when hasMore is false', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(pullWorkspaceChanges).toHaveBeenCalledTimes(1);
-            expect(res.cursor).toBeNull();
-            expect(res.success).toBe(true);
-        });
-        it('correctly advances cursor across multiple pages', async () => {
-            vi.mocked(pullWorkspaceChanges)
-                .mockResolvedValueOnce({
-                ok: true,
-                data: {
-                    success: true,
-                    changes: [],
-                    nextCursor: 'page-2-cursor',
-                    hasMore: true
-                }
-            })
-                .mockResolvedValueOnce({
-                ok: true,
-                data: {
-                    success: true,
-                    changes: [],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(pullWorkspaceChanges).toHaveBeenCalledTimes(2);
-            expect(res.cursor).toBeNull();
-            expect(res.success).toBe(true);
-        });
-        it('forwards workspace members from pull into local apply', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    workspaceMembers: [
-                        {
-                            userId: 'user-1',
-                            workspaceId: 'ws-1',
-                            email: 'member@example.com',
-                            displayName: 'Member One',
-                            role: 'member',
-                            permissionMode: 'read-write',
-                            betaAccess: true,
-                            status: 'active',
-                            disabled: false
-                        }
-                    ],
-                    changes: [{ op: 'upsert', task: { id: 't-1', title: 'Task', assignee: 'user-1' }, archived: false }],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                failures: [],
-                data: { success: true }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(true);
-            expect(applyLocalWorkspaceChanges).toHaveBeenCalledWith('ws-1', expect.any(Array), expect.objectContaining({
-                workspaceMembers: [
-                    expect.objectContaining({
-                        userId: 'user-1',
-                        email: 'member@example.com'
-                    })
-                ]
-            }));
-        });
-        it('applies members-only pull pages even when no entity changes are returned', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    workspaceMembers: [
-                        {
-                            userId: 'user-1',
-                            workspaceId: 'ws-1',
-                            email: 'member@example.com',
-                            displayName: 'Member One',
-                            role: 'member',
-                            permissionMode: 'read-write',
-                            betaAccess: true,
-                            status: 'active',
-                            disabled: false
-                        }
-                    ],
-                    changes: [],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                failures: [],
-                data: { success: true }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(true);
-            expect(applyLocalWorkspaceChanges).toHaveBeenCalledWith('ws-1', [], expect.objectContaining({
-                workspaceMembers: [
-                    expect.objectContaining({
-                        userId: 'user-1'
-                    })
-                ]
-            }));
-        });
-        it('surfaces retryAfterMs when cloud returns 429', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: false,
-                status: 429,
-                retryAfterMs: 30_000,
-                data: { error: 'Rate limited' }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(false);
-            expect(res.kind).toBe('pull_http');
-            expect(res.status).toBe(429);
-            expect(res.retryAfterMs).toBe(30_000);
-        });
-        it('surfaces thrown pull exceptions as exception errors', async () => {
-            vi.mocked(pullWorkspaceChanges).mockRejectedValueOnce(new Error('duplicate key value violates unique constraint'));
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(false);
-            expect(res.kind).toBe('exception');
-            expect(res.status).toBe(0);
-            expect(res.error).toContain('duplicate key value violates unique constraint');
-        });
-        it('retries pull once after 403 when ensure succeeds', async () => {
-            const ensureCloudWorkspaceReadyForSync = vi.fn().mockResolvedValue({ success: true });
-            vi.mocked(pullWorkspaceChanges)
-                .mockResolvedValueOnce({
-                ok: false,
-                status: 403,
-                data: { error: 'Forbidden' }
-            })
-                .mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false,
-                ensureCloudWorkspaceReadyForSync
-            });
-            expect(res.success).toBe(true);
-            expect(ensureCloudWorkspaceReadyForSync).toHaveBeenCalledTimes(1);
-            expect(pullWorkspaceChanges).toHaveBeenCalledTimes(2);
-        });
-        it('does not retry pull when ensure after 403 fails', async () => {
-            const ensureCloudWorkspaceReadyForSync = vi.fn().mockResolvedValue({ success: false, statusCode: 403 });
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: false,
-                status: 403,
-                data: { error: 'Forbidden' }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false,
-                ensureCloudWorkspaceReadyForSync
-            });
-            expect(res.success).toBe(false);
-            expect(res.kind).toBe('pull_http');
-            expect(res.status).toBe(403);
-            expect(ensureCloudWorkspaceReadyForSync).toHaveBeenCalledTimes(1);
-            expect(pullWorkspaceChanges).toHaveBeenCalledTimes(1);
-        });
-        it('returns pull_http kind with status 401 on auth failure', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: false,
-                status: 401,
-                data: { error: 'Unauthorized' }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(false);
-            expect(res.kind).toBe('pull_http');
-            expect(res.status).toBe(401);
-        });
-        it('returns apply_auth kind when apply-local returns 401', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [{ op: 'upsert', task: { id: 't1', title: 'Task 1', updatedAt: '2026-01-01T00:00:00Z' } }],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
-                ok: false,
-                failures: ['apply:401'],
-                appliedCount: 0
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(false);
-            expect(res.kind).toBe('apply_auth');
-            expect(res.status).toBe(401);
-        });
-        it('surfaces apply-local error details from non-ok local apply responses', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [{ op: 'upsert', task: { id: 'task-apply-error', title: 'Apply error', status: 'done', updatedAt: '2026-03-15T20:27:08.000Z' } }],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
-                ok: false,
-                status: 400,
-                failures: ['/api/taskforce/sync/workspace/apply-local:400'],
-                data: { error: 'Task apply rejected by local validation' }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(false);
-            expect(res.kind).toBe('apply_all_candidates');
-            expect(res.status).toBe(400);
-            expect(res.error).toBe('Task apply rejected by local validation');
-        });
-        it('surfaces document decryption failures without failing pull', async () => {
-            const previousKey = process.env.TASKFORCE_SYNC_KEY;
-            process.env.TASKFORCE_SYNC_KEY = 'test-sync-key';
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [{ op: 'document-upsert', path: 'docs/secret.md', content: 'V1:AESGCM:malformed' }],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                failures: [],
-                appliedCount: 1,
-                data: { success: true }
-            });
-            try {
-                const res = await runWorkspacePullSyncService({
-                    resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                    workspaceId: 'ws-1',
-                    cursor: null,
-                    bootstrap: false
-                });
-                expect(res.success).toBe(true);
-                expect(res.documentDecryptFailures).toEqual(['docs/secret.md']);
-            }
-            finally {
-                if (typeof previousKey === 'string')
-                    process.env.TASKFORCE_SYNC_KEY = previousKey;
-                else
-                    delete process.env.TASKFORCE_SYNC_KEY;
-            }
-        });
-        it('tracks event-only task pulls so callers can refresh visible task history', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [{
-                            op: 'task-event-upsert',
-                            event: {
-                                id: 'task-event-1',
-                                taskId: 'task-1',
-                                workspaceId: 'ws-1',
-                                action: 'task-status-changed',
-                                actor: 'ai-profile-1',
-                                actorType: 'ai',
-                                createdAt: '2026-04-13T10:05:00.000Z',
-                                details: {
-                                    changes: {
-                                        status: {
-                                            from: 'in-progress',
-                                            to: 'done'
-                                        }
-                                    }
-                                }
-                            }
-                        }],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                failures: [],
-                appliedCount: 1,
-                data: { success: true }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(true);
-            expect(res.pulledTaskEventUpserts).toBe(true);
-            expect(res.pulledActiveUpserts).toBe(false);
-            expect(res.pulledArchivedUpserts).toBe(false);
-        });
-        it('marks planning upserts when the pull contains initiative or workstream changes', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [{
-                            op: 'workstream-upsert',
-                            updatedAt: '2026-04-27T22:00:00.000Z',
-                            workstream: {
-                                id: 'ws-123',
-                                title: 'Planning sync workstream',
-                                description: 'Contains planning attachments',
-                                createdAt: '2026-04-27T21:00:00.000Z',
-                                updatedAt: '2026-04-27T22:00:00.000Z',
-                                attachments: []
-                            }
-                        }],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                failures: [],
-                appliedCount: 1,
-                data: { success: true }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false
-            });
-            expect(res.success).toBe(true);
-            expect(res.pulledPlanningUpserts).toBe(true);
-            expect(res.pulledActiveUpserts).toBe(false);
-            expect(res.pulledArchivedUpserts).toBe(false);
-        });
-        it('zero-change bootstrap pull (no changes, hasMore false) returns success true', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: { success: true },
-                failures: []
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-bootstrap',
-                cursor: null,
-                bootstrap: true
-            });
-            expect(res.success).toBe(true);
-            expect(res.appliedChanges).toBe(0);
-            expect(res.cursor).toBeNull();
-            expect(applyLocalWorkspaceChanges).toHaveBeenCalledWith('ws-bootstrap', [], {
-                bootstrapSnapshot: {
-                    currentAnnotatedAttachmentSessionIds: []
-                }
-            });
-        });
-        it('sends pulled annotated attachment session ids during bootstrap reconciliation', async () => {
-            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    changes: [{
-                            op: 'annotated-attachment-session-upsert',
-                            session: {
-                                id: 'session-1',
-                                workspaceId: 'ws-annotated',
-                                taskId: 'task-1',
-                                baseImageAssetId: 'asset-1',
-                                title: 'Session 1',
-                                globalInstruction: null,
-                                annotations: [],
-                                createdByActorId: null,
-                                updatedByActorId: null,
-                                createdAt: '2026-03-26T00:00:00.000Z',
-                                updatedAt: '2026-03-26T00:00:00.000Z',
-                                deletedAt: null
-                            }
-                        }],
-                    nextCursor: null,
-                    hasMore: false
-                }
-            });
-            vi.mocked(applyLocalWorkspaceChanges)
-                .mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: { success: true },
-                failures: []
-            })
-                .mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: { success: true },
-                failures: []
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-annotated',
-                cursor: null,
-                bootstrap: true
-            });
-            expect(res.success).toBe(true);
-            expect(applyLocalWorkspaceChanges).toHaveBeenNthCalledWith(1, 'ws-annotated', expect.arrayContaining([
-                expect.objectContaining({
-                    op: 'annotated-attachment-session-upsert',
-                    session: expect.objectContaining({ id: 'session-1' })
-                })
-            ]), expect.objectContaining({ repairMode: false }));
-            expect(applyLocalWorkspaceChanges).toHaveBeenNthCalledWith(2, 'ws-annotated', [], {
-                bootstrapSnapshot: {
-                    currentAnnotatedAttachmentSessionIds: ['session-1']
-                }
-            });
-        });
-        it('stops at maxPages and returns partial success', async () => {
-            // Always returns hasMore=true so the loop would run forever without maxPages
-            vi.mocked(pullWorkspaceChanges).mockResolvedValue({
-                ok: true,
-                data: {
-                    success: true,
-                    changes: [],
-                    nextCursor: 'cursor-next',
-                    hasMore: true
-                }
-            });
-            const res = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                workspaceId: 'ws-1',
-                cursor: null,
-                bootstrap: false,
-                maxPages: 3
-            });
-            expect(pullWorkspaceChanges).toHaveBeenCalledTimes(3);
-            expect(res.success).toBe(true);
-            expect(res.pages).toBe(3);
-        });
-    });
-    describe('ensureCloudWorkspaceReadyForSyncService', () => {
-        beforeEach(() => {
-            vi.mocked(handshakeWorkspace).mockReset();
-            vi.mocked(provisionWorkspace).mockReset();
-        });
-        it('returns success when handshake succeeds', async () => {
-            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
-                ok: true, status: 200, data: {}
-            });
-            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
-            expect(res.success).toBe(true);
-            expect(res.provisioned).toBe(false);
-        });
-        it('propagates 401 from handshake as auth failure', async () => {
-            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
-                ok: false, status: 401, data: { error: 'Invalid session' }
-            });
-            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
-            expect(res.success).toBe(false);
-            expect(res.statusCode).toBe(401);
-            expect(res.error).toContain('Invalid session');
-        });
-        it('propagates 429 from handshake with retryAfterMs', async () => {
-            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
-                ok: false, status: 429, retryAfterMs: 45_000, data: { error: 'Rate limited' }
-            });
-            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
-            expect(res.success).toBe(false);
-            expect(res.statusCode).toBe(429);
-            expect(res.retryAfterMs).toBe(45_000);
-        });
-        it('marks status 0 handshake failures as transient', async () => {
-            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
-                ok: false, status: 0, data: {}
-            });
-            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
-            expect(res.success).toBe(false);
-            expect(res.statusCode).toBe(0);
-            expect(res.transient).toBe(true);
-        });
-        it('recovers from missing cloud workspace selection by provisioning and retrying handshake', async () => {
-            vi.mocked(handshakeWorkspace)
-                .mockResolvedValueOnce({
-                ok: false,
-                status: 400,
-                data: {
-                    code: 'WORKSPACE_ID_REQUIRED',
-                    error: 'No cloud workspace is selected. Complete workspace setup first.'
-                }
-            })
-                .mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {}
-            });
-            vi.mocked(provisionWorkspace).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: {
-                    success: true,
-                    existing: true
-                }
-            });
-            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
-            expect(res.success).toBe(true);
-            expect(res.provisioned).toBe(true);
-            expect(provisionWorkspace).toHaveBeenCalledWith(mockResolveCloudAuthUrl, {
-                workspaceId: 'ws-test',
-                name: 'Test Workspace'
-            });
-            expect(handshakeWorkspace).toHaveBeenCalledTimes(2);
-        });
-        it('surfaces provisioning failure when recovering missing cloud workspace selection', async () => {
-            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
-                ok: false,
-                status: 400,
-                data: {
-                    code: 'WORKSPACE_ID_REQUIRED',
-                    error: 'No cloud workspace is selected. Complete workspace setup first.'
-                }
-            });
-            vi.mocked(provisionWorkspace).mockResolvedValueOnce({
-                ok: false,
-                status: 409,
-                data: {
-                    code: 'WORKSPACE_ID_ALREADY_EXISTS',
-                    error: 'Workspace ID already exists'
-                }
-            });
-            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
-            expect(res.success).toBe(false);
-            expect(res.statusCode).toBe(409);
-            expect(res.error).toContain('already linked to another cloud account');
-        });
-        it('returns failure when cloudAuthConfigured is false', async () => {
-            const res = await ensureCloudWorkspaceReadyForSyncService({
-                ...baseHandshakeInput,
-                cloudAuthConfigured: false
-            });
-            expect(res.success).toBe(false);
-            expect(handshakeWorkspace).not.toHaveBeenCalled();
-        });
-        it('returns failure when runtimeMode is not local', async () => {
-            const res = await ensureCloudWorkspaceReadyForSyncService({
-                ...baseHandshakeInput,
-                runtimeMode: 'cloud'
-            });
-            expect(res.success).toBe(false);
-            expect(handshakeWorkspace).not.toHaveBeenCalled();
-        });
-        it('returns failure when not authenticated', async () => {
-            const res = await ensureCloudWorkspaceReadyForSyncService({
-                ...baseHandshakeInput,
-                isAuthenticated: false
-            });
-            expect(res.success).toBe(false);
-            expect(handshakeWorkspace).not.toHaveBeenCalled();
-        });
-        it('maps workspace access conflicts to user-facing guidance', async () => {
-            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
-                ok: false,
-                status: 409,
-                data: { code: 'WORKSPACE_ID_MISMATCH', error: 'Workspace mismatch' }
-            });
-            vi.mocked(provisionWorkspace).mockResolvedValueOnce({
-                ok: false,
-                status: 409,
-                data: { code: 'WORKSPACE_ID_ALREADY_EXISTS', error: 'Workspace ID already exists' }
-            });
-            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
-            expect(res.success).toBe(false);
-            expect(res.statusCode).toBe(409);
-            expect(res.error).toContain('already linked to another cloud account');
-            expect(res.error).toContain('grant you access');
-        });
-        it('does not provision a new cloud workspace during attach-cloud mismatch handling', async () => {
-            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
-                ok: false,
-                status: 409,
-                data: { code: 'WORKSPACE_ID_MISMATCH', error: 'Workspace mismatch' }
-            });
-            const res = await ensureCloudWorkspaceReadyForSyncService({
-                ...baseHandshakeInput,
-                allowProvisionOnMismatch: false
-            });
-            expect(res.success).toBe(false);
-            expect(res.statusCode).toBe(409);
-            expect(provisionWorkspace).not.toHaveBeenCalled();
-        });
-    });
-    describe('syncUserGlobalSettingsService transient metadata', () => {
-        beforeEach(() => {
-            vi.mocked(pullUserSettings).mockReset();
-            vi.mocked(pushUserSettings).mockReset();
-        });
-        it('propagates retryAfterMs + transient for pull 429 failure', async () => {
-            vi.mocked(pullUserSettings).mockResolvedValueOnce({
-                ok: false,
-                status: 429,
-                retryAfterMs: 30_000,
-                data: { error: 'Rate limited' }
-            });
-            const res = await syncUserGlobalSettingsService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                userId: 'user-1',
-                preferCloudOnFirstSync: true,
-                getLocalUpdatedAt: () => null,
-                buildLocalSettings: () => ({ theme: 'dark' }),
-                applyRemoteSettings: async () => { }
-            });
-            expect(res.success).toBe(false);
-            expect(res.statusCode).toBe(429);
-            expect(res.retryAfterMs).toBe(30_000);
-            expect(res.transient).toBe(true);
-        });
-        it('propagates transient=true for push status 0 failure', async () => {
-            vi.mocked(pullUserSettings).mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                data: { settings: {}, updatedAt: null }
-            });
-            vi.mocked(pushUserSettings).mockResolvedValueOnce({
-                ok: false,
-                status: 0,
-                data: {}
-            });
-            const res = await syncUserGlobalSettingsService({
-                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
-                userId: 'user-1',
-                preferCloudOnFirstSync: false,
-                getLocalUpdatedAt: () => null,
-                buildLocalSettings: () => ({ theme: 'dark' }),
-                applyRemoteSettings: async () => { }
-            });
-            expect(res.success).toBe(false);
-            expect(res.statusCode).toBe(0);
-            expect(res.transient).toBe(true);
-        });
-    });
-});