@taskforcehq/taskforce 0.3.303 → 0.3.305

package/dist/hooks/useSyncOrchestrator.js

@@ -20,100 +20,21 @@
  */
 // === SECTION: Imports & module-level constants ===
 import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
-import { ensureCloudWorkspaceReadyForSyncService, isTransientWorkspaceSyncStatus, runWorkspacePullSyncService, runWorkspacePushSyncService, syncUserGlobalSettingsService } from '../sync/syncService';
+import { ensureCloudWorkspaceReadyForSyncService, syncUserGlobalSettingsService } from '../sync/syncService';
 import { buildWorkspaceSyncPayloadModel, buildWorkspaceSyncSignatureModel } from '../sync/workspaceSyncModel';
-import { parseAiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
 import { useWorkspaceSyncController } from './useWorkspaceSyncController';
 import { normalizeTaskforceTheme } from '../utils/theme';
 import { useRealtimeSync } from './useRealtimeSync';
 import { TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT } from '../utils/contextAssetEvents';
 import { setLocale as setAppLocale } from '../localization';
 import { normalizeTaskFromApi } from '../utils/taskNormalization.js';
-const USER_GLOBAL_SYNC_META_KEY = 'taskforce.userGlobalSyncMeta.v1';
-const SYNC_DEBUG_LOG_KEY = 'taskforce.syncDebug.v1';
-const WORKSPACE_BOOTSTRAP_TIMEOUT_MS = 120_000;
-const WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX = 'taskforce.syncWatermarks.v3';
-const WORKSPACE_SYNC_WATERMARKS_MAX_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
-const WORKSPACE_CONCURRENT_WINDOW_MESSAGE = 'Another local window is already syncing this workspace. Wait a few seconds, or press Repair in that window.';
+import { createSyncAuthCoordinator } from './sync/auth';
+import { createBootstrapTimeoutMonitor, syncBootstrapPhaseTracking } from './sync/bootstrap';
+import { buildTaxonomyStateFingerprint, flattenDocumentReviewComments, flattenTaskEvents, isValidWorkspaceKey, logSyncDebug, normalizeWorkspaceSyncAiProfileSnapshotEntry, readPersistedSyncWatermarks, readUserGlobalSyncMeta, WORKSPACE_CONCURRENT_WINDOW_MESSAGE, WORKSPACE_FULL_RECONCILE_INTERVAL_MS, writeUserGlobalSyncMeta } from './sync/orchestratorShared';
+import { createRealtimeSyncBridge } from './sync/realtime';
+import { createSyncRecoveryCoordinator } from './sync/recovery';
+import { createWorkspaceTransferCoordinator } from './sync/transfers';
 // === SECTION: Pure utility functions ===
-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;
-    }
-}
-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',
-        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
-    };
-}
-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
-    }
-}
-function buildTaxonomyStateFingerprint(taxonomyState) {
-    try {
-        return JSON.stringify(taxonomyState && typeof taxonomyState === 'object' ? taxonomyState : null);
-    }
-    catch {
-        return 'null';
-    }
-}
 function summarizeSyncPhase(enabled, phase, busy, retryAt, lastErrorMessage) {
     if (!enabled)
         return 'Sync is turned off for this workspace.';
@@ -156,84 +77,6 @@ function recommendSyncAction(enabled, phase, retryAt, lastErrorMessage) {
     }
     return 'No action needed.';
 }
-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);
-    });
-}
-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))
-            return null;
-        const savedAt = Date.parse(String(parsed.savedAt || ''));
-        if (!Number.isFinite(savedAt) || Date.now() - savedAt > WORKSPACE_SYNC_WATERMARKS_MAX_AGE_MS)
-            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 : []),
-        };
-    }
-    catch {
-        return null;
-    }
-}
-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: 7,
-            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()),
-            taxonomyStateFingerprint: typeof data.taxonomyStateFingerprint === 'string' ? data.taxonomyStateFingerprint : ''
-        }));
-    }
-    catch {
-        // localStorage may be full or unavailable; non-fatal
-    }
-}
 const EMPTY_WORKSPACE_SYNC_REFERENCE_SNAPSHOT_STATUS = {
     documents: false,
     aiProfiles: false,
@@ -241,8 +84,9 @@ const EMPTY_WORKSPACE_SYNC_REFERENCE_SNAPSHOT_STATUS = {
     documentReviewSessions: false,
     annotatedAttachmentSessions: false
 };
+export { normalizeWorkspaceSyncAiProfileSnapshotEntry };
 export function useSyncOrchestrator(input) {
-    const { currentWorkspaceId, cloudAuthConfigured, runtimeMode, authSessionResolved, isAuthenticated, authUserId, projectName, resolveCloudAuthUrl, resolveWebSocketUrl, realtimeSyncEnabled, tasks, archivedTasks, initiatives, workstreams, taxonomies, taxonomyState, setupState, globalTheme, locale, globalWeekStartsOn, themeUseGlobalDefault, setTasks, setArchivedTasks, setAuthBlocked, setIsAuthenticated, checkAuthSession, setGlobalTheme, setCurrentTheme, setSetupState, setLocale, setGlobalWeekStartsOn, fetchPlanningEntities } = input;
+    const { currentWorkspaceId, cloudAuthConfigured, runtimeMode, authSessionResolved, isAuthenticated, authUserId, projectName, resolveCloudAuthUrl, resolveWebSocketUrl, realtimeSyncEnabled, tasks, archivedTasks, deletedTasks = [], initiatives, workstreams, taxonomies, taxonomyState, setupState, globalTheme, locale, globalWeekStartsOn, themeUseGlobalDefault, setTasks, setArchivedTasks, setAuthBlocked, setIsAuthenticated, checkAuthSession, setGlobalTheme, setCurrentTheme, setSetupState, setLocale, setGlobalWeekStartsOn, fetchPlanningEntities } = input;
     const taxonomyStateFingerprint = useMemo(() => buildTaxonomyStateFingerprint(taxonomyState), [taxonomyState]);
     // === SECTION: State initialization ===
     const [userGlobalSyncStatus, setUserGlobalSyncStatus] = useState('disconnected');
@@ -253,6 +97,7 @@ export function useSyncOrchestrator(input) {
     const [workspaceLastErrorMessage, setWorkspaceLastErrorMessage] = useState(null);
     const [workspaceCloudSyncEnabled, setWorkspaceCloudSyncEnabled] = useState(false);
     const [workspaceSyncPhase, setWorkspaceSyncPhase] = useState('idle');
+    const [workspaceSyncSetupIntent, setWorkspaceSyncSetupIntent] = useState(null);
     const [workspaceSyncBusy, setWorkspaceSyncBusy] = useState(false);
     const [workspaceSyncPendingChanges, setWorkspaceSyncPendingChanges] = useState(0);
     const [workspaceSyncMarkdownDocuments, setWorkspaceSyncMarkdownDocuments] = useState([]);
@@ -381,8 +226,12 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map();
         workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
         workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
+        workspaceLastPushedTaskEventWatermarksRef.current = new Map();
         workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
         workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
+        workspaceLastPushedTaskEventWatermarksRef.current = new Map();
+        workspaceStartupFullReconcileRanRef.current = false;
+        workspaceFullReconcileInFlightRef.current = false;
         const persisted = readPersistedSyncWatermarks(currentWorkspaceId, taxonomyStateFingerprint);
         if (persisted) {
             workspaceLastPushedWatermarksRef.current = persisted.taskWatermarks;
@@ -393,6 +242,7 @@ export function useSyncOrchestrator(input) {
             workspaceLastPushedDocumentReviewSessionWatermarksRef.current = persisted.documentReviewSessionWatermarks;
             workspaceLastPushedDocumentReviewCommentWatermarksRef.current = persisted.documentReviewCommentWatermarks;
             workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = persisted.annotatedAttachmentSessionWatermarks;
+            workspaceLastPushedTaskEventWatermarksRef.current = persisted.taskEventWatermarks;
         }
     }, [currentWorkspaceId, taxonomyStateFingerprint]);
     const markWorkspaceSyncReferenceSnapshotReady = useCallback((key) => {
@@ -404,14 +254,25 @@ export function useSyncOrchestrator(input) {
             }));
     }, []);
     const workspaceSyncReferenceSnapshotsReady = Object.values(workspaceSyncReferenceSnapshotStatus).every(Boolean);
-    const { workspaceRetryAt, isWorkspaceRetryPending, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspacePullCursorRef, clearWorkspaceRetry, scheduleWorkspaceRetry, persistWorkspaceSyncPatch, loadWorkspaceSyncState, applyWorkspaceSyncStateSnapshot, saveWorkspaceCloudSyncSettings: saveWorkspaceCloudSyncSettingsBase, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease } = useWorkspaceSyncController({
+    const { workspaceRetryAt, isWorkspaceRetryPending, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspaceDeletedTaskWatermarksRef, workspacePullCursorRef, clearWorkspaceRetry, scheduleWorkspaceRetry, persistWorkspaceSyncPatch, applyWorkspaceSyncPatchLocally, loadWorkspaceSyncState, applyWorkspaceSyncStateSnapshot: applyWorkspaceSyncStateSnapshotBase, saveWorkspaceCloudSyncSettings: saveWorkspaceCloudSyncSettingsBase, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease } = useWorkspaceSyncController({
         currentWorkspaceId,
         setWorkspaceCloudSyncEnabled,
         setWorkspaceSyncPhase,
+        setWorkspaceSyncSetupIntent,
         setWorkspaceLastPullAt,
         setWorkspaceLastPushAt,
         setWorkspaceLastErrorMessage
     });
+    const applyWorkspaceSyncStateSnapshot = useCallback((nextState) => {
+        if (nextState.phase === 'attach-cloud' || nextState.phase === 'provision-local') {
+            lastBootstrapPhaseRef.current = nextState.phase;
+            if (bootstrapPhaseStartedAtRef.current === null) {
+                bootstrapPhaseStartedAtRef.current = Date.now();
+            }
+            bootstrapLastProgressAtRef.current = null;
+        }
+        applyWorkspaceSyncStateSnapshotBase(nextState);
+    }, [applyWorkspaceSyncStateSnapshotBase]);
     const workspaceLastPushedWatermarksRef = useRef(new Map());
     const workspaceLastPushedInitiativeIdsRef = useRef(new Set());
     const workspaceLastPushedInitiativeWatermarksRef = useRef(new Map());
@@ -429,12 +290,15 @@ export function useSyncOrchestrator(input) {
     const workspaceLastPushedDocumentReviewCommentWatermarksRef = useRef(new Map());
     const workspaceLastPushedAnnotatedAttachmentSessionIdsRef = useRef(new Set());
     const workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef = useRef(new Map());
+    const workspaceLastPushedTaskEventWatermarksRef = useRef(new Map());
     const workspaceStartupRepairRanRef = useRef(false);
+    const workspaceStartupFullReconcileRanRef = useRef(false);
     const workspaceRepairModeRef = useRef(false);
     const workspaceAttachBootstrapBaselineSignatureRef = useRef('');
     const workspaceCaptureAttachBootstrapBaselineRef = useRef(false);
     const workspaceDocumentsRefreshIntervalMs = 30_000;
     const workspacePullIntervalMs = realtimeSyncEnabled ? 30_000 : 15_000;
+    const workspacePushWatchdogIntervalMs = Math.max(30_000, workspacePullIntervalMs);
     const workspaceLastSuccessfulSyncAt = useMemo(() => {
         const pullMs = workspaceLastPullAt ? Date.parse(workspaceLastPullAt) : NaN;
         const pushMs = workspaceLastPushAt ? Date.parse(workspaceLastPushAt) : NaN;
@@ -656,51 +520,44 @@ export function useSyncOrchestrator(input) {
             operation
         });
     }, [currentWorkspaceId]);
+    const persistWorkspaceSyncPatchBestEffort = useCallback(async (patch) => {
+        try {
+            return await persistWorkspaceSyncPatch(patch);
+        }
+        catch {
+            return applyWorkspaceSyncPatchLocally(patch);
+        }
+    }, [applyWorkspaceSyncPatchLocally, persistWorkspaceSyncPatch]);
     const persistWorkspaceSyncPatchSafely = useCallback((patch) => {
-        void persistWorkspaceSyncPatch(patch).catch(() => { });
-    }, [persistWorkspaceSyncPatch]);
+        void persistWorkspaceSyncPatchBestEffort(patch).catch(() => { });
+    }, [persistWorkspaceSyncPatchBestEffort]);
     const scheduleWorkspaceSyncRetry = useCallback((minDelayMs) => {
         scheduleWorkspaceRetry(() => retryWorkspaceSyncRef.current(), { minDelayMs });
     }, [scheduleWorkspaceRetry]);
     useEffect(() => {
-        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;
+        syncBootstrapPhaseTracking({
+            workspaceSyncPhase,
+            lastBootstrapPhaseRef,
+            bootstrapPhaseStartedAtRef,
+            bootstrapLastProgressAtRef
+        });
     }, [workspaceSyncPhase]);
     useEffect(() => {
-        if (!workspaceCloudSyncEnabled)
-            return;
-        if (workspaceSyncPhase !== 'attach-cloud' && workspaceSyncPhase !== 'provision-local')
-            return;
-        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);
+        return createBootstrapTimeoutMonitor({
+            currentWorkspaceId,
+            workspaceCloudSyncEnabled,
+            workspaceSyncPhase,
+            workspacePullInFlightRef,
+            workspacePushInFlightRef,
+            bootstrapPhaseStartedAtRef,
+            bootstrapLastProgressAtRef,
+            setWorkspaceLastErrorMessage: (value) => setWorkspaceLastErrorMessage(value),
+            setWorkspaceLastErrorAt: (value) => setWorkspaceLastErrorAt(value),
+            setUserGlobalSyncStatus,
+            setUserGlobalSyncError: (value) => setUserGlobalSyncError(value),
+            setWorkspaceSyncBusy,
+            persistWorkspaceSyncPatchSafely
+        });
     }, [
         currentWorkspaceId,
         workspaceCloudSyncEnabled,
@@ -716,7 +573,8 @@ export function useSyncOrchestrator(input) {
             isAuthenticated,
             resolveCloudAuthUrl,
             workspaceId: currentWorkspaceId,
-            workspaceName: projectName || currentWorkspaceId
+            workspaceName: projectName || currentWorkspaceId,
+            allowProvisionOnMismatch: workspaceSyncPhase !== 'attach-cloud'
         });
     }, [
         cloudAuthConfigured,
@@ -724,7 +582,8 @@ export function useSyncOrchestrator(input) {
         isAuthenticated,
         resolveCloudAuthUrl,
         currentWorkspaceId,
-        projectName
+        projectName,
+        workspaceSyncPhase
     ]);
     useEffect(() => {
         workspaceTasksRef.current = tasks || [];
@@ -732,6 +591,14 @@ export function useSyncOrchestrator(input) {
     useEffect(() => {
         workspaceArchivedTasksRef.current = archivedTasks || [];
     }, [archivedTasks]);
+    useEffect(() => {
+        workspaceDeletedTaskWatermarksRef.current = new Map((deletedTasks || [])
+            .map((entry) => [
+            String(entry?.taskId || '').trim(),
+            String(entry?.deletedAt || '').trim()
+        ])
+            .filter(([taskId, deletedAt]) => taskId.length > 0 && Number.isFinite(Date.parse(deletedAt))));
+    }, [deletedTasks, workspaceDeletedTaskWatermarksRef]);
     useEffect(() => {
         workspaceInitiativesRef.current = initiatives || [];
     }, [initiatives]);
@@ -739,6 +606,7 @@ export function useSyncOrchestrator(input) {
         workspaceWorkstreamsRef.current = workstreams || [];
     }, [workstreams]);
     const workspaceForceFullAiProfilePushRef = useRef(false);
+    const workspaceFullReconcileInFlightRef = useRef(false);
     const buildWorkspaceSyncPayload = useCallback((options) => {
         const forceAllAiProfiles = options?.forceAllAiProfiles === true;
         // Read documents and assets from refs rather than state so that the freshest data
@@ -747,8 +615,10 @@ export function useSyncOrchestrator(input) {
         return buildWorkspaceSyncPayloadModel({
             tasks: workspaceTasksRef.current,
             archivedTasks: workspaceArchivedTasksRef.current,
+            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current),
             lastPushedTaskIds: workspaceLastPushedTaskIdsRef.current,
             pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
+            pendingDeletedTaskWatermarks: workspaceDeletedTaskWatermarksRef.current,
             initiatives: workspaceInitiativesRef.current,
             workstreams: workspaceWorkstreamsRef.current,
             taxonomies: taxonomies || [],
@@ -775,6 +645,7 @@ export function useSyncOrchestrator(input) {
             lastPushedDocumentReviewCommentWatermarks: workspaceLastPushedDocumentReviewCommentWatermarksRef.current,
             lastPushedAnnotatedAttachmentSessionIds: workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current,
             lastPushedAnnotatedAttachmentSessionWatermarks: workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current,
+            lastPushedTaskEventWatermarks: workspaceLastPushedTaskEventWatermarksRef.current,
             lastPushedWatermarks: workspaceLastPushedWatermarksRef.current
         });
     }, [taxonomies, taxonomyState]);
@@ -802,6 +673,7 @@ export function useSyncOrchestrator(input) {
             workspaceId: currentWorkspaceId,
             tasks: workspaceTasksRef.current,
             archivedTasks: workspaceArchivedTasksRef.current,
+            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current),
             pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
             initiatives: workspaceInitiativesRef.current,
             workstreams: workspaceWorkstreamsRef.current,
@@ -813,7 +685,52 @@ export function useSyncOrchestrator(input) {
             documentReviewComments: workspaceSyncDocumentReviewCommentsRef.current,
             annotatedAttachmentSessions: workspaceSyncAnnotatedAttachmentSessionsRef.current
         });
-    }, [currentWorkspaceId, taxonomies]);
+    }, [currentWorkspaceId, taxonomies, taxonomyState]);
+    const workspaceCoreSyncFingerprint = useMemo(() => JSON.stringify({
+        tasks: (tasks || [])
+            .map((task) => ({
+            id: String(task.id || '').trim(),
+            updatedAt: String(task.updatedAt || task.createdAt || '').trim(),
+            status: String(task.status || '').trim(),
+            referenceNumber: task.referenceNumber ?? null,
+            localReferenceNumber: task.localReferenceNumber ?? null
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id)),
+        archivedTasks: (archivedTasks || [])
+            .map((task) => ({
+            id: String(task.id || '').trim(),
+            updatedAt: String(task.updatedAt || task.createdAt || '').trim(),
+            status: String(task.status || '').trim(),
+            referenceNumber: task.referenceNumber ?? null,
+            localReferenceNumber: task.localReferenceNumber ?? null
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id)),
+        initiatives: (initiatives || [])
+            .map((initiative) => ({
+            id: String(initiative.id || '').trim(),
+            updatedAt: String(initiative.updatedAt || initiative.createdAt || '').trim(),
+            isArchived: Boolean(initiative.isArchived)
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id)),
+        workstreams: (workstreams || [])
+            .map((workstream) => ({
+            id: String(workstream.id || '').trim(),
+            updatedAt: String(workstream.updatedAt || workstream.createdAt || '').trim(),
+            initiativeId: typeof workstream.initiativeId === 'string' ? workstream.initiativeId.trim() : '',
+            isArchived: Boolean(workstream.isArchived)
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id)),
+        taskEvents: flattenTaskEvents(tasks || [], archivedTasks || [])
+            .map((event) => ({
+            id: String(event.id || '').trim(),
+            taskId: String(event.taskId || '').trim(),
+            createdAt: String(event.createdAt || '').trim(),
+            action: String(event.action || '').trim(),
+        }))
+            .sort((left, right) => left.id.localeCompare(right.id)),
+        taxonomies: Array.isArray(taxonomies) ? taxonomies : [],
+        taxonomyState: taxonomyState && typeof taxonomyState === 'object' ? taxonomyState : null
+    }), [tasks, archivedTasks, initiatives, workstreams, taxonomies, taxonomyState]);
     // Fingerprint of per-task attachment counts — changes when the MCP tool saves a new
     // attachment and the React app polls the updated task. Used to trigger an immediate
     // asset snapshot refresh without requiring a cross-process DOM event.
@@ -1172,6 +1089,9 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map(workspaceSyncAnnotatedAttachmentSessionsRef.current
             .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
             .filter(([id]) => id.length > 0));
+        workspaceLastPushedTaskEventWatermarksRef.current = new Map(flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current)
+            .map((entry) => [String(entry?.id || '').trim(), String(entry?.createdAt || '').trim()])
+            .filter(([id]) => id.length > 0));
     }, []);
     const refreshLocalWorkspaceTaskCollections = useCallback(async () => {
         const [tasksRes, archiveRes] = await Promise.all([
@@ -1208,557 +1128,174 @@ export function useSyncOrchestrator(input) {
         });
     }, [currentWorkspaceId, fetchPlanningEntities, setArchivedTasks, setTasks]);
     // === SECTION: Auth failure handling & sync readiness ===
-    const handleSyncAuthFailure = useCallback(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 { handleSyncAuthFailure, ensureWorkspaceSyncReady } = useMemo(() => createSyncAuthCoordinator({
+        currentWorkspaceId,
+        workspaceSyncPhase,
         clearWorkspaceRetry,
+        setWorkspaceSyncBusy,
+        setUserGlobalSyncStatus,
+        setUserGlobalSyncError: (value) => setUserGlobalSyncError(value),
+        setWorkspaceLastErrorMessage: (value) => setWorkspaceLastErrorMessage(value),
+        setWorkspaceLastErrorAt: (value) => setWorkspaceLastErrorAt(value),
         reportSyncEvent,
-        currentWorkspaceId,
         setAuthBlocked,
         setIsAuthenticated,
-        checkAuthSession
-    ]);
-    const ensureWorkspaceSyncReady = useCallback(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;
-    }, [
-        currentWorkspaceId,
+        checkAuthSession,
         ensureCloudWorkspaceReadyForSync,
-        handleSyncAuthFailure,
-        reportSyncEvent,
         scheduleWorkspaceSyncRetry,
+        persistWorkspaceSyncPatchSafely
+    }), [
+        currentWorkspaceId,
         workspaceSyncPhase,
+        clearWorkspaceRetry,
+        reportSyncEvent,
+        setAuthBlocked,
+        setIsAuthenticated,
+        checkAuthSession,
+        ensureCloudWorkspaceReadyForSync,
+        scheduleWorkspaceSyncRetry,
         persistWorkspaceSyncPatchSafely
     ]);
-    // === SECTION: Push sync ===
-    const pushWorkspaceChangesToCloud = useCallback(async (signature, options) => {
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
-            return false;
-        if (!isValidWorkspaceKey(currentWorkspaceId))
-            return false;
-        if (workspaceRepairModeRef.current === true && options?.repairMode !== true) {
-            workspacePendingSignatureRef.current = signature;
-            return false;
-        }
-        if (workspaceSyncPhase === 'attach-cloud') {
-            workspacePendingSignatureRef.current = signature;
-            return false;
-        }
-        if (!isAuthenticated) {
-            const authed = await checkAuthSession();
-            if (!authed)
-                return false;
-        }
-        if (shouldSuppressAttachBootstrapPush(signature)) {
-            return false;
-        }
-        if (workspacePushInFlightRef.current || workspacePullInFlightRef.current) {
-            workspacePendingSignatureRef.current = signature;
-            return false;
-        }
-        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'push');
-        if (!leaseAcquired) {
-            workspacePendingSignatureRef.current = signature;
-            reportWorkspaceWindowContention('push');
-            return false;
-        }
-        workspacePushInFlightRef.current = true;
-        setWorkspaceSyncBusy(true);
-        setUserGlobalSyncStatus('syncing');
-        setUserGlobalSyncError(null);
-        const pushStartedAtMs = Date.now();
-        const forceAllAiProfiles = options?.forceAllAiProfiles === true || workspaceForceFullAiProfilePushRef.current === true;
-        try {
-            await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
-            await refreshWorkspaceSyncAiProfilesSnapshot();
-            await refreshWorkspaceSyncAssetsSnapshot();
-            await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
-            const ready = await ensureWorkspaceSyncReady();
-            if (!ready)
-                return false;
-            const payload = buildWorkspaceSyncPayload({ forceAllAiProfiles });
-            setWorkspaceSyncPendingChanges(payload.changes.length);
-            const pushResult = await runWorkspacePushSyncService({
-                resolveCloudAuthUrl,
-                workspaceId: currentWorkspaceId,
-                payload,
-                ensureCloudWorkspaceReadyForSync,
-                repairMode: options?.repairMode === true || workspaceRepairModeRef.current === true
-            });
-            if (!pushResult.success) {
-                if (pushResult.status === 401) {
-                    await handleSyncAuthFailure('push', 401);
-                    return false;
-                }
-                let message = pushResult.error
-                    ? `Workspace sync push failed (${pushResult.status || 0}): ${pushResult.error}`
-                    : `Workspace sync push failed (${pushResult.status || 0})`;
-                if (pushResult.status === 413) {
-                    message = 'Workspace sync failed because the payload is too large. This usually happens when one or more attachments exceed the project limit.';
-                }
-                setUserGlobalSyncStatus('error');
-                setUserGlobalSyncError(message);
-                setWorkspaceLastErrorMessage(message);
-                setWorkspaceLastErrorAt(new Date().toISOString());
-                reportSyncEvent(currentWorkspaceId, {
-                    eventType: 'push',
-                    status: 'error',
-                    statusCode: pushResult.status,
-                    errorMessage: message,
-                    requestMs: pushResult.requestMs
-                });
-                workspacePendingSignatureRef.current = signature;
-                if (pushResult.transient || isTransientWorkspaceSyncStatus(pushResult.status)) {
-                    scheduleWorkspaceSyncRetry(pushResult.retryAfterMs);
-                }
-                else if (workspaceSyncPhase === 'active') {
-                    persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
-                }
-                return false;
-            }
-            workspaceLastPushedSignatureRef.current = signature;
-            workspaceLastPushedTaskIdsRef.current = pushResult.currentTaskIds;
-            workspaceLastPushedInitiativeIdsRef.current = new Set(pushResult.currentInitiativeIds);
-            workspaceLastPushedInitiativeWatermarksRef.current = new Map(pushResult.currentInitiativeWatermarks);
-            workspaceLastPushedWorkstreamIdsRef.current = new Set(pushResult.currentWorkstreamIds);
-            workspaceLastPushedWorkstreamWatermarksRef.current = new Map(pushResult.currentWorkstreamWatermarks);
-            workspaceLastPushedAiProfileIdsRef.current = new Set(pushResult.currentAiProfileIds);
-            workspaceLastPushedAiProfileWatermarksRef.current = new Map(pushResult.currentAiProfileWatermarks);
-            workspaceLastPushedDocumentPathsRef.current = new Set(pushResult.currentDocumentPaths);
-            workspaceLastPushedDocumentWatermarksRef.current = new Map(pushResult.currentDocumentWatermarks);
-            workspaceLastPushedAssetPathsRef.current = new Set(pushResult.currentAssetPaths);
-            workspaceLastPushedAssetWatermarksRef.current = new Map(pushResult.currentAssetWatermarks);
-            workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set(pushResult.currentDocumentReviewSessionIds);
-            workspaceLastPushedDocumentReviewSessionWatermarksRef.current = new Map(pushResult.currentDocumentReviewSessionWatermarks);
-            workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set(pushResult.currentDocumentReviewCommentIds);
-            workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map(pushResult.currentDocumentReviewCommentWatermarks);
-            workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set(pushResult.currentAnnotatedAttachmentSessionIds);
-            workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map(pushResult.currentAnnotatedAttachmentSessionWatermarks);
-            if (forceAllAiProfiles) {
-                workspaceForceFullAiProfilePushRef.current = false;
-            }
-            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);
-                }
-            }
-            // Persist watermarks so a page reload doesn't trigger a full resync
-            savePersistedSyncWatermarks(currentWorkspaceId, {
-                taskWatermarks: workspaceLastPushedWatermarksRef.current,
-                initiativeWatermarks: workspaceLastPushedInitiativeWatermarksRef.current,
-                workstreamWatermarks: workspaceLastPushedWorkstreamWatermarksRef.current,
-                documentWatermarks: workspaceLastPushedDocumentWatermarksRef.current,
-                assetWatermarks: workspaceLastPushedAssetWatermarksRef.current,
-                documentReviewSessionWatermarks: workspaceLastPushedDocumentReviewSessionWatermarksRef.current,
-                documentReviewCommentWatermarks: workspaceLastPushedDocumentReviewCommentWatermarksRef.current,
-                annotatedAttachmentSessionWatermarks: workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current,
-                taxonomyStateFingerprint
-            });
-            if (Array.isArray(pushResult.emittedEventIds) && pushResult.emittedEventIds.length > 0) {
-                for (const rawEventId of pushResult.emittedEventIds) {
-                    const eventId = String(rawEventId || '').trim();
-                    if (!eventId || 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);
-                }
-            }
-            clearWorkspaceRetry();
-            clearWorkspaceIssue();
-            const syncedAt = pushResult.syncedAt || new Date().toISOString();
-            setWorkspaceLastPushAt(syncedAt);
-            setWorkspaceSyncPendingChanges(0);
-            setUserGlobalSyncStatus('idle');
-            persistWorkspaceSyncPatchSafely({
-                phase: 'active',
-                lastPushAt: syncedAt,
-                lastSyncedAt: syncedAt,
-                lastErrorMessage: null
-            });
-            reportSyncEvent(currentWorkspaceId, {
-                eventType: workspaceSyncPhase === 'provision-local' ? 'bootstrap' : 'push',
-                status: 'success',
-                changeCount: pushResult.changeCount,
-                requestMs: pushResult.requestMs
-            });
-            return true;
-        }
-        catch (error) {
-            const message = 'Workspace sync push failed.';
-            setUserGlobalSyncStatus('error');
-            setUserGlobalSyncError(message);
-            setWorkspaceLastErrorMessage(message);
-            setWorkspaceLastErrorAt(new Date().toISOString());
-            workspacePendingSignatureRef.current = signature;
-            scheduleWorkspaceSyncRetry();
-            reportSyncEvent(currentWorkspaceId, {
-                eventType: 'push',
-                status: 'error',
-                errorMessage: `${message} ${String(error?.message || '').trim()}`.trim()
-            });
-            logSyncDebug('push_failed_exception', {
-                workspaceId: currentWorkspaceId,
-                elapsedMs: Date.now() - pushStartedAtMs
-            });
-            return false;
-        }
-        finally {
-            workspacePushInFlightRef.current = false;
-            setWorkspaceSyncBusy(workspacePullInFlightRef.current);
-            releaseWorkspaceSyncLease(currentWorkspaceId);
-            const pendingSignature = workspacePendingSignatureRef.current;
-            if (pendingSignature
-                && pendingSignature !== workspaceLastPushedSignatureRef.current
-                && !workspacePullInFlightRef.current) {
-                workspacePendingSignatureRef.current = '';
-                window.setTimeout(() => {
-                    void pushWorkspaceChangesToCloud(pendingSignature);
-                }, 120);
-            }
-        }
-    }, [
+    // === SECTION: Push/Pull sync ===
+    const transferCoordinator = useMemo(() => createWorkspaceTransferCoordinator({
         cloudAuthConfigured,
         runtimeMode,
         workspaceCloudSyncEnabled,
         currentWorkspaceId,
         workspaceSyncPhase,
+        taxonomyStateFingerprint,
         isAuthenticated,
         checkAuthSession,
-        clearWorkspaceIssue,
-        refreshWorkspaceSyncMarkdownDocumentsSnapshot,
-        refreshWorkspaceSyncAiProfilesSnapshot,
-        refreshWorkspaceSyncAssetsSnapshot,
-        refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
-        ensureWorkspaceSyncReady,
-        buildWorkspaceSyncPayload,
         resolveCloudAuthUrl,
         ensureCloudWorkspaceReadyForSync,
-        shouldSuppressAttachBootstrapPush,
+        ensureWorkspaceSyncReady,
         handleSyncAuthFailure,
         clearWorkspaceRetry,
-        persistWorkspaceSyncPatch,
-        reportSyncEvent,
+        clearWorkspaceIssue,
+        isWorkspaceRetryPending,
         scheduleWorkspaceSyncRetry,
+        persistWorkspaceSyncPatchSafely,
+        persistWorkspaceSyncPatchBestEffort,
+        reportSyncEvent,
         acquireWorkspaceSyncLease,
         releaseWorkspaceSyncLease,
         reportWorkspaceWindowContention,
+        refreshWorkspaceSyncMarkdownDocumentsSnapshot,
+        refreshWorkspaceSyncAiProfilesSnapshot,
+        refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
+        refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot,
+        refreshLocalWorkspaceTaskCollections,
+        buildWorkspaceSyncPayload,
+        buildWorkspaceSyncSignature,
+        seedWorkspaceSnapshotPushBaseline,
+        shouldSuppressAttachBootstrapPush,
+        recordSuppressedEventIds: (...args) => realtimeBridgeRef.current.recordSuppressedEventIds(...args),
+        workspaceRepairModeRef,
+        workspaceForceFullAiProfilePushRef,
         workspacePushInFlightRef,
         workspacePullInFlightRef,
-        persistWorkspaceSyncPatchSafely
-    ]);
-    // === SECTION: Pull sync ===
-    const pullWorkspaceChangesFromCloud = useCallback(async (options) => {
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
-            return false;
-        if (!isValidWorkspaceKey(currentWorkspaceId))
-            return false;
-        if (workspaceRepairModeRef.current === true && options?.repairMode !== true)
-            return false;
-        if (workspaceSyncPhase === 'provision-local')
-            return false;
-        if (isWorkspaceRetryPending())
-            return false;
-        if (!isAuthenticated) {
-            const authed = await checkAuthSession();
-            if (!authed)
-                return false;
-        }
-        if (workspacePullInFlightRef.current || workspacePushInFlightRef.current)
-            return false;
-        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'pull');
-        if (!leaseAcquired) {
-            reportWorkspaceWindowContention('pull');
-            return false;
-        }
-        workspacePullInFlightRef.current = true;
-        setWorkspaceSyncBusy(true);
-        setUserGlobalSyncStatus('syncing');
-        setUserGlobalSyncError(null);
-        const pullStartedAtMs = Date.now();
-        try {
-            const ready = await ensureWorkspaceSyncReady();
-            if (!ready)
-                return false;
-            const bootstrap = workspaceSyncPhase === 'attach-cloud';
-            const cursor = bootstrap ? null : workspacePullCursorRef.current;
-            const pullResult = await runWorkspacePullSyncService({
-                resolveCloudAuthUrl,
-                workspaceId: currentWorkspaceId,
-                cursor,
-                bootstrap,
-                ensureCloudWorkspaceReadyForSync,
-                maxPages: 20,
-                repairMode: options?.repairMode === true || workspaceRepairModeRef.current === true,
-                onPagePulled: () => { bootstrapLastProgressAtRef.current = Date.now(); },
-                onChangesApplied: () => { bootstrapLastProgressAtRef.current = Date.now(); }
-            });
-            if (!pullResult.success) {
-                if (pullResult.kind === 'pull_http' && pullResult.status === 401) {
-                    await handleSyncAuthFailure('pull', 401);
-                    return false;
-                }
-                if (pullResult.kind === 'apply_auth') {
-                    await handleSyncAuthFailure('apply', 401);
-                    return false;
-                }
-                let message = pullResult.kind === 'apply_payload' || pullResult.kind === 'apply_all_candidates' || pullResult.kind === 'exception'
-                    ? String(pullResult.error || 'Workspace sync apply failed.')
-                    : `Workspace sync pull failed (${pullResult.status || 0})`;
-                if (pullResult.status === 413) {
-                    message = 'Local sync failed because the downloaded payload is too large. This usually happens when the workspace contains massive attachments.';
-                }
-                setUserGlobalSyncStatus('error');
-                setUserGlobalSyncError(message);
-                setWorkspaceLastErrorMessage(message);
-                setWorkspaceLastErrorAt(new Date().toISOString());
-                reportSyncEvent(currentWorkspaceId, {
-                    eventType: pullResult.kind?.startsWith('apply') ? 'apply' : 'pull',
-                    status: 'error',
-                    statusCode: pullResult.status,
-                    errorMessage: message,
-                    requestMs: pullResult.pullRequestMs,
-                    details: {
-                        pages: pullResult.pages,
-                        applyMs: pullResult.applyMs,
-                        ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
-                    }
-                });
-                if (pullResult.transient || pullResult.hasTransientApplyFailure || isTransientWorkspaceSyncStatus(pullResult.status)) {
-                    scheduleWorkspaceSyncRetry(pullResult.retryAfterMs);
-                }
-                else {
-                    persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
-                }
-                return false;
-            }
-            if (Array.isArray(pullResult.emittedEventIds)) {
-                for (const eventId of pullResult.emittedEventIds) {
-                    if (eventId) {
-                        realtimeSuppressedEventIdsRef.current.add(eventId);
-                        // Optional: cleanup after a generous delay if WebSocket never arrives to clear it
-                        setTimeout(() => {
-                            realtimeSuppressedEventIdsRef.current.delete(eventId);
-                        }, 60000);
-                    }
-                }
-            }
-            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) {
-                logSyncDebug('pull_document_decrypt_failures', {
-                    workspaceId: currentWorkspaceId,
-                    failureCount: decryptFailures.length
-                });
-            }
-            workspacePullCursorRef.current = pullResult.cursor || null;
-            if (pullResult.appliedChanges > 0 && (pullResult.pulledActiveUpserts || pullResult.pulledArchivedUpserts)) {
-                try {
-                    await refreshLocalWorkspaceTaskCollections();
-                }
-                catch {
-                    logSyncDebug('pull_local_refresh_failed', {
-                        workspaceId: currentWorkspaceId,
-                        appliedChanges: pullResult.appliedChanges
-                    });
-                }
-            }
-            clearWorkspaceRetry();
-            clearWorkspaceIssue();
-            const syncedAt = pullResult.syncedAt || new Date().toISOString();
-            setWorkspaceLastPullAt(syncedAt);
-            setWorkspaceSyncPendingChanges(0);
-            setUserGlobalSyncStatus('idle');
-            if (workspaceSyncPhase === 'attach-cloud') {
-                workspaceCaptureAttachBootstrapBaselineRef.current = true;
-                workspacePendingSignatureRef.current = '';
-            }
-            await persistWorkspaceSyncPatch({
-                phase: 'active',
-                pullCursor: workspacePullCursorRef.current,
-                lastPullAt: syncedAt,
-                lastSyncedAt: syncedAt,
-                lastErrorMessage: null
-            });
-            reportSyncEvent(currentWorkspaceId, {
-                eventType: workspaceSyncPhase === 'attach-cloud' ? 'bootstrap' : 'pull',
-                status: 'success',
-                changeCount: pullResult.appliedChanges,
-                requestMs: pullResult.pullRequestMs,
-                details: {
-                    pages: pullResult.pages,
-                    applyMs: pullResult.applyMs,
-                    ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
-                }
-            });
-            if (workspaceSyncPhase === 'attach-cloud') {
-                await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
-                await refreshWorkspaceSyncAssetsSnapshot();
-                await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
-                await refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
-                seedWorkspaceSnapshotPushBaseline();
-                return true;
-            }
-            const pendingSignature = workspacePendingSignatureRef.current || buildWorkspaceSyncSignature();
-            if (pendingSignature && pendingSignature !== workspaceLastPushedSignatureRef.current) {
-                workspacePendingSignatureRef.current = '';
-                window.setTimeout(() => {
-                    void pushWorkspaceChangesToCloud(pendingSignature);
-                }, 120);
-            }
-            return true;
-        }
-        catch (error) {
-            const detail = String(error?.message || '').trim();
-            const message = detail
-                ? `Workspace sync pull failed. ${detail}`
-                : 'Workspace sync pull failed.';
-            setUserGlobalSyncStatus('error');
-            setUserGlobalSyncError(message);
-            setWorkspaceLastErrorMessage(message);
-            setWorkspaceLastErrorAt(new Date().toISOString());
-            scheduleWorkspaceSyncRetry();
-            reportSyncEvent(currentWorkspaceId, {
-                eventType: 'pull',
-                status: 'error',
-                errorMessage: message,
-                requestMs: Date.now() - pullStartedAtMs
-            });
-            logSyncDebug('pull_failed_exception', {
-                workspaceId: currentWorkspaceId,
-                elapsedMs: Date.now() - pullStartedAtMs,
-                error: detail || null
-            });
-            return false;
-        }
-        finally {
-            workspacePullInFlightRef.current = false;
-            setWorkspaceSyncBusy(workspacePushInFlightRef.current);
-            releaseWorkspaceSyncLease(currentWorkspaceId);
-        }
-    }, [
+        workspaceLastPushedSignatureRef,
+        workspacePendingSignatureRef,
+        workspaceLastPushedTaskIdsRef,
+        workspaceDeletedTaskIdsRef,
+        workspaceDeletedTaskWatermarksRef,
+        workspacePullCursorRef,
+        workspaceLastPushedWatermarksRef,
+        workspaceLastPushedInitiativeIdsRef,
+        workspaceLastPushedInitiativeWatermarksRef,
+        workspaceLastPushedWorkstreamIdsRef,
+        workspaceLastPushedWorkstreamWatermarksRef,
+        workspaceLastPushedAiProfileIdsRef,
+        workspaceLastPushedAiProfileWatermarksRef,
+        workspaceLastPushedDocumentPathsRef,
+        workspaceLastPushedDocumentWatermarksRef,
+        workspaceLastPushedAssetPathsRef,
+        workspaceLastPushedAssetWatermarksRef,
+        workspaceLastPushedDocumentReviewSessionIdsRef,
+        workspaceLastPushedDocumentReviewSessionWatermarksRef,
+        workspaceLastPushedDocumentReviewCommentIdsRef,
+        workspaceLastPushedDocumentReviewCommentWatermarksRef,
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef,
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef,
+        workspaceLastPushedTaskEventWatermarksRef,
+        workspaceCaptureAttachBootstrapBaselineRef,
+        workspaceStartupFullReconcileRanRef,
+        workspaceFullReconcileInFlightRef,
+        bootstrapLastProgressAtRef,
+        realtimeSuppressedEventQueueRef,
+        setWorkspaceSyncBusy,
+        setUserGlobalSyncStatus,
+        setUserGlobalSyncError,
+        setWorkspaceLastErrorMessage,
+        setWorkspaceLastErrorAt,
+        setWorkspaceLastPullAt,
+        setWorkspaceLastPushAt,
+        setWorkspaceSyncPendingChanges,
+        setTasks,
+        setArchivedTasks
+    }), [
         cloudAuthConfigured,
         runtimeMode,
         workspaceCloudSyncEnabled,
         currentWorkspaceId,
         workspaceSyncPhase,
-        isWorkspaceRetryPending,
+        taxonomyStateFingerprint,
         isAuthenticated,
         checkAuthSession,
-        clearWorkspaceIssue,
-        ensureWorkspaceSyncReady,
         resolveCloudAuthUrl,
         ensureCloudWorkspaceReadyForSync,
+        ensureWorkspaceSyncReady,
         handleSyncAuthFailure,
-        refreshLocalWorkspaceTaskCollections,
+        clearWorkspaceRetry,
+        clearWorkspaceIssue,
+        scheduleWorkspaceSyncRetry,
+        persistWorkspaceSyncPatchSafely,
+        persistWorkspaceSyncPatchBestEffort,
+        reportSyncEvent,
+        acquireWorkspaceSyncLease,
+        releaseWorkspaceSyncLease,
+        reportWorkspaceWindowContention,
         refreshWorkspaceSyncMarkdownDocumentsSnapshot,
+        refreshWorkspaceSyncAiProfilesSnapshot,
         refreshWorkspaceSyncAssetsSnapshot,
         refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
         refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot,
-        clearWorkspaceRetry,
-        persistWorkspaceSyncPatch,
-        reportSyncEvent,
+        refreshLocalWorkspaceTaskCollections,
+        buildWorkspaceSyncPayload,
         buildWorkspaceSyncSignature,
-        pushWorkspaceChangesToCloud,
         seedWorkspaceSnapshotPushBaseline,
-        scheduleWorkspaceSyncRetry,
-        acquireWorkspaceSyncLease,
-        releaseWorkspaceSyncLease,
-        reportWorkspaceWindowContention,
-        workspacePushInFlightRef,
-        workspacePullInFlightRef,
-        persistWorkspaceSyncPatchSafely
+        shouldSuppressAttachBootstrapPush,
+        setTasks,
+        setArchivedTasks
     ]);
-    // === SECTION: Realtime sync integration ===
-    const handleRealtimeSignal = useCallback((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 { pushWorkspaceChangesToCloud, pullWorkspaceChangesFromCloud } = transferCoordinator;
+    const realtimeBridgeRef = useRef({
+        handleRealtimeSignal: () => { },
+        recordSuppressedEventIds: () => { },
+        clearRealtimePullDebounce: () => { }
+    });
+    const realtimeBridge = useMemo(() => createRealtimeSyncBridge({
         cloudAuthConfigured,
         runtimeMode,
         workspaceCloudSyncEnabled,
         workspaceSyncPhase,
+        workspacePullInFlightRef,
+        realtimePullDebounceRef,
+        realtimeSuppressedEventIdsRef,
+        clearWorkspaceRetry,
         isWorkspaceRetryPending,
+        pullWorkspaceChangesFromCloud
+    }), [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        workspaceSyncPhase,
         clearWorkspaceRetry,
-        workspacePullInFlightRef,
+        isWorkspaceRetryPending,
         pullWorkspaceChangesFromCloud
     ]);
+    realtimeBridgeRef.current = realtimeBridge;
     const realtimeSocketUrl = resolveWebSocketUrl('/taskforce-ws');
     const normalizedRealtimeUserId = String(authUserId || '').trim();
     const realtimeEnabled = Boolean(realtimeSyncEnabled
@@ -1774,7 +1311,7 @@ export function useSyncOrchestrator(input) {
         enabled: realtimeEnabled,
         workspaceId: currentWorkspaceId,
         websocketUrl: realtimeSocketUrl,
-        onSignal: handleRealtimeSignal,
+        onSignal: realtimeBridge.handleRealtimeSignal,
         onTelemetry: setRealtimeTelemetry,
         userId: normalizedRealtimeUserId || undefined
     });
@@ -1782,39 +1319,9 @@ export function useSyncOrchestrator(input) {
         setRealtimeConnectionState(realtimeSync.connectionState);
     }, [realtimeSync.connectionState]);
     useEffect(() => {
-        return () => {
-            if (realtimePullDebounceRef.current !== null) {
-                window.clearTimeout(realtimePullDebounceRef.current);
-                realtimePullDebounceRef.current = null;
-            }
-        };
-    }, []);
+        return () => realtimeBridge.clearRealtimePullDebounce();
+    }, [realtimeBridge]);
     // === SECTION: Repair & manual retry ===
-    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 (settings) => {
         return saveWorkspaceCloudSyncSettingsBase(settings, {
             cloudAuthConfigured,
@@ -1830,144 +1337,79 @@ export function useSyncOrchestrator(input) {
     const retryUserGlobalSettingsSync = useCallback(async () => {
         await syncUserGlobalSettings({ preferCloudOnFirstSync: false });
     }, [syncUserGlobalSettings]);
-    const retryWorkspaceCloudSync = useCallback(async () => {
-        clearWorkspaceRetry();
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
-            return false;
-        if (!isAuthenticated) {
-            const authed = await checkAuthSession();
-            if (!authed)
-                return false;
-        }
-        workspaceForceFullAiProfilePushRef.current = true;
-        if (workspaceSyncPhase === 'provision-local') {
-            const signature = buildWorkspaceSyncSignature();
-            if (!signature)
-                return false;
-            return pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true });
-        }
-        const pulled = await pullWorkspaceChangesFromCloud();
-        if (workspaceSyncPhase === 'attach-cloud')
-            return pulled;
-        const signature = buildWorkspaceSyncSignature();
-        const forceAllAiProfiles = workspaceForceFullAiProfilePushRef.current === true;
-        if (!forceAllAiProfiles && shouldSuppressAttachBootstrapPush(signature)) {
-            return pulled;
-        }
-        if (signature) {
-            workspacePendingSignatureRef.current = signature;
-            const pushed = await pushWorkspaceChangesToCloud(signature, {
-                forceAllAiProfiles
-            });
-            return pulled || pushed;
-        }
-        return pulled;
-    }, [
-        clearWorkspaceRetry,
-        cloudAuthConfigured,
-        runtimeMode,
+    const recoveryCoordinator = useMemo(() => createSyncRecoveryCoordinator({
+        currentWorkspaceId,
+        taxonomyStateFingerprint,
         workspaceCloudSyncEnabled,
-        isAuthenticated,
-        checkAuthSession,
         workspaceSyncPhase,
-        buildWorkspaceSyncSignature,
-        shouldSuppressAttachBootstrapPush,
-        pushWorkspaceChangesToCloud,
-        pullWorkspaceChangesFromCloud
-    ]);
-    const resetWorkspaceSyncCursorAndPull = useCallback(async () => {
-        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'repair');
-        if (!leaseAcquired) {
-            forceClearWorkspaceSyncLease(currentWorkspaceId);
-            const reclaimed = await acquireWorkspaceSyncLease(currentWorkspaceId, 'repair');
-            if (!reclaimed) {
-                reportWorkspaceWindowContention('repair');
-                return;
-            }
-        }
-        clearWorkspaceRetry();
-        clearWorkspaceIssue();
-        bootstrapPhaseStartedAtRef.current = null;
-        bootstrapLastProgressAtRef.current = null;
-        workspacePullCursorRef.current = null;
-        workspaceAttachBootstrapBaselineSignatureRef.current = '';
-        workspaceCaptureAttachBootstrapBaselineRef.current = false;
-        workspacePendingSignatureRef.current = '';
-        workspaceLastPushedSignatureRef.current = '';
-        workspaceLastPushedWatermarksRef.current = new Map();
-        workspaceLastPushedInitiativeIdsRef.current = new Set();
-        workspaceLastPushedInitiativeWatermarksRef.current = new Map();
-        workspaceLastPushedWorkstreamIdsRef.current = new Set();
-        workspaceLastPushedWorkstreamWatermarksRef.current = new Map();
-        workspaceLastPushedAiProfileIdsRef.current = new Set();
-        workspaceLastPushedAiProfileWatermarksRef.current = new Map();
-        workspaceLastPushedDocumentPathsRef.current = new Set();
-        workspaceLastPushedDocumentWatermarksRef.current = new Map();
-        workspaceLastPushedAssetPathsRef.current = new Set();
-        workspaceLastPushedAssetWatermarksRef.current = new Map();
-        workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set();
-        workspaceLastPushedDocumentReviewSessionWatermarksRef.current = new Map();
-        workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set();
-        workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map();
-        workspaceForceFullAiProfilePushRef.current = false;
-        workspaceStartupRepairRanRef.current = false;
-        // Clear persisted watermarks so the next push is a full resync (repair intent)
-        savePersistedSyncWatermarks(currentWorkspaceId, {
-            taskWatermarks: new Map(),
-            initiativeWatermarks: new Map(),
-            workstreamWatermarks: new Map(),
-            documentWatermarks: new Map(),
-            assetWatermarks: new Map(),
-            documentReviewSessionWatermarks: new Map(),
-            documentReviewCommentWatermarks: new Map(),
-            annotatedAttachmentSessionWatermarks: new Map(),
-            taxonomyStateFingerprint
-        });
-        try {
-            if (!workspaceCloudSyncEnabled)
-                return;
-            workspaceRepairModeRef.current = true;
-            const repairPhase = workspaceSyncPhase === 'provision-local'
-                ? 'provision-local'
-                : workspaceSyncPhase === 'attach-cloud'
-                    ? 'attach-cloud'
-                    : lastBootstrapPhaseRef.current === 'provision-local' || lastBootstrapPhaseRef.current === 'attach-cloud'
-                        ? lastBootstrapPhaseRef.current
-                        : (workspaceLastPullAt ? 'attach-cloud' : 'provision-local');
-            await persistWorkspaceSyncPatch({
-                phase: repairPhase,
-                pullCursor: null,
-                lastErrorMessage: null
-            });
-            if (repairPhase === 'provision-local') {
-                const signature = buildWorkspaceSyncSignature();
-                if (!signature)
-                    return;
-                await pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true, repairMode: true });
-                return;
-            }
-            await pullWorkspaceChangesFromCloud({ repairMode: true });
-        }
-        finally {
-            workspaceRepairModeRef.current = false;
-            releaseWorkspaceSyncLease(currentWorkspaceId);
-        }
-    }, [
+        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
+    }), [
         currentWorkspaceId,
-        forceClearWorkspaceSyncLease,
+        taxonomyStateFingerprint,
         workspaceCloudSyncEnabled,
         workspaceSyncPhase,
+        workspaceLastPullAt,
+        acquireWorkspaceSyncLease,
+        releaseWorkspaceSyncLease,
+        forceClearWorkspaceSyncLease,
+        clearWorkspaceRetry,
+        clearWorkspaceIssue,
+        reportWorkspaceWindowContention,
         persistWorkspaceSyncPatch,
         buildWorkspaceSyncSignature,
-        workspaceLastPullAt,
         pullWorkspaceChangesFromCloud,
         pushWorkspaceChangesToCloud,
-        releaseWorkspaceSyncLease,
-        reportWorkspaceWindowContention
+        cloudAuthConfigured,
+        runtimeMode,
+        isAuthenticated,
+        checkAuthSession
     ]);
+    const { retryWorkspaceCloudSync, resetWorkspaceSyncCursorAndPull } = recoveryCoordinator;
     // === SECTION: Diagnostics & reactive effects ===
     const getWorkspaceSyncDiagnostics = useCallback(() => {
         return {
@@ -2026,6 +1468,13 @@ export function useSyncOrchestrator(input) {
     useEffect(() => {
         retryWorkspaceSyncRef.current = retryWorkspaceCloudSync;
     }, [retryWorkspaceCloudSync]);
+    const refreshWorkspaceSyncContextAssetSnapshots = useCallback(() => {
+        void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+        void refreshWorkspaceSyncAssetsSnapshot();
+    }, [
+        refreshWorkspaceSyncMarkdownDocumentsSnapshot,
+        refreshWorkspaceSyncAssetsSnapshot
+    ]);
     useEffect(() => {
         if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
             return;
@@ -2041,11 +1490,7 @@ export function useSyncOrchestrator(input) {
             const eventWorkspaceId = String(detail?.workspaceId || '').trim() || 'default';
             if (eventWorkspaceId !== currentWorkspaceId)
                 return;
-            void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
-            void refreshWorkspaceSyncAiProfilesSnapshot();
-            void refreshWorkspaceSyncAssetsSnapshot();
-            void refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
-            void refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
+            refreshWorkspaceSyncContextAssetSnapshots();
         };
         window.addEventListener(TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT, handleContextAssetsMutated);
         const docsIntervalId = window.setInterval(() => {
@@ -2078,6 +1523,7 @@ export function useSyncOrchestrator(input) {
         authSessionResolved,
         isAuthenticated,
         currentWorkspaceId,
+        refreshWorkspaceSyncContextAssetSnapshots,
         refreshWorkspaceSyncMarkdownDocumentsSnapshot,
         refreshWorkspaceSyncAiProfilesSnapshot,
         refreshWorkspaceSyncAssetsSnapshot,
@@ -2096,12 +1542,8 @@ export function useSyncOrchestrator(input) {
             return;
         if (!taskAttachmentsFingerprint)
             return;
-        void refreshWorkspaceSyncAssetsSnapshot();
-        void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
-        void refreshWorkspaceSyncAiProfilesSnapshot();
-        void refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
-        void refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
-    }, [cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, authSessionResolved, isAuthenticated, taskAttachmentsFingerprint, refreshWorkspaceSyncAssetsSnapshot, refreshWorkspaceSyncMarkdownDocumentsSnapshot, refreshWorkspaceSyncAiProfilesSnapshot, refreshWorkspaceSyncDocumentReviewSessionsSnapshot, refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot]);
+        refreshWorkspaceSyncContextAssetSnapshots();
+    }, [cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, authSessionResolved, isAuthenticated, taskAttachmentsFingerprint, refreshWorkspaceSyncContextAssetSnapshots]);
     useEffect(() => {
         if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved)
             return;
@@ -2134,6 +1576,7 @@ export function useSyncOrchestrator(input) {
         buildWorkspaceSyncSignature,
         shouldSuppressAttachBootstrapPush,
         buildWorkspaceSyncPayload,
+        workspaceCoreSyncFingerprint,
         workspaceSyncAiProfilesFingerprint,
         workspaceSyncMarkdownDocumentsFingerprint,
         workspaceSyncAssetsFingerprint,
@@ -2143,6 +1586,41 @@ export function useSyncOrchestrator(input) {
         workspacePushInFlightRef,
         workspacePullInFlightRef
     ]);
+    useEffect(() => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved)
+            return;
+        if (workspaceSyncPhase !== 'active')
+            return;
+        if (!workspaceSyncReferenceSnapshotsReady)
+            return;
+        const intervalId = window.setInterval(() => {
+            if (workspacePushInFlightRef.current || workspacePullInFlightRef.current)
+                return;
+            if (isWorkspaceRetryPending())
+                return;
+            const signature = workspacePendingSignatureRef.current || buildWorkspaceSyncSignature();
+            if (!signature || signature === workspaceLastPushedSignatureRef.current)
+                return;
+            const pendingPayload = buildWorkspaceSyncPayload();
+            setWorkspaceSyncPendingChanges(pendingPayload.changes.length);
+            if (pendingPayload.changes.length === 0)
+                return;
+            void pushWorkspaceChangesToCloud(signature);
+        }, workspacePushWatchdogIntervalMs);
+        return () => window.clearInterval(intervalId);
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        authSessionResolved,
+        workspaceSyncPhase,
+        workspaceSyncReferenceSnapshotsReady,
+        buildWorkspaceSyncSignature,
+        buildWorkspaceSyncPayload,
+        pushWorkspaceChangesToCloud,
+        isWorkspaceRetryPending,
+        workspacePushWatchdogIntervalMs
+    ]);
     useEffect(() => {
         if (cloudAuthConfigured && runtimeMode === 'local' && workspaceCloudSyncEnabled)
             return;
@@ -2157,25 +1635,54 @@ export function useSyncOrchestrator(input) {
     useEffect(() => {
         if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved)
             return;
-        if (workspaceSyncPhase === 'provision-local')
+        if (workspaceSyncPhase === 'provision-local' || workspaceSyncPhase === 'error')
             return;
         if (isWorkspaceRetryPending())
             return;
-        void pullWorkspaceChangesFromCloud();
+        const shouldKickOffPull = workspaceSyncPhase === 'attach-cloud' || !workspaceLastPullAt;
+        if (shouldKickOffPull) {
+            void pullWorkspaceChangesFromCloud();
+        }
         const intervalId = window.setInterval(() => {
             void pullWorkspaceChangesFromCloud();
         }, workspacePullIntervalMs);
-        return () => window.clearInterval(intervalId);
+        return () => {
+            window.clearInterval(intervalId);
+        };
     }, [
         cloudAuthConfigured,
         runtimeMode,
         workspaceCloudSyncEnabled,
         authSessionResolved,
         workspaceSyncPhase,
+        workspaceLastPullAt,
         isWorkspaceRetryPending,
         pullWorkspaceChangesFromCloud,
         workspacePullIntervalMs
     ]);
+    useEffect(() => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved || !isAuthenticated)
+            return;
+        if (workspaceSyncPhase !== 'active')
+            return;
+        const intervalId = window.setInterval(() => {
+            if (workspaceFullReconcileInFlightRef.current)
+                return;
+            workspaceFullReconcileInFlightRef.current = true;
+            void pullWorkspaceChangesFromCloud({ forceCursorNull: true }).finally(() => {
+                workspaceFullReconcileInFlightRef.current = false;
+            });
+        }, WORKSPACE_FULL_RECONCILE_INTERVAL_MS);
+        return () => window.clearInterval(intervalId);
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        authSessionResolved,
+        isAuthenticated,
+        workspaceSyncPhase,
+        pullWorkspaceChangesFromCloud
+    ]);
     useEffect(() => {
         if (runtimeMode !== 'local' || !isAuthenticated)
             return;
@@ -2277,6 +1784,7 @@ export function useSyncOrchestrator(input) {
         workspaceLastSuccessfulSyncAt,
         workspaceCloudSyncEnabled,
         workspaceSyncPhase,
+        workspaceSyncSetupIntent,
         workspaceSyncStatus,
         workspaceSyncSummary,
         workspaceSyncRecommendedAction,
@@ -2291,6 +1799,7 @@ export function useSyncOrchestrator(input) {
         workspacePendingSignatureRef,
         workspaceLastPushedTaskIdsRef,
         workspaceDeletedTaskIdsRef,
+        workspaceDeletedTaskWatermarksRef,
         workspacePullCursorRef,
         clearWorkspaceRetry,
         persistWorkspaceSyncPatch,