@taskforcehq/taskforce 0.3.170 → 0.3.301

package/dist/hooks/useSyncOrchestrator.js

@@ -1,17 +1,45 @@
-import { useState, useEffect, useCallback, useRef } from 'react';
-import { calculateWorkspaceRetryDelayMs, ensureCloudWorkspaceReadyForSyncService, runWorkspacePullSyncService, runWorkspacePushSyncService, syncUserGlobalSettingsService } from '../sync/syncService';
+/**
+ * useSyncOrchestrator — React hook that orchestrates all cloud sync activity for a workspace.
+ *
+ * Sections:
+ *   - Imports & module-level constants        (line ~1)
+ *   - Pure utility functions                  (line ~28)
+ *   - Public interface & hook entry           (line ~126)
+ *   - State initialization                    (line ~191)
+ *   - User global settings sync              (line ~229)
+ *   - Workspace sync helpers & bootstrap      (line ~516)
+ *   - Auth failure handling & sync readiness  (line ~731)
+ *   - Push sync                               (line ~804)
+ *   - Pull sync                               (line ~985)
+ *   - Realtime sync integration               (line ~1181)
+ *   - Repair & manual retry                   (line ~1239)
+ *   - Diagnostics & reactive effects          (line ~1390)
+ *   - Return value                            (line ~1532)
+ *
+ * Key exports: useSyncOrchestrator, UseSyncOrchestratorInput, WorkspaceSyncStatus
+ */
+// === SECTION: Imports & module-level constants ===
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { ensureCloudWorkspaceReadyForSyncService, isTransientWorkspaceSyncStatus, runWorkspacePullSyncService, runWorkspacePushSyncService, 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';
-// ---------------------------------------------------------------------------
-// Module-level constants & helpers (moved from useTaskforce)
-// ---------------------------------------------------------------------------
+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_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;
+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.';
+// === 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;
@@ -29,6 +57,29 @@ function logSyncDebug(event, details) {
     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 {};
@@ -37,7 +88,9 @@ function readUserGlobalSyncMeta() {
         if (!raw)
             return {};
         const parsed = JSON.parse(raw);
-        return parsed && typeof parsed === 'object' ? parsed : {};
+        return parsed && typeof parsed === 'object'
+            ? parsed
+            : {};
     }
     catch {
         return {};
@@ -53,30 +106,182 @@ function writeUserGlobalSyncMeta(next) {
         // best-effort only
     }
 }
-// ---------------------------------------------------------------------------
-// Hook
-// ---------------------------------------------------------------------------
+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.';
+    if (phase === 'provision-local') {
+        return busy
+            ? 'Uploading this workspace to cloud for the first time.'
+            : 'Preparing the first upload to cloud.';
+    }
+    if (phase === 'attach-cloud') {
+        return busy
+            ? 'Pulling the cloud workspace into this device.'
+            : 'Waiting for the first cloud pull into this device.';
+    }
+    if (retryAt) {
+        return 'Sync hit a temporary problem and will retry automatically.';
+    }
+    if (lastErrorMessage) {
+        return 'Sync needs attention before it can continue.';
+    }
+    if (busy) {
+        return 'Sync is currently running.';
+    }
+    return 'Sync is healthy.';
+}
+function recommendSyncAction(enabled, phase, retryAt, lastErrorMessage) {
+    if (!enabled) {
+        return 'Turn on sync when you are ready to back up this workspace.';
+    }
+    if (phase === 'provision-local') {
+        return 'Keep this window open while the first upload finishes. If it seems stalled, press Sync.';
+    }
+    if (phase === 'attach-cloud') {
+        return 'Keep this window open for the first cloud pull. If it does not move, press Repair.';
+    }
+    if (retryAt) {
+        return 'Wait for the automatic retry, or press Sync to retry now.';
+    }
+    if (lastErrorMessage) {
+        return 'Press Sync to retry. If the same error keeps returning, press Repair.';
+    }
+    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,
+    assets: false,
+    documentReviewSessions: false,
+    annotatedAttachmentSessions: false
+};
 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 { 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 taxonomyStateFingerprint = useMemo(() => buildTaxonomyStateFingerprint(taxonomyState), [taxonomyState]);
+    // === SECTION: State initialization ===
     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 [workspaceSyncPhase, setWorkspaceSyncPhase] = useState('idle');
+    const [workspaceSyncBusy, setWorkspaceSyncBusy] = useState(false);
+    const [workspaceSyncPendingChanges, setWorkspaceSyncPendingChanges] = useState(0);
+    const [workspaceSyncMarkdownDocuments, setWorkspaceSyncMarkdownDocuments] = useState([]);
+    const [workspaceSyncMarkdownDocumentsFingerprint, setWorkspaceSyncMarkdownDocumentsFingerprint] = useState('');
+    // Ref mirror kept in sync with state — readable synchronously inside callbacks to avoid
+    // stale-closure issues when buildWorkspaceSyncPayload is called after an async refresh.
+    const workspaceTasksRef = useRef(tasks || []);
+    const workspaceArchivedTasksRef = useRef(archivedTasks || []);
+    const workspaceInitiativesRef = useRef(initiatives || []);
+    const workspaceWorkstreamsRef = useRef(workstreams || []);
+    const workspaceSyncMarkdownDocumentsRef = useRef([]);
+    const [workspaceSyncAiProfiles, setWorkspaceSyncAiProfiles] = useState([]);
+    const [workspaceSyncAiProfilesFingerprint, setWorkspaceSyncAiProfilesFingerprint] = useState('');
+    const [workspaceSyncAiProfilesLastFetchAt, setWorkspaceSyncAiProfilesLastFetchAt] = useState(null);
+    const [workspaceSyncAiProfilesLastFetchError, setWorkspaceSyncAiProfilesLastFetchError] = useState(null);
+    const [workspaceSyncAiProfilesRawCount, setWorkspaceSyncAiProfilesRawCount] = useState(0);
+    const [workspaceSyncAiProfilesLastSkipReason, setWorkspaceSyncAiProfilesLastSkipReason] = useState(null);
+    const workspaceSyncAiProfilesRef = useRef([]);
+    const [workspaceSyncAssets, setWorkspaceSyncAssets] = useState([]);
+    const [workspaceSyncAssetsFingerprint, setWorkspaceSyncAssetsFingerprint] = useState('');
+    const workspaceSyncAssetsRef = useRef([]);
+    const [workspaceSyncDocumentReviewSessions, setWorkspaceSyncDocumentReviewSessions] = useState([]);
+    const [workspaceSyncDocumentReviewSessionsFingerprint, setWorkspaceSyncDocumentReviewSessionsFingerprint] = useState('');
+    const workspaceSyncDocumentReviewSessionsRef = useRef([]);
+    const workspaceSyncDocumentReviewCommentsRef = useRef([]);
+    const [workspaceSyncAnnotatedAttachmentSessions, setWorkspaceSyncAnnotatedAttachmentSessions] = useState([]);
+    const [workspaceSyncAnnotatedAttachmentSessionsFingerprint, setWorkspaceSyncAnnotatedAttachmentSessionsFingerprint] = useState('');
+    const workspaceSyncAnnotatedAttachmentSessionsRef = useRef([]);
+    const [workspaceSyncReferenceSnapshotStatus, setWorkspaceSyncReferenceSnapshotStatus] = useState(EMPTY_WORKSPACE_SYNC_REFERENCE_SNAPSHOT_STATUS);
     const [realtimeConnectionState, setRealtimeConnectionState] = useState('degraded-fallback');
     const [realtimeTelemetry, setRealtimeTelemetry] = useState({
         accepted: 0,
@@ -85,38 +290,27 @@ export function useSyncOrchestrator(input) {
         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 workspaceSyncMarkdownDocumentsFingerprintRef = useRef('');
+    const workspaceSyncAiProfilesFingerprintRef = useRef('');
+    const workspaceSyncAssetsFingerprintRef = useRef('');
+    const workspaceSyncDocumentReviewSessionsFingerprintRef = useRef('');
+    const workspaceSyncAnnotatedAttachmentSessionsFingerprintRef = 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 retryWorkspaceSyncRef = useRef(() => Promise.resolve(false));
     const syncUserGlobalSettingsRef = useRef(async () => { });
+    const bootstrapPhaseStartedAtRef = useRef(null);
+    const bootstrapLastProgressAtRef = useRef(null);
+    const lastBootstrapPhaseRef = useRef('idle');
+    // === SECTION: User global settings sync ===
     const clearUserSettingsRetry = useCallback(() => {
         if (userSettingsRetryTimeoutRef.current !== null) {
             window.clearTimeout(userSettingsRetryTimeoutRef.current);
@@ -129,59 +323,160 @@ export function useSyncOrchestrator(input) {
         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);
+        const computedDelay = 1500 * (2 ** Math.max(0, nextAttempt - 1));
+        const retryAfterFloor = Number.isFinite(Number(minDelayMs))
+            ? Math.max(0, Math.floor(Number(minDelayMs)))
+            : 0;
+        const delayMs = Math.max(Math.min(120_000, 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);
+        workspaceSyncMarkdownDocumentsFingerprintRef.current = '';
+        workspaceSyncAiProfilesFingerprintRef.current = '';
+        workspaceSyncAssetsFingerprintRef.current = '';
+        workspaceSyncDocumentReviewSessionsFingerprintRef.current = '';
+        workspaceSyncAnnotatedAttachmentSessionsFingerprintRef.current = '';
+        workspaceAttachBootstrapBaselineSignatureRef.current = '';
+        workspaceCaptureAttachBootstrapBaselineRef.current = false;
+        setWorkspaceSyncMarkdownDocuments([]);
+        setWorkspaceSyncMarkdownDocumentsFingerprint('');
+        workspaceSyncAiProfilesRef.current = [];
+        setWorkspaceSyncAiProfiles([]);
+        setWorkspaceSyncAiProfilesFingerprint('');
+        setWorkspaceSyncAssets([]);
+        setWorkspaceSyncAssetsFingerprint('');
+        workspaceSyncDocumentReviewSessionsRef.current = [];
+        workspaceSyncDocumentReviewCommentsRef.current = [];
+        setWorkspaceSyncDocumentReviewSessions([]);
+        setWorkspaceSyncDocumentReviewSessionsFingerprint('');
+        workspaceSyncAnnotatedAttachmentSessionsRef.current = [];
+        setWorkspaceSyncAnnotatedAttachmentSessions([]);
+        setWorkspaceSyncAnnotatedAttachmentSessionsFingerprint('');
+        setWorkspaceSyncReferenceSnapshotStatus(EMPTY_WORKSPACE_SYNC_REFERENCE_SNAPSHOT_STATUS);
+        setWorkspaceLastErrorMessage(null);
+        setWorkspaceLastErrorAt(null);
+        setWorkspaceSyncPendingChanges(0);
+        realtimeSuppressedEventIdsRef.current = new Set();
+        realtimeSuppressedEventQueueRef.current = [];
+        // Reset watermarks for the new workspace, then restore from localStorage if recent
+        // enough. This prevents a full resync on every page reload while still catching any
+        // changes that happened while the app was closed.
         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();
-        realtimeSuppressedEventIdsRef.current = new Set();
-        realtimeSuppressedEventQueueRef.current = [];
-    }, [currentWorkspaceId]);
-    // -----------------------------------------------------------------------
-    // useWorkspaceSyncController
-    // -----------------------------------------------------------------------
-    const handleFailureRecorded = useCallback(() => {
-        setWorkspaceLastErrorAt(new Date().toISOString());
+        workspaceLastPushedAssetPathsRef.current = new Set();
+        workspaceLastPushedAssetWatermarksRef.current = new Map();
+        workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set();
+        workspaceLastPushedDocumentReviewSessionWatermarksRef.current = new Map();
+        workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set();
+        workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map();
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
+        const persisted = readPersistedSyncWatermarks(currentWorkspaceId, taxonomyStateFingerprint);
+        if (persisted) {
+            workspaceLastPushedWatermarksRef.current = persisted.taskWatermarks;
+            workspaceLastPushedInitiativeWatermarksRef.current = persisted.initiativeWatermarks;
+            workspaceLastPushedWorkstreamWatermarksRef.current = persisted.workstreamWatermarks;
+            workspaceLastPushedDocumentWatermarksRef.current = persisted.documentWatermarks;
+            workspaceLastPushedAssetWatermarksRef.current = persisted.assetWatermarks;
+            workspaceLastPushedDocumentReviewSessionWatermarksRef.current = persisted.documentReviewSessionWatermarks;
+            workspaceLastPushedDocumentReviewCommentWatermarksRef.current = persisted.documentReviewCommentWatermarks;
+            workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = persisted.annotatedAttachmentSessionWatermarks;
+        }
+    }, [currentWorkspaceId, taxonomyStateFingerprint]);
+    const markWorkspaceSyncReferenceSnapshotReady = useCallback((key) => {
+        setWorkspaceSyncReferenceSnapshotStatus((current) => (current[key]
+            ? current
+            : {
+                ...current,
+                [key]: true
+            }));
     }, []);
-    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({
+    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({
         currentWorkspaceId,
-        setWorkspaceSyncReady,
-        setWorkspaceCloudHydrated,
-        onFailureRecorded: handleFailureRecorded,
         setWorkspaceCloudSyncEnabled,
-        setWorkspaceSyncSourceOfTruth,
-        setWorkspaceSyncOnboardingCompleted,
-        setUserGlobalLastSyncedAt,
+        setWorkspaceSyncPhase,
         setWorkspaceLastPullAt,
-        setWorkspaceLastPushAt
+        setWorkspaceLastPushAt,
+        setWorkspaceLastErrorMessage
     });
-    // -----------------------------------------------------------------------
-    // 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 workspaceLastPushedInitiativeIdsRef = useRef(new Set());
+    const workspaceLastPushedInitiativeWatermarksRef = useRef(new Map());
+    const workspaceLastPushedWorkstreamIdsRef = useRef(new Set());
+    const workspaceLastPushedWorkstreamWatermarksRef = useRef(new Map());
+    const workspaceLastPushedAiProfileIdsRef = useRef(new Set());
+    const workspaceLastPushedAiProfileWatermarksRef = useRef(new Map());
     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 workspaceLastPushedAssetPathsRef = useRef(new Set());
+    const workspaceLastPushedAssetWatermarksRef = useRef(new Map());
+    const workspaceLastPushedDocumentReviewSessionIdsRef = useRef(new Set());
+    const workspaceLastPushedDocumentReviewSessionWatermarksRef = useRef(new Map());
+    const workspaceLastPushedDocumentReviewCommentIdsRef = useRef(new Set());
+    const workspaceLastPushedDocumentReviewCommentWatermarksRef = useRef(new Map());
+    const workspaceLastPushedAnnotatedAttachmentSessionIdsRef = useRef(new Set());
+    const workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef = useRef(new Map());
+    const workspaceStartupRepairRanRef = 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 workspaceLastSuccessfulSyncAt = useMemo(() => {
+        const pullMs = workspaceLastPullAt ? Date.parse(workspaceLastPullAt) : NaN;
+        const pushMs = workspaceLastPushAt ? Date.parse(workspaceLastPushAt) : NaN;
+        if (Number.isFinite(pullMs) && Number.isFinite(pushMs)) {
+            return pullMs >= pushMs ? workspaceLastPullAt : workspaceLastPushAt;
+        }
+        if (Number.isFinite(pullMs))
+            return workspaceLastPullAt;
+        if (Number.isFinite(pushMs))
+            return workspaceLastPushAt;
+        return null;
+    }, [workspaceLastPullAt, workspaceLastPushAt]);
+    const workspaceSyncStatus = useMemo(() => {
+        if (!workspaceCloudSyncEnabled)
+            return 'off';
+        if (workspaceSyncBusy || workspaceSyncPhase === 'provision-local' || workspaceSyncPhase === 'attach-cloud') {
+            return 'syncing';
+        }
+        if (workspaceRetryAt || workspaceLastErrorMessage || workspaceSyncPhase === 'error') {
+            return 'attention';
+        }
+        return 'healthy';
+    }, [
+        workspaceCloudSyncEnabled,
+        workspaceSyncBusy,
+        workspaceSyncPhase,
+        workspaceRetryAt,
+        workspaceLastErrorMessage
+    ]);
+    const workspaceSyncSummary = useMemo(() => summarizeSyncPhase(workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceSyncBusy, workspaceRetryAt, workspaceLastErrorMessage), [
+        workspaceCloudSyncEnabled,
+        workspaceSyncPhase,
+        workspaceSyncBusy,
+        workspaceRetryAt,
+        workspaceLastErrorMessage
+    ]);
+    const workspaceSyncRecommendedAction = useMemo(() => recommendSyncAction(workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceRetryAt, workspaceLastErrorMessage), [
+        workspaceCloudSyncEnabled,
+        workspaceSyncPhase,
+        workspaceRetryAt,
+        workspaceLastErrorMessage
+    ]);
     const getLocalUserSyncUpdatedAt = useCallback((userId) => {
         const key = String(userId || '').trim();
         if (!key)
@@ -216,14 +511,15 @@ export function useSyncOrchestrator(input) {
         applyingRemoteUserSettingsRef.current = true;
         try {
             const patch = {};
-            if (remote.theme === 'dark' || remote.theme === 'light' || remote.theme === 'midnight') {
-                setGlobalTheme(remote.theme);
+            const remoteTheme = normalizeTaskforceTheme(remote.theme);
+            if (remoteTheme) {
+                setGlobalTheme(remoteTheme);
                 if (themeUseGlobalDefault)
-                    setCurrentTheme(remote.theme);
-                patch.theme = remote.theme;
+                    setCurrentTheme(remoteTheme);
+                patch.theme = remoteTheme;
             }
             if (remote.operatingMode === 'core' || remote.operatingMode === 'operations') {
-                setSetupState((prev) => prev ? { ...prev, mode: remote.operatingMode } : prev);
+                setSetupState((prev) => (prev ? { ...prev, mode: remote.operatingMode } : prev));
                 patch.setup = { mode: remote.operatingMode };
             }
             if (remote.localization && typeof remote.localization === 'object') {
@@ -253,7 +549,14 @@ export function useSyncOrchestrator(input) {
         finally {
             applyingRemoteUserSettingsRef.current = false;
         }
-    }, [themeUseGlobalDefault, setGlobalTheme, setCurrentTheme, setSetupState, setLocale, setGlobalWeekStartsOn]);
+    }, [
+        themeUseGlobalDefault,
+        setGlobalTheme,
+        setCurrentTheme,
+        setSetupState,
+        setLocale,
+        setGlobalWeekStartsOn
+    ]);
     const syncUserGlobalSettings = useCallback(async (options) => {
         const preferCloudOnFirstSync = options?.preferCloudOnFirstSync !== false;
         if (!cloudAuthConfigured)
@@ -302,8 +605,6 @@ export function useSyncOrchestrator(input) {
             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);
@@ -320,15 +621,15 @@ export function useSyncOrchestrator(input) {
             userSettingsSyncInFlightRef.current = false;
         }
     }, [
+        cloudAuthConfigured,
         runtimeMode,
         isAuthenticated,
         authUserId,
+        resolveCloudAuthUrl,
         getLocalUserSyncUpdatedAt,
-        setLocalUserSyncUpdatedAt,
-        applyRemoteUserGlobalSyncPayload,
         buildUserGlobalSyncPayload,
-        resolveCloudAuthUrl,
-        cloudAuthConfigured,
+        applyRemoteUserGlobalSyncPayload,
+        setLocalUserSyncUpdatedAt,
         clearUserSettingsRetry,
         scheduleUserSettingsRetry
     ]);
@@ -340,9 +641,74 @@ export function useSyncOrchestrator(input) {
             clearUserSettingsRetry();
         };
     }, [clearUserSettingsRetry]);
-    // -----------------------------------------------------------------------
-    // Workspace sync helpers
-    // -----------------------------------------------------------------------
+    // === SECTION: Workspace sync helpers & bootstrap ===
+    const clearWorkspaceIssue = useCallback(() => {
+        setWorkspaceLastErrorMessage(null);
+        setWorkspaceLastErrorAt(null);
+    }, []);
+    const reportWorkspaceWindowContention = useCallback((operation) => {
+        setWorkspaceLastErrorMessage(WORKSPACE_CONCURRENT_WINDOW_MESSAGE);
+        setWorkspaceLastErrorAt(new Date().toISOString());
+        setUserGlobalSyncStatus('error');
+        setUserGlobalSyncError(WORKSPACE_CONCURRENT_WINDOW_MESSAGE);
+        logSyncDebug('workspace_sync_window_contention', {
+            workspaceId: currentWorkspaceId,
+            operation
+        });
+    }, [currentWorkspaceId]);
+    const persistWorkspaceSyncPatchSafely = useCallback((patch) => {
+        void persistWorkspaceSyncPatch(patch).catch(() => { });
+    }, [persistWorkspaceSyncPatch]);
+    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;
+    }, [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);
+    }, [
+        currentWorkspaceId,
+        workspaceCloudSyncEnabled,
+        workspaceSyncPhase,
+        persistWorkspaceSyncPatchSafely,
+        workspacePullInFlightRef,
+        workspacePushInFlightRef
+    ]);
     const ensureCloudWorkspaceReadyForSync = useCallback(async () => {
         return ensureCloudWorkspaceReadyForSyncService({
             cloudAuthConfigured,
@@ -360,20 +726,58 @@ export function useSyncOrchestrator(input) {
         currentWorkspaceId,
         projectName
     ]);
-    const buildWorkspaceSyncPayload = useCallback(() => {
+    useEffect(() => {
+        workspaceTasksRef.current = tasks || [];
+    }, [tasks]);
+    useEffect(() => {
+        workspaceArchivedTasksRef.current = archivedTasks || [];
+    }, [archivedTasks]);
+    useEffect(() => {
+        workspaceInitiativesRef.current = initiatives || [];
+    }, [initiatives]);
+    useEffect(() => {
+        workspaceWorkstreamsRef.current = workstreams || [];
+    }, [workstreams]);
+    const workspaceForceFullAiProfilePushRef = 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
+        // fetched by an immediately-preceding async refresh is used, even when React has not
+        // yet committed the corresponding state update (stale-closure guard).
         return buildWorkspaceSyncPayloadModel({
-            tasks: tasks || [],
-            archivedTasks: archivedTasks || [],
+            tasks: workspaceTasksRef.current,
+            archivedTasks: workspaceArchivedTasksRef.current,
             lastPushedTaskIds: workspaceLastPushedTaskIdsRef.current,
             pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
+            initiatives: workspaceInitiativesRef.current,
+            workstreams: workspaceWorkstreamsRef.current,
             taxonomies: taxonomies || [],
-            documents: workspaceSyncDocuments || [],
+            taxonomyState,
+            lastPushedInitiativeIds: workspaceLastPushedInitiativeIdsRef.current,
+            lastPushedInitiativeWatermarks: workspaceLastPushedInitiativeWatermarksRef.current,
+            lastPushedWorkstreamIds: workspaceLastPushedWorkstreamIdsRef.current,
+            lastPushedWorkstreamWatermarks: workspaceLastPushedWorkstreamWatermarksRef.current,
+            aiProfiles: workspaceSyncAiProfilesRef.current,
+            lastPushedAiProfileIds: forceAllAiProfiles ? new Set() : workspaceLastPushedAiProfileIdsRef.current,
+            lastPushedAiProfileWatermarks: forceAllAiProfiles ? new Map() : workspaceLastPushedAiProfileWatermarksRef.current,
+            documents: workspaceSyncMarkdownDocumentsRef.current,
+            assets: workspaceSyncAssetsRef.current,
+            documentReviewSessions: workspaceSyncDocumentReviewSessionsRef.current,
+            documentReviewComments: workspaceSyncDocumentReviewCommentsRef.current,
+            annotatedAttachmentSessions: workspaceSyncAnnotatedAttachmentSessionsRef.current,
             lastPushedDocumentPaths: workspaceLastPushedDocumentPathsRef.current,
             lastPushedDocumentWatermarks: workspaceLastPushedDocumentWatermarksRef.current,
+            lastPushedAssetPaths: workspaceLastPushedAssetPathsRef.current,
+            lastPushedAssetWatermarks: workspaceLastPushedAssetWatermarksRef.current,
+            lastPushedDocumentReviewSessionIds: workspaceLastPushedDocumentReviewSessionIdsRef.current,
+            lastPushedDocumentReviewSessionWatermarks: workspaceLastPushedDocumentReviewSessionWatermarksRef.current,
+            lastPushedDocumentReviewCommentIds: workspaceLastPushedDocumentReviewCommentIdsRef.current,
+            lastPushedDocumentReviewCommentWatermarks: workspaceLastPushedDocumentReviewCommentWatermarksRef.current,
+            lastPushedAnnotatedAttachmentSessionIds: workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current,
+            lastPushedAnnotatedAttachmentSessionWatermarks: workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current,
             lastPushedWatermarks: workspaceLastPushedWatermarksRef.current
         });
-    }, [tasks, archivedTasks, taxonomies, workspaceSyncDocuments]);
-    // Fire-and-forget: persist browser-side sync event to the local SQLite event log.
+    }, [taxonomies, taxonomyState]);
     const reportSyncEvent = useCallback((workspaceId, event) => {
         if (runtimeMode !== 'local')
             return;
@@ -392,23 +796,66 @@ export function useSyncOrchestrator(input) {
         });
     }, [runtimeMode]);
     const buildWorkspaceSyncSignature = useCallback(() => {
+        // Read documents and assets from refs for the same stale-closure reason as
+        // buildWorkspaceSyncPayload — the signature must reflect the freshest known data.
         return buildWorkspaceSyncSignatureModel({
             workspaceId: currentWorkspaceId,
-            tasks: tasks || [],
-            archivedTasks: archivedTasks || [],
+            tasks: workspaceTasksRef.current,
+            archivedTasks: workspaceArchivedTasksRef.current,
             pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
+            initiatives: workspaceInitiativesRef.current,
+            workstreams: workspaceWorkstreamsRef.current,
             taxonomies: taxonomies || [],
-            documents: workspaceSyncDocuments || []
+            aiProfiles: workspaceSyncAiProfilesRef.current,
+            documents: workspaceSyncMarkdownDocumentsRef.current,
+            assets: workspaceSyncAssetsRef.current,
+            documentReviewSessions: workspaceSyncDocumentReviewSessionsRef.current,
+            documentReviewComments: workspaceSyncDocumentReviewCommentsRef.current,
+            annotatedAttachmentSessions: workspaceSyncAnnotatedAttachmentSessionsRef.current
         });
-    }, [tasks, archivedTasks, currentWorkspaceId, taxonomies, workspaceSyncDocuments]);
-    const refreshWorkspaceSyncDocumentsSnapshot = useCallback(async () => {
+    }, [currentWorkspaceId, taxonomies]);
+    // 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.
+    const taskAttachmentsFingerprint = useMemo(() => {
+        const parts = [];
+        for (const task of tasks || []) {
+            const count = Array.isArray(task.attachments) ? task.attachments.length : 0;
+            if (count > 0)
+                parts.push(`${task.id}:${count}`);
+        }
+        return parts.join('|');
+    }, [tasks]);
+    const shouldSuppressAttachBootstrapPush = useCallback((signature) => {
+        if (!signature)
+            return false;
+        if (workspaceCaptureAttachBootstrapBaselineRef.current) {
+            workspaceCaptureAttachBootstrapBaselineRef.current = false;
+            workspaceAttachBootstrapBaselineSignatureRef.current = signature;
+            workspaceLastPushedSignatureRef.current = signature;
+            setWorkspaceSyncPendingChanges(0);
+            return true;
+        }
+        const baselineSignature = workspaceAttachBootstrapBaselineSignatureRef.current;
+        if (!baselineSignature)
+            return false;
+        if (signature === baselineSignature) {
+            workspaceLastPushedSignatureRef.current = signature;
+            setWorkspaceSyncPendingChanges(0);
+            return true;
+        }
+        workspaceAttachBootstrapBaselineSignatureRef.current = '';
+        return false;
+    }, []);
+    const refreshWorkspaceSyncMarkdownDocumentsSnapshot = useCallback(async () => {
         if (runtimeMode !== 'local')
             return;
-        const workspaceKey = String(currentWorkspaceId || '').trim();
-        if (!workspaceKey || workspaceKey.toLowerCase() === 'default')
+        if (!isValidWorkspaceKey(currentWorkspaceId))
+            return;
+        if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated))
             return;
         try {
-            const res = await fetch(`/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(workspaceKey)}`, {
+            const res = await fetch(`/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
                 method: 'GET',
                 credentials: 'include'
             });
@@ -420,188 +867,522 @@ export function useSyncOrchestrator(input) {
                     .map((entry) => ({
                     path: String(entry?.path || '').trim(),
                     updatedAt: String(entry?.updatedAt || '').trim(),
-                    content: typeof entry?.content === 'string' ? entry.content : ''
+                    content: typeof entry?.content === 'string' ? entry.content : '',
+                    assetId: typeof entry?.assetId === 'string' && entry.assetId.trim().length > 0 ? entry.assetId.trim() : undefined,
+                    documentId: typeof entry?.documentId === 'string' && entry.documentId.trim().length > 0 ? entry.documentId.trim() : null,
+                    referenceNumber: Number.isFinite(Number(entry?.referenceNumber)) ? Math.max(1, Math.floor(Number(entry.referenceNumber))) : null,
+                    version: Number.isFinite(Number(entry?.version)) ? Math.max(1, Math.floor(Number(entry.version))) : null,
+                    taskId: typeof entry?.taskId === 'string' && entry.taskId.trim().length > 0 ? entry.taskId.trim() : null,
+                    logicalName: typeof entry?.logicalName === 'string' && entry.logicalName.trim().length > 0 ? entry.logicalName.trim() : null,
+                    caption: typeof entry?.caption === 'string' && entry.caption.trim().length > 0 ? entry.caption.trim() : null,
+                    originalFilename: typeof entry?.originalFilename === 'string' && entry.originalFilename.trim().length > 0 ? entry.originalFilename.trim() : null,
+                    linkRole: entry?.linkRole === 'reference' ? 'reference' : 'attachment'
                 }))
                     .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)
+            if (fingerprint === workspaceSyncMarkdownDocumentsFingerprintRef.current)
                 return;
-            workspaceSyncDocumentsFingerprintRef.current = fingerprint;
-            setWorkspaceSyncDocuments(docs);
-            setWorkspaceSyncDocumentsFingerprint(fingerprint);
+            workspaceSyncMarkdownDocumentsFingerprintRef.current = fingerprint;
+            workspaceSyncMarkdownDocumentsRef.current = docs;
+            setWorkspaceSyncMarkdownDocuments(docs);
+            setWorkspaceSyncMarkdownDocumentsFingerprint(fingerprint);
         }
         catch (error) {
-            const detail = String(error?.message || error || '');
             logSyncDebug('documents_snapshot_refresh_failed', {
-                workspaceId: workspaceKey,
-                error: detail
+                workspaceId: currentWorkspaceId,
+                error: String(error?.message || error || '')
             });
-            reportSyncEvent(workspaceKey, {
-                eventType: 'push',
-                status: 'error',
-                errorMessage: `Workspace documents snapshot refresh failed: ${detail}`
+        }
+        finally {
+            markWorkspaceSyncReferenceSnapshotReady('documents');
+        }
+    }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
+    const refreshWorkspaceSyncAiProfilesSnapshot = useCallback(async () => {
+        if (runtimeMode !== 'local') {
+            setWorkspaceSyncAiProfilesLastSkipReason('runtime-not-local');
+            return;
+        }
+        if (!isValidWorkspaceKey(currentWorkspaceId)) {
+            setWorkspaceSyncAiProfilesLastSkipReason('workspace-id-invalid');
+            return;
+        }
+        if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated)) {
+            setWorkspaceSyncAiProfilesLastSkipReason(!authSessionResolved ? 'auth-unresolved' : 'auth-required');
+            return;
+        }
+        setWorkspaceSyncAiProfilesLastSkipReason(null);
+        try {
+            const res = await fetch(`/api/taskforce/sync/workspace/ai-profiles?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
+                method: 'GET',
+                credentials: 'include'
             });
+            if (!res.ok) {
+                setWorkspaceSyncAiProfilesLastFetchError(`HTTP ${res.status}`);
+                setWorkspaceSyncAiProfilesLastFetchAt(new Date().toISOString());
+                return;
+            }
+            const data = await res.json().catch(() => ({}));
+            const rawAiProfiles = Array.isArray(data?.aiProfiles) ? data.aiProfiles : [];
+            setWorkspaceSyncAiProfilesRawCount(rawAiProfiles.length);
+            const aiProfiles = Array.isArray(data?.aiProfiles)
+                ? data.aiProfiles
+                    .map((entry) => normalizeWorkspaceSyncAiProfileSnapshotEntry(entry))
+                    .filter((entry) => entry.id.length > 0 && entry.workspaceId.length > 0)
+                : [];
+            setWorkspaceSyncAiProfilesLastFetchError(null);
+            setWorkspaceSyncAiProfilesLastFetchAt(new Date().toISOString());
+            const fingerprint = typeof data?.fingerprint === 'string'
+                ? data.fingerprint
+                : JSON.stringify(aiProfiles.map((entry) => `${entry.id}:${entry.updatedAt}:${entry.name}:${entry.username}`).sort());
+            if (fingerprint === workspaceSyncAiProfilesFingerprintRef.current)
+                return;
+            workspaceSyncAiProfilesFingerprintRef.current = fingerprint;
+            workspaceSyncAiProfilesRef.current = aiProfiles;
+            setWorkspaceSyncAiProfiles(aiProfiles);
+            setWorkspaceSyncAiProfilesFingerprint(fingerprint);
+        }
+        catch (error) {
+            setWorkspaceSyncAiProfilesLastFetchError(String(error?.message || error || 'unknown-error'));
+            setWorkspaceSyncAiProfilesLastFetchAt(new Date().toISOString());
+            logSyncDebug('ai_profiles_snapshot_refresh_failed', {
+                workspaceId: currentWorkspaceId,
+                error: String(error?.message || error || '')
+            });
+        }
+        finally {
+            markWorkspaceSyncReferenceSnapshotReady('aiProfiles');
         }
-    }, [runtimeMode, currentWorkspaceId, reportSyncEvent]);
+    }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
+    const refreshWorkspaceSyncAssetsSnapshot = useCallback(async () => {
+        if (runtimeMode !== 'local')
+            return;
+        if (!isValidWorkspaceKey(currentWorkspaceId))
+            return;
+        if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated))
+            return;
+        try {
+            const res = await fetch(`/api/taskforce/sync/workspace/assets?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
+                method: 'GET',
+                credentials: 'include'
+            });
+            if (!res.ok)
+                return;
+            const data = await res.json().catch(() => ({}));
+            const assets = Array.isArray(data?.assets)
+                ? data.assets
+                    .map((entry) => ({
+                    path: String(entry?.path || '').trim(),
+                    updatedAt: String(entry?.updatedAt || '').trim(),
+                    contentBase64: typeof entry?.contentBase64 === 'string' ? entry.contentBase64 : '',
+                    assetId: typeof entry?.assetId === 'string' && entry.assetId.trim().length > 0 ? entry.assetId.trim() : undefined,
+                    kind: entry?.kind === 'image' ? 'image' : 'file',
+                    mimeType: typeof entry?.mimeType === 'string' && entry.mimeType.trim().length > 0 ? entry.mimeType.trim() : 'application/octet-stream',
+                    referenceNumber: Number.isFinite(Number(entry?.referenceNumber)) ? Math.max(1, Math.floor(Number(entry.referenceNumber))) : null,
+                    taskId: typeof entry?.taskId === 'string' && entry.taskId.trim().length > 0 ? entry.taskId.trim() : null,
+                    logicalName: typeof entry?.logicalName === 'string' && entry.logicalName.trim().length > 0 ? entry.logicalName.trim() : null,
+                    caption: typeof entry?.caption === 'string' && entry.caption.trim().length > 0 ? entry.caption.trim() : null,
+                    originalFilename: typeof entry?.originalFilename === 'string' && entry.originalFilename.trim().length > 0 ? entry.originalFilename.trim() : null,
+                    linkRole: entry?.linkRole === 'reference'
+                        ? 'reference'
+                        : entry?.linkRole === 'image'
+                            ? 'image'
+                            : 'attachment'
+                }))
+                    .filter((entry) => entry.path.length > 0 && entry.contentBase64.length > 0)
+                : [];
+            const fingerprint = typeof data?.fingerprint === 'string'
+                ? data.fingerprint
+                : JSON.stringify(assets.map((entry) => `${entry.path}:${entry.updatedAt}:${entry.contentBase64.length}`).sort());
+            if (fingerprint === workspaceSyncAssetsFingerprintRef.current)
+                return;
+            workspaceSyncAssetsFingerprintRef.current = fingerprint;
+            workspaceSyncAssetsRef.current = assets;
+            setWorkspaceSyncAssets(assets);
+            setWorkspaceSyncAssetsFingerprint(fingerprint);
+        }
+        catch (error) {
+            logSyncDebug('assets_snapshot_refresh_failed', {
+                workspaceId: currentWorkspaceId,
+                error: String(error?.message || error || '')
+            });
+        }
+        finally {
+            markWorkspaceSyncReferenceSnapshotReady('assets');
+        }
+    }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
+    const refreshWorkspaceSyncDocumentReviewSessionsSnapshot = useCallback(async () => {
+        if (runtimeMode !== 'local')
+            return;
+        if (!isValidWorkspaceKey(currentWorkspaceId))
+            return;
+        if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated))
+            return;
+        try {
+            const res = await fetch(`/api/taskforce/sync/workspace/document-reviews?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
+                method: 'GET',
+                credentials: 'include'
+            });
+            if (!res.ok)
+                return;
+            const data = await res.json().catch(() => ({}));
+            const sessions = Array.isArray(data?.sessions)
+                ? data.sessions
+                    .map((entry) => ({
+                    id: String(entry?.id || '').trim(),
+                    assetId: String(entry?.assetId || '').trim(),
+                    documentId: typeof entry?.documentId === 'string' && entry.documentId.trim().length > 0 ? entry.documentId.trim() : null,
+                    documentVersion: Number.isFinite(Number(entry?.documentVersion)) ? Math.max(1, Math.floor(Number(entry.documentVersion))) : null,
+                    title: typeof entry?.title === 'string' && entry.title.trim().length > 0 ? entry.title.trim() : null,
+                    status: entry?.status === 'resolved' ? 'resolved' : 'open',
+                    comments: Array.isArray(entry?.comments) ? entry.comments : [],
+                    createdByActorId: typeof entry?.createdByActorId === 'string' && entry.createdByActorId.trim().length > 0 ? entry.createdByActorId.trim() : null,
+                    updatedByActorId: typeof entry?.updatedByActorId === 'string' && entry.updatedByActorId.trim().length > 0 ? entry.updatedByActorId.trim() : null,
+                    createdAt: String(entry?.createdAt || '').trim(),
+                    updatedAt: String(entry?.updatedAt || entry?.createdAt || '').trim(),
+                    deletedAt: typeof entry?.deletedAt === 'string' && entry.deletedAt.trim().length > 0 ? entry.deletedAt.trim() : null
+                }))
+                    .filter((entry) => entry.id.length > 0 && entry.assetId.length > 0)
+                : [];
+            const comments = Array.isArray(data?.comments)
+                ? data.comments
+                    .map((entry) => ({
+                    id: String(entry?.id || '').trim(),
+                    sessionId: String(entry?.sessionId || '').trim(),
+                    body: typeof entry?.body === 'string' ? entry.body : '',
+                    anchor: entry?.anchor ?? null,
+                    order: Number.isFinite(Number(entry?.order)) ? Math.max(0, Math.floor(Number(entry.order))) : 0,
+                    authorActorId: typeof entry?.authorActorId === 'string' && entry.authorActorId.trim().length > 0 ? entry.authorActorId.trim() : null,
+                    createdAt: String(entry?.createdAt || '').trim(),
+                    updatedAt: String(entry?.updatedAt || entry?.createdAt || '').trim(),
+                    deletedAt: typeof entry?.deletedAt === 'string' && entry.deletedAt.trim().length > 0 ? entry.deletedAt.trim() : null
+                }))
+                    .filter((entry) => entry.id.length > 0 && entry.sessionId.length > 0)
+                : flattenDocumentReviewComments(sessions);
+            const fingerprint = typeof data?.fingerprint === 'string'
+                ? data.fingerprint
+                : JSON.stringify([
+                    ...sessions.map((entry) => `${entry.id}:${entry.updatedAt}:${entry.status}:${entry.deletedAt || ''}:${entry.comments.length}`).sort(),
+                    ...comments.map((entry) => `${entry.id}:${entry.sessionId}:${entry.updatedAt}:${entry.deletedAt || ''}`).sort()
+                ]);
+            if (fingerprint === workspaceSyncDocumentReviewSessionsFingerprintRef.current)
+                return;
+            workspaceSyncDocumentReviewSessionsFingerprintRef.current = fingerprint;
+            workspaceSyncDocumentReviewSessionsRef.current = sessions;
+            workspaceSyncDocumentReviewCommentsRef.current = comments;
+            setWorkspaceSyncDocumentReviewSessions(sessions);
+            setWorkspaceSyncDocumentReviewSessionsFingerprint(fingerprint);
+        }
+        catch (error) {
+            logSyncDebug('document_review_sessions_snapshot_refresh_failed', {
+                workspaceId: currentWorkspaceId,
+                error: String(error?.message || error || '')
+            });
+        }
+        finally {
+            markWorkspaceSyncReferenceSnapshotReady('documentReviewSessions');
+        }
+    }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
+    const refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot = useCallback(async () => {
+        if (runtimeMode !== 'local')
+            return;
+        if (!isValidWorkspaceKey(currentWorkspaceId))
+            return;
+        if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated))
+            return;
+        try {
+            const res = await fetch(`/api/taskforce/sync/workspace/annotated-attachments?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
+                method: 'GET',
+                credentials: 'include'
+            });
+            if (!res.ok)
+                return;
+            const data = await res.json().catch(() => ({}));
+            const sessions = Array.isArray(data?.sessions)
+                ? data.sessions
+                    .map((entry) => ({
+                    id: String(entry?.id || '').trim(),
+                    workspaceId: String(entry?.workspaceId || '').trim(),
+                    taskId: String(entry?.taskId || '').trim(),
+                    baseImageAssetId: String(entry?.baseImageAssetId || '').trim(),
+                    title: typeof entry?.title === 'string' && entry.title.trim().length > 0 ? entry.title.trim() : null,
+                    globalInstruction: typeof entry?.globalInstruction === 'string' && entry.globalInstruction.trim().length > 0 ? entry.globalInstruction.trim() : null,
+                    annotations: Array.isArray(entry?.annotations) ? entry.annotations : [],
+                    createdByActorId: typeof entry?.createdByActorId === 'string' && entry.createdByActorId.trim().length > 0 ? entry.createdByActorId.trim() : null,
+                    updatedByActorId: typeof entry?.updatedByActorId === 'string' && entry.updatedByActorId.trim().length > 0 ? entry.updatedByActorId.trim() : null,
+                    createdAt: String(entry?.createdAt || '').trim(),
+                    updatedAt: String(entry?.updatedAt || entry?.createdAt || '').trim(),
+                    deletedAt: typeof entry?.deletedAt === 'string' && entry.deletedAt.trim().length > 0 ? entry.deletedAt.trim() : null
+                }))
+                    .filter((entry) => (entry.id.length > 0
+                    && entry.workspaceId.length > 0
+                    && entry.taskId.length > 0
+                    && entry.baseImageAssetId.length > 0))
+                : [];
+            const fingerprint = typeof data?.fingerprint === 'string'
+                ? data.fingerprint
+                : JSON.stringify(sessions.map((entry) => `${entry.id}:${entry.updatedAt}:${entry.taskId}:${entry.baseImageAssetId}:${entry.annotations.length}:${entry.deletedAt || ''}`).sort());
+            if (fingerprint === workspaceSyncAnnotatedAttachmentSessionsFingerprintRef.current)
+                return;
+            workspaceSyncAnnotatedAttachmentSessionsFingerprintRef.current = fingerprint;
+            workspaceSyncAnnotatedAttachmentSessionsRef.current = sessions;
+            setWorkspaceSyncAnnotatedAttachmentSessions(sessions);
+            setWorkspaceSyncAnnotatedAttachmentSessionsFingerprint(fingerprint);
+        }
+        catch (error) {
+            logSyncDebug('annotated_attachment_sessions_snapshot_refresh_failed', {
+                workspaceId: currentWorkspaceId,
+                error: String(error?.message || error || '')
+            });
+        }
+        finally {
+            markWorkspaceSyncReferenceSnapshotReady('annotatedAttachmentSessions');
+        }
+    }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
+    const seedWorkspaceSnapshotPushBaseline = useCallback(() => {
+        workspaceLastPushedDocumentPathsRef.current = new Set(workspaceSyncMarkdownDocumentsRef.current
+            .map((entry) => String(entry?.path || '').trim())
+            .filter((path) => path.length > 0));
+        workspaceLastPushedDocumentWatermarksRef.current = new Map(workspaceSyncMarkdownDocumentsRef.current
+            .map((entry) => [String(entry?.path || '').trim(), String(entry?.updatedAt || '').trim()])
+            .filter(([path]) => path.length > 0));
+        workspaceLastPushedAssetPathsRef.current = new Set(workspaceSyncAssetsRef.current
+            .map((entry) => String(entry?.path || '').trim())
+            .filter((path) => path.length > 0));
+        workspaceLastPushedAssetWatermarksRef.current = new Map(workspaceSyncAssetsRef.current
+            .map((entry) => [String(entry?.path || '').trim(), String(entry?.updatedAt || '').trim()])
+            .filter(([path]) => path.length > 0));
+        workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set(workspaceSyncDocumentReviewSessionsRef.current
+            .map((entry) => String(entry?.id || '').trim())
+            .filter((id) => id.length > 0));
+        workspaceLastPushedDocumentReviewSessionWatermarksRef.current = new Map(workspaceSyncDocumentReviewSessionsRef.current
+            .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
+            .filter(([id]) => id.length > 0));
+        workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set(workspaceSyncDocumentReviewCommentsRef.current
+            .map((entry) => String(entry?.id || '').trim())
+            .filter((id) => id.length > 0));
+        workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map(workspaceSyncDocumentReviewCommentsRef.current
+            .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
+            .filter(([id]) => id.length > 0));
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set(workspaceSyncAnnotatedAttachmentSessionsRef.current
+            .map((entry) => String(entry?.id || '').trim())
+            .filter((id) => id.length > 0));
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map(workspaceSyncAnnotatedAttachmentSessionsRef.current
+            .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
+            .filter(([id]) => id.length > 0));
+    }, []);
+    const refreshLocalWorkspaceTaskCollections = useCallback(async () => {
+        const [tasksRes, archiveRes] = await Promise.all([
+            fetch('/api/taskforce/tasks', {
+                method: 'GET',
+                credentials: 'include'
+            }),
+            fetch('/api/taskforce/archive', {
+                method: 'GET',
+                credentials: 'include'
+            })
+        ]);
+        if (tasksRes.ok) {
+            const tasksPayload = await tasksRes.json().catch(() => ({}));
+            const normalizedTasks = Array.isArray(tasksPayload?.tasks)
+                ? tasksPayload.tasks.map((task) => normalizeTaskFromApi(task))
+                : [];
+            setTasks(normalizedTasks);
+        }
+        if (archiveRes.ok) {
+            const archivePayload = await archiveRes.json().catch(() => ({}));
+            const normalizedArchive = Array.isArray(archivePayload?.archived)
+                ? archivePayload.archived.map((task) => ({
+                    ...normalizeTaskFromApi(task),
+                    isArchived: true
+                }))
+                : [];
+            setArchivedTasks(normalizedArchive);
+        }
+        await fetchPlanningEntities().catch(() => {
+            logSyncDebug('refresh_planning_entities_failed', {
+                workspaceId: currentWorkspaceId
+            });
+        });
+    }, [currentWorkspaceId, fetchPlanningEntities, setArchivedTasks, setTasks]);
+    // === SECTION: Auth failure handling & sync readiness ===
     const handleSyncAuthFailure = useCallback(async (source, statusCode) => {
         clearWorkspaceRetry();
-        logSyncDebug('sync_auth_failure', { source, status: statusCode, workspaceId: currentWorkspaceId });
-        incrementWorkspaceSyncAuthFailure();
-        recordWorkspaceSyncFailure(source, statusCode);
+        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();
-    }, [clearWorkspaceRetry, currentWorkspaceId, checkAuthSession, recordWorkspaceSyncFailure, incrementWorkspaceSyncAuthFailure, setAuthBlocked, setIsAuthenticated]);
+    }, [
+        clearWorkspaceRetry,
+        reportSyncEvent,
+        currentWorkspaceId,
+        setAuthBlocked,
+        setIsAuthenticated,
+        checkAuthSession
+    ]);
     const ensureWorkspaceSyncReady = useCallback(async () => {
-        const workspaceKey = String(currentWorkspaceId || '').trim();
-        if (!workspaceKey || workspaceKey.toLowerCase() === 'default') {
-            logSyncDebug('sync_ready_blocked_unresolved_workspace', { workspaceKey, runtimeMode });
-            setUserGlobalSyncStatus('error');
+        if (!isValidWorkspaceKey(currentWorkspaceId)) {
             const message = 'Workspace sync blocked: local workspace ID is unresolved.';
-            setUserGlobalSyncError(message);
             setWorkspaceLastErrorMessage(message);
             setWorkspaceLastErrorAt(new Date().toISOString());
-            setWorkspaceSyncReady(false);
+            setUserGlobalSyncError(message);
+            setUserGlobalSyncStatus('error');
             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);
+        if (ensured.success)
+            return true;
+        if (ensured.statusCode === 401) {
+            await handleSyncAuthFailure('handshake', 401);
             return false;
         }
-        logSyncDebug('sync_ready_ok', { workspaceKey });
-        workspaceSyncReadyRef.current.add(workspaceKey);
-        setWorkspaceSyncReady(true);
-        return true;
+        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,
         ensureCloudWorkspaceReadyForSync,
-        runtimeMode,
-        recordWorkspaceSyncFailure,
         handleSyncAuthFailure,
-        scheduleWorkspacePullRetry
+        reportSyncEvent,
+        scheduleWorkspaceSyncRetry,
+        workspaceSyncPhase,
+        persistWorkspaceSyncPatchSafely
     ]);
-    const pushWorkspaceChangesToCloud = useCallback(async (signature) => {
+    // === 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;
         }
-        const workspaceKey = String(currentWorkspaceId || '').trim();
-        if (!workspaceKey || workspaceKey.toLowerCase() === 'default')
+        if (shouldSuppressAttachBootstrapPush(signature)) {
             return false;
-        if (workspaceSyncSourceOfTruth === 'cloud' && !workspaceCloudHydratedRef.current.has(workspaceKey)) {
+        }
+        if (workspacePushInFlightRef.current || workspacePullInFlightRef.current) {
             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) {
+        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 refreshWorkspaceSyncDocumentsSnapshot();
+            await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+            await refreshWorkspaceSyncAiProfilesSnapshot();
+            await refreshWorkspaceSyncAssetsSnapshot();
+            await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
             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 payload = buildWorkspaceSyncPayload({ forceAllAiProfiles });
+            setWorkspaceSyncPendingChanges(payload.changes.length);
             const pushResult = await runWorkspacePushSyncService({
                 resolveCloudAuthUrl,
                 workspaceId: currentWorkspaceId,
                 payload,
-                ensureCloudWorkspaceReadyForSync
+                ensureCloudWorkspaceReadyForSync,
+                repairMode: options?.repairMode === true || workspaceRepairModeRef.current === true
             });
             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
+                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);
-            // Merge newly pushed watermarks into the per-task map so subsequent
-            // pushes skip tasks that haven't changed since this push.
+            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);
             }
@@ -611,28 +1392,22 @@ export function useSyncOrchestrator(input) {
                     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
+            // 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
             });
-            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))
+                    if (!eventId || realtimeSuppressedEventIdsRef.current.has(eventId))
                         continue;
                     realtimeSuppressedEventIdsRef.current.add(eventId);
                     realtimeSuppressedEventQueueRef.current.push(eventId);
@@ -643,25 +1418,53 @@ export function useSyncOrchestrator(input) {
                         realtimeSuppressedEventIdsRef.current.delete(stale);
                 }
             }
-            void persistWorkspaceSyncPatch({
+            clearWorkspaceRetry();
+            clearWorkspaceIssue();
+            const syncedAt = pushResult.syncedAt || new Date().toISOString();
+            setWorkspaceLastPushAt(syncedAt);
+            setWorkspaceSyncPendingChanges(0);
+            setUserGlobalSyncStatus('idle');
+            persistWorkspaceSyncPatchSafely({
+                phase: 'active',
                 lastPushAt: syncedAt,
-                lastSyncedAt: syncedAt
+                lastSyncedAt: syncedAt,
+                lastErrorMessage: null
+            });
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: workspaceSyncPhase === 'provision-local' ? 'bootstrap' : 'push',
+                status: 'success',
+                changeCount: pushResult.changeCount,
+                requestMs: pushResult.requestMs
             });
             return true;
         }
-        catch {
-            logSyncDebug('push_failed_exception', { workspaceId: currentWorkspaceId, elapsedMs: Date.now() - pushStartedAtMs });
-            recordWorkspaceSyncFailure('push');
-            setUserGlobalSyncStatus('error');
+        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) {
+            if (pendingSignature
+                && pendingSignature !== workspaceLastPushedSignatureRef.current
+                && !workspacePullInFlightRef.current) {
                 workspacePendingSignatureRef.current = '';
                 window.setTimeout(() => {
                     void pushWorkspaceChangesToCloud(pendingSignature);
@@ -671,171 +1474,124 @@ export function useSyncOrchestrator(input) {
     }, [
         cloudAuthConfigured,
         runtimeMode,
+        workspaceCloudSyncEnabled,
+        currentWorkspaceId,
+        workspaceSyncPhase,
         isAuthenticated,
         checkAuthSession,
-        workspaceCloudSyncEnabled,
-        workspaceSyncSourceOfTruth,
-        buildWorkspaceSyncPayload,
+        clearWorkspaceIssue,
+        refreshWorkspaceSyncMarkdownDocumentsSnapshot,
+        refreshWorkspaceSyncAiProfilesSnapshot,
+        refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
         ensureWorkspaceSyncReady,
-        refreshWorkspaceSyncDocumentsSnapshot,
+        buildWorkspaceSyncPayload,
+        resolveCloudAuthUrl,
         ensureCloudWorkspaceReadyForSync,
+        shouldSuppressAttachBootstrapPush,
         handleSyncAuthFailure,
-        recordWorkspaceSyncFailure,
         clearWorkspaceRetry,
-        isWorkspacePullRetryPending,
-        currentWorkspaceId,
-        resolveCloudAuthUrl
+        persistWorkspaceSyncPatch,
+        reportSyncEvent,
+        scheduleWorkspaceSyncRetry,
+        acquireWorkspaceSyncLease,
+        releaseWorkspaceSyncLease,
+        reportWorkspaceWindowContention,
+        workspacePushInFlightRef,
+        workspacePullInFlightRef,
+        persistWorkspaceSyncPatchSafely
     ]);
-    const pullWorkspaceChangesFromCloud = useCallback(async () => {
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled) {
-            logSyncDebug('pull_abort', { reason: 'config_disabled', cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled });
+    // === 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) {
-                logSyncDebug('pull_abort', { reason: 'not_authenticated' });
+            if (!authed)
                 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' });
+        if (workspacePullInFlightRef.current || workspacePushInFlightRef.current)
             return false;
-        }
-        const leaseAcquired = await tryAcquireWorkspacePullLease(workspaceKey);
+        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'pull');
         if (!leaseAcquired) {
-            markWorkspacePullCooldown(workspaceKey, 12_000);
-            logSyncDebug('pull_abort', { reason: 'non_leader_tab', workspaceId: workspaceKey });
+            reportWorkspaceWindowContention('pull');
             return false;
         }
         workspacePullInFlightRef.current = true;
-        const bootstrapThisRun = !workspaceCloudHydratedRef.current.has(workspaceKey);
-        if (bootstrapThisRun) {
-            setWorkspaceBootstrapSyncInProgress(true);
-            setWorkspaceBootstrapSyncPages(0);
-            setWorkspaceBootstrapSyncAppliedChanges(0);
-        }
+        setWorkspaceSyncBusy(true);
         setUserGlobalSyncStatus('syncing');
         setUserGlobalSyncError(null);
         const pullStartedAtMs = Date.now();
         try {
             const ready = await ensureWorkspaceSyncReady();
-            if (!ready) {
-                logSyncDebug('pull_abort', { reason: 'ensure_ready_failed' });
+            if (!ready)
                 return false;
-            }
-            const initialCursor = workspacePullBootstrapDoneRef.current
-                ? workspacePullCursorRef.current
-                : null;
-            logSyncDebug('pull_start', { workspaceId: currentWorkspaceId, cursor: initialCursor });
+            const bootstrap = workspaceSyncPhase === 'attach-cloud';
+            const cursor = bootstrap ? null : workspacePullCursorRef.current;
             const pullResult = await runWorkspacePullSyncService({
                 resolveCloudAuthUrl,
                 workspaceId: currentWorkspaceId,
-                cursor: initialCursor,
-                bootstrap: bootstrapThisRun,
+                cursor,
+                bootstrap,
                 ensureCloudWorkspaceReadyForSync,
                 maxPages: 20,
-                onPagePulled: bootstrapThisRun ? () => {
-                    setWorkspaceBootstrapSyncPages((prev) => prev + 1);
-                } : undefined,
-                onChangesApplied: bootstrapThisRun ? (count) => {
-                    setWorkspaceBootstrapSyncAppliedChanges((prev) => prev + count);
-                } : undefined
+                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') {
-                    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();
-                    }
+                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;
                 }
-                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;
+                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.';
                 }
-                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
+                setWorkspaceLastErrorAt(new Date().toISOString());
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: pullResult.kind?.startsWith('apply') ? 'apply' : 'pull',
+                    status: 'error',
+                    statusCode: pullResult.status,
+                    errorMessage: message,
+                    requestMs: pullResult.pullRequestMs
                 });
+                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 || ''))));
@@ -844,117 +1600,55 @@ export function useSyncOrchestrator(input) {
                 ? 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', {
+                logSyncDebug('pull_document_decrypt_failures', {
                     workspaceId: currentWorkspaceId,
-                    count: decryptFailures.length,
-                    paths: decryptFailures
-                });
-                reportSyncEvent(currentWorkspaceId, {
-                    eventType: 'apply',
-                    status: 'error',
-                    errorMessage: `${warning} paths=${decryptFailures.join(', ')}`,
-                    changeCount: pullResult.appliedChanges
+                    failureCount: decryptFailures.length
                 });
             }
-            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);
-                        }
-                    }
+                    await refreshLocalWorkspaceTaskCollections();
                 }
                 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
-                    });
                 }
             }
+            clearWorkspaceRetry();
+            clearWorkspaceIssue();
             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
+            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: 'pull',
+                eventType: workspaceSyncPhase === 'attach-cloud' ? 'bootstrap' : '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 });
+            if (workspaceSyncPhase === 'attach-cloud') {
+                await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+                await refreshWorkspaceSyncAssetsSnapshot();
+                await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
+                await refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
+                seedWorkspaceSnapshotPushBaseline();
+                return true;
             }
-            const pendingSignature = workspacePendingSignatureRef.current;
+            const pendingSignature = workspacePendingSignatureRef.current || buildWorkspaceSyncSignature();
             if (pendingSignature && pendingSignature !== workspaceLastPushedSignatureRef.current) {
                 workspacePendingSignatureRef.current = '';
                 window.setTimeout(() => {
@@ -963,122 +1657,116 @@ export function useSyncOrchestrator(input) {
             }
             return true;
         }
-        catch {
-            logSyncDebug('pull_failed_exception', { workspaceId: currentWorkspaceId, elapsedMs: Date.now() - pullStartedAtMs });
-            recordWorkspaceSyncFailure('pull');
+        catch (error) {
+            const detail = String(error?.message || '').trim();
+            const message = detail
+                ? `Workspace sync pull failed. ${detail}`
+                : 'Workspace sync pull failed.';
             setUserGlobalSyncStatus('error');
-            const message = 'Workspace sync pull failed.';
             setUserGlobalSyncError(message);
             setWorkspaceLastErrorMessage(message);
-            scheduleWorkspacePullRetry(() => pullFromCloudRef.current(), {
-                workspaceId: workspaceKey
+            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 {
-            if (bootstrapThisRun) {
-                setWorkspaceBootstrapSyncInProgress(false);
-            }
             workspacePullInFlightRef.current = false;
-            releaseWorkspacePullLease(workspaceKey);
+            setWorkspaceSyncBusy(workspacePushInFlightRef.current);
+            releaseWorkspaceSyncLease(currentWorkspaceId);
         }
     }, [
         cloudAuthConfigured,
         runtimeMode,
-        isAuthenticated,
-        checkAuthSession,
         workspaceCloudSyncEnabled,
-        resolveCloudAuthUrl,
         currentWorkspaceId,
-        isWorkspacePullRetryPending,
+        workspaceSyncPhase,
+        isWorkspaceRetryPending,
+        isAuthenticated,
+        checkAuthSession,
+        clearWorkspaceIssue,
         ensureWorkspaceSyncReady,
+        resolveCloudAuthUrl,
+        ensureCloudWorkspaceReadyForSync,
         handleSyncAuthFailure,
-        recordWorkspaceSyncFailure,
+        refreshLocalWorkspaceTaskCollections,
+        refreshWorkspaceSyncMarkdownDocumentsSnapshot,
+        refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
+        refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot,
         clearWorkspaceRetry,
-        scheduleWorkspacePullRetry,
-        tryAcquireWorkspacePullLease,
-        releaseWorkspacePullLease,
-        markWorkspacePullCooldown,
-        reportSyncEvent,
         persistWorkspaceSyncPatch,
-        buildWorkspaceSyncSignature
+        reportSyncEvent,
+        buildWorkspaceSyncSignature,
+        pushWorkspaceChangesToCloud,
+        seedWorkspaceSnapshotPushBaseline,
+        scheduleWorkspaceSyncRetry,
+        acquireWorkspaceSyncLease,
+        releaseWorkspaceSyncLease,
+        reportWorkspaceWindowContention,
+        workspacePushInFlightRef,
+        workspacePullInFlightRef,
+        persistWorkspaceSyncPatchSafely
     ]);
-    // 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]);
+    // === 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)) {
-            logSyncDebug('realtime_signal_suppressed_self_echo', {
-                workspaceId: currentWorkspaceId,
-                eventId,
-                signalType: signal.type
-            });
+        if (eventId && realtimeSuppressedEventIdsRef.current.delete(eventId))
             return;
-        }
-        if (isWorkspacePullRetryPending() || workspacePullInFlightRef.current)
+        if (isWorkspaceRetryPending() || workspacePullInFlightRef.current)
             return;
         if (realtimePullDebounceRef.current !== null) {
             window.clearTimeout(realtimePullDebounceRef.current);
         }
         realtimePullDebounceRef.current = window.setTimeout(() => {
             realtimePullDebounceRef.current = null;
-            void pullFromCloudRef.current();
+            void pullWorkspaceChangesFromCloud();
         }, 180);
     }, [
         cloudAuthConfigured,
         runtimeMode,
         workspaceCloudSyncEnabled,
-        isWorkspacePullRetryPending,
+        workspaceSyncPhase,
+        isWorkspaceRetryPending,
         workspacePullInFlightRef,
-        currentWorkspaceId
+        pullWorkspaceChangesFromCloud
     ]);
     const realtimeSocketUrl = resolveWebSocketUrl('/taskforce-ws');
+    const normalizedRealtimeUserId = String(authUserId || '').trim();
     const realtimeEnabled = Boolean(realtimeSyncEnabled
         && cloudAuthConfigured
         && runtimeMode === 'local'
         && workspaceCloudSyncEnabled
-        && isAuthenticated);
+        && authSessionResolved
+        && isAuthenticated
+        && normalizedRealtimeUserId
+        && normalizedRealtimeUserId !== 'anonymous'
+        && realtimeSocketUrl);
     const realtimeSync = useRealtimeSync({
         enabled: realtimeEnabled,
         workspaceId: currentWorkspaceId,
         websocketUrl: realtimeSocketUrl,
         onSignal: handleRealtimeSignal,
-        onTelemetry: setRealtimeTelemetry
+        onTelemetry: setRealtimeTelemetry,
+        userId: normalizedRealtimeUserId || undefined
     });
     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) {
@@ -1087,6 +1775,7 @@ export function useSyncOrchestrator(input) {
             }
         };
     }, []);
+    // === SECTION: Repair & manual retry ===
     const fetchLocalWorkspaceSnapshot = useCallback(async () => {
         const [localTasksRes, localArchiveRes] = await Promise.all([
             fetch('/api/taskforce/tasks', {
@@ -1112,110 +1801,308 @@ export function useSyncOrchestrator(input) {
             archived: Array.isArray(localArchivePayload?.archived) ? localArchivePayload.archived : []
         };
     }, []);
-    const saveWorkspaceCloudSyncSettings = useCallback(async (input) => {
-        return saveWorkspaceCloudSyncSettingsBase(input, {
+    const saveWorkspaceCloudSyncSettings = useCallback(async (settings) => {
+        return saveWorkspaceCloudSyncSettingsBase(settings, {
             cloudAuthConfigured,
             isAuthenticated,
-            resolveCloudAuthUrl,
-            ensureCloudWorkspaceReadyForSync,
-            fetchLocalWorkspaceSnapshot
+            ensureCloudWorkspaceReadyForSync
         });
     }, [
+        saveWorkspaceCloudSyncSettingsBase,
         cloudAuthConfigured,
         isAuthenticated,
-        resolveCloudAuthUrl,
-        ensureCloudWorkspaceReadyForSync,
-        fetchLocalWorkspaceSnapshot,
-        saveWorkspaceCloudSyncSettingsBase
+        ensureCloudWorkspaceReadyForSync
     ]);
-    // -----------------------------------------------------------------------
-    // Retry / reset functions
-    // -----------------------------------------------------------------------
     const retryUserGlobalSettingsSync = useCallback(async () => {
         await syncUserGlobalSettings({ preferCloudOnFirstSync: false });
     }, [syncUserGlobalSettings]);
     const retryWorkspaceCloudSync = useCallback(async () => {
         clearWorkspaceRetry();
         if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
-            return;
+            return false;
         if (!isAuthenticated) {
             const authed = await checkAuthSession();
             if (!authed)
-                return;
+                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();
-        if (signature && signature !== workspaceLastPushedSignatureRef.current) {
-            void pushWorkspaceChangesToCloud(signature);
+        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;
         }
-        await pullWorkspaceChangesFromCloud();
+        return pulled;
     }, [
         clearWorkspaceRetry,
         cloudAuthConfigured,
         runtimeMode,
+        workspaceCloudSyncEnabled,
         isAuthenticated,
         checkAuthSession,
-        workspaceCloudSyncEnabled,
+        workspaceSyncPhase,
         buildWorkspaceSyncSignature,
+        shouldSuppressAttachBootstrapPush,
         pushWorkspaceChangesToCloud,
         pullWorkspaceChangesFromCloud
     ]);
     const resetWorkspaceSyncCursorAndPull = useCallback(async () => {
-        clearWorkspaceRetry();
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
-            return;
-        if (!isAuthenticated) {
-            const authed = await checkAuthSession();
-            if (!authed)
+        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;
-        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.
+        workspaceAttachBootstrapBaselineSignatureRef.current = '';
+        workspaceCaptureAttachBootstrapBaselineRef.current = false;
+        workspacePendingSignatureRef.current = '';
+        workspaceLastPushedSignatureRef.current = '';
         workspaceLastPushedWatermarksRef.current = new Map();
-        logSyncDebug('pull_cursor_reset', { workspaceId: currentWorkspaceId });
-        void persistWorkspaceSyncPatch({ pullCursor: null });
-        await pullWorkspaceChangesFromCloud();
+        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);
+        }
     }, [
+        acquireWorkspaceSyncLease,
         clearWorkspaceRetry,
-        cloudAuthConfigured,
-        runtimeMode,
-        isAuthenticated,
-        checkAuthSession,
+        clearWorkspaceIssue,
+        currentWorkspaceId,
+        forceClearWorkspaceSyncLease,
         workspaceCloudSyncEnabled,
+        workspaceSyncPhase,
+        persistWorkspaceSyncPatch,
+        buildWorkspaceSyncSignature,
+        workspaceLastPullAt,
+        pullWorkspaceChangesFromCloud,
+        pushWorkspaceChangesToCloud,
+        releaseWorkspaceSyncLease,
+        reportWorkspaceWindowContention
+    ]);
+    // === SECTION: Diagnostics & reactive effects ===
+    const getWorkspaceSyncDiagnostics = useCallback(() => {
+        return {
+            workspaceId: currentWorkspaceId,
+            enabled: workspaceCloudSyncEnabled,
+            phase: workspaceSyncPhase,
+            status: workspaceSyncStatus,
+            summary: workspaceSyncSummary,
+            lastSuccessfulSyncAt: workspaceLastSuccessfulSyncAt,
+            lastPullAt: workspaceLastPullAt,
+            lastPushAt: workspaceLastPushAt,
+            lastErrorAt: workspaceLastErrorAt,
+            pendingChanges: workspaceSyncPendingChanges,
+            lastErrorMessage: workspaceLastErrorMessage,
+            recommendedAction: workspaceSyncRecommendedAction,
+            documentSnapshotCount: workspaceSyncMarkdownDocuments.length,
+            aiProfileSnapshotCount: workspaceSyncAiProfiles.length,
+            aiProfileSnapshotRawCount: workspaceSyncAiProfilesRawCount,
+            aiProfileSnapshotLastFetchAt: workspaceSyncAiProfilesLastFetchAt,
+            aiProfileSnapshotLastFetchError: workspaceSyncAiProfilesLastFetchError,
+            aiProfileSnapshotLastSkipReason: workspaceSyncAiProfilesLastSkipReason,
+            assetSnapshotCount: workspaceSyncAssets.length,
+            documentReviewSessionSnapshotCount: workspaceSyncDocumentReviewSessions.length,
+            documentReviewSessionSnapshotFingerprint: workspaceSyncDocumentReviewSessionsFingerprint,
+            annotatedAttachmentSessionSnapshotCount: workspaceSyncAnnotatedAttachmentSessions.length,
+            annotatedAttachmentSessionSnapshotFingerprint: workspaceSyncAnnotatedAttachmentSessionsFingerprint,
+            lastPushedAiProfileCount: workspaceLastPushedAiProfileIdsRef.current.size,
+            lastPushedAiProfileWatermarkCount: workspaceLastPushedAiProfileWatermarksRef.current.size,
+            forceFullAiProfilePushQueued: workspaceForceFullAiProfilePushRef.current === true
+        };
+    }, [
         currentWorkspaceId,
-        pullWorkspaceChangesFromCloud
+        workspaceCloudSyncEnabled,
+        workspaceSyncPhase,
+        workspaceSyncStatus,
+        workspaceSyncSummary,
+        workspaceLastSuccessfulSyncAt,
+        workspaceLastPullAt,
+        workspaceLastPushAt,
+        workspaceLastErrorAt,
+        workspaceSyncPendingChanges,
+        workspaceLastErrorMessage,
+        workspaceSyncRecommendedAction,
+        workspaceSyncMarkdownDocuments.length,
+        workspaceSyncAiProfiles.length,
+        workspaceSyncAiProfilesRawCount,
+        workspaceSyncAiProfilesLastFetchAt,
+        workspaceSyncAiProfilesLastFetchError,
+        workspaceSyncAiProfilesLastSkipReason,
+        workspaceSyncAssets.length,
+        workspaceSyncDocumentReviewSessions.length,
+        workspaceSyncDocumentReviewSessionsFingerprint,
+        workspaceSyncAnnotatedAttachmentSessions.length,
+        workspaceSyncAnnotatedAttachmentSessionsFingerprint
     ]);
-    // -----------------------------------------------------------------------
-    // Sync effects
-    // -----------------------------------------------------------------------
-    // Documents refresh interval
+    useEffect(() => {
+        retryWorkspaceSyncRef.current = retryWorkspaceCloudSync;
+    }, [retryWorkspaceCloudSync]);
     useEffect(() => {
         if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
             return;
-        void refreshWorkspaceSyncDocumentsSnapshot();
+        if (!authSessionResolved || !isAuthenticated)
+            return;
+        void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+        void refreshWorkspaceSyncAiProfilesSnapshot();
+        void refreshWorkspaceSyncAssetsSnapshot();
+        void refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
+        void refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
+        const handleContextAssetsMutated = (event) => {
+            const detail = event.detail;
+            const eventWorkspaceId = String(detail?.workspaceId || '').trim() || 'default';
+            if (eventWorkspaceId !== currentWorkspaceId)
+                return;
+            void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+            void refreshWorkspaceSyncAiProfilesSnapshot();
+            void refreshWorkspaceSyncAssetsSnapshot();
+            void refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
+            void refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
+        };
+        window.addEventListener(TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT, handleContextAssetsMutated);
         const docsIntervalId = window.setInterval(() => {
-            void refreshWorkspaceSyncDocumentsSnapshot();
-        }, 12000);
-        return () => window.clearInterval(docsIntervalId);
+            void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+        }, workspaceDocumentsRefreshIntervalMs);
+        const aiProfilesIntervalId = window.setInterval(() => {
+            void refreshWorkspaceSyncAiProfilesSnapshot();
+        }, workspaceDocumentsRefreshIntervalMs);
+        const assetsIntervalId = window.setInterval(() => {
+            void refreshWorkspaceSyncAssetsSnapshot();
+        }, workspaceDocumentsRefreshIntervalMs);
+        const documentReviewSessionsIntervalId = window.setInterval(() => {
+            void refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
+        }, workspaceDocumentsRefreshIntervalMs);
+        const annotatedAttachmentSessionsIntervalId = window.setInterval(() => {
+            void refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
+        }, workspaceDocumentsRefreshIntervalMs);
+        return () => {
+            window.removeEventListener(TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT, handleContextAssetsMutated);
+            window.clearInterval(docsIntervalId);
+            window.clearInterval(aiProfilesIntervalId);
+            window.clearInterval(assetsIntervalId);
+            window.clearInterval(documentReviewSessionsIntervalId);
+            window.clearInterval(annotatedAttachmentSessionsIntervalId);
+        };
     }, [
         cloudAuthConfigured,
         runtimeMode,
         workspaceCloudSyncEnabled,
-        refreshWorkspaceSyncDocumentsSnapshot
+        authSessionResolved,
+        isAuthenticated,
+        currentWorkspaceId,
+        refreshWorkspaceSyncMarkdownDocumentsSnapshot,
+        refreshWorkspaceSyncAiProfilesSnapshot,
+        refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
+        refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot,
+        workspaceDocumentsRefreshIntervalMs
     ]);
-    // Push on signature change
+    // When task attachments change (e.g., after the MCP save_task_attachment tool writes a
+    // file and the React polling detects the updated task), refresh the asset snapshot
+    // immediately so the new binary is included in the next push payload. This closes the
+    // gap where the MCP path cannot dispatch the browser-only context-assets-mutated event.
     useEffect(() => {
         if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
             return;
+        if (!authSessionResolved || !isAuthenticated)
+            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]);
+    useEffect(() => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved)
+            return;
+        if (workspaceSyncPhase === 'attach-cloud')
+            return;
+        if (!workspaceSyncReferenceSnapshotsReady)
+            return;
         const signature = buildWorkspaceSyncSignature();
+        if (shouldSuppressAttachBootstrapPush(signature))
+            return;
         if (!signature || signature === workspaceLastPushedSignatureRef.current)
             return;
-        if (workspacePushInFlightRef.current) {
+        const pendingPayload = buildWorkspaceSyncPayload();
+        setWorkspaceSyncPendingChanges(pendingPayload.changes.length);
+        if (workspacePushInFlightRef.current || workspacePullInFlightRef.current) {
             workspacePendingSignatureRef.current = signature;
             return;
         }
@@ -1227,66 +2114,54 @@ export function useSyncOrchestrator(input) {
         cloudAuthConfigured,
         runtimeMode,
         workspaceCloudSyncEnabled,
+        authSessionResolved,
+        workspaceSyncPhase,
+        workspaceSyncReferenceSnapshotsReady,
         buildWorkspaceSyncSignature,
-        workspaceSyncDocumentsFingerprint,
-        pushWorkspaceChangesToCloud
+        shouldSuppressAttachBootstrapPush,
+        buildWorkspaceSyncPayload,
+        workspaceSyncAiProfilesFingerprint,
+        workspaceSyncMarkdownDocumentsFingerprint,
+        workspaceSyncAssetsFingerprint,
+        workspaceSyncDocumentReviewSessionsFingerprint,
+        workspaceSyncAnnotatedAttachmentSessionsFingerprint,
+        pushWorkspaceChangesToCloud,
+        workspacePushInFlightRef,
+        workspacePullInFlightRef
     ]);
-    // Clear sync state when disabled
     useEffect(() => {
         if (cloudAuthConfigured && runtimeMode === 'local' && workspaceCloudSyncEnabled)
             return;
         clearWorkspaceRetry();
-        setWorkspaceSyncReady(false);
-        setWorkspaceCloudHydrated(false);
+        setWorkspaceSyncBusy(false);
     }, [
         cloudAuthConfigured,
         runtimeMode,
         workspaceCloudSyncEnabled,
         clearWorkspaceRetry
     ]);
-    // Pull interval
     useEffect(() => {
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved)
+            return;
+        if (workspaceSyncPhase === 'provision-local')
             return;
-        if (isWorkspacePullRetryPending())
+        if (isWorkspaceRetryPending())
             return;
         void pullWorkspaceChangesFromCloud();
         const intervalId = window.setInterval(() => {
             void pullWorkspaceChangesFromCloud();
-        }, 8000);
+        }, workspacePullIntervalMs);
         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
+        authSessionResolved,
+        workspaceSyncPhase,
+        isWorkspaceRetryPending,
+        pullWorkspaceChangesFromCloud,
+        workspacePullIntervalMs
     ]);
-    // User global settings: initial sync on auth
     useEffect(() => {
         if (runtimeMode !== 'local' || !isAuthenticated)
             return;
@@ -1294,7 +2169,6 @@ export function useSyncOrchestrator(input) {
             return;
         void syncUserGlobalSettings({ preferCloudOnFirstSync: true });
     }, [runtimeMode, isAuthenticated, authUserId, syncUserGlobalSettings]);
-    // User global settings: push on settings change
     useEffect(() => {
         if (runtimeMode !== 'local' || !isAuthenticated)
             return;
@@ -1313,7 +2187,6 @@ export function useSyncOrchestrator(input) {
         if (signature === lastUserGlobalSyncSignatureRef.current)
             return;
         lastUserGlobalSyncSignatureRef.current = signature;
-        setUserGlobalSyncPendingChanges(1);
         setLocalUserSyncUpdatedAt(authUserId, new Date().toISOString());
         const timeoutId = window.setTimeout(() => {
             void syncUserGlobalSettings({ preferCloudOnFirstSync: false });
@@ -1327,61 +2200,77 @@ export function useSyncOrchestrator(input) {
         setLocalUserSyncUpdatedAt,
         syncUserGlobalSettings
     ]);
-    // -----------------------------------------------------------------------
-    // Return
-    // -----------------------------------------------------------------------
+    // On first workspace activation, call the server-side startup repair endpoint once.
+    // This re-registers DB records for asset/document files that exist on disk but have
+    // missing or stale-tombstoned metadata — a common result of a crash between file write
+    // and DB upsert. The repair only adds missing records; it never deletes files.
+    useEffect(() => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        if (!authSessionResolved || !isAuthenticated)
+            return;
+        if (workspaceSyncPhase === 'provision-local' || workspaceSyncPhase === 'attach-cloud')
+            return;
+        if (workspaceStartupRepairRanRef.current)
+            return;
+        workspaceStartupRepairRanRef.current = true;
+        fetch('/api/taskforce/sync/workspace/repair-startup', {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ workspaceId: currentWorkspaceId })
+        }).then(async (res) => {
+            if (!res.ok)
+                return;
+            const data = await res.json().catch(() => ({}));
+            if (data?.applied > 0) {
+                logSyncDebug('startup_repair_applied', {
+                    workspaceId: currentWorkspaceId,
+                    applied: data.applied,
+                    skipped: data.skipped,
+                    failed: data.failed
+                });
+                // Refresh snapshots so newly recovered assets are included in the next push
+                void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+                void refreshWorkspaceSyncAiProfilesSnapshot();
+                void refreshWorkspaceSyncAssetsSnapshot();
+                void refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
+            }
+        }).catch(() => { });
+    }, [
+        cloudAuthConfigured,
+        runtimeMode,
+        workspaceCloudSyncEnabled,
+        authSessionResolved,
+        isAuthenticated,
+        workspaceSyncPhase,
+        currentWorkspaceId,
+        refreshWorkspaceSyncMarkdownDocumentsSnapshot,
+        refreshWorkspaceSyncAiProfilesSnapshot,
+        refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncDocumentReviewSessionsSnapshot
+    ]);
+    // === SECTION: Return value ===
     return {
-        // State
         userGlobalSyncStatus,
         setUserGlobalSyncStatus,
-        userGlobalLastSyncedAt,
-        setUserGlobalLastSyncedAt,
-        userGlobalSyncPendingChanges,
-        setUserGlobalSyncPendingChanges,
         userGlobalSyncError,
         setUserGlobalSyncError,
         workspaceLastPullAt,
-        setWorkspaceLastPullAt,
         workspaceLastPushAt,
-        setWorkspaceLastPushAt,
         workspaceLastErrorAt,
-        setWorkspaceLastErrorAt,
         workspaceLastErrorMessage,
-        setWorkspaceLastErrorMessage,
-        workspaceLastWarningMessage,
-        setWorkspaceLastWarningMessage,
+        workspaceLastSuccessfulSyncAt,
         workspaceCloudSyncEnabled,
-        realtimeConnectionState,
-        realtimeTelemetry,
-        setWorkspaceCloudSyncEnabled,
-        workspaceSyncSourceOfTruth,
-        setWorkspaceSyncSourceOfTruth,
-        workspaceSyncOnboardingCompleted,
-        setWorkspaceSyncOnboardingCompleted,
-        workspaceSyncReady,
-        setWorkspaceSyncReady,
-        workspaceCloudHydrated,
-        setWorkspaceCloudHydrated,
-        workspaceSyncDocuments,
-        setWorkspaceSyncDocuments,
-        workspaceSyncDocumentsFingerprint,
-        setWorkspaceSyncDocumentsFingerprint,
-        // Refs
+        workspaceSyncPhase,
+        workspaceSyncStatus,
+        workspaceSyncSummary,
+        workspaceSyncRecommendedAction,
+        workspaceSyncBusy,
+        workspaceSyncPendingChanges,
         syncInFlightRef,
-        // From useWorkspaceSyncController
         workspaceRetryAt,
-        isWorkspacePullRetryPending,
-        workspaceBootstrapSyncInProgress,
-        setWorkspaceBootstrapSyncInProgress,
-        workspaceBootstrapSyncPages,
-        setWorkspaceBootstrapSyncPages,
-        workspaceBootstrapSyncAppliedChanges,
-        setWorkspaceBootstrapSyncAppliedChanges,
-        workspaceSyncFailureCount,
-        workspaceSyncRetryScheduledCount,
-        workspaceSyncAuthFailureCount,
-        workspaceSyncLastFailureSource,
-        workspaceSyncLastFailureStatusCode,
+        isWorkspaceRetryPending,
         workspacePushInFlightRef,
         workspacePullInFlightRef,
         workspaceLastPushedSignatureRef,
@@ -1389,39 +2278,18 @@ export function useSyncOrchestrator(input) {
         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
+        resetWorkspaceSyncCursorAndPull,
+        getWorkspaceSyncDiagnostics
     };
 }