@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/hooks/sync/lifecyclePolicy.test.js

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import { resolveWorkspaceAutomaticPullPolicy, resolveWorkspaceSyncPresentation, shouldRunWorkspaceStartupRepair, shouldScheduleWorkspaceReactivePush, shouldStartWorkspacePeriodicFullReconcile, shouldStartWorkspacePushWatchdog, } from './lifecyclePolicy';
+const makeLifecycleBaseArgs = () => ({
+    cloudAuthConfigured: true,
+    runtimeMode: 'local',
+    workspaceCloudSyncEnabled: true,
+    authSessionResolved: true
+});
+describe('sync lifecycle policy', () => {
+    it('reports bootstrap phases as syncing with phase-specific guidance', () => {
+        expect(resolveWorkspaceSyncPresentation({
+            enabled: true,
+            phase: 'attach-cloud',
+            busy: false,
+            retryAt: null,
+            lastErrorMessage: null
+        })).toEqual({
+            status: 'syncing',
+            summary: 'Waiting for the first cloud pull into this device.',
+            recommendedAction: 'Keep this window open for the first cloud pull. If it does not move, press Repair.'
+        });
+    });
+    it('reports retry state as attention even when sync is otherwise idle', () => {
+        expect(resolveWorkspaceSyncPresentation({
+            enabled: true,
+            phase: 'active',
+            busy: false,
+            retryAt: '2026-04-18T16:00:00.000Z',
+            lastErrorMessage: null
+        })).toEqual({
+            status: 'attention',
+            summary: 'Sync hit a temporary problem and will retry automatically.',
+            recommendedAction: 'Wait for the automatic retry, or press Sync to retry now.'
+        });
+    });
+    it('allows reactive push only after bootstrap and reference snapshots are ready', () => {
+        expect(shouldScheduleWorkspaceReactivePush({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            workspaceSyncReferenceSnapshotsReady: true
+        })).toBe(true);
+        expect(shouldScheduleWorkspaceReactivePush({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'attach-cloud',
+            workspaceSyncReferenceSnapshotsReady: true
+        })).toBe(false);
+        expect(shouldScheduleWorkspaceReactivePush({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            workspaceSyncReferenceSnapshotsReady: false
+        })).toBe(false);
+    });
+    it('starts the push watchdog only for active sync', () => {
+        expect(shouldStartWorkspacePushWatchdog({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            workspaceSyncReferenceSnapshotsReady: true
+        })).toBe(true);
+        expect(shouldStartWorkspacePushWatchdog({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'error',
+            workspaceSyncReferenceSnapshotsReady: true
+        })).toBe(false);
+    });
+    it('starts automatic pull for attach-cloud and kickstarts first active pull when no pull has succeeded yet', () => {
+        expect(resolveWorkspaceAutomaticPullPolicy({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'attach-cloud',
+            lastPullAt: null,
+            retryPending: false
+        })).toEqual({
+            shouldStart: true,
+            shouldKickOffImmediately: true
+        });
+        expect(resolveWorkspaceAutomaticPullPolicy({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            lastPullAt: null,
+            retryPending: false
+        })).toEqual({
+            shouldStart: true,
+            shouldKickOffImmediately: true
+        });
+        expect(resolveWorkspaceAutomaticPullPolicy({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            lastPullAt: '2026-04-18T15:00:00.000Z',
+            retryPending: true
+        })).toEqual({
+            shouldStart: false,
+            shouldKickOffImmediately: false
+        });
+    });
+    it('runs periodic full reconcile and startup repair only in authenticated active sync', () => {
+        expect(shouldStartWorkspacePeriodicFullReconcile({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            isAuthenticated: true
+        })).toBe(true);
+        expect(shouldStartWorkspacePeriodicFullReconcile({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'attach-cloud',
+            isAuthenticated: true
+        })).toBe(false);
+        expect(shouldRunWorkspaceStartupRepair({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            isAuthenticated: true,
+            alreadyRan: false
+        })).toBe(true);
+        expect(shouldRunWorkspaceStartupRepair({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'error',
+            isAuthenticated: true,
+            alreadyRan: false
+        })).toBe(true);
+        expect(shouldRunWorkspaceStartupRepair({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            isAuthenticated: true,
+            alreadyRan: true
+        })).toBe(false);
+    });
+});

package/dist/hooks/sync/orchestratorShared.d.ts

@@ -1,6 +1,7 @@
 import type { WorkspaceTaxonomyState } from '../../shared/taxonomyState.js';
-import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncTaskEventSnapshot } from '../../sync/workspaceSyncModel';
-import type { TaskItem } from '../../types';
+import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncEntityEventSnapshot } from '../../sync/workspaceSyncModel';
+import type { WorkspaceSyncPushBaselineSnapshot } from '../../sync/workspaceSyncState.js';
+import type { InitiativeItem, TaskItem, WorkstreamItem } from '../../types';
 export declare const USER_GLOBAL_SYNC_META_KEY = "taskforce.userGlobalSyncMeta.v1";
 export declare const SYNC_DEBUG_LOG_KEY = "taskforce.syncDebug.v1";
 export declare const WORKSPACE_BOOTSTRAP_TIMEOUT_MS = 120000;
@@ -18,11 +19,15 @@ export declare function writeUserGlobalSyncMeta(next: Record<string, {
 }>): void;
 export declare function buildTaxonomyStateFingerprint(taxonomyState?: WorkspaceTaxonomyState): string;
 export declare function flattenDocumentReviewComments(sessions: WorkspaceSyncDocumentReviewSessionSnapshot[]): WorkspaceSyncDocumentReviewCommentSnapshot[];
-export declare function flattenTaskEvents(tasks: TaskItem[], archivedTasks: TaskItem[]): WorkspaceSyncTaskEventSnapshot[];
+export declare function flattenTaskEvents(tasks: TaskItem[], archivedTasks: TaskItem[], initiatives?: InitiativeItem[], workstreams?: WorkstreamItem[]): WorkspaceSyncEntityEventSnapshot[];
 export interface PersistedSyncWatermarks {
+    taskIds: Set<string>;
     taskWatermarks: Map<string, string>;
+    taskChangeKeys?: Map<string, string>;
     initiativeWatermarks: Map<string, string>;
     workstreamWatermarks: Map<string, string>;
+    aiProfileWatermarks: Map<string, string>;
+    aiProfileChangeKeys?: Map<string, string>;
     documentWatermarks: Map<string, string>;
     assetWatermarks: Map<string, string>;
     documentReviewSessionWatermarks: Map<string, string>;
@@ -30,7 +35,11 @@ export interface PersistedSyncWatermarks {
     annotatedAttachmentSessionWatermarks: Map<string, string>;
     taskEventWatermarks: Map<string, string>;
 }
+export declare function buildPersistedSyncWatermarksSnapshot(data: PersistedSyncWatermarks & {
+    taxonomyStateFingerprint?: string;
+}): WorkspaceSyncPushBaselineSnapshot;
+export declare function parsePersistedSyncWatermarksSnapshot(snapshot: WorkspaceSyncPushBaselineSnapshot | null | undefined, taxonomyStateFingerprint?: string): PersistedSyncWatermarks | null;
 export declare function readPersistedSyncWatermarks(workspaceId: string, taxonomyStateFingerprint?: string): PersistedSyncWatermarks | null;
 export declare function savePersistedSyncWatermarks(workspaceId: string, data: PersistedSyncWatermarks & {
     taxonomyStateFingerprint?: string;
-}): void;
+}): boolean;

package/dist/hooks/sync/orchestratorShared.js

@@ -1,4 +1,6 @@
 import { parseAiProfileSurfaceType } from '../../shared/aiProfileSurfaceType.js';
+import { parseAiProfileSeatScope } from '../../shared/aiProfileSeatScope.js';
+import { normalizeSyncNullableId, normalizeSyncNullableIsoString, normalizeSyncNullableString, normalizeSyncSameOriginAssetUrl, } from '../../sync/syncFieldSemantics.js';
 export const USER_GLOBAL_SYNC_META_KEY = 'taskforce.userGlobalSyncMeta.v1';
 export const SYNC_DEBUG_LOG_KEY = 'taskforce.syncDebug.v1';
 export const WORKSPACE_BOOTSTRAP_TIMEOUT_MS = 120_000;
@@ -36,29 +38,27 @@ export function normalizeWorkspaceSyncAiProfileSnapshotEntry(entry) {
         username: String(entry?.username || '').trim(),
         icon: String(entry?.icon || 'Bot').trim() || 'Bot',
         color: String(entry?.color || '#8b5cf6').trim() || '#8b5cf6',
-        description: typeof entry?.description === 'string' && entry.description.trim().length > 0
-            ? entry.description.trim()
-            : null,
-        role: typeof entry?.role === 'string' && entry.role.trim().length > 0
-            ? entry.role.trim()
-            : null,
-        provider: typeof entry?.provider === 'string' && entry.provider.trim().length > 0
-            ? entry.provider.trim()
-            : null,
-        model: typeof entry?.model === 'string' && entry.model.trim().length > 0
-            ? entry.model.trim()
-            : null,
+        avatarUrl: normalizeSyncSameOriginAssetUrl(entry?.avatarUrl ?? entry?.avatar_url),
+        avatarSourceUrl: normalizeSyncSameOriginAssetUrl(entry?.avatarSourceUrl ?? entry?.avatar_source_url),
+        avatarRevision: Number.isFinite(Number(entry?.avatarRevision ?? entry?.avatar_revision)) ? Math.max(0, Math.floor(Number(entry?.avatarRevision ?? entry?.avatar_revision))) : 0,
+        avatarUpdatedAt: normalizeSyncNullableIsoString(entry?.avatarUpdatedAt ?? entry?.avatar_updated_at),
+        description: normalizeSyncNullableString(entry?.description),
+        role: normalizeSyncNullableString(entry?.role),
+        provider: normalizeSyncNullableString(entry?.provider),
+        model: normalizeSyncNullableString(entry?.model),
         surfaceType: parseAiProfileSurfaceType(entry?.surfaceType ?? entry?.surface_type),
+        seatScope: parseAiProfileSeatScope(entry?.seatScope ?? entry?.seat_scope),
         providerMetadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata)
             ? metadata
             : null,
+        archivedAt: normalizeSyncNullableIsoString(entry?.archivedAt ?? entry?.archived_at),
+        archivedBy: normalizeSyncNullableId(entry?.archivedBy ?? entry?.archived_by),
+        archivedReason: normalizeSyncNullableString(entry?.archivedReason ?? entry?.archived_reason),
+        mergedIntoProfileId: normalizeSyncNullableId(entry?.mergedIntoProfileId ?? entry?.merged_into_profile_id),
+        rosterStateUpdatedAt: normalizeSyncNullableIsoString(entry?.rosterStateUpdatedAt ?? entry?.roster_state_updated_at),
         createdAt: String(entry?.createdAt || entry?.created_at || '').trim(),
         updatedAt: String(entry?.updatedAt || entry?.updated_at || entry?.createdAt || entry?.created_at || '').trim(),
-        lastActiveAt: typeof entry?.lastActiveAt === 'string' && entry.lastActiveAt.trim().length > 0
-            ? entry.lastActiveAt.trim()
-            : typeof entry?.last_active_at === 'string' && entry.last_active_at.trim().length > 0
-                ? entry.last_active_at.trim()
-                : null
+        lastActiveAt: normalizeSyncNullableIsoString(entry?.lastActiveAt ?? entry?.last_active_at)
     };
 }
 export function readUserGlobalSyncMeta() {
@@ -115,7 +115,7 @@ export function flattenDocumentReviewComments(sessions) {
             .filter((comment) => comment.id.length > 0 && comment.sessionId.length > 0);
     });
 }
-export function flattenTaskEvents(tasks, archivedTasks) {
+export function flattenTaskEvents(tasks, archivedTasks, initiatives = [], workstreams = []) {
     const deduped = new Map();
     for (const task of [...(tasks || []), ...(archivedTasks || [])]) {
         const taskEvents = Array.isArray(task?.taskEvents) ? task.taskEvents : [];
@@ -128,8 +128,66 @@ export function flattenTaskEvents(tasks, archivedTasks) {
                 continue;
             const nextEvent = {
                 id,
+                workspaceId,
+                entityType: 'task',
+                entityId: taskId,
                 taskId,
+                action: String(event?.action || '').trim(),
+                actor: String(event?.actor || 'system').trim() || 'system',
+                actorType: event?.actorType === 'ai' || event?.actorType === 'human' || event?.actorType === 'system'
+                    ? event.actorType
+                    : 'system',
+                details: event?.details,
+                createdAt,
+            };
+            const existing = deduped.get(id);
+            if (!existing || nextEvent.createdAt > existing.createdAt) {
+                deduped.set(id, nextEvent);
+            }
+        }
+    }
+    for (const initiative of initiatives || []) {
+        const entityEvents = Array.isArray(initiative?.entityEvents) ? initiative.entityEvents : [];
+        for (const event of entityEvents) {
+            const id = String(event?.id || '').trim();
+            const entityId = String(event?.entityId || initiative?.id || '').trim();
+            const workspaceId = String(event?.workspaceId || '').trim();
+            const createdAt = String(event?.createdAt || '').trim();
+            if (!id || !entityId || !workspaceId || !createdAt)
+                continue;
+            const nextEvent = {
+                id,
+                workspaceId,
+                entityType: 'initiative',
+                entityId,
+                action: String(event?.action || '').trim(),
+                actor: String(event?.actor || 'system').trim() || 'system',
+                actorType: event?.actorType === 'ai' || event?.actorType === 'human' || event?.actorType === 'system'
+                    ? event.actorType
+                    : 'system',
+                details: event?.details,
+                createdAt,
+            };
+            const existing = deduped.get(id);
+            if (!existing || nextEvent.createdAt > existing.createdAt) {
+                deduped.set(id, nextEvent);
+            }
+        }
+    }
+    for (const workstream of workstreams || []) {
+        const entityEvents = Array.isArray(workstream?.entityEvents) ? workstream.entityEvents : [];
+        for (const event of entityEvents) {
+            const id = String(event?.id || '').trim();
+            const entityId = String(event?.entityId || workstream?.id || '').trim();
+            const workspaceId = String(event?.workspaceId || '').trim();
+            const createdAt = String(event?.createdAt || '').trim();
+            if (!id || !entityId || !workspaceId || !createdAt)
+                continue;
+            const nextEvent = {
+                id,
                 workspaceId,
+                entityType: 'workstream',
+                entityId,
                 action: String(event?.action || '').trim(),
                 actor: String(event?.actor || 'system').trim() || 'system',
                 actorType: event?.actorType === 'ai' || event?.actorType === 'human' || event?.actorType === 'system'
@@ -150,6 +208,52 @@ export function flattenTaskEvents(tasks, archivedTasks) {
         return left.id.localeCompare(right.id);
     });
 }
+export function buildPersistedSyncWatermarksSnapshot(data) {
+    return {
+        taskIds: Array.from(data.taskIds.values()),
+        taskWatermarks: Array.from(data.taskWatermarks.entries()),
+        taskChangeKeys: Array.from((data.taskChangeKeys || new Map()).entries()),
+        initiativeWatermarks: Array.from(data.initiativeWatermarks.entries()),
+        workstreamWatermarks: Array.from(data.workstreamWatermarks.entries()),
+        aiProfileWatermarks: Array.from(data.aiProfileWatermarks.entries()),
+        aiProfileChangeKeys: Array.from((data.aiProfileChangeKeys || new Map()).entries()),
+        documentWatermarks: Array.from(data.documentWatermarks.entries()),
+        assetWatermarks: Array.from(data.assetWatermarks.entries()),
+        documentReviewSessionWatermarks: Array.from(data.documentReviewSessionWatermarks.entries()),
+        documentReviewCommentWatermarks: Array.from(data.documentReviewCommentWatermarks.entries()),
+        annotatedAttachmentSessionWatermarks: Array.from(data.annotatedAttachmentSessionWatermarks.entries()),
+        taskEventWatermarks: Array.from(data.taskEventWatermarks.entries()),
+        taxonomyStateFingerprint: typeof data.taxonomyStateFingerprint === 'string' ? data.taxonomyStateFingerprint : ''
+    };
+}
+export function parsePersistedSyncWatermarksSnapshot(snapshot, taxonomyStateFingerprint) {
+    if (!snapshot || typeof snapshot !== 'object')
+        return null;
+    const savedTaxonomyStateFingerprint = typeof snapshot.taxonomyStateFingerprint === 'string'
+        ? snapshot.taxonomyStateFingerprint
+        : '';
+    const taskWatermarks = (!taxonomyStateFingerprint || !savedTaxonomyStateFingerprint || savedTaxonomyStateFingerprint === taxonomyStateFingerprint)
+        ? new Map(Array.isArray(snapshot.taskWatermarks) ? snapshot.taskWatermarks : [])
+        : new Map();
+    const taskIds = new Set(Array.isArray(snapshot.taskIds)
+        ? snapshot.taskIds.map((entry) => String(entry || '').trim()).filter((entry) => entry.length > 0)
+        : Array.from(taskWatermarks.keys()));
+    return {
+        taskIds,
+        taskWatermarks,
+        taskChangeKeys: new Map(Array.isArray(snapshot.taskChangeKeys) ? snapshot.taskChangeKeys : []),
+        initiativeWatermarks: new Map(Array.isArray(snapshot.initiativeWatermarks) ? snapshot.initiativeWatermarks : []),
+        workstreamWatermarks: new Map(Array.isArray(snapshot.workstreamWatermarks) ? snapshot.workstreamWatermarks : []),
+        aiProfileWatermarks: new Map(Array.isArray(snapshot.aiProfileWatermarks) ? snapshot.aiProfileWatermarks : []),
+        aiProfileChangeKeys: new Map(Array.isArray(snapshot.aiProfileChangeKeys) ? snapshot.aiProfileChangeKeys : []),
+        documentWatermarks: new Map(Array.isArray(snapshot.documentWatermarks) ? snapshot.documentWatermarks : []),
+        assetWatermarks: new Map(Array.isArray(snapshot.assetWatermarks) ? snapshot.assetWatermarks : []),
+        documentReviewSessionWatermarks: new Map(Array.isArray(snapshot.documentReviewSessionWatermarks) ? snapshot.documentReviewSessionWatermarks : []),
+        documentReviewCommentWatermarks: new Map(Array.isArray(snapshot.documentReviewCommentWatermarks) ? snapshot.documentReviewCommentWatermarks : []),
+        annotatedAttachmentSessionWatermarks: new Map(Array.isArray(snapshot.annotatedAttachmentSessionWatermarks) ? snapshot.annotatedAttachmentSessionWatermarks : []),
+        taskEventWatermarks: new Map(Array.isArray(snapshot.taskEventWatermarks) ? snapshot.taskEventWatermarks : []),
+    };
+}
 export function readPersistedSyncWatermarks(workspaceId, taxonomyStateFingerprint) {
     if (typeof window === 'undefined')
         return null;
@@ -159,25 +263,9 @@ export function readPersistedSyncWatermarks(workspaceId, taxonomyStateFingerprin
         if (!raw)
             return null;
         const parsed = JSON.parse(raw);
-        if (!parsed || (parsed.v !== 2 && parsed.v !== 3 && parsed.v !== 4 && parsed.v !== 5 && parsed.v !== 6 && parsed.v !== 7 && parsed.v !== 8))
+        if (!parsed || (parsed.v !== 2 && parsed.v !== 3 && parsed.v !== 4 && parsed.v !== 5 && parsed.v !== 6 && parsed.v !== 7 && parsed.v !== 8 && parsed.v !== 9 && parsed.v !== 10 && parsed.v !== 11))
             return null;
-        const savedTaxonomyStateFingerprint = typeof parsed.taxonomyStateFingerprint === 'string'
-            ? parsed.taxonomyStateFingerprint
-            : '';
-        const taskWatermarks = (!taxonomyStateFingerprint || !savedTaxonomyStateFingerprint || savedTaxonomyStateFingerprint === taxonomyStateFingerprint)
-            ? new Map(Array.isArray(parsed.taskWatermarks) ? parsed.taskWatermarks : [])
-            : new Map();
-        return {
-            taskWatermarks,
-            initiativeWatermarks: new Map(Array.isArray(parsed.initiativeWatermarks) ? parsed.initiativeWatermarks : []),
-            workstreamWatermarks: new Map(Array.isArray(parsed.workstreamWatermarks) ? parsed.workstreamWatermarks : []),
-            documentWatermarks: new Map(Array.isArray(parsed.documentWatermarks) ? parsed.documentWatermarks : []),
-            assetWatermarks: new Map(Array.isArray(parsed.assetWatermarks) ? parsed.assetWatermarks : []),
-            documentReviewSessionWatermarks: new Map(Array.isArray(parsed.documentReviewSessionWatermarks) ? parsed.documentReviewSessionWatermarks : []),
-            documentReviewCommentWatermarks: new Map(Array.isArray(parsed.documentReviewCommentWatermarks) ? parsed.documentReviewCommentWatermarks : []),
-            annotatedAttachmentSessionWatermarks: new Map(Array.isArray(parsed.annotatedAttachmentSessionWatermarks) ? parsed.annotatedAttachmentSessionWatermarks : []),
-            taskEventWatermarks: new Map(Array.isArray(parsed.taskEventWatermarks) ? parsed.taskEventWatermarks : []),
-        };
+        return parsePersistedSyncWatermarksSnapshot(parsed, taxonomyStateFingerprint);
     }
     catch {
         return null;
@@ -185,25 +273,18 @@ export function readPersistedSyncWatermarks(workspaceId, taxonomyStateFingerprin
 }
 export function savePersistedSyncWatermarks(workspaceId, data) {
     if (typeof window === 'undefined')
-        return;
+        return false;
     try {
         const key = `${WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX}.${workspaceId}`;
         window.localStorage.setItem(key, JSON.stringify({
-            v: 8,
+            v: 11,
             savedAt: new Date().toISOString(),
-            taskWatermarks: Array.from(data.taskWatermarks.entries()),
-            initiativeWatermarks: Array.from(data.initiativeWatermarks.entries()),
-            workstreamWatermarks: Array.from(data.workstreamWatermarks.entries()),
-            documentWatermarks: Array.from(data.documentWatermarks.entries()),
-            assetWatermarks: Array.from(data.assetWatermarks.entries()),
-            documentReviewSessionWatermarks: Array.from(data.documentReviewSessionWatermarks.entries()),
-            documentReviewCommentWatermarks: Array.from(data.documentReviewCommentWatermarks.entries()),
-            annotatedAttachmentSessionWatermarks: Array.from(data.annotatedAttachmentSessionWatermarks.entries()),
-            taskEventWatermarks: Array.from(data.taskEventWatermarks.entries()),
-            taxonomyStateFingerprint: typeof data.taxonomyStateFingerprint === 'string' ? data.taxonomyStateFingerprint : ''
+            ...buildPersistedSyncWatermarksSnapshot(data)
         }));
+        return true;
     }
     catch {
         // localStorage may be full or unavailable; non-fatal
+        return false;
     }
 }

package/dist/hooks/sync/orchestratorShared.test.js

@@ -8,11 +8,13 @@ describe('orchestratorShared sync watermarks', () => {
     it('keeps persisted sync watermarks available across long idle periods', () => {
         const key = `${WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX}.${workspaceId}`;
         localStorage.setItem(key, JSON.stringify({
-            v: 8,
+            v: 9,
             savedAt: '2026-04-14T10:00:00.000Z',
+            taskIds: ['task-1'],
             taskWatermarks: [['task-1', '2026-04-14T09:00:00.000Z']],
             initiativeWatermarks: [['initiative-1', '2026-04-14T09:00:00.000Z']],
             workstreamWatermarks: [],
+            aiProfileWatermarks: [['ai-profile-1', '2026-04-14T09:15:00.000Z']],
             documentWatermarks: [],
             assetWatermarks: [],
             documentReviewSessionWatermarks: [],
@@ -23,15 +25,40 @@ describe('orchestratorShared sync watermarks', () => {
         }));
         const persisted = readPersistedSyncWatermarks(workspaceId, '');
         expect(persisted).not.toBeNull();
+        expect(Array.from(persisted?.taskIds || [])).toEqual(['task-1']);
         expect(persisted?.taskWatermarks.get('task-1')).toBe('2026-04-14T09:00:00.000Z');
         expect(persisted?.initiativeWatermarks.get('initiative-1')).toBe('2026-04-14T09:00:00.000Z');
+        expect(persisted?.aiProfileWatermarks.get('ai-profile-1')).toBe('2026-04-14T09:15:00.000Z');
         expect(persisted?.taskEventWatermarks.get('event-1')).toBe('2026-04-14T09:30:00.000Z');
     });
+    it('persists task and ai-profile change keys alongside legacy watermarks', () => {
+        savePersistedSyncWatermarks(workspaceId, {
+            taskIds: new Set(['task-1']),
+            taskWatermarks: new Map([['task-1', '2026-04-14T09:00:00.000Z']]),
+            taskChangeKeys: new Map([['task-1', 'task-change-key-1']]),
+            initiativeWatermarks: new Map(),
+            workstreamWatermarks: new Map(),
+            aiProfileWatermarks: new Map([['ai-profile-1', '2026-04-14T09:15:00.000Z']]),
+            aiProfileChangeKeys: new Map([['ai-profile-1', 'ai-change-key-1']]),
+            documentWatermarks: new Map(),
+            assetWatermarks: new Map(),
+            documentReviewSessionWatermarks: new Map(),
+            documentReviewCommentWatermarks: new Map(),
+            annotatedAttachmentSessionWatermarks: new Map(),
+            taskEventWatermarks: new Map(),
+            taxonomyStateFingerprint: 'fingerprint-a'
+        });
+        const persisted = readPersistedSyncWatermarks(workspaceId, 'fingerprint-a');
+        expect(persisted?.taskChangeKeys?.get('task-1')).toBe('task-change-key-1');
+        expect(persisted?.aiProfileChangeKeys?.get('ai-profile-1')).toBe('ai-change-key-1');
+    });
     it('still clears task watermarks when the taxonomy fingerprint changes', () => {
         savePersistedSyncWatermarks(workspaceId, {
+            taskIds: new Set(['task-1']),
             taskWatermarks: new Map([['task-1', '2026-04-14T09:00:00.000Z']]),
             initiativeWatermarks: new Map([['initiative-1', '2026-04-14T09:00:00.000Z']]),
             workstreamWatermarks: new Map(),
+            aiProfileWatermarks: new Map([['ai-profile-1', '2026-04-14T09:15:00.000Z']]),
             documentWatermarks: new Map(),
             assetWatermarks: new Map(),
             documentReviewSessionWatermarks: new Map(),
@@ -42,8 +69,30 @@ describe('orchestratorShared sync watermarks', () => {
         });
         const persisted = readPersistedSyncWatermarks(workspaceId, 'fingerprint-b');
         expect(persisted).not.toBeNull();
+        expect(Array.from(persisted?.taskIds || [])).toEqual(['task-1']);
         expect(persisted?.taskWatermarks.size).toBe(0);
         expect(persisted?.initiativeWatermarks.get('initiative-1')).toBe('2026-04-14T09:00:00.000Z');
+        expect(persisted?.aiProfileWatermarks.get('ai-profile-1')).toBe('2026-04-14T09:15:00.000Z');
         expect(persisted?.taskEventWatermarks.get('event-1')).toBe('2026-04-14T09:30:00.000Z');
     });
+    it('falls back to task watermark keys when older persisted snapshots do not have taskIds', () => {
+        const key = `${WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX}.${workspaceId}`;
+        localStorage.setItem(key, JSON.stringify({
+            v: 9,
+            savedAt: '2026-04-14T10:00:00.000Z',
+            taskWatermarks: [['task-legacy-1', '2026-04-14T09:00:00.000Z']],
+            initiativeWatermarks: [],
+            workstreamWatermarks: [],
+            aiProfileWatermarks: [],
+            documentWatermarks: [],
+            assetWatermarks: [],
+            documentReviewSessionWatermarks: [],
+            documentReviewCommentWatermarks: [],
+            annotatedAttachmentSessionWatermarks: [],
+            taskEventWatermarks: [],
+            taxonomyStateFingerprint: ''
+        }));
+        const persisted = readPersistedSyncWatermarks(workspaceId, '');
+        expect(Array.from(persisted?.taskIds || [])).toEqual(['task-legacy-1']);
+    });
 });

package/dist/hooks/sync/pullLifecycle.d.ts

@@ -0,0 +1,31 @@
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+export interface WorkspacePullRequestPlan {
+    bootstrap: boolean;
+    cursor: string | null;
+    successEventType: 'bootstrap' | 'pull';
+}
+interface ResolveWorkspacePullRequestPlanArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    forceCursorNull?: boolean;
+    currentCursor: string | null;
+}
+interface ResolveWorkspacePullSuccessPlanArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    forceCursorNull?: boolean;
+    startupFullReconcileRan: boolean;
+    pendingSignature: string;
+    fallbackSignature: string;
+    lastPushedSignature: string;
+}
+export interface WorkspacePullSuccessPlan {
+    successEventType: 'bootstrap' | 'pull';
+    shouldCaptureAttachBootstrapBaseline: boolean;
+    shouldClearPendingSignature: boolean;
+    shouldRefreshReferenceSnapshots: boolean;
+    shouldSeedWorkspaceSnapshotPushBaseline: boolean;
+    shouldScheduleStartupFullReconcile: boolean;
+    deferredPushSignature: string | null;
+}
+export declare function resolveWorkspacePullRequestPlan({ workspaceSyncPhase, forceCursorNull, currentCursor }: ResolveWorkspacePullRequestPlanArgs): WorkspacePullRequestPlan;
+export declare function resolveWorkspacePullSuccessPlan({ workspaceSyncPhase, forceCursorNull, startupFullReconcileRan, pendingSignature, fallbackSignature, lastPushedSignature }: ResolveWorkspacePullSuccessPlanArgs): WorkspacePullSuccessPlan;
+export {};

package/dist/hooks/sync/pullLifecycle.js

@@ -0,0 +1,24 @@
+export function resolveWorkspacePullRequestPlan({ workspaceSyncPhase, forceCursorNull, currentCursor }) {
+    const bootstrap = workspaceSyncPhase === 'attach-cloud';
+    return {
+        bootstrap,
+        cursor: bootstrap || forceCursorNull === true ? null : currentCursor,
+        successEventType: bootstrap ? 'bootstrap' : 'pull'
+    };
+}
+export function resolveWorkspacePullSuccessPlan({ workspaceSyncPhase, forceCursorNull, startupFullReconcileRan, pendingSignature, fallbackSignature, lastPushedSignature }) {
+    const bootstrap = workspaceSyncPhase === 'attach-cloud';
+    const nextSignature = pendingSignature || fallbackSignature;
+    const deferredPushSignature = (!bootstrap
+        && nextSignature
+        && nextSignature !== lastPushedSignature) ? nextSignature : null;
+    return {
+        successEventType: bootstrap ? 'bootstrap' : 'pull',
+        shouldCaptureAttachBootstrapBaseline: bootstrap,
+        shouldClearPendingSignature: bootstrap || deferredPushSignature !== null,
+        shouldRefreshReferenceSnapshots: bootstrap,
+        shouldSeedWorkspaceSnapshotPushBaseline: bootstrap,
+        shouldScheduleStartupFullReconcile: !forceCursorNull && !bootstrap && !startupFullReconcileRan,
+        deferredPushSignature
+    };
+}

package/dist/hooks/sync/pullLifecycle.test.d.ts

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

package/dist/hooks/sync/pullLifecycle.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import { resolveWorkspacePullRequestPlan, resolveWorkspacePullSuccessPlan, } from './pullLifecycle';
+describe('pull lifecycle', () => {
+    it('treats attach-cloud pulls as bootstrap pulls with a null cursor', () => {
+        expect(resolveWorkspacePullRequestPlan({
+            workspaceSyncPhase: 'attach-cloud',
+            forceCursorNull: false,
+            currentCursor: 'cursor-1'
+        })).toEqual({
+            bootstrap: true,
+            cursor: null,
+            successEventType: 'bootstrap'
+        });
+    });
+    it('keeps the saved cursor for normal incremental pulls', () => {
+        expect(resolveWorkspacePullRequestPlan({
+            workspaceSyncPhase: 'active',
+            forceCursorNull: false,
+            currentCursor: 'cursor-1'
+        })).toEqual({
+            bootstrap: false,
+            cursor: 'cursor-1',
+            successEventType: 'pull'
+        });
+    });
+    it('marks attach-cloud success for reference refresh and baseline seeding without a follow-up push', () => {
+        expect(resolveWorkspacePullSuccessPlan({
+            workspaceSyncPhase: 'attach-cloud',
+            forceCursorNull: false,
+            startupFullReconcileRan: false,
+            pendingSignature: 'sig-pending',
+            fallbackSignature: 'sig-fallback',
+            lastPushedSignature: ''
+        })).toEqual({
+            successEventType: 'bootstrap',
+            shouldCaptureAttachBootstrapBaseline: true,
+            shouldClearPendingSignature: true,
+            shouldRefreshReferenceSnapshots: true,
+            shouldSeedWorkspaceSnapshotPushBaseline: true,
+            shouldScheduleStartupFullReconcile: false,
+            deferredPushSignature: null
+        });
+    });
+    it('schedules a one-time startup full reconcile and deferred push after the first normal pull', () => {
+        expect(resolveWorkspacePullSuccessPlan({
+            workspaceSyncPhase: 'active',
+            forceCursorNull: false,
+            startupFullReconcileRan: false,
+            pendingSignature: 'sig-pending',
+            fallbackSignature: 'sig-fallback',
+            lastPushedSignature: 'sig-old'
+        })).toEqual({
+            successEventType: 'pull',
+            shouldCaptureAttachBootstrapBaseline: false,
+            shouldClearPendingSignature: true,
+            shouldRefreshReferenceSnapshots: false,
+            shouldSeedWorkspaceSnapshotPushBaseline: false,
+            shouldScheduleStartupFullReconcile: true,
+            deferredPushSignature: 'sig-pending'
+        });
+    });
+    it('does not schedule a second startup full reconcile or redundant deferred push', () => {
+        expect(resolveWorkspacePullSuccessPlan({
+            workspaceSyncPhase: 'active',
+            forceCursorNull: true,
+            startupFullReconcileRan: true,
+            pendingSignature: '',
+            fallbackSignature: 'sig-current',
+            lastPushedSignature: 'sig-current'
+        })).toEqual({
+            successEventType: 'pull',
+            shouldCaptureAttachBootstrapBaseline: false,
+            shouldClearPendingSignature: false,
+            shouldRefreshReferenceSnapshots: false,
+            shouldSeedWorkspaceSnapshotPushBaseline: false,
+            shouldScheduleStartupFullReconcile: false,
+            deferredPushSignature: null
+        });
+    });
+});