@taskforcehq/taskforce 0.3.302 → 0.3.304

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

@@ -0,0 +1,122 @@
+import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
+import { type EnsureWorkspaceReadyResult } from '../../sync/syncService';
+import type { WorkspaceSyncPayload } from '../../sync/workspaceSyncModel';
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+interface CreateWorkspaceTransferCoordinatorArgs {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    workspaceCloudSyncEnabled: boolean;
+    currentWorkspaceId: string;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    taxonomyStateFingerprint: string;
+    isAuthenticated: boolean;
+    checkAuthSession: () => Promise<boolean>;
+    resolveCloudAuthUrl: (path: string) => string;
+    ensureCloudWorkspaceReadyForSync: () => Promise<EnsureWorkspaceReadyResult>;
+    ensureWorkspaceSyncReady: () => Promise<boolean>;
+    handleSyncAuthFailure: (source: 'push' | 'pull' | 'apply' | 'handshake', statusCode: number) => Promise<void>;
+    clearWorkspaceRetry: () => void;
+    clearWorkspaceIssue: () => void;
+    isWorkspaceRetryPending: () => boolean;
+    scheduleWorkspaceSyncRetry: (minDelayMs?: number) => void;
+    persistWorkspaceSyncPatchSafely: (patch: {
+        phase: 'error';
+        lastErrorMessage: string;
+    } | {
+        phase: 'active';
+        lastPushAt?: string;
+        lastPullAt?: string;
+        lastSyncedAt: string;
+        pullCursor?: string | null;
+        lastErrorMessage: null;
+    }) => void;
+    persistWorkspaceSyncPatchBestEffort: (patch: {
+        phase: 'active';
+        pullCursor: string | null;
+        lastPullAt: string;
+        lastSyncedAt: string;
+        lastErrorMessage: null;
+    }) => Promise<unknown>;
+    reportSyncEvent: (workspaceId: string, event: {
+        eventType: 'pull' | 'handshake' | 'bootstrap' | 'apply' | 'push';
+        status: 'success' | 'error';
+        statusCode?: number;
+        errorMessage?: string;
+        changeCount?: number;
+        requestMs?: number;
+        details?: Record<string, unknown>;
+    }) => void;
+    acquireWorkspaceSyncLease: (workspaceId: string, owner: 'pull' | 'push' | 'repair') => Promise<boolean>;
+    releaseWorkspaceSyncLease: (workspaceId: string) => void;
+    reportWorkspaceWindowContention: (operation: 'pull' | 'push' | 'repair') => void;
+    refreshWorkspaceSyncMarkdownDocumentsSnapshot: () => Promise<void>;
+    refreshWorkspaceSyncAiProfilesSnapshot: () => Promise<void>;
+    refreshWorkspaceSyncAssetsSnapshot: () => Promise<void>;
+    refreshWorkspaceSyncDocumentReviewSessionsSnapshot: () => Promise<void>;
+    refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot: () => Promise<void>;
+    refreshLocalWorkspaceTaskCollections: () => Promise<void>;
+    buildWorkspaceSyncPayload: (options?: {
+        forceAllAiProfiles?: boolean;
+    }) => WorkspaceSyncPayload;
+    buildWorkspaceSyncSignature: () => string;
+    seedWorkspaceSnapshotPushBaseline: () => void;
+    shouldSuppressAttachBootstrapPush: (signature: string) => boolean;
+    recordSuppressedEventIds: (eventIds: Iterable<string>, options?: {
+        queueRef?: MutableRefObject<string[]>;
+        maxQueueSize?: number;
+        ttlMs?: number;
+    }) => void;
+    workspaceRepairModeRef: MutableRefObject<boolean>;
+    workspaceForceFullAiProfilePushRef: MutableRefObject<boolean>;
+    workspacePushInFlightRef: MutableRefObject<boolean>;
+    workspacePullInFlightRef: MutableRefObject<boolean>;
+    workspaceLastPushedSignatureRef: MutableRefObject<string>;
+    workspacePendingSignatureRef: MutableRefObject<string>;
+    workspaceLastPushedTaskIdsRef: MutableRefObject<Set<string>>;
+    workspaceDeletedTaskIdsRef: MutableRefObject<Set<string>>;
+    workspacePullCursorRef: MutableRefObject<string | null>;
+    workspaceLastPushedWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedInitiativeIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedInitiativeWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedWorkstreamIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedWorkstreamWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedAiProfileIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedAiProfileWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedDocumentPathsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedDocumentWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedAssetPathsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedAssetWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedDocumentReviewSessionIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedDocumentReviewSessionWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedDocumentReviewCommentIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedDocumentReviewCommentWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedAnnotatedAttachmentSessionIdsRef: MutableRefObject<Set<string>>;
+    workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedTaskEventWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceCaptureAttachBootstrapBaselineRef: MutableRefObject<boolean>;
+    workspaceStartupFullReconcileRanRef: MutableRefObject<boolean>;
+    workspaceFullReconcileInFlightRef: MutableRefObject<boolean>;
+    bootstrapLastProgressAtRef: MutableRefObject<number | null>;
+    realtimeSuppressedEventQueueRef: MutableRefObject<string[]>;
+    setWorkspaceSyncBusy: Dispatch<SetStateAction<boolean>>;
+    setUserGlobalSyncStatus: Dispatch<SetStateAction<'disconnected' | 'idle' | 'syncing' | 'error'>>;
+    setUserGlobalSyncError: Dispatch<SetStateAction<string | null>>;
+    setWorkspaceLastErrorMessage: Dispatch<SetStateAction<string | null>>;
+    setWorkspaceLastErrorAt: Dispatch<SetStateAction<string | null>>;
+    setWorkspaceLastPullAt: Dispatch<SetStateAction<string | null>>;
+    setWorkspaceLastPushAt: Dispatch<SetStateAction<string | null>>;
+    setWorkspaceSyncPendingChanges: Dispatch<SetStateAction<number>>;
+    setTasks: Dispatch<SetStateAction<any[]>>;
+    setArchivedTasks: Dispatch<SetStateAction<any[]>>;
+}
+export declare function createWorkspaceTransferCoordinator({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, currentWorkspaceId, workspaceSyncPhase, taxonomyStateFingerprint, isAuthenticated, checkAuthSession, resolveCloudAuthUrl, ensureCloudWorkspaceReadyForSync, ensureWorkspaceSyncReady, handleSyncAuthFailure, clearWorkspaceRetry, clearWorkspaceIssue, isWorkspaceRetryPending, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely, persistWorkspaceSyncPatchBestEffort, reportSyncEvent, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, reportWorkspaceWindowContention, refreshWorkspaceSyncMarkdownDocumentsSnapshot, refreshWorkspaceSyncAiProfilesSnapshot, refreshWorkspaceSyncAssetsSnapshot, refreshWorkspaceSyncDocumentReviewSessionsSnapshot, refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot, refreshLocalWorkspaceTaskCollections, buildWorkspaceSyncPayload, buildWorkspaceSyncSignature, seedWorkspaceSnapshotPushBaseline, shouldSuppressAttachBootstrapPush, recordSuppressedEventIds, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspacePullCursorRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, workspaceCaptureAttachBootstrapBaselineRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, bootstrapLastProgressAtRef, realtimeSuppressedEventQueueRef, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceSyncPendingChanges, setTasks, setArchivedTasks }: CreateWorkspaceTransferCoordinatorArgs): {
+    pushWorkspaceChangesToCloud: (signature: string, options?: {
+        forceAllAiProfiles?: boolean;
+        repairMode?: boolean;
+    }) => Promise<boolean>;
+    pullWorkspaceChangesFromCloud: (options?: {
+        repairMode?: boolean;
+        forceCursorNull?: boolean;
+    }) => Promise<boolean>;
+};
+export {};

package/dist/hooks/sync/transfers.js

@@ -0,0 +1,431 @@
+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 }) {
+    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) {
+            const authed = await checkAuthSession();
+            if (!authed)
+                return false;
+        }
+        if (shouldSuppressAttachBootstrapPush(signature)) {
+            return false;
+        }
+        if (workspacePushInFlightRef.current || workspacePullInFlightRef.current) {
+            workspacePendingSignatureRef.current = signature;
+            return false;
+        }
+        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'push');
+        if (!leaseAcquired) {
+            workspacePendingSignatureRef.current = signature;
+            reportWorkspaceWindowContention('push');
+            return false;
+        }
+        workspacePushInFlightRef.current = true;
+        setWorkspaceSyncBusy(true);
+        setUserGlobalSyncStatus('syncing');
+        setUserGlobalSyncError(null);
+        const pushStartedAtMs = Date.now();
+        const forceAllAiProfiles = options?.forceAllAiProfiles === true || workspaceForceFullAiProfilePushRef.current === true;
+        try {
+            await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+            await refreshWorkspaceSyncAiProfilesSnapshot();
+            await refreshWorkspaceSyncAssetsSnapshot();
+            await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
+            const ready = await ensureWorkspaceSyncReady();
+            if (!ready)
+                return false;
+            const payload = buildWorkspaceSyncPayload({ forceAllAiProfiles });
+            setWorkspaceSyncPendingChanges(payload.changes.length);
+            const pushResult = await runWorkspacePushSyncService({
+                resolveCloudAuthUrl,
+                workspaceId: currentWorkspaceId,
+                payload,
+                ensureCloudWorkspaceReadyForSync,
+                repairMode: options?.repairMode === true || workspaceRepairModeRef.current === true
+            });
+            if (!pushResult.success) {
+                if (pushResult.status === 401) {
+                    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(new Date().toISOString());
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'push',
+                    status: 'error',
+                    statusCode: pushResult.status,
+                    errorMessage: message,
+                    requestMs: pushResult.requestMs
+                });
+                workspacePendingSignatureRef.current = signature;
+                if (pushResult.transient || isTransientWorkspaceSyncStatus(pushResult.status)) {
+                    scheduleWorkspaceSyncRetry(pushResult.retryAfterMs);
+                }
+                else if (workspaceSyncPhase === 'active') {
+                    persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+                }
+                return false;
+            }
+            workspaceLastPushedSignatureRef.current = signature;
+            workspaceLastPushedTaskIdsRef.current = pushResult.currentTaskIds;
+            workspaceLastPushedInitiativeIdsRef.current = new Set(pushResult.currentInitiativeIds);
+            workspaceLastPushedInitiativeWatermarksRef.current = new Map(pushResult.currentInitiativeWatermarks);
+            workspaceLastPushedWorkstreamIdsRef.current = new Set(pushResult.currentWorkstreamIds);
+            workspaceLastPushedWorkstreamWatermarksRef.current = new Map(pushResult.currentWorkstreamWatermarks);
+            workspaceLastPushedAiProfileIdsRef.current = new Set(pushResult.currentAiProfileIds);
+            workspaceLastPushedAiProfileWatermarksRef.current = new Map(pushResult.currentAiProfileWatermarks);
+            workspaceLastPushedDocumentPathsRef.current = new Set(pushResult.currentDocumentPaths);
+            workspaceLastPushedDocumentWatermarksRef.current = new Map(pushResult.currentDocumentWatermarks);
+            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);
+            workspaceLastPushedTaskEventWatermarksRef.current = new Map(pushResult.currentTaskEventWatermarks);
+            if (forceAllAiProfiles) {
+                workspaceForceFullAiProfilePushRef.current = false;
+            }
+            for (const [taskId, watermark] of pushResult.pushedWatermarks) {
+                workspaceLastPushedWatermarksRef.current.set(taskId, watermark);
+            }
+            if (pushResult.deleteTaskIds.size > 0) {
+                for (const taskId of pushResult.deleteTaskIds) {
+                    workspaceDeletedTaskIdsRef.current.delete(taskId);
+                    workspaceLastPushedWatermarksRef.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
+            });
+            if (Array.isArray(pushResult.emittedEventIds) && pushResult.emittedEventIds.length > 0) {
+                recordSuppressedEventIds(pushResult.emittedEventIds, {
+                    queueRef: realtimeSuppressedEventQueueRef,
+                    maxQueueSize: 2048
+                });
+            }
+            if (Array.isArray(pushResult.appliedTaskUpserts) && pushResult.appliedTaskUpserts.length > 0) {
+                const applyResult = await applyLocalWorkspaceChanges(currentWorkspaceId, pushResult.appliedTaskUpserts.map((entry) => ({
+                    op: 'upsert',
+                    archived: entry.archived === true,
+                    task: entry.task
+                })));
+                if (applyResult.ok) {
+                    for (const entry of pushResult.appliedTaskUpserts) {
+                        const taskId = String(entry?.task?.id || '').trim();
+                        const watermark = String(entry?.task?.updatedAt || entry?.task?.createdAt || '').trim();
+                        if (!taskId || !watermark)
+                            continue;
+                        workspaceLastPushedWatermarksRef.current.set(taskId, watermark);
+                    }
+                    try {
+                        await refreshLocalWorkspaceTaskCollections();
+                    }
+                    catch {
+                        logSyncDebug('push_local_task_refresh_failed', {
+                            workspaceId: currentWorkspaceId,
+                            taskCount: pushResult.appliedTaskUpserts.length
+                        });
+                    }
+                }
+                else {
+                    logSyncDebug('push_local_task_apply_failed', {
+                        workspaceId: currentWorkspaceId,
+                        taskCount: pushResult.appliedTaskUpserts.length,
+                        status: applyResult.status,
+                        failures: applyResult.failures
+                    });
+                }
+            }
+            clearWorkspaceRetry();
+            clearWorkspaceIssue();
+            const syncedAt = pushResult.syncedAt || new Date().toISOString();
+            workspaceLastPushedSignatureRef.current = buildWorkspaceSyncSignature();
+            setWorkspaceLastPushAt(syncedAt);
+            setWorkspaceSyncPendingChanges(0);
+            setUserGlobalSyncStatus('idle');
+            persistWorkspaceSyncPatchSafely({
+                phase: 'active',
+                lastPushAt: syncedAt,
+                lastSyncedAt: syncedAt,
+                lastErrorMessage: null
+            });
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: workspaceSyncPhase === 'provision-local' ? 'bootstrap' : 'push',
+                status: 'success',
+                changeCount: pushResult.changeCount,
+                requestMs: pushResult.requestMs
+            });
+            return true;
+        }
+        catch (error) {
+            const message = 'Workspace sync push failed.';
+            setUserGlobalSyncStatus('error');
+            setUserGlobalSyncError(message);
+            setWorkspaceLastErrorMessage(message);
+            setWorkspaceLastErrorAt(new Date().toISOString());
+            workspacePendingSignatureRef.current = signature;
+            scheduleWorkspaceSyncRetry();
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: 'push',
+                status: 'error',
+                errorMessage: `${message} ${String(error?.message || '').trim()}`.trim()
+            });
+            logSyncDebug('push_failed_exception', {
+                workspaceId: currentWorkspaceId,
+                elapsedMs: Date.now() - pushStartedAtMs
+            });
+            return false;
+        }
+        finally {
+            workspacePushInFlightRef.current = false;
+            setWorkspaceSyncBusy(workspacePullInFlightRef.current);
+            releaseWorkspaceSyncLease(currentWorkspaceId);
+            const pendingSignature = workspacePendingSignatureRef.current;
+            if (pendingSignature
+                && pendingSignature !== workspaceLastPushedSignatureRef.current
+                && !workspacePullInFlightRef.current) {
+                workspacePendingSignatureRef.current = '';
+                window.setTimeout(() => {
+                    void pushWorkspaceChangesToCloud(pendingSignature);
+                }, 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) {
+            const authed = await checkAuthSession();
+            if (!authed)
+                return false;
+        }
+        if (workspacePullInFlightRef.current || workspacePushInFlightRef.current)
+            return false;
+        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'pull');
+        if (!leaseAcquired) {
+            reportWorkspaceWindowContention('pull');
+            return false;
+        }
+        workspacePullInFlightRef.current = true;
+        setWorkspaceSyncBusy(true);
+        setUserGlobalSyncStatus('syncing');
+        setUserGlobalSyncError(null);
+        const pullStartedAtMs = Date.now();
+        try {
+            const ready = await ensureWorkspaceSyncReady();
+            if (!ready)
+                return false;
+            const bootstrap = workspaceSyncPhase === 'attach-cloud';
+            const cursor = bootstrap || options?.forceCursorNull === true ? null : workspacePullCursorRef.current;
+            const pullResult = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl,
+                workspaceId: currentWorkspaceId,
+                cursor,
+                bootstrap,
+                ensureCloudWorkspaceReadyForSync,
+                maxPages: 20,
+                repairMode: options?.repairMode === true || workspaceRepairModeRef.current === true,
+                onPagePulled: () => { bootstrapLastProgressAtRef.current = Date.now(); },
+                onChangesApplied: () => { bootstrapLastProgressAtRef.current = Date.now(); }
+            });
+            if (!pullResult.success) {
+                if (pullResult.kind === 'pull_http' && pullResult.status === 401) {
+                    await handleSyncAuthFailure('pull', 401);
+                    return false;
+                }
+                if (pullResult.kind === 'apply_auth') {
+                    await handleSyncAuthFailure('apply', 401);
+                    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(new Date().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 (pullResult.transient || pullResult.hasTransientApplyFailure || isTransientWorkspaceSyncStatus(pullResult.status)) {
+                    scheduleWorkspaceSyncRetry(pullResult.retryAfterMs);
+                }
+                else {
+                    persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+                }
+                return false;
+            }
+            if (Array.isArray(pullResult.emittedEventIds)) {
+                recordSuppressedEventIds(pullResult.emittedEventIds, { ttlMs: 60_000 });
+            }
+            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) {
+                logSyncDebug('pull_document_decrypt_failures', {
+                    workspaceId: currentWorkspaceId,
+                    failureCount: decryptFailures.length
+                });
+            }
+            workspacePullCursorRef.current = pullResult.cursor || null;
+            if (pullResult.appliedChanges > 0
+                && (pullResult.pulledActiveUpserts
+                    || pullResult.pulledArchivedUpserts
+                    || pullResult.pulledTaskEventUpserts)) {
+                try {
+                    await refreshLocalWorkspaceTaskCollections();
+                }
+                catch {
+                    logSyncDebug('pull_local_refresh_failed', {
+                        workspaceId: currentWorkspaceId,
+                        appliedChanges: pullResult.appliedChanges
+                    });
+                }
+            }
+            clearWorkspaceRetry();
+            clearWorkspaceIssue();
+            const syncedAt = pullResult.syncedAt || new Date().toISOString();
+            setWorkspaceLastPullAt(syncedAt);
+            setWorkspaceSyncPendingChanges(0);
+            setUserGlobalSyncStatus('idle');
+            if (workspaceSyncPhase === 'attach-cloud') {
+                workspaceCaptureAttachBootstrapBaselineRef.current = true;
+                workspacePendingSignatureRef.current = '';
+            }
+            await persistWorkspaceSyncPatchBestEffort({
+                phase: 'active',
+                pullCursor: workspacePullCursorRef.current,
+                lastPullAt: syncedAt,
+                lastSyncedAt: syncedAt,
+                lastErrorMessage: null
+            });
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: workspaceSyncPhase === 'attach-cloud' ? 'bootstrap' : 'pull',
+                status: 'success',
+                changeCount: pullResult.appliedChanges,
+                requestMs: pullResult.pullRequestMs,
+                details: {
+                    pages: pullResult.pages,
+                    applyMs: pullResult.applyMs,
+                    ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                }
+            });
+            if (workspaceSyncPhase === 'attach-cloud') {
+                await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
+                await refreshWorkspaceSyncAssetsSnapshot();
+                await refreshWorkspaceSyncDocumentReviewSessionsSnapshot();
+                await refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot();
+                seedWorkspaceSnapshotPushBaseline();
+                return true;
+            }
+            if (!options?.forceCursorNull && !bootstrap && !workspaceStartupFullReconcileRanRef.current) {
+                workspaceStartupFullReconcileRanRef.current = true;
+                window.setTimeout(() => {
+                    if (workspaceFullReconcileInFlightRef.current)
+                        return;
+                    workspaceFullReconcileInFlightRef.current = true;
+                    void pullWorkspaceChangesFromCloud({ forceCursorNull: true }).finally(() => {
+                        workspaceFullReconcileInFlightRef.current = false;
+                    });
+                }, 250);
+            }
+            const pendingSignature = workspacePendingSignatureRef.current || buildWorkspaceSyncSignature();
+            if (pendingSignature && pendingSignature !== workspaceLastPushedSignatureRef.current) {
+                workspacePendingSignatureRef.current = '';
+                window.setTimeout(() => {
+                    void pushWorkspaceChangesToCloud(pendingSignature);
+                }, 120);
+            }
+            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(new Date().toISOString());
+            scheduleWorkspaceSyncRetry();
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: 'pull',
+                status: 'error',
+                errorMessage: message,
+                requestMs: Date.now() - pullStartedAtMs
+            });
+            logSyncDebug('pull_failed_exception', {
+                workspaceId: currentWorkspaceId,
+                elapsedMs: Date.now() - pullStartedAtMs,
+                error: detail || null
+            });
+            return false;
+        }
+        finally {
+            workspacePullInFlightRef.current = false;
+            setWorkspaceSyncBusy(workspacePushInFlightRef.current);
+            releaseWorkspaceSyncLease(currentWorkspaceId);
+        }
+    };
+    return {
+        pushWorkspaceChangesToCloud,
+        pullWorkspaceChangesFromCloud
+    };
+}

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

@@ -0,0 +1,16 @@
+import { type MutableRefObject } from 'react';
+interface UseDataVersionRefreshArgs {
+    isOpen: boolean;
+    authBlocked: boolean;
+    authRequiredForApi: boolean;
+    isAuthenticated: boolean;
+    canCallProtectedApi: boolean;
+    shouldGateProtectedApiCalls: boolean;
+    authSessionResolvedRef: MutableRefObject<boolean>;
+    authRequiredForApiRef: MutableRefObject<boolean>;
+    isAuthenticatedRef: MutableRefObject<boolean>;
+    dataVersionRef: MutableRefObject<number | null>;
+    refreshTaskCollectionsForDataVersion: () => Promise<void>;
+}
+export declare function useDataVersionRefresh({ isOpen, authBlocked, authRequiredForApi, isAuthenticated, canCallProtectedApi, shouldGateProtectedApiCalls, authSessionResolvedRef, authRequiredForApiRef, isAuthenticatedRef, dataVersionRef, refreshTaskCollectionsForDataVersion }: UseDataVersionRefreshArgs): void;
+export {};

package/dist/hooks/sync/useDataVersionRefresh.js

@@ -0,0 +1,73 @@
+import { useEffect } from 'react';
+import { shouldSkipDataVersionPolling, shouldSkipDataVersionTick } from '../auth/useAuthGuardPolicy';
+export function useDataVersionRefresh({ isOpen, authBlocked, authRequiredForApi, isAuthenticated, canCallProtectedApi, shouldGateProtectedApiCalls, authSessionResolvedRef, authRequiredForApiRef, isAuthenticatedRef, dataVersionRef, refreshTaskCollectionsForDataVersion }) {
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof document === 'undefined')
+            return;
+        if (shouldSkipDataVersionPolling({
+            isOpen,
+            authBlocked,
+            authRequiredForApi,
+            isAuthenticated,
+            canCallProtectedApi
+        }))
+            return;
+        let cancelled = false;
+        const checkDataVersion = async () => {
+            if (cancelled || document.visibilityState !== 'visible')
+                return;
+            if (shouldSkipDataVersionTick({
+                shouldGateProtectedApiCalls,
+                authSessionResolved: authSessionResolvedRef.current,
+                authRequiredForApi: authRequiredForApiRef.current,
+                isAuthenticated: isAuthenticatedRef.current
+            }))
+                return;
+            try {
+                const res = await fetch('/api/taskforce/data-version');
+                if (!res.ok)
+                    return;
+                const data = await res.json();
+                const version = Number(data?.dataVersion);
+                if (!Number.isFinite(version))
+                    return;
+                if (dataVersionRef.current === null) {
+                    dataVersionRef.current = version;
+                    return;
+                }
+                if (version !== dataVersionRef.current) {
+                    dataVersionRef.current = version;
+                    await refreshTaskCollectionsForDataVersion();
+                }
+            }
+            catch {
+                // best effort only
+            }
+        };
+        const onVisibilityChange = () => {
+            if (document.visibilityState === 'visible') {
+                void checkDataVersion();
+            }
+        };
+        const intervalId = window.setInterval(() => { void checkDataVersion(); }, 3000);
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        void checkDataVersion();
+        return () => {
+            cancelled = true;
+            window.clearInterval(intervalId);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [
+        isOpen,
+        authBlocked,
+        authRequiredForApi,
+        isAuthenticated,
+        canCallProtectedApi,
+        shouldGateProtectedApiCalls,
+        authSessionResolvedRef,
+        authRequiredForApiRef,
+        isAuthenticatedRef,
+        dataVersionRef,
+        refreshTaskCollectionsForDataVersion
+    ]);
+}

package/dist/hooks/ui/useResourceExport.d.ts

@@ -1,8 +1,10 @@
 import type { Environment } from '../../types';
 interface UseResourceExportInput {
     storagePath: string;
+    shouldDeferProtectedApiCalls: boolean;
+    shouldBlockProtectedApiCalls: boolean;
 }
-export declare function useResourceExport({ storagePath }: UseResourceExportInput): {
+export declare function useResourceExport({ storagePath, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls }: UseResourceExportInput): {
     exportEnvironment: string;
     setExportEnvironment: import("react").Dispatch<import("react").SetStateAction<string>>;
     availableEnvironments: Environment[];