@taskforcehq/taskforce 0.3.303 → 0.3.304

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[];

package/dist/hooks/ui/useResourceExport.js

@@ -1,11 +1,12 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
-export function useResourceExport({ storagePath }) {
+export function useResourceExport({ storagePath, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls }) {
     const [exportEnvironment, setExportEnvironment] = useState('antigravity');
     const [availableEnvironments, setAvailableEnvironments] = useState([]);
     const [exportWorkflowsPath, setExportWorkflowsPath] = useState('.agent/workflows');
     const [exportingResource, setExportingResource] = useState(null);
     const [exportResult, setExportResult] = useState(null);
     const exportResultTimerRef = useRef(null);
+    const shouldSkipProtectedApiCalls = shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls;
     useEffect(() => {
         const env = availableEnvironments.find((item) => item.id === exportEnvironment);
         if (env) {
@@ -23,13 +24,15 @@ export function useResourceExport({ storagePath }) {
         }, 5000);
     }, []);
     const loadAvailableEnvironments = useCallback(async () => {
+        if (shouldSkipProtectedApiCalls)
+            return;
         const envRes = await fetch('/api/taskforce/environments');
         if (!envRes.ok)
             return;
         const envData = await envRes.json().catch(() => ({}));
         if (envData.environments)
             setAvailableEnvironments(envData.environments);
-    }, []);
+    }, [shouldSkipProtectedApiCalls]);
     const handleExportWorkflows = useCallback(async (environment, selected) => {
         setExportingResource('workflows');
         setExportResult(null);

package/dist/hooks/ui/useWorkflowTemplates.js

@@ -2,8 +2,9 @@ import { useCallback, useState } from 'react';
 export function useWorkflowTemplates({ shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls }) {
     const [availableWorkflows, setAvailableWorkflows] = useState([]);
     const [initiativeTemplates, setInitiativeTemplates] = useState([]);
+    const shouldSkipProtectedApiCalls = shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls;
     const fetchWorkflows = useCallback(async () => {
-        if (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls)
+        if (shouldSkipProtectedApiCalls)
             return;
         try {
             const res = await fetch('/api/taskforce/workflow-templates');
@@ -15,8 +16,10 @@ export function useWorkflowTemplates({ shouldDeferProtectedApiCalls, shouldBlock
         catch {
             // Ignore error
         }
-    }, [shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls]);
+    }, [shouldSkipProtectedApiCalls]);
     const fetchInitiativeTemplates = useCallback(async () => {
+        if (shouldSkipProtectedApiCalls)
+            return [];
         try {
             const res = await fetch('/api/taskforce/initiative-templates');
             if (!res.ok)
@@ -29,9 +32,9 @@ export function useWorkflowTemplates({ shouldDeferProtectedApiCalls, shouldBlock
         catch {
             return [];
         }
-    }, []);
+    }, [shouldSkipProtectedApiCalls]);
     const fetchWorkflowTemplate = useCallback(async (name) => {
-        if (!name)
+        if (!name || shouldSkipProtectedApiCalls)
             return null;
         const paths = [
             `/api/taskforce/workflow-template/${encodeURIComponent(name)}`,
@@ -51,8 +54,10 @@ export function useWorkflowTemplates({ shouldDeferProtectedApiCalls, shouldBlock
         catch {
             return null;
         }
-    }, []);
+    }, [shouldSkipProtectedApiCalls]);
     const fetchWorkflowOverrideNames = useCallback(async () => {
+        if (shouldSkipProtectedApiCalls)
+            return [];
         try {
             const res = await fetch('/api/taskforce/workflow-editor/overrides');
             if (!res.ok)
@@ -63,7 +68,7 @@ export function useWorkflowTemplates({ shouldDeferProtectedApiCalls, shouldBlock
         catch {
             return [];
         }
-    }, []);
+    }, [shouldSkipProtectedApiCalls]);
     const saveWorkflowTemplateDraft = useCallback(async (name, draft) => {
         try {
             const res = await fetch('/api/taskforce/workflow-editor/save', {

package/dist/hooks/useRealtimeSync.js

@@ -168,7 +168,8 @@ export function useRealtimeSync(input) {
                 if (event.type === 'taskforce:update') {
                     queueSignal({
                         type: 'taskforce:update',
-                        workspaceId: normalizedWorkspaceId
+                        workspaceId: normalizedWorkspaceId,
+                        eventId: typeof event.eventId === 'string' ? event.eventId.trim() : undefined
                     });
                     return;
                 }

package/dist/hooks/useSyncOrchestrator.aiProfiles.test.js

@@ -10,6 +10,10 @@ describe('normalizeWorkspaceSyncAiProfileSnapshotEntry', () => {
             username: 'codex',
             icon: 'Bot',
             color: '#0ea5e9',
+            description: 'Terminal-first coding agent',
+            role: 'Implementer',
+            provider: 'OpenAI',
+            model: 'gpt-5.4',
             surface_type: 'coding_tool',
             provider_metadata: { source: 'test' },
             created_at: '2026-03-15T18:00:00.000Z',
@@ -24,6 +28,10 @@ describe('normalizeWorkspaceSyncAiProfileSnapshotEntry', () => {
             username: 'codex',
             icon: 'Bot',
             color: '#0ea5e9',
+            description: 'Terminal-first coding agent',
+            role: 'Implementer',
+            provider: 'OpenAI',
+            model: 'gpt-5.4',
             surfaceType: 'coding_tool',
             providerMetadata: { source: 'test' },
             createdAt: '2026-03-15T18:00:00.000Z',

package/dist/hooks/useSyncOrchestrator.context-assets.test.d.ts

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