@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/engine/workspaceSyncEngineTransfers.js

@@ -0,0 +1,1184 @@
+import { isTransientWorkspaceSyncStatus, runWorkspacePullSyncService, runWorkspacePushSyncService } from '../syncService.js';
+import { createWorkspaceSyncLeaseHeldDecision, resolvePullSyncReadiness, resolvePushSyncReadiness } from './workspaceSyncEngineControlPlane.js';
+import { resolveWorkspacePullRequestPlan, resolveWorkspacePullSuccessPlan } from './workspaceSyncEnginePullPolicy.js';
+import { runWorkspaceSyncV3InitiativeProjectionCycle } from '../v3/workspaceSyncV3FeedOrchestrator.js';
+import { runWorkspaceSyncV3CombinedProjectionCycle } from '../v3/workspaceSyncV3CombinedFeedOrchestrator.js';
+import { hydrateWorkspaceSyncV3AttachmentAsset } from '../v3/workspaceSyncV3AttachmentAssetHydration.js';
+import { WORKSPACE_SYNC_V3_APPLY_NOT_COMMITTED } from './workspaceSyncEngineRemoteServices.js';
+export function combinedAttachmentAssetHydrationId(input) {
+    if (input.causeCode === 'TASK_ATTACHMENT_ASSET_NOT_READY' && input.causeAssetId) {
+        return input.causeAssetId;
+    }
+    if (input.status !== 409)
+        return null;
+    const match = /^Task attachment asset is unavailable because it has not reached this runtime: ([A-Za-z0-9._:-]+)$/
+        .exec(String(input.error || ''));
+    return match?.[1] || null;
+}
+function v3ApplyingPage(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    const repair = data.repair;
+    return repair && typeof repair === 'object' && !Array.isArray(repair)
+        ? repair
+        : data;
+}
+function v3NextCursor(input) {
+    if (input.kind === 'delta')
+        return String(input.page.nextCursor || '') || null;
+    if (input.page.hasMore === true)
+        return String(input.page.nextRepairCursor || '') || null;
+    return input.kind === 'repair' ? String(input.page.resumeCursor || '') || null : null;
+}
+export function createWorkspaceSyncV3TransferBindings(input) {
+    const receipts = new WeakMap();
+    const pendingReceipts = new Set();
+    const capture = (response) => {
+        const page = v3ApplyingPage(response.data);
+        if (response.transferReceipt) {
+            pendingReceipts.add(response.transferReceipt);
+            if (page)
+                receipts.set(page, response.transferReceipt);
+        }
+        return response;
+    };
+    const completionGroup = (page, apply) => {
+        const receipt = receipts.get(page);
+        if (!receipt)
+            return undefined;
+        const group = input.remoteServices.buildV3ApplyCompletionGroup({
+            workspaceId: input.workspaceId,
+            apply,
+            receipts: [receipt],
+        });
+        if (!group) {
+            throw new Error('A v3 sync transfer receipt did not produce an apply completion group.');
+        }
+        return group;
+    };
+    const abandonReceipts = async (pending) => {
+        try {
+            await input.remoteServices.abandonTransferReceipts({
+                workspaceId: input.workspaceId,
+                receipts: pending,
+                errorCode: WORKSPACE_SYNC_V3_APPLY_NOT_COMMITTED,
+            });
+        }
+        catch {
+            // The adapter operation is idempotent. Retry once so a transient
+            // local store failure cannot strand an accepted gateway permit.
+            await input.remoteServices.abandonTransferReceipts({
+                workspaceId: input.workspaceId,
+                receipts: pending,
+                errorCode: WORKSPACE_SYNC_V3_APPLY_NOT_COMMITTED,
+            });
+        }
+    };
+    const abandonReceipt = async (page) => {
+        const receipt = receipts.get(page);
+        if (!receipt)
+            return;
+        await abandonReceipts([receipt]);
+        receipts.delete(page);
+        pendingReceipts.delete(receipt);
+    };
+    const applyWithReceipt = async (page, apply, applyLocal) => {
+        let abandonmentAttempted = false;
+        try {
+            const group = completionGroup(page, apply);
+            const result = await applyLocal(group);
+            if (group
+                && (!result
+                    || typeof result !== 'object'
+                    || !('ok' in result)
+                    || result.ok !== true)) {
+                abandonmentAttempted = true;
+                await abandonReceipt(page);
+            }
+            else if (group) {
+                const receipt = receipts.get(page);
+                receipts.delete(page);
+                if (receipt)
+                    pendingReceipts.delete(receipt);
+            }
+            return result;
+        }
+        catch (error) {
+            if (!abandonmentAttempted)
+                await abandonReceipt(page);
+            throw error;
+        }
+    };
+    const abandonPendingReceipts = async () => {
+        if (pendingReceipts.size === 0)
+            return;
+        const pending = Array.from(pendingReceipts);
+        await abandonReceipts(pending);
+        for (const receipt of pending)
+            pendingReceipts.delete(receipt);
+    };
+    return {
+        abandonPendingReceipts,
+        initiative: {
+            getLocalProjection: input.localServices.readInitiativeProjection,
+            applyLocalProjection: (workspaceId, applyInput) => {
+                if (applyInput.kind === 'rollback') {
+                    return input.localServices.applyInitiativeProjection(workspaceId, applyInput);
+                }
+                const apply = {
+                    projection: 'initiative',
+                    kind: applyInput.kind,
+                    epoch: applyInput.epoch,
+                    previousCursor: applyInput.previousCursor,
+                    nextCursor: v3NextCursor({
+                        kind: applyInput.kind,
+                        page: applyInput.page,
+                    }),
+                };
+                return applyWithReceipt(applyInput.page, apply, (group) => input.localServices.applyInitiativeProjection(workspaceId, applyInput, group ? { completionGroup: group } : undefined));
+            },
+            pullFeed: async (_resolveCloudAuthUrl, pullInput) => (capture(await input.remoteServices.pullInitiativeFeed(pullInput))),
+            pullInitiativeRepair: async (_resolveCloudAuthUrl, pullInput) => capture(await input.remoteServices.pullInitiativeRepair(pullInput)),
+        },
+        combined: {
+            getLocalProjection: input.localServices.readCombinedProjection,
+            applyLocalProjection: (workspaceId, applyInput, coverage) => {
+                const apply = {
+                    projection: 'combined',
+                    kind: applyInput.kind,
+                    epoch: applyInput.epoch,
+                    previousCursor: applyInput.previousCursor,
+                    nextCursor: v3NextCursor({
+                        kind: applyInput.kind,
+                        page: applyInput.page,
+                    }),
+                };
+                return applyWithReceipt(applyInput.page, apply, (group) => input.localServices.applyCombinedProjection(workspaceId, applyInput, coverage, group ? { completionGroup: group } : undefined));
+            },
+            getLocalTaskCommentAudit: input.localServices.readTaskCommentAuditCursor,
+            applyLocalTaskCommentAudit: (workspaceId, page) => {
+                const apply = {
+                    projection: 'task-comment-audit',
+                    kind: 'audit',
+                    previousCursor: page.previousCursor,
+                    nextCursor: page.nextCursor,
+                };
+                return applyWithReceipt(page, apply, (group) => input.localServices.applyTaskCommentAuditPage(workspaceId, page, group ? { completionGroup: group } : undefined));
+            },
+            pullFeed: async (_resolveCloudAuthUrl, pullInput) => (capture(await input.remoteServices.pullCombinedFeed(pullInput))),
+            pullFallbackRepair: async (_resolveCloudAuthUrl, pullInput) => capture(await input.remoteServices.pullCombinedRepair(pullInput)),
+            pullTaskCommentAudit: async (_resolveCloudAuthUrl, pullInput) => capture(await input.remoteServices.pullTaskCommentAudit(pullInput)),
+        },
+    };
+}
+export function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtimeMode, initiativeFeedActivationEnabled, combinedFeedActivationEnabled, combinedFeedCoverage, workspaceCloudSyncEnabled, currentWorkspaceId, workspaceSyncPhase, isAuthenticated, checkAuthSession, resolveCloudAuthUrl, ensureCloudWorkspaceReadyForSync, ensureWorkspaceSyncReady, handleSyncAuthFailure, clearWorkspaceRetry, clearWorkspaceIssue, isWorkspaceRetryPending, isDurableRecoveryBlockingOrdinaryPush, isExecutionAuthorized = () => true, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely, persistWorkspaceSyncPatchBestEffort, persistWorkspaceSyncWatermarksSnapshotBestEffort, refreshWorkspaceAiProfilePushBaselineFromPersistence, reportSyncEvent, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, recordWorkspaceSyncCompletion, reportWorkspaceWindowContention, refreshWorkspaceSyncMarkdownDocumentsSnapshot, refreshWorkspaceSyncAiProfilesSnapshot, refreshWorkspaceSyncAssetsSnapshot, refreshWorkspaceSyncTaxonomySnapshot, refreshWorkspaceSyncPlanningEntitiesSnapshot, refreshWorkspaceSyncDocumentReviewSessionsSnapshot, refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot, refreshWorkspaceSyncTaskforceAgentsSnapshot, refreshLocalWorkspaceTaskCollections, buildWorkspaceSyncPayload, buildWorkspaceSyncSignature, seedWorkspaceSnapshotPushBaseline, shouldSuppressAttachBootstrapPush, recordSuppressedEventIds, runtime, localServices, remoteServices, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceSyncPendingChanges, setTasks, setArchivedTasks, now, scheduleTask, logDebug = () => undefined, notifyAiProfilesMutated = () => undefined, notifyAgentsMutated = () => undefined, notifyAgentSkillsMutated = () => undefined }) {
+    const { repairMode: workspaceRepairModeRef, forceFullAiProfilePush: workspaceForceFullAiProfilePushRef, pushInFlight: workspacePushInFlightRef, pullInFlight: workspacePullInFlightRef, pullAfterPushRequested: workspacePullAfterPushRequestedRef, pendingPushReplay: workspacePendingPushReplayRef, blockedPushSignature: workspaceBlockedPushSignatureRef, lastPushedSignature: workspaceLastPushedSignatureRef, pendingSignature: workspacePendingSignatureRef, lastPushedTaskIds: workspaceLastPushedTaskIdsRef, deletedTaskIds: workspaceDeletedTaskIdsRef, deletedTaskWatermarks: workspaceDeletedTaskWatermarksRef, pullCursor: workspacePullCursorRef, lastPushedWatermarks: workspaceLastPushedWatermarksRef, lastPushedTaskChangeKeys: workspaceLastPushedTaskChangeKeysRef, lastPushedTaskRelationshipChangeKeys: workspaceLastPushedTaskRelationshipChangeKeysRef, lastPushedTaxonomyChangeKey: workspaceLastPushedTaxonomyChangeKeyRef, lastPushedInitiativeIds: workspaceLastPushedInitiativeIdsRef, lastPushedInitiativeWatermarks: workspaceLastPushedInitiativeWatermarksRef, lastPushedWorkstreamIds: workspaceLastPushedWorkstreamIdsRef, lastPushedWorkstreamWatermarks: workspaceLastPushedWorkstreamWatermarksRef, lastPushedAiProfileIds: workspaceLastPushedAiProfileIdsRef, lastPushedAiProfileWatermarks: workspaceLastPushedAiProfileWatermarksRef, lastPushedAiProfileChangeKeys: workspaceLastPushedAiProfileChangeKeysRef, lastPushedDocumentPaths: workspaceLastPushedDocumentPathsRef, lastPushedDocumentWatermarks: workspaceLastPushedDocumentWatermarksRef, lastPushedAssetPaths: workspaceLastPushedAssetPathsRef, lastPushedAssetWatermarks: workspaceLastPushedAssetWatermarksRef, lastPushedDocumentReviewSessionIds: workspaceLastPushedDocumentReviewSessionIdsRef, lastPushedDocumentReviewSessionWatermarks: workspaceLastPushedDocumentReviewSessionWatermarksRef, lastPushedDocumentReviewCommentIds: workspaceLastPushedDocumentReviewCommentIdsRef, lastPushedDocumentReviewCommentWatermarks: workspaceLastPushedDocumentReviewCommentWatermarksRef, lastPushedAnnotatedAttachmentSessionIds: workspaceLastPushedAnnotatedAttachmentSessionIdsRef, lastPushedAnnotatedAttachmentSessionWatermarks: workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, lastPushedTaskforceAgentIds: workspaceLastPushedTaskforceAgentIdsRef, lastPushedTaskforceAgentWatermarks: workspaceLastPushedTaskforceAgentWatermarksRef, lastPushedTaskforceAgentSkillIds: workspaceLastPushedTaskforceAgentSkillIdsRef, lastPushedTaskforceAgentSkillWatermarks: workspaceLastPushedTaskforceAgentSkillWatermarksRef, lastPushedAgentConversationIds: workspaceLastPushedAgentConversationIdsRef, lastPushedAgentConversationWatermarks: workspaceLastPushedAgentConversationWatermarksRef, lastPushedTaskEventWatermarks: workspaceLastPushedTaskEventWatermarksRef, baselineResetReason: workspaceBaselineResetReasonRef, captureAttachBootstrapBaseline: workspaceCaptureAttachBootstrapBaselineRef, startupFullReconcileRan: workspaceStartupFullReconcileRanRef, startupFullReconcileRequested: workspaceStartupFullReconcileRequestedRef, fullReconcileInFlight: workspaceFullReconcileInFlightRef, bootstrapLastProgressAtMs: bootstrapLastProgressAtRef, realtimeSuppressedEventQueue: realtimeSuppressedEventQueueRef, } = runtime;
+    const scheduledTasks = new Map();
+    let disposed = false;
+    const scheduleCoordinatorTask = (key, callback, delayMs) => {
+        if (disposed || !isExecutionAuthorized() || scheduledTasks.has(key))
+            return;
+        let scheduledTask = null;
+        scheduledTask = scheduleTask(() => {
+            scheduledTasks.delete(key);
+            if (!disposed && isExecutionAuthorized())
+                callback();
+        }, delayMs);
+        scheduledTasks.set(key, scheduledTask);
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        for (const scheduledTask of scheduledTasks.values())
+            scheduledTask.cancel();
+        scheduledTasks.clear();
+    };
+    const pushWorkspaceChangesToCloud = async (signature, options) => {
+        if (!isExecutionAuthorized())
+            return false;
+        if (options?.repairMode !== true && isDurableRecoveryBlockingOrdinaryPush()) {
+            workspacePendingSignatureRef.current = signature;
+            return false;
+        }
+        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 (!pushReadiness.allowed) {
+            if (pushReadiness.retainPendingSignature) {
+                workspacePendingSignatureRef.current = signature;
+            }
+            return false;
+        }
+        if (shouldSuppressAttachBootstrapPush(signature)) {
+            return false;
+        }
+        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'push');
+        if (!leaseAcquired) {
+            const leaseDecision = createWorkspaceSyncLeaseHeldDecision('push');
+            if (!leaseDecision.allowed && leaseDecision.retainPendingSignature) {
+                workspacePendingSignatureRef.current = signature;
+            }
+            reportWorkspaceWindowContention('push');
+            return false;
+        }
+        workspacePushInFlightRef.current = true;
+        setWorkspaceSyncBusy(true);
+        setUserGlobalSyncStatus('syncing');
+        setUserGlobalSyncError(null);
+        const pushStartedAtMs = now().getTime();
+        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;
+        let suppressDeferredPush = false;
+        try {
+            refreshWorkspaceAiProfilePushBaselineFromPersistence?.();
+            const snapshotRefreshResults = [
+                await refreshWorkspaceSyncMarkdownDocumentsSnapshot(),
+                await refreshWorkspaceSyncAiProfilesSnapshot(),
+                await refreshWorkspaceSyncAssetsSnapshot(),
+                await refreshWorkspaceSyncTaxonomySnapshot(),
+                await refreshWorkspaceSyncPlanningEntitiesSnapshot(),
+                await refreshWorkspaceSyncDocumentReviewSessionsSnapshot(),
+                await refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(),
+                await refreshWorkspaceSyncTaskforceAgentsSnapshot?.()
+            ];
+            if (repairMode && snapshotRefreshResults.some((result) => result === false)) {
+                const message = 'Workspace sync repair could not refresh the complete local snapshot. Press Repair to retry.';
+                clearWorkspaceRetry();
+                setUserGlobalSyncStatus('error');
+                setUserGlobalSyncError(message);
+                setWorkspaceLastErrorMessage(message);
+                setWorkspaceLastErrorAt(now().toISOString());
+                await persistWorkspaceSyncPatchBestEffort({ phase: 'error', lastErrorMessage: message });
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'push',
+                    status: 'error',
+                    errorMessage: message,
+                    details: { recovery: 'repair-snapshot-refresh-failed' }
+                });
+                return false;
+            }
+            const ready = await ensureWorkspaceSyncReady();
+            if (!ready)
+                return false;
+            if (!isExecutionAuthorized())
+                return false;
+            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: replayPayload?.repairMode ?? repairMode,
+                remoteServices,
+                localServices,
+            });
+            if (!pushResult.success) {
+                if (pushResult.status === 401) {
+                    suppressDeferredPush = true;
+                    workspacePendingPushReplayRef.current = null;
+                    await handleSyncAuthFailure('push', 401);
+                    return false;
+                }
+                let message = pushResult.error
+                    ? `Workspace sync push failed (${pushResult.status || 0}): ${pushResult.error}`
+                    : `Workspace sync push failed (${pushResult.status || 0})`;
+                if (pushResult.status === 413) {
+                    message = 'Workspace sync failed because the payload is too large. This usually happens when one or more attachments exceed the project limit.';
+                }
+                setUserGlobalSyncStatus('error');
+                setUserGlobalSyncError(message);
+                setWorkspaceLastErrorMessage(message);
+                setWorkspaceLastErrorAt(now().toISOString());
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'push',
+                    status: 'error',
+                    statusCode: pushResult.status,
+                    errorMessage: message,
+                    requestMs: pushResult.requestMs,
+                    details: {
+                        payloadDiagnostics: payload.deltaDiagnostics || null,
+                        replayedPayload,
+                        ...(pushResult.batchProgress
+                            ? { pushBatchProgress: pushResult.batchProgress }
+                            : {}),
+                    }
+                });
+                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 {
+                    suppressDeferredPush = true;
+                    workspaceBlockedPushSignatureRef.current = attemptSignature;
+                    workspacePendingPushReplayRef.current = null;
+                    if (workspaceSyncPhase === 'active') {
+                        persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+                    }
+                }
+                return false;
+            }
+            const appliedTaskUpserts = pushResult.appliedTaskUpserts || [];
+            if (appliedTaskUpserts.length > 0) {
+                const pushTransferReceipts = pushResult.pushTransferReceipts || [];
+                const completionGroup = pushResult.pushBoundary
+                    ? remoteServices.buildV2PushApplyCompletionGroup({
+                        workspaceId: currentWorkspaceId,
+                        pushBoundary: pushResult.pushBoundary,
+                        receipts: pushTransferReceipts,
+                    })
+                    : undefined;
+                if (pushTransferReceipts.length > 0 && !completionGroup) {
+                    await remoteServices.abandonTransferReceipts({
+                        workspaceId: currentWorkspaceId,
+                        receipts: pushTransferReceipts,
+                        errorCode: 'WORKSPACE_SYNC_V2_PUSH_APPLY_COMPLETION_INVALID',
+                    });
+                    throw new Error('Accepted V2 push echoes are missing an atomic local apply completion group.');
+                }
+                let applyResult;
+                try {
+                    const authoritativeChanges = appliedTaskUpserts.map((entry) => ({
+                        op: 'upsert',
+                        archived: entry.archived === true,
+                        task: entry.task,
+                        ...(entry.durableRevision ? { durableRevision: entry.durableRevision } : {}),
+                    }));
+                    applyResult = completionGroup
+                        ? await localServices.applyV2Batch(currentWorkspaceId, authoritativeChanges, { completionGroup })
+                        : await localServices.applyV2Batch(currentWorkspaceId, authoritativeChanges);
+                }
+                catch (error) {
+                    if (pushTransferReceipts.length > 0) {
+                        await remoteServices.abandonTransferReceipts({
+                            workspaceId: currentWorkspaceId,
+                            receipts: pushTransferReceipts,
+                            errorCode: 'WORKSPACE_SYNC_V2_PUSH_AUTHORITATIVE_APPLY_FAILED',
+                        });
+                    }
+                    throw error;
+                }
+                if (!applyResult.ok) {
+                    if (pushTransferReceipts.length > 0) {
+                        await remoteServices.abandonTransferReceipts({
+                            workspaceId: currentWorkspaceId,
+                            receipts: pushTransferReceipts,
+                            errorCode: 'WORKSPACE_SYNC_V2_PUSH_AUTHORITATIVE_APPLY_FAILED',
+                        });
+                    }
+                    throw new Error(`Authoritative V2 push echo apply failed (${applyResult.status || 0}).`);
+                }
+                for (const entry of appliedTaskUpserts) {
+                    const taskId = String(entry.task.id || '').trim();
+                    const watermark = String(entry.task.updatedAt || entry.task.createdAt || '').trim();
+                    if (!taskId || !watermark)
+                        continue;
+                    pushResult.currentTaskWatermarks?.set(taskId, watermark);
+                    pushResult.pushedWatermarks.set(taskId, watermark);
+                }
+                try {
+                    await refreshLocalWorkspaceTaskCollections();
+                }
+                catch {
+                    logDebug('push_local_task_refresh_failed', {
+                        workspaceId: currentWorkspaceId,
+                        taskCount: appliedTaskUpserts.length,
+                    });
+                }
+            }
+            workspacePendingPushReplayRef.current = null;
+            workspaceBlockedPushSignatureRef.current = '';
+            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);
+            if (workspaceLastPushedTaskRelationshipChangeKeysRef) {
+                workspaceLastPushedTaskRelationshipChangeKeysRef.current = pushResult.currentTaskRelationshipChangeKeys
+                    ? new Map(pushResult.currentTaskRelationshipChangeKeys)
+                    : new Map(workspaceLastPushedTaskRelationshipChangeKeysRef.current);
+            }
+            if (workspaceLastPushedTaxonomyChangeKeyRef) {
+                workspaceLastPushedTaxonomyChangeKeyRef.current = pushResult.currentTaxonomyChangeKey
+                    ?? workspaceLastPushedTaxonomyChangeKeyRef.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);
+            workspaceLastPushedAssetWatermarksRef.current = new Map(pushResult.currentAssetWatermarks);
+            workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set(pushResult.currentDocumentReviewSessionIds);
+            workspaceLastPushedDocumentReviewSessionWatermarksRef.current = new Map(pushResult.currentDocumentReviewSessionWatermarks);
+            workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set(pushResult.currentDocumentReviewCommentIds);
+            workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map(pushResult.currentDocumentReviewCommentWatermarks);
+            workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set(pushResult.currentAnnotatedAttachmentSessionIds);
+            workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map(pushResult.currentAnnotatedAttachmentSessionWatermarks);
+            if (workspaceLastPushedTaskforceAgentIdsRef) {
+                workspaceLastPushedTaskforceAgentIdsRef.current = new Set(pushResult.currentTaskforceAgentIds);
+            }
+            if (workspaceLastPushedTaskforceAgentWatermarksRef) {
+                workspaceLastPushedTaskforceAgentWatermarksRef.current = new Map(pushResult.currentTaskforceAgentWatermarks);
+            }
+            if (workspaceLastPushedTaskforceAgentSkillIdsRef) {
+                workspaceLastPushedTaskforceAgentSkillIdsRef.current = new Set(pushResult.currentTaskforceAgentSkillIds);
+            }
+            if (workspaceLastPushedTaskforceAgentSkillWatermarksRef) {
+                workspaceLastPushedTaskforceAgentSkillWatermarksRef.current = new Map(pushResult.currentTaskforceAgentSkillWatermarks);
+            }
+            if (workspaceLastPushedAgentConversationIdsRef) {
+                workspaceLastPushedAgentConversationIdsRef.current = new Set(pushResult.currentAgentConversationIds);
+            }
+            if (workspaceLastPushedAgentConversationWatermarksRef) {
+                workspaceLastPushedAgentConversationWatermarksRef.current = new Map(pushResult.currentAgentConversationWatermarks);
+            }
+            workspaceLastPushedTaskEventWatermarksRef.current = new Map(pushResult.currentTaskEventWatermarks);
+            if (forceAllAiProfiles) {
+                workspaceForceFullAiProfilePushRef.current = false;
+            }
+            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);
+                }
+            }
+            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,
+                    maxQueueSize: 2048
+                });
+            }
+            clearWorkspaceRetry();
+            const syncedAt = pushResult.syncedAt || now().toISOString();
+            workspaceLastPushedSignatureRef.current = buildWorkspaceSyncSignature();
+            setWorkspaceLastPushAt(syncedAt);
+            setWorkspaceSyncPendingChanges(0);
+            setUserGlobalSyncStatus('idle');
+            persistWorkspaceSyncPatchSafely({
+                phase: 'active',
+                lastPushAt: syncedAt,
+                lastSyncedAt: syncedAt
+            });
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: workspaceSyncPhase === 'provision-local' ? 'bootstrap' : 'push',
+                status: 'success',
+                changeCount: pushResult.changeCount,
+                requestMs: pushResult.requestMs,
+                details: {
+                    payloadDiagnostics: pushResult.effectiveDeltaDiagnostics || payload.deltaDiagnostics || null,
+                    ...(pushResult.batchProgress
+                        ? { pushBatchProgress: pushResult.batchProgress }
+                        : {}),
+                    ...(pushResult.effectiveDeltaDiagnostics && payload.deltaDiagnostics
+                        && pushResult.effectiveDeltaDiagnostics.totalChanges !== payload.deltaDiagnostics.totalChanges
+                        ? { candidatePayloadDiagnostics: payload.deltaDiagnostics }
+                        : {}),
+                    replayedPayload
+                }
+            });
+            return true;
+        }
+        catch (error) {
+            const message = 'Workspace sync push failed.';
+            setUserGlobalSyncStatus('error');
+            setUserGlobalSyncError(message);
+            setWorkspaceLastErrorMessage(message);
+            setWorkspaceLastErrorAt(now().toISOString());
+            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(),
+                details: {
+                    replayedPayload
+                }
+            });
+            logDebug('push_failed_exception', {
+                workspaceId: currentWorkspaceId,
+                elapsedMs: now().getTime() - pushStartedAtMs
+            });
+            return false;
+        }
+        finally {
+            workspacePushInFlightRef.current = false;
+            setWorkspaceSyncBusy(workspacePullInFlightRef.current);
+            releaseWorkspaceSyncLease(currentWorkspaceId);
+            if (workspacePullAfterPushRequestedRef.current
+                && !workspacePullInFlightRef.current
+                && !isWorkspaceRetryPending()) {
+                scheduleCoordinatorTask('pull-after-push', () => {
+                    void pullWorkspaceChangesFromCloud();
+                }, 0);
+            }
+            const pendingSignature = workspacePendingSignatureRef.current;
+            const latestSignature = buildWorkspaceSyncSignature();
+            if (pendingSignature
+                && latestSignature
+                && latestSignature !== workspaceLastPushedSignatureRef.current
+                && !workspacePullInFlightRef.current
+                && !isWorkspaceRetryPending()
+                && !suppressDeferredPush) {
+                scheduleCoordinatorTask('pending-push', () => {
+                    const signatureToPush = workspacePendingSignatureRef.current || latestSignature;
+                    workspacePendingSignatureRef.current = '';
+                    void pushWorkspaceChangesToCloud(signatureToPush);
+                }, 120);
+            }
+        }
+    };
+    const pullWorkspaceChangesFromCloud = async (options) => {
+        if (!isExecutionAuthorized())
+            return false;
+        const explicitRepairMode = options?.repairMode === true;
+        const persistExplicitRepairFailure = async (message) => {
+            if (!explicitRepairMode)
+                return;
+            clearWorkspaceRetry();
+            await persistWorkspaceSyncPatchBestEffort({ phase: 'error', lastErrorMessage: message });
+        };
+        let pullReadiness = resolvePullSyncReadiness({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            currentWorkspaceId,
+            workspaceSyncPhase,
+            isAuthenticated,
+            repairModeActive: workspaceRepairModeRef.current === true,
+            repairModeBypass: explicitRepairMode,
+            retryPending: isWorkspaceRetryPending(),
+            pullInFlight: workspacePullInFlightRef.current,
+            pushInFlight: workspacePushInFlightRef.current
+        });
+        if (!pullReadiness.allowed && pullReadiness.reason === 'auth-required') {
+            const authed = await checkAuthSession();
+            if (!authed) {
+                await persistExplicitRepairFailure('Session expired. Sign in again, then press Repair to resume cloud sync.');
+                return false;
+            }
+            pullReadiness = resolvePullSyncReadiness({
+                cloudAuthConfigured,
+                runtimeMode,
+                workspaceCloudSyncEnabled,
+                currentWorkspaceId,
+                workspaceSyncPhase,
+                isAuthenticated: true,
+                repairModeActive: workspaceRepairModeRef.current === true,
+                repairModeBypass: explicitRepairMode,
+                retryPending: isWorkspaceRetryPending(),
+                pullInFlight: workspacePullInFlightRef.current,
+                pushInFlight: workspacePushInFlightRef.current
+            });
+        }
+        if (!pullReadiness.allowed) {
+            if (pullReadiness.reason === 'push-in-flight' && !explicitRepairMode) {
+                workspacePullAfterPushRequestedRef.current = true;
+            }
+            return false;
+        }
+        workspacePullAfterPushRequestedRef.current = false;
+        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'pull');
+        if (!leaseAcquired) {
+            reportWorkspaceWindowContention('pull');
+            return false;
+        }
+        workspacePullInFlightRef.current = true;
+        setWorkspaceSyncBusy(true);
+        setUserGlobalSyncStatus('syncing');
+        setUserGlobalSyncError(null);
+        const pullStartedAtMs = now().getTime();
+        let pullSucceeded = false;
+        try {
+            const ready = await ensureWorkspaceSyncReady();
+            if (!ready) {
+                await persistExplicitRepairFailure('Workspace sync repair could not validate cloud access. Resolve the reported error, then press Repair to retry.');
+                return false;
+            }
+            if (!isExecutionAuthorized())
+                return false;
+            const projectionOutcome = { authFailure: false, failure: null };
+            let excludeInitiativesFromV2 = false;
+            let excludedProjections = [];
+            let projectionAppliedChanges = 0;
+            const recordProjectionChanges = (changeCount) => {
+                projectionAppliedChanges += Math.max(0, Number(changeCount) || 0);
+            };
+            const v3Transfers = createWorkspaceSyncV3TransferBindings({
+                workspaceId: currentWorkspaceId,
+                remoteServices,
+                localServices,
+            });
+            let combinedAttachmentAssetHydrationIdValue = '';
+            let combinedAttachmentAssetHydrationError = '';
+            const recordProjectionResult = (cycle, projectionCycle) => {
+                if (cycle.kind === 'auth-failure') {
+                    projectionOutcome.authFailure = true;
+                    return false;
+                }
+                if (cycle.kind === 'transient-failure') {
+                    projectionOutcome.failure = {
+                        status: cycle.status,
+                        retryAfterMs: cycle.retryAfterMs,
+                        error: String(cycle.error || 'Workspace projection synchronization failed.'),
+                        projectionCycle,
+                    };
+                    return false;
+                }
+                return true;
+            };
+            try {
+                if (combinedFeedActivationEnabled === true) {
+                    const initiativeRollback = await runWorkspaceSyncV3InitiativeProjectionCycle({
+                        activationEnabled: false, resolveCloudAuthUrl, workspaceId: currentWorkspaceId,
+                        onChangesApplied: recordProjectionChanges,
+                        dependencies: v3Transfers.initiative,
+                    });
+                    if (recordProjectionResult(initiativeRollback, 'initiative')) {
+                        const combinedCycle = await runWorkspaceSyncV3CombinedProjectionCycle({
+                            activationEnabled: true, coverage: combinedFeedCoverage,
+                            resolveCloudAuthUrl, workspaceId: currentWorkspaceId,
+                            forceAuthoritativeRepair: options?.forceV3AuthoritativeRepair === true,
+                            ...(options?.recoveryBatchId ? { recoveryBatchId: options.recoveryBatchId } : {}),
+                            onChangesApplied: recordProjectionChanges,
+                            dependencies: v3Transfers.combined,
+                        });
+                        excludedProjections = combinedCycle.excludedProjections;
+                        const hydrationAssetId = combinedCycle.kind === 'transient-failure'
+                            ? combinedAttachmentAssetHydrationId(combinedCycle)
+                            : null;
+                        if (hydrationAssetId) {
+                            combinedAttachmentAssetHydrationIdValue = hydrationAssetId;
+                            combinedAttachmentAssetHydrationError = combinedCycle.kind === 'transient-failure'
+                                ? combinedCycle.error
+                                : '';
+                        }
+                        else {
+                            recordProjectionResult(combinedCycle, 'combined');
+                        }
+                    }
+                }
+                else {
+                    if (combinedFeedActivationEnabled !== undefined) {
+                        const combinedRollback = await runWorkspaceSyncV3CombinedProjectionCycle({
+                            activationEnabled: false, coverage: combinedFeedCoverage,
+                            resolveCloudAuthUrl, workspaceId: currentWorkspaceId,
+                            onChangesApplied: recordProjectionChanges,
+                            dependencies: v3Transfers.combined,
+                        });
+                        recordProjectionResult(combinedRollback, 'combined');
+                    }
+                    if (!projectionOutcome.authFailure && !projectionOutcome.failure
+                        && initiativeFeedActivationEnabled !== undefined) {
+                        const initiativeCycle = await runWorkspaceSyncV3InitiativeProjectionCycle({
+                            activationEnabled: initiativeFeedActivationEnabled,
+                            resolveCloudAuthUrl,
+                            workspaceId: currentWorkspaceId,
+                            onChangesApplied: recordProjectionChanges,
+                            dependencies: v3Transfers.initiative,
+                        });
+                        if (recordProjectionResult(initiativeCycle, 'initiative')) {
+                            excludeInitiativesFromV2 = initiativeCycle.excludeInitiativesFromV2;
+                        }
+                    }
+                }
+            }
+            finally {
+                await v3Transfers.abandonPendingReceipts();
+            }
+            if (projectionOutcome.authFailure) {
+                await handleSyncAuthFailure('pull', 401);
+                await persistExplicitRepairFailure('Session expired. Sign in again, then press Repair to resume cloud sync.');
+                return false;
+            }
+            if (projectionOutcome.failure) {
+                setWorkspaceLastErrorMessage(projectionOutcome.failure.error);
+                setWorkspaceLastErrorAt(now().toISOString());
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'apply',
+                    status: 'error',
+                    statusCode: projectionOutcome.failure.status,
+                    errorMessage: projectionOutcome.failure.error,
+                    details: {
+                        recovery: 'projection-cycle-retry',
+                        projectionCycle: projectionOutcome.failure.projectionCycle,
+                        ...(projectionOutcome.failure.retryAfterMs !== undefined
+                            ? { retryAfterMs: projectionOutcome.failure.retryAfterMs }
+                            : {}),
+                    },
+                });
+                if (explicitRepairMode) {
+                    await persistWorkspaceSyncPatchBestEffort({ phase: 'error', lastErrorMessage: projectionOutcome.failure.error });
+                }
+                else {
+                    scheduleWorkspaceSyncRetry(projectionOutcome.failure.retryAfterMs);
+                }
+                return false;
+            }
+            if (combinedAttachmentAssetHydrationIdValue) {
+                const hydrationResult = await hydrateWorkspaceSyncV3AttachmentAsset({
+                    workspaceId: currentWorkspaceId,
+                    assetId: combinedAttachmentAssetHydrationIdValue,
+                    remoteServices,
+                    localServices,
+                }).catch((error) => ({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error || 'Unknown hydration failure.'),
+                }));
+                if (hydrationResult.success && hydrationResult.emittedEventIds.length > 0) {
+                    recordSuppressedEventIds(hydrationResult.emittedEventIds, { ttlMs: 60_000 });
+                }
+                setUserGlobalSyncStatus('error');
+                setUserGlobalSyncError(combinedAttachmentAssetHydrationError);
+                setWorkspaceLastErrorMessage(combinedAttachmentAssetHydrationError);
+                setWorkspaceLastErrorAt(now().toISOString());
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'apply',
+                    status: 'error',
+                    errorMessage: combinedAttachmentAssetHydrationError,
+                    changeCount: hydrationResult.success ? hydrationResult.appliedChanges : 0,
+                    details: {
+                        recovery: hydrationResult.success
+                            ? 'combined-attachment-asset-hydrated-retry-pending'
+                            : 'combined-attachment-asset-hydration-failed',
+                        assetId: combinedAttachmentAssetHydrationIdValue,
+                        ...(!hydrationResult.success ? { hydrationError: hydrationResult.error } : {}),
+                    },
+                });
+                scheduleWorkspaceSyncRetry();
+                return false;
+            }
+            const pullRequestPlan = resolveWorkspacePullRequestPlan({
+                workspaceSyncPhase,
+                forceCursorNull: options?.forceCursorNull === true,
+                currentCursor: workspacePullCursorRef.current
+            });
+            const pullResult = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl,
+                workspaceId: currentWorkspaceId,
+                cursor: explicitRepairMode ? null : pullRequestPlan.cursor,
+                bootstrap: pullRequestPlan.bootstrap,
+                ensureCloudWorkspaceReadyForSync,
+                maxPages: explicitRepairMode ? 200 : 20,
+                repairMode: explicitRepairMode || workspaceRepairModeRef.current === true,
+                contentMode: options?.forceCursorNull === true ? 'manifest' : 'full',
+                excludeInitiatives: excludeInitiativesFromV2,
+                excludedProjections,
+                onPagePulled: () => { bootstrapLastProgressAtRef.current = now().getTime(); },
+                onAiProfilesApplied: () => {
+                    notifyAiProfilesMutated({
+                        workspaceId: currentWorkspaceId,
+                        reason: 'sync-apply',
+                        origin: 'sync-orchestrator',
+                    });
+                },
+                onChangesApplied: () => { bootstrapLastProgressAtRef.current = now().getTime(); },
+                remoteServices,
+                localServices,
+            });
+            if (!pullResult.success) {
+                if (pullResult.kind === 'pull_http' && pullResult.status === 401) {
+                    await handleSyncAuthFailure('pull', 401);
+                    await persistExplicitRepairFailure('Session expired. Sign in again, then press Repair to resume cloud sync.');
+                    return false;
+                }
+                if (pullResult.kind === 'apply_auth') {
+                    await handleSyncAuthFailure('apply', 401);
+                    await persistExplicitRepairFailure('Session expired. Sign in again, then press Repair to resume cloud sync.');
+                    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(now().toISOString());
+                    reportSyncEvent(currentWorkspaceId, {
+                        eventType: 'pull',
+                        status: 'error',
+                        statusCode: pullResult.status,
+                        errorMessage: message,
+                        requestMs: pullResult.pullRequestMs,
+                        details: {
+                            recovery: 'cursor-reset',
+                            ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                        }
+                    });
+                    if (explicitRepairMode) {
+                        await persistWorkspaceSyncPatchBestEffort({ phase: 'error', lastErrorMessage: message });
+                    }
+                    else {
+                        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})`;
+                if (pullResult.status === 413) {
+                    message = 'Local sync failed because the downloaded payload is too large. This usually happens when the workspace contains massive attachments.';
+                }
+                setUserGlobalSyncStatus('error');
+                setUserGlobalSyncError(message);
+                setWorkspaceLastErrorMessage(message);
+                setWorkspaceLastErrorAt(now().toISOString());
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: pullResult.kind?.startsWith('apply') ? 'apply' : 'pull',
+                    status: 'error',
+                    statusCode: pullResult.status,
+                    errorMessage: message,
+                    requestMs: pullResult.pullRequestMs,
+                    details: {
+                        pages: pullResult.pages,
+                        applyMs: pullResult.applyMs,
+                        ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                    }
+                });
+                if (explicitRepairMode) {
+                    await persistWorkspaceSyncPatchBestEffort({ phase: 'error', lastErrorMessage: message });
+                }
+                else if (pullResult.transient || pullResult.hasTransientApplyFailure || isTransientWorkspaceSyncStatus(pullResult.status)) {
+                    scheduleWorkspaceSyncRetry(pullResult.retryAfterMs);
+                }
+                else {
+                    persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+                }
+                return false;
+            }
+            if (explicitRepairMode && pullResult.hasMore === true) {
+                const message = 'Workspace sync repair stopped before the full cloud snapshot was downloaded. Press Repair to retry.';
+                setUserGlobalSyncStatus('error');
+                setUserGlobalSyncError(message);
+                setWorkspaceLastErrorMessage(message);
+                setWorkspaceLastErrorAt(now().toISOString());
+                await persistWorkspaceSyncPatchBestEffort({ phase: 'error', lastErrorMessage: message });
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'pull',
+                    status: 'error',
+                    errorMessage: message,
+                    requestMs: pullResult.pullRequestMs,
+                    details: { pages: pullResult.pages, applyMs: pullResult.applyMs, recovery: 'repair-pull-incomplete' }
+                });
+                return false;
+            }
+            if (Array.isArray(pullResult.emittedEventIds)) {
+                recordSuppressedEventIds(pullResult.emittedEventIds, { ttlMs: 60_000 });
+            }
+            const pulledAgentManagerState = (pullResult.pulledTaskforceAgentUpserts
+                || pullResult.pulledAgentRoleUpserts
+                || pullResult.pulledTaskforceAgentSkillUpserts
+                || pullResult.pulledAgentConversationUpserts);
+            if (pulledAgentManagerState) {
+                await refreshWorkspaceSyncTaskforceAgentsSnapshot?.();
+            }
+            if (pullResult.pulledTaskforceAgentUpserts
+                || pullResult.pulledAgentRoleUpserts
+                || pullResult.pulledAgentConversationUpserts) {
+                notifyAgentsMutated({
+                    workspaceId: currentWorkspaceId,
+                    reason: 'sync-apply',
+                });
+            }
+            if (pullResult.pulledTaskforceAgentSkillUpserts) {
+                notifyAgentSkillsMutated({
+                    workspaceId: currentWorkspaceId,
+                    reason: 'sync-apply',
+                });
+            }
+            if (pullResult.pulledDeleteTaskIds.size > 0) {
+                setTasks((prev) => prev.filter((task) => !pullResult.pulledDeleteTaskIds.has(String(task.id || ''))));
+                setArchivedTasks((prev) => prev.filter((task) => !pullResult.pulledDeleteTaskIds.has(String(task.id || ''))));
+            }
+            const decryptFailures = Array.isArray(pullResult.documentDecryptFailures)
+                ? pullResult.documentDecryptFailures.filter((value) => String(value || '').trim().length > 0)
+                : [];
+            if (decryptFailures.length > 0) {
+                logDebug('pull_document_decrypt_failures', {
+                    workspaceId: currentWorkspaceId,
+                    failureCount: decryptFailures.length
+                });
+            }
+            workspacePullCursorRef.current = pullResult.cursor || null;
+            if (projectionAppliedChanges > 0
+                || (pullResult.appliedChanges > 0
+                    && (explicitRepairMode
+                        || pullResult.pulledActiveUpserts
+                        || pullResult.pulledArchivedUpserts
+                        || pullResult.pulledTaskEventUpserts
+                        || pullResult.pulledPlanningUpserts
+                        || pullResult.pulledDeleteTaskIds.size > 0))) {
+                try {
+                    await refreshLocalWorkspaceTaskCollections();
+                }
+                catch {
+                    logDebug('pull_local_refresh_failed', {
+                        workspaceId: currentWorkspaceId,
+                        appliedChanges: pullResult.appliedChanges + projectionAppliedChanges
+                    });
+                    if (explicitRepairMode) {
+                        const message = 'Workspace sync repair could not refresh tasks and relationships after the cloud pull. Press Repair to retry.';
+                        clearWorkspaceRetry();
+                        setUserGlobalSyncStatus('error');
+                        setUserGlobalSyncError(message);
+                        setWorkspaceLastErrorMessage(message);
+                        setWorkspaceLastErrorAt(now().toISOString());
+                        await persistWorkspaceSyncPatchBestEffort({ phase: 'error', lastErrorMessage: message });
+                        return false;
+                    }
+                }
+            }
+            clearWorkspaceRetry();
+            clearWorkspaceIssue();
+            const syncedAt = pullResult.syncedAt || now().toISOString();
+            setWorkspaceLastPullAt(syncedAt);
+            setWorkspaceSyncPendingChanges(0);
+            setUserGlobalSyncStatus('idle');
+            const pullSuccessPlan = resolveWorkspacePullSuccessPlan({
+                workspaceSyncPhase,
+                forceCursorNull: options?.forceCursorNull === true,
+                repairMode: explicitRepairMode,
+                startupFullReconcileRan: workspaceStartupFullReconcileRanRef.current,
+                pendingSignature: workspacePendingSignatureRef.current,
+                fallbackSignature: buildWorkspaceSyncSignature(),
+                lastPushedSignature: workspaceLastPushedSignatureRef.current
+            });
+            if (pullSuccessPlan.shouldCaptureAttachBootstrapBaseline) {
+                workspaceCaptureAttachBootstrapBaselineRef.current = true;
+            }
+            if (pullSuccessPlan.shouldClearPendingSignature) {
+                workspacePendingSignatureRef.current = pullSuccessPlan.deferredPushSignature || '';
+                workspacePendingPushReplayRef.current = null;
+            }
+            await persistWorkspaceSyncPatchBestEffort({
+                phase: 'active',
+                pullCursor: workspacePullCursorRef.current,
+                lastPullAt: syncedAt,
+                lastSyncedAt: syncedAt,
+                ...(options?.forceCursorNull === true
+                    ? { startupFullReconcileCompletedAt: syncedAt }
+                    : {}),
+                lastErrorMessage: null
+            });
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: pullSuccessPlan.successEventType,
+                status: 'success',
+                changeCount: pullResult.appliedChanges + projectionAppliedChanges,
+                requestMs: pullResult.pullRequestMs,
+                details: {
+                    pages: pullResult.pages,
+                    applyMs: pullResult.applyMs,
+                    ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                }
+            });
+            if (pullSuccessPlan.shouldRefreshReferenceSnapshots) {
+                await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+                await refreshWorkspaceSyncAssetsSnapshot();
+                await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
+                await refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
+            }
+            if (pullSuccessPlan.shouldSeedWorkspaceSnapshotPushBaseline) {
+                seedWorkspaceSnapshotPushBaseline();
+            }
+            if (pullSuccessPlan.shouldRefreshReferenceSnapshots || pullSuccessPlan.shouldSeedWorkspaceSnapshotPushBaseline) {
+                pullSucceeded = true;
+                return true;
+            }
+            if (pullSuccessPlan.shouldScheduleStartupFullReconcile) {
+                workspaceStartupFullReconcileRequestedRef.current = true;
+                scheduleCoordinatorTask('startup-full-reconcile', () => {
+                    if (!workspaceStartupFullReconcileRequestedRef.current
+                        || workspaceFullReconcileInFlightRef.current)
+                        return;
+                    workspaceStartupFullReconcileRequestedRef.current = false;
+                    workspaceStartupFullReconcileRanRef.current = true;
+                    workspaceFullReconcileInFlightRef.current = true;
+                    void pullWorkspaceChangesFromCloud({ forceCursorNull: true }).finally(() => {
+                        workspaceFullReconcileInFlightRef.current = false;
+                    });
+                }, 250);
+            }
+            const shouldReassertAiProfilesAfterFullReconcile = (options?.forceCursorNull === true
+                && !explicitRepairMode
+                && workspaceSyncPhase === 'active');
+            if (shouldReassertAiProfilesAfterFullReconcile) {
+                const reassertSignature = buildWorkspaceSyncSignature();
+                if (reassertSignature) {
+                    workspaceForceFullAiProfilePushRef.current = true;
+                    workspacePendingSignatureRef.current = reassertSignature;
+                    scheduleCoordinatorTask('pending-push', () => {
+                        const signatureToPush = workspacePendingSignatureRef.current || reassertSignature;
+                        workspacePendingSignatureRef.current = '';
+                        void pushWorkspaceChangesToCloud(signatureToPush, { forceAllAiProfiles: true });
+                    }, 120);
+                }
+            }
+            else if (pullSuccessPlan.deferredPushSignature) {
+                const deferredPushSignature = pullSuccessPlan.deferredPushSignature;
+                scheduleCoordinatorTask('pending-push', () => {
+                    const signatureToPush = workspacePendingSignatureRef.current || deferredPushSignature;
+                    workspacePendingSignatureRef.current = '';
+                    void pushWorkspaceChangesToCloud(signatureToPush);
+                }, 120);
+            }
+            pullSucceeded = true;
+            return true;
+        }
+        catch (error) {
+            const detail = String(error?.message || '').trim();
+            const message = detail
+                ? `Workspace sync pull failed. ${detail}`
+                : 'Workspace sync pull failed.';
+            setUserGlobalSyncStatus('error');
+            setUserGlobalSyncError(message);
+            setWorkspaceLastErrorMessage(message);
+            setWorkspaceLastErrorAt(now().toISOString());
+            if (explicitRepairMode) {
+                await persistWorkspaceSyncPatchBestEffort({ phase: 'error', lastErrorMessage: message });
+            }
+            else {
+                scheduleWorkspaceSyncRetry();
+            }
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: 'pull',
+                status: 'error',
+                errorMessage: message,
+                requestMs: now().getTime() - pullStartedAtMs
+            });
+            logDebug('pull_failed_exception', {
+                workspaceId: currentWorkspaceId,
+                elapsedMs: now().getTime() - pullStartedAtMs,
+                error: detail || null
+            });
+            return false;
+        }
+        finally {
+            workspacePullInFlightRef.current = false;
+            setWorkspaceSyncBusy(workspacePushInFlightRef.current);
+            if (pullSucceeded) {
+                recordWorkspaceSyncCompletion(currentWorkspaceId, 'pull');
+            }
+            releaseWorkspaceSyncLease(currentWorkspaceId);
+        }
+    };
+    const resumeDeferredWork = () => {
+        if (!isExecutionAuthorized())
+            return;
+        if (workspacePullAfterPushRequestedRef.current) {
+            scheduleCoordinatorTask('pull-after-push', () => {
+                void pullWorkspaceChangesFromCloud();
+            }, 0);
+        }
+        if (workspacePendingSignatureRef.current) {
+            scheduleCoordinatorTask('pending-push', () => {
+                const signatureToPush = workspacePendingSignatureRef.current;
+                if (!signatureToPush)
+                    return;
+                workspacePendingSignatureRef.current = '';
+                void pushWorkspaceChangesToCloud(signatureToPush, {
+                    forceAllAiProfiles: workspaceForceFullAiProfilePushRef.current,
+                });
+            }, 120);
+        }
+        if (workspaceStartupFullReconcileRequestedRef.current) {
+            scheduleCoordinatorTask('startup-full-reconcile', () => {
+                if (!workspaceStartupFullReconcileRequestedRef.current
+                    || workspaceFullReconcileInFlightRef.current)
+                    return;
+                workspaceStartupFullReconcileRequestedRef.current = false;
+                workspaceStartupFullReconcileRanRef.current = true;
+                workspaceFullReconcileInFlightRef.current = true;
+                void pullWorkspaceChangesFromCloud({ forceCursorNull: true }).finally(() => {
+                    workspaceFullReconcileInFlightRef.current = false;
+                });
+            }, 250);
+        }
+    };
+    return {
+        pushWorkspaceChangesToCloud,
+        pullWorkspaceChangesFromCloud,
+        resumeDeferredWork,
+        dispose,
+    };
+}