@taskforcehq/taskforce 0.3.300 → 0.3.302

package/dist/sync/workspacePullFeed.d.ts

@@ -0,0 +1,28 @@
+import type { TaskforceCore, TaskforceSyncCapable } from '../core/Taskforce.js';
+import type { WorkspaceSyncChange, WorkspaceSyncWorkspaceMemberSnapshot } from './workspaceSyncModel.js';
+import { createCollaborationSyncState } from './collaborationSyncState.js';
+import { createContentSyncState } from './contentSyncState.js';
+type SyncCore = TaskforceCore & TaskforceSyncCapable;
+export interface WorkspaceSyncCursorValue {
+    u: string;
+    id: string;
+}
+type EncodedWorkspaceSyncChange = WorkspaceSyncChange & {
+    watermark: string;
+};
+export interface WorkspacePullFeedResult {
+    workspaceMembers: WorkspaceSyncWorkspaceMemberSnapshot[];
+    changes: EncodedWorkspaceSyncChange[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+export declare function buildWorkspacePullFeed(input: {
+    core: SyncCore;
+    workspaceId: string;
+    cursor: WorkspaceSyncCursorValue | null;
+    pageSize: number;
+    encodeWorkspaceSyncCursor: (cursor: WorkspaceSyncCursorValue | null) => string | null;
+    contentSyncState: ReturnType<typeof createContentSyncState>;
+    collaborationSyncState: ReturnType<typeof createCollaborationSyncState>;
+}): Promise<WorkspacePullFeedResult>;
+export {};

package/dist/sync/workspacePullFeed.js

@@ -0,0 +1,301 @@
+import { serializeTaskForSync } from './taskSyncPayload.js';
+export async function buildWorkspacePullFeed(input) {
+    const { core, workspaceId, cursor, pageSize, encodeWorkspaceSyncCursor, contentSyncState, collaborationSyncState } = input;
+    const syncCursor = cursor ? { watermark: cursor.u, id: cursor.id } : null;
+    const dbFetchLimit = pageSize * 2 + 10;
+    const taskRows = core.listTasksForSync(workspaceId, syncCursor, dbFetchLimit);
+    const upsertEntries = taskRows
+        .map((entry) => {
+        const watermark = String(entry.task?.updatedAt || entry.task?.createdAt || '').trim();
+        const taskId = String(entry.task?.id || '').trim();
+        return {
+            kind: 'upsert',
+            watermark,
+            sortId: taskId,
+            task: serializeTaskForSync(entry.task),
+            archived: Boolean(entry.archived)
+        };
+    })
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
+    const rawDeleteEntries = core.listWorkspaceSyncDeletesSince(workspaceId, syncCursor, dbFetchLimit);
+    const deleteEntries = rawDeleteEntries
+        .map((entry) => ({
+        kind: 'delete',
+        watermark: String(entry.deletedAt || '').trim(),
+        sortId: String(entry.taskId || '').trim(),
+        taskId: String(entry.taskId || '').trim()
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
+    const taxonomySnapshot = core.getTaxonomiesSyncSnapshot(workspaceId);
+    const taxonomyEntries = (taxonomySnapshot
+        && Array.isArray(taxonomySnapshot.taxonomies)
+        && Number.isFinite(Date.parse(String(taxonomySnapshot.updatedAt || '').trim())))
+        ? [{
+                kind: 'taxonomy',
+                watermark: String(taxonomySnapshot.updatedAt || '').trim(),
+                sortId: '__taxonomy_config__',
+                taxonomies: taxonomySnapshot.taxonomies,
+                ...(taxonomySnapshot.taxonomyState ? { taxonomyState: taxonomySnapshot.taxonomyState } : {})
+            }]
+        : [];
+    const initiativeEntries = core.listInitiatives(workspaceId)
+        .map((initiative) => ({
+        kind: 'initiative',
+        watermark: String(initiative.updatedAt || initiative.createdAt || '').trim(),
+        sortId: `initiative:${String(initiative.id || '').trim()}`,
+        initiative
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.initiative.id.length > 0);
+    const workstreamEntries = core.listWorkstreams(workspaceId)
+        .map((workstream) => ({
+        kind: 'workstream',
+        watermark: String(workstream.updatedAt || workstream.createdAt || '').trim(),
+        sortId: `workstream:${String(workstream.id || '').trim()}`,
+        workstream
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.workstream.id.length > 0);
+    const aiProfileEntries = core.listAiProfiles(workspaceId)
+        .map((profile) => ({
+        kind: 'ai-profile',
+        watermark: String(profile.updatedAt || profile.createdAt || '').trim(),
+        sortId: `ai-profile:${String(profile.id || '').trim()}`,
+        profile
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
+    const documentEntries = (await contentSyncState.listWorkspaceSyncDocumentsSnapshot(core.getPaths().basePath, workspaceId))
+        .map((doc) => ({
+        kind: 'document',
+        watermark: String(doc.updatedAt || '').trim(),
+        sortId: `doc:${String(doc.path || '').trim()}`,
+        path: String(doc.path || '').trim(),
+        content: String(doc.content || ''),
+        assetId: doc.assetId,
+        documentId: doc.documentId,
+        referenceNumber: doc.referenceNumber,
+        version: doc.version,
+        taskId: doc.taskId,
+        logicalName: doc.logicalName,
+        caption: doc.caption,
+        originalFilename: doc.originalFilename,
+        linkRole: (doc.linkRole === 'reference' ? 'reference' : 'attachment')
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
+    const documentDeleteEntries = contentSyncState.listWorkspaceSyncDocumentDeletesSnapshot(workspaceId)
+        .map((doc) => ({
+        kind: 'document-delete',
+        watermark: String(doc.deletedAt || '').trim(),
+        sortId: `doc-delete:${String(doc.path || '').trim()}:${String(doc.assetId || '').trim()}`,
+        path: String(doc.path || '').trim(),
+        assetId: typeof doc.assetId === 'string' && doc.assetId.trim().length > 0 ? doc.assetId.trim() : undefined
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
+    const documentReviewSessions = collaborationSyncState.listWorkspaceSyncDocumentReviewSessionsSnapshot(workspaceId);
+    const documentReviewSessionEntries = documentReviewSessions
+        .filter((session) => !session.deletedAt)
+        .map((session) => ({
+        kind: 'document-review-session',
+        watermark: String(session.updatedAt || session.createdAt || '').trim(),
+        sortId: `document-review-session:${String(session.id || '').trim()}`,
+        session
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.session.id.length > 0 && entry.session.assetId.length > 0);
+    const documentReviewSessionDeleteEntries = documentReviewSessions
+        .filter((session) => typeof session.deletedAt === 'string' && session.deletedAt.trim().length > 0)
+        .map((session) => ({
+        kind: 'document-review-session-delete',
+        watermark: String(session.deletedAt || session.updatedAt || '').trim(),
+        sortId: `document-review-session-delete:${String(session.id || '').trim()}`,
+        sessionId: String(session.id || '').trim()
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sessionId.length > 0);
+    const documentReviewComments = collaborationSyncState.listWorkspaceSyncDocumentReviewCommentsSnapshot(workspaceId);
+    const documentReviewCommentEntries = documentReviewComments
+        .filter((comment) => !comment.deletedAt)
+        .map((comment) => ({
+        kind: 'document-review-comment',
+        watermark: String(comment.updatedAt || comment.createdAt || '').trim(),
+        sortId: `document-review-comment:${String(comment.id || '').trim()}`,
+        comment
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.comment.id.length > 0 && entry.comment.sessionId.length > 0);
+    const documentReviewCommentDeleteEntries = documentReviewComments
+        .filter((comment) => typeof comment.deletedAt === 'string' && comment.deletedAt.trim().length > 0)
+        .map((comment) => ({
+        kind: 'document-review-comment-delete',
+        watermark: String(comment.deletedAt || comment.updatedAt || '').trim(),
+        sortId: `document-review-comment-delete:${String(comment.id || '').trim()}`,
+        commentId: String(comment.id || '').trim()
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.commentId.length > 0);
+    const annotatedAttachmentSessions = collaborationSyncState.listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(workspaceId);
+    const annotatedAttachmentSessionEntries = annotatedAttachmentSessions
+        .filter((session) => !session.deletedAt)
+        .map((session) => ({
+        kind: 'annotated-attachment-session',
+        watermark: String(session.updatedAt || session.createdAt || '').trim(),
+        sortId: `annotated-attachment-session:${String(session.id || '').trim()}`,
+        session
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.session.id.length > 0 && entry.session.baseImageAssetId.length > 0);
+    const annotatedAttachmentSessionDeleteEntries = annotatedAttachmentSessions
+        .filter((session) => typeof session.deletedAt === 'string' && session.deletedAt.trim().length > 0)
+        .map((session) => ({
+        kind: 'annotated-attachment-session-delete',
+        watermark: String(session.deletedAt || session.updatedAt || '').trim(),
+        sortId: `annotated-attachment-session-delete:${String(session.id || '').trim()}`,
+        sessionId: String(session.id || '').trim()
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sessionId.length > 0);
+    const assetEntries = (await contentSyncState.listWorkspaceSyncBinaryAssetsSnapshot(core.getPaths().basePath, workspaceId))
+        .map((asset) => ({
+        kind: 'asset',
+        watermark: String(asset.updatedAt || '').trim(),
+        sortId: `asset:${String(asset.path || '').trim()}`,
+        path: String(asset.path || '').trim(),
+        contentBase64: String(asset.contentBase64 || ''),
+        assetId: asset.assetId,
+        kindValue: asset.kind,
+        mimeType: asset.mimeType,
+        referenceNumber: asset.referenceNumber,
+        taskId: asset.taskId,
+        logicalName: asset.logicalName,
+        caption: asset.caption,
+        originalFilename: asset.originalFilename,
+        linkRole: asset.linkRole
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0 && entry.contentBase64.length > 0);
+    const assetDeleteEntries = contentSyncState.listWorkspaceSyncBinaryAssetDeletesSnapshot(workspaceId)
+        .map((asset) => ({
+        kind: 'asset-delete',
+        watermark: String(asset.deletedAt || '').trim(),
+        sortId: `asset-delete:${String(asset.path || '').trim()}:${String(asset.assetId || '').trim()}`,
+        path: String(asset.path || '').trim(),
+        assetId: typeof asset.assetId === 'string' && asset.assetId.trim().length > 0 ? asset.assetId.trim() : undefined
+    }))
+        .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
+    const all = [
+        ...upsertEntries,
+        ...deleteEntries,
+        ...taxonomyEntries,
+        ...initiativeEntries,
+        ...workstreamEntries,
+        ...aiProfileEntries,
+        ...documentEntries,
+        ...documentDeleteEntries,
+        ...documentReviewSessionEntries,
+        ...documentReviewSessionDeleteEntries,
+        ...documentReviewCommentEntries,
+        ...documentReviewCommentDeleteEntries,
+        ...annotatedAttachmentSessionEntries,
+        ...annotatedAttachmentSessionDeleteEntries,
+        ...assetEntries,
+        ...assetDeleteEntries
+    ];
+    const afterCursor = all.filter((entry) => {
+        if (!cursor)
+            return true;
+        if (entry.watermark > cursor.u)
+            return true;
+        if (entry.watermark < cursor.u)
+            return false;
+        return entry.sortId > cursor.id;
+    });
+    afterCursor.sort((a, b) => {
+        if (a.watermark !== b.watermark)
+            return a.watermark.localeCompare(b.watermark);
+        return String(a.sortId || '').localeCompare(String(b.sortId || ''));
+    });
+    const page = afterCursor.slice(0, pageSize);
+    const hasMore = afterCursor.length > pageSize;
+    const last = page.length > 0 ? page[page.length - 1] : null;
+    const nextCursor = encodeWorkspaceSyncCursor(last
+        ? { u: last.watermark, id: String(last.sortId || '') }
+        : cursor);
+    const workspaceMembers = core.listWorkspaceUsers(workspaceId).map((member) => ({
+        userId: member.userId,
+        workspaceId,
+        email: member.email,
+        displayName: member.displayName || null,
+        role: member.role,
+        permissionMode: member.permissionMode,
+        betaAccess: member.betaAccess,
+        status: member.status,
+        disabled: member.disabled,
+        createdAt: member.createdAt || null,
+        updatedAt: member.updatedAt || null,
+        emailVerifiedAt: member.emailVerifiedAt || null
+    }));
+    const changes = page.map((entry) => (entry.kind === 'delete'
+        ? { op: 'delete', taskId: entry.taskId, deletedAt: entry.watermark, watermark: entry.watermark }
+        : entry.kind === 'taxonomy'
+            ? {
+                op: 'taxonomy-upsert',
+                taxonomies: entry.taxonomies,
+                ...(entry.taxonomyState ? { taxonomyState: entry.taxonomyState } : {}),
+                updatedAt: entry.watermark,
+                watermark: entry.watermark
+            }
+            : entry.kind === 'initiative'
+                ? { op: 'initiative-upsert', initiative: entry.initiative, updatedAt: entry.watermark, watermark: entry.watermark }
+                : entry.kind === 'workstream'
+                    ? { op: 'workstream-upsert', workstream: entry.workstream, updatedAt: entry.watermark, watermark: entry.watermark }
+                    : entry.kind === 'ai-profile'
+                        ? { op: 'ai-profile-upsert', profile: entry.profile, updatedAt: entry.watermark, watermark: entry.watermark }
+                        : entry.kind === 'document-review-session'
+                            ? { op: 'document-review-session-upsert', session: entry.session, updatedAt: entry.watermark, watermark: entry.watermark }
+                            : entry.kind === 'document-review-session-delete'
+                                ? { op: 'document-review-session-delete', sessionId: entry.sessionId, deletedAt: entry.watermark, watermark: entry.watermark }
+                                : entry.kind === 'document-review-comment'
+                                    ? { op: 'document-review-comment-upsert', comment: entry.comment, updatedAt: entry.watermark, watermark: entry.watermark }
+                                    : entry.kind === 'document-review-comment-delete'
+                                        ? { op: 'document-review-comment-delete', commentId: entry.commentId, deletedAt: entry.watermark, watermark: entry.watermark }
+                                        : entry.kind === 'annotated-attachment-session'
+                                            ? { op: 'annotated-attachment-session-upsert', session: entry.session, updatedAt: entry.watermark, watermark: entry.watermark }
+                                            : entry.kind === 'annotated-attachment-session-delete'
+                                                ? { op: 'annotated-attachment-session-delete', sessionId: entry.sessionId, deletedAt: entry.watermark, watermark: entry.watermark }
+                                                : entry.kind === 'document'
+                                                    ? {
+                                                        op: 'document-upsert',
+                                                        path: entry.path,
+                                                        updatedAt: entry.watermark,
+                                                        content: entry.content,
+                                                        assetId: entry.assetId,
+                                                        documentId: entry.documentId,
+                                                        referenceNumber: entry.referenceNumber,
+                                                        version: entry.version,
+                                                        taskId: entry.taskId,
+                                                        logicalName: entry.logicalName,
+                                                        caption: entry.caption,
+                                                        originalFilename: entry.originalFilename,
+                                                        linkRole: entry.linkRole,
+                                                        watermark: entry.watermark
+                                                    }
+                                                    : entry.kind === 'document-delete'
+                                                        ? { op: 'document-delete', path: entry.path, assetId: entry.assetId, deletedAt: entry.watermark, watermark: entry.watermark }
+                                                        : entry.kind === 'asset'
+                                                            ? {
+                                                                op: 'asset-upsert',
+                                                                path: entry.path,
+                                                                updatedAt: entry.watermark,
+                                                                contentBase64: entry.contentBase64,
+                                                                assetId: entry.assetId,
+                                                                kind: entry.kindValue,
+                                                                mimeType: entry.mimeType,
+                                                                referenceNumber: entry.referenceNumber,
+                                                                taskId: entry.taskId,
+                                                                logicalName: entry.logicalName,
+                                                                caption: entry.caption,
+                                                                originalFilename: entry.originalFilename,
+                                                                linkRole: entry.linkRole,
+                                                                watermark: entry.watermark
+                                                            }
+                                                            : entry.kind === 'asset-delete'
+                                                                ? { op: 'asset-delete', path: entry.path, assetId: entry.assetId, deletedAt: entry.watermark, watermark: entry.watermark }
+                                                                : { op: 'upsert', task: entry.task, archived: Boolean(entry.archived), watermark: entry.watermark }));
+    return {
+        workspaceMembers,
+        changes,
+        nextCursor,
+        hasMore
+    };
+}

package/dist/sync/workspacePullFeed.test.d.ts

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

package/dist/sync/workspacePullFeed.test.js

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest';
+import { buildWorkspacePullFeed } from './workspacePullFeed';
+function createCoreMock() {
+    return {
+        getPaths: () => ({ basePath: '/tmp/taskforce-test' }),
+        listTasksForSync: () => [],
+        listWorkspaceSyncDeletesSince: () => [],
+        getTaxonomiesSyncSnapshot: () => null,
+        listInitiatives: () => [],
+        listWorkstreams: () => [],
+        listAiProfiles: () => [],
+        listWorkspaceUsers: () => [],
+    };
+}
+function createContentSyncStateMock() {
+    return {
+        listWorkspaceSyncDocumentsSnapshot: async () => [],
+        listWorkspaceSyncDocumentDeletesSnapshot: () => [],
+        listWorkspaceSyncBinaryAssetsSnapshot: async () => [],
+        listWorkspaceSyncBinaryAssetDeletesSnapshot: () => [],
+    };
+}
+function createCollaborationSyncStateMock() {
+    return {
+        listWorkspaceSyncDocumentReviewSessionsSnapshot: () => [],
+        listWorkspaceSyncDocumentReviewCommentsSnapshot: () => [],
+        listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot: () => [],
+    };
+}
+function encodeCursor(cursor) {
+    return cursor ? `${cursor.u}|${cursor.id}` : null;
+}
+describe('workspacePullFeed', () => {
+    it('sorts entries by watermark and sort id, then paginates deterministically', async () => {
+        const core = createCoreMock();
+        core.listTasksForSync = () => [
+            {
+                archived: false,
+                task: {
+                    id: 'b-task',
+                    title: 'Task B',
+                    status: 'task',
+                    category: 'general',
+                    type: 'task',
+                    createdAt: '2026-04-10T10:00:00.000Z',
+                }
+            },
+            {
+                archived: false,
+                task: {
+                    id: 'a-task',
+                    title: 'Task A',
+                    status: 'task',
+                    category: 'general',
+                    type: 'task',
+                    createdAt: '2026-04-10T10:00:00.000Z',
+                }
+            },
+            {
+                archived: false,
+                task: {
+                    id: 'c-task',
+                    title: 'Task C',
+                    status: 'task',
+                    category: 'general',
+                    type: 'task',
+                    createdAt: '2026-04-11T10:00:00.000Z',
+                }
+            },
+        ];
+        const result = await buildWorkspacePullFeed({
+            core,
+            workspaceId: 'workspace-1',
+            cursor: null,
+            pageSize: 2,
+            encodeWorkspaceSyncCursor: encodeCursor,
+            contentSyncState: createContentSyncStateMock(),
+            collaborationSyncState: createCollaborationSyncStateMock(),
+        });
+        expect(result.changes).toHaveLength(2);
+        expect(result.changes[0]).toEqual(expect.objectContaining({
+            op: 'upsert',
+            watermark: '2026-04-10T10:00:00.000Z',
+            task: expect.objectContaining({ id: 'a-task' }),
+        }));
+        expect(result.changes[1]).toEqual(expect.objectContaining({
+            op: 'upsert',
+            watermark: '2026-04-10T10:00:00.000Z',
+            task: expect.objectContaining({ id: 'b-task' }),
+        }));
+        expect(result.nextCursor).toBe('2026-04-10T10:00:00.000Z|b-task');
+        expect(result.hasMore).toBe(true);
+    });
+    it('resumes strictly after the cursor and preserves workspace member snapshots', async () => {
+        const core = createCoreMock();
+        core.listTasksForSync = () => [
+            {
+                archived: false,
+                task: {
+                    id: 'z-task',
+                    title: 'Carry task',
+                    status: 'review',
+                    category: 'general',
+                    type: 'task',
+                    createdAt: '2026-04-10T10:00:00.000Z',
+                }
+            }
+        ];
+        core.listWorkspaceSyncDeletesSince = () => [
+            {
+                taskId: 'delete-task',
+                deletedAt: '2026-04-10T10:00:00.000Z',
+            },
+            {
+                taskId: 'later-delete',
+                deletedAt: '2026-04-11T09:00:00.000Z',
+            }
+        ];
+        core.listWorkspaceUsers = () => [
+            {
+                userId: 'user-1',
+                email: 'person@example.com',
+                displayName: 'Person',
+                role: 'owner',
+                permissionMode: 'read-write',
+                betaAccess: true,
+                status: 'active',
+                disabled: false,
+                createdAt: '2026-04-01T00:00:00.000Z',
+                updatedAt: '2026-04-02T00:00:00.000Z',
+                emailVerifiedAt: '2026-04-03T00:00:00.000Z',
+            }
+        ];
+        const result = await buildWorkspacePullFeed({
+            core,
+            workspaceId: 'workspace-2',
+            cursor: { u: '2026-04-10T10:00:00.000Z', id: 'delete-task' },
+            pageSize: 10,
+            encodeWorkspaceSyncCursor: encodeCursor,
+            contentSyncState: createContentSyncStateMock(),
+            collaborationSyncState: createCollaborationSyncStateMock(),
+        });
+        expect(result.changes).toEqual([
+            expect.objectContaining({
+                op: 'upsert',
+                watermark: '2026-04-10T10:00:00.000Z',
+                task: expect.objectContaining({ id: 'z-task' }),
+            }),
+            expect.objectContaining({
+                op: 'delete',
+                taskId: 'later-delete',
+                watermark: '2026-04-11T09:00:00.000Z',
+            }),
+        ]);
+        expect(result.hasMore).toBe(false);
+        expect(result.nextCursor).toBe('2026-04-11T09:00:00.000Z|later-delete');
+        expect(result.workspaceMembers).toEqual([
+            expect.objectContaining({
+                userId: 'user-1',
+                workspaceId: 'workspace-2',
+                email: 'person@example.com',
+                displayName: 'Person',
+            })
+        ]);
+    });
+});

package/dist/sync/workspaceSyncModel.d.ts

@@ -3,6 +3,8 @@ import type { DocumentReviewCommentRecord, DocumentReviewSessionStatus } from '.
 import type { AnnotatedAttachmentAnnotation } from '../annotatedAttachments/types.js';
 import type { WorkspaceTaxonomyState } from '../shared/taxonomyState.js';
 import { type AiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
+import { type TaskSyncPayload } from './taskSyncPayload.js';
+export type WorkspaceSyncTaskSnapshot = TaskSyncPayload;
 export interface WorkspaceSyncAiProfileSnapshot {
     id: string;
     workspaceId: string;
@@ -98,7 +100,7 @@ export interface WorkspaceSyncWorkstreamSnapshot {
 export type WorkspaceSyncChange = {
     op: 'upsert';
     archived: boolean;
-    task: TaskItem;
+    task: WorkspaceSyncTaskSnapshot;
 } | {
     op: 'delete';
     taskId: string;
@@ -204,6 +206,7 @@ export interface WorkspaceSyncPayload {
     /** Watermarks for every task upsert included in this payload (id → updatedAt|createdAt). */
     pushedWatermarks: Map<string, string>;
 }
+export declare function toWorkspaceSyncTaskSnapshot(task: TaskItem): WorkspaceSyncTaskSnapshot;
 export interface WorkspaceSyncDocumentSnapshot {
     path: string;
     updatedAt: string;

package/dist/sync/workspaceSyncModel.js

@@ -1,4 +1,8 @@
 import { parseAiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
+import { serializeTaskForSync } from './taskSyncPayload.js';
+export function toWorkspaceSyncTaskSnapshot(task) {
+    return serializeTaskForSync(task);
+}
 function sortTasksForSync(tasks) {
     return [...tasks].sort((left, right) => {
         const leftId = String(left?.id || '').trim();
@@ -13,6 +17,9 @@ export function buildWorkspaceSyncPayloadModel(input) {
         .filter((taskId) => taskId.length > 0));
     const lastWatermarks = input.lastPushedWatermarks;
     const isDirty = (task) => {
+        if ((task?.referenceNumber === undefined || task?.referenceNumber === null) && Number.isFinite(Number(task?.localReferenceNumber))) {
+            return true;
+        }
         if (!lastWatermarks || lastWatermarks.size === 0)
             return true;
         const taskId = String(task?.id || '').trim();
@@ -31,7 +38,7 @@ export function buildWorkspaceSyncPayloadModel(input) {
         const wm = String(task?.updatedAt || task?.createdAt || '').trim();
         if (taskId)
             pushedWatermarks.set(taskId, wm);
-        return { op: 'upsert', archived: false, task };
+        return { op: 'upsert', archived: false, task: toWorkspaceSyncTaskSnapshot(task) };
     });
     const archivedChanges = archivedTasksOrdered
         .filter((task) => !pendingDeleteIds.has(String(task?.id || '').trim()) && isDirty(task))
@@ -40,7 +47,7 @@ export function buildWorkspaceSyncPayloadModel(input) {
         const wm = String(task?.updatedAt || task?.createdAt || '').trim();
         if (taskId)
             pushedWatermarks.set(taskId, wm);
-        return { op: 'upsert', archived: true, task };
+        return { op: 'upsert', archived: true, task: toWorkspaceSyncTaskSnapshot(task) };
     });
     const currentTaskIds = new Set();
     for (const task of input.tasks || []) {

package/dist/sync/workspaceSyncModel.test.js

@@ -711,5 +711,34 @@ describe('workspaceSyncModel', () => {
             ]));
             expect(payload.pushedWatermarks.get('task-1')).toBe('2026-03-16T10:05:00.000Z');
         });
+        it('keeps provisional local-reference tasks dirty until a canonical reference is assigned', () => {
+            const payload = buildWorkspaceSyncPayloadModel({
+                tasks: [{
+                        id: 'task-provisional-1',
+                        title: 'Offline draft',
+                        status: 'task',
+                        createdAt: '2026-03-16T10:00:00.000Z',
+                        updatedAt: '2026-03-16T10:05:00.000Z',
+                        referenceNumber: null,
+                        localReferenceNumber: 3
+                    }],
+                archivedTasks: [],
+                lastPushedTaskIds: new Set(['task-provisional-1']),
+                pendingDeletedTaskIds: new Set(),
+                lastPushedWatermarks: new Map([
+                    ['task-provisional-1', '2026-03-16T10:05:00.000Z']
+                ])
+            });
+            expect(payload.changes).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    op: 'upsert',
+                    archived: false,
+                    task: expect.objectContaining({
+                        id: 'task-provisional-1',
+                        referenceNumber: null
+                    })
+                })
+            ]));
+        });
     });
 });

package/dist/test/setup.js

@@ -6,7 +6,7 @@ import os from 'os';
 import path from 'path';
 // Ensure all tests write global settings to a writable temp home.
 const testHome = path.join(os.tmpdir(), 'taskforce-vitest-home');
-fs.mkdirSync(path.join(testHome, '.tasknexus'), { recursive: true });
+fs.mkdirSync(path.join(testHome, '.taskforce'), { recursive: true });
 process.env.HOME = testHome;
 process.env.USERPROFILE = testHome;
 // Cleanup after each test case (e.g. clearing jsdom)

package/dist/types.d.ts

@@ -163,6 +163,7 @@ export interface ChecklistItem {
 export interface TaskItem {
     id: string;
     referenceNumber?: number | null;
+    localReferenceNumber?: number | null;
     referenceLabel?: string;
     title: string;
     description: string | null;