@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/hooks/useSyncOrchestrator.js

@@ -26,57 +26,19 @@ import { useWorkspaceSyncController } from './useWorkspaceSyncController';
 import { normalizeTaskforceTheme } from '../utils/theme';
 import { useRealtimeSync } from './useRealtimeSync';
 import { TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT } from '../utils/contextAssetEvents';
+import { TASKFORCE_AI_PROFILES_MUTATED_EVENT } from '../utils/aiProfileEvents';
 import { setLocale as setAppLocale } from '../localization';
 import { normalizeTaskFromApi } from '../utils/taskNormalization.js';
+import { normalizeSyncEventDetails } from '../utils/syncEventDetails';
 import { createSyncAuthCoordinator } from './sync/auth';
 import { createBootstrapTimeoutMonitor, syncBootstrapPhaseTracking } from './sync/bootstrap';
-import { buildTaxonomyStateFingerprint, flattenDocumentReviewComments, flattenTaskEvents, isValidWorkspaceKey, logSyncDebug, normalizeWorkspaceSyncAiProfileSnapshotEntry, readPersistedSyncWatermarks, readUserGlobalSyncMeta, WORKSPACE_CONCURRENT_WINDOW_MESSAGE, WORKSPACE_FULL_RECONCILE_INTERVAL_MS, writeUserGlobalSyncMeta } from './sync/orchestratorShared';
+import { resolvePullSyncReadiness, resolvePushSyncReadiness, resolveRetrySyncReadiness } from './sync/controlPlane';
+import { resolveWorkspaceAutomaticPullPolicy, resolveWorkspaceSyncPresentation, shouldRunWorkspaceStartupRepair, shouldScheduleWorkspaceReactivePush, shouldStartWorkspacePeriodicFullReconcile, shouldStartWorkspacePushWatchdog, } from './sync/lifecyclePolicy';
+import { buildPersistedSyncWatermarksSnapshot, buildTaxonomyStateFingerprint, flattenDocumentReviewComments, flattenTaskEvents, isValidWorkspaceKey, logSyncDebug, normalizeWorkspaceSyncAiProfileSnapshotEntry, parsePersistedSyncWatermarksSnapshot, readPersistedSyncWatermarks, readUserGlobalSyncMeta, savePersistedSyncWatermarks, WORKSPACE_CONCURRENT_WINDOW_MESSAGE, WORKSPACE_FULL_RECONCILE_INTERVAL_MS, writeUserGlobalSyncMeta } from './sync/orchestratorShared';
 import { createRealtimeSyncBridge } from './sync/realtime';
 import { createSyncRecoveryCoordinator } from './sync/recovery';
 import { createWorkspaceTransferCoordinator } from './sync/transfers';
-// === SECTION: Pure utility functions ===
-function 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.';
-}
+import { aiProfileSyncResourceAdapter, taskSyncResourceAdapter } from '../sync/syncResourceAdapters.js';
 const EMPTY_WORKSPACE_SYNC_REFERENCE_SNAPSHOT_STATUS = {
     documents: false,
     aiProfiles: false,
@@ -109,6 +71,7 @@ export function useSyncOrchestrator(input) {
     const workspaceInitiativesRef = useRef(initiatives || []);
     const workspaceWorkstreamsRef = useRef(workstreams || []);
     const workspaceSyncMarkdownDocumentsRef = useRef([]);
+    const workspaceSyncKnownDocumentPathsRef = useRef(new Set());
     const [workspaceSyncAiProfiles, setWorkspaceSyncAiProfiles] = useState([]);
     const [workspaceSyncAiProfilesFingerprint, setWorkspaceSyncAiProfilesFingerprint] = useState('');
     const [workspaceSyncAiProfilesLastFetchAt, setWorkspaceSyncAiProfilesLastFetchAt] = useState(null);
@@ -119,6 +82,7 @@ export function useSyncOrchestrator(input) {
     const [workspaceSyncAssets, setWorkspaceSyncAssets] = useState([]);
     const [workspaceSyncAssetsFingerprint, setWorkspaceSyncAssetsFingerprint] = useState('');
     const workspaceSyncAssetsRef = useRef([]);
+    const workspaceSyncKnownAssetPathsRef = useRef(new Set());
     const [workspaceSyncDocumentReviewSessions, setWorkspaceSyncDocumentReviewSessions] = useState([]);
     const [workspaceSyncDocumentReviewSessionsFingerprint, setWorkspaceSyncDocumentReviewSessionsFingerprint] = useState('');
     const workspaceSyncDocumentReviewSessionsRef = useRef([]);
@@ -137,6 +101,7 @@ export function useSyncOrchestrator(input) {
     });
     const userSettingsSyncInFlightRef = useRef(false);
     const userSettingsRetryTimeoutRef = useRef(null);
+    const workspaceBaselineResetReasonRef = useRef('missing-baseline');
     const userSettingsRetryAttemptRef = useRef(0);
     const applyingRemoteUserSettingsRef = useRef(false);
     const initialUserSettingsSyncCompletedRef = useRef(new Set());
@@ -150,6 +115,7 @@ export function useSyncOrchestrator(input) {
     const realtimePullDebounceRef = useRef(null);
     const realtimeSuppressedEventIdsRef = useRef(new Set());
     const realtimeSuppressedEventQueueRef = useRef([]);
+    const workspacePendingPushReplayRef = useRef(null);
     const retryWorkspaceSyncRef = useRef(() => Promise.resolve(false));
     const syncUserGlobalSettingsRef = useRef(async () => { });
     const bootstrapPhaseStartedAtRef = useRef(null);
@@ -178,73 +144,6 @@ export function useSyncOrchestrator(input) {
             void syncUserGlobalSettingsRef.current({ preferCloudOnFirstSync: false });
         }, delayMs);
     }, [clearUserSettingsRetry]);
-    useEffect(() => {
-        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();
-        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();
-        workspaceLastPushedTaskEventWatermarksRef.current = new Map();
-        workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
-        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
-        workspaceLastPushedTaskEventWatermarksRef.current = new Map();
-        workspaceStartupFullReconcileRanRef.current = false;
-        workspaceFullReconcileInFlightRef.current = false;
-        const persisted = readPersistedSyncWatermarks(currentWorkspaceId, taxonomyStateFingerprint);
-        if (persisted) {
-            workspaceLastPushedWatermarksRef.current = persisted.taskWatermarks;
-            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;
-            workspaceLastPushedTaskEventWatermarksRef.current = persisted.taskEventWatermarks;
-        }
-    }, [currentWorkspaceId, taxonomyStateFingerprint]);
     const markWorkspaceSyncReferenceSnapshotReady = useCallback((key) => {
         setWorkspaceSyncReferenceSnapshotStatus((current) => (current[key]
             ? current
@@ -254,7 +153,7 @@ export function useSyncOrchestrator(input) {
             }));
     }, []);
     const workspaceSyncReferenceSnapshotsReady = Object.values(workspaceSyncReferenceSnapshotStatus).every(Boolean);
-    const { workspaceRetryAt, isWorkspaceRetryPending, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspaceDeletedTaskWatermarksRef, workspacePullCursorRef, clearWorkspaceRetry, scheduleWorkspaceRetry, persistWorkspaceSyncPatch, applyWorkspaceSyncPatchLocally, loadWorkspaceSyncState, applyWorkspaceSyncStateSnapshot: applyWorkspaceSyncStateSnapshotBase, saveWorkspaceCloudSyncSettings: saveWorkspaceCloudSyncSettingsBase, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease } = useWorkspaceSyncController({
+    const { workspaceRetryAt, isWorkspaceRetryPending, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspaceDeletedTaskWatermarksRef, workspacePullCursorRef, clearWorkspaceRetry, scheduleWorkspaceRetry, persistWorkspaceSyncPatch, applyWorkspaceSyncPatchLocally, readWorkspaceSyncStateSnapshot, loadWorkspaceSyncState, applyWorkspaceSyncStateSnapshot: applyWorkspaceSyncStateSnapshotBase, saveWorkspaceCloudSyncSettings: saveWorkspaceCloudSyncSettingsBase, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease } = useWorkspaceSyncController({
         currentWorkspaceId,
         setWorkspaceCloudSyncEnabled,
         setWorkspaceSyncPhase,
@@ -274,12 +173,14 @@ export function useSyncOrchestrator(input) {
         applyWorkspaceSyncStateSnapshotBase(nextState);
     }, [applyWorkspaceSyncStateSnapshotBase]);
     const workspaceLastPushedWatermarksRef = useRef(new Map());
+    const workspaceLastPushedTaskChangeKeysRef = useRef(new Map());
     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 workspaceLastPushedAiProfileChangeKeysRef = useRef(new Map());
     const workspaceLastPushedDocumentPathsRef = useRef(new Set());
     const workspaceLastPushedDocumentWatermarksRef = useRef(new Map());
     const workspaceLastPushedAssetPathsRef = useRef(new Set());
@@ -291,6 +192,48 @@ export function useSyncOrchestrator(input) {
     const workspaceLastPushedAnnotatedAttachmentSessionIdsRef = useRef(new Set());
     const workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef = useRef(new Map());
     const workspaceLastPushedTaskEventWatermarksRef = useRef(new Map());
+    const hydrateWorkspacePushBaselines = useCallback((persisted) => {
+        if (!persisted)
+            return false;
+        workspaceLastPushedTaskIdsRef.current = new Set(persisted.taskIds);
+        workspaceLastPushedWatermarksRef.current = persisted.taskWatermarks;
+        workspaceLastPushedTaskChangeKeysRef.current = persisted.taskChangeKeys || new Map();
+        workspaceLastPushedInitiativeIdsRef.current = new Set(Array.from(persisted.initiativeWatermarks.keys()));
+        workspaceLastPushedInitiativeWatermarksRef.current = persisted.initiativeWatermarks;
+        workspaceLastPushedWorkstreamIdsRef.current = new Set(Array.from(persisted.workstreamWatermarks.keys()));
+        workspaceLastPushedWorkstreamWatermarksRef.current = persisted.workstreamWatermarks;
+        workspaceLastPushedAiProfileIdsRef.current = new Set(Array.from(persisted.aiProfileWatermarks.keys()));
+        workspaceLastPushedAiProfileWatermarksRef.current = persisted.aiProfileWatermarks;
+        workspaceLastPushedAiProfileChangeKeysRef.current = persisted.aiProfileChangeKeys || new Map();
+        workspaceLastPushedDocumentPathsRef.current = new Set(Array.from(persisted.documentWatermarks.keys()));
+        workspaceLastPushedDocumentWatermarksRef.current = persisted.documentWatermarks;
+        workspaceLastPushedAssetPathsRef.current = new Set(Array.from(persisted.assetWatermarks.keys()));
+        workspaceLastPushedAssetWatermarksRef.current = persisted.assetWatermarks;
+        workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set(Array.from(persisted.documentReviewSessionWatermarks.keys()));
+        workspaceLastPushedDocumentReviewSessionWatermarksRef.current = persisted.documentReviewSessionWatermarks;
+        workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set(Array.from(persisted.documentReviewCommentWatermarks.keys()));
+        workspaceLastPushedDocumentReviewCommentWatermarksRef.current = persisted.documentReviewCommentWatermarks;
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set(Array.from(persisted.annotatedAttachmentSessionWatermarks.keys()));
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = persisted.annotatedAttachmentSessionWatermarks;
+        workspaceLastPushedTaskEventWatermarksRef.current = persisted.taskEventWatermarks;
+        workspaceBaselineResetReasonRef.current = null;
+        return true;
+    }, [workspaceLastPushedTaskIdsRef]);
+    const buildCurrentPersistedWorkspaceSyncWatermarks = useCallback(() => ({
+        taskIds: workspaceLastPushedTaskIdsRef.current,
+        taskWatermarks: workspaceLastPushedWatermarksRef.current,
+        taskChangeKeys: workspaceLastPushedTaskChangeKeysRef.current,
+        initiativeWatermarks: workspaceLastPushedInitiativeWatermarksRef.current,
+        workstreamWatermarks: workspaceLastPushedWorkstreamWatermarksRef.current,
+        aiProfileWatermarks: workspaceLastPushedAiProfileWatermarksRef.current,
+        aiProfileChangeKeys: workspaceLastPushedAiProfileChangeKeysRef.current,
+        documentWatermarks: workspaceLastPushedDocumentWatermarksRef.current,
+        assetWatermarks: workspaceLastPushedAssetWatermarksRef.current,
+        documentReviewSessionWatermarks: workspaceLastPushedDocumentReviewSessionWatermarksRef.current,
+        documentReviewCommentWatermarks: workspaceLastPushedDocumentReviewCommentWatermarksRef.current,
+        annotatedAttachmentSessionWatermarks: workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current,
+        taskEventWatermarks: workspaceLastPushedTaskEventWatermarksRef.current,
+    }), []);
     const workspaceStartupRepairRanRef = useRef(false);
     const workspaceStartupFullReconcileRanRef = useRef(false);
     const workspaceRepairModeRef = useRef(false);
@@ -311,36 +254,22 @@ export function useSyncOrchestrator(input) {
             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), [
+    const workspaceSyncPresentation = useMemo(() => resolveWorkspaceSyncPresentation({
+        enabled: workspaceCloudSyncEnabled,
+        phase: workspaceSyncPhase,
+        busy: workspaceSyncBusy,
+        retryAt: workspaceRetryAt,
+        lastErrorMessage: workspaceLastErrorMessage
+    }), [
         workspaceCloudSyncEnabled,
         workspaceSyncPhase,
         workspaceSyncBusy,
         workspaceRetryAt,
         workspaceLastErrorMessage
     ]);
-    const workspaceSyncRecommendedAction = useMemo(() => recommendSyncAction(workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceRetryAt, workspaceLastErrorMessage), [
-        workspaceCloudSyncEnabled,
-        workspaceSyncPhase,
-        workspaceRetryAt,
-        workspaceLastErrorMessage
-    ]);
+    const workspaceSyncStatus = workspaceSyncPresentation.status;
+    const workspaceSyncSummary = workspaceSyncPresentation.summary;
+    const workspaceSyncRecommendedAction = workspaceSyncPresentation.recommendedAction;
     const getLocalUserSyncUpdatedAt = useCallback((userId) => {
         const key = String(userId || '').trim();
         if (!key)
@@ -531,6 +460,102 @@ export function useSyncOrchestrator(input) {
     const persistWorkspaceSyncPatchSafely = useCallback((patch) => {
         void persistWorkspaceSyncPatchBestEffort(patch).catch(() => { });
     }, [persistWorkspaceSyncPatchBestEffort]);
+    const persistWorkspaceSyncWatermarksSnapshotBestEffort = useCallback(() => {
+        const snapshotData = {
+            ...buildCurrentPersistedWorkspaceSyncWatermarks(),
+            taxonomyStateFingerprint
+        };
+        const persisted = savePersistedSyncWatermarks(currentWorkspaceId, snapshotData);
+        void persistWorkspaceSyncPatchBestEffort({
+            pushBaseline: buildPersistedSyncWatermarksSnapshot(snapshotData)
+        }).catch(() => { });
+        return persisted;
+    }, [
+        buildCurrentPersistedWorkspaceSyncWatermarks,
+        currentWorkspaceId,
+        persistWorkspaceSyncPatchBestEffort,
+        taxonomyStateFingerprint
+    ]);
+    useEffect(() => {
+        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();
+        workspaceLastPushedTaskChangeKeysRef.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();
+        workspaceLastPushedAiProfileChangeKeysRef.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();
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
+        workspaceLastPushedTaskEventWatermarksRef.current = new Map();
+        workspaceStartupFullReconcileRanRef.current = false;
+        workspaceFullReconcileInFlightRef.current = false;
+        const persisted = readPersistedSyncWatermarks(currentWorkspaceId, taxonomyStateFingerprint);
+        if (!hydrateWorkspacePushBaselines(persisted)) {
+            workspaceBaselineResetReasonRef.current = 'missing-baseline';
+        }
+    }, [currentWorkspaceId, hydrateWorkspacePushBaselines, taxonomyStateFingerprint]);
+    useEffect(() => {
+        if (workspaceBaselineResetReasonRef.current !== 'missing-baseline')
+            return;
+        const persistedLocal = readPersistedSyncWatermarks(currentWorkspaceId, taxonomyStateFingerprint);
+        if (hydrateWorkspacePushBaselines(persistedLocal))
+            return;
+        const persistedRemote = parsePersistedSyncWatermarksSnapshot(readWorkspaceSyncStateSnapshot().pushBaseline, taxonomyStateFingerprint);
+        if (!hydrateWorkspacePushBaselines(persistedRemote))
+            return;
+        savePersistedSyncWatermarks(currentWorkspaceId, {
+            ...buildCurrentPersistedWorkspaceSyncWatermarks(),
+            taxonomyStateFingerprint
+        });
+    }, [
+        buildCurrentPersistedWorkspaceSyncWatermarks,
+        currentWorkspaceId,
+        hydrateWorkspacePushBaselines,
+        readWorkspaceSyncStateSnapshot,
+        taxonomyStateFingerprint,
+        workspaceCloudSyncEnabled,
+        workspaceSyncPhase
+    ]);
     const scheduleWorkspaceSyncRetry = useCallback((minDelayMs) => {
         scheduleWorkspaceRetry(() => retryWorkspaceSyncRef.current(), { minDelayMs });
     }, [scheduleWorkspaceRetry]);
@@ -592,13 +617,16 @@ export function useSyncOrchestrator(input) {
         workspaceArchivedTasksRef.current = archivedTasks || [];
     }, [archivedTasks]);
     useEffect(() => {
+        workspaceDeletedTaskIdsRef.current = new Set((deletedTasks || [])
+            .map((entry) => String(entry?.taskId || '').trim())
+            .filter((taskId) => taskId.length > 0));
         workspaceDeletedTaskWatermarksRef.current = new Map((deletedTasks || [])
             .map((entry) => [
             String(entry?.taskId || '').trim(),
             String(entry?.deletedAt || '').trim()
         ])
             .filter(([taskId, deletedAt]) => taskId.length > 0 && Number.isFinite(Date.parse(deletedAt))));
-    }, [deletedTasks, workspaceDeletedTaskWatermarksRef]);
+    }, [deletedTasks, workspaceDeletedTaskIdsRef, workspaceDeletedTaskWatermarksRef]);
     useEffect(() => {
         workspaceInitiativesRef.current = initiatives || [];
     }, [initiatives]);
@@ -615,7 +643,7 @@ export function useSyncOrchestrator(input) {
         return buildWorkspaceSyncPayloadModel({
             tasks: workspaceTasksRef.current,
             archivedTasks: workspaceArchivedTasksRef.current,
-            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current),
+            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current, workspaceInitiativesRef.current, workspaceWorkstreamsRef.current),
             lastPushedTaskIds: workspaceLastPushedTaskIdsRef.current,
             pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
             pendingDeletedTaskWatermarks: workspaceDeletedTaskWatermarksRef.current,
@@ -630,8 +658,11 @@ export function useSyncOrchestrator(input) {
             aiProfiles: workspaceSyncAiProfilesRef.current,
             lastPushedAiProfileIds: forceAllAiProfiles ? new Set() : workspaceLastPushedAiProfileIdsRef.current,
             lastPushedAiProfileWatermarks: forceAllAiProfiles ? new Map() : workspaceLastPushedAiProfileWatermarksRef.current,
+            lastPushedAiProfileChangeKeys: forceAllAiProfiles ? new Map() : workspaceLastPushedAiProfileChangeKeysRef.current,
             documents: workspaceSyncMarkdownDocumentsRef.current,
             assets: workspaceSyncAssetsRef.current,
+            currentDocumentPaths: workspaceSyncKnownDocumentPathsRef.current,
+            currentAssetPaths: workspaceSyncKnownAssetPathsRef.current,
             documentReviewSessions: workspaceSyncDocumentReviewSessionsRef.current,
             documentReviewComments: workspaceSyncDocumentReviewCommentsRef.current,
             annotatedAttachmentSessions: workspaceSyncAnnotatedAttachmentSessionsRef.current,
@@ -646,25 +677,42 @@ export function useSyncOrchestrator(input) {
             lastPushedAnnotatedAttachmentSessionIds: workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current,
             lastPushedAnnotatedAttachmentSessionWatermarks: workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current,
             lastPushedTaskEventWatermarks: workspaceLastPushedTaskEventWatermarksRef.current,
-            lastPushedWatermarks: workspaceLastPushedWatermarksRef.current
+            baselineResetReason: workspaceBaselineResetReasonRef.current,
+            lastPushedWatermarks: workspaceLastPushedWatermarksRef.current,
+            lastPushedTaskChangeKeys: workspaceLastPushedTaskChangeKeysRef.current
         });
     }, [taxonomies, taxonomyState]);
     const reportSyncEvent = useCallback((workspaceId, event) => {
         if (runtimeMode !== 'local')
             return;
-        fetch('/api/taskforce/sync/events', {
-            method: 'POST',
-            credentials: 'include',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ ...event, workspaceId })
-        }).catch((error) => {
+        try {
+            const normalizedEvent = {
+                ...event,
+                workspaceId,
+                details: normalizeSyncEventDetails(event.details)
+            };
+            void fetch('/api/taskforce/sync/events', {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(normalizedEvent)
+            }).catch((error) => {
+                logSyncDebug('sync_event_post_failed', {
+                    workspaceId,
+                    eventType: event.eventType,
+                    status: event.status,
+                    error: String(error?.message || error || '')
+                });
+            });
+        }
+        catch (error) {
             logSyncDebug('sync_event_post_failed', {
                 workspaceId,
                 eventType: event.eventType,
                 status: event.status,
                 error: String(error?.message || error || '')
             });
-        });
+        }
     }, [runtimeMode]);
     const buildWorkspaceSyncSignature = useCallback(() => {
         // Read documents and assets from refs for the same stale-closure reason as
@@ -673,7 +721,7 @@ export function useSyncOrchestrator(input) {
             workspaceId: currentWorkspaceId,
             tasks: workspaceTasksRef.current,
             archivedTasks: workspaceArchivedTasksRef.current,
-            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current),
+            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current, workspaceInitiativesRef.current, workspaceWorkstreamsRef.current),
             pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
             initiatives: workspaceInitiativesRef.current,
             workstreams: workspaceWorkstreamsRef.current,
@@ -720,17 +768,25 @@ export function useSyncOrchestrator(input) {
             isArchived: Boolean(workstream.isArchived)
         }))
             .sort((left, right) => left.id.localeCompare(right.id)),
-        taskEvents: flattenTaskEvents(tasks || [], archivedTasks || [])
+        taskEvents: flattenTaskEvents(tasks || [], archivedTasks || [], initiatives || [], workstreams || [])
             .map((event) => ({
             id: String(event.id || '').trim(),
-            taskId: String(event.taskId || '').trim(),
+            entityType: String(event.entityType || 'task').trim(),
+            entityId: String(event.entityId || event.taskId || '').trim(),
             createdAt: String(event.createdAt || '').trim(),
             action: String(event.action || '').trim(),
         }))
             .sort((left, right) => left.id.localeCompare(right.id)),
+        deletedTasks: (deletedTasks || [])
+            .map((entry) => ({
+            taskId: String(entry?.taskId || '').trim(),
+            deletedAt: String(entry?.deletedAt || '').trim()
+        }))
+            .filter((entry) => entry.taskId.length > 0 && Number.isFinite(Date.parse(entry.deletedAt)))
+            .sort((left, right) => left.taskId.localeCompare(right.taskId)),
         taxonomies: Array.isArray(taxonomies) ? taxonomies : [],
         taxonomyState: taxonomyState && typeof taxonomyState === 'object' ? taxonomyState : null
-    }), [tasks, archivedTasks, initiatives, workstreams, taxonomies, taxonomyState]);
+    }), [tasks, archivedTasks, deletedTasks, initiatives, workstreams, taxonomies, taxonomyState]);
     // Fingerprint of per-task attachment counts — changes when the MCP tool saves a new
     // attachment and the React app polls the updated task. Used to trigger an immediate
     // asset snapshot refresh without requiring a cross-process DOM event.
@@ -797,6 +853,11 @@ export function useSyncOrchestrator(input) {
                 }))
                     .filter((entry) => entry.path.length > 0)
                 : [];
+            const knownDocumentPaths = new Set(Array.isArray(data?.knownPaths)
+                ? data.knownPaths
+                    .map((entry) => String(entry || '').trim())
+                    .filter((entry) => entry.length > 0)
+                : docs.map((entry) => entry.path));
             const fingerprint = typeof data?.fingerprint === 'string'
                 ? data.fingerprint
                 : JSON.stringify(docs.map((entry) => `${entry.path}:${entry.updatedAt}:${entry.content.length}`).sort());
@@ -804,6 +865,7 @@ export function useSyncOrchestrator(input) {
                 return;
             workspaceSyncMarkdownDocumentsFingerprintRef.current = fingerprint;
             workspaceSyncMarkdownDocumentsRef.current = docs;
+            workspaceSyncKnownDocumentPathsRef.current = knownDocumentPaths;
             setWorkspaceSyncMarkdownDocuments(docs);
             setWorkspaceSyncMarkdownDocumentsFingerprint(fingerprint);
         }
@@ -853,7 +915,16 @@ export function useSyncOrchestrator(input) {
             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());
+                : JSON.stringify(aiProfiles.map((entry) => [
+                    entry.id,
+                    entry.updatedAt,
+                    entry.name,
+                    entry.username,
+                    entry.archivedAt ?? '',
+                    entry.archivedReason ?? '',
+                    entry.mergedIntoProfileId ?? '',
+                    entry.rosterStateUpdatedAt ?? ''
+                ].join(':')).sort());
             if (fingerprint === workspaceSyncAiProfilesFingerprintRef.current)
                 return;
             workspaceSyncAiProfilesFingerprintRef.current = fingerprint;
@@ -910,6 +981,11 @@ export function useSyncOrchestrator(input) {
                 }))
                     .filter((entry) => entry.path.length > 0 && entry.contentBase64.length > 0)
                 : [];
+            const knownAssetPaths = new Set(Array.isArray(data?.knownPaths)
+                ? data.knownPaths
+                    .map((entry) => String(entry || '').trim())
+                    .filter((entry) => entry.length > 0)
+                : assets.map((entry) => entry.path));
             const fingerprint = typeof data?.fingerprint === 'string'
                 ? data.fingerprint
                 : JSON.stringify(assets.map((entry) => `${entry.path}:${entry.updatedAt}:${entry.contentBase64.length}`).sort());
@@ -917,6 +993,7 @@ export function useSyncOrchestrator(input) {
                 return;
             workspaceSyncAssetsFingerprintRef.current = fingerprint;
             workspaceSyncAssetsRef.current = assets;
+            workspaceSyncKnownAssetPathsRef.current = knownAssetPaths;
             setWorkspaceSyncAssets(assets);
             setWorkspaceSyncAssetsFingerprint(fingerprint);
         }
@@ -930,6 +1007,37 @@ export function useSyncOrchestrator(input) {
             markWorkspaceSyncReferenceSnapshotReady('assets');
         }
     }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
+    const refreshWorkspaceSyncPlanningEntitiesSnapshot = useCallback(async () => {
+        if (runtimeMode !== 'local')
+            return;
+        if (!isValidWorkspaceKey(currentWorkspaceId))
+            return;
+        if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated))
+            return;
+        try {
+            const res = await fetch(`/api/taskforce/planning/bootstrap?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
+                method: 'GET',
+                credentials: 'include'
+            });
+            if (!res.ok)
+                return;
+            const data = await res.json().catch(() => ({}));
+            const nextInitiatives = Array.isArray(data?.initiatives)
+                ? data.initiatives.filter((entry) => (Boolean(entry && typeof entry === 'object' && typeof entry.id === 'string')))
+                : [];
+            const nextWorkstreams = Array.isArray(data?.workstreams)
+                ? data.workstreams.filter((entry) => (Boolean(entry && typeof entry === 'object' && typeof entry.id === 'string')))
+                : [];
+            workspaceInitiativesRef.current = nextInitiatives;
+            workspaceWorkstreamsRef.current = nextWorkstreams;
+        }
+        catch (error) {
+            logSyncDebug('planning_snapshot_refresh_failed', {
+                workspaceId: currentWorkspaceId,
+                error: String(error?.message || error || '')
+            });
+        }
+    }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated]);
     const refreshWorkspaceSyncDocumentReviewSessionsSnapshot = useCallback(async () => {
         if (runtimeMode !== 'local')
             return;
@@ -1059,6 +1167,38 @@ export function useSyncOrchestrator(input) {
         }
     }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
     const seedWorkspaceSnapshotPushBaseline = useCallback(() => {
+        workspaceLastPushedTaskIdsRef.current = new Set([...workspaceTasksRef.current, ...workspaceArchivedTasksRef.current]
+            .map((entry) => String(entry?.id || '').trim())
+            .filter((id) => id.length > 0));
+        workspaceLastPushedWatermarksRef.current = new Map([...workspaceTasksRef.current, ...workspaceArchivedTasksRef.current]
+            .map((entry) => [String(entry?.id || '').trim(), taskSyncResourceAdapter.getWatermark(entry)])
+            .filter(([id]) => id.length > 0));
+        workspaceLastPushedTaskChangeKeysRef.current = new Map([
+            ...workspaceTasksRef.current.map((entry) => [String(entry?.id || '').trim(), taskSyncResourceAdapter.getChangeKey({ ...entry, isArchived: false })]),
+            ...workspaceArchivedTasksRef.current.map((entry) => [String(entry?.id || '').trim(), taskSyncResourceAdapter.getChangeKey({ ...entry, isArchived: true })])
+        ]
+            .filter(([id]) => id.length > 0));
+        workspaceLastPushedInitiativeIdsRef.current = new Set(workspaceInitiativesRef.current
+            .map((entry) => String(entry?.id || '').trim())
+            .filter((id) => id.length > 0));
+        workspaceLastPushedInitiativeWatermarksRef.current = new Map(workspaceInitiativesRef.current
+            .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
+            .filter(([id]) => id.length > 0));
+        workspaceLastPushedWorkstreamIdsRef.current = new Set(workspaceWorkstreamsRef.current
+            .map((entry) => String(entry?.id || '').trim())
+            .filter((id) => id.length > 0));
+        workspaceLastPushedWorkstreamWatermarksRef.current = new Map(workspaceWorkstreamsRef.current
+            .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
+            .filter(([id]) => id.length > 0));
+        workspaceLastPushedAiProfileIdsRef.current = new Set(workspaceSyncAiProfilesRef.current
+            .map((entry) => String(entry?.id || '').trim())
+            .filter((id) => id.length > 0));
+        workspaceLastPushedAiProfileWatermarksRef.current = new Map(workspaceSyncAiProfilesRef.current
+            .map((entry) => [String(entry?.id || '').trim(), aiProfileSyncResourceAdapter.getWatermark(entry)])
+            .filter(([id]) => id.length > 0));
+        workspaceLastPushedAiProfileChangeKeysRef.current = new Map(workspaceSyncAiProfilesRef.current
+            .map((entry) => [String(entry?.id || '').trim(), aiProfileSyncResourceAdapter.getChangeKey(entry)])
+            .filter(([id]) => id.length > 0));
         workspaceLastPushedDocumentPathsRef.current = new Set(workspaceSyncMarkdownDocumentsRef.current
             .map((entry) => String(entry?.path || '').trim())
             .filter((path) => path.length > 0));
@@ -1089,10 +1229,12 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map(workspaceSyncAnnotatedAttachmentSessionsRef.current
             .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
             .filter(([id]) => id.length > 0));
-        workspaceLastPushedTaskEventWatermarksRef.current = new Map(flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current)
+        workspaceLastPushedTaskEventWatermarksRef.current = new Map(flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current, workspaceInitiativesRef.current, workspaceWorkstreamsRef.current)
             .map((entry) => [String(entry?.id || '').trim(), String(entry?.createdAt || '').trim()])
             .filter(([id]) => id.length > 0));
-    }, []);
+        const persisted = persistWorkspaceSyncWatermarksSnapshotBestEffort();
+        workspaceBaselineResetReasonRef.current = persisted ? null : 'storage-write-failed';
+    }, [persistWorkspaceSyncWatermarksSnapshotBestEffort]);
     const refreshLocalWorkspaceTaskCollections = useCallback(async () => {
         const [tasksRes, archiveRes] = await Promise.all([
             fetch('/api/taskforce/tasks', {
@@ -1163,7 +1305,6 @@ export function useSyncOrchestrator(input) {
         workspaceCloudSyncEnabled,
         currentWorkspaceId,
         workspaceSyncPhase,
-        taxonomyStateFingerprint,
         isAuthenticated,
         checkAuthSession,
         resolveCloudAuthUrl,
@@ -1176,6 +1317,7 @@ export function useSyncOrchestrator(input) {
         scheduleWorkspaceSyncRetry,
         persistWorkspaceSyncPatchSafely,
         persistWorkspaceSyncPatchBestEffort,
+        persistWorkspaceSyncWatermarksSnapshotBestEffort,
         reportSyncEvent,
         acquireWorkspaceSyncLease,
         releaseWorkspaceSyncLease,
@@ -1183,6 +1325,7 @@ export function useSyncOrchestrator(input) {
         refreshWorkspaceSyncMarkdownDocumentsSnapshot,
         refreshWorkspaceSyncAiProfilesSnapshot,
         refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncPlanningEntitiesSnapshot,
         refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
         refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot,
         refreshLocalWorkspaceTaskCollections,
@@ -1195,6 +1338,7 @@ export function useSyncOrchestrator(input) {
         workspaceForceFullAiProfilePushRef,
         workspacePushInFlightRef,
         workspacePullInFlightRef,
+        workspacePendingPushReplayRef,
         workspaceLastPushedSignatureRef,
         workspacePendingSignatureRef,
         workspaceLastPushedTaskIdsRef,
@@ -1202,12 +1346,14 @@ export function useSyncOrchestrator(input) {
         workspaceDeletedTaskWatermarksRef,
         workspacePullCursorRef,
         workspaceLastPushedWatermarksRef,
+        workspaceLastPushedTaskChangeKeysRef,
         workspaceLastPushedInitiativeIdsRef,
         workspaceLastPushedInitiativeWatermarksRef,
         workspaceLastPushedWorkstreamIdsRef,
         workspaceLastPushedWorkstreamWatermarksRef,
         workspaceLastPushedAiProfileIdsRef,
         workspaceLastPushedAiProfileWatermarksRef,
+        workspaceLastPushedAiProfileChangeKeysRef,
         workspaceLastPushedDocumentPathsRef,
         workspaceLastPushedDocumentWatermarksRef,
         workspaceLastPushedAssetPathsRef,
@@ -1219,6 +1365,7 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedAnnotatedAttachmentSessionIdsRef,
         workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef,
         workspaceLastPushedTaskEventWatermarksRef,
+        workspaceBaselineResetReasonRef,
         workspaceCaptureAttachBootstrapBaselineRef,
         workspaceStartupFullReconcileRanRef,
         workspaceFullReconcileInFlightRef,
@@ -1252,6 +1399,7 @@ export function useSyncOrchestrator(input) {
         scheduleWorkspaceSyncRetry,
         persistWorkspaceSyncPatchSafely,
         persistWorkspaceSyncPatchBestEffort,
+        persistWorkspaceSyncWatermarksSnapshotBestEffort,
         reportSyncEvent,
         acquireWorkspaceSyncLease,
         releaseWorkspaceSyncLease,
@@ -1259,6 +1407,7 @@ export function useSyncOrchestrator(input) {
         refreshWorkspaceSyncMarkdownDocumentsSnapshot,
         refreshWorkspaceSyncAiProfilesSnapshot,
         refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncPlanningEntitiesSnapshot,
         refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
         refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot,
         refreshLocalWorkspaceTaskCollections,
@@ -1339,7 +1488,6 @@ export function useSyncOrchestrator(input) {
     }, [syncUserGlobalSettings]);
     const recoveryCoordinator = useMemo(() => createSyncRecoveryCoordinator({
         currentWorkspaceId,
-        taxonomyStateFingerprint,
         workspaceCloudSyncEnabled,
         workspaceSyncPhase,
         workspaceLastPullAt,
@@ -1355,12 +1503,14 @@ export function useSyncOrchestrator(input) {
         workspacePendingSignatureRef,
         workspaceLastPushedSignatureRef,
         workspaceLastPushedWatermarksRef,
+        workspaceLastPushedTaskChangeKeysRef,
         workspaceLastPushedInitiativeIdsRef,
         workspaceLastPushedInitiativeWatermarksRef,
         workspaceLastPushedWorkstreamIdsRef,
         workspaceLastPushedWorkstreamWatermarksRef,
         workspaceLastPushedAiProfileIdsRef,
         workspaceLastPushedAiProfileWatermarksRef,
+        workspaceLastPushedAiProfileChangeKeysRef,
         workspaceLastPushedDocumentPathsRef,
         workspaceLastPushedDocumentWatermarksRef,
         workspaceLastPushedAssetPathsRef,
@@ -1372,6 +1522,7 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedAnnotatedAttachmentSessionIdsRef,
         workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef,
         workspaceLastPushedTaskEventWatermarksRef,
+        workspaceBaselineResetReasonRef,
         bootstrapPhaseStartedAtRef,
         bootstrapLastProgressAtRef,
         acquireWorkspaceSyncLease,
@@ -1380,7 +1531,9 @@ export function useSyncOrchestrator(input) {
         clearWorkspaceRetry,
         clearWorkspaceIssue,
         reportWorkspaceWindowContention,
+        reportSyncEvent,
         persistWorkspaceSyncPatch,
+        persistWorkspaceSyncWatermarksSnapshotBestEffort,
         buildWorkspaceSyncSignature,
         pullWorkspaceChangesFromCloud,
         pushWorkspaceChangesToCloud,
@@ -1400,7 +1553,9 @@ export function useSyncOrchestrator(input) {
         clearWorkspaceRetry,
         clearWorkspaceIssue,
         reportWorkspaceWindowContention,
+        reportSyncEvent,
         persistWorkspaceSyncPatch,
+        persistWorkspaceSyncWatermarksSnapshotBestEffort,
         buildWorkspaceSyncSignature,
         pullWorkspaceChangesFromCloud,
         pushWorkspaceChangesToCloud,
@@ -1412,6 +1567,39 @@ export function useSyncOrchestrator(input) {
     const { retryWorkspaceCloudSync, resetWorkspaceSyncCursorAndPull } = recoveryCoordinator;
     // === SECTION: Diagnostics & reactive effects ===
     const getWorkspaceSyncDiagnostics = useCallback(() => {
+        const pushReadiness = resolvePushSyncReadiness({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            currentWorkspaceId,
+            workspaceSyncPhase,
+            isAuthenticated,
+            repairModeActive: workspaceRepairModeRef.current === true,
+            repairModeBypass: false,
+            pushInFlight: workspacePushInFlightRef.current,
+            pullInFlight: workspacePullInFlightRef.current
+        });
+        const retryPending = isWorkspaceRetryPending();
+        const pullReadiness = resolvePullSyncReadiness({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            currentWorkspaceId,
+            workspaceSyncPhase,
+            isAuthenticated,
+            repairModeActive: workspaceRepairModeRef.current === true,
+            repairModeBypass: false,
+            retryPending,
+            pushInFlight: workspacePushInFlightRef.current,
+            pullInFlight: workspacePullInFlightRef.current
+        });
+        const retryReadiness = resolveRetrySyncReadiness({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            currentWorkspaceId,
+            isAuthenticated
+        });
         return {
             workspaceId: currentWorkspaceId,
             enabled: workspaceCloudSyncEnabled,
@@ -1425,6 +1613,13 @@ export function useSyncOrchestrator(input) {
             pendingChanges: workspaceSyncPendingChanges,
             lastErrorMessage: workspaceLastErrorMessage,
             recommendedAction: workspaceSyncRecommendedAction,
+            pushBlockedReason: pushReadiness.allowed ? null : pushReadiness.reason,
+            pullBlockedReason: pullReadiness.allowed ? null : pullReadiness.reason,
+            retryBlockedReason: retryReadiness.allowed ? null : retryReadiness.reason,
+            repairActive: workspaceRepairModeRef.current === true,
+            pushInFlight: workspacePushInFlightRef.current === true,
+            pullInFlight: workspacePullInFlightRef.current === true,
+            retryPending,
             documentSnapshotCount: workspaceSyncMarkdownDocuments.length,
             aiProfileSnapshotCount: workspaceSyncAiProfiles.length,
             aiProfileSnapshotRawCount: workspaceSyncAiProfilesRawCount,
@@ -1441,9 +1636,12 @@ export function useSyncOrchestrator(input) {
             forceFullAiProfilePushQueued: workspaceForceFullAiProfilePushRef.current === true
         };
     }, [
+        cloudAuthConfigured,
         currentWorkspaceId,
+        runtimeMode,
         workspaceCloudSyncEnabled,
         workspaceSyncPhase,
+        isAuthenticated,
         workspaceSyncStatus,
         workspaceSyncSummary,
         workspaceLastSuccessfulSyncAt,
@@ -1463,7 +1661,8 @@ export function useSyncOrchestrator(input) {
         workspaceSyncDocumentReviewSessions.length,
         workspaceSyncDocumentReviewSessionsFingerprint,
         workspaceSyncAnnotatedAttachmentSessions.length,
-        workspaceSyncAnnotatedAttachmentSessionsFingerprint
+        workspaceSyncAnnotatedAttachmentSessionsFingerprint,
+        isWorkspaceRetryPending
     ]);
     useEffect(() => {
         retryWorkspaceSyncRef.current = retryWorkspaceCloudSync;
@@ -1492,7 +1691,16 @@ export function useSyncOrchestrator(input) {
                 return;
             refreshWorkspaceSyncContextAssetSnapshots();
         };
+        const handleAiProfilesMutated = (event) => {
+            const detail = event.detail;
+            const eventWorkspaceId = String(detail?.workspaceId || '').trim() || 'default';
+            if (eventWorkspaceId !== currentWorkspaceId)
+                return;
+            void refreshWorkspaceSyncAiProfilesSnapshot();
+            void refreshWorkspaceSyncAssetsSnapshot();
+        };
         window.addEventListener(TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT, handleContextAssetsMutated);
+        window.addEventListener(TASKFORCE_AI_PROFILES_MUTATED_EVENT, handleAiProfilesMutated);
         const docsIntervalId = window.setInterval(() => {
             void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
         }, workspaceDocumentsRefreshIntervalMs);
@@ -1510,6 +1718,7 @@ export function useSyncOrchestrator(input) {
         }, workspaceDocumentsRefreshIntervalMs);
         return () => {
             window.removeEventListener(TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT, handleContextAssetsMutated);
+            window.removeEventListener(TASKFORCE_AI_PROFILES_MUTATED_EVENT, handleAiProfilesMutated);
             window.clearInterval(docsIntervalId);
             window.clearInterval(aiProfilesIntervalId);
             window.clearInterval(assetsIntervalId);
@@ -1545,11 +1754,14 @@ export function useSyncOrchestrator(input) {
         refreshWorkspaceSyncContextAssetSnapshots();
     }, [cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, authSessionResolved, isAuthenticated, taskAttachmentsFingerprint, refreshWorkspaceSyncContextAssetSnapshots]);
     useEffect(() => {
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved)
-            return;
-        if (workspaceSyncPhase === 'attach-cloud')
-            return;
-        if (!workspaceSyncReferenceSnapshotsReady)
+        if (!shouldScheduleWorkspaceReactivePush({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            authSessionResolved,
+            workspaceSyncPhase,
+            workspaceSyncReferenceSnapshotsReady
+        }))
             return;
         const signature = buildWorkspaceSyncSignature();
         if (shouldSuppressAttachBootstrapPush(signature))
@@ -1587,11 +1799,14 @@ export function useSyncOrchestrator(input) {
         workspacePullInFlightRef
     ]);
     useEffect(() => {
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved)
-            return;
-        if (workspaceSyncPhase !== 'active')
-            return;
-        if (!workspaceSyncReferenceSnapshotsReady)
+        if (!shouldStartWorkspacePushWatchdog({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            authSessionResolved,
+            workspaceSyncPhase,
+            workspaceSyncReferenceSnapshotsReady
+        }))
             return;
         const intervalId = window.setInterval(() => {
             if (workspacePushInFlightRef.current || workspacePullInFlightRef.current)
@@ -1633,14 +1848,18 @@ export function useSyncOrchestrator(input) {
         clearWorkspaceRetry
     ]);
     useEffect(() => {
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved)
-            return;
-        if (workspaceSyncPhase === 'provision-local' || workspaceSyncPhase === 'error')
-            return;
-        if (isWorkspaceRetryPending())
+        const pullPolicy = resolveWorkspaceAutomaticPullPolicy({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            authSessionResolved,
+            workspaceSyncPhase,
+            lastPullAt: workspaceLastPullAt,
+            retryPending: isWorkspaceRetryPending()
+        });
+        if (!pullPolicy.shouldStart)
             return;
-        const shouldKickOffPull = workspaceSyncPhase === 'attach-cloud' || !workspaceLastPullAt;
-        if (shouldKickOffPull) {
+        if (pullPolicy.shouldKickOffImmediately) {
             void pullWorkspaceChangesFromCloud();
         }
         const intervalId = window.setInterval(() => {
@@ -1661,9 +1880,14 @@ export function useSyncOrchestrator(input) {
         workspacePullIntervalMs
     ]);
     useEffect(() => {
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled || !authSessionResolved || !isAuthenticated)
-            return;
-        if (workspaceSyncPhase !== 'active')
+        if (!shouldStartWorkspacePeriodicFullReconcile({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            authSessionResolved,
+            isAuthenticated,
+            workspaceSyncPhase
+        }))
             return;
         const intervalId = window.setInterval(() => {
             if (workspaceFullReconcileInFlightRef.current)
@@ -1726,13 +1950,15 @@ export function useSyncOrchestrator(input) {
     // 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)
+        if (!shouldRunWorkspaceStartupRepair({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            authSessionResolved,
+            isAuthenticated,
+            workspaceSyncPhase,
+            alreadyRan: workspaceStartupRepairRanRef.current
+        }))
             return;
         workspaceStartupRepairRanRef.current = true;
         fetch('/api/taskforce/sync/workspace/repair-startup', {