@taskforcehq/taskforce 0.3.305 → 0.3.306

package/dist/sync/syncFieldSemantics.js

@@ -0,0 +1,55 @@
+export function hasOwnSyncField(source, field) {
+    return Boolean(source) && typeof source === 'object' && Object.prototype.hasOwnProperty.call(source, field);
+}
+export function normalizeSyncOptionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+export function normalizeSyncNullableString(value) {
+    if (value === undefined || value === null)
+        return null;
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : null;
+}
+export function normalizeSyncOptionalId(value) {
+    return normalizeSyncOptionalString(value);
+}
+export function normalizeSyncNullableId(value) {
+    return normalizeSyncNullableString(value);
+}
+export function normalizeSyncNullableIsoString(value) {
+    return normalizeSyncNullableString(value);
+}
+export function normalizeSyncSameOriginAssetUrl(value) {
+    const normalized = normalizeSyncNullableString(value);
+    if (!normalized)
+        return null;
+    return normalized.startsWith('/api/taskforce/context/') ? normalized : null;
+}
+export function readSyncOptionalStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncOptionalString(source[field]);
+}
+export function readSyncNullableStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableString(source[field]);
+}
+export function readSyncNullableIdField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableId(source[field]);
+}
+export function readSyncNullableIsoStringField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncNullableIsoString(source[field]);
+}
+export function readSyncSameOriginAssetUrlField(source, field) {
+    if (!hasOwnSyncField(source, field))
+        return undefined;
+    return normalizeSyncSameOriginAssetUrl(source[field]);
+}

package/dist/sync/syncResourceAdapters.d.ts

@@ -0,0 +1,44 @@
+import type { TaskItem } from '../types.js';
+export interface SyncAiProfileLike {
+    id?: string | null;
+    workspaceId?: string | null;
+    profileToken?: string | null;
+    name?: string | null;
+    username?: string | null;
+    icon?: string | null;
+    color?: string | null;
+    avatarUrl?: string | null;
+    avatarSourceUrl?: string | null;
+    description?: string | null;
+    role?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    surfaceType?: string | null;
+    seatScope?: string | null;
+    providerMetadata?: Record<string, unknown> | null;
+    archivedAt?: string | null;
+    archivedBy?: string | null;
+    archivedReason?: string | null;
+    mergedIntoProfileId?: string | null;
+    rosterStateUpdatedAt?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    lastActiveAt?: string | null;
+}
+export interface SyncResourceAdapter<T> {
+    kind: string;
+    getId: (resource: T) => string;
+    getWatermark: (resource: T) => string;
+    getChangeKey: (resource: T) => string;
+}
+export interface SyncResourceBaselineState {
+    watermarks?: Map<string, string> | null;
+    changeKeys?: Map<string, string> | null;
+}
+export declare function getAiProfileSyncWatermark(profile: Partial<SyncAiProfileLike> | null | undefined): string;
+export declare function getAiProfileSyncChangeKey(profile: Partial<SyncAiProfileLike> | null | undefined): string;
+export declare const taskSyncResourceAdapter: SyncResourceAdapter<Partial<TaskItem> & {
+    isArchived?: boolean | null;
+}>;
+export declare const aiProfileSyncResourceAdapter: SyncResourceAdapter<Partial<SyncAiProfileLike>>;
+export declare function shouldSyncResource<T>(adapter: SyncResourceAdapter<T>, resource: T, baseline?: SyncResourceBaselineState | null): boolean;

package/dist/sync/syncResourceAdapters.js

@@ -0,0 +1,77 @@
+import { buildTaskSyncChangeKey } from './taskSyncChangeKey.js';
+import { normalizeSyncNullableIsoString, normalizeSyncNullableString, normalizeSyncOptionalId, normalizeSyncSameOriginAssetUrl, } from './syncFieldSemantics.js';
+function normalizeSyncTimestampMax(...values) {
+    return values.reduce((latest, value) => {
+        const normalized = normalizeSyncNullableIsoString(value) || '';
+        if (!latest)
+            return normalized;
+        if (!normalized)
+            return latest;
+        return normalized > latest ? normalized : latest;
+    }, '');
+}
+export function getAiProfileSyncWatermark(profile) {
+    const source = profile || {};
+    return normalizeSyncTimestampMax(source.createdAt, source.updatedAt, source.lastActiveAt, source.archivedAt, source.rosterStateUpdatedAt);
+}
+export function getAiProfileSyncChangeKey(profile) {
+    const source = profile || {};
+    return JSON.stringify({
+        id: String(source.id || '').trim(),
+        workspaceId: String(source.workspaceId || '').trim(),
+        profileToken: String(source.profileToken || '').trim(),
+        name: String(source.name || '').trim(),
+        username: String(source.username || '').trim(),
+        icon: String(source.icon || 'Bot').trim() || 'Bot',
+        color: String(source.color || '#8b5cf6').trim() || '#8b5cf6',
+        avatarUrl: normalizeSyncSameOriginAssetUrl(source.avatarUrl) || '',
+        avatarSourceUrl: normalizeSyncSameOriginAssetUrl(source.avatarSourceUrl) || '',
+        description: normalizeSyncNullableString(source.description) || '',
+        role: normalizeSyncNullableString(source.role) || '',
+        provider: normalizeSyncNullableString(source.provider) || '',
+        model: normalizeSyncNullableString(source.model) || '',
+        surfaceType: normalizeSyncNullableString(source.surfaceType) || '',
+        seatScope: normalizeSyncNullableString(source.seatScope) || '',
+        providerMetadata: source.providerMetadata && typeof source.providerMetadata === 'object' && !Array.isArray(source.providerMetadata)
+            ? source.providerMetadata
+            : null,
+        archivedAt: normalizeSyncNullableIsoString(source.archivedAt) || '',
+        archivedBy: normalizeSyncOptionalId(source.archivedBy) || '',
+        archivedReason: normalizeSyncNullableString(source.archivedReason) || '',
+        mergedIntoProfileId: normalizeSyncOptionalId(source.mergedIntoProfileId) || '',
+        rosterStateUpdatedAt: normalizeSyncNullableIsoString(source.rosterStateUpdatedAt) || '',
+        createdAt: normalizeSyncNullableIsoString(source.createdAt) || '',
+        updatedAt: normalizeSyncNullableIsoString(source.updatedAt) || '',
+        lastActiveAt: normalizeSyncNullableIsoString(source.lastActiveAt) || '',
+    });
+}
+export const taskSyncResourceAdapter = {
+    kind: 'task',
+    getId: (task) => String(task?.id || '').trim(),
+    getWatermark: (task) => String(task?.updatedAt || task?.createdAt || '').trim(),
+    getChangeKey: (task) => buildTaskSyncChangeKey(task, Boolean(task?.isArchived))
+};
+export const aiProfileSyncResourceAdapter = {
+    kind: 'ai-profile',
+    getId: (profile) => String(profile?.id || '').trim(),
+    getWatermark: (profile) => getAiProfileSyncWatermark(profile),
+    getChangeKey: (profile) => getAiProfileSyncChangeKey(profile)
+};
+export function shouldSyncResource(adapter, resource, baseline) {
+    const id = adapter.getId(resource);
+    if (!id)
+        return false;
+    const currentChangeKey = adapter.getChangeKey(resource);
+    const previousWatermarks = baseline?.watermarks;
+    if (!previousWatermarks || previousWatermarks.size === 0)
+        return true;
+    if (!previousWatermarks.has(id))
+        return true;
+    const previousChangeKeys = baseline?.changeKeys;
+    const previousChangeKey = previousChangeKeys?.get(id);
+    if (typeof previousChangeKey === 'string') {
+        return previousChangeKey !== currentChangeKey;
+    }
+    const previousWatermark = previousWatermarks.get(id) || '';
+    return previousWatermark !== currentChangeKey;
+}

package/dist/sync/syncService.d.ts

@@ -56,6 +56,8 @@ export interface WorkspacePushSyncResult {
     changeCount: number;
     deleteCount: number;
     currentTaskIds: Set<string>;
+    currentTaskWatermarks?: Map<string, string>;
+    currentTaskChangeKeys?: Map<string, string>;
     deleteTaskIds: Set<string>;
     currentInitiativeIds: Set<string>;
     currentInitiativeWatermarks: Map<string, string>;
@@ -63,6 +65,7 @@ export interface WorkspacePushSyncResult {
     currentWorkstreamWatermarks: Map<string, string>;
     currentAiProfileIds: Set<string>;
     currentAiProfileWatermarks: Map<string, string>;
+    currentAiProfileChangeKeys?: Map<string, string>;
     currentDocumentPaths: Set<string>;
     deleteDocumentPaths: Set<string>;
     currentDocumentWatermarks: Map<string, string>;
@@ -81,6 +84,7 @@ export interface WorkspacePushSyncResult {
     currentTaskEventWatermarks: Map<string, string>;
     /** Watermarks for every task upsert that was successfully pushed. */
     pushedWatermarks: Map<string, string>;
+    pushedTaskChangeKeys?: 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. */
@@ -106,6 +110,7 @@ export interface WorkspacePullSyncResult {
     success: boolean;
     kind?: WorkspacePullFailureKind;
     status?: number;
+    errorCode?: string;
     retryAfterMs?: number;
     transient?: boolean;
     failures?: string[];

package/dist/sync/syncService.js

@@ -15,6 +15,14 @@ function resolveWorkspaceAccessConflictMessage(data, fallbackStatus) {
     }
     return rawError || `Workspace provisioning failed (${fallbackStatus})`;
 }
+function isMissingCloudWorkspaceSelection(data, status) {
+    if (status !== 400)
+        return false;
+    const code = String(data.code || '').trim().toUpperCase();
+    const rawError = String(data.error || '').trim().toLowerCase();
+    return code === 'WORKSPACE_ID_REQUIRED'
+        && rawError.includes('no cloud workspace is selected');
+}
 export async function ensureCloudWorkspaceReadyForSyncService(input) {
     if (!input.cloudAuthConfigured)
         return { success: false, error: 'Cloud auth endpoint is not configured.' };
@@ -44,6 +52,39 @@ export async function ensureCloudWorkspaceReadyForSyncService(input) {
                 error: String(data.error || 'Workspace sync rate limited. Please retry later.')
             };
         }
+        if (isMissingCloudWorkspaceSelection(data, handshakeResult.status)) {
+            const provisionResult = await provisionWorkspace(input.resolveCloudAuthUrl, {
+                workspaceId: input.workspaceId,
+                name: input.workspaceName || input.workspaceId
+            });
+            if (!provisionResult.ok) {
+                const provisionError = asObjectRecord(provisionResult.data);
+                return {
+                    success: false,
+                    statusCode: provisionResult.status,
+                    transient: isTransientWorkspaceSyncStatus(provisionResult.status),
+                    retryAfterMs: provisionResult.retryAfterMs,
+                    error: resolveWorkspaceAccessConflictMessage(provisionError, provisionResult.status)
+                };
+            }
+            handshakeResult = await handshakeWorkspace(input.resolveCloudAuthUrl, input.workspaceId);
+            if (!handshakeResult.ok) {
+                const retryData = asObjectRecord(handshakeResult.data);
+                if (handshakeResult.status === 401) {
+                    return { success: false, statusCode: 401, transient: false, error: String(retryData.error || 'Authentication required for workspace sync.') };
+                }
+                if (handshakeResult.status === 429) {
+                    return { success: false, statusCode: 429, retryAfterMs: handshakeResult.retryAfterMs, transient: true, error: String(retryData.error || 'Workspace sync rate limited. Please retry later.') };
+                }
+                return {
+                    success: false,
+                    statusCode: handshakeResult.status,
+                    transient: isTransientWorkspaceSyncStatus(handshakeResult.status),
+                    error: String(retryData.error || `Workspace sync handshake failed (${handshakeResult.status})`)
+                };
+            }
+            return { success: true, provisioned: true };
+        }
         if (handshakeResult.status === 409 && data.code === 'WORKSPACE_ID_MISMATCH') {
             if (input.allowProvisionOnMismatch === false) {
                 return {
@@ -173,6 +214,8 @@ export async function runWorkspacePushSyncService(input) {
             changeCount,
             deleteCount,
             currentTaskIds: input.payload.currentTaskIds,
+            currentTaskWatermarks: input.payload.currentTaskWatermarks ?? new Map(),
+            currentTaskChangeKeys: input.payload.currentTaskChangeKeys ?? new Map(),
             deleteTaskIds: input.payload.deleteTaskIds,
             currentInitiativeIds: input.payload.currentInitiativeIds,
             currentInitiativeWatermarks: input.payload.currentInitiativeWatermarks,
@@ -180,6 +223,7 @@ export async function runWorkspacePushSyncService(input) {
             currentWorkstreamWatermarks: input.payload.currentWorkstreamWatermarks,
             currentAiProfileIds: input.payload.currentAiProfileIds,
             currentAiProfileWatermarks: input.payload.currentAiProfileWatermarks,
+            currentAiProfileChangeKeys: input.payload.currentAiProfileChangeKeys ?? new Map(),
             currentDocumentPaths: input.payload.currentDocumentPaths,
             deleteDocumentPaths: input.payload.deleteDocumentPaths,
             currentDocumentWatermarks: input.payload.currentDocumentWatermarks,
@@ -197,6 +241,7 @@ export async function runWorkspacePushSyncService(input) {
             currentAnnotatedAttachmentSessionWatermarks: input.payload.currentAnnotatedAttachmentSessionWatermarks,
             currentTaskEventWatermarks: input.payload.currentTaskEventWatermarks,
             pushedWatermarks: new Map(),
+            pushedTaskChangeKeys: new Map(),
             emittedEventIds: [],
             appliedTaskUpserts: []
         };
@@ -231,6 +276,8 @@ export async function runWorkspacePushSyncService(input) {
         changeCount,
         deleteCount,
         currentTaskIds: input.payload.currentTaskIds,
+        currentTaskWatermarks: input.payload.currentTaskWatermarks ?? new Map(),
+        currentTaskChangeKeys: input.payload.currentTaskChangeKeys ?? new Map(),
         deleteTaskIds: input.payload.deleteTaskIds,
         currentInitiativeIds: input.payload.currentInitiativeIds,
         currentInitiativeWatermarks: input.payload.currentInitiativeWatermarks,
@@ -238,6 +285,7 @@ export async function runWorkspacePushSyncService(input) {
         currentWorkstreamWatermarks: input.payload.currentWorkstreamWatermarks,
         currentAiProfileIds: input.payload.currentAiProfileIds,
         currentAiProfileWatermarks: input.payload.currentAiProfileWatermarks,
+        currentAiProfileChangeKeys: input.payload.currentAiProfileChangeKeys ?? new Map(),
         currentDocumentPaths: input.payload.currentDocumentPaths,
         deleteDocumentPaths: input.payload.deleteDocumentPaths,
         currentDocumentWatermarks: input.payload.currentDocumentWatermarks,
@@ -255,6 +303,7 @@ export async function runWorkspacePushSyncService(input) {
         currentAnnotatedAttachmentSessionWatermarks: input.payload.currentAnnotatedAttachmentSessionWatermarks,
         currentTaskEventWatermarks: input.payload.currentTaskEventWatermarks,
         pushedWatermarks: input.payload.pushedWatermarks,
+        pushedTaskChangeKeys: input.payload.pushedTaskChangeKeys ?? new Map(),
         emittedEventIds,
         appliedTaskUpserts
     };
@@ -296,10 +345,13 @@ export async function runWorkspacePullSyncService(input) {
                 }
             }
             if (!pullRes.ok) {
+                const pullErrorData = asObjectRecord(pullRes.data);
                 return {
                     success: false,
                     kind: 'pull_http',
                     status: pullRes.status,
+                    errorCode: typeof pullErrorData.code === 'string' ? pullErrorData.code : undefined,
+                    error: typeof pullErrorData.error === 'string' ? pullErrorData.error : undefined,
                     retryAfterMs: pullRes.retryAfterMs,
                     transient: isTransientWorkspaceSyncStatus(pullRes.status),
                     cursor,

package/dist/sync/syncService.test.js

@@ -443,7 +443,7 @@ describe('syncService', () => {
                 status: 200,
                 data: {
                     success: true,
-                    changes: [{ op: 'upsert', task: { id: 't-parent', title: 'Parent', status: 'done', updatedAt: '2026-03-15T20:27:08.000Z' } }],
+                    changes: [{ op: 'upsert', task: { id: 'task-apply-error', title: 'Apply error', status: 'done', updatedAt: '2026-03-15T20:27:08.000Z' } }],
                     nextCursor: null,
                     hasMore: false
                 }
@@ -452,7 +452,7 @@ describe('syncService', () => {
                 ok: false,
                 status: 400,
                 failures: ['/api/taskforce/sync/workspace/apply-local:400'],
-                data: { error: 'Parent tasks cannot be marked done manually; completion is derived from descendants' }
+                data: { error: 'Task apply rejected by local validation' }
             });
             const res = await runWorkspacePullSyncService({
                 resolveCloudAuthUrl: mockResolveCloudAuthUrl,
@@ -463,7 +463,7 @@ describe('syncService', () => {
             expect(res.success).toBe(false);
             expect(res.kind).toBe('apply_all_candidates');
             expect(res.status).toBe(400);
-            expect(res.error).toBe('Parent tasks cannot be marked done manually; completion is derived from descendants');
+            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;
@@ -702,6 +702,60 @@ describe('syncService', () => {
             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,

package/dist/sync/taskSyncChangeKey.d.ts

@@ -0,0 +1,2 @@
+import type { TaskItem } from '../types.js';
+export declare function buildTaskSyncChangeKey(task: Partial<TaskItem> | null | undefined, archivedValue: boolean): string;

package/dist/sync/taskSyncChangeKey.js

@@ -0,0 +1,143 @@
+import { serializeTaskForSync } from './taskSyncPayload.js';
+import { normalizeSyncNullableId, normalizeSyncNullableIsoString, normalizeSyncNullableString, normalizeSyncOptionalId, normalizeSyncOptionalString, } from './syncFieldSemantics.js';
+function normalizeConflictTaxonomies(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const entries = Object.entries(value)
+        .filter(([key]) => String(key || '').trim().length > 0)
+        .sort(([left], [right]) => left.localeCompare(right));
+    const normalized = {};
+    for (const [key, raw] of entries) {
+        if (Array.isArray(raw)) {
+            normalized[key] = raw.map((entry) => String(entry ?? '')).sort((left, right) => left.localeCompare(right));
+            continue;
+        }
+        if (raw === undefined || raw === null)
+            continue;
+        normalized[key] = String(raw);
+    }
+    return normalized;
+}
+function normalizeConflictChecklistItems(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => {
+        const entry = item && typeof item === 'object' ? item : {};
+        return {
+            id: String(entry.id || '').trim(),
+            title: String(entry.title || '').trim(),
+            isCompleted: Boolean(entry.isCompleted),
+            order: entry.order === undefined || entry.order === null ? '' : String(entry.order),
+        };
+    })
+        .sort((left, right) => {
+        const leftOrder = Number.parseInt(left.order, 10);
+        const rightOrder = Number.parseInt(right.order, 10);
+        if (Number.isFinite(leftOrder) && Number.isFinite(rightOrder) && leftOrder !== rightOrder) {
+            return leftOrder - rightOrder;
+        }
+        if (left.title !== right.title)
+            return left.title.localeCompare(right.title);
+        return left.id.localeCompare(right.id);
+    });
+}
+function normalizeSyncComments(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        const comment = entry && typeof entry === 'object' ? entry : null;
+        return {
+            id: String(comment?.id || '').trim(),
+            author: String(comment?.author || '').trim(),
+            submittedAuthor: normalizeSyncOptionalString(comment?.submittedAuthor) || '',
+            text: String(comment?.text || ''),
+            timestamp: normalizeSyncNullableIsoString(comment?.timestamp) || '',
+            actor: comment?.actor ?? null,
+        };
+    })
+        .sort((left, right) => {
+        if (left.timestamp !== right.timestamp)
+            return left.timestamp.localeCompare(right.timestamp);
+        if (left.id !== right.id)
+            return left.id.localeCompare(right.id);
+        if (left.author !== right.author)
+            return left.author.localeCompare(right.author);
+        return left.text.localeCompare(right.text);
+    });
+}
+function normalizeSyncAttachments(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        if (typeof entry === 'string') {
+            const path = entry.trim();
+            return {
+                path,
+                fsPath: '',
+                caption: '',
+                displayName: '',
+                originalFilename: '',
+                assetId: '',
+                referenceNumber: '',
+                taskId: '',
+                timestamp: '',
+            };
+        }
+        const attachment = entry && typeof entry === 'object' ? entry : null;
+        return {
+            path: String(attachment?.path || '').trim(),
+            fsPath: normalizeSyncOptionalString(attachment?.fsPath) || '',
+            caption: normalizeSyncOptionalString(attachment?.caption) || '',
+            displayName: normalizeSyncOptionalString(attachment?.displayName) || '',
+            originalFilename: normalizeSyncOptionalString(attachment?.originalFilename) || '',
+            assetId: normalizeSyncOptionalId(attachment?.assetId) || '',
+            referenceNumber: attachment?.referenceNumber === undefined || attachment.referenceNumber === null
+                ? ''
+                : String(attachment.referenceNumber),
+            taskId: normalizeSyncNullableId(attachment?.taskId) || '',
+            timestamp: normalizeSyncNullableIsoString(attachment?.timestamp) || '',
+        };
+    })
+        .sort((left, right) => {
+        if (left.path !== right.path)
+            return left.path.localeCompare(right.path);
+        if (left.assetId !== right.assetId)
+            return left.assetId.localeCompare(right.assetId);
+        if (left.timestamp !== right.timestamp)
+            return left.timestamp.localeCompare(right.timestamp);
+        return JSON.stringify(left).localeCompare(JSON.stringify(right));
+    });
+}
+export function buildTaskSyncChangeKey(task, archivedValue) {
+    const source = serializeTaskForSync(task);
+    return JSON.stringify({
+        id: source.id,
+        title: source.title,
+        description: normalizeSyncNullableString(source.description) || '',
+        category: source.category,
+        type: source.type,
+        priority: source.priority === undefined || source.priority === null ? '' : String(source.priority),
+        complexity: source.complexity === undefined || source.complexity === null ? '' : String(source.complexity),
+        status: source.status,
+        approach: normalizeSyncOptionalString(source.approach) || '',
+        canceledReason: normalizeSyncNullableString(source.canceledReason) || '',
+        createdAt: source.createdAt,
+        completedAt: normalizeSyncNullableIsoString(source.completedAt) || '',
+        taxonomies: normalizeConflictTaxonomies(source.taxonomies),
+        createdBy: normalizeSyncOptionalId(source.createdBy) || '',
+        assignee: normalizeSyncOptionalId(source.assignee) || '',
+        scheduledDate: normalizeSyncNullableString(source.scheduledDate) || '',
+        dueDate: normalizeSyncNullableString(source.dueDate) || '',
+        scheduledWeekKey: normalizeSyncNullableString(source.scheduledWeekKey) || '',
+        orderInDay: source.orderInDay === undefined || source.orderInDay === null ? '' : String(source.orderInDay),
+        workstreamId: normalizeSyncNullableId(source.workstreamId) || '',
+        referenceNumber: source.referenceNumber === undefined || source.referenceNumber === null ? '' : String(source.referenceNumber),
+        comments: normalizeSyncComments(source.comments),
+        attachments: normalizeSyncAttachments(source.attachments),
+        checklistItems: normalizeConflictChecklistItems(source.checklistItems),
+        isArchived: archivedValue ? '1' : '0'
+    });
+}

package/dist/sync/taskSyncPayload.js

@@ -1,16 +1,11 @@
+import { normalizeSyncNullableString, normalizeSyncOptionalString, } from './syncFieldSemantics.js';
 function toOptionalString(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    const normalized = String(value).trim();
-    return normalized.length > 0 ? normalized : undefined;
+    return normalizeSyncOptionalString(value);
 }
 function toNullableString(value) {
     if (value === undefined)
         return undefined;
-    if (value === null)
-        return null;
-    const normalized = String(value).trim();
-    return normalized.length > 0 ? normalized : null;
+    return normalizeSyncNullableString(value);
 }
 function toOptionalBoolean(value) {
     return typeof value === 'boolean' ? value : undefined;

package/dist/sync/workspacePullFeed.js

@@ -1,4 +1,5 @@
 import { serializeTaskForSync } from './taskSyncPayload.js';
+import { aiProfileSyncResourceAdapter, taskSyncResourceAdapter } from './syncResourceAdapters.js';
 export async function buildWorkspacePullFeed(input) {
     const buildStartedAtMs = Date.now();
     const { core, workspaceId, cursor, pageSize, encodeWorkspaceSyncCursor, contentSyncState, collaborationSyncState } = input;
@@ -7,7 +8,7 @@ export async function buildWorkspacePullFeed(input) {
     const taskRows = core.listTasksForSync(workspaceId, syncCursor, dbFetchLimit);
     const upsertEntries = taskRows
         .map((entry) => {
-        const watermark = String(entry.task?.updatedAt || entry.task?.createdAt || '').trim();
+        const watermark = taskSyncResourceAdapter.getWatermark(entry.task);
         const taskId = String(entry.task?.id || '').trim();
         return {
             kind: 'upsert',
@@ -55,10 +56,10 @@ export async function buildWorkspacePullFeed(input) {
         workstream
     }))
         .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.workstream.id.length > 0);
-    const aiProfileEntries = core.listAiProfiles(workspaceId)
+    const aiProfileEntries = core.listAiProfiles(workspaceId, { includeArchived: true })
         .map((profile) => ({
         kind: 'ai-profile',
-        watermark: String(profile.updatedAt || profile.createdAt || '').trim(),
+        watermark: aiProfileSyncResourceAdapter.getWatermark(profile),
         sortId: `ai-profile:${String(profile.id || '').trim()}`,
         profile
     }))

package/dist/sync/workspacePullFeed.test.js

@@ -126,6 +126,7 @@ describe('workspacePullFeed', () => {
                 userId: 'user-1',
                 email: 'person@example.com',
                 displayName: 'Person',
+                avatarUrl: '/api/taskforce/context/users%2Fuser-1%2Fprofile%2Favatar%2Fheadshot.webp',
                 role: 'owner',
                 permissionMode: 'read-write',
                 betaAccess: true,
@@ -167,6 +168,48 @@ describe('workspacePullFeed', () => {
                 displayName: 'Person',
             })
         ]);
+        expect(result.workspaceMembers[0]).not.toHaveProperty('avatarUrl');
+    });
+    it('includes ai-profile upserts with avatar fields in the pull feed', async () => {
+        const core = createCoreMock();
+        core.listAiProfiles = () => [
+            {
+                id: 'ai-profile-1',
+                workspaceId: 'workspace-1',
+                profileToken: 'tfp_test',
+                name: 'Codex',
+                username: 'codex',
+                icon: 'Bot',
+                color: '#0ea5e9',
+                avatarUrl: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fai-profiles%2Fai-profile-1%2Favatar%2Favatar.webp',
+                avatarSourceUrl: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fai-profiles%2Fai-profile-1%2Favatar%2Fsource.webp',
+                createdAt: '2026-04-10T10:00:00.000Z',
+                updatedAt: '2026-04-10T10:05:00.000Z',
+                lastActiveAt: '2026-04-10T10:05:00.000Z'
+            }
+        ];
+        const result = await buildWorkspacePullFeed({
+            core,
+            workspaceId: 'workspace-1',
+            cursor: null,
+            pageSize: 10,
+            encodeWorkspaceSyncCursor: encodeCursor,
+            contentSyncState: createContentSyncStateMock(),
+            collaborationSyncState: createCollaborationSyncStateMock(),
+        });
+        expect(result.changes).toEqual([
+            expect.objectContaining({
+                op: 'ai-profile-upsert',
+                watermark: '2026-04-10T10:05:00.000Z',
+                profile: expect.objectContaining({
+                    id: 'ai-profile-1',
+                    avatarUrl: expect.stringContaining('/api/taskforce/context/'),
+                    avatarSourceUrl: expect.stringContaining('/api/taskforce/context/')
+                })
+            })
+        ]);
+        expect(result.nextCursor).toBe('2026-04-10T10:05:00.000Z|ai-profile:ai-profile-1');
+        expect(result.hasMore).toBe(false);
     });
     it('hydrates document and asset payloads only for entries included in the current page', async () => {
         const core = createCoreMock();