@taskforcehq/taskforce 0.3.304 → 0.3.306

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, 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, 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,6 +58,9 @@ 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;
         try {
             await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
             await refreshWorkspaceSyncAiProfilesSnapshot();
@@ -47,17 +69,24 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
             const ready = await ensureWorkspaceSyncReady();
             if (!ready)
                 return false;
-            const payload = buildWorkspaceSyncPayload({ forceAllAiProfiles });
+            const pendingReplay = workspacePendingPushReplayRef.current;
+            const replayPayload = pendingReplay && pendingReplay.signature === signature
+                ? 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 +105,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;
                 if (pushResult.transient || isTransientWorkspaceSyncStatus(pushResult.status)) {
+                    workspacePendingPushReplayRef.current = {
+                        signature,
+                        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;
             }
+            workspacePendingPushReplayRef.current = null;
             workspaceLastPushedSignatureRef.current = signature;
             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,24 +164,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,
@@ -186,7 +233,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,11 +248,22 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
             setWorkspaceLastErrorMessage(message);
             setWorkspaceLastErrorAt(new Date().toISOString());
             workspacePendingSignatureRef.current = signature;
+            if (payloadForAttempt) {
+                workspacePendingPushReplayRef.current = {
+                    signature,
+                    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,
@@ -214,34 +276,54 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
             setWorkspaceSyncBusy(workspacePullInFlightRef.current);
             releaseWorkspaceSyncLease(currentWorkspaceId);
             const pendingSignature = workspacePendingSignatureRef.current;
+            const latestSignature = buildWorkspaceSyncSignature();
             if (pendingSignature
-                && pendingSignature !== workspaceLastPushedSignatureRef.current
-                && !workspacePullInFlightRef.current) {
+                && latestSignature
+                && latestSignature !== workspaceLastPushedSignatureRef.current
+                && !workspacePullInFlightRef.current
+                && !isWorkspaceRetryPending()) {
                 workspacePendingSignatureRef.current = '';
                 window.setTimeout(() => {
-                    void pushWorkspaceChangesToCloud(pendingSignature);
+                    void pushWorkspaceChangesToCloud(latestSignature);
                 }, 120);
             }
         }
     };
     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');
@@ -256,13 +338,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,
@@ -278,6 +363,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})`;
@@ -345,9 +452,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',
@@ -357,7 +475,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,
@@ -367,15 +485,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)
@@ -386,11 +508,10 @@ export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtim
                     });
                 }, 250);
             }
-            const pendingSignature = workspacePendingSignatureRef.current || buildWorkspaceSyncSignature();
-            if (pendingSignature && pendingSignature !== workspaceLastPushedSignatureRef.current) {
-                workspacePendingSignatureRef.current = '';
+            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 {};