@taskforcehq/taskforce 0.3.302 → 0.3.304

package/dist/sync/syncApplyHandlers.test.js

@@ -0,0 +1,377 @@
+import { describe, expect, it, vi } from 'vitest';
+import { applyCollaborationSyncChanges, applyContentSyncChanges, applyPreparedTaskSyncSnapshot, applyTaskSyncDeletes, classifyWorkspaceSyncChanges, prepareTaskSyncSnapshotApply, } from './syncApplyHandlers.js';
+function createCoreFixture(overrides = {}) {
+    return {
+        resolveTaskIdentifier: vi.fn().mockReturnValue(null),
+        getTask: vi.fn().mockReturnValue(null),
+        deleteTaskForSync: vi.fn(),
+        applyWorkspaceSyncSnapshot: vi.fn().mockReturnValue({
+            total: 1,
+            created: 0,
+            updated: 1,
+            archived: 0,
+            unarchived: 0,
+            skipped: 0,
+        }),
+        notifyDocumentMetadataMutation: vi.fn(),
+        getDocumentWatermark: vi.fn().mockReturnValue(null),
+        getTenantId: vi.fn().mockReturnValue('tenant-1'),
+        getDocumentReviewSession: vi.fn().mockReturnValue(null),
+        upsertDocumentReviewSessionForSync: vi.fn(),
+        listDocumentReviewCommentsForSync: vi.fn().mockReturnValue([]),
+        upsertDocumentReviewCommentForSync: vi.fn(),
+        deleteDocumentReviewSessionForSync: vi.fn(),
+        deleteDocumentReviewCommentForSync: vi.fn(),
+        getAnnotatedAttachmentSession: vi.fn().mockReturnValue(null),
+        upsertAnnotatedAttachmentSessionForSync: vi.fn(),
+        deleteAnnotatedAttachmentSessionForSync: vi.fn(),
+        ...overrides,
+    };
+}
+describe('syncApplyHandlers', () => {
+    it('classifies task and workstream changes, then prepares and applies the task snapshot pipeline', () => {
+        const diagnostics = [];
+        const workspaceId = 'workspace-1';
+        const applyModel = classifyWorkspaceSyncChanges({
+            workspaceId,
+            incomingChanges: [
+                {
+                    op: 'workstream-upsert',
+                    workstream: {
+                        id: 'workstream-1',
+                        title: 'Delivery',
+                        description: null,
+                        createdAt: '2026-04-10T09:00:00.000Z',
+                        updatedAt: '2026-04-10T09:00:00.000Z',
+                    },
+                },
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-1',
+                        title: 'Superseded task',
+                        status: 'task',
+                        category: 'general',
+                        type: 'feature',
+                        createdAt: '2026-04-10T09:00:00.000Z',
+                        updatedAt: '2026-04-10T10:00:00.000Z',
+                        referenceNumber: 7,
+                    },
+                },
+                {
+                    op: 'upsert',
+                    archived: true,
+                    task: {
+                        id: 'task-2',
+                        title: 'Archived task',
+                        status: 'done',
+                        category: 'general',
+                        type: 'feature',
+                        createdAt: '2026-04-10T09:00:00.000Z',
+                        updatedAt: '2026-04-10T10:30:00.000Z',
+                        isArchived: true,
+                    },
+                },
+                {
+                    op: 'delete',
+                    taskId: 'task-1',
+                },
+                {
+                    op: 'delete',
+                    taskId: 'task-stale',
+                },
+            ],
+            normalizeWorkspaceSyncDocumentPath: (rawPath) => typeof rawPath === 'string' ? rawPath : null,
+            normalizeTaskAssetPath: (rawPath) => typeof rawPath === 'string' ? rawPath : null,
+            normalizeIncomingAiProfileSurfaceType: () => null,
+            normalizeTaskEventSyncPayload: () => null,
+            recordSyncDiagnostic: (targetWorkspaceId, eventType, message, details) => {
+                diagnostics.push({ workspaceId: targetWorkspaceId, eventType, message, details });
+            },
+        });
+        expect(applyModel.planning.incomingWorkstreams.get('workstream-1')).toEqual(expect.objectContaining({
+            id: 'workstream-1',
+            title: 'Delivery',
+        }));
+        expect(applyModel.taskMutations.upserts).toHaveLength(2);
+        expect(applyModel.taskMutations.deletes.get('task-1')).toBe('2026-04-10T11:00:00.000Z');
+        const core = createCoreFixture({
+            resolveTaskIdentifier: vi.fn().mockReturnValue({
+                id: 'task-local-7',
+                title: 'Local incumbent',
+                referenceNumber: 7,
+            }),
+            getTask: vi.fn().mockImplementation((taskId) => {
+                if (taskId === 'task-1') {
+                    return {
+                        id: 'task-1',
+                        title: 'Superseded task',
+                        createdAt: '2026-04-10T09:00:00.000Z',
+                        updatedAt: '2026-04-10T10:00:00.000Z',
+                        isArchived: false,
+                    };
+                }
+                if (taskId === 'task-stale') {
+                    return {
+                        id: 'task-stale',
+                        title: 'Keep local task',
+                        createdAt: '2026-04-10T09:00:00.000Z',
+                        updatedAt: '2026-04-10T09:30:00.000Z',
+                        isArchived: false,
+                    };
+                }
+                return null;
+            }),
+        });
+        const prepared = prepareTaskSyncSnapshotApply({
+            core,
+            workspaceId,
+            taskMutations: applyModel.taskMutations,
+            recordSyncDiagnostic: (targetWorkspaceId, eventType, message, details) => {
+                diagnostics.push({ workspaceId: targetWorkspaceId, eventType, message, details });
+            },
+        });
+        expect(prepared.tasks).toEqual([]);
+        expect(prepared.archived).toEqual([
+            expect.objectContaining({
+                id: 'task-2',
+                title: 'Archived task',
+            }),
+        ]);
+        expect(diagnostics).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                workspaceId,
+                eventType: 'apply',
+                message: 'Detected task reference number mismatch during normal sync.',
+                details: expect.objectContaining({
+                    referenceLabel: 'T-7',
+                    existingTaskId: 'task-local-7',
+                    taskId: 'task-1',
+                }),
+            }),
+        ]));
+        const deleteCount = applyTaskSyncDeletes({
+            core,
+            workspaceId,
+            taskMutations: applyModel.taskMutations,
+            recordSyncDiagnostic: vi.fn(),
+        });
+        expect(deleteCount).toBe(2);
+        expect(core.deleteTaskForSync).toHaveBeenCalledTimes(1);
+        expect(core.deleteTaskForSync).toHaveBeenCalledWith('task-1', workspaceId, { persistBackup: false });
+        const result = applyPreparedTaskSyncSnapshot({
+            core,
+            workspaceId,
+            prepared,
+        });
+        expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledWith({
+            tasks: [],
+            archived: [
+                expect.objectContaining({
+                    id: 'task-2',
+                    title: 'Archived task',
+                    isArchived: true,
+                }),
+            ],
+        }, workspaceId);
+        expect(result).toEqual(expect.objectContaining({ total: 1 }));
+    });
+    it('applies document and asset changes through the content handler helpers', async () => {
+        const core = createCoreFixture();
+        const writeWorkspaceSyncDocument = vi.fn().mockResolvedValue(undefined);
+        const writeWorkspaceSyncBinaryAsset = vi.fn().mockResolvedValue(undefined);
+        const deleteWorkspaceSyncDocument = vi.fn();
+        const deleteWorkspaceSyncBinaryAsset = vi.fn();
+        await applyContentSyncChanges({
+            core,
+            workspaceId: 'workspace-1',
+            incomingDocuments: [
+                {
+                    path: 'docs/spec.md',
+                    updatedAt: '2026-04-10T10:00:00.000Z',
+                    content: '# Spec',
+                    assetId: 'asset-doc-1',
+                },
+            ],
+            incomingDocumentDeletes: new Map([
+                ['docs/stale.md', '2026-04-10T11:00:00.000Z'],
+            ]),
+            incomingAssets: [
+                {
+                    path: 'assets/proof.png',
+                    updatedAt: '2026-04-10T10:05:00.000Z',
+                    contentBase64: Buffer.from('png-bytes').toString('base64'),
+                    assetId: 'asset-image-1',
+                    kind: 'image',
+                    mimeType: 'image/png',
+                },
+            ],
+            incomingAssetDeletes: new Map([
+                ['assets/stale.png', '2026-04-10T11:05:00.000Z'],
+            ]),
+            basePath: '/tmp/taskforce-sync-content',
+            hasObjectStorageClient: () => false,
+            hasDocumentSyncMetadataDrift: () => false,
+            hasBinaryAssetSyncMetadataDrift: () => false,
+            getExistingDocument: () => null,
+            writeWorkspaceSyncDocument,
+            deleteWorkspaceSyncDocument,
+            writeWorkspaceSyncBinaryAsset,
+            deleteWorkspaceSyncBinaryAsset,
+            getExistingBinaryAsset: () => null,
+            recordSyncDiagnostic: vi.fn(),
+        });
+        expect(writeWorkspaceSyncDocument).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'docs/spec.md', assetId: 'asset-doc-1' }), 'workspace-1', { allowReferenceNumberReassignment: true });
+        expect(writeWorkspaceSyncBinaryAsset).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'assets/proof.png', assetId: 'asset-image-1' }), 'workspace-1', { allowReferenceNumberReassignment: true });
+        expect(deleteWorkspaceSyncDocument).toHaveBeenCalledWith('/tmp/taskforce-sync-content', 'docs/stale.md', 'workspace-1');
+        expect(deleteWorkspaceSyncBinaryAsset).toHaveBeenCalledWith('/tmp/taskforce-sync-content', 'assets/stale.png', 'workspace-1');
+        expect(core.notifyDocumentMetadataMutation).toHaveBeenNthCalledWith(1, 'workspace-1', ['docs/spec.md', 'assets/proof.png'], 'upsert');
+        expect(core.notifyDocumentMetadataMutation).toHaveBeenNthCalledWith(2, 'workspace-1', ['docs/stale.md', 'assets/stale.png'], 'delete');
+    });
+    it('only allows reference reassignment for content writes when the content changed or repair is explicit', async () => {
+        const core = createCoreFixture({
+            getDocumentWatermark: vi.fn().mockReturnValue(null),
+        });
+        const writeWorkspaceSyncDocument = vi.fn().mockResolvedValue(undefined);
+        const writeWorkspaceSyncBinaryAsset = vi.fn().mockResolvedValue(undefined);
+        await applyContentSyncChanges({
+            core,
+            workspaceId: 'workspace-1',
+            incomingDocuments: [
+                {
+                    path: 'docs/spec.md',
+                    updatedAt: '2026-04-10T10:00:00.000Z',
+                    content: '# Spec',
+                    assetId: 'asset-doc-1',
+                    referenceNumber: 22,
+                },
+            ],
+            incomingDocumentDeletes: new Map(),
+            incomingAssets: [
+                {
+                    path: 'assets/proof.png',
+                    updatedAt: '2026-04-10T10:05:00.000Z',
+                    contentBase64: Buffer.from('new-bytes').toString('base64'),
+                    assetId: 'asset-image-1',
+                    kind: 'image',
+                    mimeType: 'image/png',
+                    referenceNumber: 33,
+                },
+            ],
+            incomingAssetDeletes: new Map(),
+            basePath: '/tmp/taskforce-sync-content',
+            hasObjectStorageClient: () => false,
+            hasDocumentSyncMetadataDrift: () => true,
+            hasBinaryAssetSyncMetadataDrift: () => true,
+            getExistingDocument: () => ({
+                updatedAt: '2026-04-10T10:00:00.000Z',
+                contentHash: '6bb50a17e2dc2fc14caea95a15cd8572018b6d22d74fb7b9ad015b5a0a8a935e',
+            }),
+            writeWorkspaceSyncDocument,
+            deleteWorkspaceSyncDocument: vi.fn(),
+            writeWorkspaceSyncBinaryAsset,
+            deleteWorkspaceSyncBinaryAsset: vi.fn(),
+            getExistingBinaryAsset: () => ({
+                updatedAt: '2026-04-10T10:00:00.000Z',
+                contentSha256: 'old-hash',
+            }),
+            recordSyncDiagnostic: vi.fn(),
+        });
+        expect(writeWorkspaceSyncDocument).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'docs/spec.md' }), 'workspace-1', { allowReferenceNumberReassignment: false });
+        expect(writeWorkspaceSyncBinaryAsset).toHaveBeenCalledWith('/tmp/taskforce-sync-content', expect.objectContaining({ path: 'assets/proof.png' }), 'workspace-1', { allowReferenceNumberReassignment: true });
+    });
+    it('applies collaboration upserts and deletes through the collaboration handlers', () => {
+        const core = createCoreFixture();
+        applyCollaborationSyncChanges({
+            core,
+            workspaceId: 'workspace-1',
+            incomingDocumentReviewSessions: new Map([
+                ['session-1', {
+                        id: 'session-1',
+                        assetId: 'asset-doc-1',
+                        documentId: 'doc-1',
+                        documentVersion: 3,
+                        title: 'Review round',
+                        status: 'open',
+                        comments: [],
+                        createdByActorId: 'user-1',
+                        updatedByActorId: 'user-1',
+                        createdAt: '2026-04-10T09:00:00.000Z',
+                        updatedAt: '2026-04-10T10:00:00.000Z',
+                        deletedAt: null,
+                    }],
+            ]),
+            incomingDocumentReviewSessionDeletes: new Map([
+                ['session-2', '2026-04-10T11:00:00.000Z'],
+            ]),
+            incomingDocumentReviewComments: new Map([
+                ['comment-1', {
+                        id: 'comment-1',
+                        sessionId: 'session-1',
+                        body: 'Looks good',
+                        anchor: { kind: 'document' },
+                        order: 0,
+                        authorActorId: 'user-1',
+                        createdAt: '2026-04-10T09:05:00.000Z',
+                        updatedAt: '2026-04-10T10:05:00.000Z',
+                        deletedAt: null,
+                    }],
+            ]),
+            incomingDocumentReviewCommentDeletes: new Map([
+                ['comment-2', '2026-04-10T11:05:00.000Z'],
+            ]),
+            incomingAnnotatedAttachmentSessions: new Map([
+                ['annotation-session-1', {
+                        id: 'annotation-session-1',
+                        workspaceId: 'workspace-1',
+                        taskId: 'task-1',
+                        baseImageAssetId: 'asset-image-1',
+                        title: 'Annotations',
+                        globalInstruction: 'Inspect issue',
+                        annotations: [],
+                        createdByActorId: 'user-1',
+                        updatedByActorId: 'user-1',
+                        createdAt: '2026-04-10T09:10:00.000Z',
+                        updatedAt: '2026-04-10T10:10:00.000Z',
+                        deletedAt: null,
+                    }],
+            ]),
+            incomingAnnotatedAttachmentSessionDeletes: new Map([
+                ['annotation-session-2', '2026-04-10T11:10:00.000Z'],
+            ]),
+            recordSyncDiagnostic: vi.fn(),
+            createSyncRouteError: (message, details) => Object.assign(new Error(message), { details }),
+        });
+        expect(core.upsertDocumentReviewSessionForSync).toHaveBeenCalledWith(expect.objectContaining({
+            id: 'session-1',
+            workspaceId: 'workspace-1',
+            assetId: 'asset-doc-1',
+        }));
+        expect(core.deleteDocumentReviewSessionForSync).toHaveBeenCalledWith({
+            workspaceId: 'workspace-1',
+            sessionId: 'session-2',
+            deletedAt: '2026-04-10T11:00:00.000Z',
+        });
+        expect(core.upsertDocumentReviewCommentForSync).toHaveBeenCalledWith(expect.objectContaining({
+            id: 'comment-1',
+            sessionId: 'session-1',
+            workspaceId: 'workspace-1',
+        }));
+        expect(core.deleteDocumentReviewCommentForSync).toHaveBeenCalledWith({
+            workspaceId: 'workspace-1',
+            commentId: 'comment-2',
+            deletedAt: '2026-04-10T11:05:00.000Z',
+        });
+        expect(core.upsertAnnotatedAttachmentSessionForSync).toHaveBeenCalledWith(expect.objectContaining({
+            id: 'annotation-session-1',
+            workspaceId: 'workspace-1',
+            baseImageAssetId: 'asset-image-1',
+        }));
+        expect(core.deleteAnnotatedAttachmentSessionForSync).toHaveBeenCalledWith({
+            workspaceId: 'workspace-1',
+            sessionId: 'annotation-session-2',
+            deletedAt: '2026-04-10T11:10:00.000Z',
+        });
+    });
+});

package/dist/sync/syncService.d.ts

@@ -1,4 +1,4 @@
-import type { WorkspaceSyncPayload } from './workspaceSyncModel';
+import type { WorkspaceSyncPayload, WorkspaceSyncTaskSnapshot } from './workspaceSyncModel';
 export declare function isTransientWorkspaceSyncStatus(status: number | null | undefined): boolean;
 export interface EnsureWorkspaceReadyInput {
     cloudAuthConfigured: boolean;
@@ -77,10 +77,16 @@ export interface WorkspacePushSyncResult {
     currentAnnotatedAttachmentSessionIds: Set<string>;
     deleteAnnotatedAttachmentSessionIds: Set<string>;
     currentAnnotatedAttachmentSessionWatermarks: Map<string, string>;
+    currentTaskEventWatermarks: Map<string, string>;
     /** Watermarks for every task upsert that was successfully pushed. */
     pushedWatermarks: Map<string, string>;
     /** Server-emitted realtime mutation event ids for this push apply. */
     emittedEventIds: string[];
+    /** Authoritative task snapshots returned immediately by the push route for incoming task upserts. */
+    appliedTaskUpserts: Array<{
+        archived: boolean;
+        task: WorkspaceSyncTaskSnapshot;
+    }>;
 }
 export declare function runWorkspacePushSyncService(input: WorkspacePushSyncInput): Promise<WorkspacePushSyncResult>;
 export type WorkspacePullFailureKind = 'pull_http' | 'apply_auth' | 'apply_all_candidates' | 'apply_payload' | 'exception';
@@ -113,8 +119,10 @@ export interface WorkspacePullSyncResult {
     pulledDeleteTaskIds: Set<string>;
     pulledActiveUpserts: boolean;
     pulledArchivedUpserts: boolean;
+    pulledTaskEventUpserts?: boolean;
     documentDecryptFailures?: string[];
     emittedEventIds?: string[];
+    serverDiagnostics?: Record<string, unknown> | null;
 }
 export declare function runWorkspacePullSyncService(input: WorkspacePullSyncInput): Promise<WorkspacePullSyncResult>;
 export declare function syncUserGlobalSettingsService(input: UserSettingsSyncInput): Promise<UserSettingsSyncResult>;

package/dist/sync/syncService.js

@@ -187,8 +187,10 @@ export async function runWorkspacePushSyncService(input) {
             currentAnnotatedAttachmentSessionIds: input.payload.currentAnnotatedAttachmentSessionIds,
             deleteAnnotatedAttachmentSessionIds: input.payload.deleteAnnotatedAttachmentSessionIds,
             currentAnnotatedAttachmentSessionWatermarks: input.payload.currentAnnotatedAttachmentSessionWatermarks,
+            currentTaskEventWatermarks: input.payload.currentTaskEventWatermarks,
             pushedWatermarks: new Map(),
-            emittedEventIds: []
+            emittedEventIds: [],
+            appliedTaskUpserts: []
         };
     }
     const pushData = asObjectRecord(pushResult.data);
@@ -197,6 +199,23 @@ export async function runWorkspacePushSyncService(input) {
             .map((entry) => String(entry || '').trim())
             .filter(Boolean)))
         : [];
+    const appliedTaskUpserts = Array.isArray(pushData.appliedTaskUpserts)
+        ? pushData.appliedTaskUpserts
+            .map((entry) => {
+            const source = entry && typeof entry === 'object' ? entry : {};
+            const task = source.task && typeof source.task === 'object'
+                ? source.task
+                : null;
+            const taskId = String(task?.id || '').trim();
+            if (!task || !taskId)
+                return null;
+            return {
+                archived: source.archived === true,
+                task
+            };
+        })
+            .filter((entry) => Boolean(entry))
+        : [];
     return {
         success: true,
         syncedAt: new Date().toISOString(),
@@ -226,8 +245,10 @@ export async function runWorkspacePushSyncService(input) {
         currentAnnotatedAttachmentSessionIds: input.payload.currentAnnotatedAttachmentSessionIds,
         deleteAnnotatedAttachmentSessionIds: input.payload.deleteAnnotatedAttachmentSessionIds,
         currentAnnotatedAttachmentSessionWatermarks: input.payload.currentAnnotatedAttachmentSessionWatermarks,
+        currentTaskEventWatermarks: input.payload.currentTaskEventWatermarks,
         pushedWatermarks: input.payload.pushedWatermarks,
-        emittedEventIds
+        emittedEventIds,
+        appliedTaskUpserts
     };
 }
 export async function runWorkspacePullSyncService(input) {
@@ -240,9 +261,11 @@ export async function runWorkspacePullSyncService(input) {
     const pulledDeleteTaskIds = new Set();
     let pulledActiveUpserts = false;
     let pulledArchivedUpserts = false;
+    let pulledTaskEventUpserts = false;
     const documentDecryptFailures = new Set();
     const emittedEventIds = new Set();
     const pulledAnnotatedAttachmentSessionIds = new Set();
+    let lastServerDiagnostics = null;
     const maxPages = Number.isFinite(Number(input.maxPages)) ? Math.max(1, Math.floor(Number(input.maxPages))) : 20;
     try {
         while (hasMore && pages < maxPages) {
@@ -279,11 +302,17 @@ export async function runWorkspacePullSyncService(input) {
                     pulledDeleteTaskIds,
                     pulledActiveUpserts,
                     pulledArchivedUpserts,
-                    documentDecryptFailures: Array.from(documentDecryptFailures)
+                    pulledTaskEventUpserts,
+                    documentDecryptFailures: Array.from(documentDecryptFailures),
+                    serverDiagnostics: null
                 };
             }
             const pullData = pullRes.data || {};
             const changes = Array.isArray(pullData?.changes) ? pullData.changes : [];
+            const serverDiagnostics = pullData?.diagnostics && typeof pullData.diagnostics === 'object'
+                ? pullData.diagnostics
+                : null;
+            lastServerDiagnostics = serverDiagnostics;
             const hasWorkspaceMembersSnapshot = Array.isArray(pullData?.workspaceMembers);
             const workspaceMembers = hasWorkspaceMembersSnapshot
                 ? pullData.workspaceMembers
@@ -303,6 +332,10 @@ export async function runWorkspacePullSyncService(input) {
                         pulledAnnotatedAttachmentSessionIds.add(sessionId);
                     continue;
                 }
+                if (change.op === 'task-event-upsert') {
+                    pulledTaskEventUpserts = true;
+                    continue;
+                }
                 if (change.op === 'document-upsert') {
                     if (typeof change.content === 'string' && typeof process !== 'undefined' && process.env?.TASKFORCE_SYNC_KEY) {
                         try {
@@ -365,7 +398,9 @@ export async function runWorkspacePullSyncService(input) {
                             pulledDeleteTaskIds,
                             pulledActiveUpserts,
                             pulledArchivedUpserts,
-                            documentDecryptFailures: Array.from(documentDecryptFailures)
+                            pulledTaskEventUpserts,
+                            documentDecryptFailures: Array.from(documentDecryptFailures),
+                            serverDiagnostics
                         };
                     }
                     const hasTransientApplyFailure = applyFailures.some((entry) => {
@@ -391,8 +426,10 @@ export async function runWorkspacePullSyncService(input) {
                         pulledDeleteTaskIds,
                         pulledActiveUpserts,
                         pulledArchivedUpserts,
+                        pulledTaskEventUpserts,
                         documentDecryptFailures: Array.from(documentDecryptFailures),
-                        emittedEventIds: Array.from(emittedEventIds)
+                        emittedEventIds: Array.from(emittedEventIds),
+                        serverDiagnostics: lastServerDiagnostics
                     };
                 }
                 const applyPayloadData = asObjectRecord(applyResult.data);
@@ -411,8 +448,10 @@ export async function runWorkspacePullSyncService(input) {
                         pulledDeleteTaskIds,
                         pulledActiveUpserts,
                         pulledArchivedUpserts,
+                        pulledTaskEventUpserts,
                         documentDecryptFailures: Array.from(documentDecryptFailures),
-                        emittedEventIds: Array.from(emittedEventIds)
+                        emittedEventIds: Array.from(emittedEventIds),
+                        serverDiagnostics: lastServerDiagnostics
                     };
                 }
                 applyMs += (Date.now() - applyStartedAtMs);
@@ -460,8 +499,10 @@ export async function runWorkspacePullSyncService(input) {
                         pulledDeleteTaskIds,
                         pulledActiveUpserts,
                         pulledArchivedUpserts,
+                        pulledTaskEventUpserts,
                         documentDecryptFailures: Array.from(documentDecryptFailures),
-                        emittedEventIds: Array.from(emittedEventIds)
+                        emittedEventIds: Array.from(emittedEventIds),
+                        serverDiagnostics: lastServerDiagnostics
                     };
                 }
                 const hasTransientApplyFailure = bootstrapApplyFailures.some((entry) => {
@@ -487,8 +528,10 @@ export async function runWorkspacePullSyncService(input) {
                     pulledDeleteTaskIds,
                     pulledActiveUpserts,
                     pulledArchivedUpserts,
+                    pulledTaskEventUpserts,
                     documentDecryptFailures: Array.from(documentDecryptFailures),
-                    emittedEventIds: Array.from(emittedEventIds)
+                    emittedEventIds: Array.from(emittedEventIds),
+                    serverDiagnostics: lastServerDiagnostics
                 };
             }
             applyMs += (Date.now() - bootstrapApplyStartedAtMs);
@@ -504,8 +547,10 @@ export async function runWorkspacePullSyncService(input) {
             pulledDeleteTaskIds,
             pulledActiveUpserts,
             pulledArchivedUpserts,
+            pulledTaskEventUpserts,
             documentDecryptFailures: Array.from(documentDecryptFailures),
-            emittedEventIds: Array.from(emittedEventIds)
+            emittedEventIds: Array.from(emittedEventIds),
+            serverDiagnostics: lastServerDiagnostics
         };
     }
     catch (error) {
@@ -523,8 +568,10 @@ export async function runWorkspacePullSyncService(input) {
             pulledDeleteTaskIds,
             pulledActiveUpserts,
             pulledArchivedUpserts,
+            pulledTaskEventUpserts,
             documentDecryptFailures: Array.from(documentDecryptFailures),
-            emittedEventIds: Array.from(emittedEventIds)
+            emittedEventIds: Array.from(emittedEventIds),
+            serverDiagnostics: null
         };
     }
 }

package/dist/sync/syncService.test.js

@@ -37,6 +37,7 @@ function buildPayload(overrides = {}) {
         currentAnnotatedAttachmentSessionIds: new Set(),
         deleteAnnotatedAttachmentSessionIds: new Set(),
         currentAnnotatedAttachmentSessionWatermarks: new Map(),
+        currentTaskEventWatermarks: new Map(),
         pushedWatermarks: new Map(),
         ...overrides
     };
@@ -500,6 +501,53 @@ describe('syncService', () => {
                     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('zero-change bootstrap pull (no changes, hasMore false) returns success true', async () => {
             vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
                 ok: true,

package/dist/sync/workspacePullFeed.d.ts

@@ -15,6 +15,17 @@ export interface WorkspacePullFeedResult {
     changes: EncodedWorkspaceSyncChange[];
     nextCursor: string | null;
     hasMore: boolean;
+    diagnostics: {
+        totalEntries: number;
+        pageEntries: number;
+        skippedHydrationEntries: number;
+        documentIndexCount: number;
+        assetIndexCount: number;
+        indexMs: number;
+        hydrationMs: number;
+        encodeMs: number;
+        buildMs: number;
+    };
 }
 export declare function buildWorkspacePullFeed(input: {
     core: SyncCore;