@taskforcehq/taskforce 0.3.168

package/dist/hooks/useSyncOrchestrator.js

@@ -0,0 +1,1427 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { calculateWorkspaceRetryDelayMs, ensureCloudWorkspaceReadyForSyncService, runWorkspacePullSyncService, runWorkspacePushSyncService, syncUserGlobalSettingsService } from '../sync/syncService';
+import { buildWorkspaceSyncPayloadModel, buildWorkspaceSyncSignatureModel } from '../sync/workspaceSyncModel';
+import { useWorkspaceSyncController } from './useWorkspaceSyncController';
+import { useRealtimeSync } from './useRealtimeSync';
+import { setLocale as setAppLocale } from '../localization';
+// ---------------------------------------------------------------------------
+// Module-level constants & helpers (moved from useTaskforce)
+// ---------------------------------------------------------------------------
+const USER_GLOBAL_SYNC_META_KEY = 'taskforce.userGlobalSyncMeta.v1';
+const SYNC_DEBUG_LOG_KEY = 'taskforce.syncDebug.v1';
+const WORKSPACE_HYDRATION_PUSH_BLOCK_WARNING = 'Local changes queued — waiting for initial cloud pull before upload.';
+const WORKSPACE_HYDRATION_PUSH_BLOCK_ESCAPE_MS = 45_000;
+const WORKSPACE_HYDRATION_PUSH_BLOCK_RECOVERY_COOLDOWN_MS = 15_000;
+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;
+    }
+}
+function logSyncDebug(event, details) {
+    if (!isSyncDebugLoggingEnabled())
+        return;
+    const payload = details && typeof details === 'object' ? details : {};
+    console.info('[Taskforce Sync]', event, payload);
+}
+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 {};
+    }
+}
+function writeUserGlobalSyncMeta(next) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.setItem(USER_GLOBAL_SYNC_META_KEY, JSON.stringify(next));
+    }
+    catch {
+        // best-effort only
+    }
+}
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+export function useSyncOrchestrator(input) {
+    const { currentWorkspaceId, cloudAuthConfigured, runtimeMode, isAuthenticated, authUserId, projectName, resolveCloudAuthUrl, resolveWebSocketUrl, realtimeSyncEnabled, tasks, archivedTasks, taxonomies, setupState, globalTheme, locale, globalWeekStartsOn, themeUseGlobalDefault, setTasks, setArchivedTasks, setAuthBlocked, setIsAuthenticated, checkAuthSession, setGlobalTheme, setCurrentTheme, setSetupState, setLocale, setGlobalWeekStartsOn } = input;
+    // -----------------------------------------------------------------------
+    // Sync state
+    // -----------------------------------------------------------------------
+    const [userGlobalSyncStatus, setUserGlobalSyncStatus] = useState('disconnected');
+    const [userGlobalLastSyncedAt, setUserGlobalLastSyncedAt] = useState(null);
+    const [userGlobalSyncPendingChanges, setUserGlobalSyncPendingChanges] = useState(0);
+    const [userGlobalSyncError, setUserGlobalSyncError] = useState(null);
+    const [workspaceLastPullAt, setWorkspaceLastPullAt] = useState(null);
+    const [workspaceLastPushAt, setWorkspaceLastPushAt] = useState(null);
+    const [workspaceLastErrorAt, setWorkspaceLastErrorAt] = useState(null);
+    const [workspaceLastErrorMessage, setWorkspaceLastErrorMessage] = useState(null);
+    const [workspaceLastWarningMessage, setWorkspaceLastWarningMessage] = useState(null);
+    const [workspaceCloudSyncEnabled, setWorkspaceCloudSyncEnabled] = useState(false);
+    const [workspaceSyncSourceOfTruth, setWorkspaceSyncSourceOfTruth] = useState(null);
+    const [workspaceSyncOnboardingCompleted, setWorkspaceSyncOnboardingCompleted] = useState(false);
+    const [workspaceSyncReady, setWorkspaceSyncReady] = useState(false);
+    const [workspaceCloudHydrated, setWorkspaceCloudHydrated] = useState(false);
+    const [workspaceSyncDocuments, setWorkspaceSyncDocuments] = useState([]);
+    const [workspaceSyncDocumentsFingerprint, setWorkspaceSyncDocumentsFingerprint] = useState('');
+    const [realtimeConnectionState, setRealtimeConnectionState] = useState('degraded-fallback');
+    const [realtimeTelemetry, setRealtimeTelemetry] = useState({
+        accepted: 0,
+        duplicateDiscarded: 0,
+        outOfOrderDiscarded: 0,
+        invalidDiscarded: 0,
+        recoveryTriggered: 0
+    });
+    // -----------------------------------------------------------------------
+    // Sync refs
+    // -----------------------------------------------------------------------
+    const userSettingsSyncInFlightRef = useRef(false);
+    const userSettingsRetryTimeoutRef = useRef(null);
+    const userSettingsRetryAttemptRef = useRef(0);
+    const applyingRemoteUserSettingsRef = useRef(false);
+    const initialUserSettingsSyncCompletedRef = useRef(new Set());
+    const lastUserGlobalSyncSignatureRef = useRef('');
+    const workspaceSyncDocumentsFingerprintRef = useRef('');
+    const syncInFlightRef = useRef(false);
+    const workspacePushBlockedSinceRef = useRef(new Map());
+    const workspacePushBlockedRecoveryAtRef = useRef(new Map());
+    const realtimePullDebounceRef = useRef(null);
+    const realtimeSuppressedEventIdsRef = useRef(new Set());
+    const realtimeSuppressedEventQueueRef = useRef([]);
+    const realtimeTelemetryReportedAtRef = useRef(0);
+    const realtimeTelemetrySnapshotRef = useRef({
+        accepted: 0,
+        duplicateDiscarded: 0,
+        outOfOrderDiscarded: 0,
+        invalidDiscarded: 0,
+        recoveryTriggered: 0
+    });
+    // Stable ref so ensureWorkspaceSyncReady can schedule a retry via pullFromCloud
+    // without creating a forward-reference dependency cycle.
+    const pullFromCloudRef = useRef(() => Promise.resolve(false));
+    // Mirror of workspaceSyncOnboardingCompleted state — kept as a ref so the
+    // pullWorkspaceChangesFromCloud callback can read the current value without
+    // needing to be re-created every time the state changes (stale closure guard).
+    const onboardingCompletedRef = useRef(false);
+    const syncUserGlobalSettingsRef = useRef(async () => { });
+    const clearUserSettingsRetry = useCallback(() => {
+        if (userSettingsRetryTimeoutRef.current !== null) {
+            window.clearTimeout(userSettingsRetryTimeoutRef.current);
+            userSettingsRetryTimeoutRef.current = null;
+        }
+    }, []);
+    const scheduleUserSettingsRetry = useCallback((minDelayMs) => {
+        if (typeof window === 'undefined')
+            return;
+        clearUserSettingsRetry();
+        const nextAttempt = Math.max(1, Math.floor(userSettingsRetryAttemptRef.current) + 1);
+        userSettingsRetryAttemptRef.current = nextAttempt;
+        const computedDelay = calculateWorkspaceRetryDelayMs(nextAttempt);
+        const retryAfterFloor = Number.isFinite(Number(minDelayMs)) ? Math.max(0, Math.floor(Number(minDelayMs))) : 0;
+        const delayMs = Math.max(computedDelay, retryAfterFloor);
+        userSettingsRetryTimeoutRef.current = window.setTimeout(() => {
+            userSettingsRetryTimeoutRef.current = null;
+            void syncUserGlobalSettingsRef.current({ preferCloudOnFirstSync: false });
+        }, delayMs);
+    }, [clearUserSettingsRetry]);
+    // -----------------------------------------------------------------------
+    // Reset document fingerprint and push watermarks when workspace changes
+    // -----------------------------------------------------------------------
+    useEffect(() => {
+        workspaceSyncDocumentsFingerprintRef.current = '';
+        setWorkspaceSyncDocuments([]);
+        setWorkspaceSyncDocumentsFingerprint('');
+        setWorkspaceLastWarningMessage(null);
+        workspacePushBlockedSinceRef.current.delete(currentWorkspaceId);
+        workspacePushBlockedRecoveryAtRef.current.delete(currentWorkspaceId);
+        workspaceLastPushedWatermarksRef.current = new Map();
+        workspaceLastPushedDocumentPathsRef.current = new Set();
+        workspaceLastPushedDocumentWatermarksRef.current = new Map();
+        realtimeSuppressedEventIdsRef.current = new Set();
+        realtimeSuppressedEventQueueRef.current = [];
+    }, [currentWorkspaceId]);
+    // -----------------------------------------------------------------------
+    // useWorkspaceSyncController
+    // -----------------------------------------------------------------------
+    const handleFailureRecorded = useCallback(() => {
+        setWorkspaceLastErrorAt(new Date().toISOString());
+    }, []);
+    const { workspaceRetryAt, isWorkspacePullRetryPending, workspaceBootstrapSyncInProgress, setWorkspaceBootstrapSyncInProgress, workspaceBootstrapSyncPages, setWorkspaceBootstrapSyncPages, workspaceBootstrapSyncAppliedChanges, setWorkspaceBootstrapSyncAppliedChanges, workspaceSyncFailureCount, workspaceSyncRetryScheduledCount, workspaceSyncAuthFailureCount, workspaceSyncLastFailureSource, workspaceSyncLastFailureStatusCode, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspacePullCursorRef, workspacePullBootstrapDoneRef, workspaceBackfillForcedRef, workspaceSyncReadyRef, workspaceCloudHydratedRef, clearWorkspaceRetry, scheduleWorkspacePullRetry, isWorkspacePullCooldownActive, markWorkspacePullCooldown, tryAcquireWorkspacePullLease, releaseWorkspacePullLease, recordWorkspaceSyncFailure, incrementWorkspaceSyncAuthFailure, persistWorkspaceSyncPatch, loadWorkspaceSyncState, applyWorkspaceSyncStateSnapshot, saveWorkspaceCloudSyncSettings: saveWorkspaceCloudSyncSettingsBase } = useWorkspaceSyncController({
+        currentWorkspaceId,
+        setWorkspaceSyncReady,
+        setWorkspaceCloudHydrated,
+        onFailureRecorded: handleFailureRecorded,
+        setWorkspaceCloudSyncEnabled,
+        setWorkspaceSyncSourceOfTruth,
+        setWorkspaceSyncOnboardingCompleted,
+        setUserGlobalLastSyncedAt,
+        setWorkspaceLastPullAt,
+        setWorkspaceLastPushAt
+    });
+    // -----------------------------------------------------------------------
+    // Per-task watermark map: tracks the updatedAt|createdAt of each task as of its last
+    // successful push. Used by buildWorkspaceSyncPayload to skip unchanged tasks (dirty push).
+    const workspaceLastPushedWatermarksRef = useRef(new Map());
+    // Tracks document paths present at last successful push so removed docs can emit
+    // document-delete operations on the next payload build.
+    const workspaceLastPushedDocumentPathsRef = useRef(new Set());
+    // Tracks last pushed document updatedAt per path to reduce unchanged document-upsert churn.
+    const workspaceLastPushedDocumentWatermarksRef = useRef(new Map());
+    // User global settings sync helpers
+    // -----------------------------------------------------------------------
+    const getLocalUserSyncUpdatedAt = useCallback((userId) => {
+        const key = String(userId || '').trim();
+        if (!key)
+            return null;
+        const meta = readUserGlobalSyncMeta();
+        const value = meta[key]?.updatedAt;
+        return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+    }, []);
+    const setLocalUserSyncUpdatedAt = useCallback((userId, updatedAt) => {
+        const key = String(userId || '').trim();
+        const ts = String(updatedAt || '').trim();
+        if (!key || !ts)
+            return;
+        const meta = readUserGlobalSyncMeta();
+        meta[key] = { updatedAt: ts };
+        writeUserGlobalSyncMeta(meta);
+    }, []);
+    const buildUserGlobalSyncPayload = useCallback(() => {
+        const mode = setupState?.mode === 'operations' ? 'operations' : 'core';
+        return {
+            theme: globalTheme,
+            operatingMode: mode,
+            localization: {
+                locale,
+                weekStartsOn: globalWeekStartsOn
+            }
+        };
+    }, [globalTheme, setupState?.mode, locale, globalWeekStartsOn]);
+    const applyRemoteUserGlobalSyncPayload = useCallback(async (remote) => {
+        if (!remote || typeof remote !== 'object')
+            return;
+        applyingRemoteUserSettingsRef.current = true;
+        try {
+            const patch = {};
+            if (remote.theme === 'dark' || remote.theme === 'light' || remote.theme === 'midnight') {
+                setGlobalTheme(remote.theme);
+                if (themeUseGlobalDefault)
+                    setCurrentTheme(remote.theme);
+                patch.theme = remote.theme;
+            }
+            if (remote.operatingMode === 'core' || remote.operatingMode === 'operations') {
+                setSetupState((prev) => prev ? { ...prev, mode: remote.operatingMode } : prev);
+                patch.setup = { mode: remote.operatingMode };
+            }
+            if (remote.localization && typeof remote.localization === 'object') {
+                const localizationPatch = {};
+                if (typeof remote.localization.locale === 'string' && remote.localization.locale.trim().length > 0) {
+                    const applied = setAppLocale(remote.localization.locale.trim());
+                    setLocale(applied);
+                }
+                const weekStartsOn = String(remote.localization.weekStartsOn || '').trim().toLowerCase();
+                if (weekStartsOn === 'sunday' || weekStartsOn === 'monday') {
+                    setGlobalWeekStartsOn(weekStartsOn);
+                    localizationPatch.weekStartsOn = weekStartsOn;
+                }
+                if (Object.keys(localizationPatch).length > 0) {
+                    patch.schedulePreferences = localizationPatch;
+                }
+            }
+            if (Object.keys(patch).length > 0) {
+                await fetch('/api/taskforce/global-settings', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    credentials: 'include',
+                    body: JSON.stringify(patch)
+                });
+            }
+        }
+        finally {
+            applyingRemoteUserSettingsRef.current = false;
+        }
+    }, [themeUseGlobalDefault, setGlobalTheme, setCurrentTheme, setSetupState, setLocale, setGlobalWeekStartsOn]);
+    const syncUserGlobalSettings = useCallback(async (options) => {
+        const preferCloudOnFirstSync = options?.preferCloudOnFirstSync !== false;
+        if (!cloudAuthConfigured)
+            return;
+        if (runtimeMode !== 'local' || !isAuthenticated) {
+            clearUserSettingsRetry();
+            userSettingsRetryAttemptRef.current = 0;
+            setUserGlobalSyncStatus('disconnected');
+            return;
+        }
+        const userId = String(authUserId || '').trim();
+        if (!userId || userId === 'anonymous') {
+            clearUserSettingsRetry();
+            userSettingsRetryAttemptRef.current = 0;
+            setUserGlobalSyncStatus('disconnected');
+            return;
+        }
+        if (userSettingsSyncInFlightRef.current)
+            return;
+        setUserGlobalSyncStatus('syncing');
+        setUserGlobalSyncError(null);
+        userSettingsSyncInFlightRef.current = true;
+        try {
+            const syncResult = await syncUserGlobalSettingsService({
+                resolveCloudAuthUrl,
+                userId,
+                preferCloudOnFirstSync,
+                getLocalUpdatedAt: getLocalUserSyncUpdatedAt,
+                buildLocalSettings: buildUserGlobalSyncPayload,
+                applyRemoteSettings: applyRemoteUserGlobalSyncPayload
+            });
+            if (!syncResult.success) {
+                setUserGlobalSyncStatus('error');
+                if (syncResult.transient) {
+                    setUserGlobalSyncError(syncResult.error || 'Sync failed temporarily. Retrying automatically.');
+                    scheduleUserSettingsRetry(syncResult.retryAfterMs);
+                }
+                else {
+                    clearUserSettingsRetry();
+                    userSettingsRetryAttemptRef.current = 0;
+                    setUserGlobalSyncError(syncResult.error || 'Sync failed.');
+                }
+                return;
+            }
+            clearUserSettingsRetry();
+            userSettingsRetryAttemptRef.current = 0;
+            const syncedAt = String(syncResult.updatedAt || '').trim() || new Date().toISOString();
+            setLocalUserSyncUpdatedAt(userId, syncedAt);
+            setUserGlobalLastSyncedAt(syncedAt);
+            setUserGlobalSyncPendingChanges(0);
+            setUserGlobalSyncStatus('idle');
+            setUserGlobalSyncError(null);
+            initialUserSettingsSyncCompletedRef.current.add(userId);
+            if (syncResult.mode === 'pulled') {
+                lastUserGlobalSyncSignatureRef.current = '';
+            }
+        }
+        catch {
+            setUserGlobalSyncStatus('error');
+            setUserGlobalSyncError('Sync failed temporarily. Retrying automatically.');
+            scheduleUserSettingsRetry();
+        }
+        finally {
+            userSettingsSyncInFlightRef.current = false;
+        }
+    }, [
+        runtimeMode,
+        isAuthenticated,
+        authUserId,
+        getLocalUserSyncUpdatedAt,
+        setLocalUserSyncUpdatedAt,
+        applyRemoteUserGlobalSyncPayload,
+        buildUserGlobalSyncPayload,
+        resolveCloudAuthUrl,
+        cloudAuthConfigured,
+        clearUserSettingsRetry,
+        scheduleUserSettingsRetry
+    ]);
+    useEffect(() => {
+        syncUserGlobalSettingsRef.current = syncUserGlobalSettings;
+    }, [syncUserGlobalSettings]);
+    useEffect(() => {
+        return () => {
+            clearUserSettingsRetry();
+        };
+    }, [clearUserSettingsRetry]);
+    // -----------------------------------------------------------------------
+    // Workspace sync helpers
+    // -----------------------------------------------------------------------
+    const ensureCloudWorkspaceReadyForSync = useCallback(async () => {
+        return ensureCloudWorkspaceReadyForSyncService({
+            cloudAuthConfigured,
+            runtimeMode,
+            isAuthenticated,
+            resolveCloudAuthUrl,
+            workspaceId: currentWorkspaceId,
+            workspaceName: projectName || currentWorkspaceId
+        });
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        isAuthenticated,
+        resolveCloudAuthUrl,
+        currentWorkspaceId,
+        projectName
+    ]);
+    const buildWorkspaceSyncPayload = useCallback(() => {
+        return buildWorkspaceSyncPayloadModel({
+            tasks: tasks || [],
+            archivedTasks: archivedTasks || [],
+            lastPushedTaskIds: workspaceLastPushedTaskIdsRef.current,
+            pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
+            taxonomies: taxonomies || [],
+            documents: workspaceSyncDocuments || [],
+            lastPushedDocumentPaths: workspaceLastPushedDocumentPathsRef.current,
+            lastPushedDocumentWatermarks: workspaceLastPushedDocumentWatermarksRef.current,
+            lastPushedWatermarks: workspaceLastPushedWatermarksRef.current
+        });
+    }, [tasks, archivedTasks, taxonomies, workspaceSyncDocuments]);
+    // Fire-and-forget: persist browser-side sync event to the local SQLite event log.
+    const reportSyncEvent = useCallback((workspaceId, event) => {
+        if (runtimeMode !== 'local')
+            return;
+        fetch('/api/taskforce/sync/events', {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ...event, workspaceId })
+        }).catch((error) => {
+            logSyncDebug('sync_event_post_failed', {
+                workspaceId,
+                eventType: event.eventType,
+                status: event.status,
+                error: String(error?.message || error || '')
+            });
+        });
+    }, [runtimeMode]);
+    const buildWorkspaceSyncSignature = useCallback(() => {
+        return buildWorkspaceSyncSignatureModel({
+            workspaceId: currentWorkspaceId,
+            tasks: tasks || [],
+            archivedTasks: archivedTasks || [],
+            pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
+            taxonomies: taxonomies || [],
+            documents: workspaceSyncDocuments || []
+        });
+    }, [tasks, archivedTasks, currentWorkspaceId, taxonomies, workspaceSyncDocuments]);
+    const refreshWorkspaceSyncDocumentsSnapshot = useCallback(async () => {
+        if (runtimeMode !== 'local')
+            return;
+        const workspaceKey = String(currentWorkspaceId || '').trim();
+        if (!workspaceKey || workspaceKey.toLowerCase() === 'default')
+            return;
+        try {
+            const res = await fetch(`/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(workspaceKey)}`, {
+                method: 'GET',
+                credentials: 'include'
+            });
+            if (!res.ok)
+                return;
+            const data = await res.json().catch(() => ({}));
+            const docs = Array.isArray(data?.documents)
+                ? data.documents
+                    .map((entry) => ({
+                    path: String(entry?.path || '').trim(),
+                    updatedAt: String(entry?.updatedAt || '').trim(),
+                    content: typeof entry?.content === 'string' ? entry.content : ''
+                }))
+                    .filter((entry) => entry.path.length > 0)
+                : [];
+            const fingerprint = typeof data?.fingerprint === 'string'
+                ? data.fingerprint
+                : JSON.stringify(docs.map((entry) => `${entry.path}:${entry.updatedAt}:${entry.content.length}`).sort());
+            if (fingerprint === workspaceSyncDocumentsFingerprintRef.current)
+                return;
+            workspaceSyncDocumentsFingerprintRef.current = fingerprint;
+            setWorkspaceSyncDocuments(docs);
+            setWorkspaceSyncDocumentsFingerprint(fingerprint);
+        }
+        catch (error) {
+            const detail = String(error?.message || error || '');
+            logSyncDebug('documents_snapshot_refresh_failed', {
+                workspaceId: workspaceKey,
+                error: detail
+            });
+            reportSyncEvent(workspaceKey, {
+                eventType: 'push',
+                status: 'error',
+                errorMessage: `Workspace documents snapshot refresh failed: ${detail}`
+            });
+        }
+    }, [runtimeMode, currentWorkspaceId, reportSyncEvent]);
+    const handleSyncAuthFailure = useCallback(async (source, statusCode) => {
+        clearWorkspaceRetry();
+        logSyncDebug('sync_auth_failure', { source, status: statusCode, workspaceId: currentWorkspaceId });
+        incrementWorkspaceSyncAuthFailure();
+        recordWorkspaceSyncFailure(source, statusCode);
+        setUserGlobalSyncStatus('error');
+        const message = 'Session expired. Sign in again to resume cloud sync.';
+        setUserGlobalSyncError(message);
+        setWorkspaceLastErrorMessage(message);
+        setAuthBlocked(true);
+        setIsAuthenticated(false);
+        await checkAuthSession();
+    }, [clearWorkspaceRetry, currentWorkspaceId, checkAuthSession, recordWorkspaceSyncFailure, incrementWorkspaceSyncAuthFailure, setAuthBlocked, setIsAuthenticated]);
+    const ensureWorkspaceSyncReady = useCallback(async () => {
+        const workspaceKey = String(currentWorkspaceId || '').trim();
+        if (!workspaceKey || workspaceKey.toLowerCase() === 'default') {
+            logSyncDebug('sync_ready_blocked_unresolved_workspace', { workspaceKey, runtimeMode });
+            setUserGlobalSyncStatus('error');
+            const message = 'Workspace sync blocked: local workspace ID is unresolved.';
+            setUserGlobalSyncError(message);
+            setWorkspaceLastErrorMessage(message);
+            setWorkspaceLastErrorAt(new Date().toISOString());
+            setWorkspaceSyncReady(false);
+            return false;
+        }
+        if (workspaceSyncReadyRef.current.has(workspaceKey))
+            return true;
+        const ensured = await ensureCloudWorkspaceReadyForSync();
+        if (!ensured.success) {
+            logSyncDebug('sync_ready_failed', { workspaceKey, statusCode: ensured.statusCode || null, error: ensured.error || null });
+            if (ensured.statusCode === 401) {
+                await handleSyncAuthFailure('handshake', 401);
+                return false;
+            }
+            if (ensured.statusCode === 429) {
+                recordWorkspaceSyncFailure('handshake', 429);
+                setUserGlobalSyncStatus('error');
+                const message = ensured.error || 'Sync paused — rate limit reached. Will retry automatically.';
+                setUserGlobalSyncError(message);
+                setWorkspaceLastErrorMessage(message);
+                setWorkspaceLastErrorAt(new Date().toISOString());
+                setWorkspaceSyncReady(false);
+                scheduleWorkspacePullRetry(() => pullFromCloudRef.current(), {
+                    minDelayMs: ensured.retryAfterMs,
+                    workspaceId: workspaceKey
+                });
+                return false;
+            }
+            recordWorkspaceSyncFailure('handshake');
+            setUserGlobalSyncStatus('error');
+            const message = ensured.error || 'Workspace sync handshake failed.';
+            setUserGlobalSyncError(message);
+            setWorkspaceLastErrorMessage(message);
+            setWorkspaceSyncReady(false);
+            return false;
+        }
+        logSyncDebug('sync_ready_ok', { workspaceKey });
+        workspaceSyncReadyRef.current.add(workspaceKey);
+        setWorkspaceSyncReady(true);
+        return true;
+    }, [
+        currentWorkspaceId,
+        ensureCloudWorkspaceReadyForSync,
+        runtimeMode,
+        recordWorkspaceSyncFailure,
+        handleSyncAuthFailure,
+        scheduleWorkspacePullRetry
+    ]);
+    const pushWorkspaceChangesToCloud = useCallback(async (signature) => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return false;
+        if (!isAuthenticated) {
+            const authed = await checkAuthSession();
+            if (!authed)
+                return false;
+        }
+        const workspaceKey = String(currentWorkspaceId || '').trim();
+        if (!workspaceKey || workspaceKey.toLowerCase() === 'default')
+            return false;
+        if (workspaceSyncSourceOfTruth === 'cloud' && !workspaceCloudHydratedRef.current.has(workspaceKey)) {
+            workspacePendingSignatureRef.current = signature;
+            const now = Date.now();
+            const blockedAt = workspacePushBlockedSinceRef.current.get(workspaceKey) || now;
+            workspacePushBlockedSinceRef.current.set(workspaceKey, blockedAt);
+            setWorkspaceLastWarningMessage(WORKSPACE_HYDRATION_PUSH_BLOCK_WARNING);
+            if (isWorkspacePullRetryPending()) {
+                const blockedMs = now - blockedAt;
+                const nextRecoveryAt = workspacePushBlockedRecoveryAtRef.current.get(workspaceKey) || 0;
+                if (blockedMs >= WORKSPACE_HYDRATION_PUSH_BLOCK_ESCAPE_MS && now >= nextRecoveryAt) {
+                    workspacePushBlockedRecoveryAtRef.current.set(workspaceKey, now + WORKSPACE_HYDRATION_PUSH_BLOCK_RECOVERY_COOLDOWN_MS);
+                    logSyncDebug('push_blocked_waiting_hydration_force_pull', {
+                        workspaceId: workspaceKey,
+                        blockedMs
+                    });
+                    clearWorkspaceRetry();
+                    window.setTimeout(() => {
+                        void pullFromCloudRef.current();
+                    }, 120);
+                }
+            }
+            return false;
+        }
+        if (workspacePushInFlightRef.current) {
+            workspacePendingSignatureRef.current = signature;
+            return false;
+        }
+        workspacePushInFlightRef.current = true;
+        setUserGlobalSyncStatus('syncing');
+        setUserGlobalSyncError(null);
+        const pushStartedAtMs = Date.now();
+        try {
+            await refreshWorkspaceSyncDocumentsSnapshot();
+            const ready = await ensureWorkspaceSyncReady();
+            if (!ready)
+                return false;
+            const payload = buildWorkspaceSyncPayload();
+            logSyncDebug('push_start', {
+                workspaceId: currentWorkspaceId,
+                changeCount: payload.changes.length,
+                deleteCount: payload.deleteTaskIds.size
+            });
+            setUserGlobalSyncPendingChanges(payload.changes.length);
+            const pushResult = await runWorkspacePushSyncService({
+                resolveCloudAuthUrl,
+                workspaceId: currentWorkspaceId,
+                payload,
+                ensureCloudWorkspaceReadyForSync
+            });
+            if (!pushResult.success) {
+                if (pushResult.status === 401) {
+                    await handleSyncAuthFailure('push', 401);
+                    return false;
+                }
+                logSyncDebug('push_failed_http', {
+                    workspaceId: currentWorkspaceId,
+                    status: pushResult.status || 0,
+                    error: pushResult.error || null,
+                    code: pushResult.code || null,
+                    elapsedMs: Date.now() - pushStartedAtMs,
+                    requestMs: pushResult.requestMs
+                });
+                recordWorkspaceSyncFailure('push', pushResult.status || undefined);
+                setUserGlobalSyncStatus('error');
+                const message = pushResult.error
+                    ? `Workspace sync push failed (${pushResult.status || 0}): ${pushResult.error}`
+                    : `Workspace sync push failed (${pushResult.status || 0})`;
+                setUserGlobalSyncError(message);
+                setWorkspaceLastErrorMessage(message);
+                return false;
+            }
+            workspaceLastPushedSignatureRef.current = signature;
+            workspaceLastPushedTaskIdsRef.current = pushResult.currentTaskIds;
+            workspaceLastPushedDocumentPathsRef.current = new Set(pushResult.currentDocumentPaths);
+            workspaceLastPushedDocumentWatermarksRef.current = new Map(pushResult.currentDocumentWatermarks);
+            // Merge newly pushed watermarks into the per-task map so subsequent
+            // pushes skip tasks that haven't changed since this push.
+            for (const [taskId, watermark] of pushResult.pushedWatermarks) {
+                workspaceLastPushedWatermarksRef.current.set(taskId, watermark);
+            }
+            if (pushResult.deleteTaskIds.size > 0) {
+                for (const taskId of pushResult.deleteTaskIds) {
+                    workspaceDeletedTaskIdsRef.current.delete(taskId);
+                    workspaceLastPushedWatermarksRef.current.delete(taskId);
+                }
+            }
+            const syncedAt = pushResult.syncedAt || new Date().toISOString();
+            logSyncDebug('push_success', {
+                workspaceId: currentWorkspaceId,
+                syncedAt,
+                changeCount: pushResult.changeCount,
+                deleteCount: pushResult.deleteCount,
+                elapsedMs: Date.now() - pushStartedAtMs,
+                requestMs: pushResult.requestMs
+            });
+            setUserGlobalLastSyncedAt(syncedAt);
+            setWorkspaceLastPushAt(syncedAt);
+            setUserGlobalSyncPendingChanges(0);
+            setUserGlobalSyncStatus('idle');
+            setUserGlobalSyncError(null);
+            setWorkspaceLastErrorMessage(null);
+            setWorkspaceLastErrorAt(null);
+            if (Array.isArray(pushResult.emittedEventIds) && pushResult.emittedEventIds.length > 0) {
+                for (const rawEventId of pushResult.emittedEventIds) {
+                    const eventId = String(rawEventId || '').trim();
+                    if (!eventId)
+                        continue;
+                    if (realtimeSuppressedEventIdsRef.current.has(eventId))
+                        continue;
+                    realtimeSuppressedEventIdsRef.current.add(eventId);
+                    realtimeSuppressedEventQueueRef.current.push(eventId);
+                }
+                while (realtimeSuppressedEventQueueRef.current.length > 2048) {
+                    const stale = realtimeSuppressedEventQueueRef.current.shift();
+                    if (stale)
+                        realtimeSuppressedEventIdsRef.current.delete(stale);
+                }
+            }
+            void persistWorkspaceSyncPatch({
+                lastPushAt: syncedAt,
+                lastSyncedAt: syncedAt
+            });
+            return true;
+        }
+        catch {
+            logSyncDebug('push_failed_exception', { workspaceId: currentWorkspaceId, elapsedMs: Date.now() - pushStartedAtMs });
+            recordWorkspaceSyncFailure('push');
+            setUserGlobalSyncStatus('error');
+            const message = 'Workspace sync push failed.';
+            setUserGlobalSyncError(message);
+            setWorkspaceLastErrorMessage(message);
+            return false;
+        }
+        finally {
+            workspacePushInFlightRef.current = false;
+            const pendingSignature = workspacePendingSignatureRef.current;
+            if (pendingSignature && pendingSignature !== workspaceLastPushedSignatureRef.current) {
+                workspacePendingSignatureRef.current = '';
+                window.setTimeout(() => {
+                    void pushWorkspaceChangesToCloud(pendingSignature);
+                }, 120);
+            }
+        }
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        isAuthenticated,
+        checkAuthSession,
+        workspaceCloudSyncEnabled,
+        workspaceSyncSourceOfTruth,
+        buildWorkspaceSyncPayload,
+        ensureWorkspaceSyncReady,
+        refreshWorkspaceSyncDocumentsSnapshot,
+        ensureCloudWorkspaceReadyForSync,
+        handleSyncAuthFailure,
+        recordWorkspaceSyncFailure,
+        clearWorkspaceRetry,
+        isWorkspacePullRetryPending,
+        currentWorkspaceId,
+        resolveCloudAuthUrl
+    ]);
+    const pullWorkspaceChangesFromCloud = useCallback(async () => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled) {
+            logSyncDebug('pull_abort', { reason: 'config_disabled', cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled });
+            return false;
+        }
+        if (!isAuthenticated) {
+            const authed = await checkAuthSession();
+            if (!authed) {
+                logSyncDebug('pull_abort', { reason: 'not_authenticated' });
+                return false;
+            }
+        }
+        const workspaceKey = String(currentWorkspaceId || '').trim();
+        if (!workspaceKey || workspaceKey.toLowerCase() === 'default') {
+            logSyncDebug('pull_abort', { reason: 'invalid_workspace', workspaceKey });
+            return false;
+        }
+        if (isWorkspacePullRetryPending()) {
+            logSyncDebug('pull_abort', { reason: 'retry_pending' });
+            return false;
+        }
+        if (workspacePullInFlightRef.current) {
+            logSyncDebug('pull_abort', { reason: 'already_in_flight' });
+            return false;
+        }
+        const leaseAcquired = await tryAcquireWorkspacePullLease(workspaceKey);
+        if (!leaseAcquired) {
+            markWorkspacePullCooldown(workspaceKey, 12_000);
+            logSyncDebug('pull_abort', { reason: 'non_leader_tab', workspaceId: workspaceKey });
+            return false;
+        }
+        workspacePullInFlightRef.current = true;
+        const bootstrapThisRun = !workspaceCloudHydratedRef.current.has(workspaceKey);
+        if (bootstrapThisRun) {
+            setWorkspaceBootstrapSyncInProgress(true);
+            setWorkspaceBootstrapSyncPages(0);
+            setWorkspaceBootstrapSyncAppliedChanges(0);
+        }
+        setUserGlobalSyncStatus('syncing');
+        setUserGlobalSyncError(null);
+        const pullStartedAtMs = Date.now();
+        try {
+            const ready = await ensureWorkspaceSyncReady();
+            if (!ready) {
+                logSyncDebug('pull_abort', { reason: 'ensure_ready_failed' });
+                return false;
+            }
+            const initialCursor = workspacePullBootstrapDoneRef.current
+                ? workspacePullCursorRef.current
+                : null;
+            logSyncDebug('pull_start', { workspaceId: currentWorkspaceId, cursor: initialCursor });
+            const pullResult = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl,
+                workspaceId: currentWorkspaceId,
+                cursor: initialCursor,
+                bootstrap: bootstrapThisRun,
+                ensureCloudWorkspaceReadyForSync,
+                maxPages: 20,
+                onPagePulled: bootstrapThisRun ? () => {
+                    setWorkspaceBootstrapSyncPages((prev) => prev + 1);
+                } : undefined,
+                onChangesApplied: bootstrapThisRun ? (count) => {
+                    setWorkspaceBootstrapSyncAppliedChanges((prev) => prev + count);
+                } : undefined
+            });
+            if (!pullResult.success) {
+                if (pullResult.kind === 'pull_http') {
+                    if (pullResult.status === 401) {
+                        await handleSyncAuthFailure('pull', 401);
+                        return false;
+                    }
+                    logSyncDebug('pull_failed_http', {
+                        workspaceId: currentWorkspaceId,
+                        status: pullResult.status || 0,
+                        cursor: pullResult.cursor,
+                        elapsedMs: Date.now() - pullStartedAtMs,
+                        requestMs: pullResult.pullRequestMs,
+                        applyMs: pullResult.applyMs
+                    });
+                    reportSyncEvent(currentWorkspaceId, {
+                        eventType: 'pull',
+                        status: 'error',
+                        statusCode: pullResult.status || 0,
+                        requestMs: pullResult.pullRequestMs
+                    });
+                    recordWorkspaceSyncFailure('pull', pullResult.status || undefined);
+                    setUserGlobalSyncStatus('error');
+                    const message = `Workspace sync pull failed (${pullResult.status || 0})`;
+                    setUserGlobalSyncError(message);
+                    setWorkspaceLastErrorMessage(message);
+                    if ((pullResult.status || 0) === 429 || (pullResult.status || 0) >= 500) {
+                        scheduleWorkspacePullRetry(() => pullFromCloudRef.current(), {
+                            minDelayMs: pullResult.retryAfterMs,
+                            workspaceId: workspaceKey
+                        });
+                    }
+                    else {
+                        clearWorkspaceRetry();
+                    }
+                    return false;
+                }
+                if (pullResult.kind === 'apply_auth') {
+                    await handleSyncAuthFailure('apply', 401);
+                    return false;
+                }
+                if (pullResult.kind === 'apply_all_candidates') {
+                    const applyFailures = pullResult.failures || [];
+                    logSyncDebug('apply_failed_all_candidates', {
+                        workspaceId: currentWorkspaceId,
+                        failures: applyFailures
+                    });
+                    setUserGlobalSyncStatus('error');
+                    const detail = applyFailures.length > 0 ? ` [${applyFailures.join(', ')}]` : '';
+                    recordWorkspaceSyncFailure('apply');
+                    const message = `Workspace sync apply failed${detail}`;
+                    setUserGlobalSyncError(message);
+                    setWorkspaceLastErrorMessage(message);
+                    if (pullResult.hasTransientApplyFailure) {
+                        scheduleWorkspacePullRetry(() => pullFromCloudRef.current(), {
+                            workspaceId: workspaceKey
+                        });
+                    }
+                    else {
+                        clearWorkspaceRetry();
+                    }
+                    return false;
+                }
+                if (pullResult.kind === 'apply_payload') {
+                    logSyncDebug('apply_failed_payload', {
+                        workspaceId: currentWorkspaceId,
+                        error: String(pullResult.error || '')
+                    });
+                    setUserGlobalSyncStatus('error');
+                    recordWorkspaceSyncFailure('apply');
+                    const message = String(pullResult.error || 'Workspace sync apply failed.');
+                    setUserGlobalSyncError(message);
+                    setWorkspaceLastErrorMessage(message);
+                    return false;
+                }
+                logSyncDebug('pull_failed_exception', { workspaceId: currentWorkspaceId, elapsedMs: Date.now() - pullStartedAtMs });
+                recordWorkspaceSyncFailure('pull');
+                setUserGlobalSyncStatus('error');
+                const message = 'Workspace sync pull failed.';
+                setUserGlobalSyncError(message);
+                setWorkspaceLastErrorMessage(message);
+                scheduleWorkspacePullRetry(() => pullFromCloudRef.current(), {
+                    workspaceId: workspaceKey
+                });
+                return false;
+            }
+            if (pullResult.pulledDeleteTaskIds.size > 0) {
+                setTasks((prev) => prev.filter((task) => !pullResult.pulledDeleteTaskIds.has(String(task.id || ''))));
+                setArchivedTasks((prev) => prev.filter((task) => !pullResult.pulledDeleteTaskIds.has(String(task.id || ''))));
+            }
+            const decryptFailures = Array.isArray(pullResult.documentDecryptFailures)
+                ? pullResult.documentDecryptFailures.filter((value) => String(value || '').trim().length > 0)
+                : [];
+            if (decryptFailures.length > 0) {
+                const warning = `Some synced documents could not be decrypted (${decryptFailures.length}).`;
+                setWorkspaceLastWarningMessage(warning);
+                logSyncDebug('pull_document_decrypt_partial_failure', {
+                    workspaceId: currentWorkspaceId,
+                    count: decryptFailures.length,
+                    paths: decryptFailures
+                });
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'apply',
+                    status: 'error',
+                    errorMessage: `${warning} paths=${decryptFailures.join(', ')}`,
+                    changeCount: pullResult.appliedChanges
+                });
+            }
+            else {
+                setWorkspaceLastWarningMessage(null);
+            }
+            workspacePullCursorRef.current = pullResult.cursor || null;
+            workspacePullBootstrapDoneRef.current = true;
+            workspaceCloudHydratedRef.current.add(workspaceKey);
+            workspacePushBlockedSinceRef.current.delete(workspaceKey);
+            workspacePushBlockedRecoveryAtRef.current.delete(workspaceKey);
+            setWorkspaceCloudHydrated(true);
+            // If a local mutation happened before initial cloud hydration finished, flush it now.
+            const currentSignature = buildWorkspaceSyncSignature();
+            if (currentSignature && currentSignature !== workspaceLastPushedSignatureRef.current) {
+                workspacePendingSignatureRef.current = currentSignature;
+            }
+            if (pullResult.appliedChanges > 0 && (pullResult.pulledActiveUpserts || pullResult.pulledArchivedUpserts)) {
+                // Source of truth for UI is local DB after apply-local writes.
+                try {
+                    const refreshRequests = [];
+                    if (pullResult.pulledActiveUpserts) {
+                        refreshRequests.push(fetch('/api/taskforce/tasks', {
+                            method: 'GET',
+                            credentials: 'include'
+                        }));
+                    }
+                    if (pullResult.pulledArchivedUpserts) {
+                        refreshRequests.push(fetch('/api/taskforce/archive', {
+                            method: 'GET',
+                            credentials: 'include'
+                        }));
+                    }
+                    const refreshResponses = await Promise.all(refreshRequests);
+                    for (const response of refreshResponses) {
+                        if (!response.ok)
+                            continue;
+                        const data = await response.json().catch(() => ({}));
+                        if (Array.isArray(data?.tasks)) {
+                            setTasks(data.tasks);
+                        }
+                        else if (Array.isArray(data?.archived)) {
+                            setArchivedTasks(data.archived);
+                        }
+                    }
+                }
+                catch {
+                    logSyncDebug('pull_local_refresh_failed', {
+                        workspaceId: currentWorkspaceId,
+                        appliedChanges: pullResult.appliedChanges
+                    });
+                    reportSyncEvent(currentWorkspaceId, {
+                        eventType: 'apply',
+                        status: 'error',
+                        errorMessage: 'Local state refresh failed after apply-local.',
+                        changeCount: pullResult.appliedChanges
+                    });
+                }
+            }
+            const syncedAt = pullResult.syncedAt || new Date().toISOString();
+            logSyncDebug('pull_success', {
+                workspaceId: currentWorkspaceId,
+                syncedAt,
+                appliedChanges: pullResult.appliedChanges,
+                pulledDeleteCount: pullResult.pulledDeleteTaskIds.size,
+                cursor: workspacePullCursorRef.current,
+                elapsedMs: Date.now() - pullStartedAtMs,
+                requestMs: pullResult.pullRequestMs,
+                applyMs: pullResult.applyMs,
+                pages: pullResult.pages
+            });
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: 'pull',
+                status: 'success',
+                changeCount: pullResult.appliedChanges,
+                requestMs: pullResult.pullRequestMs
+            });
+            setUserGlobalLastSyncedAt(syncedAt);
+            setWorkspaceLastPullAt(syncedAt);
+            setUserGlobalSyncPendingChanges(0);
+            setUserGlobalSyncStatus('idle');
+            setUserGlobalSyncError(null);
+            setWorkspaceLastErrorMessage(null);
+            setWorkspaceLastErrorAt(null);
+            clearWorkspaceRetry();
+            void persistWorkspaceSyncPatch({
+                pullCursor: workspacePullCursorRef.current,
+                lastPullAt: syncedAt,
+                lastSyncedAt: syncedAt
+            });
+            // I6: delay onboardingCompleted until first successful pull-and-apply.
+            // The setup flow intentionally starts with onboardingCompleted=false so that
+            // a broken apply-local path re-surfaces the onboarding prompt rather than
+            // leaving the user silently stuck with stale data.
+            if (!onboardingCompletedRef.current) {
+                onboardingCompletedRef.current = true;
+                setWorkspaceSyncOnboardingCompleted(true);
+                void persistWorkspaceSyncPatch({ onboardingCompleted: true });
+            }
+            const pendingSignature = workspacePendingSignatureRef.current;
+            if (pendingSignature && pendingSignature !== workspaceLastPushedSignatureRef.current) {
+                workspacePendingSignatureRef.current = '';
+                window.setTimeout(() => {
+                    void pushWorkspaceChangesToCloud(pendingSignature);
+                }, 120);
+            }
+            return true;
+        }
+        catch {
+            logSyncDebug('pull_failed_exception', { workspaceId: currentWorkspaceId, elapsedMs: Date.now() - pullStartedAtMs });
+            recordWorkspaceSyncFailure('pull');
+            setUserGlobalSyncStatus('error');
+            const message = 'Workspace sync pull failed.';
+            setUserGlobalSyncError(message);
+            setWorkspaceLastErrorMessage(message);
+            scheduleWorkspacePullRetry(() => pullFromCloudRef.current(), {
+                workspaceId: workspaceKey
+            });
+            return false;
+        }
+        finally {
+            if (bootstrapThisRun) {
+                setWorkspaceBootstrapSyncInProgress(false);
+            }
+            workspacePullInFlightRef.current = false;
+            releaseWorkspacePullLease(workspaceKey);
+        }
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        isAuthenticated,
+        checkAuthSession,
+        workspaceCloudSyncEnabled,
+        resolveCloudAuthUrl,
+        currentWorkspaceId,
+        isWorkspacePullRetryPending,
+        ensureWorkspaceSyncReady,
+        handleSyncAuthFailure,
+        recordWorkspaceSyncFailure,
+        clearWorkspaceRetry,
+        scheduleWorkspacePullRetry,
+        tryAcquireWorkspacePullLease,
+        releaseWorkspacePullLease,
+        markWorkspacePullCooldown,
+        reportSyncEvent,
+        persistWorkspaceSyncPatch,
+        buildWorkspaceSyncSignature
+    ]);
+    // Keep the stable pull ref in sync so ensureWorkspaceSyncReady can schedule
+    // a retry callback without creating a forward-reference dependency cycle.
+    useEffect(() => {
+        pullFromCloudRef.current = pullWorkspaceChangesFromCloud;
+    }, [pullWorkspaceChangesFromCloud]);
+    // Mirror onboardingCompleted state to a ref so the pull callback can read it
+    // without stale-closure risk.
+    useEffect(() => {
+        onboardingCompletedRef.current = workspaceSyncOnboardingCompleted;
+    }, [workspaceSyncOnboardingCompleted]);
+    const handleRealtimeSignal = useCallback((signal) => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        const eventId = String(signal?.eventId || '').trim();
+        if (eventId && realtimeSuppressedEventIdsRef.current.delete(eventId)) {
+            logSyncDebug('realtime_signal_suppressed_self_echo', {
+                workspaceId: currentWorkspaceId,
+                eventId,
+                signalType: signal.type
+            });
+            return;
+        }
+        if (isWorkspacePullRetryPending() || workspacePullInFlightRef.current)
+            return;
+        if (realtimePullDebounceRef.current !== null) {
+            window.clearTimeout(realtimePullDebounceRef.current);
+        }
+        realtimePullDebounceRef.current = window.setTimeout(() => {
+            realtimePullDebounceRef.current = null;
+            void pullFromCloudRef.current();
+        }, 180);
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        isWorkspacePullRetryPending,
+        workspacePullInFlightRef,
+        currentWorkspaceId
+    ]);
+    const realtimeSocketUrl = resolveWebSocketUrl('/taskforce-ws');
+    const realtimeEnabled = Boolean(realtimeSyncEnabled
+        && cloudAuthConfigured
+        && runtimeMode === 'local'
+        && workspaceCloudSyncEnabled
+        && isAuthenticated);
+    const realtimeSync = useRealtimeSync({
+        enabled: realtimeEnabled,
+        workspaceId: currentWorkspaceId,
+        websocketUrl: realtimeSocketUrl,
+        onSignal: handleRealtimeSignal,
+        onTelemetry: setRealtimeTelemetry
+    });
+    useEffect(() => {
+        setRealtimeConnectionState(realtimeSync.connectionState);
+    }, [realtimeSync.connectionState]);
+    useEffect(() => {
+        const current = realtimeTelemetry;
+        const previous = realtimeTelemetrySnapshotRef.current;
+        const deltaDuplicates = Math.max(0, current.duplicateDiscarded - previous.duplicateDiscarded);
+        const deltaOutOfOrder = Math.max(0, current.outOfOrderDiscarded - previous.outOfOrderDiscarded);
+        const deltaInvalid = Math.max(0, current.invalidDiscarded - previous.invalidDiscarded);
+        if (deltaDuplicates === 0 && deltaOutOfOrder === 0 && deltaInvalid === 0)
+            return;
+        const now = Date.now();
+        const noisyOnly = deltaOutOfOrder === 0;
+        if (noisyOnly && now - realtimeTelemetryReportedAtRef.current < 5000) {
+            return;
+        }
+        realtimeTelemetryReportedAtRef.current = now;
+        realtimeTelemetrySnapshotRef.current = { ...current };
+        reportSyncEvent(currentWorkspaceId, {
+            eventType: 'apply',
+            status: deltaOutOfOrder > 0 ? 'error' : 'success',
+            errorMessage: `Realtime telemetry duplicate=${deltaDuplicates} outOfOrder=${deltaOutOfOrder} invalid=${deltaInvalid}`
+        });
+    }, [realtimeTelemetry, reportSyncEvent, currentWorkspaceId]);
+    useEffect(() => {
+        return () => {
+            if (realtimePullDebounceRef.current !== null) {
+                window.clearTimeout(realtimePullDebounceRef.current);
+                realtimePullDebounceRef.current = null;
+            }
+        };
+    }, []);
+    const fetchLocalWorkspaceSnapshot = useCallback(async () => {
+        const [localTasksRes, localArchiveRes] = await Promise.all([
+            fetch('/api/taskforce/tasks', {
+                method: 'GET',
+                credentials: 'include'
+            }),
+            fetch('/api/taskforce/archive', {
+                method: 'GET',
+                credentials: 'include'
+            })
+        ]);
+        if (!localTasksRes.ok || !localArchiveRes.ok) {
+            return {
+                tasks: [],
+                archived: [],
+                error: 'Failed to read local workspace snapshot before sync bootstrap.'
+            };
+        }
+        const localTasksPayload = await localTasksRes.json().catch(() => ({}));
+        const localArchivePayload = await localArchiveRes.json().catch(() => ({}));
+        return {
+            tasks: Array.isArray(localTasksPayload?.tasks) ? localTasksPayload.tasks : [],
+            archived: Array.isArray(localArchivePayload?.archived) ? localArchivePayload.archived : []
+        };
+    }, []);
+    const saveWorkspaceCloudSyncSettings = useCallback(async (input) => {
+        return saveWorkspaceCloudSyncSettingsBase(input, {
+            cloudAuthConfigured,
+            isAuthenticated,
+            resolveCloudAuthUrl,
+            ensureCloudWorkspaceReadyForSync,
+            fetchLocalWorkspaceSnapshot
+        });
+    }, [
+        cloudAuthConfigured,
+        isAuthenticated,
+        resolveCloudAuthUrl,
+        ensureCloudWorkspaceReadyForSync,
+        fetchLocalWorkspaceSnapshot,
+        saveWorkspaceCloudSyncSettingsBase
+    ]);
+    // -----------------------------------------------------------------------
+    // Retry / reset functions
+    // -----------------------------------------------------------------------
+    const retryUserGlobalSettingsSync = useCallback(async () => {
+        await syncUserGlobalSettings({ preferCloudOnFirstSync: false });
+    }, [syncUserGlobalSettings]);
+    const retryWorkspaceCloudSync = useCallback(async () => {
+        clearWorkspaceRetry();
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        if (!isAuthenticated) {
+            const authed = await checkAuthSession();
+            if (!authed)
+                return;
+        }
+        const signature = buildWorkspaceSyncSignature();
+        if (signature && signature !== workspaceLastPushedSignatureRef.current) {
+            void pushWorkspaceChangesToCloud(signature);
+        }
+        await pullWorkspaceChangesFromCloud();
+    }, [
+        clearWorkspaceRetry,
+        cloudAuthConfigured,
+        runtimeMode,
+        isAuthenticated,
+        checkAuthSession,
+        workspaceCloudSyncEnabled,
+        buildWorkspaceSyncSignature,
+        pushWorkspaceChangesToCloud,
+        pullWorkspaceChangesFromCloud
+    ]);
+    const resetWorkspaceSyncCursorAndPull = useCallback(async () => {
+        clearWorkspaceRetry();
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        if (!isAuthenticated) {
+            const authed = await checkAuthSession();
+            if (!authed)
+                return;
+        }
+        workspacePullCursorRef.current = null;
+        workspacePullBootstrapDoneRef.current = false;
+        const workspaceKey = String(currentWorkspaceId || '').trim();
+        if (!workspaceKey || workspaceKey.toLowerCase() === 'default')
+            return;
+        workspaceCloudHydratedRef.current.delete(workspaceKey);
+        setWorkspaceCloudHydrated(false);
+        // Reset watermarks so the next push re-sends the full snapshot.
+        workspaceLastPushedWatermarksRef.current = new Map();
+        logSyncDebug('pull_cursor_reset', { workspaceId: currentWorkspaceId });
+        void persistWorkspaceSyncPatch({ pullCursor: null });
+        await pullWorkspaceChangesFromCloud();
+    }, [
+        clearWorkspaceRetry,
+        cloudAuthConfigured,
+        runtimeMode,
+        isAuthenticated,
+        checkAuthSession,
+        workspaceCloudSyncEnabled,
+        currentWorkspaceId,
+        pullWorkspaceChangesFromCloud
+    ]);
+    // -----------------------------------------------------------------------
+    // Sync effects
+    // -----------------------------------------------------------------------
+    // Documents refresh interval
+    useEffect(() => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        void refreshWorkspaceSyncDocumentsSnapshot();
+        const docsIntervalId = window.setInterval(() => {
+            void refreshWorkspaceSyncDocumentsSnapshot();
+        }, 12000);
+        return () => window.clearInterval(docsIntervalId);
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        refreshWorkspaceSyncDocumentsSnapshot
+    ]);
+    // Push on signature change
+    useEffect(() => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        const signature = buildWorkspaceSyncSignature();
+        if (!signature || signature === workspaceLastPushedSignatureRef.current)
+            return;
+        if (workspacePushInFlightRef.current) {
+            workspacePendingSignatureRef.current = signature;
+            return;
+        }
+        const timeoutId = window.setTimeout(() => {
+            void pushWorkspaceChangesToCloud(signature);
+        }, 1500);
+        return () => window.clearTimeout(timeoutId);
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        buildWorkspaceSyncSignature,
+        workspaceSyncDocumentsFingerprint,
+        pushWorkspaceChangesToCloud
+    ]);
+    // Clear sync state when disabled
+    useEffect(() => {
+        if (cloudAuthConfigured && runtimeMode === 'local' && workspaceCloudSyncEnabled)
+            return;
+        clearWorkspaceRetry();
+        setWorkspaceSyncReady(false);
+        setWorkspaceCloudHydrated(false);
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        clearWorkspaceRetry
+    ]);
+    // Pull interval
+    useEffect(() => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        if (isWorkspacePullRetryPending())
+            return;
+        void pullWorkspaceChangesFromCloud();
+        const intervalId = window.setInterval(() => {
+            void pullWorkspaceChangesFromCloud();
+        }, 8000);
+        return () => window.clearInterval(intervalId);
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        isWorkspacePullRetryPending,
+        pullWorkspaceChangesFromCloud
+    ]);
+    // Backfill: pull when local is empty
+    useEffect(() => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        if (tasks.length > 0 || archivedTasks.length > 0)
+            return;
+        const workspaceKey = String(currentWorkspaceId || '').trim();
+        if (!workspaceKey || workspaceKey.toLowerCase() === 'default')
+            return;
+        if (workspaceBackfillForcedRef.current.has(workspaceKey))
+            return;
+        workspaceBackfillForcedRef.current.add(workspaceKey);
+        workspacePullCursorRef.current = null;
+        workspacePullBootstrapDoneRef.current = false;
+        void pullWorkspaceChangesFromCloud();
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        currentWorkspaceId,
+        tasks.length,
+        archivedTasks.length,
+        pullWorkspaceChangesFromCloud
+    ]);
+    // User global settings: initial sync on auth
+    useEffect(() => {
+        if (runtimeMode !== 'local' || !isAuthenticated)
+            return;
+        if (!authUserId || authUserId === 'anonymous')
+            return;
+        void syncUserGlobalSettings({ preferCloudOnFirstSync: true });
+    }, [runtimeMode, isAuthenticated, authUserId, syncUserGlobalSettings]);
+    // User global settings: push on settings change
+    useEffect(() => {
+        if (runtimeMode !== 'local' || !isAuthenticated)
+            return;
+        if (!authUserId || authUserId === 'anonymous')
+            return;
+        if (!initialUserSettingsSyncCompletedRef.current.has(authUserId))
+            return;
+        if (applyingRemoteUserSettingsRef.current)
+            return;
+        const payload = buildUserGlobalSyncPayload();
+        const signature = JSON.stringify(payload);
+        if (!lastUserGlobalSyncSignatureRef.current) {
+            lastUserGlobalSyncSignatureRef.current = signature;
+            return;
+        }
+        if (signature === lastUserGlobalSyncSignatureRef.current)
+            return;
+        lastUserGlobalSyncSignatureRef.current = signature;
+        setUserGlobalSyncPendingChanges(1);
+        setLocalUserSyncUpdatedAt(authUserId, new Date().toISOString());
+        const timeoutId = window.setTimeout(() => {
+            void syncUserGlobalSettings({ preferCloudOnFirstSync: false });
+        }, 350);
+        return () => window.clearTimeout(timeoutId);
+    }, [
+        runtimeMode,
+        isAuthenticated,
+        authUserId,
+        buildUserGlobalSyncPayload,
+        setLocalUserSyncUpdatedAt,
+        syncUserGlobalSettings
+    ]);
+    // -----------------------------------------------------------------------
+    // Return
+    // -----------------------------------------------------------------------
+    return {
+        // State
+        userGlobalSyncStatus,
+        setUserGlobalSyncStatus,
+        userGlobalLastSyncedAt,
+        setUserGlobalLastSyncedAt,
+        userGlobalSyncPendingChanges,
+        setUserGlobalSyncPendingChanges,
+        userGlobalSyncError,
+        setUserGlobalSyncError,
+        workspaceLastPullAt,
+        setWorkspaceLastPullAt,
+        workspaceLastPushAt,
+        setWorkspaceLastPushAt,
+        workspaceLastErrorAt,
+        setWorkspaceLastErrorAt,
+        workspaceLastErrorMessage,
+        setWorkspaceLastErrorMessage,
+        workspaceLastWarningMessage,
+        setWorkspaceLastWarningMessage,
+        workspaceCloudSyncEnabled,
+        realtimeConnectionState,
+        realtimeTelemetry,
+        setWorkspaceCloudSyncEnabled,
+        workspaceSyncSourceOfTruth,
+        setWorkspaceSyncSourceOfTruth,
+        workspaceSyncOnboardingCompleted,
+        setWorkspaceSyncOnboardingCompleted,
+        workspaceSyncReady,
+        setWorkspaceSyncReady,
+        workspaceCloudHydrated,
+        setWorkspaceCloudHydrated,
+        workspaceSyncDocuments,
+        setWorkspaceSyncDocuments,
+        workspaceSyncDocumentsFingerprint,
+        setWorkspaceSyncDocumentsFingerprint,
+        // Refs
+        syncInFlightRef,
+        // From useWorkspaceSyncController
+        workspaceRetryAt,
+        isWorkspacePullRetryPending,
+        workspaceBootstrapSyncInProgress,
+        setWorkspaceBootstrapSyncInProgress,
+        workspaceBootstrapSyncPages,
+        setWorkspaceBootstrapSyncPages,
+        workspaceBootstrapSyncAppliedChanges,
+        setWorkspaceBootstrapSyncAppliedChanges,
+        workspaceSyncFailureCount,
+        workspaceSyncRetryScheduledCount,
+        workspaceSyncAuthFailureCount,
+        workspaceSyncLastFailureSource,
+        workspaceSyncLastFailureStatusCode,
+        workspacePushInFlightRef,
+        workspacePullInFlightRef,
+        workspaceLastPushedSignatureRef,
+        workspacePendingSignatureRef,
+        workspaceLastPushedTaskIdsRef,
+        workspaceDeletedTaskIdsRef,
+        workspacePullCursorRef,
+        workspacePullBootstrapDoneRef,
+        workspaceBackfillForcedRef,
+        workspaceSyncReadyRef,
+        workspaceCloudHydratedRef,
+        clearWorkspaceRetry,
+        scheduleWorkspacePullRetry,
+        isWorkspacePullCooldownActive,
+        markWorkspacePullCooldown,
+        tryAcquireWorkspacePullLease,
+        releaseWorkspacePullLease,
+        recordWorkspaceSyncFailure,
+        incrementWorkspaceSyncAuthFailure,
+        persistWorkspaceSyncPatch,
+        loadWorkspaceSyncState,
+        applyWorkspaceSyncStateSnapshot,
+        // Functions
+        syncUserGlobalSettings,
+        getLocalUserSyncUpdatedAt,
+        setLocalUserSyncUpdatedAt,
+        buildUserGlobalSyncPayload,
+        applyRemoteUserGlobalSyncPayload,
+        ensureCloudWorkspaceReadyForSync,
+        buildWorkspaceSyncPayload,
+        buildWorkspaceSyncSignature,
+        refreshWorkspaceSyncDocumentsSnapshot,
+        handleSyncAuthFailure,
+        ensureWorkspaceSyncReady,
+        pushWorkspaceChangesToCloud,
+        pullWorkspaceChangesFromCloud,
+        fetchLocalWorkspaceSnapshot,
+        saveWorkspaceCloudSyncSettings,
+        retryUserGlobalSettingsSync,
+        retryWorkspaceCloudSync,
+        resetWorkspaceSyncCursorAndPull
+    };
+}