@taskforcehq/taskforce 0.3.303 → 0.3.304

package/dist/hooks/sync/auth.js

@@ -0,0 +1,61 @@
+import { isTransientWorkspaceSyncStatus } from '../../sync/syncService';
+import { isValidWorkspaceKey } from './orchestratorShared';
+export function createSyncAuthCoordinator({ currentWorkspaceId, workspaceSyncPhase, clearWorkspaceRetry, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, reportSyncEvent, setAuthBlocked, setIsAuthenticated, checkAuthSession, ensureCloudWorkspaceReadyForSync, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely }) {
+    const handleSyncAuthFailure = async (source, statusCode) => {
+        clearWorkspaceRetry();
+        setWorkspaceSyncBusy(false);
+        setUserGlobalSyncStatus('error');
+        const message = 'Session expired. Sign in again to resume cloud sync.';
+        setUserGlobalSyncError(message);
+        setWorkspaceLastErrorMessage(message);
+        setWorkspaceLastErrorAt(new Date().toISOString());
+        reportSyncEvent(currentWorkspaceId, {
+            eventType: source === 'handshake' ? 'handshake' : source,
+            status: 'error',
+            statusCode,
+            errorMessage: message
+        });
+        setAuthBlocked(true);
+        setIsAuthenticated(false);
+        await checkAuthSession();
+    };
+    const ensureWorkspaceSyncReady = async () => {
+        if (!isValidWorkspaceKey(currentWorkspaceId)) {
+            const message = 'Workspace sync blocked: local workspace ID is unresolved.';
+            setWorkspaceLastErrorMessage(message);
+            setWorkspaceLastErrorAt(new Date().toISOString());
+            setUserGlobalSyncError(message);
+            setUserGlobalSyncStatus('error');
+            return false;
+        }
+        const ensured = await ensureCloudWorkspaceReadyForSync();
+        if (ensured.success)
+            return true;
+        if (ensured.statusCode === 401) {
+            await handleSyncAuthFailure('handshake', 401);
+            return false;
+        }
+        const message = ensured.error || 'Workspace sync handshake failed.';
+        setWorkspaceLastErrorMessage(message);
+        setWorkspaceLastErrorAt(new Date().toISOString());
+        setUserGlobalSyncError(message);
+        setUserGlobalSyncStatus('error');
+        reportSyncEvent(currentWorkspaceId, {
+            eventType: 'handshake',
+            status: 'error',
+            statusCode: ensured.statusCode,
+            errorMessage: message
+        });
+        if (ensured.transient || isTransientWorkspaceSyncStatus(ensured.statusCode)) {
+            scheduleWorkspaceSyncRetry(ensured.retryAfterMs);
+        }
+        else if (workspaceSyncPhase === 'active') {
+            persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+        }
+        return false;
+    };
+    return {
+        handleSyncAuthFailure,
+        ensureWorkspaceSyncReady
+    };
+}

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

@@ -0,0 +1,34 @@
+import type { MutableRefObject } from 'react';
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+interface BootstrapPhaseTrackingArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    lastBootstrapPhaseRef: MutableRefObject<WorkspaceSyncPhase>;
+    bootstrapPhaseStartedAtRef: MutableRefObject<number | null>;
+    bootstrapLastProgressAtRef: MutableRefObject<number | null>;
+}
+export declare function syncBootstrapPhaseTracking({ workspaceSyncPhase, lastBootstrapPhaseRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef }: BootstrapPhaseTrackingArgs): void;
+interface BootstrapTimeoutMonitorArgs {
+    currentWorkspaceId: string;
+    workspaceCloudSyncEnabled: boolean;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspacePullInFlightRef: MutableRefObject<boolean>;
+    workspacePushInFlightRef: MutableRefObject<boolean>;
+    bootstrapPhaseStartedAtRef: MutableRefObject<number | null>;
+    bootstrapLastProgressAtRef: MutableRefObject<number | null>;
+    setWorkspaceLastErrorMessage: (value: string) => void;
+    setWorkspaceLastErrorAt: (value: string) => void;
+    setUserGlobalSyncStatus: (value: 'error') => void;
+    setUserGlobalSyncError: (value: string) => void;
+    setWorkspaceSyncBusy: (value: boolean) => void;
+    persistWorkspaceSyncPatchSafely: (patch: {
+        phase: 'error';
+        lastErrorMessage: string;
+    }) => void;
+}
+export declare function createBootstrapTimeoutMonitor({ currentWorkspaceId, workspaceCloudSyncEnabled, workspaceSyncPhase, workspacePullInFlightRef, workspacePushInFlightRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceSyncBusy, persistWorkspaceSyncPatchSafely }: BootstrapTimeoutMonitorArgs): (() => void) | undefined;
+export declare function resolveRepairPhase(args: {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    lastBootstrapPhase: WorkspaceSyncPhase;
+    workspaceLastPullAt: string | null;
+}): WorkspaceSyncPhase;
+export {};

package/dist/hooks/sync/bootstrap.js

@@ -0,0 +1,52 @@
+import { WORKSPACE_BOOTSTRAP_TIMEOUT_MS, logSyncDebug } from './orchestratorShared';
+export function syncBootstrapPhaseTracking({ workspaceSyncPhase, lastBootstrapPhaseRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef }) {
+    if (workspaceSyncPhase === 'attach-cloud' || workspaceSyncPhase === 'provision-local') {
+        lastBootstrapPhaseRef.current = workspaceSyncPhase;
+        if (bootstrapPhaseStartedAtRef.current === null) {
+            bootstrapPhaseStartedAtRef.current = Date.now();
+        }
+        bootstrapLastProgressAtRef.current = null;
+        return;
+    }
+    bootstrapPhaseStartedAtRef.current = null;
+    bootstrapLastProgressAtRef.current = null;
+}
+export function createBootstrapTimeoutMonitor({ currentWorkspaceId, workspaceCloudSyncEnabled, workspaceSyncPhase, workspacePullInFlightRef, workspacePushInFlightRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceSyncBusy, persistWorkspaceSyncPatchSafely }) {
+    if (!workspaceCloudSyncEnabled)
+        return undefined;
+    if (workspaceSyncPhase !== 'attach-cloud' && workspaceSyncPhase !== 'provision-local')
+        return undefined;
+    const intervalId = window.setInterval(() => {
+        if (workspaceSyncPhase !== 'attach-cloud' && workspaceSyncPhase !== 'provision-local')
+            return;
+        if (workspacePullInFlightRef.current || workspacePushInFlightRef.current)
+            return;
+        const lastActivity = Math.max(bootstrapPhaseStartedAtRef.current ?? 0, bootstrapLastProgressAtRef.current ?? 0);
+        if (lastActivity > 0 && (Date.now() - lastActivity) < WORKSPACE_BOOTSTRAP_TIMEOUT_MS)
+            return;
+        const phaseLabel = workspaceSyncPhase === 'attach-cloud' ? 'initial cloud pull' : 'initial cloud upload';
+        const message = `Workspace sync ${phaseLabel} stalled. Press Repair to restart sync for this workspace.`;
+        setWorkspaceLastErrorMessage(message);
+        setWorkspaceLastErrorAt(new Date().toISOString());
+        setUserGlobalSyncStatus('error');
+        setUserGlobalSyncError(message);
+        setWorkspaceSyncBusy(false);
+        persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+        logSyncDebug('workspace_sync_bootstrap_timeout', {
+            workspaceId: currentWorkspaceId,
+            phase: workspaceSyncPhase
+        });
+    }, 10_000);
+    return () => window.clearInterval(intervalId);
+}
+export function resolveRepairPhase(args) {
+    const { workspaceSyncPhase, lastBootstrapPhase, workspaceLastPullAt } = args;
+    if (workspaceSyncPhase === 'provision-local')
+        return 'provision-local';
+    if (workspaceSyncPhase === 'attach-cloud')
+        return 'attach-cloud';
+    if (lastBootstrapPhase === 'provision-local' || lastBootstrapPhase === 'attach-cloud') {
+        return lastBootstrapPhase;
+    }
+    return workspaceLastPullAt ? 'attach-cloud' : 'provision-local';
+}

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

@@ -0,0 +1,36 @@
+import type { WorkspaceTaxonomyState } from '../../shared/taxonomyState.js';
+import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncTaskEventSnapshot } from '../../sync/workspaceSyncModel';
+import type { TaskItem } 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;
+export declare const WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX = "taskforce.syncWatermarks.v3";
+export declare const WORKSPACE_FULL_RECONCILE_INTERVAL_MS: number;
+export declare const WORKSPACE_CONCURRENT_WINDOW_MESSAGE = "Another local window is already syncing this workspace. Wait a few seconds, or press Repair in that window.";
+export declare function isValidWorkspaceKey(workspaceId: string): boolean;
+export declare function logSyncDebug(event: string, details?: Record<string, unknown>): void;
+export declare function normalizeWorkspaceSyncAiProfileSnapshotEntry(entry: any): WorkspaceSyncAiProfileSnapshot;
+export declare function readUserGlobalSyncMeta(): Record<string, {
+    updatedAt: string;
+}>;
+export declare function writeUserGlobalSyncMeta(next: Record<string, {
+    updatedAt: 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 interface PersistedSyncWatermarks {
+    taskWatermarks: Map<string, string>;
+    initiativeWatermarks: Map<string, string>;
+    workstreamWatermarks: Map<string, string>;
+    documentWatermarks: Map<string, string>;
+    assetWatermarks: Map<string, string>;
+    documentReviewSessionWatermarks: Map<string, string>;
+    documentReviewCommentWatermarks: Map<string, string>;
+    annotatedAttachmentSessionWatermarks: Map<string, string>;
+    taskEventWatermarks: Map<string, string>;
+}
+export declare function readPersistedSyncWatermarks(workspaceId: string, taxonomyStateFingerprint?: string): PersistedSyncWatermarks | null;
+export declare function savePersistedSyncWatermarks(workspaceId: string, data: PersistedSyncWatermarks & {
+    taxonomyStateFingerprint?: string;
+}): void;

package/dist/hooks/sync/orchestratorShared.js

@@ -0,0 +1,209 @@
+import { parseAiProfileSurfaceType } from '../../shared/aiProfileSurfaceType.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;
+export const WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX = 'taskforce.syncWatermarks.v3';
+export const WORKSPACE_FULL_RECONCILE_INTERVAL_MS = 5 * 60 * 1000;
+export const WORKSPACE_CONCURRENT_WINDOW_MESSAGE = 'Another local window is already syncing this workspace. Wait a few seconds, or press Repair in that window.';
+export function isValidWorkspaceKey(workspaceId) {
+    const workspaceKey = String(workspaceId || '').trim();
+    return workspaceKey.length > 0 && workspaceKey.toLowerCase() !== 'default';
+}
+function isSyncDebugLoggingEnabled() {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        const raw = String(window.localStorage.getItem(SYNC_DEBUG_LOG_KEY) || '').trim().toLowerCase();
+        return raw === '1' || raw === 'true' || raw === 'on' || raw === 'yes';
+    }
+    catch {
+        return false;
+    }
+}
+export function logSyncDebug(event, details) {
+    if (!isSyncDebugLoggingEnabled())
+        return;
+    const payload = details && typeof details === 'object' ? details : {};
+    console.info('[Taskforce Sync]', event, payload);
+}
+export function normalizeWorkspaceSyncAiProfileSnapshotEntry(entry) {
+    const metadata = entry?.providerMetadata ?? entry?.provider_metadata ?? null;
+    return {
+        id: String(entry?.id || '').trim(),
+        workspaceId: String(entry?.workspaceId || entry?.workspace_id || '').trim(),
+        profileToken: String(entry?.profileToken || entry?.profile_token || '').trim(),
+        name: String(entry?.name || '').trim(),
+        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,
+        surfaceType: parseAiProfileSurfaceType(entry?.surfaceType ?? entry?.surface_type),
+        providerMetadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+            ? metadata
+            : null,
+        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
+    };
+}
+export function readUserGlobalSyncMeta() {
+    if (typeof window === 'undefined')
+        return {};
+    try {
+        const raw = window.localStorage.getItem(USER_GLOBAL_SYNC_META_KEY);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object'
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function writeUserGlobalSyncMeta(next) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.setItem(USER_GLOBAL_SYNC_META_KEY, JSON.stringify(next));
+    }
+    catch {
+        // best-effort only
+    }
+}
+export function buildTaxonomyStateFingerprint(taxonomyState) {
+    try {
+        return JSON.stringify(taxonomyState && typeof taxonomyState === 'object' ? taxonomyState : null);
+    }
+    catch {
+        return 'null';
+    }
+}
+export function flattenDocumentReviewComments(sessions) {
+    return sessions.flatMap((session) => {
+        const sessionId = String(session?.id || '').trim();
+        if (!sessionId || !Array.isArray(session?.comments))
+            return [];
+        return session.comments
+            .map((comment) => ({
+            id: String(comment?.id || '').trim(),
+            sessionId,
+            body: String(comment?.body || ''),
+            anchor: comment?.anchor ?? null,
+            order: Number.isFinite(Number(comment?.order)) ? Math.max(0, Math.floor(Number(comment.order))) : 0,
+            authorActorId: typeof comment?.authorActorId === 'string' && comment.authorActorId.trim().length > 0 ? comment.authorActorId.trim() : null,
+            createdAt: String(comment?.createdAt || '').trim(),
+            updatedAt: String(comment?.updatedAt || comment?.createdAt || '').trim(),
+            deletedAt: typeof comment?.deletedAt === 'string' && comment.deletedAt.trim().length > 0 ? comment.deletedAt.trim() : null,
+        }))
+            .filter((comment) => comment.id.length > 0 && comment.sessionId.length > 0);
+    });
+}
+export function flattenTaskEvents(tasks, archivedTasks) {
+    const deduped = new Map();
+    for (const task of [...(tasks || []), ...(archivedTasks || [])]) {
+        const taskEvents = Array.isArray(task?.taskEvents) ? task.taskEvents : [];
+        for (const event of taskEvents) {
+            const id = String(event?.id || '').trim();
+            const taskId = String(event?.taskId || task?.id || '').trim();
+            const workspaceId = String(event?.workspaceId || '').trim();
+            const createdAt = String(event?.createdAt || '').trim();
+            if (!id || !taskId || !workspaceId || !createdAt)
+                continue;
+            const nextEvent = {
+                id,
+                taskId,
+                workspaceId,
+                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);
+            }
+        }
+    }
+    return Array.from(deduped.values()).sort((left, right) => {
+        if (left.createdAt !== right.createdAt)
+            return left.createdAt.localeCompare(right.createdAt);
+        return left.id.localeCompare(right.id);
+    });
+}
+export function readPersistedSyncWatermarks(workspaceId, taxonomyStateFingerprint) {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        const key = `${WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX}.${workspaceId}`;
+        const raw = window.localStorage.getItem(key);
+        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))
+            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 : []),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function savePersistedSyncWatermarks(workspaceId, data) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        const key = `${WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX}.${workspaceId}`;
+        window.localStorage.setItem(key, JSON.stringify({
+            v: 8,
+            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 : ''
+        }));
+    }
+    catch {
+        // localStorage may be full or unavailable; non-fatal
+    }
+}

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

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

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

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { readPersistedSyncWatermarks, savePersistedSyncWatermarks, WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX, } from './orchestratorShared';
+describe('orchestratorShared sync watermarks', () => {
+    const workspaceId = 'workspace-local-active';
+    beforeEach(() => {
+        localStorage.clear();
+    });
+    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,
+            savedAt: '2026-04-14T10:00:00.000Z',
+            taskWatermarks: [['task-1', '2026-04-14T09:00:00.000Z']],
+            initiativeWatermarks: [['initiative-1', '2026-04-14T09:00:00.000Z']],
+            workstreamWatermarks: [],
+            documentWatermarks: [],
+            assetWatermarks: [],
+            documentReviewSessionWatermarks: [],
+            documentReviewCommentWatermarks: [],
+            annotatedAttachmentSessionWatermarks: [],
+            taskEventWatermarks: [['event-1', '2026-04-14T09:30:00.000Z']],
+            taxonomyStateFingerprint: ''
+        }));
+        const persisted = readPersistedSyncWatermarks(workspaceId, '');
+        expect(persisted).not.toBeNull();
+        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?.taskEventWatermarks.get('event-1')).toBe('2026-04-14T09:30:00.000Z');
+    });
+    it('still clears task watermarks when the taxonomy fingerprint changes', () => {
+        savePersistedSyncWatermarks(workspaceId, {
+            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(),
+            documentWatermarks: new Map(),
+            assetWatermarks: new Map(),
+            documentReviewSessionWatermarks: new Map(),
+            documentReviewCommentWatermarks: new Map(),
+            annotatedAttachmentSessionWatermarks: new Map(),
+            taskEventWatermarks: new Map([['event-1', '2026-04-14T09:30:00.000Z']]),
+            taxonomyStateFingerprint: 'fingerprint-a'
+        });
+        const persisted = readPersistedSyncWatermarks(workspaceId, 'fingerprint-b');
+        expect(persisted).not.toBeNull();
+        expect(persisted?.taskWatermarks.size).toBe(0);
+        expect(persisted?.initiativeWatermarks.get('initiative-1')).toBe('2026-04-14T09:00:00.000Z');
+        expect(persisted?.taskEventWatermarks.get('event-1')).toBe('2026-04-14T09:30:00.000Z');
+    });
+});

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

@@ -0,0 +1,25 @@
+import type { MutableRefObject } from 'react';
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+import type { RealtimeSyncSignal } from '../useRealtimeSync';
+interface CreateRealtimeSyncBridgeArgs {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    workspaceCloudSyncEnabled: boolean;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspacePullInFlightRef: MutableRefObject<boolean>;
+    realtimePullDebounceRef: MutableRefObject<number | null>;
+    realtimeSuppressedEventIdsRef: MutableRefObject<Set<string>>;
+    clearWorkspaceRetry: () => void;
+    isWorkspaceRetryPending: () => boolean;
+    pullWorkspaceChangesFromCloud: () => Promise<boolean>;
+}
+export declare function createRealtimeSyncBridge({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, workspaceSyncPhase, workspacePullInFlightRef, realtimePullDebounceRef, realtimeSuppressedEventIdsRef, clearWorkspaceRetry, isWorkspaceRetryPending, pullWorkspaceChangesFromCloud }: CreateRealtimeSyncBridgeArgs): {
+    handleRealtimeSignal: (signal: RealtimeSyncSignal) => void;
+    recordSuppressedEventIds: (eventIds: Iterable<string>, options?: {
+        queueRef?: MutableRefObject<string[]>;
+        maxQueueSize?: number;
+        ttlMs?: number;
+    }) => void;
+    clearRealtimePullDebounce: () => void;
+};
+export {};

package/dist/hooks/sync/realtime.js

@@ -0,0 +1,60 @@
+export function createRealtimeSyncBridge({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, workspaceSyncPhase, workspacePullInFlightRef, realtimePullDebounceRef, realtimeSuppressedEventIdsRef, clearWorkspaceRetry, isWorkspaceRetryPending, pullWorkspaceChangesFromCloud }) {
+    const handleRealtimeSignal = (signal) => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        if (workspaceSyncPhase === 'provision-local')
+            return;
+        const eventId = String(signal?.eventId || '').trim();
+        if (eventId && realtimeSuppressedEventIdsRef.current.delete(eventId))
+            return;
+        if (workspacePullInFlightRef.current)
+            return;
+        if (isWorkspaceRetryPending()) {
+            clearWorkspaceRetry();
+        }
+        if (realtimePullDebounceRef.current !== null) {
+            window.clearTimeout(realtimePullDebounceRef.current);
+        }
+        realtimePullDebounceRef.current = window.setTimeout(() => {
+            realtimePullDebounceRef.current = null;
+            void pullWorkspaceChangesFromCloud();
+        }, 180);
+    };
+    const recordSuppressedEventIds = (eventIds, options) => {
+        const queueRef = options?.queueRef;
+        const maxQueueSize = Number.isFinite(options?.maxQueueSize) ? Math.max(1, Number(options?.maxQueueSize)) : 2048;
+        const ttlMs = Number.isFinite(options?.ttlMs) ? Math.max(0, Number(options?.ttlMs)) : null;
+        for (const rawEventId of eventIds) {
+            const eventId = String(rawEventId || '').trim();
+            if (!eventId || realtimeSuppressedEventIdsRef.current.has(eventId))
+                continue;
+            realtimeSuppressedEventIdsRef.current.add(eventId);
+            if (queueRef) {
+                queueRef.current.push(eventId);
+            }
+            if (ttlMs !== null) {
+                window.setTimeout(() => {
+                    realtimeSuppressedEventIdsRef.current.delete(eventId);
+                }, ttlMs);
+            }
+        }
+        if (queueRef) {
+            while (queueRef.current.length > maxQueueSize) {
+                const stale = queueRef.current.shift();
+                if (stale)
+                    realtimeSuppressedEventIdsRef.current.delete(stale);
+            }
+        }
+    };
+    const clearRealtimePullDebounce = () => {
+        if (realtimePullDebounceRef.current !== null) {
+            window.clearTimeout(realtimePullDebounceRef.current);
+            realtimePullDebounceRef.current = null;
+        }
+    };
+    return {
+        handleRealtimeSignal,
+        recordSuppressedEventIds,
+        clearRealtimePullDebounce
+    };
+}

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

@@ -0,0 +1,69 @@
+import type { MutableRefObject } from 'react';
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+interface CreateSyncRecoveryCoordinatorArgs {
+    currentWorkspaceId: string;
+    taxonomyStateFingerprint: string;
+    workspaceCloudSyncEnabled: boolean;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspaceLastPullAt: string | null;
+    lastBootstrapPhaseRef: MutableRefObject<WorkspaceSyncPhase>;
+    workspaceRepairModeRef: MutableRefObject<boolean>;
+    workspaceForceFullAiProfilePushRef: MutableRefObject<boolean>;
+    workspaceStartupRepairRanRef: MutableRefObject<boolean>;
+    workspaceStartupFullReconcileRanRef: MutableRefObject<boolean>;
+    workspaceFullReconcileInFlightRef: MutableRefObject<boolean>;
+    workspacePullCursorRef: MutableRefObject<string | null>;
+    workspaceAttachBootstrapBaselineSignatureRef: MutableRefObject<string>;
+    workspaceCaptureAttachBootstrapBaselineRef: MutableRefObject<boolean>;
+    workspacePendingSignatureRef: MutableRefObject<string>;
+    workspaceLastPushedSignatureRef: MutableRefObject<string>;
+    workspaceLastPushedWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedInitiativeIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedInitiativeWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedWorkstreamIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedWorkstreamWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedAiProfileIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedAiProfileWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedDocumentPathsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedDocumentWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedAssetPathsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedAssetWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedDocumentReviewSessionIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedDocumentReviewSessionWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedDocumentReviewCommentIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedDocumentReviewCommentWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedAnnotatedAttachmentSessionIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedTaskEventWatermarksRef: MutableRefObject<Map<string, string>>;
+    bootstrapPhaseStartedAtRef: MutableRefObject<number | null>;
+    bootstrapLastProgressAtRef: MutableRefObject<number | null>;
+    acquireWorkspaceSyncLease: (workspaceId: string, owner: 'pull' | 'push' | 'repair') => Promise<boolean>;
+    releaseWorkspaceSyncLease: (workspaceId: string) => void;
+    forceClearWorkspaceSyncLease: (workspaceId: string) => void;
+    clearWorkspaceRetry: () => void;
+    clearWorkspaceIssue: () => void;
+    reportWorkspaceWindowContention: (operation: 'pull' | 'push' | 'repair') => void;
+    persistWorkspaceSyncPatch: (patch: {
+        phase: WorkspaceSyncPhase;
+        pullCursor: null;
+        lastErrorMessage: null;
+    }) => Promise<unknown>;
+    buildWorkspaceSyncSignature: () => string;
+    pullWorkspaceChangesFromCloud: (options?: {
+        repairMode?: boolean;
+        forceCursorNull?: boolean;
+    }) => Promise<boolean>;
+    pushWorkspaceChangesToCloud: (signature: string, options?: {
+        forceAllAiProfiles?: boolean;
+        repairMode?: boolean;
+    }) => Promise<boolean>;
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    isAuthenticated: boolean;
+    checkAuthSession: () => Promise<boolean>;
+}
+export declare function createSyncRecoveryCoordinator({ currentWorkspaceId, taxonomyStateFingerprint, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, lastBootstrapPhaseRef, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspaceStartupRepairRanRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, workspacePullCursorRef, workspaceAttachBootstrapBaselineSignatureRef, workspaceCaptureAttachBootstrapBaselineRef, workspacePendingSignatureRef, workspaceLastPushedSignatureRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, persistWorkspaceSyncPatch, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession }: CreateSyncRecoveryCoordinatorArgs): {
+    retryWorkspaceCloudSync: () => Promise<boolean>;
+    resetWorkspaceSyncCursorAndPull: () => Promise<void>;
+};
+export {};