@taskforcehq/taskforce 0.3.305 → 0.3.307

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

@@ -1,14 +1,19 @@
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
 import { type EnsureWorkspaceReadyResult } from '../../sync/syncService';
-import type { WorkspaceSyncPayload } from '../../sync/workspaceSyncModel';
+import type { WorkspaceSyncBaselineResetReason, WorkspaceSyncPayload } from '../../sync/workspaceSyncModel';
 import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+export interface PendingWorkspacePushReplay {
+    signature: string;
+    payload: WorkspaceSyncPayload;
+    forceAllAiProfiles: boolean;
+    repairMode: boolean;
+}
 interface CreateWorkspaceTransferCoordinatorArgs {
     cloudAuthConfigured: boolean;
     runtimeMode: 'local' | 'cloud';
     workspaceCloudSyncEnabled: boolean;
     currentWorkspaceId: string;
     workspaceSyncPhase: WorkspaceSyncPhase;
-    taxonomyStateFingerprint: string;
     isAuthenticated: boolean;
     checkAuthSession: () => Promise<boolean>;
     resolveCloudAuthUrl: (path: string) => string;
@@ -29,6 +34,8 @@ interface CreateWorkspaceTransferCoordinatorArgs {
         lastSyncedAt: string;
         pullCursor?: string | null;
         lastErrorMessage: null;
+    } | {
+        pullCursor: null;
     }) => void;
     persistWorkspaceSyncPatchBestEffort: (patch: {
         phase: 'active';
@@ -37,6 +44,7 @@ interface CreateWorkspaceTransferCoordinatorArgs {
         lastSyncedAt: string;
         lastErrorMessage: null;
     }) => Promise<unknown>;
+    persistWorkspaceSyncWatermarksSnapshotBestEffort: () => boolean;
     reportSyncEvent: (workspaceId: string, event: {
         eventType: 'pull' | 'handshake' | 'bootstrap' | 'apply' | 'push';
         status: 'success' | 'error';
@@ -52,6 +60,7 @@ interface CreateWorkspaceTransferCoordinatorArgs {
     refreshWorkspaceSyncMarkdownDocumentsSnapshot: () => Promise<void>;
     refreshWorkspaceSyncAiProfilesSnapshot: () => Promise<void>;
     refreshWorkspaceSyncAssetsSnapshot: () => Promise<void>;
+    refreshWorkspaceSyncPlanningEntitiesSnapshot: () => Promise<void>;
     refreshWorkspaceSyncDocumentReviewSessionsSnapshot: () => Promise<void>;
     refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot: () => Promise<void>;
     refreshLocalWorkspaceTaskCollections: () => Promise<void>;
@@ -70,6 +79,7 @@ interface CreateWorkspaceTransferCoordinatorArgs {
     workspaceForceFullAiProfilePushRef: MutableRefObject<boolean>;
     workspacePushInFlightRef: MutableRefObject<boolean>;
     workspacePullInFlightRef: MutableRefObject<boolean>;
+    workspacePendingPushReplayRef: MutableRefObject<PendingWorkspacePushReplay | null>;
     workspaceLastPushedSignatureRef: MutableRefObject<string>;
     workspacePendingSignatureRef: MutableRefObject<string>;
     workspaceLastPushedTaskIdsRef: MutableRefObject<Set<string>>;
@@ -77,12 +87,14 @@ interface CreateWorkspaceTransferCoordinatorArgs {
     workspaceDeletedTaskWatermarksRef: MutableRefObject<Map<string, string>>;
     workspacePullCursorRef: MutableRefObject<string | null>;
     workspaceLastPushedWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedTaskChangeKeysRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedInitiativeIdsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedInitiativeWatermarksRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedWorkstreamIdsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedWorkstreamWatermarksRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedAiProfileIdsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedAiProfileWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedAiProfileChangeKeysRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedDocumentPathsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedDocumentWatermarksRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedAssetPathsRef: MutableRefObject<Set<string>>;
@@ -94,6 +106,7 @@ interface CreateWorkspaceTransferCoordinatorArgs {
     workspaceLastPushedAnnotatedAttachmentSessionIdsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedTaskEventWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceBaselineResetReasonRef: MutableRefObject<WorkspaceSyncBaselineResetReason | null>;
     workspaceCaptureAttachBootstrapBaselineRef: MutableRefObject<boolean>;
     workspaceStartupFullReconcileRanRef: MutableRefObject<boolean>;
     workspaceFullReconcileInFlightRef: MutableRefObject<boolean>;
@@ -110,7 +123,7 @@ interface CreateWorkspaceTransferCoordinatorArgs {
     setTasks: Dispatch<SetStateAction<any[]>>;
     setArchivedTasks: Dispatch<SetStateAction<any[]>>;
 }
-export declare function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, currentWorkspaceId, workspaceSyncPhase, taxonomyStateFingerprint, isAuthenticated, checkAuthSession, resolveCloudAuthUrl, ensureCloudWorkspaceReadyForSync, ensureWorkspaceSyncReady, handleSyncAuthFailure, clearWorkspaceRetry, clearWorkspaceIssue, isWorkspaceRetryPending, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely, persistWorkspaceSyncPatchBestEffort, reportSyncEvent, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, reportWorkspaceWindowContention, refreshWorkspaceSyncMarkdownDocumentsSnapshot, refreshWorkspaceSyncAiProfilesSnapshot, refreshWorkspaceSyncAssetsSnapshot, refreshWorkspaceSyncDocumentReviewSessionsSnapshot, refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot, refreshLocalWorkspaceTaskCollections, buildWorkspaceSyncPayload, buildWorkspaceSyncSignature, seedWorkspaceSnapshotPushBaseline, shouldSuppressAttachBootstrapPush, recordSuppressedEventIds, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspaceDeletedTaskWatermarksRef, workspacePullCursorRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, workspaceCaptureAttachBootstrapBaselineRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, bootstrapLastProgressAtRef, realtimeSuppressedEventQueueRef, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceSyncPendingChanges, setTasks, setArchivedTasks }: CreateWorkspaceTransferCoordinatorArgs): {
+export declare function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, currentWorkspaceId, workspaceSyncPhase, isAuthenticated, checkAuthSession, resolveCloudAuthUrl, ensureCloudWorkspaceReadyForSync, ensureWorkspaceSyncReady, handleSyncAuthFailure, clearWorkspaceRetry, clearWorkspaceIssue, isWorkspaceRetryPending, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely, persistWorkspaceSyncPatchBestEffort, persistWorkspaceSyncWatermarksSnapshotBestEffort, reportSyncEvent, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, reportWorkspaceWindowContention, refreshWorkspaceSyncMarkdownDocumentsSnapshot, refreshWorkspaceSyncAiProfilesSnapshot, refreshWorkspaceSyncAssetsSnapshot, refreshWorkspaceSyncPlanningEntitiesSnapshot, refreshWorkspaceSyncDocumentReviewSessionsSnapshot, refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot, refreshLocalWorkspaceTaskCollections, buildWorkspaceSyncPayload, buildWorkspaceSyncSignature, seedWorkspaceSnapshotPushBaseline, shouldSuppressAttachBootstrapPush, recordSuppressedEventIds, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspacePushInFlightRef, workspacePullInFlightRef, workspacePendingPushReplayRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspaceDeletedTaskWatermarksRef, workspacePullCursorRef, workspaceLastPushedWatermarksRef, workspaceLastPushedTaskChangeKeysRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedAiProfileChangeKeysRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, workspaceBaselineResetReasonRef, workspaceCaptureAttachBootstrapBaselineRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, bootstrapLastProgressAtRef, realtimeSuppressedEventQueueRef, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceSyncPendingChanges, setTasks, setArchivedTasks }: CreateWorkspaceTransferCoordinatorArgs): {
     pushWorkspaceChangesToCloud: (signature: string, options?: {
         forceAllAiProfiles?: boolean;
         repairMode?: boolean;

package/dist/hooks/sync/transfers.js

@@ -1,35 +1,54 @@
 import { applyLocalWorkspaceChanges } from '../../sync/cloudSyncApi';
 import { isTransientWorkspaceSyncStatus, runWorkspacePullSyncService, runWorkspacePushSyncService } from '../../sync/syncService';
-import { logSyncDebug, savePersistedSyncWatermarks, isValidWorkspaceKey } from './orchestratorShared';
-export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, currentWorkspaceId, workspaceSyncPhase, taxonomyStateFingerprint, isAuthenticated, checkAuthSession, resolveCloudAuthUrl, ensureCloudWorkspaceReadyForSync, ensureWorkspaceSyncReady, handleSyncAuthFailure, clearWorkspaceRetry, clearWorkspaceIssue, isWorkspaceRetryPending, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely, persistWorkspaceSyncPatchBestEffort, reportSyncEvent, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, reportWorkspaceWindowContention, refreshWorkspaceSyncMarkdownDocumentsSnapshot, refreshWorkspaceSyncAiProfilesSnapshot, refreshWorkspaceSyncAssetsSnapshot, refreshWorkspaceSyncDocumentReviewSessionsSnapshot, refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot, refreshLocalWorkspaceTaskCollections, buildWorkspaceSyncPayload, buildWorkspaceSyncSignature, seedWorkspaceSnapshotPushBaseline, shouldSuppressAttachBootstrapPush, recordSuppressedEventIds, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspaceDeletedTaskWatermarksRef, workspacePullCursorRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, workspaceCaptureAttachBootstrapBaselineRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, bootstrapLastProgressAtRef, realtimeSuppressedEventQueueRef, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceSyncPendingChanges, setTasks, setArchivedTasks }) {
+import { createWorkspaceSyncLeaseHeldDecision, resolvePullSyncReadiness, resolvePushSyncReadiness } from './controlPlane';
+import { resolveWorkspacePullRequestPlan, resolveWorkspacePullSuccessPlan } from './pullLifecycle';
+import { logSyncDebug } from './orchestratorShared';
+export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, currentWorkspaceId, workspaceSyncPhase, isAuthenticated, checkAuthSession, resolveCloudAuthUrl, ensureCloudWorkspaceReadyForSync, ensureWorkspaceSyncReady, handleSyncAuthFailure, clearWorkspaceRetry, clearWorkspaceIssue, isWorkspaceRetryPending, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely, persistWorkspaceSyncPatchBestEffort, persistWorkspaceSyncWatermarksSnapshotBestEffort, reportSyncEvent, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, reportWorkspaceWindowContention, refreshWorkspaceSyncMarkdownDocumentsSnapshot, refreshWorkspaceSyncAiProfilesSnapshot, refreshWorkspaceSyncAssetsSnapshot, refreshWorkspaceSyncPlanningEntitiesSnapshot, refreshWorkspaceSyncDocumentReviewSessionsSnapshot, refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot, refreshLocalWorkspaceTaskCollections, buildWorkspaceSyncPayload, buildWorkspaceSyncSignature, seedWorkspaceSnapshotPushBaseline, shouldSuppressAttachBootstrapPush, recordSuppressedEventIds, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspacePushInFlightRef, workspacePullInFlightRef, workspacePendingPushReplayRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspaceDeletedTaskWatermarksRef, workspacePullCursorRef, workspaceLastPushedWatermarksRef, workspaceLastPushedTaskChangeKeysRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedAiProfileChangeKeysRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, workspaceBaselineResetReasonRef, workspaceCaptureAttachBootstrapBaselineRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, bootstrapLastProgressAtRef, realtimeSuppressedEventQueueRef, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceSyncPendingChanges, setTasks, setArchivedTasks }) {
     const pushWorkspaceChangesToCloud = 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) {
+        let pushReadiness = resolvePushSyncReadiness({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            currentWorkspaceId,
+            workspaceSyncPhase,
+            isAuthenticated,
+            repairModeActive: workspaceRepairModeRef.current === true,
+            repairModeBypass: options?.repairMode === true,
+            pushInFlight: workspacePushInFlightRef.current,
+            pullInFlight: workspacePullInFlightRef.current
+        });
+        if (!pushReadiness.allowed && pushReadiness.reason === 'auth-required') {
             const authed = await checkAuthSession();
             if (!authed)
                 return false;
+            pushReadiness = resolvePushSyncReadiness({
+                cloudAuthConfigured,
+                runtimeMode,
+                workspaceCloudSyncEnabled,
+                currentWorkspaceId,
+                workspaceSyncPhase,
+                isAuthenticated: true,
+                repairModeActive: workspaceRepairModeRef.current === true,
+                repairModeBypass: options?.repairMode === true,
+                pushInFlight: workspacePushInFlightRef.current,
+                pullInFlight: workspacePullInFlightRef.current
+            });
         }
-        if (shouldSuppressAttachBootstrapPush(signature)) {
+        if (!pushReadiness.allowed) {
+            if (pushReadiness.retainPendingSignature) {
+                workspacePendingSignatureRef.current = signature;
+            }
             return false;
         }
-        if (workspacePushInFlightRef.current || workspacePullInFlightRef.current) {
-            workspacePendingSignatureRef.current = signature;
+        if (shouldSuppressAttachBootstrapPush(signature)) {
             return false;
         }
         const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'push');
         if (!leaseAcquired) {
-            workspacePendingSignatureRef.current = signature;
+            const leaseDecision = createWorkspaceSyncLeaseHeldDecision('push');
+            if (!leaseDecision.allowed && leaseDecision.retainPendingSignature) {
+                workspacePendingSignatureRef.current = signature;
+            }
             reportWorkspaceWindowContention('push');
             return false;
         }
@@ -39,25 +58,48 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
         setUserGlobalSyncError(null);
         const pushStartedAtMs = Date.now();
         const forceAllAiProfiles = options?.forceAllAiProfiles === true || workspaceForceFullAiProfilePushRef.current === true;
+        const repairMode = options?.repairMode === true || workspaceRepairModeRef.current === true;
+        let payloadForAttempt = null;
+        let replayedPayload = false;
+        let attemptSignature = signature;
         try {
             await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
             await refreshWorkspaceSyncAiProfilesSnapshot();
             await refreshWorkspaceSyncAssetsSnapshot();
+            await refreshWorkspaceSyncPlanningEntitiesSnapshot();
             await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
             const ready = await ensureWorkspaceSyncReady();
             if (!ready)
                 return false;
-            const payload = buildWorkspaceSyncPayload({ forceAllAiProfiles });
+            const refreshedSignature = buildWorkspaceSyncSignature();
+            if (refreshedSignature) {
+                attemptSignature = refreshedSignature;
+            }
+            if (shouldSuppressAttachBootstrapPush(attemptSignature)) {
+                return false;
+            }
+            const pendingReplay = workspacePendingPushReplayRef.current;
+            const canReplayPayload = (pendingReplay
+                && pendingReplay.signature === attemptSignature
+                && (!forceAllAiProfiles || pendingReplay.forceAllAiProfiles === true)
+                && (!repairMode || pendingReplay.repairMode === true));
+            const replayPayload = canReplayPayload
+                ? pendingReplay
+                : null;
+            const payload = replayPayload?.payload || buildWorkspaceSyncPayload({ forceAllAiProfiles });
+            payloadForAttempt = payload;
+            replayedPayload = replayPayload !== null;
             setWorkspaceSyncPendingChanges(payload.changes.length);
             const pushResult = await runWorkspacePushSyncService({
                 resolveCloudAuthUrl,
                 workspaceId: currentWorkspaceId,
                 payload,
                 ensureCloudWorkspaceReadyForSync,
-                repairMode: options?.repairMode === true || workspaceRepairModeRef.current === true
+                repairMode: replayPayload?.repairMode ?? repairMode
             });
             if (!pushResult.success) {
                 if (pushResult.status === 401) {
+                    workspacePendingPushReplayRef.current = null;
                     await handleSyncAuthFailure('push', 401);
                     return false;
                 }
@@ -76,25 +118,48 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                     status: 'error',
                     statusCode: pushResult.status,
                     errorMessage: message,
-                    requestMs: pushResult.requestMs
+                    requestMs: pushResult.requestMs,
+                    details: {
+                        payloadDiagnostics: payload.deltaDiagnostics || null,
+                        replayedPayload
+                    }
                 });
-                workspacePendingSignatureRef.current = signature;
+                workspacePendingSignatureRef.current = attemptSignature;
                 if (pushResult.transient || isTransientWorkspaceSyncStatus(pushResult.status)) {
+                    workspacePendingPushReplayRef.current = {
+                        signature: attemptSignature,
+                        payload,
+                        forceAllAiProfiles: replayPayload?.forceAllAiProfiles ?? forceAllAiProfiles,
+                        repairMode: replayPayload?.repairMode ?? repairMode
+                    };
                     scheduleWorkspaceSyncRetry(pushResult.retryAfterMs);
                 }
-                else if (workspaceSyncPhase === 'active') {
-                    persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+                else {
+                    workspacePendingPushReplayRef.current = null;
+                    if (workspaceSyncPhase === 'active') {
+                        persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+                    }
                 }
                 return false;
             }
-            workspaceLastPushedSignatureRef.current = signature;
+            workspacePendingPushReplayRef.current = null;
+            workspaceLastPushedSignatureRef.current = attemptSignature;
             workspaceLastPushedTaskIdsRef.current = pushResult.currentTaskIds;
+            workspaceLastPushedWatermarksRef.current = pushResult.currentTaskWatermarks
+                ? new Map(pushResult.currentTaskWatermarks)
+                : new Map(workspaceLastPushedWatermarksRef.current);
+            workspaceLastPushedTaskChangeKeysRef.current = pushResult.currentTaskChangeKeys
+                ? new Map(pushResult.currentTaskChangeKeys)
+                : new Map(workspaceLastPushedTaskChangeKeysRef.current);
             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);
+            workspaceLastPushedAiProfileChangeKeysRef.current = pushResult.currentAiProfileChangeKeys
+                ? new Map(pushResult.currentAiProfileChangeKeys)
+                : new Map(workspaceLastPushedAiProfileChangeKeysRef.current);
             workspaceLastPushedDocumentPathsRef.current = new Set(pushResult.currentDocumentPaths);
             workspaceLastPushedDocumentWatermarksRef.current = new Map(pushResult.currentDocumentWatermarks);
             workspaceLastPushedAssetPathsRef.current = new Set(pushResult.currentAssetPaths);
@@ -112,25 +177,19 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
             for (const [taskId, watermark] of pushResult.pushedWatermarks) {
                 workspaceLastPushedWatermarksRef.current.set(taskId, watermark);
             }
+            for (const [taskId, changeKey] of (pushResult.pushedTaskChangeKeys || new Map())) {
+                workspaceLastPushedTaskChangeKeysRef.current.set(taskId, changeKey);
+            }
             if (pushResult.deleteTaskIds.size > 0) {
                 for (const taskId of pushResult.deleteTaskIds) {
                     workspaceDeletedTaskIdsRef.current.delete(taskId);
                     workspaceDeletedTaskWatermarksRef.current.delete(taskId);
                     workspaceLastPushedWatermarksRef.current.delete(taskId);
+                    workspaceLastPushedTaskChangeKeysRef.current.delete(taskId);
                 }
             }
-            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,
-                taskEventWatermarks: workspaceLastPushedTaskEventWatermarksRef.current,
-                taxonomyStateFingerprint
-            });
+            const persisted = await persistWorkspaceSyncWatermarksSnapshotBestEffort();
+            workspaceBaselineResetReasonRef.current = persisted ? null : 'storage-write-failed';
             if (Array.isArray(pushResult.emittedEventIds) && pushResult.emittedEventIds.length > 0) {
                 recordSuppressedEventIds(pushResult.emittedEventIds, {
                     queueRef: realtimeSuppressedEventQueueRef,
@@ -187,7 +246,11 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                 eventType: workspaceSyncPhase === 'provision-local' ? 'bootstrap' : 'push',
                 status: 'success',
                 changeCount: pushResult.changeCount,
-                requestMs: pushResult.requestMs
+                requestMs: pushResult.requestMs,
+                details: {
+                    payloadDiagnostics: payload.deltaDiagnostics || null,
+                    replayedPayload
+                }
             });
             return true;
         }
@@ -197,12 +260,23 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
             setUserGlobalSyncError(message);
             setWorkspaceLastErrorMessage(message);
             setWorkspaceLastErrorAt(new Date().toISOString());
-            workspacePendingSignatureRef.current = signature;
+            workspacePendingSignatureRef.current = attemptSignature;
+            if (payloadForAttempt) {
+                workspacePendingPushReplayRef.current = {
+                    signature: attemptSignature,
+                    payload: payloadForAttempt,
+                    forceAllAiProfiles,
+                    repairMode
+                };
+            }
             scheduleWorkspaceSyncRetry();
             reportSyncEvent(currentWorkspaceId, {
                 eventType: 'push',
                 status: 'error',
-                errorMessage: `${message} ${String(error?.message || '').trim()}`.trim()
+                errorMessage: `${message} ${String(error?.message || '').trim()}`.trim(),
+                details: {
+                    replayedPayload
+                }
             });
             logSyncDebug('push_failed_exception', {
                 workspaceId: currentWorkspaceId,
@@ -229,23 +303,40 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
         }
     };
     const pullWorkspaceChangesFromCloud = 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) {
+        let pullReadiness = resolvePullSyncReadiness({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            currentWorkspaceId,
+            workspaceSyncPhase,
+            isAuthenticated,
+            repairModeActive: workspaceRepairModeRef.current === true,
+            repairModeBypass: options?.repairMode === true,
+            retryPending: isWorkspaceRetryPending(),
+            pullInFlight: workspacePullInFlightRef.current,
+            pushInFlight: workspacePushInFlightRef.current
+        });
+        if (!pullReadiness.allowed && pullReadiness.reason === 'auth-required') {
             const authed = await checkAuthSession();
             if (!authed)
                 return false;
+            pullReadiness = resolvePullSyncReadiness({
+                cloudAuthConfigured,
+                runtimeMode,
+                workspaceCloudSyncEnabled,
+                currentWorkspaceId,
+                workspaceSyncPhase,
+                isAuthenticated: true,
+                repairModeActive: workspaceRepairModeRef.current === true,
+                repairModeBypass: options?.repairMode === true,
+                retryPending: isWorkspaceRetryPending(),
+                pullInFlight: workspacePullInFlightRef.current,
+                pushInFlight: workspacePushInFlightRef.current
+            });
         }
-        if (workspacePullInFlightRef.current || workspacePushInFlightRef.current)
+        if (!pullReadiness.allowed) {
             return false;
+        }
         const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'pull');
         if (!leaseAcquired) {
             reportWorkspaceWindowContention('pull');
@@ -260,13 +351,16 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
             const ready = await ensureWorkspaceSyncReady();
             if (!ready)
                 return false;
-            const bootstrap = workspaceSyncPhase === 'attach-cloud';
-            const cursor = bootstrap || options?.forceCursorNull === true ? null : workspacePullCursorRef.current;
+            const pullRequestPlan = resolveWorkspacePullRequestPlan({
+                workspaceSyncPhase,
+                forceCursorNull: options?.forceCursorNull === true,
+                currentCursor: workspacePullCursorRef.current
+            });
             const pullResult = await runWorkspacePullSyncService({
                 resolveCloudAuthUrl,
                 workspaceId: currentWorkspaceId,
-                cursor,
-                bootstrap,
+                cursor: pullRequestPlan.cursor,
+                bootstrap: pullRequestPlan.bootstrap,
                 ensureCloudWorkspaceReadyForSync,
                 maxPages: 20,
                 repairMode: options?.repairMode === true || workspaceRepairModeRef.current === true,
@@ -282,6 +376,28 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                     await handleSyncAuthFailure('apply', 401);
                     return false;
                 }
+                if (pullResult.kind === 'pull_http' && pullResult.errorCode === 'INVALID_SYNC_CURSOR') {
+                    const message = 'Saved sync cursor was invalid. Clearing it and retrying from the beginning.';
+                    workspacePullCursorRef.current = null;
+                    persistWorkspaceSyncPatchSafely({ pullCursor: null });
+                    setUserGlobalSyncStatus('error');
+                    setUserGlobalSyncError(message);
+                    setWorkspaceLastErrorMessage(message);
+                    setWorkspaceLastErrorAt(new Date().toISOString());
+                    reportSyncEvent(currentWorkspaceId, {
+                        eventType: 'pull',
+                        status: 'error',
+                        statusCode: pullResult.status,
+                        errorMessage: message,
+                        requestMs: pullResult.pullRequestMs,
+                        details: {
+                            recovery: 'cursor-reset',
+                            ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                        }
+                    });
+                    scheduleWorkspaceSyncRetry(150);
+                    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})`;
@@ -332,7 +448,8 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
             if (pullResult.appliedChanges > 0
                 && (pullResult.pulledActiveUpserts
                     || pullResult.pulledArchivedUpserts
-                    || pullResult.pulledTaskEventUpserts)) {
+                    || pullResult.pulledTaskEventUpserts
+                    || pullResult.pulledPlanningUpserts)) {
                 try {
                     await refreshLocalWorkspaceTaskCollections();
                 }
@@ -349,9 +466,20 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
             setWorkspaceLastPullAt(syncedAt);
             setWorkspaceSyncPendingChanges(0);
             setUserGlobalSyncStatus('idle');
-            if (workspaceSyncPhase === 'attach-cloud') {
+            const pullSuccessPlan = resolveWorkspacePullSuccessPlan({
+                workspaceSyncPhase,
+                forceCursorNull: options?.forceCursorNull === true,
+                startupFullReconcileRan: workspaceStartupFullReconcileRanRef.current,
+                pendingSignature: workspacePendingSignatureRef.current,
+                fallbackSignature: buildWorkspaceSyncSignature(),
+                lastPushedSignature: workspaceLastPushedSignatureRef.current
+            });
+            if (pullSuccessPlan.shouldCaptureAttachBootstrapBaseline) {
                 workspaceCaptureAttachBootstrapBaselineRef.current = true;
+            }
+            if (pullSuccessPlan.shouldClearPendingSignature) {
                 workspacePendingSignatureRef.current = '';
+                workspacePendingPushReplayRef.current = null;
             }
             await persistWorkspaceSyncPatchBestEffort({
                 phase: 'active',
@@ -361,7 +489,7 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                 lastErrorMessage: null
             });
             reportSyncEvent(currentWorkspaceId, {
-                eventType: workspaceSyncPhase === 'attach-cloud' ? 'bootstrap' : 'pull',
+                eventType: pullSuccessPlan.successEventType,
                 status: 'success',
                 changeCount: pullResult.appliedChanges,
                 requestMs: pullResult.pullRequestMs,
@@ -371,15 +499,19 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                     ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
                 }
             });
-            if (workspaceSyncPhase === 'attach-cloud') {
+            if (pullSuccessPlan.shouldRefreshReferenceSnapshots) {
                 await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
                 await refreshWorkspaceSyncAssetsSnapshot();
                 await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
                 await refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
+            }
+            if (pullSuccessPlan.shouldSeedWorkspaceSnapshotPushBaseline) {
                 seedWorkspaceSnapshotPushBaseline();
+            }
+            if (pullSuccessPlan.shouldRefreshReferenceSnapshots || pullSuccessPlan.shouldSeedWorkspaceSnapshotPushBaseline) {
                 return true;
             }
-            if (!options?.forceCursorNull && !bootstrap && !workspaceStartupFullReconcileRanRef.current) {
+            if (pullSuccessPlan.shouldScheduleStartupFullReconcile) {
                 workspaceStartupFullReconcileRanRef.current = true;
                 window.setTimeout(() => {
                     if (workspaceFullReconcileInFlightRef.current)
@@ -390,11 +522,23 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                     });
                 }, 250);
             }
-            const pendingSignature = workspacePendingSignatureRef.current || buildWorkspaceSyncSignature();
-            if (pendingSignature && pendingSignature !== workspaceLastPushedSignatureRef.current) {
-                workspacePendingSignatureRef.current = '';
+            const shouldReassertAiProfilesAfterFullReconcile = (options?.forceCursorNull === true
+                && options?.repairMode !== true
+                && workspaceSyncPhase === 'active');
+            if (shouldReassertAiProfilesAfterFullReconcile) {
+                const reassertSignature = buildWorkspaceSyncSignature();
+                if (reassertSignature) {
+                    workspaceForceFullAiProfilePushRef.current = true;
+                    workspacePendingSignatureRef.current = reassertSignature;
+                    window.setTimeout(() => {
+                        void pushWorkspaceChangesToCloud(reassertSignature, { forceAllAiProfiles: true });
+                    }, 120);
+                }
+            }
+            else if (pullSuccessPlan.deferredPushSignature) {
+                const deferredPushSignature = pullSuccessPlan.deferredPushSignature;
                 window.setTimeout(() => {
-                    void pushWorkspaceChangesToCloud(pendingSignature);
+                    void pushWorkspaceChangesToCloud(deferredPushSignature);
                 }, 120);
             }
             return true;

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

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